C++AI算法
宇树 G1 机器人 SDK2 开发指南：环境搭建至 Demo 测试
介绍宇树 G1 人形机器人 SDK2（C++ 与 Python）的开发流程。内容包括环境搭建（Ubuntu 20.04）、依赖安装、SDK 编译、网络配置（静态 IP 设置）、Demo 运行调试及常见问题解决。通过关节摆动与音频播放示例，帮助开发者快速实现机器人通信与控制。
介绍宇树 G1 人形机器人 SDK2（C++ 与 Python）的开发流程。内容包括环境搭建（Ubuntu 20.04）、依赖安装、SDK 编译、网络配置（静态 IP 设置）、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。
| 字段 | 填写内容 |
|---|---|
| 地址（Address） | 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) < :
()
sys.exit()
ChannelFactoryInitialize(, sys.argv[])
ctrl = G1Controller()
ctrl.init_cmd()
sub = ChannelSubscriber(TOPIC_LOWSTATE, LowState_)
sub.Init(ctrl.low_state_handler, )
pub = ChannelPublisher(TOPIC_LOWCMD, LowCmd_)
pub.Init()
()
t =
:
ctrl.low_state :
ctrl.low_cmd.motor_cmd[].q = * math.sin(t)
ctrl.low_cmd.motor_cmd[].kp =
ctrl.low_cmd.motor_cmd[].kd =
pub.Write(ctrl.low_cmd)
t +=
time.sleep()
__name__ == :
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 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 进入调试模式 |
| 编译警告 / 错误 | 依赖版本冲突 | 参考各问题具体解决方案 |
环境准备
├── 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
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online