143 lines
5.8 KiB
Markdown
143 lines
5.8 KiB
Markdown
# 包结构与数据流
|
|
|
|
## 模块依赖图
|
|
|
|
```
|
|
┌──────────────────────┐
|
|
│ MCUClient │ ← 用户主要 API
|
|
│ (connection/) │
|
|
└──────┬───────────────┘
|
|
│
|
|
┌──────────────┼──────────────┐
|
|
▼ ▼ ▼
|
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
│ codec/ │ │ types/ │ │ safety/ │
|
|
│ Blowfish │ │ LowCmd │ │ apply_ │
|
|
│ build_* │ │ LowState │ │ safety │
|
|
│ parse_* │ │ MotorCmd │ │ │
|
|
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
|
|
│ │ │
|
|
└────────────────┼────────────────┘
|
|
▼
|
|
┌─────────────┐
|
|
│ utils/ │
|
|
│ common.py │ ← CRC, float_hex
|
|
│ constants │ ← 关节限位, 默认地址
|
|
└─────────────┘
|
|
```
|
|
|
|
## 数据流: 收一帧 → 用户处理 → 发命令
|
|
|
|
```
|
|
UDP 858B 密文 UDP 616B 密文
|
|
▲ │
|
|
│ ▼
|
|
MCU :8007 MCU :8007
|
|
│ ▲
|
|
▼ │
|
|
┌─────────────────────────────────────────────────┐
|
|
│ MCUClient.recv_latest() │
|
|
│ socket.recvfrom() │
|
|
│ bf.decrypt_ecb(data[:856]) → 856B 明文 │
|
|
│ parse_low_state(...) → LowState 结构 │
|
|
└─────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌──────────┐ 用户逻辑 ┌──────────┐
|
|
│ LowState │ ──────────► │ LowCmd │
|
|
└──────────┘ qDes, Kp, └──────────┘
|
|
Kd, tau... │
|
|
▼
|
|
┌─────────────────────────────────────────────────┐
|
|
│ apply_safety(cmd, state, power_factor=1) │
|
|
│ position_limit(cmd) │
|
|
│ power_protect(cmd, state, factor) │
|
|
│ position_protect(cmd, state, limit_rad) │
|
|
└─────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────┐
|
|
│ MCUClient.send(cmd) │
|
|
│ build_low_cmd_plain(cmd) → 616B 明文 │
|
|
│ bf.encrypt_ecb(plain) → 616B 密文 │
|
|
│ sock.sendto(cipher, ...) │
|
|
└─────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## 各包职责
|
|
|
|
### utils/
|
|
|
|
最底层。纯函数, 无副作用, 无依赖其他模块。
|
|
|
|
- `common.py`: CRC, float↔hex, tau↔2B, Kp↔2B, Kd↔2B, decode_sn/version
|
|
- `constants.py`: MCU 地址, 关节命名, 限位, TAU_MAX, DAMPING_POSE
|
|
|
|
### types/
|
|
|
|
数据结构 (dataclass)。依赖 utils, 不依赖 codec/safety/connection。
|
|
|
|
- `motor.py`: MotorCmd, MotorState, MotorMode
|
|
- `imu.py`: IMU
|
|
- `bms.py`: BMS
|
|
- `remote.py`: RemoteState, parse_remote
|
|
- `low_cmd.py`: LowCmd (12 motorCmd + 元数据)
|
|
- `low_state.py`: LowState (12 motorState + IMU + BMS + remote 等)
|
|
|
|
### codec/
|
|
|
|
加解密和序列化。依赖 types + utils。
|
|
|
|
- `blowfish.py`: 标准 Blowfish ECB (LE 字节序), 接受预生成 state
|
|
- `lowcmd_builder.py`: LowCmd → 616B 明文 → 加密后 616B
|
|
- `lowstate_parser.py`: 解密后 807B → LowState 结构
|
|
|
|
### safety/
|
|
|
|
控制保护层。依赖 types + utils。
|
|
|
|
- `safety.py`: PositionLimit/PowerProtect/PositionProtect 三个保护 + 统一入口 apply_safety
|
|
|
|
### connection/
|
|
|
|
UDP 高层抽象。依赖前面所有。
|
|
|
|
- `mcu_client.py`: MCUClient (socket + Blowfish + 序列化 + safe_stop)
|
|
|
|
## 用户三种用法
|
|
|
|
### Level 1: 高层 (推荐)
|
|
|
|
```python
|
|
from go1_pro_sdk import MCUClient, LowCmd, MotorCmd, MotorMode
|
|
|
|
with MCUClient() as client:
|
|
client.wake_mcu()
|
|
state = client.recv_state()
|
|
cmd = LowCmd()
|
|
cmd.set_motor('FR_1', MotorCmd(mode=MotorMode.Servo, q=1.2, Kp=5, Kd=1))
|
|
client.send(cmd)
|
|
client.safe_stop()
|
|
```
|
|
|
|
### Level 2: 中层 (自己管 socket, 用编解码)
|
|
|
|
```python
|
|
from go1_pro_sdk import Blowfish, build_low_cmd_encrypted, parse_low_state, LowCmd
|
|
import socket
|
|
|
|
bf = Blowfish.from_state_file('go1_pro_sdk/_data/blowfish_state.bin')
|
|
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
|
|
sock.bind(('', 0))
|
|
|
|
cmd = LowCmd()
|
|
sock.sendto(build_low_cmd_encrypted(cmd, bf), ('192.168.123.10', 8007))
|
|
data, _ = sock.recvfrom(2048)
|
|
state = parse_low_state(bf.decrypt_ecb(data[:856]))
|
|
```
|
|
|
|
### Level 3: 底层 (诊断/逆向)
|
|
|
|
直接用 `Blowfish.encrypt_block(b8)` / `Blowfish.decrypt_block(b8)`, 自己处理 8B 块。
|
|
适合协议研究或字节级 diff。
|