> 以宇树 G1 人形机器人为主线，系统介绍 **unitree_sdk2**（C++）与 **unitree_sdk2_python**（Python）的完整开发流程，涵盖通信架构原理、环境搭建、依赖安装、Demo 编译运行、网络配置以及常见问题处理，适合具身智能领域的初中级开发者快速上手。 目录 SDK2 概述与架构原理 开发环境要求 获取官方 SDK 包 安装依赖与编译 机器人与开发机网…
本文以宇树 G1 人形机器人为主线，系统介绍 unitree_sdk2（C++）与 （Python）的完整开发流程，涵盖通信架构原理、环境搭建、依赖安装、Demo 编译运行、网络配置以及常见问题处理，适合具身智能领域的初中级开发者快速上手。
unitree_sdk2 是宇树科技官方提供的机器人二次开发工具包，支持 Go2、B2、H1、G1 等主流机型在真实环境中的数据通信与运动控制。它是 unitree_legged_sdk 的升级替代版本，底层基于 CycloneDDS 实现了一套高效可靠的机器人通信机制。
| SDK 包 | 语言 | 适用场景 |
|---|---|---|
unitree_sdk2 | C++ | 高性能实时控制、底层关节控制、嵌入式开发 |
unitree_sdk2_python | Python | 快速原型验证、上层应用开发、算法研究 |
开始开发前，了解硬件规格有助于正确配置控制参数：
| 参数项 | 规格 |
|---|---|
| 身高（站立） | 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 |
| 项目 | 要求 |
|---|---|
| 操作系统 | 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 系统。
# 克隆 C++ SDK
git clone https://github.com/unitreerobotics/unitree_sdk2
# 克隆 Python SDK
git clone https://github.com/unitreerobotics/unitree_sdk2_python
若 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
克隆完成后，C++ SDK 的核心目录结构如下：
unitree_sdk2/
├── CMakeLists.txt # 顶层构建文件
├── include/
│ └── unitree/ # SDK 头文件
│ ├── robot/ # 机器人控制接口
│ └── idl/ # DDS IDL 数据结构定义
├── example/
│ ├── g1/ # G1 机器人示例
│ │ ├── low_level/ # 底层关节控制
│ │ ├── audio/ # 音频播放
│ │ └── ...
│ ├── go2/ # Go2 机器人示例
│ └── h1/ # H1 机器人示例
└── lib/ # 预编译库文件
首先更新系统软件源，然后一次性安装所有编译依赖：
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 依赖） |
cd unitree_sdk2
# 标准两步构建
mkdir build && cd build
cmake ..
make
# 确保 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 安装成功！')"
SDK2 通过有线以太网实现 PC 与机器人之间的 DDS 通信，正确的网络配置是连接成功的前提。
开发电脑 宇树 G1 机器人
┌─────────────────┐ 以太网 ┌─────────────────┐
│ eth0（或其他） ├──────────┤ 固定 IP │
│ 192.168.123.222 │ 网线直连│ 192.168.123.161 │
└─────────────────┘ 或通过交换机 └─────────────────┘
机器人固定使用 192.168.123.161 作为 IP 地址，开发机需设置为同一网段（123 网段）的其他 IP。
192.168.123.222（或其他 123 网段空闲 IP） |
| 子网掩码（Netmask） | 255.255.255.0 |
| 网关（Gateway） | 192.168.123.1 |# 查看网卡名称（记住连接机器人的那块网卡名，如 eth0、enp3s0 等）
ifconfig
# 临时设置（重启后失效，用于快速测试）
sudo ip addr add 192.168.123.222/24 dev eth0
sudo ip link set eth0 up
# 测试是否能 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
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输出为准。
在运行任何 Demo 之前，必须按以下步骤准备机器人：
步骤 1：开机
└── 将机器人在吊装状态下通电启动
↓
步骤 2：等待零力矩模式
└── 等待机器人完成自检，进入零力矩（Damping）模式
关节处于自由垂落状态，此时可安全操作
↓
步骤 3：进入调试模式
└── 同时长按遥控器 L2 + R2 组合键
机器人进入调试模式，等待外部控制指令
⚠️ 安全提示：务必在吊装状态下进行调试，防止机器人倒塌造成损坏。进入调试模式后，机器人关节将响应外部控制指令，请确保周围无障碍物。首次测试建议先以最小幅度运行 Demo，确认行为符合预期后再扩大测试范围。
cd unitree_sdk2
cmake -B build
cmake --build build
以 G1 踝关节摆动为例：
# 语法：./build/bin/<demo名称> <网卡名称>
./build/bin/g1_ankle_swing_example enp3s0
将 enp3s0 替换为你实际的网卡名称。
程序运行后的预期行为：
rt/lowstate 话题，接收关节状态rt/lowcmd 话题发布控制指令./build/bin/g1_audio_server_example enp3s0
预期效果：机器人内置扬声器播放预设音频，可用于验证音频通信链路是否正常。
Python SDK 提供了与 C++ SDK 功能等价的接口，更适合快速开发和算法验证。
cd unitree_sdk2_python
python3 ./example/g1/audio/g1_audio_client_example.py enp3s0
以下是一个完整的 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()
问题 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
问题 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 # 换成实际网卡名
问题 5：pip3 install -e . 失败
# 升级 pip 后重试
pip3 install --upgrade pip setuptools wheel
pip3 install -e .
# 若提示权限不足，加 --user 或使用 sudo
pip3 install --user -e .
问题 6：ModuleNotFoundError: No module named '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 进入调试模式 |
| 编译警告 / 错误 | 依赖版本冲突 | 参考各问题具体解决方案 |
环境准备
├── 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 |
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online