1. SDK2 概述与架构原理
1.1 宇树 SDK2 是什么
unitree_sdk2 是宇树科技官方提供的机器人二次开发工具包，支持 Go2、B2、H1、G1 等主流机型在真实环境中的数据通信与运动控制。它是 unitree_legged_sdk 的升级替代版本，底层基于 CycloneDDS 实现了一套高效可靠的机器人通信机制。
| SDK 包 | 语言 | 适用场景 |
|---|---|---|
unitree_sdk2 | C++ | 高性能实时控制、底层关节控制、嵌入式开发 |
unitree_sdk2_python | Python | 快速原型验证、上层应用开发、算法研究 |
1.2 宇树 G1 机器人规格速览
开始开发前，先了解硬件规格有助于正确配置控制参数：
| 参数项 | 规格 |
|---|---|
| 身高（站立） | 1320 mm |
| 整机重量 | ≈ 35 kg |
| 总自由度（关节电机） | 23 ~ 43 个（版本不同） |
| 单臂自由度 | 5 DOF（标准）/ 7 DOF（含腕关节） |
| 单腿自由度 | 6 DOF（髋 ×3 + 膝 ×1 + 踝 ×2） |
| 膝关节最大扭矩 | 90 N·m |
| 最大关节扭矩 | 120 N·m |
| 手臂最大负载 | ≈ 3 kg |
| 通信接口 | 以太网（CycloneDDS） |
| 机器人固定 IP | 192.168.123.161 |
2. 开发环境要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Ubuntu 20.04 LTS（推荐，官方完整支持） |
| 编译器 | GCC 9+ / G++ 9+ |
| 构建工具 | CMake 3.16+ |
| Python | Python 3.8+（建议 3.10） |
| 网络接口 | 有线以太网（需与机器人同网段） |
| C++ SDK | unitree_sdk2 |
| Python SDK | unitree_sdk2_python |
⚠️ 注意：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 目录结构预览
克隆完成后，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
各依赖包用途说明：
| 包名 | 用途 |
|---|---|
cmake / build-essential / g++ | 基础编译工具链 |
libyaml-cpp-dev | YAML 配置文件解析（机器人参数配置） |
libeigen3-dev | 线性代数库（矩阵运算、坐标变换） |
libboost-all-dev | C++ 通用工具库（异步 IO、线程等） |
libspdlog-dev | 高性能日志库 |
libfmt-dev | 格式化输出库（spdlog 依赖） |
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 网络拓扑
开发电脑 宇树 G1 机器人
┌─────────────────┐ 以太网 ┌─────────────────┐
│ eth0（或其他） ├──────────┤ 固定 IP │
│ 192.168.123.222 │ 网线直连│ 192.168.123.161 │
└─────────────────┘ └─────────────────┘
或通过交换机
机器人固定使用 192.168.123.161 作为 IP 地址，开发机需设置为同一网段（123 网段）的其他 IP。
5.2 Ubuntu 图形界面配置静态 IP
- 打开 系统设置 → 网络（Network）
- 选择连接机器人的有线网卡，点击 ⚙ 设置图标
- 选择 IPv4 选项卡，将方式改为 手动（Manual）
- 填写以下信息：
| 字段 | 填写内容 |
|---|---|
| 地址（Address） | 192.168.123.222（或其他 123 网段空闲 IP） |
| 子网掩码（Netmask） | 255.255.255.0 |
| 网关（Gateway） | 192.168.123.1 |
- 点击 应用（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：开机
└── 将机器人在吊装状态下通电启动
↓
步骤 2：等待零力矩模式
└── 等待机器人完成自检，进入零力矩（Damping）模式
关节处于自由垂落状态，此时可安全操作
↓
步骤 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 替换为你实际的网卡名称。
程序运行后的预期行为：
- 终端输出连接状态日志
- 订阅机器人
rt/lowstate话题，接收关节状态 - 向
rt/lowcmd话题发布控制指令 - 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__)"
| 现象 | 可能原因 | 快速解决 |
|---|---|---|
| 编译时找不到头文件 | 依赖库未安装 | 重新运行 apt-get install 命令 |
ping 不通 | 网络配置错误 | 检查 IP 地址是否在 123 网段 |
| Demo 运行无输出 | 网卡名称错误 | 用 ifconfig 查询正确名称 |
| Python 模块找不到 | 未安装 SDK | 在 SDK 目录执行 pip3 install -e . |
| 关节无响应 | 未进入调试模式 | 重新按 L2 + R2 进入调试模式 |
| 编译警告 / 错误 | 依赖版本冲突 | 参考各问题具体解决方案 |
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）
└── 真机部署
参考资源
| 资源 | 地址 |
|---|---|
| 宇树官方文档中心 | support.unitree.com |
| C++ SDK 仓库 | github.com/unitreerobotics/unitree_sdk2 |
| Python SDK 仓库 | github.com/unitreerobotics/unitree_sdk2_python |
| MuJoCo 仿真器 | github.com/unitreerobotics/unitree_mujoco |
| ROS2 支持包 | github.com/unitreerobotics/unitree_ros2 |
| 强化学习训练框架 | github.com/unitreerobotics/unitree_rl_gym |
| 宇树开源项目总览 | unitree.com/cn/mobile/opensource |
