171 lines
5.3 KiB
Markdown
171 lines
5.3 KiB
Markdown
# Go1 PRO SDK
|
||
|
||
Unitree Go1 **PRO** 机型的低层电机控制 Python SDK。完整逆向 PRO 版的私有协议（Blowfish 加密 + 私有 LowCmd 格式），不依赖官方 C++ SDK，Mac 直连可达 480Hz 控制频率。
|
||
|
||
> 这是为 PRO 准备的 SDK。如果你有 **EDU** 版机器狗，请用原版 [free-dog-sdk](https://github.com/Bin4ry/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 示例时，可以继续使用原来的模块名和
|
||
调用顺序：
|
||
|
||
```python
|
||
import robot_interface as sdk
|
||
|
||
udp = sdk.UDP(sdk.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`](docs/OFFICIAL_API_COMPATIBILITY.md)。
|
||
官方 `HighCmd/HighState` UDP 通道和 C++ ABI 当前不在兼容范围内。
|
||
|
||
### 高层控制 (走/跳/姿态, 通过 sportMode 系统)
|
||
|
||
```python
|
||
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 个电机)
|
||
|
||
```python
|
||
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（很少见，除非固件升级），需要重新提取：
|
||
|
||
```bash
|
||
# 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 工作，必须先停掉狗上的:
|
||
|
||
```bash
|
||
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
|
||
bash tools/stop_sportmode.sh stop
|
||
```
|
||
|
||
### 3. 跑示例
|
||
|
||
```bash
|
||
# 只读监听 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
|
||
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
|
||
```
|
||
|
||
## 文档
|
||
|
||
- `docs/PROTOCOL.md` — PRO LowCmd/LowState 字节级格式规格
|
||
- `docs/SAFETY.md` — 安全测试清单
|
||
- `docs/REVERSE_ENGINEERING.md` — 逆向工程过程精华
|
||
- `docs/ARCHITECTURE.md` — 包结构与数据流
|
||
|
||
## 致谢
|
||
|
||
- 原版 [free-dog-sdk](https://github.com/Bin4ry/free-dog-sdk) by Bin4ry (Andreas Makris) — 提供了 EDU 版的基础数据结构和 CRC 实现
|
||
- Unitree 官方 [unitree_legged_sdk](https://github.com/unitreerobotics/unitree_legged_sdk) — 公开了 safety.h 的接口定义
|
||
|
||
## License
|
||
|
||
MIT (跟 free-dog-sdk 一致)
|