32. starling-sim-ardupilot-copter/plane

There are two images currently built: starling-sim-arducopter and starling-sim-arduplane. These are built against the relevant stable branch: ArduCopter-stable and ArduPlane-stable respectively.

The SITL starts up with a TCP server listening on port 5760. It will not begin simulating the vehicle until a connection is made to this port. Currently, the SITL's built-in simulator is used for both copter and plane images.

32.1 Environment Variables

Name Default Value Description
AP_SYSID 1 MAVLink system ID to be used by the SITL. Can also be set to "ordinal" or "ip"
AP_SYSID_BASE 1 Base system ID for ordinal-based generation
AP_VEHICLE {from build arg} Which vehicle is being used. Either "copter" or "plane"
AP_MODEL {null} Alternate model argument. Set to override default model
AP_PARAM_PATH {null} Alternate path to parameter file. Set to override default path
AP_PARAM_FILE {null} Alternate parameter file name. Set to override default parameter file
AP_HOME 51.4235413,-2.6708488,50,250 Start location for SITL
AP_OFFSET_X 0 Start location x offset for SITL
AP_OFFSET_Y 0 Start location y offset for SITL
AP_DISTRIBUTE {null} If set, automatically generate AP_OFFSET_X and AP_OFFSET_Y
AP_USE_GAZEBO {null} If set, use a Gazebo model as physics backend
AP_SIM_ADDRESS IP address to use for talking to Gazebo instance
AP_SIM_HOST {null} Hostname to use for talking to Gazebo instance. Will override AP_SIM_ADDRESS

32.1.1 AP_SYSID

Sets the MAVLink system ID to be used by the SITL. This must either be a value between 1 and 255 inclusive or set to "ordinal" or "ip". Other values will cause the container to exit.

When set to "ordinal, the entrypoint script will attempt to retrieve a 0-indexed ordinal from the end of the container's hostname. The hostnames should be of the form ${HOSTNAME}-${ORDINAL}, e.g. sitl-0, sitl-1, sitl-3. This behaviour supports deployment of this image as part of a Kubernetes StatefulSet.

When set to "ip", the entrypoint script retrieves the last octet of the container's IP address and uses that as the system ID. e.g. will result in a system ID of 4.

At present, the system ID is set by appending it to the parameter file. If a custom parameter file is supplied, it should not contain the SYSID_THISMAV parameter.


This variable only affects the container when using the ordinal-based generation outlined above. The value set here will be added to the ordinal from the hostname to derive the MAVLink system ID. If the resultant value is not a valid system ID, i.e. it is not between 1 and 255 inclusive, the container will exit.


By default this will be either "copter" or "plane" and is derived from the image's arguments at build time. This argument is used to set which executable is used and should not be overriden. It is also used to set defaults for the MODEL and PARAM_FILE variables unless they are overridden.

32.1.4 AP_MODEL

Used as the value of the --model argument to the ArduPilot SITL binary. For copter images, this is set to quad. For plane images, this is set to plane.


The path to the folder containing the parameter file. If left blank, the in-source folder will be used: Tools/autotest/default_params. This can be changed to allow for supplying a custom set of parameter files through a volume mount. The final folder on the path should be default_params.


Comma separated list of alternate set of parameter file paths to use. If set this overrides the default parameter files used. AP_PARAM_PATH is ignored if this is set so the absolute paths to files are needed. An additional file will be appended to set the system ID.


AP_HOME sets the start location for the SITL. Format is {Latitude},{Longitude},{Altitude},{Heading}

AP_OFFSET_X and AP_OFFSET_Y are body frame offsets in metres from AP_HOME for this vehicle. This allows a grid of vehicles to be created using a single AP_HOME while varying the offsets.


When set, AP_DISTRIBUTE directs the entrypoint script to automatically generate offsets. It does this based on the final value of the AP_SYSID environment variable, i.e. after it has been resolved into a number. This number then dictates the position of the vehicle within a 16 by 16 grid, with the position of AP_HOME at the (0,0) position. The grid lines are laid out at 1m separations. As a SYSID of 0 is invalid, no vehicle will be placed directly on the AP_HOME position.


When set, AP_USE_GAZEBO will cause the SITL to connect to an instance of the ArduPilot plugin running as part of a Gazebo model. At present, this will use the default IP and port pair:


Use this to adjust the IP address that the SITL uses to connect to the simulator backend. At present, this is only relevant when AP_USE_GAZEBO is set.

32.1.11 AP_SIM_HOST

When set, the container will resolve the hostname stored in this variable using getent hosts. The value from the lookup will be used in preference to any address set in AP_SIM_ADDRESS. If the hostname lookup fails, the container will exit early.

32.2 Dockerfile Build Arguments

32.2.1 VEHICLE

Controls which target is built. Passed as ./waf ${VEHICLE} to build the SITL. Also set as the value of the AP_VEHICLE environment variable. By default this is set to copter

32.2.2 BRANCH

Set the branch of ArduPilot to checkout prior to build. By default this is set to ArduCopter-stable