跳到主要内容 宇树机器人 SDK2 开发指南：从环境搭建到 Demo 测试 | 极客日志
C++ AI 算法
宇树机器人 SDK2 开发指南：从环境搭建到 Demo 测试 介绍宇树 G1 人形机器人 SDK2（C++ 与 Python）的完整开发流程。内容涵盖通信架构原理、Ubuntu 环境搭建、依赖安装、网络配置及 Demo 运行调试。通过关节摆动和音频播放示例，帮助开发者快速上手具身智能领域的机器人控制与二次开发，并提供常见问题解决方案。
RustyLab 发布于 2026/4/5 更新于 2026/4/13 1. SDK2 概述与架构原理
1.1 宇树 SDK2 是什么
unitree_sdk2 是宇树科技官方提供的机器人二次开发工具包，支持 Go2、B2、H1、G1 等主流机型在真实环境中的数据通信与运动控制。它是 unitree_legged_sdk 的升级替代版本，底层基于 CycloneDDS 实现了一套高效可靠的机器人通信机制。
SDK 包 语言 适用场景 unitree_sdk2C++ 高性能实时控制、底层关节控制、嵌入式开发 unitree_sdk2_pythonPython 快速原型验证、上层应用开发、算法研究
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 系统。
微信扫一扫，关注极客日志 微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
相关免费在线工具 加密/解密文本 使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
Markdown 转 HTML 将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
3. 获取官方 SDK 包
3.1 正常网络环境
git clone https://github.com/unitreerobotics/unitree_sdk2
git clone https://github.com/unitreerobotics/unitree_sdk2_python
3.2 国内网络加速（可选） 若 GitHub 访问较慢，可将域名替换为国内镜像加速节点：
git clone https://bgithub.xyz/unitreerobotics/unitree_sdk2
git clone https://bgithub.xyz/unitreerobotics/unitree_sdk2_python
3.3 目录结构预览 unitree_sdk2/
├── CMakeLists.txt
├── include /
│ └── unitree/
│ ├── robot/
│ └── idl/
├── example/
│ ├── g1/
│ │ ├── low_level/
│ │ ├── audio/
│ │ └── ...
│ ├── go2/
│ └── 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-devYAML 配置文件解析（机器人参数配置） libeigen3-dev线性代数库（矩阵运算、坐标变换） libboost-all-devC++ 通用工具库（异步 IO、线程等） libspdlog-dev高性能日志库 libfmt-dev格式化输出库（spdlog 依赖）
4.2 编译 C++ SDK cd unitree_sdk2
mkdir build
cd build
cmake ..
make
4.3 Python SDK 安装
sudo apt install python3-pip
pip3 install --upgrade pip
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（可选）
ifconfig
sudo ip addr add 192.168.123.222/24 dev eth0
sudo ip link set eth0 up
5.4 验证网络连通性
5.5 查询实际网卡名称 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
./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 )
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
time.sleep(0.002 )
if __name__ == "__main__" :
main()
8. 常见问题与解决方案
8.1 编译类错误 问题 1：fatal error: dds/dds.hpp: No such file or directory
find /usr -name "dds.hpp" 2>/dev/null
sudo apt-get install -y ros-noetic-cyclonedds
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
sudo apt-get install --reinstall libyaml-cpp-dev
8.2 网络连接类错误 问题 3：ping 192.168.123.161 无响应
问题 4：Demo 运行无响应（DDS 连接失败）
ifconfig | grep -E "^[a-z]"
./build/bin/g1_ankle_swing_example enp3s0
8.3 Python 环境类错误 问题 5：pip3 install -e . 失败
pip3 install --upgrade pip setuptools wheel
pip3 install -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）
└── 真机部署
参考资源 
