px4_msgs

ROS 2 message and service definitions for the PX4 Autopilot.

Overview

px4_msgs is a ROS 2 interface package: it contains only .msg and .srv definitions and the build rules that turn them into the C++/Python interfaces used by ROS 2 applications. The definitions mirror PX4’s internal uORB topics, so that a ROS 2 node can exchange them with the autopilot over the uXRCE-DDS bridge (the uxrce_dds_client running on PX4 talks to the MicroXRCEAgent running on the companion side, which publishes/subscribes these topics on the ROS 2 graph).

Because the definitions come straight from PX4, this package is the single source of truth that keeps a ROS 2 workspace ABI-compatible with a given PX4 firmware version.

Installation

From source (recommended today)

Clone the branch that matches your PX4 version (see Supported versions) into a colcon workspace and build:

mkdir -p ~/ros2_ws/src && cd ~/ros2_ws/src
git clone https://github.com/PX4/px4_msgs.git
cd ~/ros2_ws
source /opt/ros/jazzy/setup.bash      # or humble / kilted / rolling
colcon build --packages-select px4_msgs

See Using colcon to build packages and the PX4 ROS 2 User Guide for the full workflow.

From a binary (apt)

Once the package has completed its build-farm release it is installable as a Debian package:

sudo apt install ros-${ROS_DISTRO}-px4-msgs

You can also build a .deb locally — see Building Debian packages.

Usage

After sourcing the workspace, the generated interfaces are available like any other ROS 2 message package:

#include <px4_msgs/msg/vehicle_status.hpp>
// ...
sub_ = create_subscription<px4_msgs::msg::VehicleStatus>(
  "/fmu/out/vehicle_status", rclcpp::QoS(10).best_effort(),
  [](px4_msgs::msg::VehicleStatus::SharedPtr msg) { /* ... */ });

from px4_msgs.msg import VehicleStatus

Note: PX4 publishes with best-effort QoS; subscribers must use a compatible QoS profile (as above) or they will not receive any data. Topic names and directions (/fmu/out/..., /fmu/in/...) are documented in the PX4 uXRCE-DDS topic list.

Package layout

px4_msgs/
├── msg/            # message definitions (*.msg), generated from PX4 uORB
├── srv/            # service definitions (*.srv)
├── CMakeLists.txt  # globs msg/ and srv/ and calls rosidl_generate_interfaces
└── package.xml     # ament_cmake, format 3, member of rosidl_interface_packages

Supported versions and compatibility

px4_msgs is a pure interface package, so the definitions build on any maintained ROS 2 distribution. What ties a checkout to a firmware is the PX4 release line, not the ROS 2 distribution: each PX4 release has its own branch and main tracks PX4 main. Pick the branch that matches the PX4 version you fly, then build it on whichever ROS 2 distribution you run.

PX4 release → px4_msgs branch

ROS 2 distribution → Ubuntu

The ROS 2 distribution fixes the Ubuntu version (REP 2000). CI builds main against every maintained distribution:

File truncated at 100 lines see the full file

Contributing

Thanks for your interest in contributing to px4_msgs!

Message and service definitions are auto-generated

Do not commit changes directly to this repository that modify the message or service definitions. All *.msg and *.srv files are generated from the uORB message definitions in the PX4-Autopilot repository.

The definitions here are synchronized automatically: a CI/CD pipeline in PX4-Autopilot pushes the updated ROS message definitions to this repository whenever the upstream definitions change, and a new versioned set is published when a PX4 release is created. As a result, the main branch here is kept in sync with the main branch of PX4-Autopilot.

Any fix or improvement to a message or service definition must therefore be made on the uORB message files in PX4-Autopilot — follow the PX4 contributing guide.

Contributing to the repository infrastructure

Changes to the packaging, build system, CI, or documentation are welcome here. To contribute:

1. Fork the repository and create a topic branch off main.
2. Make your changes and update the CHANGELOG.rst when appropriate.
3. Ensure the package still builds and tests pass:

   colcon build --packages-select px4_msgs
   colcon test --packages-select px4_msgs
   

1. (Optional but recommended) install and run pre-commit:

   pre-commit install
   pre-commit run --all-files
   

1. Open a pull request, filling in the pull request template.

Commit conventions

Please write Conventional Commits and sign off your work under the Developer Certificate of Origin using git commit -s.

Code of Conduct

By participating, you are expected to uphold our Code of Conduct.

Release process

Releases are automated end to end:

1. The upstream PX4 message-sync bot updates main/release/** and bumps the package version. The Create GitHub release workflow detects a new vX.Y.Z and publishes a GitHub release, with notes auto-generated from the message/service diff against the previous release by scripts/generate_release_notes.sh.
2. Publishing a release triggers the Package (.deb) workflow, which builds the Debian packages for every supported ROS 2 distribution and architecture and attaches them to the release.
3. It also triggers the Release to rosdistro (bloom) workflow, which opens the release pull request against ros/rosdistro so the package is built by the official ROS build farm.

The in-repo CHANGELOG.rst can be regenerated from the tag history at any time with scripts/generate_changelog.sh --in-place.

One-time setup required

These steps must be done once by a maintainer before the automation is fully operational:

• Releases use a single release repository, PX4/px4_msgs-release. (The separate PX4/px4_msgs2-release was a ROS 2-only split; it has been archived in favour of the single px4_msgs-release and is not referenced by any current ROS distribution.) Seed a bloom track for each current distribution (humble, jazzy, kilted, rolling) once with an interactive bloom-release using main as the upstream devel branch, e.g.:

  bloom-release --rosdistro jazzy --new-track px4_msgs
  

• That first run also opens the pull request that adds the release: block for px4_msgs to ros/rosdistro (today it has only source:/doc:, so the package is not yet built as binaries on the farm). After the tracks and the release: block exist, the Release to rosdistro (bloom) workflow automates subsequent releases.
• Add a BLOOM_GITHUB_TOKEN repository secret: a token that can push to PX4/px4_msgs-release and open a pull request on ros/rosdistro.
• Add a RELEASE_TOKEN repository secret (a PAT) so that releases created by the automation cascade into the packaging and bloom workflows. Releases created with the default GITHUB_TOKEN do not trigger downstream workflows.