ArduPilot SITL: infrastructure for running cosimulation
The examples of the Ardupilot support package include the ready-made ArduPilot SITL environment: the ArduPilot autopilot (copter arducopter), assembled for Software In The Loop (SITL) mode with calculation of physical simulation parameters, and MAVProxy for telemetry transmission.
The basic concepts used in the article:
-
SITL (Software In The Loop) is a simulator that allows you to run the ArduPilot autopilot firmware on a personal computer without a hardware flight control board. In the simulation mode, SITL does not calculate the physics of the device itself, but receives it from the outside.
-
Cosimulation is a joint calculation in which the physics of the device is considered Engee, and the control logic is ArduPilot SITL; the parties synchronously exchange data over UDP.
-
Lockstep — synchronous exchange «frame by frame» Each side waits for the other’s response before proceeding to the next step of the calculation.
-
A PWM frame is a set of control signals (pulse width modulation) for motors that SITL sends to Engee.
-
JSON sensor frame — response Engee with virtual sensor data (position, orientation, speeds) serialized in JSON.
-
MAVProxy is an open—source lightweight ground control station (GCS) running on the command line and designed for systems using the MAVLink protocol (for example, ArduPilot); it relays telemetry to the outside in this infrastructure.
-
GCS (Ground Control Station) is a software application on a ground computer that communicates wirelessly with the autopilot and is used for parameter setting, mission planning, real—time monitoring, and manual flight control.
How the infrastructure works
The infrastructure for running the simulation is a Docker container.
The container is located in the catalog of support package examples (example_ardupilot/ardupilot-sitl). Get examples of the support package in Engee you can use the command:
engee.package.getdemos("Engee-Device-Manager")
Two processes are running in the container:
-
ArduPilot SITL (
arducopter) in the mode of calculating the physical parameters of the simulation in Engee. In this mode, the autopilot does not calculate the physics of the device itself: it sends Engee PWM motor control frames via UDP per port9002and expects a JSON frame with sensor data in response. The exchange is synchronized (lockstep); the exchange frequency is set in the autopilot parameters file (see Autopilot parameters). -
MAVProxy connects to the Ardupilot SITL and relays the MAVLink telemetry to the outside. This approach allows a single telemetry stream to reach several consumers at once: on a UDP port.
14550— for the ground station (GCS), on14551— for Engee, on14552— for diagnosis.
The exchange scheme:
ArduPilot SITL (контейнер) Engee
ШИМ-кадр, UDP 9002 ---------> Ardupilot Setup / Ardupilot RX
<--------- JSON-кадр сенсоров, UDP 9002 (Ardupilot TX)
MAVProxy (контейнер)
телеметрия MAVLink ----------> UDP 14550 (наземная станция GCS)
UDP 14551 (блоки MAVLink в Engee)
UDP 14552 (диагностика)
Ports
| Port | Direction | Appointment |
|---|---|---|
UDP 9002 |
Ardupilot SITL ↔ Engee |
PWM frames from Ardupilot SITL in Engee, JSON sensor frames from Engee in Ardupilot SITL |
UDP 14550 |
MAVProxy → GCS |
MAVLink telemetry for the ground station |
UDP 14551 |
MAVProxy → Engee |
MAVLink telemetry for MAVLink blocks |
UDP 14552 |
MAVProxy → Engee |
diagnostics |
What needs to be installed
Docker
-
Windows — Docker Desktop. WSL2 is installed automatically, there is no need to configure anything manually.
-
Linux — Docker Engine and the compose plugin:
sudo apt-get update sudo apt-get install -y docker.io docker-compose-v2
Launch
Windows
-
Install and run Docker Desktop, wait for the Ready status.
-
Launch
windows\build_and_run.batfrom the catalogardupilot-sitl. The first build takes about 30 minutes (cloned and compiled by ArduPilot), subsequent runs take seconds. -
Check that the container has risen:
docker ps -a
At the container ap_physics There must be a status Up X minutes.
Customization Engee
-
In Engee open the example model
example_engee_ardupilot_flight.engeefrom the catalog of support package examples (example_ardupilot). -
Execute the script
Quadcopter_Parameters.ngscript— it sets the parameters of the physics of the device: the mass, the position of the motors relative to the center of mass, the speed limit of the screws and the coefficients of the regulators. -
Run the simulation. The model contains a subsystem
Ardupilot controlwith blocks Ardupilot Setup, Ardupilot RX and Ardupilot TX, configured for UDP127.0.0.1:9002; the frequency of the model calculation steps is set according to the frequency of the autopilot cycle from the parameter file.
Launch order: first the container, then the model Engee — block Ardupilot Setup waits for the first PWM frame from Ardupilot SITL during 5 seconds after the start of the simulation.
Ground Station (GCS)
A ground station is optional for simulation: Engee communicates with autopilot directly over UDP 9002. However, MAVProxy relays the MAVLink telemetry to the outside: to the UDP port 14550 — for the ground station, on 14551 — for Engee, on 14552 — for diagnostics. Thanks to this, several consumers can be connected to telemetry at the same time: for example, to monitor the flight and control the device from a ground station, while the same data continues to flow to Engee to the port 14551.
To receive telemetry, configure the ground station to use the ArduPilot protocol and receive data over UDP on the port. 14550.
Autopilot Settings
The behavior of ArduPilot is configured by the parameter file common/engee_physics.parm, which is mounted in a container. The parameter file is a standard configuration method for ArduPilot: it sets the frequency of the simulation cycle and the main control loop, the coefficients of the regulators (angles, angular velocities, positional contours), motor parameters, reinforcement conditions, and other autopilot settings.
File engee_physics.parm, which comes with the container, belongs to the demo model example_engee_ardupilot_flight.engee from the catalog of examples of the support package: it is configured for the device and the physics of this particular model. For your own model, create your own parameter file. The frequency of exchange in it should correspond to the step of calculating the model, and the autopilot settings should correspond to the type and design of the device.
The frequency of exchange in the simulation mode is set in this file, which is the step of calculating the model. Engee must match it.
To change the parameters, edit common/engee_physics.parm and restart the container (run again build_and_run.bat / build_and_run.sh).
The default home point of the device: -35.363261, 149.165237, 584, 0 (latitude, longitude, altitude, direction). It can be changed by an environment variable. HOME_LOC in the file docker-compose.yml.
Network
Interaction Engee and the container does not require manual port configuration.: Engee always listens to the UDP port 9002 on your car (address 127.0.0.1), and the container delivers its packages there by itself.
-
Windows — The container runs on the Docker Desktop bridge network and accesses the host via
host.docker.internal; all traffic is outbound, so the container packets end up on UDP9002cars with Engee. -
Linux — the container runs on the host network and communicates with Engee and a ground station directly via
127.0.0.1.
The difference between the platforms has already been taken into account in docker-compose.yml for each of them (variables SIM_HOST and GCS_HOST) — shared files do not need to be changed.
Diagnostics
| Problem | What to check |
|---|---|
Container |
|
The model stopped with an error |
is the container running; is the UDP port busy |
There is no telemetry in the ground station (GCS) |
does GCS listen to UDP |