宇树机器人 SDK2 开发指南：环境搭建与 Demo 测试

⚠️ 注意：SDK2 不建议在 Windows 上直接使用；若只有 Windows 主机，需安装 VMware 后在 Ubuntu 虚拟机中开发，但虚拟机的网卡直通配置较复杂，强烈建议使用原生 Ubuntu 系统。

3. 获取官方 SDK 包

3.1 正常网络环境

# 克隆 C++ SDK
git clone https://github.com/unitreerobotics/unitree_sdk2
# 克隆 Python SDK
git clone https://github.com/unitreerobotics/unitree_sdk2_python

3.2 国内网络加速（可选）

若 GitHub 访问较慢，可将域名替换为国内镜像加速节点：

# 将 https://github.com 替换为 https://bgithub.xyz
git clone https://bgithub.xyz/unitreerobotics/unitree_sdk2
git clone https://bgithub.xyz/unitreerobotics/unitree_sdk2_python
# 或使用 Gitee 镜像（若有同步）
# git clone https://gitee.com/unitreerobotics/unitree_sdk2

3.3 目录结构预览

克隆完成后，C++ SDK 的核心目录结构如下：

unitree_sdk2/
├── CMakeLists.txt          # 顶层构建文件
├── include/
│   └── unitree/            # SDK 头文件
│       ├── robot/          # 机器人控制接口
│       └── idl/            # DDS IDL 数据结构定义
├── example/
│   ├── g1/                 # G1 机器人示例
│   │   ├── low_level/      # 底层关节控制
│   │   ├── audio/          # 音频播放
│   │   └── ...
│   ├── go2/                # Go2 机器人示例
│   └── h1/                 # H1 机器人示例
└── lib/                    # 预编译库文件

4. 安装依赖与编译

4.1 C++ SDK 依赖安装

首先更新系统软件源，然后一次性安装所有编译依赖：

sudo apt-get update
sudo apt-get install -y cmake g++ build-essential libyaml-cpp-dev libeigen3-dev libboost-all-dev libspdlog-dev libfmt-dev

各依赖包用途说明：

4.2 编译 C++ SDK

cd unitree_sdk2
# 方法一：标准两步构建
mkdir build
cd build
cmake ..
make

4.3 Python SDK 安装

# 确保 pip3 是最新版本
sudo apt install python3-pip
pip3 install --upgrade pip
# 进入 Python SDK 目录并以可编辑模式安装
cd ~/unitree_sdk2_python
pip3 install -e .

验证安装是否成功：

python3 -c "import unitree_sdk2py; print('SDK 安装成功！')"

5. 机器人与开发机网络配置

SDK2 通过有线以太网实现 PC 与机器人之间的 DDS 通信，正确的网络配置是连接成功的前提。

5.1 网络拓扑

开发电脑 (eth0: 192.168.123.222) <--- 网线 ---> 宇树 G1 机器人 (192.168.123.161)

机器人固定使用 192.168.123.161 作为 IP 地址，开发机需设置为同一网段（123 网段）的其他 IP。

5.2 Ubuntu 图形界面配置静态 IP

1. 打开 系统设置 → 网络（Network）
2. 选择连接机器人的有线网卡，点击 ⚙ 设置图标
3. 选择 IPv4 选项卡，将方式改为 手动（Manual）
4. 填写以下信息：

5. 点击 应用（Apply），断开并重新连接网络使配置生效。

5.3 命令行配置静态 IP（可选）

# 查看网卡名称（记住连接机器人的那块网卡名，如 eth0、enp3s0 等）
ifconfig
# 临时设置（重启后失效，用于快速测试）
sudo ip addr add 192.168.123.222/24 dev eth0
sudo ip link set eth0 up

5.4 验证网络连通性

# 测试是否能 ping 通机器人
ping 192.168.123.161
# 正常输出示例：
# PING 192.168.123.161 (192.168.123.161) 56(84) bytes of data.
# 64 bytes from 192.168.123.161: icmp_seq=1 ttl=64 time=0.456 ms

5.5 查询实际网卡名称

ifconfig

输出示例：

enp3s0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500 inet 192.168.123.222 netmask 255.255.255.0 broadcast 192.168.123.255 ...
lo: flags=73<UP,LOOPBACK,RUNNING> mtu 65536 ...

⚠️ 重要：记下连接机器人的网卡名称（如 enp3s0、eth0），后续运行 Demo 时需要作为命令行参数传入。不同电脑的网卡名称可能不同，请以实际 ifconfig 输出为准。

6. 调试并运行 Demo

6.1 机器人准备流程

在运行任何 Demo 之前，必须按以下步骤准备机器人：

1. 步骤 1：开机
   • 将机器人在吊装状态下通电启动
2. 步骤 2：等待零力矩模式
   • 等待机器人完成自检，进入零力矩（Damping）模式
   • 关节处于自由垂落状态，此时可安全操作
3. 步骤 3：进入调试模式
   • 同时长按遥控器 L2 + R2 组合键
   • 机器人进入调试模式，等待外部控制指令

⚠️ 安全提示：务必在吊装状态下进行调试，防止机器人倒塌造成损坏。进入调试模式后，机器人关节将响应外部控制指令，请确保周围无障碍物。首次测试建议先以最小幅度运行 Demo，确认行为符合预期后再扩大测试范围。

6.2 Step 1：重新编译（首次运行必须）

cd unitree_sdk2
cmake -B build
cmake --build build

6.3 Step 2：运行关节摆动 Demo

以 G1 踝关节摆动为例：

# 语法：./build/bin/<demo 名称> <网卡名称>
./build/bin/g1_ankle_swing_example enp3s0

将 enp3s0 替换为你实际的网卡名称。

程序运行后的预期行为：

1. 终端输出连接状态日志
2. 订阅机器人 rt/lowstate 话题，接收关节状态
3. 向 rt/lowcmd 话题发布控制指令
4. G1 的踝关节开始按正弦波形规律左右摆动

6.4 Step 3：运行音频播放 Demo（C++）

./build/bin/g1_audio_server_example enp3s0

预期效果：机器人内置扬声器播放预设音频，可用于验证音频通信链路是否正常。

7. Python SDK Demo 测试

Python SDK 提供了与 C++ SDK 功能等价的接口，更适合快速开发和算法验证。

7.1 运行音频客户端示例

cd unitree_sdk2_python
python3 ./example/g1/audio/g1_audio_client_example.py enp3s0

7.2 Python SDK 使用范例

以下是一个完整的 Python 控制示例，展示如何订阅机器人状态并发布控制指令：

import sys
import time
import math
from unitree_sdk2py.core.channel import ChannelSubscriber, ChannelPublisher, ChannelFactoryInitialize
from unitree_sdk2py.idl.unitree_go.msg.dds_ import LowCmd_, LowState_

# 话题名称常量
TOPIC_LOWCMD = "rt/lowcmd"
TOPIC_LOWSTATE = "rt/lowstate"

class G1Controller:
    def __init__(self):
        self.low_state = None
        self.low_cmd = LowCmd_()

    def init_cmd(self):
        """初始化控制指令结构，所有关节设置为阻尼模式"""
        for i in range(35):
            self.low_cmd.motor_cmd[i].mode = 0x01
            self.low_cmd.motor_cmd[i].q = 0.0
            self.low_cmd.motor_cmd[i].dq = 0.0
            self.low_cmd.motor_cmd[i].kp = 0.0
            self.low_cmd.motor_cmd[i].kd = 0.5  # 阻尼系数
            self.low_cmd.motor_cmd[i].tau = 0.0

    def low_state_handler(self, msg: LowState_):
        """机器人状态回调函数"""
        self.low_state = msg

def main():
    if len(sys.argv) < 2:
        print("用法：python3 script.py <网卡名称>")
        sys.exit(1)

    # 初始化 DDS 通信
    ChannelFactoryInitialize(0, sys.argv[1])
    ctrl = G1Controller()
    ctrl.init_cmd()

    # 创建订阅器（接收机器人状态）
    sub = ChannelSubscriber(TOPIC_LOWSTATE, LowState_)
    sub.Init(ctrl.low_state_handler, 10)

    # 创建发布器（发送控制指令）
    pub = ChannelPublisher(TOPIC_LOWCMD, LowCmd_)
    pub.Init()

    print("连接成功，开始控制循环...")
    t = 0.0
    while True:
        # 踝关节正弦摆动示例
        if ctrl.low_state is not None:
            ctrl.low_cmd.motor_cmd[14].q = 0.3 * math.sin(t)  # 左踝关节
            ctrl.low_cmd.motor_cmd[14].kp = 10.0
            ctrl.low_cmd.motor_cmd[14].kd = 1.0
            pub.Write(ctrl.low_cmd)
        t += 0.002  # 500 Hz 控制频率
        time.sleep(0.002)

if __name__ == "__main__":
    main()

8. 常见问题与解决方案

8.1 编译类错误

问题 1：fatal error: dds/dds.hpp: No such file or directory

# 原因：CycloneDDS 库未正确安装或 CMake 未找到库路径
# 解决：
# 检查 dds.h 是否存在
find /usr -name "dds.hpp" 2>/dev/null
# 如果不存在，手动安装 cyclonedds
sudo apt-get install -y ros-noetic-cyclonedds
# 如果已装 ROS Noetic
# 或从源码编译
git clone https://github.com/eclipse-cyclonedds/cyclonedds
cd cyclonedds && mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
make -j$(nproc) && sudo make install

问题 2：libyaml-cpp 相关编译错误

# 重新安装
sudo apt-get install --reinstall libyaml-cpp-dev

8.2 网络连接类错误

问题 3：ping 192.168.123.161 无响应

# 排查步骤：
# ① 确认网线物理连接正常（网卡指示灯是否亮起）
# ② 确认 IP 配置在正确的网卡上（注意多网卡环境）
# ③ 确认机器人已开机并处于调试模式
# ④ 检查防火墙是否阻断了 ICMP 包：
sudo ufw disable  # 临时关闭防火墙测试
# ⑤ 用 ifconfig 确认 PC 端 IP 是否在 192.168.123.x 网段

问题 4：Demo 运行无响应（DDS 连接失败）

# 确认网卡名称正确（区分大小写）
ifconfig | grep -E "^[a-z]"
# 以正确网卡名重新运行
./build/bin/g1_ankle_swing_example enp3s0  # 换成实际网卡名

8.3 Python 环境类错误

问题 5：pip3 install -e . 失败

# 升级 pip 后重试
pip3 install --upgrade pip setuptools wheel
pip3 install -e .
# 若提示权限不足，加 --user 或使用 sudo pip3 install --user -e .

问题 6：ModuleNotFoundError: No such module 'unitree_sdk2py'

# 检查是否在正确目录下安装
cd ~/unitree_sdk2_python
pip3 install -e .
# 验证模块路径
python3 -c "import unitree_sdk2py; print(unitree_sdk2py.__file__)"

9. 总结

9.1 完整开发流程回顾

# 环境准备
# ├── Ubuntu 20.04 系统
# ├── 安装编译依赖（apt-get）
# └── 克隆 SDK 仓库

# SDK 编译安装
# ├── C++：cmake -B build && cmake --build build
# └── Python：pip3 install -e .

# 网络配置
# ├── 开发机设置静态 IP（192.168.123.x 网段）
# ├── ping 192.168.123.161 验证连通性
# └── ifconfig 查询网卡名称

# 机器人准备
# ├── 吊装状态下开机
# ├── 等待零力矩模式
# └── 遥控器 L2 + R2 进入调试模式

# Demo 测试
# ├── C++ Demo：./build/bin/g1_ankle_swing_example <网卡名>
# └── Python Demo：python3 ./example/g1/audio/g1_audio_client_example.py <网卡名>

# 二次开发
# ├── 仿真验证（unitree_mujoco）
# └── 真机部署

参考资源