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.

uXRCE-DDS is the middleware that connects PX4’s internal uORB message bus to the DDS global data space used by ROS 2. It splits the work between a lightweight client that runs inside PX4 firmware and a agent that runs on your companion computer. When both are running and connected, uORB topics become live ROS 2 topics that any node in your network can publish or subscribe to.
The PX4 uXRCE-DDS client is based on agent version v2.x. It is not compatible with the latest v3.x agent. Install agent version v2.4.3 or a compatible v2.x release.

​
Architecture

The client and agent communicate over a serial or UDP link and exchange messages in both directions:
  • Client — compiled into PX4 firmware at build time via code generation. It translates uORB messages to CDR-serialized DDS messages and vice versa. The set of topics it handles is defined in dds_topics.yaml.
  • Agent — runs on the companion computer. It acts as a proxy, forwarding messages between the client and the broader DDS network where your ROS 2 nodes live. The agent has no dependency on PX4 source code and can be installed independently.
PX4 Firmware                    Companion Computer
┌────────────────────┐           ┌──────────────────────────┐
│  uORB message bus  │           │  DDS global data space   │
│         │          │  serial   │         │                │
│  uxrce_dds_client  │◄─────────►│  MicroXRCEAgent          │
│  (built-in)        │  or UDP   │                │         │
└────────────────────┘           │        ROS 2 nodes       │
                                 └──────────────────────────┘

​
Installing the agent

Install the Micro XRCE-DDS Agent on your companion computer. Build from source at the v2.4.3 tag:
1

Clone and build the agent

git clone -b v2.4.3 https://github.com/eProsima/Micro-XRCE-DDS-Agent.git
cd Micro-XRCE-DDS-Agent
mkdir build && cd build
cmake ..
make
sudo make install
sudo ldconfig /usr/local/lib/
2

Verify the installation

MicroXRCEAgent --help
You should see the agent’s usage output listing available transport options.

​
Starting the agent and client

Run the agent on the companion computer first, then start the client on the PX4 side.
On the companion computer (or host machine for SITL):
MicroXRCEAgent udp4 --port 8888
On the PX4 shell (MAVLink console or nsh):
uxrce_dds_client start -t udp -h 127.0.0.1 -p 8888
For SITL, the client starts automatically with the simulator. You only need to launch the agent manually.
The uXRCE-DDS client is built into PX4 firmware by default but does not start automatically on hardware. You must start it explicitly via the PX4 shell or by adding the start command to your rc.local startup script.

​
Topic naming convention

All bridged topics follow a predictable naming scheme:
DirectionPatternExample
PX4 → ROS 2/fmu/out/<MessageName>/fmu/out/VehicleOdometry
ROS 2 → PX4/fmu/in/<MessageName>/fmu/in/OffboardControlMode
List all available topics after the bridge is running: 
ros2 topic list | grep fmu

​
Configuring bridged topics (dds_topics.yaml)

The set of uORB topics exposed over DDS is controlled by the file src/modules/uxrce_dds_client/dds_topics.yaml in the PX4 source tree. Each entry specifies the topic name, message type, and direction. 
publications:
  - topic: /fmu/out/VehicleOdometry
    type: px4_msgs::msg::VehicleOdometry

  - topic: /fmu/out/VehicleStatus
    type: px4_msgs::msg::VehicleStatus

subscriptions:
  - topic: /fmu/in/OffboardControlMode
    type: px4_msgs::msg::OffboardControlMode

  - topic: /fmu/in/TrajectorySetpoint
    type: px4_msgs::msg::TrajectorySetpoint

  - topic: /fmu/in/VehicleCommand
    type: px4_msgs::msg::VehicleCommand
To expose additional topics, add them to this file and rebuild the firmware.

​
Verifying the connection

Once the agent is running and the client has connected, you should see output in the agent terminal indicating an established session. Confirm from ROS 2: 
# Check that PX4 topics are visible
ros2 topic list | grep /fmu/out/

# Echo vehicle status at 1 Hz
ros2 topic echo /fmu/out/VehicleStatus --once
If no /fmu/ topics appear, check that the client started successfully on the PX4 side (uxrce_dds_client status) and that the agent and client are configured to use the same transport, IP address, and port.

Build docs developers (and LLMs) love

Get started for freeTalk to us