Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Ardupilot/ardupilot/llms.txt

Use this file to discover all available pages before exploring further.

Software-In-The-Loop (SITL) simulation lets you build and run ArduPilot firmware entirely on your desktop computer. The simulated vehicle responds to the same MAVLink messages as real hardware, so you can develop, test, and debug autopilot behavior without ever needing a physical flight controller. This guide walks through cloning the repository, installing dependencies, building ArduCopter for SITL, and launching the simulator with MAVProxy.
Never run waf with sudo. Running the build system as root causes permission and environment problems that are difficult to recover from. Always call ./waf as a regular user from the repository root.
1

Clone the repository with submodules

ArduPilot depends on several Git submodules (ChibiOS, MAVLink definitions, googletest, and others). Clone with --recurse-submodules to fetch them all in one step:
git clone --recurse-submodules https://github.com/ArduPilot/ardupilot.git
cd ardupilot
If you already cloned without submodules, initialize them with:
git submodule update --init --recursive
2

Install dependencies

ArduPilot provides platform-specific prerequisite scripts under Tools/environment_install/. For Ubuntu or Debian:
Tools/environment_install/install-prereqs-ubuntu.sh -y
After the script completes, reload your shell environment so that newly installed tools (including MAVProxy) are on your PATH:
. ~/.profile
For macOS, use Tools/environment_install/install-prereqs-mac.sh instead.
3

Configure the build for SITL

The configure step only needs to be run once, or whenever you want to change the target board. For SITL, pass --board sitl:
./waf configure --board sitl
To include debug symbols (useful when attaching gdb to the simulator):
./waf configure --board sitl --debug
4

Build ArduCopter

With the board configured, build the ArduCopter firmware. Waf automatically parallelizes the build across all available CPU cores:
./waf copter
The resulting binary is placed at build/sitl/bin/arducopter. You can also build other vehicle types in the same way — ./waf plane, ./waf rover, ./waf sub — after configuring for SITL.
5

Launch the SITL simulator

sim_vehicle.py is the primary entry point for starting a simulated vehicle. It handles launching the ArduPilot binary with the correct SITL arguments and optionally starting MAVProxy:
Tools/autotest/sim_vehicle.py -v ArduCopter
Pass --map and --console to open a moving-map display and a telemetry console in MAVProxy automatically:
Tools/autotest/sim_vehicle.py -v ArduCopter --map --console
Use -f to select a specific frame type, for example -f quad, -f hexa, or -f heli for a traditional helicopter.
The simulator starts and MAVProxy connects automatically. You will see MAVLink heartbeat messages and sensor data streaming in the terminal.
6

Connect with MAVProxy

MAVProxy is started automatically by sim_vehicle.py. Once the simulator is running, you can interact with it directly from the MAVProxy prompt. Common commands to get started:
# Arm the vehicle
arm throttle

# Switch to guided mode and take off to 20 metres
mode guided
takeoff 20

# Return to launch
mode rtl
To connect an external ground control station (such as Mission Planner or QGroundControl) running on the same machine, add an output port when launching:
Tools/autotest/sim_vehicle.py -v ArduCopter --out=127.0.0.1:14551
The GCS should then be able to connect on UDP port 14551.

Build docs developers (and LLMs) love

Get started for freeTalk to us