UAV-develop/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-07-24 15:27:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(uxrce): add support for DDS v3, ROS 2 lyrical and humble (#27705)

Browse Source
This commit is contained in:
Beniamino Pozzan
2026-06-24 07:16:00 +01:00
committed by GitHub
parent d31c692347
commit 4c3b41d43e
2 changed files with 139 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
docs/en/middleware/uxrce_dds.md
View File

@@ -22,13 +22,13 @@ The agent acts as a proxy for the client, enabling it to publish and subscribe t
![Architecture uXRCE-DDS with ROS 2](../../assets/middleware/xrce_dds/architecture_xrce-dds_ros2.svg)
In order for PX4 uORB topics to be shared on the DDS network you will need _uXRCE-DDS client_ running on PX4, connected to the _micro XRCE-DDS agent_ running on the companion.
In order for PX4 uORB topics to be shared on the DDS network you will need _uXRCE-DDS client_ running on PX4, connected to the _Micro XRCE-DDS Agent_ running on the companion.
The PX4 [uxrce_dds_client](../modules/modules_system.md#uxrce-dds-client) publishes to/from a defined set of uORB topics to the global DDS data space.
The [eProsima micro XRCE-DDS _agent_](https://github.com/eProsima/Micro-XRCE-DDS-Agent) runs on the companion computer and acts as a proxy for the client in the DDS/ROS 2 network.
The [eProsima Micro XRCE-DDS _Agent_](https://github.com/eProsima/Micro-XRCE-DDS-Agent) runs on the companion computer and acts as a proxy for the client in the DDS/ROS 2 network.
The agent itself has no dependency on client-side code and can be built and/or installed independent of PX4 or ROS.
The agent itself has no dependency on client-side code and can be built and/or installed independent of PX4 or ROS, as long as version compatibility is ensured.
Code that wants to subscribe/publish to PX4 does have a dependency on client-side code; it requires uORB message definitions that match those used to create the PX4 uXRCE-DDS client so that it can interpret the messages.
@@ -41,7 +41,7 @@ Code that wants to subscribe/publish to PX4 does have a dependency on client-sid
The PX4 [uxrce_dds_client](../modules/modules_system.md#uxrce-dds-client) is generated at build time and included in PX4 firmware by default.
The agent has no dependency on client code.
It can be built standalone or in a ROS 2 workspace, or installed as a snap package on Ubuntu.
It can be built standalone or in a ROS 2 workspace.
When PX4 is built, a code generator uses the uORB message definitions in the source tree ([PX4-Autopilot/msg](https://github.com/PX4/PX4-Autopilot/tree/main/msg)) to compile support for the subset of uORB topics in [/src/modules/uxrce_dds_client/dds_topics.yaml](../middleware/dds_topics.md) into [uxrce_dds_client](../modules/modules_system.md#uxrce-dds-client).
@@ -51,6 +51,28 @@ ROS 2 applications need to be built in a workspace that includes the _same_ mess
These can be included into a workspace by cloning the interface package [PX4/px4_msgs](https://github.com/PX4/px4_msgs) into your ROS 2 workspace and switching to the appropriate branch.
Note that all code generation associated with the messages is handled by ROS 2.
## Version selection
There are two main major active Micro XRCE-DDS versions: `v2.x` and `v3.x`.
These need to be paired to the corresponding major DDS version.
In standalone DDS applications you should use the latest DDS version with `Micro XRCE-DDS v3.x`.
However, in ROS 2 applications the DDS version is locked down by the chosen ROS 2 distribution: `v3.x` is required if you want to use the latest ROS 2 distributions.
<Badge type="tip" text="PX4 v1.18" /> In its default configuration `uxrce_dds_client` is built targeting Micro XRCE-DDS `v2.x`.
To target `v3.x` instead, the [`Kconfig`](../hardware/porting_guide_config.md#px4-menuconfig-setup) variable `UXRCE_DDS_CLIENT_USE_DDS_V3` must be set, and a custom build performed.
The following table explains the required Micro-XRCE-DDS-Agent versions and `UXRCE_DDS_CLIENT_USE_DDS_V3` value for different ROS 2 distributions.
| ROS 2 version | fast-dds version | required Micro-XRCE-DDS-Agent version | `UXRCE_DDS_CLIENT_USE_DDS_V3` <Badge type="tip" text="PX4 v1.18" /> |
| ------------- | ---------------- | ------------------------------------- | ------------------------------------------------------------------- |
| Foxy | 2.0.x | 2.4.2 | unset / `N` |
| Humble | 2.6.x | 2.4.2 | unset / `N` |
| Jazzy | 2.14.0 | 2.4.3 | unset / `N` |
| Kilted | 2.14.4 | 2.4.3 | unset / `N` |
| Lyrical | 3.6.x | 3.0.1 | set / `Y` |
| Rolling | 3.6.x | 3.0.1 | set / `Y` |
## Micro XRCE-DDS Agent Installation
The Micro XRCE-DDS Agent can be installed on the companion computer using a binary package, built and installed from source, or built and run from within a ROS 2 workspace.
@@ -61,14 +83,14 @@ The official (and more complete) installation guide is the Eprosima: [micro XRCE
This section summarises the options that have been tested with PX4 during creation of these docs.
:::
::: warning
PX4 Micro XRCE-DDS Client is based on version `v2.x` which is not compatible with the latest `v3.x` Agent version.
:::
### Install Standalone from Source
On Ubuntu you can build from source and install the Agent standalone using the following commands:
::::tabs
::: tab DDS v2
```sh
git clone -b v2.4.3 https://github.com/eProsima/Micro-XRCE-DDS-Agent.git
cd Micro-XRCE-DDS-Agent
@@ -80,47 +102,36 @@ sudo make install
sudo ldconfig /usr/local/lib/
```
:::
::: tab DDS v3
```sh
git clone -b v3.0.1 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/
```
Don't forget to set `UXRCE_DDS_CLIENT_USE_DDS_V3` before building PX4 when using DDS v3!
:::
::::
::: info
There are various build configuration options linked from the corresponding topic in the [official guide](https://micro-xrce-dds.docs.eprosima.com/en/latest/installation.html#installing-the-agent-standalone), but these have not been tested.
:::
To start the agent with settings for connecting to the uXRCE-DDS client running on the simulator:
```sh
MicroXRCEAgent udp4 -p 8888
```
### Install from Snap Package
Install from a snap package on Ubuntu using the following command:
```sh
sudo snap install micro-xrce-dds-agent --edge
```
To start the agent with settings for connecting to the uXRCE-DDS client running on the simulator (note that the command name is different than if you build the agent locally):
```sh
micro-xrce-dds-agent udp4 -p 8888
```
### Build/Run within ROS 2 Workspace
The agent can be built and launched within a ROS 2 workspace (or build standalone and launched from a workspace).
The agent can be built and launched within a ROS 2 workspace (or built standalone and launched from a workspace).
You must already have installed ROS 2 following the instructions in: [ROS 2 User Guide > Install ROS 2](../ros2/user_guide.md#install-ros-2).
::: warning
This approach will use the existing ROS 2 versions of the Agent dependencies, such as `fastcdr` and `fastdds`.
This considerably speeds up the build process but requires that the Agent dependency versions match the ROS 2 ones:
| ROS 2 version | Micro-XRCE-DDS-Agent version |
| ------------- | ---------------------------- |
| Foxy | v2.4.2 |
| Humble | v2.4.2 |
| Jazzy | v2.4.3 |
:::
To build the agent within ROS:
1. Create a workspace directory for the agent:
@@ -129,10 +140,30 @@ To build the agent within ROS:
mkdir -p ~/px4_ros_uxrce_dds_ws/src
```
1. Clone the source code for the eProsima [Micro-XRCE-DDS-Agent](https://github.com/eProsima/Micro-XRCE-DDS-Agent) to the `/src` directory (the `main` branch is cloned by default):
2. Clone the source code for the eProsima [Micro-XRCE-DDS-Agent](https://github.com/eProsima/Micro-XRCE-DDS-Agent) to the `/src` directory (the `main` branch is cloned by default):
::::tabs
::: tab lyrical
```sh
cd ~/px4_ros_uxrce_dds_ws/src
git clone -b v3.0.1 https://github.com/eProsima/Micro-XRCE-DDS-Agent.git
```
Don't forget to set `UXRCE_DDS_CLIENT_USE_DDS_V3` before building PX4 when using DDS v3!
:::
::: tab kilted
```sh
cd ~/px4_ros_uxrce_dds_ws/src
git clone -b v2.4.3 https://github.com/eProsima/Micro-XRCE-DDS-Agent.git
```
:::
::: tab jazzy
```sh
@@ -162,10 +193,28 @@ To build the agent within ROS:
::::
1. Source the ROS 2 development environment, and compile the workspace using `colcon`:
3. Source the ROS 2 development environment, and compile the workspace using `colcon`:
:::: tabs
::: tab lyrical
```sh
source /opt/ros/lyrical/setup.bash
colcon build
```
:::
::: tab kilted
```sh
source /opt/ros/kilted/setup.bash
colcon build
```
:::
::: tab jazzy
```sh
@@ -195,48 +244,58 @@ To build the agent within ROS:
::::
This builds all the folders under `/src` using the sourced toolchain.
This builds all the folders under `~/px4_ros_uxrce_dds_ws/src` using the sourced toolchain.
To run the micro XRCE-DDS agent in the workspace:
To run the Micro XRCE-DDS Agent in the workspace you just need to source the `local_setup.bash` to make the executables available in the terminal (also `setup.bash` if using a new terminal).
1. Source the `local_setup.bash` to make the executables available in the terminal (also `setup.bash` if using a new terminal).
:::: tabs
:::: tabs
::: tab lyrical
::: tab jazzy
```sh
source /opt/ros/lyrical/setup.bash
source install/local_setup.bash
```
```sh
source /opt/ros/jazzy/setup.bash
source install/local_setup.bash
```
:::
:::
::: tab kilted
::: tab humble
```sh
source /opt/ros/kilted/setup.bash
source install/local_setup.bash
```
```sh
source /opt/ros/humble/setup.bash
source install/local_setup.bash
```
:::
:::
::: tab jazzy
::: tab foxy
```sh
source /opt/ros/jazzy/setup.bash
source install/local_setup.bash
```
```sh
source /opt/ros/foxy/setup.bash
source install/local_setup.bash
```
:::
:::
::: tab humble
::::
```sh
source /opt/ros/humble/setup.bash
source install/local_setup.bash
```
1) Start the agent with settings for connecting to the uXRCE-DDS client running on the simulator:
:::
```sh
MicroXRCEAgent udp4 -p 8888
```
::: tab foxy
```sh
source /opt/ros/foxy/setup.bash
source install/local_setup.bash
```
:::
::::
## Starting Agent and Client
@@ -317,7 +376,7 @@ The configuration can be done using the [UXRCE-DDS parameters](../advanced_confi
This provides a logical separation between DDS networks, and can be used to separate clients on different networks.
By default, ROS 2 operates on ID 0.
- [UXRCE_DDS_PTCFG](../advanced_config/parameter_reference.md#UXRCE_DDS_PTCFG): uXRCE-DDS participant configuration.
It allows to restrict the visibility of the DDS topics to the _localhost_ only and to use user-customized participant configuration files stored on the agent side.
It allows you to restrict the visibility of the DDS topics to the _localhost_ only and to use user-customized participant configuration files stored on the agent side.
- [UXRCE_DDS_SYNCT](../advanced_config/parameter_reference.md#UXRCE_DDS_SYNCT): Bridge time synchronization enable.
The uXRCE-DDS client module can synchronize the timestamp of the messages exchanged over the bridge.
This is the default configuration. In certain situations, for example during [simulations](../ros2/user_guide.md#ros-gazebo-and-px4-time-synchronization), this feature may be disabled.
@@ -328,7 +387,7 @@ The configuration can be done using the [UXRCE-DDS parameters](../advanced_confi
To use hardware flow control, a custom MicroXRCE Agent needs to be adopted. Please refer to [this PR](https://github.com/eProsima/Micro-XRCE-DDS-Agent/pull/407) for the required changes, cherry-pick them on top of the [agent version](#build-run-within-ros-2-workspace) you need to use and then run the agent with the additional `--flow-control` option.
::: info
Many ports are already have a default configuration.
Many ports already have a default configuration.
To use these ports you must first disable the existing configuration:
- `TELEM1` and `TELEM2` are set up by default to connect via MAVLink to a GCS and a companion computer (respectively).
@@ -364,7 +423,7 @@ These allow users to create custom startup files for their simulations:
- `ROS_DOMAIN_ID`: Use this to replace [UXRCE_DDS_DOM_ID](../advanced_config/parameter_reference.md#UXRCE_DDS_DOM_ID).
- `PX4_UXRCE_DDS_PORT`: Use this to replace [UXRCE_DDS_PRT](../advanced_config/parameter_reference.md#UXRCE_DDS_PRT).
For example, the following command can be used to start a Gazebo simulation with che client operating on the DDS domain `3`, port `9999` and topic namespace `drone`.
For example, the following command can be used to start a Gazebo simulation with the client operating on the DDS domain `3`, port `9999` and topic namespace `drone`.
```sh
ROS_DOMAIN_ID=3 PX4_UXRCE_DDS_PORT=9999 PX4_UXRCE_DDS_NS=drone make px4_sitl gz_x500
@@ -532,7 +591,7 @@ subscriptions_multi:
```
Each (`topic`,`type`) pairs defines:
Each (`topic`, `type`) pair defines:
1. A new `publication`, `subscription`, or `subscriptions_multi`, depending on the list to which it is added.
2. The topic _base name_, which **must** coincide with the desired uORB topic name that you want to publish/subscribe.
@@ -631,7 +690,7 @@ Take a look at the [client startup section](#starting-the-client) to learn how t
#### New file for setting which topics are published
The list of topics that are published and subscribed for a particular firmware is now managed by the [dds_topics.yaml](../middleware/dds_topics.md) configuration file, which replaces [urtps_bridge_topics.yaml](https://github.com/PX4/PX4-Autopilot/blob/release/1.13/msg/tools/urtps_bridge_topics.yaml)
The list of topics that are published and subscribed for a particular firmware is now managed by the [dds_topics.yaml](../middleware/dds_topics.md) configuration file, which replaces [urtps_bridge_topics.yaml](https://github.com/PX4/PX4-Autopilot/blob/release/1.13/msg/tools/urtps_bridge_topics.yaml).
See [Supported uORB Messages](#supported-uorb-messages) and [DDS Topics YAML](#dds-topics-yaml) sections for more information.
@@ -660,7 +719,7 @@ There are many ways to install it on your PC / companion computer - for more inf
#### Application-Specific Changes
If you where not using ROS 2 alongside the agent ([Fast DDS Interface ROS-Independent](https://docs.px4.io/v1.13/en/middleware/micrortps#agent-in-an-offboard-fast-dds-interface-ros-independent)), then you need to migrate to [eProsima Fast DDS](https://fast-dds.docs.eprosima.com/en/latest/index.html).
If you were not using ROS 2 alongside the agent ([Fast DDS Interface ROS-Independent](https://docs.px4.io/v1.13/en/middleware/micrortps#agent-in-an-offboard-fast-dds-interface-ros-independent)), then you need to migrate to [eProsima Fast DDS](https://fast-dds.docs.eprosima.com/en/latest/index.html).
ROS 2 applications still need to compile alongside the PX4 messages, which you do by adding the [px4_msgs](https://github.com/PX4/px4_msgs) package to your workspace.
You can remove the [px4_ros_com](https://github.com/PX4/px4_ros_com) package as it is no longer needed, other than for example code.

8
docs/en/releases/1.18.md
View File

@@ -51,11 +51,11 @@ Please continue reading for [upgrade instructions](#upgrade-guide).
| Name | Notes |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COM_FLT_PROFILE` | Unused ([PX4-Autopilot#26735](https://github.com/PX4/PX4-Autopilot/pull/26735)) |
| `COM_KILL_DISARM` | Autopilot now always disarms if still killed after 5 sections (previous default). ([PX4-Autopilot#26736](https://github.com/PX4/PX4-Autopilot/pull/26736)) |
| `COM_KILL_DISARM` | Autopilot now always disarms if still killed after 5 seconds (previous default). ([PX4-Autopilot#26736](https://github.com/PX4/PX4-Autopilot/pull/26736)) |
| `COM_MOT_TEST_EN` | Motor tests now always possible (was the default). ([PX4-Autopilot#26775](https://github.com/PX4/PX4-Autopilot/pull/26775)) |
| `COM_TAKEOFF_ACT` | Vehicle always switches to Hold mode when the takeoff is done. If you want to automatically do a mission, take off in Mission mode. ([PX4-Autopilot#26808](https://github.com/PX4/PX4-Autopilot/pull/26808)) |
| `COM_HLDL_REG_T` | When a high latency link is regained it's always considered regained immediately (was the default). ([PX4-Autopilot#26809](https://github.com/PX4/PX4-Autopilot/pull/26809)) |
| `COM_ARM_SDCARD` | There's now always warning when the autopilot SD card is missing (was the default). Boards that don't have an SD card need to skip the check with a compile time define. ([PX4-Autopilot#27259](https://github.com/PX4/PX4-Autopilot/pull/27259)) |
| `COM_ARM_SDCARD` | There's now always a warning when the autopilot SD card is missing (was the default). Boards that don't have an SD card need to skip the check with a compile time define. ([PX4-Autopilot#27259](https://github.com/PX4/PX4-Autopilot/pull/27259)) |
| `COM_IMB_PROP_ACT` | There's now always a warning when imbalanced propellers (high vibration) is detected (was the default). ([PX4-Autopilot#27260](https://github.com/PX4/PX4-Autopilot/pull/27260)) |
| `COM_OBC_LOSS_T` | Timeout for missing heartbeats from the onboard computer is always 5 seconds (was the default). ([PX4-Autopilot#27261](https://github.com/PX4/PX4-Autopilot/pull/27261)) |
| `COM_LKDOWN_TKO` | Takeoff failure detection always runs for 3 seconds (was the default). ([PX4-Autopilot#27262](https://github.com/PX4/PX4-Autopilot/pull/27262)) |
@@ -108,9 +108,9 @@ Please continue reading for [upgrade instructions](#upgrade-guide).
- TBD
### uXRCE-DDS / Zenoh / ROS2
### uXRCE-DDS / Zenoh / ROS 2
- TBD
- uXRCE-DDS, add support for DDS `v3`, ROS 2 Lyrical and Rolling ([PX4-Autopilot#27597](https://github.com/PX4/PX4-Autopilot/pull/27597))
<!-- MOVED THIS TO v1.17