RoboMaster 底盘职责型架构

版本: 2.0 平台: Allwinner T153 / Linux 底盘控制频率: 1 kHz 实现范围: 四轮麦轮底盘；云台与发射机构尚未实现

本文是架构的唯一规范。docs/chassis.md 只记录接线、标定、部署与排障。

1. 架构原则

一个 crate 一件事：协议、传输、设备运行时、算法、仿真、工具和应用入口分别成 crate。
依赖必须无环：允许依赖同层或更低抽象，但禁止反向控制依赖和隐藏的完整链路打包。
std，禁止 unsafe：workspace 使用 unsafe_code = "forbid"；允许使用提供安全 API 的第三方依赖。
实时调度交给 systemd：进程不调用 libc FFI，不实现 SCHED_FIFO 或 mlockall。
二级语义分层：crate 名不变，manifest 按 crates/<layer>/<domain> 组织；依赖只能由高层指向低层。
crate 内保持扁平：只允许 Cargo 惯例目录 src、tests；src 内不建立模块子目录。
安全边界独立于控制律：总线负责反馈新鲜度、命令租约和零电流；控制器通过策略接口组合。

2. Workspace

基础
  can                 CAN 帧、CanBus、CanLink、MockBus
  imu                 IMU 数据契约

协议
  motor-protocol      C620/C610、GM6020 编解码、多圈与 ID
  delta10-protocol    DETA10 帧布局与解码
  dr16-protocol       DJI DR16 D-BUS 帧布局与解码

驱动
  socketcan           Linux SocketCAN ↔ CanLink
  slcan               Lawicel 串口 CAN ↔ CanLink
  delta10             DETA10 IMU 驱动
  dr16                DR16 D-BUS 串口接收驱动

设备与运行时
  motor               Motor 能力 trait、状态、命令、减速比、注册表、EffortPolicy
  esc-bus             ESC 帧泵、反馈状态、租约、离线保护、effort 输出

控制
  pid                 通用 PID
  motor-control       速度/位置/串级/前馈与 MotorPolicy
  mecanum             麦轮正逆运动学

实验与仿真
  motor-model         DC/GM3508 物理模型
  experiment          Scenario、Trace、Window、StepMetrics
  sim-harness         同步闭环、总线损伤、域随机化、假电调
  tuning              Relay/ZN、成本、增益空间、搜索、预设

应用
  chassis-config      chassis.toml schema 与校验
  bench               真机链路门面、安全包络、试验采样
  chassisd            底盘守护进程二进制
  spin                chassis / motor 台架二进制
  chassis-tune        自动整定二进制与报告/绘图适配

验证
  integration-tests   跨层闭环、语义一致性与 vcan 集成测试

共 24 个 crate（含顶层 verification/integration 集成测试包）。crate 名不使用 rm- 等无领域含义的统一前缀。

3. 允许依赖

机器可读规则见 config/dependency-policy.toml 和 docs/dependencies.md。just audit 同时检查层 rank、正常/dev 依赖、外部库职责和 trait 边界；正常与 dev 依赖都必须单向。

主要边如下：

motor-protocol   -> can
delta10-protocol -> can, imu
dr16-protocol    -> (无内部依赖)
socketcan        -> can
slcan            -> can
delta10          -> can, imu, delta10-protocol
dr16             -> dr16-protocol

motor            -> can, motor-protocol
esc-bus          -> can, motor, motor-protocol

pid              -> (无内部依赖)
motor-control    -> pid, motor
mecanum          -> (无内部依赖)

motor-model      -> motor-protocol
sim-harness      -> can, motor, motor-control, motor-model, motor-protocol, experiment
tuning           -> pid, motor-control, motor-model, sim-harness, experiment

chassis-config   -> esc-bus, motor-control, motor-protocol, mecanum
bench            -> can, esc-bus, experiment, motor, motor-control, socketcan, slcan

chassisd         -> chassis-config, dr16, esc-bus, mecanum, motor-control, sim-harness, socketcan
spin             -> bench, dr16, esc-bus, motor-control, socketcan, slcan
chassis-tune     -> bench, chassis-config, experiment, sim-harness, tuning

禁止边：

esc-bus -> motor-control / pid：esc-bus 不包含控制律。
bench -> tuning：真机试验只产生 TrialOutcome；成本和搜索适配在 chassis-tune。
sim-harness -> tuning：仿真只产生模型与轨迹；搜索器不反向渗入仿真。
协议或驱动依赖设备、控制、仿真、整定或应用 crate。

motor::EffortPolicy 是控制与总线的唯一组合点。motor-control::MotorPolicy 实现该 trait，应用负责把它传给 esc_bus::EscBus::spawn。

4. 运行模型

底盘速度环和 ESC 命令节拍为 1 kHz。
esc-bus 每拍读取命令租约和反馈新鲜度，再调用 EffortPolicy。
反馈超时或命令租约到期时强制零输出；策略状态会被复位。
上层必须逐拍重发目标值；一次性命令会在默认 50 ms 后失效。
chassisd 将麦轮逆解得到的轮端速度经 OutputShaft 换算到转子速度。

5. std 与实时策略

Rust 代码只使用 std 与安全第三方 API，workspace 设置 unsafe_code = "forbid"。
不依赖 libc，不包含 FFI、no_std 分支或 realtime 模块。
deploy/chassisd.service 通过 CPUSchedulingPolicy=fifo、 CPUSchedulingPriority=80、LimitRTPRIO=95 设置调度策略。
LimitMEMLOCK=infinity 只提高锁定额度；std 程序不调用 mlockall，本文不承诺主动锁页。
不支持的平台由 socketcan 返回明确错误；核心算法与仿真可跨平台测试。

6. 目录规则

每个 crate 仅包含：

Cargo.toml
src/lib.rs       # 库
src/main.rs      # 二进制
tests/*.rs       # 可选集成测试

不允许 src/<module>/ 子目录。单元测试使用源码文件内的 #[cfg(test)] mod tests。

7. 当前实现边界

已实现：

C620/C610 电流协议、GM6020 电压协议骨架、多圈跟踪与 ID 校验。
SocketCAN、SLCAN、DETA10 驱动骨架、MockBus。
四轮 ESC 总线、命令租约、反馈离线保护、外部控制策略。
PID、速度/位置/串级/前馈、麦轮运动学。
电机模型、总线损伤、同步/异步闭环、参数搜索、预设与报告。
chassisd --mock、spin chassis|motor|rc、chassis-tune。
DR16/D-BUS 遥控输入、S1 使能、断流失能和 500 ms 速度斜坡。

未实现：

云台与发射机构任务和控制律。
DETA10 真实载荷布局（决策点 D1，原手册链接失效）。
GM6020 实车闭环。
E907 异构核（决策点 D4）。
进程内 mlockall。

8. 验收

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --all-targets
Linux vcan：cargo test -p socketcan@0.1.0 --test vcan -- --ignored --test-threads 1
find crates/*/src -mindepth 2 -type d 无输出。
Rust 源码不得包含 unsafe、libc 或 no_std。
cargo tree 确认禁止边不存在、依赖图无环。

6.9 KiB Raw Permalink Blame History Unescape Escape