4.0 KiB
4.0 KiB
Unitree 官方 SDK 接口兼容说明
对比基准：Unitree unitree_legged_sdk
go1 分支，README 版本 v3.8.6，提交
4539a6c10dfbc9781cea6fcb7d51bc6ddc6f71e1（2023-07-11）。
结论
本项目和官方 SDK 使用相近的低层对象模型，但此前不是调用兼容：本项目入口是
MCUClient.send()/recv_state()，官方 Python wrapper 入口是
robot_interface.UDP.SetSend()/Send()/Recv()/GetRecv()。
当前项目已提供 robot_interface 兼容模块。官方低层 Python 示例可保留原来的
导入和主要调用流程，同时底层会使用 Go1 PRO 所需的 Blowfish 加密和 616 字节
私有 LowCmd 协议。
接口矩阵
| 官方接口 | 本项目原接口 | 当前兼容状态 |
|---|---|---|
robot_interface.LowCmd/LowState |
同名类型 | 已对齐命令和常用状态字段名 |
MotorCmd/MotorState/IMU |
同名类型 | 常用字段已对齐 |
BmsState |
BMS |
名称已对齐；PRO 状态区较短，见下文 |
BmsCmd, Cartesian, UDPState |
原先缺失 | 已补齐 |
UDP(LOWLEVEL, ...) |
MCUClient(...) |
已适配标准四参数构造 |
InitCmdData |
原先缺失 | 已实现官方 stop sentinel 初始化 |
Recv/GetRecv/SetSend/Send |
recv_latest/send |
已适配 |
Safety.PositionLimit |
position_limit |
已适配，跳过 PosStopF |
Safety.PowerProtect |
power_protect |
调用兼容，算法不是官方闭源实现 |
Safety.PositionProtect |
position_protect |
调用兼容，保护动作更保守 |
HighCmd/HighState |
MQTT Go1/Go1MQTT |
类型已提供，UDP 传输不支持 |
Loop/LoopFunc |
无 | 官方 Python wrapper 本身也未导出 |
| C++ headers/static library | 无 | 不兼容 C++ 源码或 ABI |
关键协议差异
官方 SDK 的公开结构不能直接描述本项目实测的 Go1 PRO 线协议。PRO 低层通道需要：
- 616 字节
LowCmd，CRC 位于 612； - Blowfish ECB 加密；
bandWidth使用实测字节序和值；- 858 字节加密状态包中取 856 字节块解密，再解析 807 字节有效状态。
因此兼容层只对齐用户代码接口，不替换本项目现有 codec，也不承诺二进制包与官方 EDU SDK 相同。
官方风格用法
import robot_interface as sdk
udp = sdk.UDP(sdk.LOWLEVEL, 8080, "192.168.123.10", 8007)
safe = sdk.Safety(sdk.LeggedType.Go1)
cmd = sdk.LowCmd()
state = sdk.LowState()
udp.InitCmdData(cmd)
udp.Recv()
udp.GetRecv(state)
cmd.motorCmd[sdk.FR_1].q = 1.2
cmd.motorCmd[sdk.FR_1].dq = 0.0
cmd.motorCmd[sdk.FR_1].Kp = 5.0
cmd.motorCmd[sdk.FR_1].Kd = 1.0
safe.PositionLimit(cmd)
safe.PowerProtect(cmd, state, 1)
udp.SetSend(cmd)
udp.Send()
UDP(HIGHLEVEL, ..., "192.168.123.161", 8082) 不会被静默映射到 MQTT。两种通道
状态模型和时序不同，兼容层会明确抛出 NotImplementedError。高层控制继续使用
Go1 或 Go1MQTT。
尚未完全对齐的风险
- 官方
PowerProtect实现在静态库中，头文件只公开签名。本项目当前保护逻辑按 关节力矩限幅和实测过载执行，不等价于官方内部的累计功率算法。 - 官方
BmsState是 34 字节，本项目实测的 PRO 状态布局只给 BMS 分配 24 字节；cell_vol后半部分不能视为完整的官方数据。 LowState.tick当前没有从 PRO 包中解析，仍为默认值；footForce和footForceEst的偏移来自逆向推断，尚未达到官方字段的同等可信度。head/SN/version/reserve/crc在本地原生类型中部分使用bytes，官方 wrapper 使用定长整数数组或整数。命令 builder 接受两种常见赋值形态，但读取后的 Python 类型不保证完全相同。- 本项目
LowState是 PRO 抓包格式的解释，不应按官方#pragma pack(1)结构大小 直接做内存映射。 - 官方 C++ 用户需要单独的 C++ facade 和库链接方案；Python 兼容模块不能让现有 C++ 程序直接重编译通过。