PX4 Autopilot: Architecture, Failsafes & ROS 2

PX4 Autopilot

PX4 is an open-source flight control stack for drones and other unmanned vehicles, hosted by the Dronecode Foundation under the Linux Foundation and licensed under the permissive BSD-3 license. It powers multicopters, fixed-wing aircraft, VTOLs, and rovers, and is widely used by commercial drone makers, researchers, and integrators — particularly those building on ROS 2, thanks to PX4's native DDS bridge.

PX4 is built as a set of modules that communicate through an internal publish-subscribe bus called uORB, running on the NuttX real-time operating system on flight controllers (and on Linux for some targets and for simulation). Understanding this architecture — which module estimates the state, which decides modes and failsafes, which runs each control loop — is the key to configuring, extending, and debugging PX4 vehicles safely.

TL;DR

PX4 runs on NuttX with modules connected by uORB topics: sensors, EKF2, commander (arming, modes, failsafes), navigator (missions, return), controllers, and control allocation.
Vehicles are defined by airframe configurations and dynamic control allocation (actuator geometry set in parameters).
Configure with QGroundControl; script with MAVSDK; integrate with ROS 2 through uXRCE-DDS, which exposes uORB topics directly.
Set failsafe actions (RC loss, data link loss, low battery, geofence, offboard loss) before autonomous flight.
Develop in SITL with Gazebo, use HITL for flight-controller timing, and review ULog files in Flight Review.
Extend with custom modules or offboard software, and validate changes up a controlled test ladder.

Quick Example

Configuring failsafes and a geofence from the PX4 shell (in SITL, the pxh> prompt; on hardware, the MAVLink console in QGroundControl):

Starting SITL and bridging PX4 topics into ROS 2:

Core Concepts

Architecture

Because modules exchange data only through uORB topics, the listener and uorb top shell commands, logs, and ROS 2 topics all show the same internal state. See Real-Time Operating Systems.

Airframes and Control Allocation

Airframe configurations set defaults for a vehicle class; dynamic control allocation describes motor and servo positions, directions, and functions in parameters, so new geometries rarely need code changes. Actuator testing in QGroundControl verifies motor order and direction before first flight.

Flight Modes and Failsafes

Manual modes (Stabilized, Acro), assisted modes (Altitude, Position), and autonomous modes (Mission, Return, Land, Hold, Takeoff, Offboard) are managed by the commander. Its failsafe state machine applies configured actions for RC loss, data link loss, low battery, geofence breach, estimator problems, and offboard loss — set what happens if the companion computer stops sending setpoints. Preflight checks block arming when sensors, calibration, or estimator health are inadequate. See Drone Autopilot Systems.

Ground Control and Integration

QGroundControl configures airframes, calibrates sensors, sets parameters, plans missions, and displays telemetry.
MAVSDK provides a high-level API in C++, Python, and other languages over MAVLink.
uXRCE-DDS bridges uORB topics to ROS 2 (/fmu/out/... for telemetry, /fmu/in/... for commands such as offboard setpoints), using the px4_msgs package matched to the PX4 version.
Custom modules written in C++ extend PX4 onboard for features that must run in the real-time loop.

Simulation, Logs, and Validation

SITL runs PX4 against Gazebo or other simulators for development and CI; HITL runs firmware on the actual flight controller with simulated sensors. Every flight produces a ULog; upload it to Flight Review or analyze it with pyulog and PlotJuggler to check vibration, estimator innovations, and tracking. Validation progresses from SITL to HITL to tethered or controlled flights to supervised operations. See Robot Simulation and Validation and Gazebo.

Best Practices

Keep Flight-Critical Logic in PX4

Let PX4 handle stabilization and failsafes; keep companion software for higher-level autonomy with defined offboard-loss behavior.

Match px4_msgs to the Firmware

Build ROS 2 nodes against the px4_msgs version that matches the PX4 release to avoid silent message mismatches.

Treat Parameters and Airframes as Code

Export parameters, version them with the firmware release, and review diffs before flights.

Review ULogs Routinely

Inspect logs after every test flight, not only after incidents, and keep them with parameter snapshots.

Common Mistakes

Mismatched Message Definitions

Offboard Without Setpoint Streaming

Default Failsafes Assumed

FAQ

What is PX4?

An open-source autopilot software stack for drones and other unmanned vehicles, providing estimation, control, modes, missions, and failsafes on flight controllers and in simulation.

What is uORB?

PX4's internal publish-subscribe messaging system through which all modules exchange data such as sensor readings, estimates, setpoints, and status.

How does PX4 integrate with ROS 2?

Through uXRCE-DDS: a client in PX4 connects to a Micro XRCE-DDS agent, which exposes selected uORB topics as ROS 2 topics using px4_msgs message definitions.

What is offboard mode?

A mode in which PX4 follows position, velocity, attitude, or other setpoints streamed by external software, typically on a companion computer, while PX4 keeps stabilization and failsafes.

How do I analyze PX4 flight logs?

Download the ULog file and upload it to Flight Review, or analyze it locally with pyulog or PlotJuggler, focusing on vibration, estimator health, and setpoint tracking.