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 compiles the full ArduPilot flight stack and runs it as a native process on your development machine. The simulated vehicle receives realistic sensor data from a physics model and responds exactly as it would on real hardware — making it the primary environment for developing and validating code changes before any physical flight.

​
How SITL works

SITL uses the AP_HAL_SITL hardware abstraction layer, which replaces drivers for IMU, GPS, barometer, and other sensors with software models. A separate physics backend (the default is ArduPilot’s built-in model, with optional external simulators) generates the sensor data and receives actuator outputs in a closed loop. The sim_vehicle.py script in Tools/autotest/ handles building the binary, launching the physics model, and starting MAVProxy for ground control. 
Tools/autotest/sim_vehicle.py   ← launch script
SITL/                           ← physics model backends
libraries/AP_HAL_SITL/          ← HAL implementation for SITL

​
Supported vehicle types

Vehicle flag (-v)Description
ArduCopterMultirotor vehicles (quad, hexa, octa, y6, heli, …)
ArduPlaneFixed-wing and VTOL aircraft
RoverGround rovers and boats
ArduSubUnderwater ROVs
AntennaTrackerAntenna tracker
BlimpBlimp vehicle

​
Running SITL

The fastest way to start is with sim_vehicle.py, which configures, builds, and launches the simulation in one command.
1

Install prerequisites

Follow the ArduPilot environment setup guide for your OS, then clone the repository with all submodules:
git clone --recurse-submodules https://github.com/ArduPilot/ardupilot.git
cd ardupilot
2

Launch a copter simulation

Run sim_vehicle.py with the -v flag to select a vehicle. The script builds the binary automatically on first run:
Tools/autotest/sim_vehicle.py -v ArduCopter
MAVProxy starts in the same terminal. You should see the copter armed and ready on the MAVProxy console.
3

Open the map and console

Add --map and --console to get a moving-map display and a parameter/flight-mode console:
Tools/autotest/sim_vehicle.py -v ArduCopter --map --console
4

Choose a different frame

Use --frame (-f) to select a specific airframe. For example, to simulate a traditional helicopter:
Tools/autotest/sim_vehicle.py -v ArduCopter -f heli --map --console

​
Frame types

The --frame option selects the motor layout for the vehicle. The most common copter frames are:
FrameDescription
quad (default)4-motor quadrotor in + configuration
X4-motor quadrotor in X configuration
hexa6-motor hexarotor
octa8-motor octorotor
octa-quad8-motor octa-quad
y6Y6 coaxial tricopter
triTricopter
heliTraditional helicopter
heli-dualDual-rotor helicopter
For ArduPlane you can use frames such as plane, quadplane, plane-elevon, and plane-vtail. For external simulators, frames like gazebo-iris and airsim-copter are available.

​
Common sim_vehicle.py options

Tools/autotest/sim_vehicle.py -v ArduCopter \
  -f hexa \             # frame type
  -L KSFO \             # start location (named location or lat,lon,alt,hdg)
  --speedup 5 \         # run simulation at 5× real time
  --wipe \              # wipe EEPROM (reset all parameters)
  --map \               # open a moving-map window
  --console             # open a MAVProxy console window
Runs the simulation faster than real time. Useful for long missions or autotest runs. --speedup 1 is real time (default); higher values trade timing accuracy for speed.
Deletes the simulated EEPROM file so the vehicle starts with factory defaults. Use this when switching frame types or after parameter corruption.
Sets the takeoff location. Named locations (e.g., KSFO, CMAC) are defined in Tools/autotest/locations.txt. You can also pass a raw lat,lon,alt,heading string.
Forwards MAVLink traffic to an additional endpoint. Example: --out 127.0.0.1:14550 to connect a second ground station.

​
External simulators

SITL can delegate physics to an external simulator for higher-fidelity models or sensor simulation:

Gazebo

ROS-friendly robot simulator with plugin-based sensor models. Use the gazebo-iris frame and the ArduPilot Gazebo plugin.

JSBSim

High-fidelity fixed-wing aerodynamics. Integrated directly; select with -f jsbsim.

FlightGear

Open-source flight simulator used for visual rendering. Connect via the flightgear model.

X-Plane

Commercial flight simulator. Connect using the xplane model flag with SITL acting as the autopilot.

​
MAVProxy integration

sim_vehicle.py starts MAVProxy automatically and connects it to the SITL process. Useful MAVProxy commands during a session: 
arm throttle          # arm the vehicle (bypasses pre-arm checks)
mode GUIDED           # switch to GUIDED flight mode
takeoff 20            # command a 20 m takeoff
wp load mission.txt   # load a waypoint file
param set SYSID_THISMAV 1   # set a parameter at runtime
You can connect Mission Planner or QGroundControl to the default UDP port 14550 while SITL is running to use a full GCS interface alongside MAVProxy.

​
Autotest framework

Tools/autotest/autotest.py is the integration test runner used by CI. It builds a vehicle binary and executes scripted test scenarios against SITL, checking that the vehicle behaves correctly. 
# Build ArduCopter and run all copter tests
Tools/autotest/autotest.py build.Copter test.Copter

# Run a single named test
Tools/autotest/autotest.py build.Copter test.Copter.RTLYaw
Vehicle test suites live alongside the launcher: Tools/autotest/arducopter.py, arduplane.py, rover.py, and ardusub.py. Each test method arms the vehicle, executes a manoeuvre, and asserts expected behaviour.
SITL is the recommended environment for testing Lua scripts. Place your .lua file in a scripts/ directory inside the working directory and launch SITL as normal. Set SCR_ENABLE=1 in MAVProxy (param set SCR_ENABLE 1) and reboot the simulated vehicle.

Build docs developers (and LLMs) love

Get started for freeTalk to us