Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PX4/PX4-Autopilot/llms.txt

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

PX4 supports two simulation approaches that let you develop and test flight software without risking hardware. Software-In-The-Loop (SITL) runs the entire PX4 flight stack as a process on your computer, paired with an external physics simulator. Hardware-In-The-Loop (HITL) runs real PX4 firmware on a flight controller board but feeds it simulated sensor data instead of live hardware inputs. Both modes let you interact with PX4 through QGroundControl, offboard APIs like MAVSDK or MAVROS, and joysticks or gamepads — exactly as you would with a real vehicle.

​
SITL vs HITL

Software-In-The-Loop (SITL)

The full PX4 flight stack runs as a native process on your development machine. A separate simulator process provides physics, sensor data, and rendering. No flight controller hardware required. Best for rapid development, algorithm testing, and CI pipelines.

Hardware-In-The-Loop (HITL)

Real PX4 firmware runs on your flight controller board. Simulated sensor data is injected over USB/serial. Tests real hardware timing and driver behavior without spinning motors. Best for pre-flight integration testing.
HITL simulation requires a supported flight controller running standard PX4 firmware. Flash your board with a HITL-enabled build, enable SYS_HITL=1, and connect it via USB before launching the simulator.

​
Supported simulators

The PX4 core team actively maintains two simulators. Choose based on your workflow.

Gazebo

The recommended simulator for new projects on Ubuntu 22.04 and later. Offers photorealistic 3D rendering, a rich sensor library (cameras, LiDAR, depth sensors), custom worlds and model plugins, and documented multi-vehicle support. Communicates with PX4 directly via Gazebo Transport — no MAVLink required.Supported vehicles: Quadrotor (x500), Plane, Standard VTOL, Tailsitter, Tiltrotor, Rovers

SIH (Simulation-In-Hardware)

A lightweight, zero-dependency simulator that runs physics entirely inside PX4 as a C++ module. Headless by default for maximum iteration speed. Works on macOS Apple Silicon. Can also run on flight controller hardware (SYS_HITL=2). Communicates via uORB — no MAVLink or external process required.Supported vehicles: Quad, Hex, Plane, Tailsitter, Standard VTOL, Rover
Gazebo Classic is being downgraded to community-supported status and is no longer recommended for new projects. Use Gazebo (formerly Gazebo Ignition) instead. Gazebo Classic remains available but will not receive core team maintenance going forward.

​
Simulator comparison

FeatureGazeboSIH
Default modeGUI with 3D renderingHeadless (fastest iteration)
Physics engineExternal (gz-physics)Internal C++ module via uORB
External dependenciesGazebo packages, rendering libsNone
Sensor simulationCamera, LiDAR, depth, IMU, GPS, baro, magIMU, GPS, baro, mag, airspeed
Multi-vehicleYesYes
ROS 2 integrationYes (uXRCE-DDS)Yes (uXRCE-DDS)
Runs on FC hardwareNoYes (SYS_HITL=2)
macOS Apple SiliconUnstableWorks natively
Faster-than-realtimeYesYes

​
Choosing a simulator

  • Full 3D rendering, custom worlds, camera/LiDAR sensors, or ROS integration: Use Gazebo. Largest ecosystem, photorealistic rendering, extensive sensor library.
  • Fast headless iteration, controls research, zero-dependency setup, or macOS: Use SIH. Runs entirely inside PX4 with no external dependencies; physics parameters are directly tunable via SIH_* parameters.
  • Hardware integration testing without propellers: Use SIH on flight controller hardware with SYS_HITL=2.
SITL instances communicate over UDP. PX4 uses fixed default ports so that QGroundControl and offboard APIs connect automatically.
PortDirectionPurpose
14550PX4 → GCSQGroundControl and other ground stations listen here by default
14540PX4 → Offboard APIMAVSDK, MAVROS, and other developer APIs listen here
4560Simulator → PX4PX4 opens a TCP connection to the simulator on this port (MAVLink-based sims only)
Multi-vehicle simulations allocate a separate offboard API port per instance, sequentially from 14540 to 14549. Additional instances beyond ten all share port 14549.
Gazebo communicates with PX4 via Gazebo Transport (not MAVLink), so the TCP port 4560 does not apply. SIH uses uORB internally and requires no network ports at all. By default, PX4 routes MAVLink traffic to localhost only. To expose the simulation to QGroundControl running on another machine, you can use mavlink-router, enable UDP broadcasting with the -p flag in the mavlink module, or set up an SSH tunnel.

​
Connecting QGroundControl

QGroundControl connects to SITL automatically when it detects a MAVLink heartbeat on UDP port 14550. No manual configuration is needed when running PX4 SITL on the same machine as QGroundControl.
1

Start the simulation

Launch PX4 SITL with your chosen simulator. The flight stack will begin broadcasting MAVLink heartbeats on port 14550.
make px4_sitl gz_x500
2

Open QGroundControl

Launch QGroundControl. It listens on UDP port 14550 by default and will detect the simulated vehicle within a few seconds.
3

Verify connection

The vehicle icon appears on the QGroundControl map. You can arm, set flight modes, plan missions, and monitor telemetry exactly as you would with real hardware.
If QGroundControl does not connect automatically, confirm that no firewall is blocking UDP port 14550, and that the simulation is running on the same host or that you have configured MAVLink routing to reach the remote machine.

​
Running simulation faster than real time

SITL supports faster-than-realtime execution for all supported simulators. Set the PX4_SIM_SPEED_FACTOR environment variable before launching: 
PX4_SIM_SPEED_FACTOR=2 make px4_sitl gz_x500
PX4 SITL and the simulator run in lockstep, meaning they advance time together. This makes arbitrary speed multipliers and step-through debugging possible without desynchronizing sensor and actuator messages.

​
Simulating failsafes

You can trigger safety failsafes such as GPS failure, battery drain, and RC signal loss inside the simulation to test your vehicle’s behavior before flying for real. To simulate GPS failure, set the SENS_GPS_MASK parameter or use the MAVLink shell: 
# In the PX4 shell (pxh>), force GPS failure:
failure gps off
# Re-enable GPS:
failure gps ok
Other injectable failures include battery (failure battery off), RC signal loss (failure rc off), and barometer failure (failure baro off).

Build docs developers (and LLMs) love

Get started for freeTalk to us