Servers by jDrones

Run Simulator SITL using pre-built Docker image with your GCS (MacOS/XQuartz tutorial)


(Dr Nic Williams) #1

UPDATE: please see @luisvale comment about running natively within MacOS. I didn’t know this when I wrote the Docker image nor this tutorial. Hurray for better information! :slight_smile:

For MacOS we have several ground control GCS options including APM Planner 2 and QGroundControl, unfortunately neither offer in-built Simulator In The Loop (SITL) like the Windows-only Mission Planner.

Fortunately SITL can be run standalone from the ardupilot github project, and the GCS can automatically discover SITL. Unfortunately it is a relatively lengthy sequence of steps for MacOS users via Vagrant. For MacOS users I wrote up a Tutorial for running SITL Simulator on MacOS with Vagrant + XQuartz.

I wondered if it would be a nice UX for people to use Docker and a pre-built Docker image. And it sort of is nice. Except for the 3G+ size of the Docker image layers, which hopefully we can improve on in future.

To get started on MacOS, install Docker, and Xquartz.

To configure and run Xquartz, download the pre-built Docker image drnic/ardupilot-sitl, and run your favourite simulator robot:

HOST_IP=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')
xhost + $HOST_IP

docker run -ti -e HOST_IP=$HOST_IP -e DISPLAY=$HOST_IP:0 \
  -v /tmp/.X11-unix:/tmp/.X11-unix -p 14550:14550 \
  drnic/ardupilot-sitl \
  Tools/autotest/ \
  --no-rebuild --console --map --out=$HOST_IP:14550 \
  -v APMrover2 -L Kingaroy

The first time you run docker run ... drnic/ardupilot-sitl ... it will download all the layers of the Docker image. This is currently 3G+. Sorry about that.

You should see two windows appear with the ArduRover simulator centered on Kingaroy airport. I can feel the speed already along that tarmac.

You can replace -v APMrover2 with -v ArduPlane, -v ArduCopter, -v Helicopter; and could replace -L Kingaroy with -L <location> from

Any tutorial in should “just work”.

You can pass the -h flag to the end and see the flag options, such as:


  -h, --help            show this help message and exit
  -v VEHICLE, --vehicle=VEHICLE
                        vehicle type (ArduCopter|AntennaTracker|APMrover2|Ardu
  -f FRAME, --frame=FRAME
                        set vehicle frame type
                        ArduCopter: octa-quad|cwx|singlecopter|gazebo-
                        AntennaTracker: tracker
                        APMrover2: rover|rover-
                        ArduSub: gazebo-bluerov2|vectored
                        ArduPlane: quadplane-
  -C, --sim_vehicle_sh_compatible
                        be compatible with the way works; make
                        this the first option
  -H, --hil             start HIL

SITL, whilst running inside Docker, still exposes MAVProxy to your local machine on port 14550.

This means you can now launch your GCS - APM Planner 2, QGroundControl, etc - and they should immediately connect to your simulator.

Very exciting. Our MacOS GCS has a locally running SITL.

The pre-built Docker image is currently a fork of upstream ardupilot, with the image regularly rebuilt from any changes to upstream (see Concourse CI pipeline).

Re-pull the image to get new SITL/ardupilot updates (about 300M update each time):

docker pull drnic/ardupilot-sitl

If you have any troubles with this tutorial or the Docker image please let me know below and I’ll try to resolve it or help you out. I enjoyed seeing SITL + GCS working over Docker/Xquartz and hopefully its useful to others.

(Luís Vale Gonçalves) #2

You are aware that SITL runs natively on MacOS, so dispensing the need of Vagrant and XQuartz.

./Tools/autotest/ -v ArduCopter -f heli -L MyLocation

or if you want to do from master

cd ~/Ardupilot

 ./waf distclean

git submodule deinit -f. 

git clean -f-x -d 

git pull

git submodule update --init --recursive

./Tools/autotest/ -v ArduCopter -f heli -L MyLocation

which can be made on a simple script.

Tutorial for running SITL Simulator on MacOS with Vagrant + XQuartz
(Dr Nic Williams) #3

That is fabulous.

And I’ll acknowledge – I’m quite annoyed at myself that I never tried it over the last week just because it wasn’t explicitly mentioned in the docs. I’m quite the idiot :confused:


I went down the whole path of getting vagrant/xquartz working and then docker/xquartz. Damn.

But thank you very much for pointing this out; natively running is great.

(Luís Vale Gonçalves) #4


Our bad at ArduPilot, for not keeping up documentation :slight_smile:

(Dr Nic Williams) #5

Reading thru it references the Tools/scripts/ -y script that I’ve seen in my Docker/Vagrant setups. I’m aware just how much stuff this script installs; and that it assumes ubuntu/debian. I didn’t seem to have to do this for MacOS. Do you know what the equivalent MacOS/homebrew dependencies are? I’ll look at writing a MacOS docs page.

(Mike Boland) #6

All I get here on @luisvale ./Tools commands is
Traceback (most recent call last):
File “./Tools/autotest/”, line 25, in
from MAVProxy.modules.lib import mp_util
ImportError: No module named MAVProxy.modules.lib

Are there dependancies missing or am I just missing something.

(Luís Vale Gonçalves) #7

I’ll have to redo these instructions for Mojave, but you do have an equivalent script

check the script. it installs the dependencies.

(rmackay9) #8

Thanks for this. I hope it’s OK, I copied the first image to the top of the blog post. It means there are duplicate images but it also looks nicer when viewed from to have an image at the top.

(Mike Boland) #9

Have followed all this through and installed everything without error.

(peterbarker) #10

I merged a patch fixing this earlier today…

(Luís Vale Gonçalves) #11

the --user one ? Wasn’t required. Perhaps more important would be to move all the tools to python3 exclusively, and finish the mixed bag of required versions.