宇树 Unitree Go2 开发实操：从 SDK 环境配置到第一个运动控制 Demo（附踩坑记录）

最近不少在做巡检、科研和自动化落地的小伙伴陆续拿到了宇树 Unitree Go2。相比上一代 Go1，Go2 无论是在感知硬件还是底层通信架构上都有了不小的调整。其中对开发者影响最大的，就是通信中间件从过去的 LCM 全面切换到了 DDS（主要是 CycloneDDS），官方开发包也统一到了 unitree_sdk2。

很多朋友拿到机器后的第一反应是直接按官方 Readme 编译，结果往往卡在网络配置、DDS 节点通信或权限冲突上。这篇内容整理自阿橙最近在实机上的调测记录，从网络链路、SDK 编译到第一个 High-level 控制脚本，带大家走通全流程，并在文末附上实机调试的避坑清单。

一、硬件与版本确认

在插网线之前，先明确版本与通信物理拓扑：

1. 版本差异：宇树 Go2 分为 Air、Pro 和 EDU 版。如果你要做底层二次开发、使用 SDK 读写雷达点云或做电机级控制，必须确认拿到的是 Go2 EDU 版（通常板载 Jetson Orin 计算单元）。Air 和 Pro 版官方未开放完整的二次开发接口。
2. 网络接口：Go2 内部有自己的内网拓扑。外接开发电脑通常使用网线连接到机身内部的交换芯片引出网口（或机载计算单元的拓展网口）。默认情况下，机器狗内网网段为 192.168.123.x。

二、开发环境搭建

官方推荐的环境是 Ubuntu 20.04 / 22.04。本篇以 Ubuntu 22.04 LTS 为例，走 C++ 与 Python 的通用环境。

1. 安装基础依赖与 CycloneDDS

unitree_sdk2 强依赖 CycloneDDS。宇树在第三方依赖中打包了适配版本，建议直接使用源码编译安装：

sudo apt update
sudo apt install -y build-essential cmake git libboost-all-dev libyaml-cpp-dev

# 克隆官方仓库（包含第三方依赖）
git clone https://github.com/unitreerobotics/unitree_sdk2.git
cd unitree_sdk2

# 编译并安装自带的 cyclonedds
cd thirdparty
mkdir build && cd build
cmake ../cyclonedds -DCMAKE_INSTALL_PREFIX=/usr/local
make -j4
sudo make install

2. 编译 unitree_sdk2

回到 SDK 根目录，执行构建：

cd ../.. # 回到 unitree_sdk2 根目录
mkdir build && cd build
cmake ..
make -j4
sudo make install

如果你主要使用 Python，官方 SDK 也提供了基于 pybind11 的 Python 绑定。进入 unitree_sdk2_python 目录，通过 pip install -e . 即可完成本地环境注入。

三、配置网络与验证通信

这是初学者最容易卡住的一步。

1. 配置本地有线网卡： 将电脑网卡 IPv4 设为手动（Manual），IP 地址设置为 192.168.123.222，子网掩码 255.255.255.0，网关留空或设为 192.168.123.1。

2. Ping 连通性测试：

   • 狗身运动控制板 IP 通常为：192.168.123.161
   • 机载工控机 IP 通常为：192.168.123.18

   先在终端运行：

   bashCopy

   ping 192.168.123.161
   

   确保链路延迟在 1ms 以内且无丢包。

四、编写第一个运动控制 Demo（High-level）

在 Go2 的控制架构中，运动分为 High-level（高层运控） 与 Low-level（底层关节力矩）。第一次调测千万不要直接上 Low-level 电机力矩控制，先用封装好的 Sport 模式验证链路。

以下是一个基于 Python 的平地踏步与前进控制示例，逻辑清晰，适合验证心跳与通道：

import time
import sys
from unitree_sdk2py.core.channel import ChannelFactoryInitialize
from unitree_sdk2py.go2.sport.sport_client import SportClient

def main():
    if len(sys.argv) < 2:
        print("Usage: python3 demo_walk.py <NetworkInterface>")
        print("Example: python3 demo_walk.py eth0")
        sys.exit(-1)

    network_interface = sys.argv[1]
    
    # 1. 初始化 DDS 通道，指定绑定的物理网卡
    ChannelFactoryInitialize(0, network_interface)

    # 2. 实例化 Sport 客户端
    client = SportClient()
    client.SetTimeout(10.0)
    client.Init()

    print("Status: 正在连接 Sport 服务...")

    # 3. 站立测试
    print("Action: 站立恢复默认姿态")
    client.StandUp()
    time.sleep(2)

    # 4. 前进控制 (vx, vy, vyaw)
    # 参数含义：x轴线速度(m/s), y轴横移速度(m/s), 偏航角速度(rad/s)
    print("Action: 以 0.2 m/s 缓慢前进 3 秒")
    start_time = time.time()
    while time.time() - start_time < 3.0:
        client.Move(0.2, 0.0, 0.0)
        time.sleep(0.05)  # 保持 20Hz 左右的心跳发送

    # 5. 原地刹车并停下
    print("Action: 原地驻留")
    client.StopMove()
    time.sleep(1)

    print("Status: 测试完成")

if __name__ == "__main__":
    main()

运行方式（假设你的网卡名叫 eth0）：

python3 demo_walk.py eth0

五、探机阿橙的踩坑清单

实测中遇到的一些隐形坑点，官方文档通常只字不提，但实操时很容易让人抓狂：

1. CycloneDDS 多网卡广播风暴与选错网卡

• 现象：ping 狗身 IP 完全正常，但运行 Demo 时卡在 client.Init() 报超时。
• 原因：开发机如果同时开着 Wi-Fi，CycloneDDS 默认可能会把组播数据发到无线网卡或虚拟网卡（如 Docker 网桥）上。
• 解法：在运行程序前，务必指定绑定的网卡名称；或者配置 cyclonedds.xml，显式指定 <NetworkInterface name="你的有线网卡名"/>。

2. App 遥控器与 SDK 抢占控制权

• 现象：代码发了速度指令，狗只晃了一下就停下来，或者完全不响应。
• 原因：Go2 的配套 App 如果处于连接状态，或者手柄摇杆有轻微漂移，运控后台会优先响应手柄/App 的心跳包，覆盖 SDK 的指令。
• 解法：调试 SDK 时，将手机 App 完全退出后台，关闭蓝牙手柄连接。

3. 首次调试务必使用安全吊架（非常重要）

• 哪怕只调 High-level，也难免遇到参数给错（比如把角速度当成线速度放大了 10 倍）。
• 调试四足机器人的基本规范：机身必须挂在防跌落绳架上，四脚微微离地，先看关节响应方向是否符合预期，再落地跑。直接在地板上跑未经调试的代码，轻则断腿打齿，重则伤人。

4. 不要混淆 Sport 模式与 Low-level 关节阻抗模式

• 如果你后续要跑强化学习策略（RL）或走开源步态，需要使用 Low-level 接口。在切换到 Low-level 之前，必须先调用指令让机器狗“完全趴下并释放阻尼”，否则在 High-level 锁死状态下突然注入原始力矩，会导致底盘保护性急停甚至直接摔机。

六、场景落地：从 Hello World 到真实业务

调通上述基础 Demo 后，Go2 在实际工程落地中常见的演进路径主要有两条：

1. 工业巡检与自主建图： Go2 自带 4D 超广角激光雷达。如果做机房或变电站巡检，通常做法是将雷达点云通过 ROS 2 驱动吐出给 Cartographer 或 FAST-LIO 跑建图，然后用 Navigation 2 发送 /cmd_vel。你写的这个控制脚本，本质上就是把 Nav2 的速度指令转给 SportClient.Move() 的网桥。
2. 边缘智能感知： 利用机载 Orin 的算力部署轻量级目标检测模型（如 YOLOv8）。当视觉模型识别到目标后，通过状态机计算出目标与画面中心的误差，直接调用 client.Move(vx, 0, vyaw) 实现对人或特定设备的视觉伺服跟随。

先走通控制链路，再叠加传感器与算法，这是软硬件落地最稳妥的路径。遇到其他具体通信报错的小伙伴，可以在评论区贴上日志，我们一起看。