171 lines
6.9 KiB
Markdown
171 lines
6.9 KiB
Markdown
# 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
|
||
|
||
```text
|
||
基础
|
||
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`](config/dependency-policy.toml) 和
|
||
[`docs/dependencies.md`](docs/dependencies.md)。`just audit` 同时检查层 rank、正常/dev 依赖、
|
||
外部库职责和 trait 边界；正常与 dev 依赖都必须单向。
|
||
|
||
主要边如下：
|
||
|
||
```text
|
||
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 仅包含：
|
||
|
||
```text
|
||
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` 确认禁止边不存在、依赖图无环。
|