go1_pro_sdk/README.md

Go1 PRO SDK

Unitree Go1 PRO 机型的低层电机控制 Python/C++ SDK。完整逆向 PRO 版的私有协议（Blowfish 加密 + 私有 LowCmd 格式），不依赖官方二进制库，Mac 直连可达 480Hz 控制频率。

这是为 PRO 准备的 SDK。如果你有 EDU 版机器狗，请用原版 free-dog-sdk — PRO 跟 EDU 协议有显著差异，互不兼容。

关键特性

• 完整 Blowfish ECB 加解密（用从机器狗内存提取的 state，不依赖原始 key）
• PRO 私有 LowCmd 格式（616B / CRC@612 / bandWidth BE 字节序），跟 EDU 不同
• LowState 解析（12 关节 + IMU + BMS + 足端力 + 遥控器）
• 实时遥控器按键/摇杆/L2 读取
• 三层安全保护（PositionLimit / PowerProtect 1-10 / PositionProtect），实测扭矩过载自动停机
• 实测频率: Mac 直连 480Hz（接近原版 EDU 500Hz）
• 实测延迟: 每帧 1.74ms p50（Blowfish 加密 1ms + 解密 0.7ms + sendto 0.02ms）

快速上手

官方 Python SDK 兼容接口

需要复用官方 unitree_legged_sdk Python 示例时，可以继续使用原来的模块名和 调用顺序：

import robot_interface as sdk

LOWLEVEL = 0xff  # 官方 wrapper 不导出这个常量，官方示例也是在应用中定义

udp = sdk.UDP(LOWLEVEL, 8080, "192.168.123.10", 8007)
safe = sdk.Safety(sdk.LeggedType.Go1)
cmd, state = sdk.LowCmd(), sdk.LowState()
udp.InitCmdData(cmd)

udp.Recv()
udp.GetRecv(state)
safe.PowerProtect(cmd, state, 1)
udp.SetSend(cmd)
udp.Send()

兼容范围和协议差异见 docs/OFFICIAL_API_COMPATIBILITY.md。 官方 HighCmd/HighState UDP 通道和二进制 ABI 当前不在兼容范围内。 需要同一份代码同时运行在本项目和官方 SDK 上时，只使用官方实际导出的接口；参考 examples/example_official_compatible_position.py。

官方 C++ SDK 兼容接口

同一份低层 C++ 源码可分别链接本项目或官方 unitree_legged_sdk：

#include "unitree_legged_sdk/unitree_legged_sdk.h"
using namespace UNITREE_LEGGED_SDK;

UDP udp(LOWLEVEL, 8090, "192.168.123.10", 8007);
Safety safe(LeggedType::Go1);
LowCmd cmd{};
udp.InitCmdData(cmd);

cmake -S . -B build-cpp -DCMAKE_BUILD_TYPE=Release
cmake --build build-cpp
ctest --test-dir build-cpp --output-on-failure

PRO 环境链接本项目生成的 libunitree_legged_sdk；官方机器人环境链接官方同名库。 参考 examples/cpp/example_official_compatible_position.cpp。 Blowfish state 默认随库安装，也可用 GO1_PRO_BLOWFISH_STATE 指定。

高层控制 (走/跳/姿态, 通过 sportMode 系统)

from go1_pro_sdk import Go1, Velocity, Pose, LED

with Go1() as dog:
    dog.stand_up()
    dog.set_walk_mode()
    dog.walk(Velocity(vx=0.3))    # 前进
    dog.dance_1()
    dog.set_led(LED(0, 255, 0))
    dog.stand_down()

通过 MQTT 控制树莓派上的 Legged_sport. 跟低层互不冲突, 但只能二选一同时用.

低层控制 (直接控 12 个电机)

from go1_pro_sdk import MCUClient, LowCmd, MotorCmd, MotorMode

with MCUClient() as client:
    client.wake_mcu()                       # 唤醒并切换为我们的客户端
    state = client.recv_state()             # 读一帧状态
    print(f"FR_0 q = {state.motorState[0].q}")
    print(f"电量: {state.bms.SOC}%")
    print(f"遥控器按下: {state.remote.pressed}")

    # 控制 FR 大腿 (注意先悬空 + 安全保护层)
    cmd = LowCmd()
    cmd.set_motor('FR_1', MotorCmd(
        mode=MotorMode.Servo, q=1.2, Kp=5, Kd=1
    ))
    client.send(cmd)

    client.safe_stop()                       # 退出前发 damping

准备工作

1. 提取 Blowfish 密钥（仅需一次）

go1_pro_sdk/_data/blowfish_state.bin 已包含我们项目用的密钥。如果你的狗用的是不同的 key（很少见，除非固件升级），需要重新提取：

# SSH 到狗 (192.168.123.161)
scp tools/extract_blowfish_key.sh pi@192.168.123.161:/tmp/
ssh pi@192.168.123.161 "sudo bash /tmp/extract_blowfish_key.sh"
scp pi@192.168.123.161:/tmp/blowfish_dump.tar.gz ./data/

# Mac 端分析
python tools/analyze_blowfish_dump.py data/blowfish_dump.tar.gz
# → 输出 go1_pro_sdk/_data/blowfish_state.bin

2. 停掉狗上的抢占源

PRO 的 MCU 一次只接受一个客户端的命令。要让 SDK 工作，必须先停掉狗上的:

ssh pi@192.168.123.161 "sudo pkill -9 -f keep_sport_alive; \
                          sudo pkill -9 -f Legged_sport; \
                          sudo pkill -9 -f appTransit"

或用我们提供的:

bash tools/stop_sportmode.sh stop

3. 跑示例

# 只读监听 LowState
python examples/monitor_state.py --duration 30 --verbose

# 监听遥控器
python examples/monitor_remote.py

# 单腿 sin 摆动 (狗悬空, 振幅 0.3 rad)
python examples/example_sin_leg.py --amplitude 0.3 --freq 0.5

# 复刻原版 example_position(lowlevel).py
python examples/example_position.py

4. 测完恢复

bash tools/stop_sportmode.sh start

⚠️ 安全

直接控制 12 个电机是危险操作：

• 第一次测试 狗必须悬空 (脚架/吊带)
• 用 apply_safety(cmd, state, power_factor=1) 限制力矩到 10%
• 准备 拔电池 作为终极停机 (Legged_sport 被杀后，遥控器 L2+B 不会工作)
• 见 docs/SAFETY.md

包结构

go1_pro_sdk/
├── connection/   # MCUClient: 高层 UDP 客户端
├── codec/        # Blowfish + LowCmd 序列化 + LowState 解析
├── types/        # MotorCmd, LowState, IMU, BMS, RemoteState 等
├── safety/       # PositionLimit / PowerProtect / PositionProtect
├── utils/        # CRC, 浮点编解码, 关节常量
└── _data/        # blowfish_state.bin

include/unitree_legged_sdk/  # 官方 C++ 头文件兼容层
src/                         # PRO UDP/Blowfish/Safety 实现
tests/cpp/                   # C++ 契约、抓包和安装消费测试

文档

• docs/PROTOCOL.md — PRO LowCmd/LowState 字节级格式规格
• docs/SAFETY.md — 安全测试清单
• docs/REVERSE_ENGINEERING.md — 逆向工程过程精华
• docs/ARCHITECTURE.md — 包结构与数据流

致谢

• 原版 free-dog-sdk by Bin4ry (Andreas Makris) — 提供了 EDU 版的基础数据结构和 CRC 实现
• Unitree 官方 unitree_legged_sdk — 公开了 safety.h 的接口定义

License

MIT (跟 free-dog-sdk 一致)