📚 课程目录第4章开发环境搭建

4. 开发环境搭建

PX4 与 ROS 2 的 uXRCE-DDS 通信链路能否稳定运行，很大程度上取决于开发环境是否“版本对齐”。很多初学者在第一次联调时遇到“话题不出现”“Agent 启动即退出”“编译报错找不到 uORB 消息”等问题，根源往往不是代码写错，而是 Ubuntu、ROS 2、PX4 与 Micro XRCE-DDS Agent 四者之间的版本与依赖关系没有理顺。本章按照“系统 → ROS 2 → PX4 → Agent → 兼容性验证”的顺序，搭建一条可复现的开发环境。

4.1 核心原理：四层依赖与版本对齐

uXRCE-DDS 通信开发环境本质上是一个四层依赖栈：最底层是 Ubuntu 操作系统，提供内核、网络与编译工具链；其上是 ROS 2，提供 DDS 中间件与话题机制；再上是 PX4 固件源码，内置 uXRCE-DDS Client 并生成 uORB 消息映射；最上层是 Micro XRCE-DDS Agent，负责在串口/UDP 与 DDS 网络之间做桥接。四层之间通过“消息定义”和“协议版本”耦合，任何一层版本错位都可能导致通信失败。

4.2 方法流程：从系统到 Agent 的安装步骤

推荐使用 Ubuntu 22.04 LTS，它与 ROS 2 Humble 是官方长期支持组合。安装前先更新系统并安装基础工具：

sudo apt update && sudo apt upgrade -y
sudo apt install -y git cmake python3-pip python3-venv \
  build-essential ninja-build ccache
sudo usermod -aG dialout $USER   # 串口权限，需重新登录生效

接着安装 ROS 2 Humble。按官方源配置后安装桌面版，并安装 PX4 消息包 px4_msgs：

sudo apt install -y ros-humble-desktop
source /opt/ros/humble/setup.bash
mkdir -p ~/ws_px4/src && cd ~/ws_px4/src
git clone https://github.com/PX4/px4_msgs.git -b release/1.14
cd ~/ws_px4 && colcon build --symlink-install
source install/setup.bash

PX4 源码编译建议使用官方脚本，它会自动拉取子模块并安装工具链：

git clone https://github.com/PX4/PX4-Autopilot.git --recursive
cd PX4-Autopilot
git checkout v1.14.0
make px4_sitl gz_x500   # 编译 SITL 仿真目标

Micro XRCE-DDS Agent 推荐从源码编译，便于控制版本：

git clone https://github.com/eProsima/Micro-XRCE-DDS-Agent.git
cd Micro-XRCE-DDS-Agent
mkdir build && cd build
cmake .. && make -j$(nproc)
sudo make install
sudo ldconfig /usr/local/lib/

4.3 版本兼容性检查清单

安装完成后，必须逐项核对版本，避免“装上了但连不通”。下表给出关键检查项与推荐值：

检查项	命令	推荐值	不匹配后果
Ubuntu 版本	`lsb_release -a`	22.04 LTS	ROS 2 源不可用
ROS 2 版本	`echo $ROS_DISTRO`	humble	px4_msgs 编译失败
PX4 版本	`git describe --tags`	v1.14.x	uORB 消息字段不一致
Agent 版本	`MicroXRCEAgent --version`	v1.4.x	协议握手失败
px4_msgs 分支	`git branch`	release/1.14	话题类型不匹配

提示：PX4 与 px4_msgs 必须使用同一 release 分支。例如 PX4 v1.14.0 对应 px4_msgs release/1.14，混用会导致消息 ID 与字段定义错位。

4.4 案例场景：SITL 仿真联调验证

环境搭建完成后，用 SITL 仿真做一次最小闭环验证。先启动 PX4 SITL，再启动 Agent，最后用 ROS 2 订阅话题：

# 终端1：启动 PX4 SITL
cd ~/PX4-Autopilot
make px4_sitl gz_x500

# 终端2：启动 Agent，监听 UDP 8888
MicroXRCEAgent udp4 -p 8888

# 终端3：查看 ROS 2 话题
source ~/ws_px4/install/setup.bash
ros2 topic list | grep fmu
ros2 topic echo /fmu/out/vehicle_status --once

若 ros2 topic list 中出现 /fmu/in/ 与 /fmu/out/ 前缀话题，说明 Client 与 Agent 已成功握手，DDS 桥接正常。此时可以进一步用 ros2 topic hz /fmu/out/vehicle_attitude 观察数据频率，确认链路稳定。

常见误区：Agent 启动后没有任何输出并不代表失败，它默认静默运行；若出现 session established 日志，才表示与 PX4 Client 建链成功。若长时间无日志，优先检查 PX4 参数 XRCE_DDS_CFG 是否设置为 UDP 或串口，以及端口是否一致。

4.5 复盘：环境搭建的三个关键点

版本对齐优先于安装速度：Ubuntu、ROS 2、PX4、Agent 四者版本必须成组匹配，不要随意混用最新版。
px4_msgs 与 PX4 同源：消息包分支必须与固件 release 分支一致，否则话题类型无法解析。
先仿真后实机：用 SITL + UDP 验证链路，再切换到串口连接真实飞控，可大幅降低排障成本。