feat: 初始化

2026-09-22 20:05:16 +08:00
commit 7d87987e41
54 changed files with 6446 additions and 0 deletions
@@ -0,0 +1,77 @@
+# 架构设计
+
+## 分层
+
+```
+              ┌─────────────────────────────────────────────┐
+              │ chassisd（守护进程）                          │
+              │  配置 / CLI / 1kHz 控制循环 / 安全逻辑 / 日志   │
+              └──────┬───────────────────────────┬──────────┘
+                     │ mecanum（麦轮正逆解）        │
+                     ▼                           ▼
+              ┌────────────┐             ┌──────────────────┐
+              │ motor-core │◄─实现 trait──│ dji-esc          │
+              │ Motor trait│             │ C620/C610 协议     │
+              │ MotorState │             │ EscBus 异步驱动    │
+              │ Pid        │             │ TurnTracker 多圈  │
+              └────────────┘             └────────┬─────────┘
+                                                  │ CanLink（tokio mpsc 通道对）
+                                                  ▼
+                                    ┌──────────────────────────┐
+                                    │ dji-esc-socketcan(Linux) │
+                                    │ socketcan ↔ CanLink 桥接  │
+                                    └──────────────────────────┘
+```
+
+核心解耦点：`CanLink` 是一对 tokio 通道（发送 / 接收 `CanFrame`）。`dji-esc` 的协议状态机
+只面向通道工作，因此：
+
+- 测试中用内存通道 + 一阶电机模型（`dji_esc::sim`）构成闭环仿真，全平台可跑；
+- `dji-esc-socketcan` 把真实 SocketCAN 接口桥接到通道，只在实车上出现；
+- 未来更换总线介质（串口转 CAN、MCU 转发）只需新增一个桥接 crate。
+
+## DJI 电调 CAN 协议要点（C620 手册）
+
+| 项目 | 值 |
+| --- | --- |
+| 控制帧 ID | `0x200`（电调 1–4）、`0x1FF`（电调 5–8） |
+| 控制帧格式 | 8 字节 = 4 × i16 大端电流命令，按电调 ID 顺序 |
+| C620 电流标度 | ±16384 ↔ ±20 A |
+| C610 电流标度 | ±10000 ↔ ±10 A（M2006 组合，接硬件前需核对） |
+| 反馈帧 ID | `0x200 + 电调ID`（`0x201`–`0x208`） |
+| 反馈帧格式 | u16 角度(0..8191) + i16 转速rpm + i16 转矩电流 + i8 温度℃，均大端 |
+| 反馈频率 | 每电调 1kHz |
+
+C620 内部**只闭电流环**：转速 / 位置环由主控侧 PID 实现（`motor-core::Pid`，
+挂在 `EscBus` 的 1kHz 发送节拍上）。GM3508 减速比 3591 / 187 ≈ 19.203。
+
+## 单位与方向约定
+
+- 机器人坐标系：ISO 约定——x 前、y 左、ω 逆时针为正（见 `mecanum`）。
+- `Motor` 接口呈现的是**物理量**（安装方向修正后）：
+  `EscConfig::direction = -1` 时，驱动层在写命令与读反馈时统一翻转符号，
+  上层永远以"轮子正转 = 底盘前进方向"的正向工作。
+- `MotorState::rotor_speed_rpm` 为电机转子转速；轮端转速 = 转子转速 / 减速比。
+- 电流一律以协议原始值（raw）为主，安培换算通过 `EscModel` 常量提供。
+
+## 安全设计
+
+1. **上电门控**：底盘循环在收到任一电机首帧反馈前不下发速度命令。
+2. **反馈离线**：任一电机反馈超时（默认 100ms）→ 该电机命令强制 0 电流并告警。
+3. **命令超时**：上层 twist 命令超时（默认 200ms）→ 目标速度归零。
+4. 所有超时可经 `chassis.toml` 配置。
+
+## 测试策略
+
+| 层级 | 内容 | 平台 |
+| --- | --- | --- |
+| 单元测试 | 帧编解码字节级样例 / 饱和、多圈回绕、PID（阶跃、抗饱和、滤波）、运动学解析解 + 属性测试 | 全平台 |
+| 闭环仿真 | 内存通道 + 一阶电机模型：4 电机速度环收敛、群帧组装、离线安全、守护进程全链路 | 全平台 |
+| vcan 集成 | vcan0 双 socket 收发，真实内核 CAN 栈 | Linux（`#[ignore]`，CI 显式跑） |
+| 交叉检查 | `aarch64-unknown-linux-gnu` 全 workspace check | CI |
+
+## 部署
+
+`chassisd` 为单二进制守护进程：`--interface can0 --config /etc/chassisd/chassis.toml`。
+systemd 样例见 `deploy/chassisd.service`。板端接口就绪依赖：
+USB 转 CAN（gs_usb / candleLight）或 SPI CAN HAT（MCP2515）驱动加载后的 `can0`。