宇树 Unitree 机器人 ROS 2 Humble 环境部署指南 (Go2/B2/H1)

3.1 (重要) 安装 colcon 构建工具

colcon 是 ROS 2 的标准构建工具，我们后续编译工作空间时会用到它。

# 此包通常作为 ros-humble-desktop 的依赖被自动安装
# 为确保万无一失，我们手动执行一次
sudo apt update
sudo apt install python3-colcon-common-extensions

4. 设置环境变量

将 ROS 2 的环境设置脚本添加到您的 .bashrc 中，以便新终端自动加载。

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
# 使其在当前终端生效
source ~/.bashrc

5. 测试安装

打开两个终端。

终端 1 (Talker):

ros2 run demo_nodes_cpp talker

终端 2 (Listener):

ros2 run demo_nodes_py listener

如果您在 Listener 终端能看到 Talker 发送的 [INFO] 消息，恭喜您，ROS 2 Humble 已成功安装！

部署 Unitree ROS 2 功能包

这是本教程的核心。我们将配置 unitree_ros2 以连接到您的真实机器人。

1. 安装特定依赖

unitree_ros2 需要一些特定的 ROS 2 包和库。

sudo apt update
sudo apt install ros-humble-rmw-cyclonedds-cpp
sudo apt install ros-humble-rosidl-generator-dds-idl
sudo apt install libyaml-cpp-dev
sudo apt install git # (如果尚未安装)

2. 克隆与编译工作空间

编译工作空间：

关键提示 (Humble vs Foxy)： 官方文档指出，如果您使用 ROS 2 Foxy，必须手动下载和编译特定版本的 cyclonedds (0.10.x)。 但我们使用 Humble，可以跳过这个繁琐的步骤！Humble 自带的 rmw_cyclonedds 版本已兼容。

我们直接编译 unitree_go 和 unitree_api 包：

# 进入工作空间
cd ~/unitree_ros2/cyclonedds_ws
# (重要) 确保 ROS 2 环境已加载
source /opt/ros/humble/setup.bash
# 编译所有包
colcon build

等待编译完成，您应该会看到 install, build, log 目录。

克隆官方仓库到您的主目录：

cd ~
git clone https://github.com/unitreerobotics/unitree_ros2

3. 配置网络（连接真实机器人）

1. 物理连接：使用网线将您的 Ubuntu 电脑与机器人连接。
2. 查找网卡名称：打开终端，运行 ifconfig 或 ip a。找到您连接机器人的那个有线网卡，记下其名称，例如 enp3s0 或 eth0。
3. 设置静态 IP：
   • 打开 Ubuntu 的'网络设置'。
   • 找到该有线连接，进入 IPv4 设置。
   • 模式改为'手动'。
   • 设置地址：
     • 地址: 192.168.123.99
     • 子网掩码: 255.255.255.0
   • 点击'应用'并重新连接网络。

4. 修改环境脚本 (最关键一步)

unitree_ros2 提供了一个 setup.sh 脚本来配置 DDS。我们需要根据我们的环境（Humble 和 网卡名称）修改它。

修改文件内容：修改前 (原始文件内容)：

#!/bin/bash
echo "Setup unitree ros2 environment"
source /opt/ros/foxy/setup.bash # <--- (1) 这里是 foxy
source $HOME/unitree_ros2/cyclonedds_ws/install/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export CYCLONEDDS_URI='<CycloneDDS><Domain><General><Interfaces>
   <NetworkInterface name="enp3s0" priority="default" multicast="default" />
</Interfaces></General></Domain></CycloneDDS>'

修改后 (适配您的环境)：

#!/bin/bash
echo "Setup unitree ros2 environment"
source /opt/ros/humble/setup.bash # <--- (1) 必须改为 humble
source $HOME/unitree_ros2/cyclonedds_ws/install/setup.bash
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export CYCLONEDDS_URI='<CycloneDDS><Domain><General><Interfaces>
   <NetworkInterface name="YOUR_INTERFACE_NAME" priority="default" multicast="default" />
</Interfaces></General></Domain></CycloneDDS>'

（例如，如果您的网卡是 eth0，就改成 name="eth0"）

打开脚本文件：

gedit ~/unitree_ros2/setup.sh

5. 连接与测试

1. 启动机器人。

查看数据：

ros2 topic echo /sportmodestate

如果一切正常，您将看到机器人的状态数据开始刷屏，部署成功！

测试连接：

ros2 topic list

如果网络配置正确，DDS 会自动发现机器人。您应该能看到一系列来自机器人的话题，例如：

/api/sport/request
/lf/lowstate
/sportmodestate
/wirelesscontroller
...

打开一个新终端，运行您修改后的 setup.sh 来加载所有环境：

source ~/unitree_ros2/setup.sh

编译和运行示例

unitree_ros2 仓库还提供了一个 example 工作空间。

1. 打开一个新终端。

运行示例（例如：读取运动状态）：

# 确保您在 example 目录下
./install/unitree_ros2_example/bin/read_motion_state

您将在终端看到格式化后的机器人状态信息：

[INFO] [1697525196.266174885] [motion_state_suber]: Position -- x: 0.567083; y: 0.213920; z: 0.052338; body height: 0.320000
[INFO] [1697525196.266230044] [motion_state_suber]: Velocity -- vx: -0.008966; vy: -0.001431; vz: -0.019455; yaw: -0.002131
...

编译示例：

cd ~/unitree_ros2/example
colcon build

加载 Unitree 环境（必须！）：

source ~/unitree_ros2/setup.sh

总结与常见问题 (FAQ)

本教程详细介绍了如何在 Ubuntu 22.04 + ROS 2 Humble 环境下，部署 unitree_ros2 功能包以连接真实机器人硬件。最关键的步骤是修改 setup.sh 脚本，使其指向 humble 并使用正确的网卡名称。

Q: 我运行 ros2 topic list 为什么看不到机器人的话题？

A: 99% 是网络问题。

1. 检查物理连接：网线是否插好？机器人是否开机？
2. 检查 IP 地址：您电脑的 IP 是否静态设置为了 192.168.123.99？
3. 检查 setup.sh：您是否 source 了修改后的 setup.sh？
4. 检查网卡名称：CYCLONEDDS_URI 变量中的 name 是否绝对正确？
5. 检查防火墙：sudo ufw disable 临时禁用防火墙试试。

Q: colcon build 编译 cyclonedds_ws 失败了。

A: 确保您在编译前运行了 source /opt/ros/humble/setup.bash，并且已经安装了 ros-humble-rmw-cyclonedds-cpp 等所有依赖。