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

PX4 v1.14

信息

uXRCE-DDS 取代了 快速 RTPS 网桥 在 PX4 v1.13 中使用。如果您使用的是 Fast-RTPS 网桥，请按照 迁移指南.

PX4 使用 uXRCE-DDS 中间件，允许 uORB 信息 在配套计算机上发布和订阅，就好像它们是 ROS 2 主题。这为 PX4 和 ROS 2 提供了快速可靠的集成，使 ROS 2 应用程序更容易获取载具信息和发送命令。

PX4 使用 XRCE-DDS 实现，利用了 eProsima Micro XRCE-DDS.

以下指南介绍了架构以及设置客户端和代理的各种选项。其中特别涵盖了对 PX4 用户最重要的选项。

建筑学

uXRCE-DDS 中间件包括在 PX4 上运行的客户端和在配套计算机上运行的代理，两者之间通过串行或 UDP 链接进行双向数据交换。代理作为客户端的代理，使其能够发布和订阅全球 DDS 数据空间中的主题。

要在 DDS 网络上共享 PX4 uORB 主题，您需要 uXRCE-DDS 客户端 在 PX4 上运行，连接到 微型 XRCE-DDS 代理 在同伴身上运行。

PX4 uxrce_dds_client 向/从一组定义的 uORB 主题发布到全局 DDS 数据空间。

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

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

要订阅/发布 PX4 的代码确实依赖于客户端代码；它需要与创建 PX4 uXRCE-DDS 客户端所用的 uORB 消息定义相匹配的 uORB 消息定义，这样它才能解释消息。

代码生成

PX4 uxrce_dds_client 会在构建时生成，并默认包含在 PX4 firmare 中。该代理不依赖客户端代码。它可以独立构建或在 ROS 2 工作区中构建，也可以作为 Ubuntu 上的 snap 包安装。

构建 PX4 时，代码生成器会使用源代码树中的 uORB 消息定义 (PX4-Autopilot/msg中的 uORB 主题子集编译支持。 PX4-Autopilot/src/modules/uxrce_dds_client/dds_topics.yaml 成 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 Agent 可以使用二进制软件包安装在配套计算机上，也可以从源代码中构建和安装，或者在 ROS 2 工作区中构建和运行。所有这些方法都能获取 一应俱全 与客户端通信所需的依赖项（如 FastCDR）

信息

官方（更完整）的安装指南是 Eprosima： micro XRCE-DDS 安装指南.本节总结了在创建这些文档时使用 PX4 测试过的选项。

从源代码安装独立版本

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

Git 复制 https://github.com/eProsima/Micro-XRCE-DDS-Agent.git
CD Micro-XRCE-DDS-Agent
mkdir 构建
CD 构建
cmake ..
生产
苏都 生产 安装
苏都 ldconfig /usr/local/lib/

信息

有多种构建配置选项，可从相应主题中的 官方指南但尚未进行测试。

启动代理，设置连接到模拟器上运行的 uXRCE-DDS 客户端：

MicroXRCEAgent udp4 -p 8888

从 Snap 软件包安装

在 Ubuntu 上使用以下命令从快照软件包安装：

苏都 断 安装 micro-xrce-dds-agent --边缘

使用连接到模拟器上运行的 uXRCE-DDS 客户端的设置启动代理（注意，命令名称与在本地构建代理时不同）：

micro-xrce-dds-agent udp4 -p 8888

信息

在编写本报告时，从 snap 安装的稳定版本可以连接到 PX4，但在创建主题时会报错。使用 --边缘 上述方法确实有效。

在 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 目录（该 主要 默认情况下会克隆分支）：

   CD ~/px4_ros_uxrce_dds_ws/src
   Git 复制 https://github.com/eProsima/Micro-XRCE-DDS-Agent.git

3. 源代码 ROS 2 开发环境，并使用 胶管:

   消息来源 /opt/ros/humble/setup.bash
   胶管 构建

   消息来源 /opt/ros/foxy/setup.bash
   胶管 构建

   这将生成 /src 使用源工具链。

在工作区中运行 micro XRCE-DDS 代理：

1. 资料来源 local_setup.bash 使可执行文件在终端中可用（也可以 setup.bash 如果使用新终端）。

   消息来源 /opt/ros/humble/setup.bash
   消息来源 install/local_setup.bash

   消息来源 /opt/ros/foxy/setup.bash
   消息来源 install/local_setup.bash

1. 启动代理，设置连接到模拟器上运行的 uXRCE-DDS 客户端：

   MicroXRCEAgent udp4 -p 8888

启动代理和客户

启动代理

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

信息

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

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

MicroXRCEAgent udp4 -p 8888

在使用真实硬件时，设置取决于硬件、操作系统和通道。例如，如果您使用的是 RasPi UART0 串行端口，您可以使用该命令进行连接（基于 Raspberry Pi 文档 > 配置 UARTS):

苏都 MicroXRCEAgent 串行 --开发 /dev/AMA0 -b 921600

信息

有关设置通信频道的更多信息，请参阅 Pixhawk + 同伴设置 > 串行端口设置和子文件。

启动客户端

uXRCE-DDS 客户端模块 (uxrce_dds_client) 默认包含在所有固件和模拟器中。必须根据要与代理进行通信的通信通道的适当设置启动该程序。

信息

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

可以使用 UXRCE-DDS 参数:

• UXRCE_DDS_CFG:设置要连接的端口，例如 TELEM2, 以太网或 无线网络.

• 如果使用以太网连接：

  • UXRCE_DDS_PRT:用于指定代理的 UDP 监听端口。默认值为 8888.

  • uxrce_dds_ag_ip:用于指定代理的 IP 地址。IP 地址必须在 int32 格式，因为 PX4 不支持字符串参数。默认值为 2130706433 对应于 本地主机 127.0.0.0.1.

    您可以使用 Tools/convert_ip.py 之间进行转换：

    • 要获得 int32 以十进制点符号表示的 IP 版本，该命令为：

      python3 ./PX4-Autopilot/Tools/convert_ip.py <；的 IP 地址 于 小數 点子 注释n>；

    • 以十进制点符号从 int32 版本：

      python3 ./PX4-Autopilot/Tools/convert_ip.py -r <；的 IP 地址 于 int32 注释n>；

• 如果使用串行连接：

  • SER_TEL2_BAUD, SER_URT6_BAUD (等等）：使用 _BAUD 参数来设置波特率。例如，您可以为 SER_TEL2_BAUD 如果您使用 TELEM2.更多信息，请参见 串行端口配置.

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

  • UXRCE_DDS_KEY:uXRCE-DDS 密钥。如果您使用的是多客户端、单代理配置，则每个客户端都应有一个唯一的非零密钥。这对多载具模拟非常重要，因为在多载具模拟中，所有客户端都通过 UDP 连接到同一个代理。(请参见 EPROSIMA 官方文件 , uxr_init_session.)
  • uxrce_dds_dom_id:DDS 域 ID。它提供了 DDS 网络之间的逻辑分隔，可用于分隔不同网络上的客户端。默认情况下，ROS 2 在 ID 0 上运行。
  • uxrce_dds_ptcfguXRCE-DDS：uXRCE-DDS 参与者配置。它允许将 DDS 主题的可见性限制在 本地主机 并使用存储在代理侧的用户自定义参与者配置文件。
  • uxrce_dds_synct:启用网桥时间同步。uXRCE-DDS 客户端模块可以同步通过网桥交换的报文的时间戳。这是默认配置。在某些情况下，例如在 仿真，此功能可能会被禁用。

信息

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

• TELEM1 和 TELEM2 默认设置为通过 MAVLink 分别连接到 GCS 和配套计算机。通过设置 MAV_0_CONFIG=0 或 MAV_1_CONFIG=0 为零。参见 MAVLink 外围设备 了解更多信息。
• 其他端口也可进行类似配置。参见 串行端口配置.

设置完成后，可能需要重启 PX4 才能使参数生效。这些参数将在以后的重启中持续生效。

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

uxrce_dds_client 启动 -t udp -p 8888 -h 192.168.0.100 -n 嗡嗡声

选项 -p 或 -h 用于绕过 UXRCE_DDS_PRT 和 uxrce_dds_ag_ip.

在模拟环境中启动客户端

模拟器 启动逻辑 (init.d-posix/rcS)使用客户端启动命令进行单个和 多车模拟这样就可以设置适当的实例 ID 和 DDS 命名空间。默认情况下，客户端通过本地主机 UDP 端口启动。 8888 没有额外的命名空间。

提供的环境变量可覆盖某些 UXRCE-DDS 参数.这些允许用户为其模拟创建自定义启动文件：

• px4_uxrce_dds_ns:用它来指定主题 命名空间.
• ROS_DOMAIN_ID:用它来代替 uxrce_dds_dom_id.
• px4_uxrce_dds_port:用它来代替 UXRCE_DDS_PRT.

例如，可以使用以下命令启动 Gazebo 仿真，并在 DDS 域上运行 che 客户端 3端口 9999 和主题名称空间 嗡嗡声.

ROS_DOMAIN_ID=3 px4_uxrce_dds_port=9999 px4_uxrce_dds_ns=嗡嗡声 生产 px4_sitl gz_x500

支持的 uORB 信息

的集合 PX4 uORB 主题 在 dds_topics.yaml.

这些主题是针对特定版本的（支持内容编入了 uxrce_dds_client 在构建时）。虽然大多数版本应该支持非常相似的信息集，但要确定这一点，您需要检查特定版本的 yaml 文件。

请注意，ROS 2/DDS 需要有 一样 信息定义用于在 PX4 固件中创建 uXRCE-DDS 客户端模块，以便解释信息。信息定义存储在 ROS 2 接口包中 PX4/px4_msgs的 CI 自动同步。 主要 和发布分支。请注意，PX4 源代码中的所有信息都存在于版本库中，但只有在 dds_topics.yaml 将作为 ROS 2 的主题提供。因此

• 如果您使用的是 PX4 主版本或发布版本，您可以通过克隆接口包来获取信息定义 PX4/px4_msgs 进入你的工作空间。

• 如果您正在创建或修改 uORB 信息，则必须从 PX4 源代码树中手动更新工作区中的信息。一般来说，这意味着你要更新 dds_topics.yaml，克隆接口包，然后通过将新的/修改过的报文定义从 PX4-Autopilot/msg 到其 信息 文件夹假设 PX4-Autopilot 位于您的主目录中 ~而 px4_msgs 在 ~/px4_ros_com/src/那么命令可能是

  rm ~/px4_ros_com/src/px4_msgs/msg/*.msg
  cp ~/PX4-Autopilot/mgs/*.msg ~/px4_ros_com/src/px4_msgs/msg/

  信息

  从技术上讲 dds_topics.yaml 完全定义了 PX4 uORB 主题和 ROS 2 信息之间的关系。更多信息请参见 DDS 主题 YAML 下图

自定义主题名称空间

自定义主题名称空间可在构建时应用（更改 dds_topics.yaml)或运行时（这对多车运行非常有用）：

• 一种可能性是使用 -n 选项时启动 uxrce_dds_client 命令行。这种技术既可用于模拟，也可用于实际载具。
• 通过设置环境变量 px4_uxrce_dds_ns 然后再开始模拟。

信息

在运行时更改命名空间会将所需的命名空间作为前缀附加到所有 主题 中的字段 dds_topics.yaml.因此，类似这样的命令

uxrce_dds_client 启动 -n uav_1

或

px4_uxrce_dds_ns=uav_1 生产 px4_sitl gz_x500

将在命名空间下生成主题：

/uav_1/fmu/in/  # 为订阅者
/uav_1/fmu/out/ # 为出版商

PX4 ROS 2 QoS 设置

发布者的 PX4 QoS 设置与 ROS 2 订阅者的默认 QoS 设置不兼容。因此，如果 ROS 2 代码需要订阅 uORB 主题，就需要使用兼容的 QoS 设置。其中一个例子如下 ROS 2 用户指南 > ROS 2 用户服务质量设置.

PX4 对发布商使用以下 QoS 设置：

uxrQoS_t 优先权 = {
  .耐久性 = uxr_durability_transient_local、
  .可靠性 = uxr_reliability_best_effort、
  .历史 = uxr_history_keep_last、
  .深度 = 0,
};

PX4 对用户使用以下 QoS 设置：

uxrQoS_t 优先权 = {
  .耐久性 = uxr_durability_volatile、
  .可靠性 = uxr_reliability_best_effort、
  .历史 = uxr_history_keep_last、
  .深度 = 队列深度、
};

ROS 2 对发布者和订阅使用以下 QoS 设置（默认）："keep last"（保留最后一次"）表示历史记录，队列大小为 10；"reliable"（可靠"）表示可靠性；"volatile"（易失"）表示耐用性；"system default"（系统默认"）表示实时性。最后期限、生命周期和租期也都设置为 "默认值"。

DDS 主题 YAML

PX4 yaml 文件 dds_topics.yaml 定义了内置于固件并已发布的 PX4 uORB 主题集。更确切地说，它完全定义了 PX4 uORB 和 ROS 2 消息之间的关系/配对。

文件结构如下

出版物:

  - 主题: /fmu/out/collision_constraints
    类型: px4_msgs::msg::CollisionConstraints 碰撞约束

  ...

  - 主题: /fmu/out/vehicle_odometry
    类型: px4_msgs::msg::VehicleOdometry (载具几何尺寸)

  - 主题: /fmu/out/vehicle_status
    类型: px4_msgs::msg::VehicleStatus

  - 主题: /fmu/out/vehicle_trajectory_waypoint_desired
    类型: px4_msgs::msg::VehicleTrajectoryWaypoint

订阅:

  - 主题: /fmu/in/offboard_control_mode
    类型: px4_msgs::msg::OffboardControlMode

  ...

  - 主题: /fmu/in/vehicle_trajectory_waypoint
    类型: px4_msgs::msg::VehicleTrajectoryWaypoint

多订阅:

  - 主题: /fmu/in/vehicle_optical_flow_vel
    类型: px4_msgs::msg::VehicleOpticalFlowVel

  ...

每个主题,类型) 成对定义：

1. 一个新的 刊物, 订阅费或 多订阅取决于它被添加到的列表。
2. 主题 基本名称其中 必须 与要发布/订阅的 uORB 主题名称一致。它由 主题： 开头的 / 并不包含任何 / 中。 载具几何, 载具状态 和 车外控制模式 都是基础名称的例子。
3. 主题 命名空间.默认设置为
   • /fmu/out/ 的主题 已出版 由 PX4 提供。
   • /fmu/in/ 的主题 已订阅 由 PX4 提供。
4. 信息类型 (载具几何尺寸, 载具状态, 机外控制模式等）和 ROS 2 软件包 (px4_msgs)，它将提供报文定义。

订阅 和 多订阅 允许我们选择 ROS 2 主题路由到的 uORB 主题实例：要么是一个共享实例（它也可能从 PX4 内部 uORB 发布者那里获得更新），要么是一个单独的实例（它是为 ROS2 发布预留的）。如果没有这种机制，所有 ROS 2 消息都会被路由到 一样 uORB 主题实例（因为 ROS 2 没有"...... "的概念）。 多主题实例PX4用户不可能区分来自 ROS 2 或 PX4 发布者的数据流。

在 订阅 节至：

• 创建一条从 ROS2 主题到 默认 实例 0）。例如，它创建了一个 ROS2 用户的 /fmu/in/vehicle_odometry 的 uORB 出版商 载具几何.
• 如果其他（内部）PX4 模块已经在与 ROS2 发布者相同的 uORB 主题实例上发布信息，则该实例的订阅者将接收所有信息流。uORB 订阅者将无法确定传入的信息是由 PX4 还是 ROS2 发布的。
• 当 ROS2 发布者有望成为主题实例的唯一发布者时（例如，在离线控制期间替换主题的内部发布者），或者当多个发布流的来源并不重要时，就需要这种行为。

在 多订阅 节至：

• 创建从 ROS2 主题到 新 相关 uORB 主题的实例。例如，如果 载具几何 已经 2 的 ROS2 订阅者。 /fmu/in/vehicle_odometry 和实例上的 uORB 发布者 3 的 载具几何.
• 这可确保其他内部 PX4 模块不会在 uXRCE-DDS 使用的同一实例上发布信息。订阅者可以订阅所需的实例，并区分发布者。
• 但请注意，这保证的是 PX4 和 ROS2 发布者之间的分离，而不是多个 ROS2 发布者之间的分离。在这种情况下，它们的信息仍会被路由到同一个实例。
• 例如，当您希望 PX4 记录两个相同传感器的读数时，这就是您想要的行为；它们都将发布在同一个主题上，但其中一个使用实例 0，另一个使用实例 1。

您可以任意更改配置。例如，您可以使用不同的默认命名空间，或使用自定义包来存储消息定义。

Fast-RTPS 到 uXRCE-DDS 迁移指南

本指南说明了如何从使用 PX4 v1.13 迁移到使用 PX4 v1.13 快速 RTPS 中间件到 PX4 v1.14 uXRCE-DDS 中间件。如果您有 为 PX4 v1.13 编写的 ROS 2 应用程序或使用 Fast-RTPS 将应用程序连接到 PX4 直接.

信息

本节包含迁移特定信息。要正确理解 uXRCE-DDS，还应阅读本页的其他内容。

无需移除依赖项

uXRCE-DDS 不需要 Fast-RTPS 所需的依赖项，例如通过以下主题安装的依赖项 快速 DDS 安装.您可以保留它们，而不会影响您的 uXRCE-DDS 应用程序。

如果您选择删除依赖项，请注意不要删除应用程序使用的任何内容（如 Java）。

_rtps 目标已删除

之前使用过带有扩展名的构建目标的任何地方 _rtps例如 PX4_FMU-V5_RTPS 或 px4_sitl_rtps现在，您可以使用等效的默认目标（针对这些情况 px4_fmu-v5_default 和 px4_sitl_default).

带扩展功能的制造目标 _rtps 用于构建包含客户端 RTPS 代码的固件。uXRCE-DDS 中间件默认包含在大多数电路板的构建中，因此你不再需要特殊的固件就能使用 ROS 2。

要检查您的电路板是否安装了中间件，请查找 CONFIG_MODULES_UXRCE_DDS_CLIENT=y 在 .px4board 文件。这些文件嵌套在 PX4-自动驾驶仪/控制板.

如果不存在，或者设置为 n然后，您必须克隆 PX4 软件源，修改电路板配置，并手动 汇编 固件。

新的客户端模块和新的启动参数

由于客户端是由新的 PX4 模块实现的，因此现在有了新的参数来启动它。请看 客户启动部分 了解如何做到这一点。

用于设置发布主题的新文件

为特定固件发布和订阅的主题列表现在由 dds_topic.yaml 配置文件，取代 urtps_bridge_topics.yaml

参见 支持的 uORB 信息 和 DDS 主题 YAML 章节获取更多信息。

主题不再需要在客户端和代理之间同步。

在 ROS 2 中，代理和客户端之间的桥接主题列表不再需要同步，所以 update_px4_ros2_bridge.sh 脚本不再需要。

默认主题命名约定已更改

更改了主题命名格式：

• 发表的主题 /fmu/topic-name/out (快速-RTPS)到 /fmu/out/topic-name (XRCE-DDS）。
• 订阅主题： /fmu/topic-name/in(快速-RTPS)到 /fmu/in/topic-name (XRCE-DDS）。

您应根据新约定更新您的应用程序。

信息

您还可以编辑 dds_topic.yaml 恢复到旧的习惯。不建议这样做，因为这意味着您必须始终使用自定义固件。

XRCE-DDS-Agent

XRCE-DDS 代理是通用代理，独立于 PX4： micro-xrce-dds-agent.在个人电脑/配套电脑上安装的方法有很多种，如需了解更多信息，请参见 专门部分.

针对应用程序的更改

如果您没有在使用 ROS 2 的同时使用代理 (独立于 ROS 的快速 DDS 接口)，则需要迁移到 eProsima Fast DDS.

ROS 2 应用程序仍然需要与 PX4 消息一起编译，您可以通过添加 px4_msgs 软件包到工作区。您可以删除 px4_ros_com 包，因为除了用于示例代码外，不再需要它。

在 ROS 2 节点中，您需要

• 更新 服务质量 因为 PX4 不使用 ROS 2 的默认设置。

• 更改主题名称，除非您编辑了 dds_topic.yaml.

• 删除与时间同步相关的所有内容，因为 XRCE-DDS 会自动处理代理/客户端时间同步。

  在 C++ 应用程序中，您可以设置 时戳 字段：

  msg.timestamp = 此->；获取时钟()->；现在().纳秒() / 1000;

  在 Python 应用程序中，您可以设置 时戳 字段：

  msg.timestamp = int(自我.get_clock().now().nanoseconds / 1000)

有用资源

• PX4 中的 ROS 2：向 XRCE-DDS 无缝过渡的技术细节 - 巴勃罗-加里多 & 努诺-马克斯（youtube）
• PX4 ROS 2 机外教程 (Github gist - JulianOes)
• ROS 2 PX4 机外教程 (林在荣）。