90 lines
4.0 KiB
Markdown
90 lines
4.0 KiB
Markdown
# Unitree 官方 SDK 接口兼容说明
|
||
|
||
对比基准：Unitree [`unitree_legged_sdk`](https://github.com/unitreerobotics/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 相同。
|
||
|
||
## 官方风格用法
|
||
|
||
```python
|
||
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++ 程序直接重编译通过。
|