init pro_sdk

2026-06-20 20:02:36 +08:00
commit 5ecd422a59
49 changed files with 4226 additions and 0 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,142 @@
+# 包结构与数据流
+
+## 模块依赖图
+
+```
+                ┌──────────────────────┐
+                │  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。