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

本文以宇树 G1 人形机器人为主线，系统介绍 unitree_sdk2（C++）与 unitree_sdk2_python（Python）的完整开发流程，涵盖通信架构原理、环境搭建、依赖安装、Demo 编译运行、网络配置以及常见问题处理，适合具身智能领域的初中级开发者快速上手。

目录

1. SDK2 概述与架构原理
2. 开发环境要求
3. 获取官方 SDK 包
4. 安装依赖与编译
5. 机器人与开发机网络配置
6. 调试并运行 Demo
7. Python SDK Demo 测试
8. 常见问题与解决方案
9. 总结

1. SDK2 概述与架构原理

1.1 宇树 SDK2 是什么

unitree_sdk2 是宇树科技官方提供的机器人二次开发工具包，支持 Go2、B2、H1、G1 等主流机型在真实环境中的数据通信与运动控制。它是 unitree_legged_sdk 的升级替代版本，底层基于 CycloneDDS 实现了一套高效可靠的机器人通信机制。

1.2 宇树 G1 机器人规格速览

开始开发前，先了解硬件规格有助于正确配置控制参数：

2. 开发环境要求

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

3. 获取官方 SDK 包

3.1 正常网络环境

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

3.2 国内网络加速（可选）

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

# 将 https://github.com 替换为 https://bgithub.xyzgit 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 依赖安装

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

sudoapt-get update sudoapt-getinstall-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 是最新版本sudoaptinstall python3-pip pip3 install--upgrade pip # 进入 Python SDK 目录并以可编辑模式安装cd ~ 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

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

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

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

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

5.4 验证网络连通性

# 测试是否能 ping 通机器人ping192.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 -Bbuild 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"classG1Controller:def__init__(self): self.low_state =None self.low_cmd = LowCmd_()definit_cmd(self):"""初始化控制指令结构，所有关节设置为阻尼模式"""for i inrange(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.0deflow_state_handler(self, msg: LowState_):"""机器人状态回调函数""" self.low_state = msg defmain():iflen(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.0whileTrue:# 踝关节正弦摆动示例if ctrl.low_state isnotNone: 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 相关编译错误

# 重新安装sudoapt-getinstall--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. 总结

11.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） └── 真机部署 

参考资源

💬 本文涵盖内容为宇树 SDK2 开发的完整主流程。如需深入了解特定模块（如强化学习部署、全身运动控制、ROS2 集成），欢迎继续探讨。