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

ROS 2 Humble 环境下宇树 Unitree 机器人部署指南

本文旨在为希望在 Ubuntu 22.04 + ROS 2 Humble 环境下开发宇树（Unitree）机器人的开发者提供一份从零开始的部署指南。我们将配置 unitree_ros2 功能包，实现 ROS 2 节点与机器人底层 DDS 系统的直接通信。

一、为什么选择 unitree_ros2？

宇树官方的 unitree_ros2 仓库提供了一种更原生的集成方式。与传统 SDK 桥接不同，它利用了 Unitree SDK 2 (基于 CycloneDDS) 和 ROS 2 (同样使用 DDS) 的通信共性。这意味着 ROS 2 节点可以直接与机器人底层通信，无需额外的接口封装，数据交换更高效。

本教程将带你走通这个配置流程，并针对 Humble 环境优化了步骤，特别是跳过了 Foxy 版本中复杂的 CycloneDDS 编译环节。

核心环境要求：

• 操作系统: Ubuntu 22.04 (Jammy)
• ROS 2 版本: Humble Hawksbill (LTS)
• 目标硬件: Unitree Go2 / B2 / H1 (真实机器人)

二、安装 ROS 2 Humble

如果你已经装好了 ROS 2 Humble，可以跳过这一步。

1. 设置区域语言

确保系统支持 UTF-8，避免后续编译报错。

sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

2. 添加软件源

添加 GPG 密钥并配置 ROS 2 仓库。

sudo apt install curl gnupg lsb-release
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

3. 安装 ROS 2 桌面版

包含 RVIZ 和常用示例工具。

sudo apt update
sudo apt install ros-humble-desktop

4. 安装构建工具

colcon 是 ROS 2 的标准构建工具，务必确认已安装。

sudo apt install python3-colcon-common-extensions

5. 环境变量配置

将 ROS 2 加载脚本加入 .bashrc，这样每次打开终端都会自动生效。

echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

6. 验证安装

打开两个终端窗口测试。 终端 1:

ros2 run demo_nodes_cpp talker

终端 2:

ros2 run demo_nodes_py listener

如果 Listener 能收到 Talker 的消息，说明 ROS 2 环境正常。

三、部署 Unitree ROS 2 功能包

这是连接真实机器人的关键步骤。

1. 安装依赖

除了基础 ROS 包，还需要特定的 RMW 实现和库。

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. 克隆工作空间

官方文档提到，Foxy 版本需要手动编译 CycloneDDS，但 Humble 自带版本已兼容，我们直接编译即可。

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

编译完成后，你会看到 install, build, log 目录。接着克隆官方仓库到主目录：

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

3. 网络配置

要让电脑和机器人通信，必须设置静态 IP。

1. 物理连接：用网线将 Ubuntu 电脑与机器人连接。
2. 查找网卡：运行 ip a 找到有线网卡名称（例如 enp3s0 或 eth0）。
3. 设置静态 IP：
   • 打开 Ubuntu 网络设置，找到该有线连接。
   • IPv4 模式改为'手动'。
   • 地址设为 192.168.123.99，子网掩码 255.255.255.0。
   • 应用并重新连接。

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

unitree_ros2 提供了 setup.sh 来配置 DDS，我们需要根据当前环境修改它。

打开脚本文件：

gedit ~/unitree_ros2/setup.sh

你需要做两处关键修改：

1. 将 source /opt/ros/foxy/setup.bash 改为 source /opt/ros/humble/setup.bash。
2. 将 <NetworkInterface name="enp3s0" ...> 中的网卡名改为你实际使用的网卡名（如 eth0）。

修改后的内容大致如下：

#!/bin/bash
echo "Setup unitree ros2 environment"
source /opt/ros/humble/setup.bash
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>'

5. 连接与测试

启动机器人后，先在新终端运行你修改好的 setup.sh：

source ~/unitree_ros2/setup.sh

然后查看话题列表：

ros2 topic list

如果网络配置正确，你应该能看到 /api/sport/request, /lf/lowstate, /sportmodestate 等来自机器人的话题。

尝试读取状态：

ros2 topic echo /sportmodestate

如果数据开始刷屏，恭喜，部署成功！

四、编译和运行示例

仓库中还提供了一个 example 工作空间用于演示。

1. 进入 example 目录并编译：

cd ~/unitree_ros2/example
colcon build

2. 加载环境（必须执行）：

source ~/unitree_ros2/setup.sh

3. 运行示例程序（例如读取运动状态）：

./install/unitree_ros2_example/bin/read_motion_state

你将看到格式化的位置、速度等信息输出。

五、常见问题排查

Q: ros2 topic list 看不到机器人的话题？ A: 99% 是网络问题。

1. 检查网线是否插好，机器人是否开机。
2. 确认电脑 IP 是否静态设置为 192.168.123.99。
3. 确认是否 source 了修改后的 setup.sh。
4. 检查 CYCLONEDDS_URI 中的网卡名是否绝对正确。
5. 尝试临时关闭防火墙：sudo ufw disable。

Q: colcon build 编译 cyclonedds_ws 失败？ A: 确保在编译前运行了 source /opt/ros/humble/setup.bash，并且安装了 ros-humble-rmw-cyclonedds-cpp 等所有依赖。

---

希望这份指南能帮你顺利跑通环境。如果在实际操作中遇到其他特定问题，建议查阅官方 GitHub 仓库的最新 Issue。