linux_sentry_chassis/docs/architecture.md

架构设计

分层

              ┌─────────────────────────────────────────────┐
              │ 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。