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

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

本文面向希望在 Ubuntu 22.04 + ROS 2 Humble 环境下开发宇树（Unitree）机器人（支持 Go2, B2, H1）的开发者。我们将重点讲解如何配置 unitree_ros2 功能包，实现 ROS 2 节点与机器人底层 DDS 系统的直接通信。本教程基于官方文档优化，针对 Humble 环境调整了 CycloneDDS 相关步骤。

核心环境：

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

一、为什么选择 unitree_ros2

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

二、安装 ROS 2 Humble (Ubuntu 22.04)

若已安装可跳过此步。

1. 设置 UTF-8 区域

确保系统支持 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. 添加 ROS 2 软件源

添加 GPG 密钥并配置仓库。

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 (Humble)

安装桌面完整版，包含 RVIZ 及示例工具。

sudo apt update
sudo apt install ros-humble-desktop

4. 安装构建工具

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

sudo apt update
sudo apt install python3-colcon-common-extensions

5. 设置环境变量

将 ROS 2 环境脚本加入 .bashrc，新终端自动加载。

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

6. 测试安装

打开两个终端分别运行 talker 和 listener：

终端 1:

ros2 run demo_nodes_cpp talker

终端 2:

ros2 run demo_nodes_py listener

若 Listener 收到 Talker 消息，说明安装成功。

三、部署 Unitree ROS 2 功能包

这是连接真实机器人的核心环节。

1. 安装特定依赖

需要安装 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 版本，Humble 自带的 rmw_cyclonedds 已兼容，无需手动编译 CycloneDDS。

# 进入工作空间
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. 配置网络（连接真实机器人）

物理连接：用网线连接电脑与机器人。
查找网卡：运行 ifconfig 或 ip a，记下有线网卡名称（如 enp3s0 或 eth0）。
设置静态 IP：
- 进入 Ubuntu 网络设置 -> IPv4。
- 模式改为'手动'。
- 地址：192.168.123.99
- 子网掩码：255.255.255.0
- 应用并重新连接。

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

我们需要根据当前环境和网卡名称修改 setup.sh。

打开脚本文件：

gedit ~/unitree_ros2/setup.sh

修改前 (原始内容):

#!/bin/bash
echo "Setup unitree ros2 environment"
source /opt/ros/foxy/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="enp3s0" priority="default" multicast="default" /> </Interfaces></General></Domain></CycloneDDS>'

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

#!/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>'

请将 YOUR_INTERFACE_NAME 替换为第 3 步中查到的实际网卡名（如 eth0）。

5. 连接与测试

启动机器人。
打开新终端，运行修改后的 setup.sh：
```
source ~/unitree_ros2/setup.sh
```
查看话题列表：
```
ros2 topic list
```
若网络正常，应能看到 /api/sport/request, /lf/lowstate, /sportmodestate 等话题。
验证数据：
```
ros2 topic echo /sportmodestate
```
若看到状态数据刷屏，部署成功。

四、编译和运行示例

仓库提供了 example 工作空间用于验证。

cd ~/unitree_ros2/example
colcon build

加载环境后运行示例程序：

./install/unitree_ros2_example/bin/read_motion_state

您将看到格式化后的运动状态信息：

[INFO] [1697525196.266174885] [motion_state_suber]: Position -- x: 0.567083; y: 0.213920; z: 0.052338...

五、常见问题与总结

最关键的步骤是修改 setup.sh 脚本，确保指向 humble 并使用正确的网卡名称。

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

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

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