Add MultiWheelS Simple scheduling plugin for fleet sync
Introduce the MultiWheelS (SimpleComposer host) plugin with the MultiVehicleCar definition so fleet auto-sync is driven via Simple dispatch instead of the hand-rolled AGV.FleetGo path. Simplify MultiWheelC.AGV to BasicInterface, drop the obsolete FleetGo helper and FleetStraightMovementTest, wire MultiWheelS into Tutorial.sln, and update RunAndDeploy docs plus add the MultiVehicleAutoSyncReview notes. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Cursor
@@ -0,0 +1,196 @@
|
||||
# 自动多车联动机制问题分析（MultiVehicleAutoSyncReview）
|
||||
|
||||
本文档记录 Tutorial `MultiWheelC` 中**自动运行多车联动**机制的潜在 bug 与工程化缺陷。
|
||||
**本次仅作分析归档，不包含代码修复。**
|
||||
|
||||
相关实现：
|
||||
|
||||
- [PilotDefinition.cs](../MultiWheel/MultiWheelC/PilotDefinition.cs) — 50ms `MultiVehicleLoop` / `TickMultiVehicle`
|
||||
- [ChassisController.cs](../MultiWheel/MultiWheelC/ChassisController.cs) — 路径跟踪 → `MultiVehicleAuto*` 回调
|
||||
- [VehicleSyncModels.cs](../MultiWheel/MultiWheelC/VehicleSyncModels.cs) — register/notify 数据模型
|
||||
- 算法背景见 [MultiVehicleSync.md](./MultiVehicleSync.md)
|
||||
|
||||
---
|
||||
|
||||
## 自动联动数据流
|
||||
|
||||
```text
|
||||
Simple 调度 MultiVehicleCar (MultiVehicleSync=true)
|
||||
→ 编译 agv.BasicGo(..., multiVehicleSync:true)
|
||||
→ BasicInterface 设置 _controller.MultiVehicleSync = true
|
||||
→ MultiWheelGeometricController.Track() 跟踪路径
|
||||
→ MultiVehicleSendMotion(speed, frontTh, rearTh, idealPos, idealAngle)
|
||||
→ PilotDefinition.MultiVehicleAutoVx/FrontTh/RearTh + AutoEnabled=true
|
||||
→ TickMultiVehicle (主车) 广播 notify → 从车跟 FleetVx/FrontTh/RearTh
|
||||
→ 各车 SetOriginBias(layout) + SendMotion + 检测/SLAM 补偿
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 问题清单
|
||||
|
||||
| ID | 严重度 | 问题摘要 | 定位 |
|
||||
|----|--------|----------|------|
|
||||
| A | 高 | 在会被重新赋值的 `MultiVehicleFleet` 字段上 `lock`，互斥失效 | PilotDefinition.cs ~185-205, 多处 lock |
|
||||
| B | 高 | 路径结束/回调早退时自动速度不清零，车队滑行 | PilotDefinition.cs 44-47, ChassisController.cs 46-57 |
|
||||
| C | 高 | 主车 fleet 表无 TTL，从车崩溃后仍认为编队就绪 | PilotDefinition.cs ~178-186, 505-508 |
|
||||
| D | 中 | 曲线路径广播单一 FrontTh/RearTh，丢弃 idealPos/idealAngle | PilotDefinition.cs 417-419,616; ChassisController.cs 46 |
|
||||
| E | 低 | ControlPointRadius 与 SendMotion localControlRadius 硬编码冲突 | PilotDefinition.cs 519, 616 |
|
||||
| F | 中 | notify 经 GET query 串 fire-and-forget，无背压/限频 | PilotDefinition.cs 846-854, 696-702 |
|
||||
| G | 中 | 车队中心 CenterX/Y/Th 跨线程非原子读写 | PilotDefinition.cs 348,434-436; ChassisController.cs 60-66 |
|
||||
| H | 中 | 关闭互识别时 SLAM 全程丢失不停车 | PilotDefinition.cs 485, 535 |
|
||||
|
||||
---
|
||||
|
||||
## A. lock 目标字段会被整体替换
|
||||
|
||||
**描述**
|
||||
`MultiVehicleFleet` 在 notify 处理中被整体重新赋值：
|
||||
|
||||
```csharp
|
||||
lock (MultiVehicleFleet)
|
||||
MultiVehicleFleet = notification.Fleet ?? new Dictionary<int, VehicleSyncInfo>();
|
||||
```
|
||||
|
||||
同时其它线程（register、Tick、VisualizeFleet）也在 `lock (MultiVehicleFleet)` 上同步。
|
||||
`lock` 的对象是**引用本身**；字段被赋新字典后，不同线程可能分别锁旧引用与新引用，**互斥语义失效**，存在 torn read / 丢更新风险。
|
||||
|
||||
**影响**
|
||||
高并发下 fleet 快照不一致、Aligned/fleetReady 判定抖动，极端情况下补偿或 notify 基于过期 fleet 状态运行。
|
||||
|
||||
**建议修复**
|
||||
- 使用 `private readonly object _multiVehicleFleetLock = new();` 作为唯一锁对象；或
|
||||
- 永不替换字典引用，改为 `Clear()` + 逐条 `Update`；或
|
||||
- 使用 `ConcurrentDictionary` + 不可变快照广播。
|
||||
|
||||
---
|
||||
|
||||
## B. 自动速度残留滑行
|
||||
|
||||
**描述**
|
||||
`MultiVehicleAutoVx / FrontTh / RearTh`（PilotDefinition 第 45-47 行）由 `ChassisController.MultiVehicleSendMotion` 写入。
|
||||
当路径跟踪结束、DriveTask 完成，或回调因 `MultiVehicleFleet.Count != FleetNum` 提前 return 时，**这些字段不会被清零**。
|
||||
|
||||
`MultiVehicleAutoEnabled` 带 `[AsUpperIO(timeOutReset = true)]`，在 IO 超时前主车仍认为自动模式开启，继续读取**最后一次非零速度**并广播给从车。
|
||||
|
||||
**影响**
|
||||
路径到达终点后车队仍按末速度滑行；与手动模式「松杆即停」行为不一致，存在 overshoot / 碰撞风险。
|
||||
|
||||
**建议修复**
|
||||
- `DriveTask` 完成或 `_controller` 置 null 时显式清零 `MultiVehicleAuto*` 并 `MultiVehicleAutoEnabled=false`；
|
||||
- 主车广播前检查速度命令新鲜度（时间戳 / 控制器活跃标志）；
|
||||
- 从车侧对 `FleetVx` 增加与 notify 相同的 freshness 超时（目前已有 notification 超时，但速度字段本身无独立 TTL）。
|
||||
|
||||
---
|
||||
|
||||
## C. 主车 fleet 成员无 TTL
|
||||
|
||||
**描述**
|
||||
从车通过 `/multi-vehicle-register` 上报，主车仅 `MultiVehicleFleet[CarNum] = info` 覆盖写入，**从不删除过期条目**。
|
||||
|
||||
`fleetReady = (fleetCount == MultiVehicleFleetNum)`（第 505-508 行）只检查数量，不检查从车是否仍在线。
|
||||
|
||||
**影响**
|
||||
从车进程崩溃或网络断开后，主车仍认为编队完整并继续 `SendMotion` + notify，存活车辆按过期 layout/DetectOk 运行，编队几何错误或未检测到邻车仍运动。
|
||||
|
||||
**建议修复**
|
||||
- `VehicleSyncInfo` 增加 `LastSeenUtc`；register/notify 收到时刷新；
|
||||
- 主车 Tick 剔除超过 N×SyncInterval 未更新的成员；
|
||||
- `fleetReady` 要求所有成员 `LastSeen` 新鲜。
|
||||
|
||||
---
|
||||
|
||||
## D. 曲线路径几何与 idealPos 丢弃
|
||||
|
||||
**描述**
|
||||
主车从 `MultiVehicleAutoFrontTh/RearTh` 广播单一 `(FrontTh, RearTh)`，各从车原样套用（第 417-419、616 行）。
|
||||
这对**平移、蟹行、绕共有旋转中心**近似成立，但对**一般曲线路径**，各车相对瞬时曲率中心位置不同，应使用不同舵角。
|
||||
|
||||
`MultiWheelGeometricController` 已计算 `idealPos / idealAngle` 并传入 `MultiVehicleSendMotion`，但 [ChassisController.cs](../MultiWheel/MultiWheelC/ChassisController.cs) 回调签名中**完全忽略**这两个参数，只转发 speed + frontTh + rearTh。
|
||||
|
||||
**影响**
|
||||
自动模式下走弧线/贝塞尔时，从车仅靠检测/SLAM 补偿「事后纠偏」，存在滞后与稳态横向误差（与原地旋转 PI 纠偏同类问题，但自动模式无专用 PI）。
|
||||
|
||||
**建议修复**
|
||||
- notify 增加 `FleetIdealX/Y/Th` 或 per-car layout 目标位姿；
|
||||
- 从车按 layout 目标做前馈 + 补偿，而非共用 frontTh/rearTh；
|
||||
- 或限制自动联动仅支持直线段（文档/配置门控）。
|
||||
|
||||
---
|
||||
|
||||
## E. 控制半径硬编码冲突
|
||||
|
||||
**描述**
|
||||
`chassis.SetOriginBias` 后设置 `ControlPointRadius = syncDistance / 2f`（第 519 行），但 `SendMotion` 传入 `localControlRadius: 510`（第 616 行）硬编码，覆盖几何含义。
|
||||
|
||||
**影响**
|
||||
编队间距配置变更时，实际控制点半径仍固定 510mm，补偿/转向几何与 `TestCarSyncDistance` 不一致，调参困难。
|
||||
|
||||
**建议修复**
|
||||
统一使用 `syncDistance / 2f` 或配置项 `MultiVehicleControlRadius`，删除 magic number 510。
|
||||
|
||||
---
|
||||
|
||||
## F. notify 传输层缺陷
|
||||
|
||||
**描述**
|
||||
主车每 50ms 对每台从车 `FireAndForgetNotify`：将完整 `VehicleSyncNotification`（含整队 `Fleet` 字典）JSON 序列化后嵌入 **GET query 字符串**（第 846-854 行），共享单个 `HttpClient`，无 await、无重试、无背压。
|
||||
|
||||
**影响**
|
||||
- 车队规模增大时 URL 超长（浏览器/服务器 query 上限）；
|
||||
- 从车处理慢时请求堆积；
|
||||
- 乱序到达时从车可能短暂应用旧 notification；
|
||||
- GET 语义不适合大 payload，且不利于缓存/安全审计。
|
||||
|
||||
**建议修复**
|
||||
- 改为 POST + JSON body；
|
||||
- 仅广播命令增量 + 各车 register 拉取全量；
|
||||
- 限频 / 合并同 tick 多次 notify；
|
||||
- 记录 notify 序列号供从车丢弃旧包。
|
||||
|
||||
---
|
||||
|
||||
## G. 车队中心跨线程 torn read
|
||||
|
||||
**描述**
|
||||
`MultiVehicleLoop`（后台线程）写入 `CenterX/Y/Th`（第 434-436 行）。
|
||||
路径控制器线程通过 `MultiVehicleGetFleetPos` 读取 `PilotDefinition.Self.CenterX/Y/Th`（ChassisController 第 60-66 行）。
|
||||
三个 `float` 字段无锁、无 `volatile`，可能读到「x 已更新、y/th 仍为旧值」的组合。
|
||||
|
||||
**影响**
|
||||
单帧路径跟踪使用错误车队中心，产生短暂错误 ideal 点 → 自动速度抖动。
|
||||
|
||||
**建议修复**
|
||||
- 用 `struct FleetCenter { float X,Y,Th; long Tick; }` 整体赋值/读取（或 lock 快照）；
|
||||
- 控制器只读上一完整快照。
|
||||
|
||||
---
|
||||
|
||||
## H. 关闭互识别时 SLAM 丢失不停车
|
||||
|
||||
**描述**
|
||||
`canMove = !MultiVehicleUseDetect || (ownDetectOk && othersDetectOk)`（第 485 行）。
|
||||
当 `MultiVehicleUseDetect=false` 时 `canMove` **恒为 true**，即使 Detour 丢失、`TryInferFleetCenter` 失败，仍执行 `SendMotion`（仅 pos 补偿分支跳过）。
|
||||
|
||||
**影响**
|
||||
纯 SLAM 自动模式下定位全丢后，车队仍按最后 broadcast 速度运动，无 detect 安全网。
|
||||
|
||||
**建议修复**
|
||||
- 自动模式额外要求 `posAvailable && TryInferFleetCenter` 或 notify `PosAvailable`；
|
||||
- 与手动模式区分：手动可仅靠 detect，自动必须有有效 fleet 中心。
|
||||
|
||||
---
|
||||
|
||||
## 优先级建议（若后续修复）
|
||||
|
||||
1. **P0**：A（锁）、B（停车）、C（TTL）— 直接关系安全停车与状态一致
|
||||
2. **P1**：G（中心快照）、H（SLAM 门控）、F（notify 传输）— 稳定性与可扩展
|
||||
3. **P2**：D（曲线几何）、E（半径统一）— 精度与可维护性
|
||||
|
||||
---
|
||||
|
||||
## 修订记录
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-06-28 | 初版：基于 Tutorial MultiWheelC 自动联动实现与联调日志分析整理 |
|
||||
+18
-3
@@ -28,13 +28,22 @@ dotnet build Tutorial.sln
|
||||
|
||||
- M 插件 → `build\Medulla\plugins\`
|
||||
- C 插件 → `build\Clumsy\` 与 `build\Clumsy_AGV2\`（PostBuild 复制运行时）
|
||||
- S 插件 → `build\Simple\plugins\`（PostBuild 复制 SimpleComposer 宿主到 `build\Simple\`）
|
||||
|
||||
MultiWheelS 为旧式 net48 项目，需用 MSBuild 单独编译：
|
||||
|
||||
```powershell
|
||||
msbuild D:\MDCS\Source\Tutorial\MultiWheel\MultiWheelS\MultiWheelS.csproj /p:Configuration=Debug
|
||||
```
|
||||
|
||||
或在 Visual Studio 中打开 `Tutorial.sln` 编译 `MultiWheelS` 项目。
|
||||
|
||||
## 3. 目录结构
|
||||
|
||||
```text
|
||||
Tutorial/
|
||||
DiffWheel/DiffWheelM/ DiffWheel/DiffWheelC/
|
||||
MultiWheel/MultiWheelM/ MultiWheel/MultiWheelC/
|
||||
MultiWheel/MultiWheelM/ MultiWheel/MultiWheelC/ MultiWheel/MultiWheelS/
|
||||
deploy/ # 配置模板（入库）
|
||||
build/ # 运行目录（gitignore）
|
||||
```
|
||||
@@ -69,7 +78,13 @@ Tutorial/
|
||||
|
||||
1. 完成上一节双车启动
|
||||
2. 至少一台车 `PosAvailable=true`（Detour 定位有效）
|
||||
3. 主车 Clumsy 触发自动联动或调度 `AGV.FleetGo(..., multiVehicleSync:true)`
|
||||
3. 通过 Simple 调度触发自动联动（推荐）：
|
||||
- 编译 `MultiWheelS`（见第 2 节），确认 `build\Simple\plugins\MultiWheelS.dll` 存在
|
||||
- 在 `build\Simple\` 运行 `SimpleComposer.exe`（自动加载 `./plugins`）
|
||||
- 添加车型 **「多车联动AGV」**（`MultiVehicleCar`，`MultiVehicleSync=true`）
|
||||
- 主车设置 `cport:8008`、从车 `cport:8009`（可用 `SetCPort` 或 `conf` 字段）
|
||||
- 在该车上规划路径 → 编译为 `agv.BasicGo(..., multiVehicleSync:true)` → 主车 `ChassisController` 开启 `MultiVehicleAutoEnabled`，`PilotDefinition` 50ms 循环广播并驱动车队
|
||||
4. 自动联动机制已知问题见 [MultiVehicleAutoSyncReview.md](./MultiVehicleAutoSyncReview.md)
|
||||
|
||||
## 7. 差速示例
|
||||
|
||||
@@ -85,4 +100,4 @@ Tutorial/
|
||||
| `chassis.json` | 四轮舵轮几何 |
|
||||
| `startup.iocmd` | `SetShareObjectTag Multi1/Multi2` |
|
||||
|
||||
详细算法见 [MultiVehicleSync.md](./MultiVehicleSync.md)，修复清单见 [BugFixes.md](./BugFixes.md)。
|
||||
详细算法见 [MultiVehicleSync.md](./MultiVehicleSync.md)，修复清单见 [BugFixes.md](./BugFixes.md)，自动联动机制问题分析见 [MultiVehicleAutoSyncReview.md](./MultiVehicleAutoSyncReview.md)。
|
||||
|
||||
Reference in New Issue
Block a user