diff --git a/dev/source/docs/SITL-setup-landingpage.rst b/dev/source/docs/SITL-setup-landingpage.rst index 017c37ac36..809817fefb 100644 --- a/dev/source/docs/SITL-setup-landingpage.rst +++ b/dev/source/docs/SITL-setup-landingpage.rst @@ -4,13 +4,14 @@ Setting Up SITL =============== -These documents discuss how to install and setup the SITL environment in Linux and Windows +These documents discuss how to install and setup the SITL environment in Linux, Windows and Mac OSX .. toctree:: :maxdepth: 1 SITL setup on Linux SITL setup on Windows + SITL setup on MacOSX SITL setup on Windows in a VM SITL setup using Vagrant diff --git a/dev/source/docs/setting-up-sitl-on-macosx.rst b/dev/source/docs/setting-up-sitl-on-macosx.rst new file mode 100644 index 0000000000..a48fd71e48 --- /dev/null +++ b/dev/source/docs/setting-up-sitl-on-macosx.rst @@ -0,0 +1,137 @@ +.. _setting-up-sitl-on-macosx: + +=========================== +Setting up SITL on Mac OS X +=========================== + +This page describes how to setup the :ref:`SITL (Software In The Loop) ` on Mac OS X. The specific commands were tested on macOS Catalina 10.15.7 and macOS Big Sur 11.1. + +Overview +======== + +The SITL simulator allows you to run Plane, Copter or Rover without any +hardware. It is a build of the autopilot code using an ordinary C++ +compiler, giving you a native executable that allows you to test the +behaviour of the code without hardware. + +SITL runs natively on Linux, Windows and Mac OSX. + +.. image:: ../images/SITL_macosx.png + :target: ../_images/SITL_macosx.png + + +Install steps +============= + +This guide assumes that a build environment is already setup for Ardupilot. If that is not the case please follow the available guides to setup the build environment for Mac OSX. The following step provide a condensed versions of the steps to take. + + +Prerequisites +------------- + +The following tools need to be installed to complete the installation. Between brackets the version used by the author at time of writing. + + * Xcode (12.4) + * Xcode commandline tools (12.4) + * Homebrew (3.0.4-52-gbc37074) + +Preparing Python +---------------- + +Install the required python 3 version using homebrew and activate it. If you are familiar with pyenv or virtualenv it might be better to use one of those to setup the environment. This limits potential problems with other tools that require specific versions of python. How to do that is beyond the scope of this document. + +The following steps install python version 3.9.x for system wide usage. + +:: + + brew install python@3.9 + export PATH="$(brew --prefix)/opt/python/libexec/bin":$PATH + + pip install wheel + pip install future pymavlink mavproxy + +Optional: Add the following to the either .bashrc or .zshrc to enable this version of python be default + +:: + + export PATH="$(brew --prefix)/opt/python/libexec/bin":$PATH + + +Optional: Install sfml (used by sitl for audio and osd) + +:: + + brew install sfml + +Note that not all sfml features work on Mac OSX currently. The following error can appear `Cannot create a window from a worker thread. (OS X limitation)`, this is a result of Mac OSX specifics that haven't been catered for in the sitl code yet. + +Start SITL simulator +-------------------- + +.. warning:: + + Due to ideosyncracies with Python and using screens there are limitations when Python needs to use the screen to display a graphical UI. Python 3.9 solves part of the problem by no longer requiring a separate pythonw binary. However the requirement to run on the main display still stands. When observing the error "This program needs access to the screen. Please run with a Framework build of python, and only when you are logged in on the main display of your Mac.", disconnect external displays during startup. When SITL is started the windows can be moved around as normal. + +To start the simulator first change directory to the vehicle directory. +For example, for the multicopter code change to **ardupilot/ArduCopter**: + +:: + + cd ardupilot/ArduCopter + +The sim_vehicle script checks several environment variables to determine the OS it's running on. For Mac OSX it +requires that DISPLAY is set. + +:: + + export DISPLAY=:0.0 + +Then select the correct python environment (if not enabled by default) + +:: + + export PATH="$(brew --prefix)/opt/python/libexec/bin":$PATH + +Then start the simulator using **sim_vehicle.py**. The first time you +run it you should use the -w option to wipe the virtual EEPROM and load +the right default parameters for your vehicle. + +:: + + sim_vehicle.py -w + +After the default parameters are loaded you can start the simulator +normally. First kill the sim_vehicle.py you are running using Ctrl-C. Then: + +:: + + sim_vehicle.py --console --map + +.. tip:: + + `sim_vehicle.py `__ + has many useful options, ranging from setting the simulation speed + through to choosing the initial vehicle location. These can be listed by + calling it with the ``-h`` flag (and some are demonstrated in :ref:`Using SITL for ArduPilot Testing `). + +.. tip:: + + If the map tiles don't load, you can temporarily change the map provider in the map window by clicking View/Service. + To keep the new map service between launches, add the following lines to the end of your ".bashrc" (change MicrosoftHyb to the provider you want): + + :: + + export MAP_SERVICE="MicrosoftHyb" + + +Learn MAVProxy +-------------- + +To get the most out of SITL you really need to learn to use MAVProxy. +Have a read of the :ref:`MAVProxy documentation `. Enjoy flying! + + +Next steps +========== + +After installation, see :ref:`Using SITL for ArduPilot Testing ` for guidance on flying and testing with SITL. diff --git a/dev/source/images/SITL_macosx.png b/dev/source/images/SITL_macosx.png new file mode 100644 index 0000000000..15cb53c17a Binary files /dev/null and b/dev/source/images/SITL_macosx.png differ