Skip to content
DroidFlight Wiki

宇树 Unitree SDK 集成

概念速览

  • Unitree SDK：宇树官方 Python / C++ 客户端，控制 G1 / H1 / Go2 / B2 / Z1 等机型
  • 两代并存：SDK2 (新) 用 DDS 走 UDP/以太网，SDK1 (旧) 用自研 RPC over UDP
  • 通信方式：以太网直连 (网线) / 路由器 (DHCP) / WiFi (Go2 自带热点)
  • 关键包：unitree_sdk2py (Python 3.8+) · unitree_sdk2 (C++)

SDK1 vs SDK2

项SDK1 (旧)SDK2 (新, 2024+)
协议自研 RPCDDS (与 ROS 2 同协议)
机型Go1 / 旧 Go2G1 / H1 / 新 Go2 / B2 / Z1
实时性1 kHz1 kHz
Python 包unitree_legged_sdkunitree_sdk2py
ROS 2 桥需手写 adapter原生 DDS topic
推荐仅维护旧项目新项目默认 SDK2

安装 SDK2 (Python)

Terminal window
# 1. 创建 conda 环境 (避免污染系统 Python)
conda create -n unitree python=3.10 -y
conda activate unitree


# 2. 装 SDK2
pip install unitree_sdk2py


# 3. 装 CycloneDDS (SDK2 默认用这个 RMW)
sudo apt install ros-${ROS_DISTRO}-rmw-cyclonedds-cpp
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp


# 4. (可选) 装 unitree_ros2 — 把 SDK 桥到 ROS 2 topic
mkdir -p ~/unitree_ws/src && cd ~/unitree_ws/src
git clone https://github.com/unitreerobotics/unitree_ros2.git -b iron
cd ~/unitree_ws && rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install

物理连接

flowchart LR
    A["宇树 G1 / H1<br/>IP: 192.168.123.x<br/>静态"]
    B["PC / 工控<br/>192.168.123.99"]
    A <-->|以太网直连| B
Terminal window
# PC 端配同网段
sudo ip addr add 192.168.123.99/24 dev eth0
ip route add 192.168.123.0/24 dev eth0


# ping 测试
ping 192.168.123.161   # G1 默认 IP

最小 Python 控制示例 (SDK2)

"""G1 站立 + 挥手示例"""
from unitree_sdk2py.core.channel import ChannelFactoryInitialize
from unitree_sdk2py.g1.loco.g1_loco_client import LocoClient


# 1. 初始化 DDS 通道
ChannelFactoryInitialize(0, "192.168.123.99")  # 0 = domain 0


# 2. 创建运动控制客户端
loco = LocoClient()
loco.SetTimeout(3.0)
loco.Init()


# 3. 站起来
loco.Start()


# 4. 挥手 (左手)
loco.WaveHand()


# 5. 蹲下
loco.Squat()

常见机型 IP 默认值

机型默认 IP (机器人)网口
G1192.168.123.161ETH0 (背部)
H1192.168.123.161ETH0 (背部)
Go2192.168.123.18WiFi 热点 Unitree_Go2_xxxx
B2192.168.123.18ETH0
Z1 (机械臂)192.168.123.121ETH0

进阶

  • 多机协同：改 ROS_DOMAIN_ID (0-232) + 改 PC IP 段 (192.168.123.y)
  • VLA 接入：把 LocoClient.Move(vx, vy, omega) 替换为 Octo / OpenVLA 输出
  • 仿真对接：unitree_ros2 的 sim topic 直接桥接 Isaac Sim / MuJoCo
  • 云端控制：用 Tailscale / ZeroTier 把 SDK2 暴露到公网 (注意延迟 50ms+)

📋 复现条件

类别必备备注
硬件宇树 G1 / H1 / Go2 (任一) · 千兆网线 · Linux PCWindows 不支持 DDS
操作系统Ubuntu 22.04 / 24.04 (LTS)Mac 缺 CycloneDDS 编译链
软件版本Python 3.10+ · ROS 2 Humble/Iron/Jazzy · CycloneDDSDocker 镜像 unitree/ros2
网络192.168.123.0/24 直连 (机器人)路由器需禁 AP 隔离
账号无宇树 GitHub 公开仓库
时间SDK 装 30 min · DDS 配通 20 min · 跑通 WaveHand 1 hSim2Real 1 周
难度⭐⭐⭐ 中DDS 概念 + ROS 2 基础
预算宇树机器 ¥100,000+二手 G1 EDU ¥85,000

⛔ 别这么做 (Anti-patterns)

经验证的坑 —— 跳过 = 至少浪费半天，严重的烧板 / 锁机。

❌ 错误做法💥 后果⚠️ 风险范围
不要把 SDK2 与 SDK1 在同一项目混用两套 RPC 协议互不兼容，话题会断。🟡G1 / H1 / Go2
不要在 WiFi 模式下跑低延迟控制WiFi 抖动 10-50 ms = G1 摔倒。永远用网线。🔴所有宇树机型
不要用 pip install unitree_legged_sdk 装给 G1老 SDK 完全没有 G1 驱动，会 ImportError。🟡G1 / H1
不要在没设 RMW_IMPLEMENTATION 的情况下用 SDK2 + ROS 2默认 FastDDS 与 SDK2 CycloneDDS 互不认，话题隔离。🟡SDK2 + ROS 2 桥接
不要在真机启用 SDK 之前不接急停按钮失控 = 撞人 / 撞墙。永远物理急停触手边。🔴所有真机
不要把机器人 IP 设在 192.168.1.x (家用网段)与路由器 DHCP 冲突。永远用 192.168.123.x。🟢所有宇树机型

🚨 风险总览 (Risk Matrix)

风险等级含义例子
🟢 低改错可回滚 / 几分钟恢复IP 段冲突，IP 写死
🟡 中需要重新刷机 / 重装 / 1-2 小时恢复SDK 混用，RMW 没配
🔴 高不可逆 / 烧板 / 安全风险WiFi 跑控制，没急停

参考资料