uXRCE-DDS（PX4 - ROS 2/DDS 桥接器）

PX4 v1.14

INFO

uXRCE - DDS 取代了 PX4 v1.13 中使用的 Fast - RTPS 桥接器。 如果您之前使用的是 Fast - RTPS 桥接器，请遵循迁移指南。

PX4 使用 uXRCE - DDS 中间件，使得 uORB 消息 能够在伴随计算机上像 ROS 2 主题一样被发布和订阅。 这为 PX4 和 ROS 2 之间提供了快速可靠的集成，并且让 ROS 2 应用程序更轻松地获取飞行器信息并发送命令。

PX4 使用了基于 eProsima Micro XRCE - DDS 的 XRCE - DDS 实现。

以下指南介绍了设置客户端和代理端的架构和各种选项。 代理端（Agent）充当客户端的代理，使其能够在 DDS 全局数据空间中发布和订阅话题。

软件架构

uXRCE - DDS 中间件由运行在 PX4 上的客户端和运行在伴随计算机上的代理端组成，它们通过串行或 UDP 链路进行双向数据交换。 代理端充当客户端的代理，使其能够在全局 DDS 数据空间中发布和订阅话题。

为了让 PX4 uORB 主题能够在 DDS 网络上共享，您需要在 PX4 上运行 uXRCE - DDS 客户端，并将其连接到伴随计算机上运行的 micro XRCE - DDS 代理端。

PX4 uxrce_dds_client 将一组预定义的 uORB 主题发布到全局 DDS 数据空间，也可以从该空间订阅数据。

eProsima micro XRCE - DDS 代理端 运行在伴随计算机上，在 DDS/ROS 2 网络中充当客户端的代理。

代理端本身不依赖于客户端代码，可以独立于 PX4 或 ROS 进行构建和/或安装。

想要向 PX4 订阅/发布数据的代码依赖于客户端代码；它需要与创建 PX4 uXRCE - DDS 客户端时使用的 uORB 消息定义相匹配，以便能够解析消息。

代码生成

PX4 uxrce_dds_client 在构建时生成，并且默认包含在 PX4 固件中。 代理端不依赖于客户端代码。 它可以独立构建，也可以在 ROS 2 工作空间中构建，或者作为 snap 包安装在 Ubuntu 上。

当构建 PX4 时，代码生成器使用源代码树中的 uORB 消息定义（PX4 - Autopilot/msg），将 PX4 - Autopilot/src/modules/uxrce_dds_client/dds_topics.yaml 中部分 uORB 主题的支持编译到 uxrce_dds_client 中。

PX4 的主分支或发布版本构建会自动将构建过程中的 uORB 消息定义集导出到 PX4/px4_msgs 的相关分支中。

ROS 2 应用程序需要在包含与创建 PX4 固件中的 uXRCE - DDS 客户端模块时所使用的 相同 消息定义的工作空间中构建。 可以通过将接口包 PX4/px4_msgs 克隆到您的 ROS 2 工作空间并切换到相应分支来包含这些消息定义。 请注意，与消息相关的所有代码生成工作都由 ROS 2 处理。

Micro XRCE - DDS 代理端安装

Micro XRCE - DDS 代理端可以使用二进制包在伴随计算机上安装，也可以从源代码构建并安装，或者在 ROS 2 工作空间中构建并运行。 所有这些方法都会获取与客户端通信所需的 所有 依赖项（例如 FastCDR）。

INFO

官方（更完整）的安装指南是 Eprosima 的：micro XRCE - DDS 安装指南。 本节总结了在编写本文档期间针对 PX4 测试过的选项。

源码安装

在 Ubuntu 上，您可以使用以下命令从源代码构建并独立安装代理端：

git clone 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/

INFO

官方指南 中相应主题链接了各种构建配置选项，但这些选项尚未经过测试。

从 Snap 软件包安装

使用以下命令从 Ubuntu 的 snap 软件包安装：

sudo snap install microxrce-ds-agent --edge

要启动代理端并设置连接到模拟器上运行的 uXRCE - DDS 客户端（请注意，如果您在本地构建代理端，命令名称会有所不同）：

micro-xrce-dds-agent udp4 -p 8888

INFO

在撰写本文时，从 snap 安装的稳定版本可以连接到 PX4，但在创建主题时会报告错误。 上面使用 --edge 获取的开发版本可以正常工作。

在 ROS 2 工作空间中构建/运行

可以在 ROS 2 工作空间中构建并启动代理端（也可以独立构建并从工作空间中启动）。 您必须已经按照以下说明安装了 ROS 2：ROS 2 用户指南 > 安装 ROS 2。

要在 ROS 中构建代理端：

1. 为代理端创建一个工作空间目录：

   mkdir -p ~/px4_ros_uxrce_dds_ws/src

2. 将 eProsima Micro - XRCE - DDS - Agent 的源代码克隆到 /src 目录（默认克隆 main 分支）：

   cd ~/px4_ros_uxrce_dds_ws/src
   git clone https://github.com/eProsima/Micro-XRCE-DDS-Agent.git

3. 加载 ROS 2 开发环境，并使用 colcon 编译工作空间：

   source /opt/ros/humble/setup.bash
   colcon build

   source /opt/ros/foxy/setup.bash
   colcon build

   这将使用加载的工具链构建 /src 下的所有文件夹。

要在工作空间中运行 micro XRCE - DDS 代理端：

1. 加载 local_setup.bash 以使可执行文件在终端中可用（如果使用新终端，还需加载 setup.bash）。

   source /opt/ros/humble/setup.bash
   source install/local_setup.bash

   source /opt/ros/foxy/setup.bash
   source install/local_setup.bash

2. 启动代理并设置以连接运行在模拟器上的 uXRCE - DDS 客户端（Client）：

   MicroXRCEAgent udp4 -p 8888

启动代理端和客户端

启动代理端

代理端用于通过特定通道（如 UDP 或串行连接）连接到客户端。 通道设置在启动代理端时使用命令行选项指定。 这些选项在 eProsima 用户指南中有文档说明：Micro XRCE - DDS 代理端 > 代理端命令行界面。 请注意，代理端支持多种通道选项，但 PX4 仅支持 UDP 和串行连接。

INFO

对于每个需要连接的通道，您应该创建一个代理端实例。

例如，PX4 模拟器在 UDP 端口 8888 上运行 uXRCE - DDS 客户端，因此要连接到模拟器，您可以使用以下命令启动代理端：

MicroXRCEAgent udp4 -p 8888

在使用真实硬件时，设置取决于硬件、操作系统和通道。 例如，如果您使用的是树莓派的 UART0 串行端口，您可以使用以下命令进行连接（基于 树莓派文档 > 配置 UART 中的信息）：

sudo MicroXRCEAgent serial --dev /dev/AMA0 -b 921600

INFO

有关设置通信通道的更多信息，请参阅 Pixhawk + 伴随计算机设置 > 串行端口设置 及其子文档。

启动客户端

uXRCE - DDS 客户端模块（uxrce_dds_client）默认包含在所有固件和模拟器中。 必须使用与代理端通信所需的适当通道设置来启动它。

INFO

模拟器会使用默认的 uxrce - dds 命名空间，自动在本地 UDP 端口 8888 上启动客户端。

可以使用 UXRCE - DDS 参数 进行配置：

• UXRCE_DDS_CFG：设置要连接的端口，例如 TELEM2、Ethernet 或 Wifi。

• 如果使用以太网连接：

  • UXRCE_DDS_PRT： 使用此参数指定代理端的 UDP 监听端口。 默认值为 8888。

  • UXRCE_DDS_AG_IP： 使用此参数指定代理端的 IP 地址。 由于 PX4 不支持字符串参数，IP 地址必须以 int32 格式提供。 默认值为 2130706433，对应于 本地主机 127.0.0.1。

    您可以使用 Tools/convert_ip.py 在不同格式之间进行转换：

    • 要将十进制点分表示法的 IP 地址转换为 int32 版本，命令如下：

      python3 ./PX4-Autopilot/Tools/convert_ip.py <十进制点分表示法的 IP 地址>

    • 要从 int32 版本获取十进制点分表示法的 IP 地址：

      python3 ./PX4-Autopilot/Tools/convert_ip.py -r <int32 表示法的 IP 地址>

• 如果使用串行连接：

  • SER_TEL2_BAUD、SER_URT6_BAUD（等等）： 使用与串行端口关联的 _BAUD 参数设置波特率。 例如，如果您使用 TELEM2 连接到伴随计算机，则需要为 SER_TEL2_BAUD 设置一个值。 更多信息请参阅 串行端口配置。

• 某些设置可能还需要设置这些参数：

  • UXRCE_DDS_KEY：uXRCE - DDS 密钥。 如果您在多客户端、单代理端配置中工作，每个客户端应该有一个唯一的非零密钥。 这在多飞行器模拟中尤为重要，因为所有客户端都通过 UDP 连接到同一个代理端。 （请参阅 官方 eprosima 文档，uxr_init_session。）
  • UXRCE_DDS_DOM_ID：DDS 域 ID。 这为 DDS 网络之间提供了逻辑隔离，可用于分隔不同网络上的客户端。 默认情况下，ROS 2 在 ID 0 上运行。
  • UXRCE_DDS_PTCFG：uXRCE - DDS 参与者配置。 它允许将 DDS 主题的可见性限制为仅 本地主机，并使用存储在代理端的自定义参与者配置文件。
  • UXRCE_DDS_SYNCT：桥接时间同步启用。 uXRCE - DDS 客户端模块可以同步通过桥接交换的消息的时间戳。 这是默认配置。在某些情况下，例如在 模拟 期间，可能需要禁用此功能。

INFO

许多端口已经有默认配置。 要使用这些端口，您必须首先禁用现有的配置：

• TELEM1 和 TELEM2 默认设置为分别通过 MAVLink 连接到地面站和伴随计算机。 通过将 MAV_0_CONFIG = 0 或 MAV_1_CONFIG = 0 设置为零来禁用。 更多信息请参阅 MAVLink 外设。
• 其他端口也可以类似地进行配置。 请参阅 串行端口配置。

设置完成后，您可能需要重启 PX4 以使参数生效。 这些参数在后续重启后将继续保留。

您还可以使用命令行启动 uxrce_dds_client。 可以在 系统启动 期间调用此命令，也可以通过 MAVLink 外壳（或系统控制台）调用。 当您需要设置自定义客户端命名空间时，此方法非常有用，因为没有为此目的提供参数。 例如，以下命令可用于通过以太网连接到 192.168.0.100:8888 上的远程主机，并将客户端命名空间设置为 /drone/。

uxrce_dds_client start -t udp -p 8888 -h 192.168.0.100 -n drone

选项 -p 或 -h 用于绕过 UXRCE_DDS_PRT 和 UXRCE_DDS_AG_IP。

在模拟中启动客户端

模拟器的 启动逻辑（init.d - posix/rcS）使用客户端启动命令进行单飞行器和 多飞行器模拟，从而可以设置适当的实例 ID 和 DDS 命名空间。 默认情况下，客户端在本地 UDP 端口 8888 上启动，没有额外的命名空间。

提供了一些环境变量，用于覆盖一些 [UXRCE - DDS 参数](../advanced_config/parameter_reference.md#uxrce