# 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` 协议。

反过来，要让本项目编写的程序直接在官方 SDK 上复现，应用必须导入
`robot_interface`，并限制在官方 wrapper 真正导出的公共子集内。应用不应直接导入
`go1_pro_sdk`。

## 接口矩阵

| 官方接口 | 本项目原接口 | 当前兼容状态 |
|---|---|---|
| `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` | 无 | C++ 已提供；官方 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

LOWLEVEL = 0xff
FR_1 = 1

udp = sdk.UDP(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[FR_1].q = 1.2
cmd.motorCmd[FR_1].dq = 0.0
cmd.motorCmd[FR_1].Kp = 5.0
cmd.motorCmd[FR_1].Kd = 1.0
safe.PositionLimit(cmd)
safe.PowerProtect(cmd, state, 1)
udp.SetSend(cmd)
udp.Send()
```

这里故意不使用 `sdk.LOWLEVEL`、`sdk.FR_1`、上下文管理器或 `close()`：这些是本项目
提供的便利能力，但不属于官方 Python wrapper 的导出契约。

## C++ 同源码用法

C++ 公共入口、命名空间、结构字段和低层方法签名与官方 v3.8.6 对齐：

```cpp
#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{};
LowState state{};
udp.InitCmdData(cmd);
```

业务源码和 `#include` 不变，只切换链接库。PRO 端用本项目 CMake 目标
`unitree_legged_sdk`，官方 Go1 端用官方仓库的 `libunitree_legged_sdk.a`。本项目已经用
官方头文件反向编译可移植示例，并用本项目头文件编译官方仓库的五个 C++ 示例。

本项目构建方法：

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

标准四参数 `UDP(LOWLEVEL, ...)` 会在库内部完成 PRO 编解码。默认从安装数据目录读取
Blowfish state；需要覆盖时设置 `GO1_PRO_BLOWFISH_STATE=/path/to/blowfish_state.bin`。

## 可移植程序规则

要求同一份源码直接运行时，主控制流程只使用：

- `import robot_interface as sdk`；
- `sdk.UDP`、`sdk.Safety`、`sdk.LeggedType`；
- `sdk.LowCmd/LowState`、`MotorCmd/MotorState`、`IMU/BmsState`；
- `InitCmdData/Recv/GetRecv/SetSend/Send`；
- 官方结构中公开的字段，例如 `motorCmd[i].q` 和 `motorState[i].q`。

所有官方结构对象都应先无参构造，再逐字段赋值。例如使用
`motor = sdk.MotorCmd(); motor.q = 1.0`，不要写 `sdk.MotorCmd(q=1.0)`。后者是 Python
dataclass 常见写法，但官方 pybind wrapper 不接受构造参数。

枚举也按官方对象使用，例如 `sdk.Safety(sdk.LeggedType.Go1)`。不要把枚举当作整数比较
或直接写 `sdk.Safety(2)`；本项目的严格兼容入口会和官方一样拒绝后一种写法。

以下接口属于 PRO 扩展，使用后程序不再能在只安装官方 SDK 的环境中直接运行：

- `from go1_pro_sdk import ...`；
- `MCUClient`、`Go1`、`Go1MQTT`；
- `LowCmd.set_motor()`、`all_damping()`；
- `LowState.remote`、`apply_safety()`；
- `wake_mcu()`、`safe_stop()`、Blowfish 和快速 C++ builder。

推荐把程序分为“官方公共控制核心”和“可选 PRO 增强”两个模块。公共核心不能导入
增强模块；增强模块可以包装公共核心，但必须允许在官方环境中完全不加载。

`Send()`、`Recv()` 和 `SetSend()` 的具体正整数来自线协议和底层 socket，不属于跨
SDK 稳定契约。初始化时可以用 `Recv() > 0` 判断是否收到包，但不应比较具体字节数。

首次进入 PRO 低层通道前，应先反复发送 `InitCmdData()` 产生的 stop sentinel，并在
收到第一帧 `LowState` 后再写入有效位置目标。可移植示例已采用这一时序，避免在状态
仍为全零默认值时直接驱动关节。

`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++ 类型布局和公开符号用于源码重编译兼容，不保证本项目库与官方预编译对象之间
  的 ABI 互换；切换实现时应重新编译应用。
- 两个自定义包长 C++ `UDP` 构造函数和 `SetSend(char*)` 提供原始 UDP 透传，但不会
  自动把任意自定义结构转换为 PRO 私有协议；主动断连时间和 accessible 时间参数
  仅保留调用形状。Python 兼容入口仍只保证标准四参数 `LOWLEVEL` 通道。
- 官方 SDK 和本项目都提供顶层 `robot_interface`，同一个 Python 环境不要同时安装
  两种实现。应在 PRO 环境安装本项目，在官方机器人环境安装官方 SDK。