MDCS wiki2 - 用户贡献 [zh-cn]

核心开发指南

2026-05-16T14:00:53Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
本页是 MDCS '''核心平台开发'''的总入口，面向 ''修改 MDCS 本身''的开发者（添加新的 SLAM 后端、扩展 LadderLogic、修改 DPS 调度算法等）。完整离线副本见 `D:\src\cookbook\HOW_TO_DEV_CORE.md`。

This is the hub for '''MDCS core platform development''' — for developers ''modifying MDCS itself'' (adding a new SLAM backend, extending LadderLogic, modifying DPS scheduling, etc.). Offline mirror: `D:\src\cookbook\HOW_TO_DEV_CORE.md`.

== 1. 仓库布局 / Repo layout ==
7 个并列仓库，按依赖自底向上构建：
7 sibling repositories, built bottom-up by dependency:

{| class="wikitable"
! 仓库 / Repo !! 产物 / Output !! 作用 / Role
|-
| `D:\src\Fundamentals\` || `FundamentalLib.dll`, `FundamentalLib2.dll`, `LessokajiProtect.dll` || 通用类型 + IPC + 日志 + 许可
|-
| `D:\src\LessokajiWeaver\` || `LessokajiWeaver.Fody.dll` || 编译期 IL 注入
|-
| `D:\src\CycleGUI\` || `CycleGUI.dll`, `libVRender.dll`（C++）|| 懒协程 UI 框架
|-
| `D:\src\M2\` || `MedullaCore.dll`, `OfficialPlugins/*.dll` || 硬件抽象内核 + 一方插件
|-
| `D:\src\Detour\` || `Detour.exe`, `DetourLite.exe`, `DetourCore.dll` || 定位系统
|-
| `D:\src\Clumsy\` || `ClumsyCore.dll`, `ClumsyDance.dll` || 车载自动驾驶
|-
| `D:\src\Simple\` || `SimpleCore.dll`, `SimpleComposer.exe` || 车队管理
|}

详细的内核子页：
Per-subsystem deep-dive pages:

* [[Special:MyLanguage/MDCS仓库布局与构建链|MDCS仓库布局与构建链]]
* [[Special:MyLanguage/DObject共享内存协议|DObject共享内存协议]] — Fundamentals 内核
* [[Special:MyLanguage/CycleGUI|CycleGUI]] — UI 框架
* [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]] — 加载器 + 脚本引擎
* [[Special:MyLanguage/LadderLogic框架|LadderLogic框架]] — 周期循环
* [[Special:MyLanguage/Detour软件架构|Detour软件架构]] — 定位流水线
* [[Special:MyLanguage/DriveTask调度循环|DriveTask调度循环]] — Movement 宿主
* [[Special:MyLanguage/SimpleAgvInterface Queue机制|SimpleAgvInterface Queue机制]] — 任务流水线
* [[Special:MyLanguage/Simple软件架构|Simple软件架构]] — 调度内核
* [[Special:MyLanguage/调度内核运行原理|调度内核运行原理]] — DPS + 包络 + 可达性
* [[Special:MyLanguage/DPS调度算法详解|DPS调度算法详解]] — 死锁规避算法
* [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]] — Fody 织入
* [[Special:MyLanguage/MDCS跨切面约定|MDCS跨切面约定]] — 命名 / 线程 / 错误处理 / 版本
* [[Special:MyLanguage/MDCS平台发布流程|MDCS平台发布流程]] — Release 流程

== 2. 构建工具链 / Build chain ==
=== 顺序 / Order ===
1. LessokajiWeaver — 构建时依赖 / build-time dep
2. Fundamentals — 用 Weaver / uses Weaver
3. CycleGUI — 用 Fundamentals + 需要 `libVRender` C++ 先构建
4. M2 / MedullaCore — 用 Fundamentals + CycleGUI
5. M2 / OfficialPlugins/* — 用 MedullaCore
6. Detour / DetourCore
7. Clumsy / ClumsyCore，然后 ClumsyDance
8. Simple / SimpleCore，然后 SimpleComposer

=== 引用程序集分发 / Reference-assembly distribution ===
每个核心 DLL 都同时产生一个 ''引用程序集''（`Ref<Name>.dll`），通过 [refasmer](https://github.com/JetBrains/Refasmer) 生成。插件 csproj 引用 `Ref<Name>.dll`，不引用 impl，所以：
Each core DLL also emits a '''reference-only assembly''' (`Ref<Name>.dll`) via [refasmer]. Plugins reference the `Ref` assembly, not the impl. Therefore:

* 插件构建不会拉入 Costura 织入的传递依赖。
* 公共 API 由 `Ref` assembly 固定 —— `internal` 成员对插件不可见。

【注意】改动 `MedullaCore` 公共面后必须重新构建 impl + ref；插件用旧 `Ref` 构建后会静默缺失新成员。 
After any change to a `MedullaCore` public surface, rebuild both impl and ref assemblies; plugins built against the old ref will silently miss new members.

=== Costura.Fody 胖 DLL ===
插件输出是单 `.dll`（所有依赖嵌入为 base64 资源）。核心 DLL 自身 ''不要''加 Costura.Fody，因为多个插件都要共载它们。

Plugin outputs are fat DLLs (all deps embedded). Core DLLs themselves '''should not''' use Costura.Fody since multiple plugins co-load them.

=== LessokajiWeaver IL 注入 ===
* `[AsInitParam] / [AsUpperIO] / [AsLowerIO]` → 字段重写为同步到 DObject 的 property
* `[ReplaceWithCompileInfo]` → 编译时戳 + git 哈希
* `[Translatable] / [T(zh=, en=)]` → getter 按 `CultureInfo.CurrentUICulture` 分派

详见 [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]] 与 [[Special:MyLanguage/如何使用LessokajiWeaver的多语言功能|如何使用LessokajiWeaver的多语言功能]]。

== 3. 跨切面约定 / Cross-cutting conventions ==
=== 命名 / Naming ===
* 插件入口类: `MainIOObject`（精确匹配）。
* 引用程序集: `Ref<Name>.dll`。
* DObject 槽名: `<Producer><Tag>`（如 `MedullaCartLowerIO<tag>`）。

=== 线程 / Threading ===
* `LadderLogic` 每个 `[UseLadderLogic]` 类自己的线程。
* `DriveTask` 每个 Movement 自己的线程。
* DObject `Wait()` 阻塞；要并行多个就用 worker 线程。
* CycleGUI `Draw*` 调用从任意线程都安全。

=== 错误处理三层 / 3-layer error model ===
# 插件级 `[UseLadderLogic(resume=true)]` —— 捕获并重启循环（默认）。
# 进程级 `Hedingben.ToastText` —— UI 弹窗。
# 看门狗级（Wawa）—— 进程崩了由 Wawa 重启。

不要同时做三层；选合适的级别。 
Don't do all three — pick the right level.

=== 版本助记词 / Version mnemonics ===
每次修改编译产物，AssemblyInformationalVersion 加一个单词（如 `1.4.0+kindling`）。便于在调试时区分两个数字相同的二进制。

Each modification adds a single mnemonic word (e.g. `1.4.0+kindling`) to AssemblyInformationalVersion. Lets you disambiguate two binaries with the same number in the field.

== 4. 测试 / Tests ==
* 单元测试稀疏；机器人代码本质上靠 ''集成测试''。
* `D:\src\Fundamentals\Test\` 覆盖 DObject + DLog（最关键）。
* 多数"测试"通过 `[MovementTest]` / `[IOObjectUtility]` 在 UI 上点按钮跑。
* 修改 `DObject` 后必跑 Fundamentals 单元测试 —— IPC bug 是灾难性的。
* 修改任一 `*Core` 后跑模拟车 SimpleComposer 集成测试。

== 5. 发布 / Release ==
见 [[Special:MyLanguage/MDCS平台发布流程|MDCS平台发布流程]]。

== 6. 关联文档 / See also ==
* [[Special:MyLanguage/操作指南|操作指南]] — 运维者视角
* [[Special:MyLanguage/插件开发指南|插件开发指南]] — 插件作者视角
* [[Special:MyLanguage/车体抽象原理|车体抽象原理]] — 三层模型

[[Category:开发手册]]
[[Category:二次开发相关说明]]

操作指南

2026-05-16T14:00:52Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
本页是 MDCS '''运维与使用''' 的总入口，面向集成商 / 现场工程师 / 操作员。它把现有的使用手册按 ''从部署到日常运维''的顺序串联起来。完整的离线副本见 `D:\src\cookbook\HOW_TO_USE.md`。

This is the hub for MDCS '''operations and usage''', for integrators / commissioning engineers / operators. It stitches the existing usage manuals into a deploy-to-daily-ops sequence. The offline mirror lives at `D:\src\cookbook\HOW_TO_USE.md`.

== 1. 系统组件 / System anatomy ==
MDCS 在生产现场是 4 个进程协同工作：
MDCS is 4 cooperating processes on a production site:

* '''Medulla''' — 硬件抽象层 + 插件加载器 / hardware-abstraction layer + plugin loader (`D:\src\M2`)
* '''Detour''' — 定位系统 / positioning system (`D:\src\Detour`)
* '''Clumsy''' — 车载自动驾驶 / on-vehicle autopilot (`D:\src\Clumsy`)
* '''SimpleComposer''' — 车队 UI + 调度 / fleet UI + scheduler (`D:\src\Simple\SimpleComposer`)

进程间通过共享内存（[[Special:MyLanguage/DObject共享内存协议|DObject]]）通讯。详细分层见 [[Special:MyLanguage/车体抽象原理|车体抽象原理]]。

The processes communicate via shared memory ([[Special:MyLanguage/DObject共享内存协议|DObject]]). Layered details: [[Special:MyLanguage/车体抽象原理|vehicle abstraction]].

== 2. 部署流程 / Deployment ==
按顺序：
In order:

# 硬件清单与选型 / Hardware checklist & selection — [[Special:MyLanguage/激光雷达选型测试报告|激光雷达选型测试报告]], `wiki/MDCS-Walkthrough`
# Detour 部署 / Install Detour — [[Special:MyLanguage/下载并部署Detour|下载并部署Detour]], [[Special:MyLanguage/安装Detour|安装Detour]]
# 完整 MDCS 部署 / Full MDCS deployment — [[Special:MyLanguage/使用手册 - MDCS软件部署方法介绍|MDCS软件部署方法介绍]], [[Special:MyLanguage/使用手册 - Linux MDCS部署配置和操作说明|Linux MDCS部署配置和操作说明]]
# 许可激活 / Licensing — 经 `auth.lessokaji.com` 申请机器绑定 license / via `auth.lessokaji.com` for machine-bound license
# 网络拓扑 / Network topology — 默认端口 Medulla 8081 / Detour WebUI / Clumsy 30080 / SimpleComposer Nancy 9050+

== 3. 站点初始化 / Site bring-up ==
# 车体几何 layout JSON 配置 — `LayoutDefinition.CartLayout` at `D:\src\Detour\DetourCore\CartDefinition\LayoutDefinition.cs:79`
# 标定（顺序敏感）/ Calibration (order matters):
#* 轮径 + 轮距 / Wheel diameter + track — [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]
#* 激光雷达水平度 / Lidar horizontality — [[Special:MyLanguage/标定与校准|标定与校准]]
#* 激光雷达外参 / Lidar extrinsics — [[Special:MyLanguage/标定激光雷达外参|标定激光雷达外参]]
#* 双雷达外参 / Dual-lidar extrinsics — [[Special:MyLanguage/使用手册 - 双雷达标定手册|使用手册 - 双雷达标定手册]]
# SLAM 建图 + 编辑 / SLAM mapping + edit — [[Special:MyLanguage/激光SLAM建图|激光SLAM建图]], [[Special:MyLanguage/激光地图编辑指南|激光地图编辑指南]]
# SimpleComposer 场景搭建 / Scene authoring — [[Special:MyLanguage/开发手册 - SimpleComposer界面开发 - CAD工具|CAD工具]]
# 试运行 / Test drive — 手动 + 自动 / manual + automated

== 4. 任务下发 / Mission dispatch ==
3 个入口：
3 surfaces:

* SimpleComposer UI ("Send car to site", "Run mission template")
* Nancy HTTP API (`POST /api/dispatch`)
* WMS 集成 / WMS integration — 见 [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|如何基于SimpleCore核心库进行调度系统开发]]

任务编译流程 / Mission compilation: 业务 → `SegmentPlan` → TopazScript → 车载 ClumsyCar / 自评估车。详见 [[Special:MyLanguage/AGV任务运行逻辑|AGV任务运行逻辑]]。

== 5. 标定速查 / Calibration cookbook ==
{| class="wikitable"
! 步骤 / Step !! 文档 / Doc !! 允许误差 / Tolerance
|-
| 轮径 + 轮距 || [[Special:MyLanguage/MDCS引擎适配机器人入门教学|引擎适配教学]] || ≤ 2% drift / 5 m
|-
| 激光雷达水平 || [[Special:MyLanguage/标定与校准|标定与校准]] || ≤ 0.3°
|-
| 激光雷达外参 || [[Special:MyLanguage/标定激光雷达外参|标定激光雷达外参]] || ≤ 5 mm / 0.2°
|-
| SLAM 地图 || [[Special:MyLanguage/激光SLAM建图|激光SLAM建图]] || ≤ ±50 mm / ±2°
|-
| 二维码（纯模式）|| [[Special:MyLanguage/纯二维码导航|纯二维码导航]] || ≤ ±5 mm / ±0.2°
|}

== 6. 监控与诊断 / Monitoring & diagnostics ==
* SimpleComposer 主画布：车辆状态颜色（绿/蓝/黄/红）+ 锁占用 + Trace 面板。
* DLog：结构化日志 `logs/<YYYY-MM-DD>.log`，主题 `$lidar`, `$slam`, `$dobject`, `$watchdog` 等。
* Hedingben (Wawa)：toast 通知 / toast notifications — [[Special:MyLanguage/看门狗Wawa使用说明|看门狗Wawa使用说明]]
* 录制与回放 / Recording & replay — [[Special:MyLanguage/使用手册 - 数据录制与回放手册|数据录制与回放手册]]

== 7. 常见运维流程 / Common procedures ==
* 添加车辆到现网 / Add a vehicle — 完整流程见 HOW_TO_USE.md §6.1
* 不停机更新插件 / Hot-swap plugin — 车辆 "暂停服务" → 推送 DLL → 重启 Medulla → "重新服务" / take out of service → push DLL → restart Medulla → return
* 地图增量更新 / Map incremental update — 推荐人工审批模式 / manual-approval mode recommended
* 锁恢复 / Lock recovery — Trace 面板定位卡死 + 手动释放（管理员）/ Trace panel + manual release

详见 HOW_TO_USE.md §6 与 [[Special:MyLanguage/使用手册 - 车队管控|使用手册 - 车队管控]]。

== 8. 灾难恢复 / Disaster recovery ==
* SimpleComposer 场景 JSON 文件 / scene JSON — 每晚备份
* SLAM 地图（`*.2dlm` / `*.gtex` / `*.memslam` / `tagmap.json`）— 每次编辑后备份
* 单车 IPC 替换流程 / Per-vehicle IPC restore — 详见 HOW_TO_USE.md §8.4
* 重新激活 license — 通过 `auth.lessokaji.com`

== 9. 关联文档 / See also ==
* [[Special:MyLanguage/插件开发指南|插件开发指南]] — 插件作者视角
* [[Special:MyLanguage/核心开发指南|核心开发指南]] — 平台开发者视角
* [[Special:MyLanguage/MDCS-Walkthrough|MDCS-Walkthrough]] — 整体概述
* [[Special:MyLanguage/车体抽象原理|车体抽象原理]] — 三层模型

[[Category:使用手册]]

插件测试与发布

2026-05-16T14:00:50Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
本页讲 MDCS 插件的 ''测试 + 打包 + 发布''流程 —— 从 bench-test 单个插件，到把插件做成可分发的版本。

This page covers MDCS plugin ''testing + packaging + release'' — from bench-testing a single plugin to packaging a deliverable version.

== 1. Bench-test Medulla 插件 ==
=== 控制台测试 / Console testing ===
启动 Medulla 控制台后，可以直接 [[Special:MyLanguage/startup.iocmd脚本语法|startup.iocmd]] 命令：
After starting the Medulla console, use script commands:

<syntaxhighlight lang="text">
io load plugins/yourname.dll
your = io init <TypeName> <args>

# 读字段 / read field
your.<field>

# 写字段 / write field
your.<field> = 100

# 调方法 / invoke a [IOObjectUtility]
your <UtilityMethod>
</syntaxhighlight>

=== 雷达插件可视化 / Lidar visualisation ===
Medulla 的 `LidarTypes/MainIOObject` 暴露一个 `[IOObjectUtility]` 用于显示 2D 点云。加载完雷达后点这个按钮：
* 确认 `frame` 单调递增。
* 点云形状符合预期（前方、左右、距离合理）。
* 反光强度归一化后（`ReflexRange`）反光板明显偏红。

Lidar plugin: confirm `frame` increments monotonically, geometry matches expectation, reflectors visibly red after `ReflexRange` normalisation.

=== Cart 插件验证 / Cart plugin validation ===
{| class="wikitable"
! 检查 / Check !! 方法 / Method
|-
| `Init()` 不抛 || 看 `Hedingben` 是否有红色 toast
|-
| LadderLogic 启动 || `[IOObjectMonitor]` 看一个 ''iteration 计数器''
|-
| `[AsUpperIO]` 设置生效 || `your.vCmd = 100`，观察硬件电机
|-
| `[AsLowerIO]` 读取正常 || `your.batteryPercent` 应给真实值
|-
| `[UseLadderLogic(resume=true)]` 验证 || 故意制造异常，看是否自动重启循环 + Hedingben toast
|}

== 2. Bench-test Movement ==
`[MovementTest]` 属性在 Clumsy 测试 UI 自动注册一个按钮。要求：
* 车在静止 / 仿真环境中
* 没有 ''任何''其它 Movement 在跑

`[MovementTest]` registers a button automatically. Requires the vehicle to be still / simulated, with no other Movement running.

按下按钮 → Movement 开始；UI 实时显示驱动指令；异常时显示 stack trace。
Pressing the button starts the Movement; UI shows live drive commands; exception → stack trace surfaced.

== 3. Bench-test SimpleComposer 插件 ==
=== 仿真车 / Virtual vehicle ===
SimpleComposer 内置 ''仿真车''类型（不需要真硬件）：
* 添加 `DummyCar`，配置你的 `[CarType]` 关联。
* 发派任务从 UI 派；运动学按理想模型计算。

A built-in virtual car type lets you test without real hardware. Configure a `DummyCar` bound to your `[CarType]`; missions dispatched from the UI; kinematics calculated ideally.

=== Trace 面板 / Trace panel ===
观察：
* 每辆车的 `Queue` 行执行时间线
* 锁的获取 / 释放序列
* 任务 status 状态转换（`Programming → Forecasted → Queued → Running → Finished`）
* 异常路径

Inspect: per-car Queue row timeline, lock acquire/release sequence, status transitions, exception paths.

=== HTTP API 测试 / API testing ===
SimpleComposer 的 Nancy API 可以用 curl / Postman 测试：
<syntaxhighlight lang="bash">
curl -X POST http://localhost:9050/api/dispatch \
-H "Content-Type: application/json" \
-d '{"car": "TestCar", "target": "siteA", "mission_type": "Go"}'
</syntaxhighlight>

== 4. 录制与回放 / Recording & replay ==
DObject 自动 ''录制''（每槽可独立开关 `dobj.Recording = true`）写 `.dorec` 文件到 `medulla/recordings/`。

DObject auto-recording (per-slot `Recording = true` flag) writes `.dorec` files into `medulla/recordings/`.

回放工具用于：
* 重现现场 bug（同一序列输入 → 相同输出）
* 离线对比 SLAM 算法（同一传感器流跑多个版本）
* 培训（不用真车）

Replay flows are documented at [[Special:MyLanguage/使用手册 - 数据录制与回放手册|使用手册 - 数据录制与回放手册]]。

== 5. 版本与助记词 / Version + mnemonic ==
按项目惯例：
Project convention:

<syntaxhighlight lang="xml">
<AssemblyInformationalVersion>1.4.0+kindling</AssemblyInformationalVersion>
</syntaxhighlight>

Major.Minor.Patch + ''单词''助记词。每次改动换助记词。
Bump a fresh single-word mnemonic on each modification.

或用 `[ReplaceWithCompileInfo]` —— LessokajiWeaver 注入时间戳 + git hash 到 static string 字段（[[Special:MyLanguage/LessokajiWeaver编译后处理工具|详情]]）。
Alternative: `[ReplaceWithCompileInfo]` injects compile timestamp + git hash automatically.

== 6. 打包 / Packaging ==
=== Release 构建 / Release build ===
<syntaxhighlight lang="bash">
dotnet publish -c Release -f net6.0
</syntaxhighlight>

输出在 `bin/Release/net6.0/publish/`。Costura.Fody 已经把依赖打到单 DLL，所以只需要 ``<plugin>.dll`。
Output at `bin/Release/net6.0/publish/`. Costura.Fody has embedded deps; only one DLL needed.

=== 测试加载 / Test load ===
'''关键''' ：在一个 ''干净''的 Medulla 控制台（没有其它插件）加载新 DLL：

<syntaxhighlight lang="text">
io load plugins/yourname.dll
your = io init ...
</syntaxhighlight>

如果你 ''忘了 Costura''，其它插件可能 ''碰巧''加载了你需要的 DLL，但生产环境干净启动时会出错。这个测试能立刻发现。

If you forgot Costura, other plugins may incidentally provide the dep, but a clean production install will fail. This test surfaces it instantly.

=== Release artefact / Release zip ===
<pre>
your-plugin-1.4.0+kindling.zip
├── your-plugin.dll
├── README.md # 简短说明
├── CHANGELOG.md # 本版本变更
├── INSTALL.txt # 部署 startup.iocmd 片段
└── (optional) docs/ # 详细使用文档
</pre>

== 7. 发布 / Release ==
* '''内部分发''' / Internal: 上传到 `https://dl.lessokaji.com`（按客户分目录）。
* '''授权门''' / Auth gate: 通过 `auth.lessokaji.com` 控制谁能下载。
* '''Wiki 发布说明''' / Wiki release notes: 更新对应 wiki 页（如 `Detour版本发布记录`）。
* '''DEV_LOG''': 在仓库 `DEV_LOG.md` 加一条记录，含 ''助记词''与变更摘要。

== 8. 兼容性矩阵 / Compatibility matrix ==
{| class="wikitable"
! 你的插件目标 / Your plugin's target !! 兼容 / Compatible with
|-
| RefMedullaCore 1.x || Medulla 1.x runtime
|-
| RefMedullaCore 2.x || Medulla 2.x runtime（即当前 M2，默认）
|-
| RefClumsyCore 1.x || Clumsy 1.x
|-
| RefClumsyCore 2.x || Clumsy 2.x（当前）
|}

在 csproj 里 pin 一个主版本，在 CHANGELOG 里写清次版本要求。
Pin a major version in csproj; document minor-version requirements in CHANGELOG.

== 9. 持续集成 / CI ==
推荐流水线：
Recommended pipeline:

# 拉源 → 单元测试（如果有）→ 构建 Debug 与 Release。
# Lint csproj：检查 ''都引用了 `Ref<Name>.dll`'' 而不是 impl DLL，避免误打包。
# 自动版本号注入（git tag → AssemblyInformationalVersion）。
# Release zip 自动生成 + 上传到内部仓库。

== 10. 常见错误清单 / Pre-release checklist ==
* [ ] 测试加载 (干净环境)
* [ ] `[AsUpperIO]` / `[AsLowerIO]` 字段不是 readonly
* [ ] `Init()` 不抛异常
* [ ] LadderLogic `resume = true` 时也手动捕异常 + 写 Lower IO `eStop = true`
* [ ] Costura.Fody 在 FodyWeavers.xml
* [ ] AssemblyInformationalVersion 含助记词
* [ ] CHANGELOG.md 写了本版变更
* [ ] startup.iocmd 示例片段在 INSTALL.txt
* [ ] 在仿真车里跑过完整任务

== 相关页面 / See also ==
* [[Special:MyLanguage/插件契约与打包约定|插件契约与打包约定]]
* [[Special:MyLanguage/插件开发清单|插件开发清单]]
* [[Special:MyLanguage/startup.iocmd脚本语法|startup.iocmd脚本语法]]
* [[Special:MyLanguage/使用手册 - 数据录制与回放手册|数据录制与回放手册]]
* [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]]

[[Category:二次开发相关说明]]
[[Category:开发手册]]

插件开发清单

2026-05-16T14:00:50Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
本页是 MDCS 插件开发中 ''该做与不该做''（Do's & Don'ts）的速查表。从生产经验中总结，每一条都对应一个真实踩过的坑。

This page is the MDCS plugin-development Do's & Don'ts. Each rule reflects a real production pitfall.

== Do's ==
=== 命名与契约 / Naming & contract ===
* '''Medulla 插件入口类名必须叫 `MainIOObject`''' —— 严格大小写。
Medulla plugin entry class must be exactly `MainIOObject`.
* '''每个插件目录加 README + CHANGELOG'''，写清适配的硬件型号 + 版本 + 联系人。
* '''AssemblyInformationalVersion 含 ''助记词''''' 如 `1.4.0+kindling`，便于现场区分两个数字相同的二进制。

=== 生命周期 / Lifecycle ===
* '''构造函数廉价无副作用''' —— 硬件连接放在 `Init()`。
Constructor must be cheap and side-effect-free; hardware contact in `Init()`.
* '''`Init()` 内捕获异常，设 `eStop = true` + Hedingben toast''' —— ''不要''让 `Init()` 抛出，否则 LadderLogic 部分启动部分不启动，难诊断。
Catch exceptions in `Init()`; set `eStop = true` rather than throwing.
* '''每次部署前用 `io load` 在 ''干净''控制台测试一次加载''' —— 提前发现 Costura 缺失依赖。

=== LadderLogic ===
* '''不阻塞 `Operation()` 超 scanInterval''' —— 起 worker 线程或用 `TriggerOnce` / `WaitSignal` 拆分。
Don't block `Operation()` for longer than `scanInterval`. Spawn a worker or split with helpers.
* '''共享字段加锁''' —— 多个 LadderLogic 并发访问同一字段时用 `lock` 或 `Interlocked`。
* '''发布期间监控 Hedingben''' —— `resume = true` 默认会静默重启 buggy 循环；新插件上线时人在场看 toast。

=== IO 表 / IO fields ===
* '''上位字段 `*Cmd` 后缀，下位 `*Est` 后缀''' —— 项目约定，避免同名冲突。
* '''`[AsInitParam]` 字段加默认值''' —— 即使没人设也能初始化。
* '''敏感字段加 `[IOObjectWatch]`''' —— 电量低 / 温度高自动告警。

=== Movement / Clumsy ===
* '''Movement 实现可重入''' —— 不要 static 字段保存状态。
* '''在 `Get()` 第一帧读 pose'''，不要在构造时读 —— 构造与执行间车可能已经移动。
* '''Movement 长度 ≤ 50 行''' —— 超过就拆成多个 Movement 组合。

=== Detour / 定位 / TightCoupler ===
* '''诚实报协方差''' —— 谎报会让 TightCoupler 让该源 ''统治''融合 → 全局发散。
* '''外部反馈 `counter` 单调递增''' —— 用来检测丢帧 / 乱序。
* '''`integrated = true` 配 `startingTick`''' —— 重置（IMU 重启）时给新 baseline。

=== 工程 / Project ===
* '''每个 csproj 用 `..\tools\` HintPath''' —— 仓库一致约定。
* '''FodyWeavers.xml 含 Costura + LessokajiWeaver'''。
* '''Release 模式发布''' —— Debug 会保留更多 PDB / 符号；体积大。
* '''测试 .NET 4.8 ↔ .NET 6/8 兼容''' —— 部分老 driver 还在 .NET Framework。

=== DObject ===
* '''名 ≤ 32 字符''' —— 超长会被静默截断。
* '''读者用 `Wait()` 阻塞''' —— 比轮询省 CPU。
* '''每次 Post 含 frame counter''' —— 读者能检测丢帧。

=== 文档 / Documentation ===
* '''README 写清 ''硬件型号 + 协议版本'''''。
* '''CHANGELOG 含具体行为变化''' —— 不是 "fix bug"。
* '''startup.iocmd 示例放在 INSTALL.txt''' —— 客户照抄。

== Don'ts ==
=== 命名 ===
* ❌ '''不要把入口类改名'''（如 `MyLidar : Lidar2DIOObject`） —— 加载器找不到。
* ❌ '''不要给 IOObject 加 `[Plugin]` 属性''' —— MDCS 不用 manifest，加了也无效。

=== 加载 ===
* ❌ '''不要热替换 DLL''' —— Costura 缓存导致未定义行为。停 → 替换 → 启动。
* ❌ '''不要在 `static` 构造函数里碰硬件''' —— 加载时立刻触发。
* ❌ '''不要假设 `Init()` 立刻被调''' —— 它要 startup.iocmd 里的 `<inst> Init` 显式触发。

=== IO 表 ===
* ❌ '''`[AsUpperIO]` 不要标在 `readonly` 字段上''' —— 编译过，运行时 `MissingMethodException`。
* ❌ '''不要从外部直接写 `MedullaCartUpperIO<tag>` DObject''' —— 总走 `SetUpperIO`，否则失同步。
* ❌ '''不要把高速字段都 `[IOObjectMonitor]` 加 `VerboseLog`''' —— 日志爆炸。

=== LadderLogic ===
* ❌ '''不要在 `Operation()` 里 `Thread.Sleep`''' —— 阻塞整个 loop 线程。
* ❌ '''不要假设 LadderLogic 是实时''' —— Windows 上 1–15 ms 抖动；真实时需要 PLC。
* ❌ '''不要在多 LadderLogic 之间共享 ''可变''字段而不加锁'''。

=== Movement ===
* ❌ '''不要在 Movement 里 `Thread.Sleep`''' —— 用 `yield return` 多次。
* ❌ '''不要在 `Get()` 抛异常但不写 `eStop = true`''' —— 车继续按上一帧 `vCmd` 走。
* ❌ '''不要从 ''UI 线程''调 `DriveTask.WaitDriveTask`''' —— 它阻塞。

=== Queue ===
* ❌ '''不要假设 Queue 的不同行真的并行''' —— 当前实现是串行（行 i 等行 i-1）。详见 [[Special:MyLanguage/SimpleAgvInterface Queue机制|Queue 机制]] 的"超标量实际行为"段。
* ❌ '''不要在 action 内 ''忽略''异常''' —— 让它传出，让上层决定恢复。

=== Detour ===
* ❌ '''不要在雷达插件里调 `TightCoupler.PostExternalFeed`''' —— 雷达走 DObject `output()` 路径；TightCoupler 是 ''非雷达''来源的入口。
* ❌ '''不要谎报协方差''' —— 永远不要 "我超准请相信我"。
* ❌ '''不要在 SLAM 输出帧间 ''内部''重新加载地图''' —— 用 Detour 的 reload API。

=== SimpleComposer / Fleet ===
* ❌ '''不要在 `BusinessLogic.Plan` 里阻塞超过 100 ms''' —— UI 假死。
* ❌ '''`[CarType]` 标 ''class''，不要标实例字段''' —— 反射查找按 Type。
* ❌ '''不要在 SimpleComposer 进程内调阻塞 HTTP''' —— 用 async/await。

=== Costura / 构建 ===
* ❌ '''不要给 ''核心 DLL'' 加 Costura.Fody''' —— `MedullaCore.dll` / `ClumsyCore.dll` 等保持 ''loose'' DLL，让插件共载。
* ❌ '''不要直接引用 ''impl DLL''''' —— 引用 `Ref<Name>.dll`；否则带入 Costura 内嵌的整套依赖。

=== DObject ===
* ❌ '''不要在 Linux 上假设 `io_shared` MMF''' —— Linux 上是文件后备。
* ❌ '''不要 cache 多个 `new DObject("name")` 实例''' —— 一个 name 一个，跨进程共享。

== 性能反模式 / Performance anti-patterns ==
* ❌ '''每帧 `new` 大数组''' —— 用 buffer 池或预分配。
* ❌ '''每帧 `Console.WriteLine`''' —— 日志走 DLog，主题化、可关闭。
* ❌ '''每帧序列化大对象到 DObject''' —— 用紧凑二进制，避免 JSON。
* ❌ '''Movement 内每帧 `LINQ` 链''' —— `foreach` + 索引循环。

== 安全 / Safety ==
* '''e-stop 必须 ''独立''于 Movement 逻辑''' —— 硬件 e-stop 线 + 软件 watchdog 双层。
* '''激光雷达 < 300 mm 范围内任何点 → 触发硬 stop''' —— 不能等 Movement 层减速。
* '''功能安全设备（SIL-2 / PL-d）独立于 MDCS''' —— MDCS 是控制层，不是安全层。

== 相关页面 / See also ==
* [[Special:MyLanguage/插件契约与打包约定|插件契约与打包约定]]
* [[Special:MyLanguage/插件测试与发布|插件测试与发布]]
* [[Special:MyLanguage/插件开发指南|插件开发指南]]
* [[Special:MyLanguage/LadderLogic框架|LadderLogic框架]]
* [[Special:MyLanguage/MovementDefinition详解|MovementDefinition详解]]
* [[Special:MyLanguage/SimpleAgvInterface Queue机制|SimpleAgvInterface Queue机制]]

[[Category:二次开发相关说明]]
[[Category:开发手册]]

插件开发指南

2026-05-16T14:00:49Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
本页是 MDCS '''插件开发'''的总入口。MDCS 把所有可扩展能力归为 5 个 ''插件家族''，每个家族对应一类 ''扩展点 + 基类 + 打包约定''。完整离线副本见 `D:\src\cookbook\HOW_TO_CUSTOMIZE.md`。

This is the hub for MDCS '''plugin development'''. MDCS organises every extension point into 5 ''plugin families'', each with its own base class + packaging convention. Offline mirror: `D:\src\cookbook\HOW_TO_CUSTOMIZE.md`.

== 1. 5 类插件 / The five families ==
{| class="wikitable"
! 家族 / Family !! 宿主进程 / Host process !! 基类 / Base !! 入门页 / Tutorial
|-
| 雷达插件 / Lidar plugin || Medulla || `Lidar2DIOObject` / `Lidar3DIOObject` || [[Special:MyLanguage/如何适配新的雷达|如何适配新的雷达]] / [[Special:MyLanguage/2D激光雷达适配|2D激光雷达适配]]
|-
| 相机插件 / Camera plugin || Medulla || `IOObject`（约定 `MainIOObject` 类名）|| [[Special:MyLanguage/3D相机适配|3D相机适配]]
|-
| 底盘适配 / Cart hardware || Medulla || `CartDefinition` || [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]
|-
| Movement / 运动适配 || Clumsy || `MovementDefinition` || [[Special:MyLanguage/巡线行走|巡线行走]] / [[Special:MyLanguage/MovementDefinition详解|MovementDefinition详解]]
|-
| 车队插件 / Fleet plugin || SimpleComposer || `ClumsyCar` / `Car` / `BusinessLogic` + `[CarType]` || [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|如何基于SimpleCore核心库进行调度系统开发]]
|}

底层共通约定见以下子页：
Shared conventions live on these sub-pages:

* [[Special:MyLanguage/插件契约与打包约定|插件契约与打包约定]] — `MainIOObject` 命名 + Costura + LessokajiWeaver + 部署路径
* [[Special:MyLanguage/IOObject属性参考|IOObject属性参考]] — `[IOObjectMonitor] / [IOObjectUtility] / [IOObjectWebUtility] / [IOObjectWatch]`
* [[Special:MyLanguage/CartDefinition属性参考|CartDefinition属性参考]] — `[AsInitParam] / [AsUpperIO] / [AsLowerIO] / [UseLadderLogic]`
* [[Special:MyLanguage/LadderLogic框架|LadderLogic框架]] — 周期循环宿主
* [[Special:MyLanguage/startup.iocmd脚本语法|startup.iocmd脚本语法]] — 启动脚本
* [[Special:MyLanguage/DObject共享内存协议|DObject共享内存协议]] — IPC
* [[Special:MyLanguage/MovementDefinition详解|MovementDefinition详解]] — Movement 契约
* [[Special:MyLanguage/SimpleAgvInterface Queue机制|SimpleAgvInterface Queue机制]] — Queue 行为
* [[Special:MyLanguage/TightCoupler外部反馈API|TightCoupler外部反馈API]] — 外部位姿源接入
* [[Special:MyLanguage/插件测试与发布|插件测试与发布]] — 测试 + 打包 + 发布
* [[Special:MyLanguage/插件开发清单|插件开发清单]] — Do's & Don'ts

== 2. 工程脚手架 / Scaffolding ==
脚手架工具：`D:\src\cookbook\MDCS-plugin-helper\generate.py`（交互式 Python 脚本）。
Scaffolder: `D:\src\cookbook\MDCS-plugin-helper\generate.py` (interactive).

<syntaxhighlight lang="bash">
cd D:\src\cookbook\MDCS-plugin-helper
python generate.py
# Choose 1 — Create a project
# Pick the plugin family
# Enter project name
</syntaxhighlight>

它会下载 ''参考 DLL''（`Ref<Name>.dll` 系列）到 `ref/`，并下载对应 boilerplate `.cs` 文件。
It downloads the reference DLLs (`Ref<Name>.dll`) into `ref/` and a boilerplate `.cs` file.

== 3. 车型适配案例 / Vehicle case studies ==
按车型分类的端到端案例：
End-to-end case studies by vehicle type:

* [[Special:MyLanguage/叉车适配案例|叉车适配案例]] — 凌鸟 LB14
* [[Special:MyLanguage/潜伏顶升车(KIVA类小车)适配案例|潜伏顶升车(KIVA类小车)适配案例]] — 浙江迈睿 KIVA
* [[Special:MyLanguage/全向车适配案例|全向车适配案例]] — 麦克纳姆 + 四舵
* [[Special:MyLanguage/牵引车适配案例|牵引车适配案例]] — 单 / 双阿克曼

== 4. 特殊场景 / Specialty applications ==
* [[Special:MyLanguage/自动识别工位并取放货|自动识别工位并取放货]]
* [[Special:MyLanguage/双车/多车联动|双车 / 多车联动]]
* [[Special:MyLanguage/联动天眼系统进行装卸车|联动天眼系统进行装卸车]]
* [[Special:MyLanguage/设备跟随联动|设备跟随联动]]
* [[Special:MyLanguage/识别料框并堆垛拆垛|识别料框并堆垛拆垛]]
* [[Special:MyLanguage/汽车面差检测|汽车面差检测]]
* [[Special:MyLanguage/清洁机器人|清洁机器人]]
* [[Special:MyLanguage/复合卷料机械手叉车|复合卷料机械手叉车]]

== 5. 关联文档 / See also ==
* [[Special:MyLanguage/操作指南|操作指南]] — 运维者视角
* [[Special:MyLanguage/核心开发指南|核心开发指南]] — 平台开发者视角
* [[Special:MyLanguage/车体抽象原理|车体抽象原理]] — 三层模型

[[Category:开发手册]]
[[Category:二次开发相关说明]]

插件契约与打包约定

2026-05-16T14:00:47Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
本页讲所有 MDCS 插件 ''共通'' 的约定 —— 不论是雷达 / 相机 / 底盘 / Movement / 还是 SimpleComposer 插件，这些规则都适用。具体的 ''基类签名''见各家族页面。

This page covers the conventions ''shared by every MDCS plugin'' — lidar, camera, cart, Movement, fleet — regardless of family. The family-specific ''base-class contracts'' live on their own pages.

== 1. 命名约定 / Naming convention ==
=== MainIOObject 命名 ===
'''Medulla 端插件''' (lidar / camera / cart) 的入口类 ''必须叫 `MainIOObject`'' —— 严格区分大小写。
The Medulla-side plugin entry class ''must be named exactly `MainIOObject`'' — case-sensitive.

Medulla 加载器 (`D:\src\M2\MedullaCore\MedullaIO.cs:299`) 反射查找：
The loader does reflection lookup:

<syntaxhighlight lang="csharp">
var type = asm.GetTypes().FirstOrDefault(t => t.Name == "MainIOObject");
return Activator.CreateInstance(type); // parameterless ctor required
</syntaxhighlight>

没有 `[Plugin]` 属性，没有 manifest。仅靠类名 + 无参构造函数。
No `[Plugin]` attribute, no manifest — just the class name and a parameterless ctor.

【注意】改类名或删默认构造函数 → 加载静默失败 → 几分钟后由 `Hedingben` toast 间接报错。先用 `io load <yourplugin>.dll` 在 Medulla console 单独测试加载。 
Renaming or removing the parameterless ctor → silent load failure surfacing later in `Hedingben`. Test `io load` in isolation first.

=== Clumsy / Simple 插件类名 ===
Clumsy `MovementDefinition` 子类 + Simple `Car` / `ClumsyCar` / `BusinessLogic` 子类不要求特定类名，但用 ''属性'' 标识：
Clumsy / Simple plugins don't need a specific name; they use attributes to identify themselves:

* `[CarType]` 标 Simple 端 Car 子类
* `[MovementTest]` 标 Clumsy Movement 测试入口
* `[CoderMethod]` 标 SimpleCore TopazScript 编码器方法

=== 文件夹与 DLL 命名 / Folder & DLL naming ===
* 一方插件 / First-party: `D:\src\M2\OfficialPlugins\<VendorModel>\`
* 三方插件 / Third-party: 任意；通常 `<vendor-name>\<model>\`
* DLL 名 = `<VendorModel>.dll`，部署到 `medulla/plugins/<vendor>/` 或 `simplecomposer/plugins/`

== 2. 项目文件 / .csproj ==
=== 目标框架 / Target framework ===
* '''.NET 6.0''' or '''.NET 8.0''' — 推荐 / preferred
* '''.NET Framework 4.8''' — 部分旧雷达驱动用 / some legacy lidar drivers

=== 引用 / References ===
所有插件 csproj 都引用 ''参考程序集''（`Ref<Name>.dll`），不引用 impl DLL：
All plugin csproj reference '''reference-only assemblies''' (`Ref<Name>.dll`), not the implementation DLLs:

<syntaxhighlight lang="xml">
<ItemGroup>
<PackageReference Include="Fody" Version="6.x" PrivateAssets="all" />
<PackageReference Include="Costura.Fody" Version="5.x" />
<Reference Include="RefFundamentalLib">
<HintPath>..\tools\RefFundamentalLib.dll</HintPath>
</Reference>
<Reference Include="RefMedullaCore">
<HintPath>..\tools\RefMedullaCore.dll</HintPath>
</Reference>
<Reference Include="RefLidarController">
<HintPath>..\tools\RefLidarController.dll</HintPath>
</Reference>
</ItemGroup>
</syntaxhighlight>

`..\tools\` 模式 ''全仓库一致'' —— 不要改成 NuGet。
The `..\tools\` HintPath pattern is repo-wide; don't try to NuGet-ify it.

=== Costura.Fody 胖 DLL ===
插件输出是单 `.dll`，所有依赖（包括 LessokajiWeaver 工具库）嵌入为 base64 资源。客户只需要 1 个文件部署。
Plugin output is a single `.dll` with all deps embedded as base64 resources. Customer deployment = 1 file.

`FodyWeavers.xml` 在工程根：
<syntaxhighlight lang="xml">
<Weavers>
<Costura/>
<LessokajiWeaver/>
</Weavers>
</syntaxhighlight>

【注意】 ''Costura 缓存''可能让你看不到 FundamentalLib 升级 —— 重新构建插件后再部署，否则胖 DLL 里还是旧版 FundamentalLib。 
Costura caches dependencies in the fat DLL. After upgrading FundamentalLib, '''rebuild plugins''' before deploying.

== 3. 版本与助记词 / Version + mnemonic ==
每次修改插件，AssemblyInformationalVersion 加 ''单词助记词''：
Every plugin modification adds a single mnemonic word to AssemblyInformationalVersion:

<syntaxhighlight lang="xml">
<AssemblyInformationalVersion>1.4.0+kindling</AssemblyInformationalVersion>

<AssemblyInformationalVersion>1.4.1+lantern</AssemblyInformationalVersion>
</syntaxhighlight>

目的：现场调试时 ''肉眼区分''两个数字看起来一样的二进制。
Purpose: visually disambiguate two binaries with the same number in the field.

或者用 `[ReplaceWithCompileInfo]` —— LessokajiWeaver 在编译期注入时间戳 + git 哈希到 static string 字段。
Alternative: `[ReplaceWithCompileInfo]` — LessokajiWeaver injects timestamp + git hash at compile time.

== 4. 部署 / Deployment ==
=== Medulla 端 / Medulla-side ===
DLL 放到 `medulla/plugins/<vendor>/<plugin>.dll`，`startup.iocmd` 加：
Drop the DLL into `medulla/plugins/<vendor>/`, add to `startup.iocmd`:

<syntaxhighlight lang="text">
foo = io load plugins/<vendor>/<plugin>.dll
foo Init # if your plugin has an Init method
foo Start <args> # invoke whatever it needs
</syntaxhighlight>

startup.iocmd 语法见 [[Special:MyLanguage/startup.iocmd脚本语法|startup.iocmd脚本语法]]。

=== SimpleComposer 端 / SimpleComposer-side ===
DLL 放到 `simplecomposer/plugins/<plugin>.dll`。SimpleComposer 启动时（`D:\src\Simple\SimpleComposer\Program.cs:107-162`）自动扫所有 DLL，按 `[CarType]` / `HeuristicsContainer` / `CustomOperationsBeforeLoading.Set` / `BusinessLogic` 类型分类注册。

Drop into `simplecomposer/plugins/`. SimpleComposer auto-scans on boot.

== 5. 加载生命周期 / Load lifecycle ==

Medulla:
io load X.dll → reflection scan → instantiate MainIOObject
↓ (your ctor runs; no hardware contact)
cart Init → connect hardware → spawn LadderLogics
↓
Operation(0), Operation(1), ...

SimpleComposer:
Program.cs startup
→ load every plugins/*.dll
→ scan for [CarType] / HeuristicsContainer / BusinessLogic / CustomOps
→ register
→ MyAsmHelper.Init() invoked

【注意】 Medulla 加载器 ''不调'' `Init()`。你需要 startup.iocmd 显式调用 `cart Init`。 
The Medulla loader does NOT call `Init()`. You must invoke `cart Init` from startup.iocmd.

== 6. 一切重启 vs 热替换 / Restart vs hot swap ==
* '''Medulla 插件''': '''必须'''停 Medulla → 替换 DLL → 启动。热替换会导致 Costura 缓存冲突 / undefined behaviour。
* '''SimpleComposer 插件''': 同上 —— 关 SimpleComposer → 替换 → 启动。
* '''Clumsy MovementDefinition''': 同 Clumsy 进程重启。

Hot swap is not supported. Always stop-replace-start.

== 7. 跨平台 / Cross-platform ==
* Medulla / Detour / Clumsy / SimpleComposer 都可在 Linux 运行（.NET 6/8）。
* DObject 在 Linux 用文件后备（见 [[Special:MyLanguage/DObject共享内存协议|DObject 共享内存协议]]）。
* libVRender (CycleGUI 渲染) 已有 Linux 构建，但 Windows 是主战场。

== 相关页面 / See also ==
* [[Special:MyLanguage/startup.iocmd脚本语法|startup.iocmd脚本语法]]
* [[Special:MyLanguage/IOObject属性参考|IOObject属性参考]]
* [[Special:MyLanguage/CartDefinition属性参考|CartDefinition属性参考]]
* [[Special:MyLanguage/LadderLogic框架|LadderLogic框架]]
* [[Special:MyLanguage/插件测试与发布|插件测试与发布]]
* [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]]
* [[Special:MyLanguage/MDCS-plugin-helper|MDCS-plugin-helper]] — 脚手架工具

[[Category:二次开发相关说明]]
[[Category:开发手册]]

TightCoupler外部反馈API

2026-05-16T14:00:26Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
`TightCoupler` 是 Detour 的 ''多源位姿融合器''。非 SLAM 来源的位姿（轮编里程计 / IMU / RTK / UWB / 第三方视觉等）通过 `PostExternalFeed` API 推入 TightCoupler，与激光 / 地纹 / 二维码等 SLAM 后端一起做紧耦合优化，输出统一的 6-DoF 位姿。

`TightCoupler` is Detour's '''multi-source pose fuser'''. Non-SLAM poses (wheel odometry / IMU / RTK / UWB / third-party vision) enter through the `PostExternalFeed` API. They join the SLAM backends (laser / ground-texture / QR) in a tightly-coupled optimisation that emits the unified 6-DoF pose.

实现：`D:\src\Detour\DetourCore\Algorithms\TightCoupler.ExternalCoupler.cs:14`。
Implementation: `D:\src\Detour\DetourCore\Algorithms\TightCoupler.ExternalCoupler.cs:14`.

整体设计见 [[Special:MyLanguage/多定位源的自动综合|多定位源的自动综合]]。
For the design rationale see [[Special:MyLanguage/多定位源的自动综合|multi-source positioning fusion]].

== API 签名 / API signature ==
<syntaxhighlight lang="csharp">
public static void PostExternalFeed(ExternalFeed obj, string name);
</syntaxhighlight>

每次调用提交 ''一帧''的外部位姿观测。`name` 是 ''来源标识''（如 `"WheelImu"` / `"RTK"`），用来在融合器内部跟踪不同来源的协方差、检查超时、重映射。

Each call submits ''one frame'' of an external pose observation. `name` identifies the source (e.g. `"WheelImu"`, `"RTK"`) so the fuser can track per-source covariance, detect silence, and remap as needed.

== `ExternalFeed` 结构体 / Struct ==
<syntaxhighlight lang="csharp">
public struct ExternalFeed
{
public string name;
public long counter;
public bool hasTranslation;
public bool hasRotation;
public bool is3D;
public bool is2D;
public bool integrated;
public bool toRemap;
public long startingTick;
public float x, y, z, th, pitch, roll;
}
</syntaxhighlight>

字段语义 / Field semantics:

{| class="wikitable"
! 字段 / Field !! 含义 / Meaning
|-
| `name` || 来源名（同上）；融合器按此聚类
|-
| `counter` || 单调递增；用来检测丢帧 / out-of-order
|-
| `hasTranslation` || 该观测包含位置（x, y, [z]）/ includes translation
|-
| `hasRotation` || 该观测包含朝向（th, pitch, roll）/ includes rotation
|-
| `is2D` / `is3D` || 二选一；表示是平面运动还是 3D 6-DoF
|-
| `integrated` || true = 累积量（相对位姿）；false = 单帧绝对量 / cumulative vs single-frame
|-
| `toRemap` || true = 绝对参考系（如 RTK），融合时需要全局重映射 / absolute frame, needs global remap
|-
| `startingTick` || 累积量的基准 tick；用来检测重置（如 IMU 重启）
|-
| `x, y, z, th, pitch, roll` || 实际位姿（mm / rad）
|}

== 典型来源配置 / Canonical source configurations ==
`TightCoupler.ExternalCoupler.cs:49-54` 中的注释列出了典型用法：
The source comment lists canonical configurations:

{| class="wikitable"
! 来源 / Source !! 标志组合 / Flags
|-
| 轮编 + IMU / Wheel + IMU || `hasTranslation | hasRotation | is2D | integrated | startingTick`
|-
| 仅 IMU / IMU only || `hasRotation | (is2D 或 is3D) | integrated`
|-
| RTK GNSS || `hasTranslation | toRemap`（绝对，需重映射）
|-
| UWB / 基站 / Beacon || `hasTranslation | is2D`（绝对二维位置）
|-
| 第三方视觉 / 3rd-party vision || 视具体输出而定
|}

== 提交模板 / Submission template ==
轮编 + IMU 紧耦合：
<syntaxhighlight lang="csharp">
using DetourCore.Algorithms;

TightCoupler.PostExternalFeed(new ExternalFeed
{
name = "wheel_imu",
counter = tick++,
hasTranslation = true,
hasRotation = true,
is2D = true,
integrated = true,
startingTick = baselineTick,
x = odomX,
y = odomY,
th = odomTh
}, name: "WheelImu");
</syntaxhighlight>

RTK ：
<syntaxhighlight lang="csharp">
TightCoupler.PostExternalFeed(new ExternalFeed
{
name = "rtk",
counter = gpsTick++,
hasTranslation = true,
is2D = true,
integrated = false,
toRemap = true,
x = rtkEastingMm,
y = rtkNorthingMm
}, name: "RTK");
</syntaxhighlight>

== 协方差与权重 / Covariance & weighting ==
TightCoupler 内部按 ''协方差矩阵的逆''加权 —— 不需要插件作者设权重；插件 ''必须诚实''地报协方差。错报协方差是融合崩坏的 ''首要''原因：一个谎报"我超准"的源会 ''统治''融合结果。

TightCoupler weights by the inverse of the covariance matrix — no manual weight tuning needed; sources must ''honestly'' report covariance. Mis-reporting is the #1 cause of fusion blowups.

来源：
* SLAM 后端：Hessian 求逆
* 二维码 PnP：重投影残差
* IMU / 里程计：硬件规格 + 时间间隔
* RTK：GNSS DOP

== 异常路径 / Failure paths ==
* '''源静默 / Silence''': 超过 ''timeout''（融合器配置） → 该源从下一帧位姿图中删除，其它源不受影响。
* '''跳变 / Wild jump''': TightCoupler 内置 ''卡方检验''；> 5σ 的观测直接丢弃。
* '''融合发散 / Divergence''': 残差持续上升 → 触发 ''软重启''（保留主导源，重置其它源的位姿先验）。

== 调试 / Debug ==
Detour UI 的"融合面板" 显示：
* 每个源的最新观测时刻 + 协方差
* 当前主导源
* 残差直方图

打开 ''单源调试模式''可强制只用一个源（用于诊断单源故障）。
There's a "single-source debug mode" forcing the fusion to use only one source.

== 与雷达 Lidar 插件的区别 / vs lidar plugins ==
雷达数据 ''不走''此 API：
* 雷达插件 `output()` 把帧推到 ''DObject''；
* Detour 端 `Lidar2D.ReadLidar()` 订阅该 DObject，把 SLAM 观测加到内部位姿图。

只有 ''非传感器''的位姿来源走 `PostExternalFeed`。

Lidar data does NOT go through this API. Lidar plugins `output()` to DObject; Detour subscribes via `Lidar2D.ReadLidar()`. Only ''non-sensor'' pose sources go through `PostExternalFeed`.

== 相关页面 / See also ==
* [[Special:MyLanguage/多定位源的自动综合|多定位源的自动综合]]
* [[Special:MyLanguage/Detour软件架构|Detour软件架构]]
* [[Special:MyLanguage/Detour激光SLAM算法详解|Detour激光SLAM算法详解]]
* [[Special:MyLanguage/输入GPS外部定位|输入GPS外部定位]]
* [[Special:MyLanguage/使用手册 - 同时使用激光、地纹、二维码、轮编里程计和IMU进行鲁棒定位|同时使用激光、地纹、二维码、轮编里程计和IMU进行鲁棒定位]]

[[Category:二次开发相关说明]]
[[Category:定位导航相关手册]]

Startup.iocmd脚本语法

2026-05-16T14:00:25Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
`startup.iocmd` 是 Medulla 启动时执行的 ''迷你脚本''。语法极简：每行一条命令，支持对象加载、字段读写、方法调用。它的目的是让现场调试人员能在不写 C# 的情况下加载和初始化插件。

`startup.iocmd` is the tiny script Medulla executes at boot. The grammar is minimal — one command per line, with object loading, field read/write, and method invocation. Its purpose is to let on-site engineers load and initialise plugins without writing C#.

实现：`D:\src\M2\MedullaCore\Core\MedullaScriptEngine.cs:22-130`。
Implementation: `D:\src\M2\MedullaCore\Core\MedullaScriptEngine.cs:22-130`.

启动入口：`Startup.runScript(filename)` 在 CWD 找 `startup.iocmd`，逐行执行。
Boot entry: `Startup.runScript(filename)` reads `startup.iocmd` from CWD line by line (`Startup.cs:374-402`).

== 命令语法 / Command grammar ==
{| class="wikitable"
! 形式 / Form !! 语法 / Syntax !! 示例 / Example !! 语义 / Semantics
|-
| 加载 + 赋值 / Load + assign || `name = io load <dll>` || `lidar = io load plugins/Lidar.dll` || 加载 DLL，反射找 `MainIOObject`，实例化，注册到 `Objects[name]`
|-
| 工厂方法 / Factory method || `name = obj method arg1 arg2 ...` || `lidar = io init WLR716Lidar 192.168.0.2 2110` || 调用 obj.method 并把返回赋值给 name
|-
| 方法调用 / Method call || `name method arg1 arg2 ...` || `cart Init` || 调用 name.method（无返回）
|-
| 字段读 / Field read || `name.field` || `cart.batteryPercent` || 反射读字段或 property，控制台输出
|-
| 字段写 / Field write || `name.field = value` || `cart.TimeoutThreshold = 1000` || 反射写；`TypeDescriptor.ConvertFromString` 解析 value
|}

解析规则：按空格分词；引号内当一个 token。
Parsing: split on whitespace; quoted strings count as one token.

== 支持的参数类型 / Supported parameter types ==
* 整型 / Integers: `short`, `ushort`, `int`, `uint`, `long`, `ulong`
* 浮点 / Floats: `float`, `double`
* `bool`：`true` / `false`
* `string`：可加引号 `"with spaces"` 或不加
* `byte[]`：十六进制串 `0x12AB`
* `IOObject` 引用：按 `Objects[name]` 解析（即用其它对象的名字）

Hex literal: `0x12AB` for integer types.

Overload resolution: by name + arity, or variadic `object[]` (`MedullaScriptEngine.cs:138-144`).

== 完整示例 / Full example ==
<syntaxhighlight lang="text">
# Lidar plugin
lidar = io load plugins/LidarController.dll
lidar = lidar init WLR716Lidar 192.168.0.2 2110
lidar Start
lidar.TimeoutThreshold = 1000

# Cart adapter plugin
cart = io load plugins/MyCart.dll
cart Init
cart.brakeOn = false

# Camera
cam = io load plugins/Camera.dll
cam = cam init 192.168.0.50 8081
cam Start

# Diagnostics: open the LidarController's web utility for the loaded lidar
# (it'll appear at https://<host>:8081/lidar/ShowFrame)
</syntaxhighlight>

== Web endpoint 自动注册 / Auto web-endpoint registration ==
赋值语句 `name = io load ...` 不仅注册对象，还会把对象上 `[IOObjectWebUtility]` 标注的方法自动挂到 HTTP 路径 `/<name>/<methodname>`。
The assignment `name = io load ...` also auto-registers any `[IOObjectWebUtility]` methods at `/<name>/<methodname>`.

启动后可访问 `https://<host>:<MedullaIO.CPort>/<name>/<method>` 调用插件方法。
After boot, hit `https://<host>:<MedullaIO.CPort>/<name>/<method>` to invoke.

== 注释与空行 / Comments & blank lines ==
* 空行 / blank lines: 忽略
* `# 开头` / lines starting with `#`：注释
* 没有 ''多行命令''；每条命令必须写在一行。

== 错误处理 / Error handling ==
脚本里某行失败 → ''继续''执行下一行；错误打到 DLog + Hedingben toast。所以 `startup.iocmd` 是 "尽力而为"模型 —— 你应该用 web 端点或控制台后续确认状态，不要假设全部成功。

Failed lines log to DLog + Hedingben toast and execution continues. `startup.iocmd` is "best-effort" — confirm state via web endpoint or console afterwards.

== 扩展点 / Extension hooks ==
* 添加新的内建函数：扩展 `MedullaScriptEngine.evaluate` (line 80+)。
* 加新的参数类型：扩展 `MedullaScriptEngine.cs:69` 的 type coercion switch。
* 保持语法最简 —— 没有括号、没有嵌套调用。'''单行可读''' 是它的设计原则。

* New built-in functions: extend `MedullaScriptEngine.evaluate` (line 80+).
* New parameter types: extend the coercion switch at line 69.
* Keep the grammar minimal — no parens, no nested calls. '''Single-line readability''' is the design.

== 注意 / Caveats ==
* `startup.iocmd` 在 ''CWD'' 加载，不在 Medulla 安装目录 —— 启动脚本要把工作目录设到正确位置。 
Loaded from CWD, not Medulla's install dir — your launcher must set the working directory.
* 没有 `if / for / while` —— 控制流需要写 C# 插件。
* `name` 标识符不能含 `.` 或 `=` 或空格。

== 相关页面 / See also ==
* [[Special:MyLanguage/插件契约与打包约定|插件契约与打包约定]]
* [[Special:MyLanguage/IOObject属性参考|IOObject属性参考]]
* [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]]
* [[Special:MyLanguage/Medulla|Medulla]] / [[Special:MyLanguage/Medulla-API|Medulla-API]]

[[Category:二次开发相关说明]]
[[Category:开发手册]]

SimpleAgvInterface Queue机制

2026-05-16T14:00:23Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
`SimpleAgvInterface.Queue(params Func<Task>[] actions)` 是 Clumsy 车载侧的 ''任务流水线''机制。它把多个 ''异步 action''组织成可串可并的执行图，使任务作者能以声明式风格写出 "巡线 → 取货 → 升叉 → 倒车"这样的业务序列。

`SimpleAgvInterface.Queue(params Func<Task>[] actions)` is the '''task pipeline''' on the Clumsy on-vehicle side. It organises multiple async actions into a serial/parallel execution graph so mission authors can write business sequences declaratively.

实现：`D:\src\Clumsy\ClumsyCore\Interfaces\SimpleAgvInterface.cs:410`。
Implementation: `D:\src\Clumsy\ClumsyCore\Interfaces\SimpleAgvInterface.cs:410`.

== 基本用法 / Basic usage ==
<syntaxhighlight lang="csharp">
public void Fetch(double sx, double sy, double dx, double dy)
{
Queue(
async () =>
{
DriveTask.WaitDriveTask(new SteeringLineFollowing
{ srcX = currentX, srcY = currentY, dstX = sx, dstY = sy, basespeed = 600 }.Follow());
},
async () =>
{
DriveTask.WaitDriveTask(new AutoFetchGood
{ aX = sx, aY = sy, bX = dx, bY = dy, initSpeed = 500, stopDist = 80 }.Get());
},
async () =>
{
SetUpperIO("forkHeightTgt", 50);
await WaitForLowerIO("forkAtTarget", 4000);
},
async () =>
{
DriveTask.WaitDriveTask(new SteeringLineFollowingReverse
{ srcX = dx, srcY = dy, dstX = sx, dstY = sy, basespeed = 200 }.ReverseFollow());
});
}
</syntaxhighlight>

按提交顺序，4 个 action 形成 4 ''行''（rows），框架依次执行。
The 4 actions form 4 ''rows''; the framework executes them.

== 数据结构 / Data structure ==
内部维护两个队列（`SimpleAgvInterface.cs:308-352`）：
Internally there are two queues:

* '''`staticTaskLs : List<List<Task>>`''' — 静态共享队列；每行是 `List<Task>`。
* '''`taskLs : List<List<Task>>`''' — 当前实例的队列；可与 static 共享或独立。
* '''`queueInfo : List<SaiInfo>`''' — 每行的状态字符串、提交线程 ID、异常上下文。

每次 `Queue(actions)` 调用：
Each `Queue(actions)` call:

# 把 `actions[i]` ContinueWith 到 `taskLs[i]` 的最后一个 Task 后面。
# `actions[i]` 内部 `await taskLs[i-1].Last()` —— 即等上一 ''行''最新提交的 action 完成。
# 注册到 `queueInfo[i]`。

# Chain `actions[i]` after `taskLs[i].Last()` (the previous action in the same row).
# Inside `actions[i]`, `await taskLs[i-1].Last()` (the previous row's latest action).
# Register in `queueInfo[i]`.

== "超标量"实际行为 / The "super-scalar" reality ==
【发现】当前实现 ''没有''真正的跨行并发。第 i 行的 action ''必须''等第 i-1 行的 ''最新提交''完成，所以多行 Queue 调用实际上是 ''串行执行''。"超标量流水线"是设计目标，不是当前实现。
【发现】 The current implementation does NOT actually run rows in parallel. Row i awaits row i-1's most recent Task, so multi-row Queue calls execute '''sequentially'''. The "super-scalar pipeline" is design aspiration, not current behaviour.

也就是说：
In practice:

* '''单次 `Queue(a, b, c)`''' → a, b, c 串行（b 等 a 完成，c 等 b 完成）。
* '''连续 `Queue(a, b)`; `Queue(c, d)`''' → a → b → c → d 串行；c 等 b 完成（同行）；d 等 c 完成（同行）。
* '''并发要靠 action 内 `Task.WhenAll`''' —— 若你想 a + b 同时开始，自己在 a 内 `Task.WhenAll(taskA, taskB)`。

* `Queue(a, b, c)` runs a → b → c sequentially.
* Repeated `Queue` calls also serialise via row chaining.
* For concurrency '''within''' an action, use `Task.WhenAll` explicitly.

== `WaitAsync` / `Wait` ==
等待指定行完成：
Wait for a specific row to finish:

<syntaxhighlight lang="csharp">
await agv.WaitAsync(pipe: 2); // wait for row 2's latest task
// or sync
agv.Wait(pipe: 0);
</syntaxhighlight>

== `TryLock` / `Leave` ==
交管 ''锁''的两种执行路径，由 `useSimpleCallTraffic` 开关决定（`SimpleAgvInterface.cs:40`）：

Traffic locks have two paths controlled by `useSimpleCallTraffic`:

=== 同步内置 / In-process synchronous ===
当 `useSimpleCallTraffic = true`（同一进程跑调度内核 + 车载）：
* `TryLock(siteID, route_id)` 轮询 `PilotBase.latestLock == siteID`（`SimpleAgvInterface.cs:124`）
* `Leave(siteID)` 直接更新本地 `PilotBase.leaves`

=== HTTP RPC ===
跨进程时（车载与调度内核不在同一进程）：
* `TryLock` → POST `http://{host}:{port}/trylock` body `{carid, siteid}`（line 170）
* `Leave` → GET `/leave?carid={id}&siteid={siteID}`（line 260）

== 异常处理 / Error handling ==
* Action 内异常 → 写到 `queueInfo[i].exception`；该行后续 action 跳过；其它行继续。
* 调度可通过 `Flush()` 显式终结队列；之后 `Queue(...)` 抛 `_pipelineError`（line 112）。
* 任务级失败上报靠 ''任务脚本编译时插入的 try/catch'' + Hedingben toast。

* Exceptions in actions → recorded in `queueInfo[i].exception`; subsequent actions in that row skipped; other rows continue.
* `Flush()` ends the queue; later `Queue(...)` throws `_pipelineError`.

== 实战模式 / Patterns ==
=== 顺序业务动作 / Sequential business action ===
最常见。每个 action 是一段独立的 ''检查 → 行驶 → 等硬件''微操。
Most common. Each action is a self-contained "check → drive → wait hw" micro-op.

=== 锁先于动作 / Lock-then-act ===
<syntaxhighlight lang="csharp">
Queue(
async () => { if (!TryLock(targetSite, routeId)) return; /* signal failure */ },
async () => { /* the actual drive */ },
async () => Leave(prevSite)
);
</syntaxhighlight>

=== 设备 IO 等待 / Wait-for-IO ===
<syntaxhighlight lang="csharp">
Queue(
async () => { SetUpperIO("jackTarget", 80); },
async () => { await WaitForLowerIO("jackAtTarget", timeoutMs: 4000); }
);
</syntaxhighlight>

=== 错误恢复 / Error recovery ===
Action 内部 try/catch；失败时把 cart 切到 "故障"状态并 toast：

<syntaxhighlight lang="csharp">
Queue(
async () =>
{
try { await DoFragileThing(); }
catch (Exception e)
{
Hedingben.ToastText($"Action failed: {e.Message}", "AGV");
DriveStop();
throw;
}
}
);
</syntaxhighlight>

== 调度侧 AGVInterface / Fleet-side AGVInterface ==
SimpleCore 端的 `AGVInterface` (`D:\src\Simple\SimpleCore\BasicProps\AGVInterface.cs`) 提供 ''同款 Queue 机制''，用于自评估车：调度直接在自己进程里跑 Queue 来翻译 TopazScript。详见 [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|如何基于SimpleCore核心库进行调度系统开发]]。

The fleet-side `AGVInterface` provides the same Queue mechanism for self-evaluating cars (scheduler runs Queue locally to translate TopazScript).

== 相关页面 / See also ==
* [[Special:MyLanguage/MovementDefinition详解|MovementDefinition详解]]
* [[Special:MyLanguage/DriveTask调度循环|DriveTask调度循环]]
* [[Special:MyLanguage/车体抽象原理|车体抽象原理]]
* [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|如何基于SimpleCore核心库进行调度系统开发]]
* [[Special:MyLanguage/Clumsy-API|Clumsy-API]]

[[Category:二次开发相关说明]]
[[Category:开发手册]]

MovementDefinition详解

2026-05-16T14:00:21Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
`MovementDefinition` 是 Clumsy 中描述 ''一个运动行为''的抽象基类。每个 Movement 是一段 ''可迭代''的控制循环，由 `DriveTask` 宿主按 ''DriveTaskInterval''（默认 20 ms）周期推进。它是 Clumsy 自动驾驶的 ''基本运动语汇''。

`MovementDefinition` is the Clumsy abstract base that describes a single motion behaviour. Each Movement is an iterable control loop, ticked by `DriveTask` at `DriveTaskInterval` (default 20 ms). It's Clumsy's '''basic motion vocabulary'''.

定义：`D:\src\Clumsy\ClumsyCore\Pilot\MovementDefinition.cs:41-48`。
Definition: `D:\src\Clumsy\ClumsyCore\Pilot\MovementDefinition.cs:41-48`.

== 契约 / Contract ==
<syntaxhighlight lang="csharp">
public abstract class MovementDefinition
{
public abstract IEnumerable<bool> Get();
}

public abstract class MovementDefinition<T> : MovementDefinition
{
public new abstract IEnumerable<T> Get();
}
</syntaxhighlight>

`Get()` 返回一个 ''可迭代''；框架每次调 `MoveNext()` 推一格。

`Get()` returns an enumerable; the framework calls `MoveNext()` once per tick.

* '''每次 `yield return true`''' = "继续 tick" / "keep ticking"
* '''迭代器耗尽（不再 `yield`）''' = "Movement 完成" / "Movement done"

== 生命周期 / Lifecycle ==

你的代码 / Your code:
DriveTask.WaitDriveTask(new MyMovement{...}.Get());
│
▼
DriveTask 内部 / Inside DriveTask (D:\src\Clumsy\ClumsyCore\DriveTask.cs:104-144):
new Thread + AboveNormal priority
│
▼ 循环 / loop:
enumerator.MoveNext()
Thread.Sleep(Configuration.conf.DriveTaskInterval) // 20 ms
...
│
▼ 完成 / done (MoveNext returns false):
stopped_reason = 0
Monitor.PulseAll(wait)
│
▼ 异常 / on exception:
stopped_reason = -1
capture & rethrow on Wait()

调用方 `WaitDriveTask` 在 `Monitor.Wait(wait)` 上阻塞直到完成。
Caller `WaitDriveTask` blocks on `Monitor.Wait(wait)` until completion.

== 最小 Movement / Minimal Movement ==
<syntaxhighlight lang="csharp">
using ClumsyCore.Pilot;
using ClumsyCore.DrivePlans;
using System.Collections.Generic;

public class MyStraight : MovementDefinition
{
public float dx, dy; // displacement
public float basespeed = 600; // mm/s

public override IEnumerable<bool> Get()
{
var sx = currentX; // pose at start
var sy = currentY;
var driver = new SteeringLineFollowing
{
srcX = sx, srcY = sy,
dstX = sx + dx, dstY = sy + dy,
basespeed = basespeed
};
foreach (var t in driver.Follow()) yield return t;
}
}
</syntaxhighlight>

== [MovementTest] 属性 / Attribute ==
'''目标''' / Target: 类 / class

'''效果''' / Effect: 在 Clumsy 测试 UI 注册一个 ''测试按钮''；按下立即在车上跑这个 Movement（车应静止 / 在仿真）。
Registers a test button in the Clumsy UI; pressing it runs the Movement on a stationary (or simulated) vehicle.

<syntaxhighlight lang="csharp">
[MovementTest(name = "测试我的直线 / Test my line")]
public class MyStraight : MovementDefinition { ... }
</syntaxhighlight>

== 可用原语 / Primitive library ==
Movement 通常 ''组合''下层原语而不是从零写控制律。下面是仓库里现成的：
Movements usually compose lower-level primitives rather than implement control law from scratch.

=== ClumsyCore/Legacy/（几何跟踪基础） ===
{| class="wikitable"
! Primitive !! 用途 / Use
|-
| `SteeringLineFollowing` || 阿克曼正向纯跟踪
|-
| `SteeringLineFollowingReverse` || 阿克曼反向跟踪
|-
| `OmniWheelTracking` || 全向轮速跟踪
|-
| `LeftRightWheelTracking` || 差速轮速跟踪
|-
| `OmniBezierTracking` / `LeftRightBezierTracking` || Bezier 曲线跟踪
|-
| `TrajectoryReplanningObstacleAvoidance` || 动态避障
|}

=== ClumsyDance/Movements/（行为聚合） ===
{| class="wikitable"
! Movement !! 用途 / Use
|-
| `SlotFollowing` || 槽位跟踪（叉车叉孔 / KIVA 腿对）
|-
| `ReflexDock` || 反射式对接
|-
| `KivaFollowShelfOfManyLegs` || 多腿料架导航
|-
| `TopHatFollowing` || 礼帽形特征跟踪
|-
| `BezierMPC` || Bezier 参考的 MPC
|-
| `LRWheelOdometryCalculator` || 编码器积分助手
|}

=== ClumsyDance/Detectors/（感知） ===
{| class="wikitable"
! Detector !! 用途
|-
| `LidarDetectTray` || 通用托盘检测（2 腿 / 3 腿可调）
|-
| `Lidar2dDetect2LegTray`, `Lidar2dDetect3LegTray`, `Lidar3dDetectTray` || 特化变体
|-
| `Cam3dDetectTray` || 3D 相机检测
|}

== MovementDefinition<T> 泛型变体 / Generic variant ==
当 Movement 需要 ''返回''一个对象（如已配置好的子 Movement）：
When a Movement needs to ''return'' a typed handle (e.g. a pre-configured sub-Movement):

<syntaxhighlight lang="csharp">
public class BuildFollower : MovementDefinition<SteeringLineFollowing>
{
public float srcX, srcY, dstX, dstY;
public override IEnumerable<SteeringLineFollowing> Get()
{
yield return new SteeringLineFollowing
{
srcX = srcX, srcY = srcY,
dstX = dstX, dstY = dstY,
basespeed = 800
};
}
}
</syntaxhighlight>

== 异常 + 中止 / Exceptions & abort ==
* `Get()` 内抛异常 → `DriveTask.Wait()` 返回时 ''重新抛出''。
* `PilotBase.SecurityCheck()` 在没收到控制信号超时（默认 300 ms）时调 `DriveStop()`；当前 Movement 的 enumerator 不会再被推进，但 ''资源清理责任在 Movement 作者''（在 yield 前后包 try/finally）。
* 调用者按 `WaitDriveTask(...)` 同步等；要异步用 `DriveTask.WaitDriveTask` 包在另一线程或 `SimpleAgvInterface.Queue`。

Exceptions from `Get()` re-throw when `WaitDriveTask` returns. The watchdog (`SecurityCheck`, default 300 ms timeout) calls `DriveStop()`; the enumerator stops being advanced but Movement-owned cleanup is on the author (wrap in try/finally).

== 与 Pilot 的关系 / Relation to Pilot ==
* `PilotBase` 是 Movement 的 ''宿主进程上下文''（提供 pose、IDriveWriter 等）。
* `PilotDefinition<T>` 加 typed config。
* 95% 的车型定制不用碰 PilotBase —— 写 Movement 就够。

`PilotBase` is Movement's ''host context'' (pose, drive writers); `PilotDefinition<T>` adds typed config. 95% of customisation only needs Movements.

== 常见错误 / Gotchas ==
* '''在 `Get()` 用 `Thread.Sleep`''' → 阻塞 DriveTask 线程，定时器漂移。正确方式：`yield return` 多次。 
Don't `Thread.Sleep` inside `Get()`; just `yield return` multiple times.
* '''Movement 跨实例共享状态''' → Movement 应是 ''可重入''的；不要用 static 字段保存进度。 
Movements should be reentrant; don't use static fields for progress.
* '''忘了在不需要继续时 `yield break`''' → 看起来在原地踏步。
* '''构造时读 pose''' → 应在 `Get()` 第一帧读，避免构造与执行间车移动了。 
Read pose inside `Get()`, not in the ctor — otherwise the car may have moved.

== 相关页面 / See also ==
* [[Special:MyLanguage/巡线行走|巡线行走]]
* [[Special:MyLanguage/绕障行走|绕障行走]]
* [[Special:MyLanguage/DriveTask调度循环|DriveTask调度循环]]
* [[Special:MyLanguage/SimpleAgvInterface Queue机制|SimpleAgvInterface Queue机制]]
* [[Special:MyLanguage/车体抽象原理|车体抽象原理]]
* [[Special:MyLanguage/Clumsy-API|Clumsy-API]]

[[Category:二次开发相关说明]]
[[Category:运动控制使用手册]]

MDCS跨切面约定

2026-05-16T14:00:19Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
本页汇总 MDCS 平台 ''跨子系统''的约定 —— 命名、线程、错误处理、版本、文件布局。新加入团队或修改核心代码前先读这里。

This page collects MDCS-wide ''cross-cutting conventions'' — naming, threading, error handling, versioning, file layout. Read this before joining the team or modifying core code.

== 命名约定 / Naming conventions ==
{| class="wikitable"
! 实体 / Entity !! 约定 / Convention !! 例 / Example
|-
| Medulla 插件入口类 / Medulla plugin entry || `MainIOObject`（严格大小写）|| `LidarController.MainIOObject`
|-
| 插件文件夹（一方）|| `D:\src\M2\OfficialPlugins\<VendorModel>\` || `OfficialPlugins\LidarController\`
|-
| 引用程序集 / Reference DLL || `Ref<Name>.dll` || `RefMedullaCore.dll`
|-
| Simple 车型类 / Simple car class || 用 `[CarType]` 属性，类名任意 || `[CarType] public class LB14 : ClumsyCar`
|-
| DObject 槽名 / DObject slot name || `<Producer><Tag>` || `MedullaCartLowerIO<tag>`
|-
| Wiki 页 / Wiki page || 现有约定：`开发手册 - ...`, `使用手册 - ...`, `XXX适配案例`, `XXX技术概述` || `开发手册 - SimpleComposer界面开发 - CAD工具`
|-
| 上下位 IO 字段 / IO field || 上位 `*Cmd`，下位 `*Est`（或更具体的 `*OK`, `*Pct` 等）|| `vCmd`, `vEst`, `batteryPercent`
|}

== 线程约定 / Threading conventions ==
* '''LadderLogic''' 每个 `[UseLadderLogic]` 类自己的线程；threads 共享 CartDefinition 字段，自行同步。
* '''DriveTask''' 每个 Movement 自己的线程（`ThreadPriority.AboveNormal`）。
* '''DObject `Wait()`''' 阻塞当前线程；要并行多源就开多线程。
* '''CycleGUI Draw 调用''' 从任意线程都安全（内部 marshall 到 UI 线程）。
* '''SimpleComposer Nancy 处理器''' 在 Nancy 线程池跑；不要长阻塞。
* '''Tasks''' 多用 `async`/`await`；尽量避免 `Task.Run`（除非 explicit 后台计算）。

* LadderLogic, DriveTask each have own thread.
* DObject `Wait()` is blocking; parallelise across sources via worker threads.
* CycleGUI Draw is thread-safe.
* Nancy handlers run on Nancy's thread pool; no long blocks.
* Use `async/await`; avoid `Task.Run` unless explicit background work.

== 错误处理三层 / 3-layer error model ==
=== Layer 1 — 插件级 / Plugin-level ===
`[UseLadderLogic(resume = true)]`（默认）捕获 `Operation()` 异常并在 `resumeRetryDelay` 后重试。日常 ''可恢复''错误用这一层。

The default `resume = true` catches LadderLogic exceptions + retries after `resumeRetryDelay`. Use for routine recoverable errors.

=== Layer 2 — 进程级 / Process-level ===
`Hedingben.ToastText(message, source)` 把异常呈现给操作工。逻辑能继续但人需要知道时用。

`Hedingben.ToastText` surfaces errors as UI toasts. Use when logic can proceed but the human should know.

<syntaxhighlight lang="csharp">
catch (Exception e)
{
Hedingben.ToastText($"Failed: {e.Message}", $"{Name}:ERR");
}
</syntaxhighlight>

=== Layer 3 — 看门狗级 / Watchdog-level ===
Wawa（[[Special:MyLanguage/看门狗Wawa使用说明|看门狗Wawa使用说明]]）是进程监控；进程崩了会重启。对应"世界着火"级别的错误 —— 让它 `throw`，让 watchdog 接手。

Wawa is the process watchdog. For "the world is on fire" — `throw` and let the watchdog restart.

=== 选层 / Picking the right layer ===
{| class="wikitable"
! 情况 / Situation !! 用哪层 / Use
|-
| PLC 通讯偶尔超时 || Layer 1（resume + 重试）
|-
| 雷达连接断开 || Layer 1（重连循环）+ Layer 2（toast）
|-
| 关键传感器永久失效 || Layer 2（toast）+ 把 `eStop = true`
|-
| 内存溢出 / panic || Layer 3（throw → watchdog 重启）
|}

不要 ''同时''做三层 —— 选最合适的。
Don't do all three; pick the right one.

== 版本与助记词 / Versioning ==
每次修改编译产物：
Every modification of a compiled artefact:

* `AssemblyInformationalVersion` 加 ''单词助记词'' ：`1.4.0+kindling`
* 下次改：`1.4.1+lantern`
* 助记词 ''单一''单词；不要 hyphen / 空格

或用 `[ReplaceWithCompileInfo]` —— LessokajiWeaver 自动注入时间戳 + git hash。
Or `[ReplaceWithCompileInfo]` — auto-inject timestamp + git hash.

目的：现场调试时区分两个数字看起来一样的二进制。
Purpose: visually disambiguate field binaries with same number.

== 文件 / 路径约定 / Path conventions ==
{| class="wikitable"
! 用途 / Use !! 约定路径 / Convention
|-
| 临时工作文件 / 草稿 || `D:\src\ai-deck\<project>\` （非 repo 根；可丢弃）
|-
| 项目级开发日志 || `D:\src\<repo>\DEV_LOG.md`（仓库根；append-only）
|-
| 插件 csproj 引用 / HintPath || `..\tools\Ref<Name>.dll`
|-
| 部署时 plugin 位置 || `medulla/plugins/<vendor>/<plugin>.dll`，`simplecomposer/plugins/`
|-
| startup 脚本 || `startup.iocmd`（Medulla CWD）
|-
| SLAM 地图文件 || `*.2dlm` / `*.gtex` / `*.gtm` / `*.memslam` / `tagmap.json`
|-
| DObject 录制 || `.dorec`
|-
| 日志 / Logs || `logs/<YYYY-MM-DD>.log`（DLog）+ `hedingben.log`
|}

== DEV_LOG.md ==
仓库根 `DEV_LOG.md` 是 ''append-only''的开发日志：
The `DEV_LOG.md` at each repo root is the '''append-only''' dev log:

* 每条新条目追加到末尾，绝不修改旧条目。
* 重要发现用前缀：`【发现】 / 【注意】 / 【灵感】`
* 编译产物的版本助记词也记在这里。

DEV_LOG 的目的是让 ''下一个读者''（也许 6 个月后的自己）能复原当时的判断。
DEV_LOG's goal: the next reader (maybe you in 6 months) can reconstruct the decisions.

== 注释风格 / Comment style ==
* '''头部注释稀疏''' —— 代码应自解释。
* '''中文注释常见'''于领域特定处（运动学、标定、传感）。
* '''关键代码用 ''发现''标记''' —— 文件里也用 `// 【发现】 ...` 提醒后续读者。

* Header comments sparse — code should be self-evident.
* Chinese comments are normal in domain-specific spots.
* `// 【发现】 ...` flags for important inline notes.

== 测试纪律 / Testing discipline ==
* 单元测试稀疏；机器人代码本质上靠 ''集成''测试。
* `D:\src\Fundamentals\Test\` 覆盖 DObject + DLog（最关键基础）。
* 多数"测试"通过 `[MovementTest]` / `[IOObjectUtility]` UI 按钮跑。
* '''改 DObject 后必跑 Fundamentals 单元测试''' —— IPC bug 灾难性。
* '''改 *Core 后跑仿真车 SimpleComposer 集成测试'''。

== 文档 / Documentation ==
* '''Wiki 是事实标准'''；代码注释 / DEV_LOG 是 ''临时记''。
* 公共 API 改动必同时 update wiki。
* 私下试验在 `ai-deck/`，不要污染 wiki。

== Git 约定 / Git ==
* Branch 名：`feature/<short-name>`, `fix/<issue>`, `release/<version>`
* Commit 消息含助记词与一句话变更摘要
* PR / MR 描述含：变更动机 + 关键决策 + 测试方法

== License / 许可 ==
* 客户机器绑定 license 由 `auth.lessokaji.com` 签发；`LessokajiProtect.dll` 在 Fundamentals。
* 开发机用 ''dev license''（无限期但带水印）。
* 不要在源码里 hardcode license / serial。

== 相关页面 / See also ==
* [[Special:MyLanguage/MDCS仓库布局与构建链|MDCS仓库布局与构建链]]
* [[Special:MyLanguage/插件契约与打包约定|插件契约与打包约定]]
* [[Special:MyLanguage/插件开发清单|插件开发清单]]
* [[Special:MyLanguage/核心开发指南|核心开发指南]]
* [[Special:MyLanguage/看门狗Wawa使用说明|看门狗Wawa使用说明]]
* [[Special:MyLanguage/通用约定|通用约定]] — 已有的"通用约定"页（业务侧）

[[Category:二次开发相关说明]]
[[Category:开发手册]]
[[Category:通识和入门教学]]

MDCS平台发布流程

2026-05-16T14:00:19Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
本页是 MDCS 平台 ''内核 + 一方插件 + 客户端''的发布流程。客户端单插件发布见 [[Special:MyLanguage/插件测试与发布|插件测试与发布]]。

This page covers MDCS '''kernel + first-party plugin + client''' release flow. Single-plugin release: see [[Special:MyLanguage/插件测试与发布|insert plugin testing & release]].

== 0. 准备 / Pre-flight ==
* 所有目标变更已合并到主分支
* 单元测试通过（特别是 `D:\src\Fundamentals\Test\`）
* 仿真车集成测试通过
* DEV_LOG.md 已记录本期所有 ''发现 / 注意 / 灵感''
* 已确认变更不破坏向后兼容（或明确标注 break）

== 1. 版本号 / Version bumping ==
按 ''SemVer + 助记词'' ：
SemVer + mnemonic:

* '''Major''' (`X.0.0+...`)：破坏性 API 变更 / breaking API change
* '''Minor''' (`x.X.0+...`)：新功能 / new features
* '''Patch''' (`x.x.X+...`)：bug 修复 / bug fix
* '''Mnemonic''' (`+lantern`)：每次构建唯一单词，便于现场区分

更新位置：
Update locations:

# 各仓库根 `Directory.Build.props` 中的 `<Version>`
# 各 csproj 中的 `<AssemblyInformationalVersion>`（含助记词）
# `CHANGELOG.md`（如果有）
# DEV_LOG.md 加一条发布条目

== 2. 构建顺序 / Build order ==
按依赖自底向上：
Bottom-up:

# `LessokajiWeaver` — `dotnet build -c Release`
# `Fundamentals` — 同
# `CycleGUI` —— C++ libVRender 先构建 + 复制 .dll 到 Windows / Linux 输出
# `M2` —— MedullaCore 先，OfficialPlugins 后
# `Detour` —— DetourCore，然后 Detour.exe（.NET 4.8）+ DetourLite.exe（.NET 8）
# `Clumsy` —— ClumsyCore，然后 ClumsyDance
# `Simple` —— SimpleCore，然后 SimpleComposer

每个仓库构建后：
After each:

* 验证 `Ref<Name>.dll` 已重新生成（如果公共 API 变了）
* 把新 Ref 复制到下游仓库的 `tools/` 目录
* 提交 Ref 到下游仓库的 git

== 3. 烟雾测试 / Smoke tests ==
=== 单元 / Unit ===
<syntaxhighlight lang="bash">
dotnet test D:\src\Fundamentals\Test\
</syntaxhighlight>

特别盯 DObject 测试 —— IPC bug 灾难性。
Watch DObject tests especially — IPC bugs are catastrophic.

=== 集成 / Integration ===
仿真车 SimpleComposer ：
SimpleComposer with virtual car:

# 启动 Medulla + 仿真 `Lidar + Cart` 插件
# 启动 DetourLite
# 启动 SimpleComposer，加载场景
# 派 5–10 个混合任务
# 观察 Hedingben 是否有红色 toast
# 检查任务完成率 100%

=== 现场冒烟 / Site smoke ===
（可选 / 大改动时必做）在 ''一辆真车''上跑核心场景：
(For major changes) run the core scenarios on one real vehicle:

* 巡线行走
* 自动识别工位并取放货
* 充电流程
* 异常停 + 恢复

== 4. 一方插件重建 / Rebuild first-party plugins ==
所有 `D:\src\M2\OfficialPlugins\*` 都引用核心 Ref。任何核心 API 变更都要求：
All first-party plugins reference core Refs. Any core API change requires:

# 拉取最新核心仓库
# `dotnet build -c Release` 各插件
# 在干净 Medulla 控制台测试加载（确保 Costura 内嵌没问题）
# 把生成的 `<plugin>.dll` 复制到发布 staging

== 5. 打包 / Bundle ==
=== Medulla bundle ===
<pre>
medulla-<version>.zip
├── MedullaConsole.exe
├── MedullaCore.dll
├── plugins/
│ ├── LidarController/LidarController.dll
│ ├── CartActivator/CartActivator.dll
│ ├── Camera/Camera.dll
│ └── ...
├── tools/
│ └── (运行时工具)
├── README.md
├── CHANGELOG.md
└── startup.iocmd.sample
</pre>

=== Detour bundle ===
<pre>
detour-<version>.zip
├── Detour.exe (or DetourLite.exe)
├── DetourCore.dll
├── CycleGUI.dll
├── libVRender.dll
├── README.md
└── CHANGELOG.md
</pre>

=== SimpleComposer bundle ===
<pre>
simplecomposer-<version>.zip
├── SimpleComposer.exe
├── SimpleCore.dll
├── plugins/ (空，客户填一方/三方车型 plugin)
├── README.md
└── CHANGELOG.md
</pre>

== 6. 发布到 dl.lessokaji.com ==
* 上传 3 个 bundle 到 `dl.lessokaji.com`（内部 SFTP / S3）
* 路径：`releases/<component>/<version>/`
* 在 `auth.lessokaji.com` 注册新版本（用于授权门控）

== 7. 文档更新 / Documentation update ==
* Wiki 发布说明：`wiki/Detour版本发布记录`，Medulla / Simple 各自的发布说明页
* 主页 `首页` 更新版本徽章（如有）
* HOW_TO_USE.md / HOW_TO_CUSTOMIZE.md / HOW_TO_DEV_CORE.md（在 `D:\src\cookbook\`）

== 8. 通知 / Notify ==
* 内部团队：邮件 + Slack / 微信群通知
* 客户：按其升级合约的节奏；major 变更要预约升级窗口
* CHANGELOG 高亮 ''行为变更''（不只是 "fix bug"）

== 9. 回滚预案 / Rollback plan ==
每个 bundle 至少保留 ''前一版本''可下载。客户回滚：
Keep at least the prior version available. Client rollback:

# 停服务
# 替换为旧 bundle
# 启动；验证关键场景

''数据''兼容：
Data compatibility:
* DObject 协议（FundamentalLib 版本哈希）必须兼容；否则需重启全套
* SLAM 地图文件：通常向后兼容
* SimpleComposer 场景 JSON：通常向后兼容
* Plugin 接口（Ref assembly）：major 变更不兼容；minor 兼容

== 10. 发布后 / Post-release ==
* 在 ''新版本'' Medulla 控制台跑一遍 `io load` + `cart Init` + 核心场景，做最后冒烟。
* 收集第一周客户反馈到 ''发布后看板''。
* DEV_LOG.md 加 "release N+0day notes"。

== 11. 紧急补丁 / Emergency patch ==
* 直接在 `release/<X.Y>` 分支上 fix
* Patch 版本号 + 助记词
* 通过 ''快速通道''跳过部分 smoke（在 hot incident 时）
* 但 ''必须''跑 DObject 单元测试

== 12. 大版本规划 / Major version planning ==
* Pre-release ''alpha / beta''先给 ''友好客户''
* Beta 周期 ≥ 2 周
* Public release 必须有 ''迁移文档''（旧 → 新 API）

== 相关页面 / See also ==
* [[Special:MyLanguage/MDCS仓库布局与构建链|MDCS仓库布局与构建链]]
* [[Special:MyLanguage/MDCS跨切面约定|MDCS跨切面约定]]
* [[Special:MyLanguage/插件测试与发布|插件测试与发布]]
* [[Special:MyLanguage/Detour版本发布记录|Detour版本发布记录]]
* [[Special:MyLanguage/核心开发指南|核心开发指南]]

[[Category:开发手册]]
[[Category:二次开发相关说明]]

MDCS仓库布局与构建链

2026-05-16T14:00:17Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
MDCS 由 7 个并列仓库组成；按依赖关系自底向上构建。本页详述各仓库职责、产物、构建顺序、引用程序集机制。

MDCS consists of 7 sibling repositories built bottom-up by dependency. This page details responsibilities, outputs, build order, and the reference-assembly mechanism.

== 仓库一览 / Repositories ==
{| class="wikitable"
! 仓库 / Repo !! 解决方案 / Solution !! 产物 / Output !! 角色 / Role
|-
| `D:\src\Fundamentals\` || Fundamentals.sln || FundamentalLib.dll, FundamentalLib2.dll, LessokajiProtect.dll, LessokajiLicencer.dll || 通用类型 + IPC + 日志 + 许可
|-
| `D:\src\LessokajiWeaver\` || LessokajiWeaver.sln || LessokajiWeaver.Fody.dll, LessokajiWeaverUtilities.dll || 编译期 IL 注入（Fody）
|-
| `D:\src\CycleGUI\` || CycleGUI.sln || CycleGUI.dll, libVRender.dll（C++/Vulkan）, webVRender（WASM）|| 懒协程 UI 框架
|-
| `D:\src\M2\` || M2.sln || MedullaCore.dll, OfficialPlugins/*.dll || 硬件抽象内核 + 一方插件（雷达 / 相机 / Cart）
|-
| `D:\src\Detour\` || Detour.sln || Detour.exe（.NET 4.8 GUI），DetourLite.exe（.NET 8 headless），DetourCore.dll || 定位系统
|-
| `D:\src\Clumsy\` || Clumsy.sln || ClumsyCore.dll, ClumsyDance.dll || 车载自动驾驶
|-
| `D:\src\Simple\` || Simple.sln || SimpleCore.dll, SimpleComposer.exe（Nancy HTTP）|| 车队管理
|}

== 依赖图 / Dependency graph ==

Fundamentals ◄────────── (everything)
▲
│
CycleGUI ◄─ Detour ─── (M2, Clumsy, Simple use indirectly)
▲ ▲
│ │
M2 ◄────── Clumsy ◄── Simple
▲
└─── LessokajiWeaver (build-time only)

== 构建顺序 / Build order ==
自底向上 / Bottom-up:

# '''LessokajiWeaver''' — 构建时依赖（Fody 织入）
# '''Fundamentals''' — 用 Weaver
# '''CycleGUI''' — 用 Fundamentals；需 libVRender C++ 先构建
# '''M2 / MedullaCore''' — 用 Fundamentals + CycleGUI
# '''M2 / OfficialPlugins/\*''' — 用 MedullaCore
# '''Detour / DetourCore''' — 用 Fundamentals + CycleGUI
# '''Clumsy / ClumsyCore''' → '''ClumsyDance'''
# '''Simple / SimpleCore''' → '''SimpleComposer'''

每个仓库独立 .sln；可单独 `dotnet build` / 在 IDE 打开。
Each repo has its own .sln; independently buildable.

== 引用程序集机制 / Reference-assembly mechanism ==
=== 概念 / Concept ===
每个核心 DLL 同时产生一个 ''仅引用''的程序集 `Ref<Name>.dll`，通过 [[https://github.com/JetBrains/Refasmer refasmer]] 工具生成。

Each core DLL also emits a '''reference-only assembly''' (`Ref<Name>.dll`) via refasmer.

例如 `MedullaCore.dll` → `RefMedullaCore.dll`：后者只含 public/protected API 签名，没有方法体。
E.g. `MedullaCore.dll` → `RefMedullaCore.dll`: signature-only.

=== 为什么 / Why ===
插件 csproj ''引用'' `Ref<Name>.dll`，不引用 impl DLL ：
Plugin csproj references the `Ref` assembly:

* 插件构建不会拉入 Costura 织入的传递依赖（FodyWeavers.xml + LessokajiWeaver 等）。
* 公共 API 由 Ref assembly 固定 —— `internal` 成员对插件不可见，强制良好的封装。
* 插件 DLL 体积小、加载快。

* No Costura transitives pulled into plugin builds.
* Public API frozen by the Ref assembly; `internal` hidden from plugins — enforced encapsulation.
* Smaller plugin DLLs, faster load.

=== 生成 / Generation ===
每个核心 csproj 有 ''AfterBuild'' 目标调 refasmer，输出到 `<repo>/tools/Ref<Name>.dll`：

<syntaxhighlight lang="xml">
<Target Name="GenerateRefAssembly" AfterTargets="Build">
<Exec Command="refasmer $(TargetPath) -o $(SolutionDir)tools\Ref$(AssemblyName).dll" />
</Target>
</syntaxhighlight>

详见 `D:\src\M2\OfficialPlugins\CartActivator\CartActivator.csproj:47-54`。

=== 更新流程 / Update flow ===
改动 `MedullaCore` 公共面 → 重新 build → 同时 ''rebuild Ref assembly'' → 把 ''两个 DLL''（impl + ref）都提交到仓库。

Change `MedullaCore` public surface → build → rebuild Ref → commit '''both'''.

【注意】插件 csproj 用旧 `Ref` 构建 ''不会出错''，但运行时调新成员会 `MissingMethodException`。 
A plugin built against the old Ref doesn't fail to compile but throws `MissingMethodException` at runtime when calling the new member.

== `tools/` 目录约定 / `tools/` directory convention ==
每个仓库根有 ''`tools/`'' 子目录，存放 ''其它仓库的 Ref assembly'' + 二进制工具（refasmer.exe 等）。插件 csproj 通过相对 HintPath 引用：

Each repo root has a `tools/` subdirectory containing reference assemblies from other repos + binary tools (refasmer.exe). Plugin csproj uses relative HintPaths:

<syntaxhighlight lang="xml">
<Reference Include="RefFundamentalLib">
<HintPath>..\tools\RefFundamentalLib.dll</HintPath>
</Reference>
</syntaxhighlight>

【发现】 `..\tools\` 是 ''仓库一致''约定 —— 每个 MDCS 插件 csproj 都这么写。不要改成 NuGet 包；现有工具链不支持。
The `..\tools\` HintPath pattern is repo-wide. Don't try to NuGet-ify it.

== Costura.Fody 胖 DLL 打包 / Fat DLL packaging ==
插件 / 客户端 exe 用 ''Costura.Fody''把所有依赖打到一个 DLL 的 base64 资源里。最终客户只需要 1 个文件。
Plugins / client exes use Costura.Fody to embed all deps as base64 resources in one DLL. Customer deploys one file.

注意：
* '''核心 DLL（MedullaCore, ClumsyCore, ...）不用 Costura'''。它们要被多个插件 ''共载''，loose DLL 必要。
* '''插件 / 顶层 exe 用 Costura'''。简化部署。

Note: '''Core DLLs (MedullaCore, ClumsyCore, ...) must not use Costura''' — they need to be shared between plugins. '''Plugins / top-level exes use Costura''' for deployment simplicity.

== LessokajiWeaver 编译期注入 / Compile-time IL injection ==
Fody 加上 `LessokajiWeaver.Fody.dll` 在编译后做 IL 重写。当前生效的规则：
Fody + `LessokajiWeaver.Fody.dll` rewrites IL post-compile. Active rules:

* `[AsInitParam] / [AsUpperIO] / [AsLowerIO]` 字段 → 自动同步 DObject 的 property
* `[ReplaceWithCompileInfo]` 字段 → 编译时戳 + git 哈希
* `[Translatable] / [T(zh=, en=)]` 字段 → getter 按 `CultureInfo.CurrentUICulture` 分派

详见 [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]] 与 [[Special:MyLanguage/如何使用LessokajiWeaver的多语言功能|如何使用LessokajiWeaver的多语言功能]]。

== 跨平台 / Cross-platform ==
* 多数仓库 .NET 6/8，部分 .NET Framework 4.8（旧 lidar driver / Detour.exe）。
* Linux 支持：Medulla, Detour (Lite), Clumsy, SimpleComposer 都可跑。
* CycleGUI 的 libVRender 在 Linux 上有 build；Windows 是主战场。

== 仓库间集成测试 / Cross-repo integration ==
没有单一 mega-solution。集成测试靠：
There's no monolithic solution. Integration tests rely on:

# 改动核心后重 build 所有受影响插件。
# 在仿真车 SimpleComposer 里跑完整任务序列。
# `D:\src\Fundamentals\Test\` 单元测试（DObject + DLog 等关键基础）。

== 仓库镜像 / Repo mirror ==
* 内部 git：`git.lessokaji.com`（私有）。
* 下载站：`dl.lessokaji.com`（编译产物）。
* 认证 / 许可：`auth.lessokaji.com`。

== 相关页面 / See also ==
* [[Special:MyLanguage/核心开发指南|核心开发指南]]
* [[Special:MyLanguage/MDCS跨切面约定|MDCS跨切面约定]]
* [[Special:MyLanguage/MDCS平台发布流程|MDCS平台发布流程]]
* [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]]
* [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]]
* [[Special:MyLanguage/Detour软件架构|Detour软件架构]]
* [[Special:MyLanguage/Simple软件架构|Simple软件架构]]

[[Category:开发手册]]
[[Category:二次开发相关说明]]

LadderLogic框架

2026-05-16T14:00:15Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
'''LadderLogic''' 是 Medulla 提供的 ''周期循环宿主''。CartDefinition 插件用嵌套类 `: LadderLogic<MyCart>` + `[UseLadderLogic(IntervalMs = N)]` 声明一个定时执行的控制循环；框架按 N 毫秒间隔调用 `Operation(int iteration)`。多个循环可在同一 Cart 上共存，各自在独立线程。

'''LadderLogic''' is Medulla's ''cyclic-loop host''. A CartDefinition plugin declares a timed loop via a nested class `: LadderLogic<MyCart>` plus `[UseLadderLogic(IntervalMs = N)]`; the framework calls `Operation(int iteration)` every N ms. Multiple loops can coexist on one cart, each on its own thread.

实现：`D:\src\M2\OfficialPlugins\CartActivator\LadderLogic.cs:7-272`，属性定义 `D:\src\M2\OfficialPlugins\CartActivator\Attrs.cs:26-36`。
Implementation: `D:\src\M2\OfficialPlugins\CartActivator\LadderLogic.cs:7-272`; attribute at `Attrs.cs:26-36`.

== 最小骨架 / Minimal skeleton ==
<syntaxhighlight lang="csharp">
public class MyCart : CartDefinition
{
[AsUpperIO] public float vCmd;
[AsLowerIO] public float vEst;

public override void Init()
{
// connect to hardware here
}

[UseLadderLogic(IntervalMs = 50)]
public class Loop : LadderLogic<MyCart>
{
public override void Operation(int iteration)
{
// iteration == 0 on first tick after Init/restart
self.WriteToHw(self.vCmd);
self.vEst = self.ReadFromHw();
}
}
}
</syntaxhighlight>

== 属性参数 / Attribute parameters ==
{| class="wikitable"
! 字段 / Field !! 默认 / Default !! 含义 / Meaning
|-
| `logic: Type` || (自动)|| LadderLogic 子类（嵌套类自动绑定）
|-
| `scanInterval: int` (or `IntervalMs`)|| 50 || tick 周期（ms）
|-
| `realTime: bool` || false || 保留，暂未使用 / reserved
|-
| `resume: bool` || true || 异常后自动重启循环 / auto-restart on exception
|-
| `resumeRetryDelay: int` || 1000 || 重启前等多久（ms）
|-
| `timeoutInterval: double` || 10000 || 保留 / reserved
|}

== 生命周期 / Lifecycle ==

CartDefinition.Init() ← 你的初始化
│
▼
CartDefinition.createLadders() ← 反射扫 [UseLadderLogic]
│
▼ 对每个属性 / for each attribute
实例化 LadderLogic<T>, 注入 self = this
│
▼
创建 MultimediaTimer + 工作线程
│
▼ 周期触发 / every scanInterval ms
Operation(iteration: 0) ← 第一次 / first tick
Operation(iteration: 1)
Operation(iteration: 2)
...
│
▼ 异常时 / on exception
Hedingben.ToastText(...)
如果 resume=true 等 resumeRetryDelay 后重启 / resume after delay

== Tick 精度 / Tick precision ==
基于 MultimediaTimer（OS 决定，Windows 约 1–15 ms 分辨率）。
Based on MultimediaTimer; OS-dependent (~1–15 ms on Windows).

'''超时行为''' / Overrun: 若 `Operation()` 耗时 > scanInterval，下一 tick 排队执行（不丢 tick）。长期超时会累积延迟。
If `Operation()` exceeds scanInterval, the next tick queues behind (no tick skipping). Sustained overrun accrues latency.

【注意】不要在 `Operation()` 里阻塞 / sleep / 等 IO 超过 scanInterval。 
Don't block / sleep / wait IO longer than scanInterval inside `Operation()`.

== 多 LadderLogic 共存 / Multiple loops ==
一个 CartDefinition 可以有多个 `[UseLadderLogic]` 属性，每个一对独立的线程 + Timer：

A CartDefinition can declare multiple loops, each on its own thread:

<syntaxhighlight lang="csharp">
[UseLadderLogic(IntervalMs = 50)]
public class CtrlLoop : LadderLogic<MyCart> { ... } // motion control 50 Hz

[UseLadderLogic(IntervalMs = 200)]
public class BatteryLoop : LadderLogic<MyCart> { ... } // battery / telemetry 5 Hz

[UseLadderLogic(IntervalMs = 1000)]
public class DiagLoop : LadderLogic<MyCart> { ... } // health 1 Hz
</syntaxhighlight>

线程之间共享 cart 字段；如果同一字段同时被多个 loop 读写，自己处理同步（lock / Interlocked）。
Threads share cart fields; if multiple loops touch the same field, synchronise (lock / Interlocked).

== 内置工具方法 / Built-in helpers ==
`LadderLogic<T>` 基类提供以下状态机助手（`LadderLogic.cs:50-272`）：
The `LadderLogic<T>` base class offers these state-machine helpers (`LadderLogic.cs:50-272`):

{| class="wikitable"
! 方法 / Method !! 用途 / Use
|-
| `TriggerOnce(bool active, int millis, Action a)` || 信号持续 `millis` ms 后触发 `a()` 一次 / fire once after signal held `millis` ms
|-
| `WaitSignal(bool sig, int timeout)` || 等信号上升或超时 / wait for signal rising or timeout
|-
| `TriggerIfChanged<T>(Func<T> g, Action<T> h)` || 值变化触发 / fire when value changes
|-
| `FlipFlop<T>(ref T field, int millis, T[] vals)` || 周期切换值 / cycle values periodically (e.g. blinking LED)
|-
| `SwitcherTrigger(bool, Action, bool)` || 边沿触发一次 / edge-trigger one-shot
|-
| `ModSignal(Func<bool>, int delay, int span)` || 时间窗内信号检测 / time-window detection
|-
| `IsochronousFork(Action)` || "同步分叉"，一次只跑一个 / one-at-a-time async fork
|-
| `PriorityActions` || 高优先级动作执行器 / priority action runner
|-
| `DaemonVal(float send, float read, float r, int t, Action<bool>)` || 多变量一致性看门狗 / multi-var consistency watcher
|}

用这些替代裸 `if (Math.Abs(now - lastEvent) > T) ...` 的散乱时间状态机。

Use these helpers to replace ad-hoc `if (Math.Abs(now - lastEvent) > T) ...` time state-machines scattered through the loop.

== 错误传播 / Error propagation ==
* `Operation()` 抛异常 → 框架捕获 → log 到 DLog + Hedingben toast `"Ladder broken: <msg>"` 在 UI 显示。
* 若 `resume = true`：等 `resumeRetryDelay` 后重新调用 `Operation(iteration: 0)`（iteration 重置）。
* 若 `resume = false`：循环退出，cart 进入"半工作"状态 —— 其它 loop 还在跑。

【发现】 `resume = true` 是默认值。一个 buggy 插件不会让整个进程崩，但会 ''无限重试'' —— 务必在开发期密切看 Hedingben。 
`resume = true` is the default. A buggy plugin won't crash the process but will silently retry forever — watch Hedingben during development.

== iteration 参数 / iteration parameter ==
* `iteration == 0`：首次 tick 或异常重启后的首次 tick；框架自动清空内部跟踪状态（如 `TriggerOnce` 的计时器）。
* `iteration > 0`：递增；可用来做 "每 N tick 做一次"。

== 调试 / Debugging ==
* `Hedingben` toast 是最直接的报错通道 —— 总打开。
* DLog 有详细 stack trace 用 `$ladder` 主题。
* 用 `[IOObjectMonitor]` 暴露 `iteration` 或自定义计数器到 Medulla dashboard 看跳速。

== 相关页面 / See also ==
* [[Special:MyLanguage/CartDefinition属性参考|CartDefinition属性参考]]
* [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]
* [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]]
* [[Special:MyLanguage/看门狗Wawa使用说明|看门狗Wawa使用说明]]

[[Category:开发手册]]
[[Category:二次开发相关说明]]

IOObject属性参考

2026-05-16T14:00:13Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
本页是 Medulla `IOObject` 基类与其上 ''全部装饰属性''的速查表。属性定义在 `D:\src\M2\MedullaCore\Types\IO.cs:9-70`。

This page is the cheat sheet for the Medulla `IOObject` base class and ''all its decorating attributes''. Attribute definitions at `D:\src\M2\MedullaCore\Types\IO.cs:9-70`.

== IOObject 基类 / IOObject base ==
{| class="wikitable"
! 成员 / Member !! 类型 / Type !! 含义 / Meaning
|-
| `Name` || `string` || 实例名（由 startup.iocmd 加载时设置）/ instance name set by the script engine on load
|-
| `TimeoutThreshold` || `float = 500` || 预期更新间隔（ms）；框架不强制，插件自己用 / expected update interval, plugin-enforced
|-
| `Methods` || `string[]` || 反射回填的公共方法名 / reflection-backed; for UI auto-binding
|-
| `OpenUI(Terminal)` || virtual || 打开 UI 面板的钩子 / UI panel creation hook
|-
| `CloseUI()` || virtual || 关闭 UI / UI teardown
|-
| `SwitchTerminal(Terminal)` || virtual || 把 UI 迁移到新 Terminal / migrate UI to a new Terminal
|}

`MainIOObject` 类名是 Medulla 反射查找的硬约束（`MedullaIO.cs:299`）。
The class name `MainIOObject` is a hard-coded reflection lookup in `MedullaIO.cs:299`.

== 装饰属性 / Decorating attributes ==
=== [IOObjectMonitor] ===
'''目标''' / Target: 字段 / field

'''效果''' / Effect: 字段值导出到 CycleGUI 的属性栅格；如果 `VerboseLog = true`，每次变化记到 DLog。
Exports the field to CycleGUI's property grid; logs to DLog if `VerboseLog = true`.

<syntaxhighlight lang="csharp">
[IOObjectMonitor]
public float currentVelocity;

[IOObjectMonitor(desc = "电池剩余百分比 / Battery percentage")]
public int batteryPercent;
</syntaxhighlight>

=== [IOObjectUtility] ===
'''目标''' / Target: 方法（仅 ''零参数''）/ method (zero-arg only)

'''效果''' / Effect: 在 UI 的 "Actions" 组中显示为按钮。
Renders as a button in the UI's "Actions" group.

<syntaxhighlight lang="csharp">
[IOObjectUtility]
public void StartScan() { /* trigger device start */ }
</syntaxhighlight>

=== [IOObjectWebUtility] ===
'''目标''' / Target: 方法 / method

'''效果''' / Effect: 自动注册 HTTP 端点 `/<IOName>/<MethodName>`。
Auto-registers an HTTP endpoint `/<IOName>/<MethodName>`.

<syntaxhighlight lang="csharp">
[IOObjectWebUtility(type = WebUtilityType.API)]
public byte[] GetCurrentFrame() { /* return JSON or binary */ }

[IOObjectWebUtility(type = WebUtilityType.WebPage)]
public byte[] StatusPage() { /* return HTML */ }
</syntaxhighlight>

子类型 / Subtypes (`type` enum):
* `WebPage` — 返回 `byte[]`，作为完整页面 / returns `byte[]` as a full page
* `API` — JSON API
* `Utility` — 普通工具方法
* `DataChunk` — 大块二进制数据（流式 / chunked）

=== [IOObjectWatch] ===
'''目标''' / Target: 字段 / field

'''效果''' / Effect: 看门狗。当 JS 表达式 `jsWatcher` 在字段上为 true → 触发告警模板 `jsAlertTemplate`。
Watchdog. When the JS predicate `jsWatcher` on the field evaluates true → fires the alert template `jsAlertTemplate`.

<syntaxhighlight lang="csharp">
[IOObjectWatch(
watchVal = "value",
jsWatcher = "value < 10",
jsAlertTemplate = "Battery critically low: ${value}%",
jsAlertColorTemplate = "red",
holdIfAlert = true)]
public int batteryPercent;
</syntaxhighlight>

=== [IOObjectSerialize] ===
'''目标''' / Target: 类 / class

'''效果''' / Effect: 自定义序列化器。当前 build 未使用 / unused in current build.

<syntaxhighlight lang="csharp">
[IOObjectSerialize(Serializer = typeof(MyCustomSerializer))]
public class MyIO : IOObject { ... }
</syntaxhighlight>

== 与 CartDefinition 属性的区别 / vs CartDefinition attributes ==
注意 `[AsUpperIO] / [AsLowerIO] / [AsInitParam] / [UseLadderLogic]` 不是 `IOObject` 的属性 —— 它们属于 `CartDefinition`（位于 `CartActivator` 插件）。详见 [[Special:MyLanguage/CartDefinition属性参考|CartDefinition属性参考]]。

The `[AsUpperIO]` / `[AsLowerIO]` / `[AsInitParam]` / `[UseLadderLogic]` attributes are NOT on `IOObject` — they live in the `CartActivator` plugin's `CartDefinition` family. See [[Special:MyLanguage/CartDefinition属性参考|CartDefinition属性参考]].

== Web 端点路由 / Web endpoint routing ==
Medulla 启动 HTTP server（`Startup.cs:204-256`）后：
After Medulla starts its HTTP server:

* `GET /getIOs` — 列出所有加载的 IOObject + 它们的字段 + 方法 + 端点
* `GET/POST /<IOName>/<MethodName>` — 调用 `[IOObjectWebUtility]` 方法
* `GET /<IOName>/<FieldName>` — 读 `[IOObjectMonitor]` 字段（如果配置开放）

端口由 `MedullaIO.CPort` 控制（默认 8081 / `MedullaIO.cs:34`）。

Port controlled by `MedullaIO.CPort` (default 8081).

== 调试技巧 / Debug tips ==
* '''字段不出现在 dashboard''' → 检查 `[IOObjectMonitor]` 是否标在 ''public 字段''上。
* '''按钮不出现''' → `[IOObjectUtility]` 标在 ''public 零参数方法''上吗？
* '''Web 端点 404''' → IO 名是否正确？看 `/getIOs` 列表确认。
* '''告警不触发''' → `jsWatcher` 表达式语法错误是常见原因；用 `console.log(value)` 调试。

== 相关页面 / See also ==
* [[Special:MyLanguage/CartDefinition属性参考|CartDefinition属性参考]]
* [[Special:MyLanguage/插件契约与打包约定|插件契约与打包约定]]
* [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]]
* [[Special:MyLanguage/Medulla|Medulla]] / [[Special:MyLanguage/Medulla-API|Medulla-API]]

[[Category:二次开发相关说明]]
[[Category:开发手册]]

DriveTask调度循环

2026-05-16T14:00:12Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
`DriveTask` 是 Clumsy 内部把 [[Special:MyLanguage/MovementDefinition详解|`MovementDefinition`]] 的 ''迭代器''变成 ''周期控制循环''的工具。每次调用 `DriveTask.WaitDriveTask(IEnumerable<bool>)` ：
1. 起一条 ''新线程''（`ThreadPriority.AboveNormal`）。
2. 每隔 `Configuration.conf.DriveTaskInterval`（默认 20 ms）调一次 `enumerator.MoveNext()`。
3. 阻塞调用方直到迭代器结束（正常完成或异常）。

`DriveTask` is Clumsy's mechanism for turning a [[Special:MyLanguage/MovementDefinition详解|MovementDefinition]]'s iterator into a '''timed control loop'''. Each `DriveTask.WaitDriveTask(IEnumerable<bool>)` call:
1. Spawns a new thread at `ThreadPriority.AboveNormal`.
2. Calls `enumerator.MoveNext()` every `Configuration.conf.DriveTaskInterval` (default 20 ms).
3. Blocks the caller until the iterator ends (success or exception).

实现：`D:\src\Clumsy\ClumsyCore\DriveTask.cs:34-205`。
Implementation: `D:\src\Clumsy\ClumsyCore\DriveTask.cs:34-205`.

== 标准用法 / Standard usage ==
<syntaxhighlight lang="csharp">
DriveTask.WaitDriveTask(new SteeringLineFollowing
{
srcX = sx, srcY = sy,
dstX = dx, dstY = dy,
basespeed = 600
}.Follow());
// Returns when the Movement finishes (normal or thrown)
</syntaxhighlight>

== 循环细节 / Loop details ==

WaitDriveTask(IEnumerable<bool>) 入口:
│
▼
new DriveTask:
enumerator = iterable.GetEnumerator();
Thread(prio=AboveNormal) starts:
│
▼ 循环 / loop:
if (stopToken) break;
bool keepGoing = enumerator.MoveNext();
if (!keepGoing) { stopped_reason = 0; break; }
Thread.Sleep(DriveTaskInterval); // 20 ms 默认
│
▼ 退出 / exit (any cause):
Monitor.PulseAll(wait)
│
▼
WaitDriveTask blocks on Monitor.Wait(wait)
└─→ 醒来后检查 exception，重新抛 / wakes, rethrows captured exception if any

== `DoUntil` 并行检查 / Parallel termination check ==
`DoUntil(IEnumerable<bool> condition)` 起一条 ''并行''任务，独立轮询 `condition`；若 `condition.MoveNext()` 返回 true，停止主 Movement 并设置 `stopped_reason = stop_condition_id`：

<syntaxhighlight lang="csharp">
var driveTask = DriveTask.WaitDriveTaskBegin(new SteeringLineFollowing { ... }.Follow());
driveTask.DoUntil(new ObstacleCloseCheck { distThres = 200 }.Get());
driveTask.Wait(); // blocks; returns when either main Movement done OR DoUntil fires
</syntaxhighlight>

`stopped_reason` 区分了正常完成 (0)、`DoUntil` 触发（其条件 id）、异常 (-1)。
`stopped_reason` differentiates normal (0), `DoUntil` triggered (the cond ID), and exception (-1).

== 与 SecurityCheck 的关系 / Relation to SecurityCheck ==
`PilotBase.SecurityCheck()`（`D:\src\Clumsy\ClumsyCore\Pilot\PilotDefinition.cs:64-75`）是 ''独立''的看门狗，每个 Movement 都不感知它。SecurityCheck 监测：
* 当前 DriveTask 是否在 `Configuration.conf.DriveTaskTimeout`（默认 300 ms）内有控制信号产生。
* 若没有 → 调 `DriveStop()` 强制车停 → 主 DriveTask 的 `stopToken = true` → 下一 tick 退出循环。

【发现】 SecurityCheck 不杀 Movement 的 enumerator；它只是让 DriveTask 在下一 tick 退出循环。所以 ''Movement 作者需自己确保 `Get()` 在迭代器内可被中断''（不要 sleep 长时间）。 
SecurityCheck doesn't kill the enumerator; it just lets the loop bail next tick. Movement authors must keep `Get()` interruptible (no long sleeps).

== 异常传播 / Exception propagation ==
* `MoveNext()` 抛异常 → 捕获到 `_exception` 字段 → `stopped_reason = -1` → 触发 `Monitor.PulseAll`。
* `WaitDriveTask` 调用方 ''醒来后''重新抛该异常。
* 上游 `SimpleAgvInterface.Queue` 的 action 内异常 → 记到 `queueInfo[i].exception`，跳过本行剩余 action。

【注意】不要把异常 ''吞''在 Movement 内。让它传出，让上层决定恢复策略。 
Don't swallow exceptions inside Movements; let them propagate so the upper layer decides.

== Thread Priority 与延迟 / Thread priority & latency ==
* DriveTask 线程是 `AboveNormal`，比 LadderLogic 略高。
* tick 抖动主要来自 `Thread.Sleep` 精度（Windows ~1–15 ms 量级）。
* 高速 / 高精度场景（如 [[Special:MyLanguage/汽车面差检测|汽车面差检测]]）可能需要在 PLC 层做关键回路，DriveTask 仅做高层规划。

== 在 SimpleAgvInterface 中的使用 / Usage in SimpleAgvInterface ==
`SimpleAgvInterface.Queue` 的每个 action 内通常一次 `DriveTask.WaitDriveTask(...)`。详见 [[Special:MyLanguage/SimpleAgvInterface Queue机制|SimpleAgvInterface Queue机制]]。

Each action inside `SimpleAgvInterface.Queue` typically calls `DriveTask.WaitDriveTask` once.

== 配置 / Configuration ==
{| class="wikitable"
! 字段 / Field !! 默认 / Default !! 文件 / File
|-
| `DriveTaskInterval` || 20 ms || `D:\src\Clumsy\ClumsyCore\Configuration.cs`
|-
| `DriveTaskTimeout` || 300 ms || same
|-
| `basicSpeed` || 项目相关 || same
|}

从嵌入资源 `ClumsyCore.res.defaultconf.json` 加载，或用 `Configuration.FromFile(fn)` 覆盖。
Loaded from embedded `ClumsyCore.res.defaultconf.json` or overridden via `Configuration.FromFile`.

== 常见错误 / Common mistakes ==
* '''忘了 `WaitDriveTask` 是阻塞的''' → 在 UI 线程调会冻 UI。包到 `SimpleAgvInterface.Queue` 的 async action 里。
* '''Movement Get() 不 yield''' → 立即耗尽，DriveTask 立即返回，看起来"完成了 0 ms"。Always `yield return` at least once per control cycle.
* '''DriveStop 中无 vCmd = 0''' → 即使 enumerator 停了，最后一帧的 vCmd 还在 DObject 里，车继续动。在 `DriveStop()` 里显式清零所有 IDriveWriter 状态。

* `WaitDriveTask` is blocking; calling it on the UI thread freezes UI. Wrap in `SimpleAgvInterface.Queue`'s async action.
* If `Get()` never yields, DriveTask exits immediately.
* `DriveStop()` must explicitly zero all IDriveWriter outputs; otherwise the last frame's `vCmd` stays in DObject.

== 相关页面 / See also ==
* [[Special:MyLanguage/MovementDefinition详解|MovementDefinition详解]]
* [[Special:MyLanguage/SimpleAgvInterface Queue机制|SimpleAgvInterface Queue机制]]
* [[Special:MyLanguage/巡线行走|巡线行走]]
* [[Special:MyLanguage/绕障行走|绕障行走]]
* [[Special:MyLanguage/车体抽象原理|车体抽象原理]]
* [[Special:MyLanguage/Clumsy-API|Clumsy-API]]

[[Category:二次开发相关说明]]
[[Category:运动控制使用手册]]

DObject共享内存协议

2026-05-16T14:00:10Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
'''DObject''' 是 MDCS 的跨进程 ''命名共享内存 pub/sub'' 通讯原语。Medulla 把传感器数据、上下位 IO、调度状态等都通过 DObject 发布；Detour / Clumsy / SimpleComposer / 监控工具按名字订阅。整个 MDCS 的进程间通讯只有这一条总线。

'''DObject''' is MDCS's cross-process named-shared-memory pub/sub primitive. Medulla publishes sensor data, upper/lower IO, scheduler state via DObject; Detour / Clumsy / SimpleComposer / monitoring tools subscribe by name. It's the sole IPC bus in MDCS.

实现：`D:\src\Fundamentals\FundamentalLib\DObject.cs:18-344`。
Implementation: `D:\src\Fundamentals\FundamentalLib\DObject.cs:18-344`.

== 存储 / Storage ==
{| class="wikitable"
! 平台 / Platform !! 后端 / Backing
|-
| Windows || `MemoryMappedFile("io_shared", 256 MB)` + meta `MemoryMappedFile("io_shared_meta", 1024 B)`
|-
| Linux || `$TMPDIR/io_shared` 文件 / file-backed fallback
|}

容量 256 MB 是预分配上限；具体 DObject 槽按需扩展但不能超过总容量。

The 256 MB pool is preallocated; per-DObject slots grow on demand but the pool cap is hard.

== 二进制布局 / Binary layout ==

[meta 1024 B]
[magic: 4 B 0x90 0x97 0x92 0x96]
[FundamentalLib version hash: 4 B]
[process count: 1 B]
[PID list: 32 B (8 × int32)]
[reserved]

[payload area ≤ 256 MB]
slot 0:
[next_offset: int32]
[name_len: int32]
[name: ASCII (≤ 32 B)]
[size: int32]
[reserved: int32]
[payload: N B]
slot 1: same
...
EOF: next_offset = 0

== API ==
=== 构造 / Constructor ===
<syntaxhighlight lang="csharp">
var dobj = new DObject(string name, int defSize = 1024);
// name ≤ 32 chars; creates new slot or attaches to existing
</syntaxhighlight>

=== 写入 / Post ===
<syntaxhighlight lang="csharp">
dobj.Post(byte[] payload, bool recording = false);
// 1. acquires per-DObject named Mutex ("io_mutex_<name>")
// 2. Marshal.Copy(payload) into the slot
// 3. signals per-DObject EventWaitHandle (wakes all Wait())
// 4. if recording == true, also append to .dorec file
</syntaxhighlight>

=== 读取 / Read ===
<syntaxhighlight lang="csharp">
var reader = dobj.Reader(int offset, int len);
// reader is a delegate; on each invoke it:
// 1. acquires Mutex
// 2. copies [offset, offset+len) into a fresh byte[]
// 3. releases Mutex, returns the bytes
</syntaxhighlight>

=== 等待 / Wait ===
<syntaxhighlight lang="csharp">
bool gotNewFrame = dobj.Wait(int timeoutMs);
// blocks on the EventWaitHandle; returns true on signal, false on timeout
</syntaxhighlight>

== 并发模型 / Concurrency ==
* '''每 DObject 一把命名 Mutex''' (`io_mutex_<name>`) 保护 Post/Read 互斥。
* '''每 DObject 一个 EventWaitHandle''' 用于 `Wait()` 唤醒。
* Mutex + EventWaitHandle 都是系统级原语（Windows: 命名 Mutex + AutoReset Event；Linux: FSWEventWaitHandle）。
* 读者使用 `Wait` 阻塞到下次写入；轮询读取也 OK 但浪费 CPU。

* Per-DObject named Mutex protects Post/Read mutual exclusion.
* Per-DObject EventWaitHandle wakes `Wait()`.
* Both are kernel-level primitives — cross-process safe.

== 版本校验 / Version safety ==
Meta 块的第二个 4 字节存 ''FundamentalLib 编译哈希''。读取时若 `X.conf.EnsureFlibSame = true` 且哈希不匹配 → 抛异常。这能立刻发现"同一系统里加载了两个不同版本的 FundamentalLib"的灾难性 bug。

The meta block stores the compiling FundamentalLib's version hash. On read, if `X.conf.EnsureFlibSame = true` and the hash differs → throw. Catches the "two different FundamentalLib.dll versions loaded in one system" disaster bug.

【发现】这是 MDCS 调试中最有用的护栏 —— 重新构建 FundamentalLib 但忘了重建消费者时，立刻抛错。
The single most useful guardrail in MDCS debugging.

== 录制 / Recording ==
`dobj.Recording = true` 时每次 `Post()` 同时把数据追加到磁盘 `.dorec` 流。
With `dobj.Recording = true` every `Post()` also appends to a disk `.dorec` stream.

格式 / Format: `[name] [DateTime.ToBinary] [RND id] [length] [payload]`。

清理 / Cleanup: 按 ''年龄''（`RecordingKeepSeconds`）和 ''总磁盘大小''（`RecordingDiskSizeLimitMB`）双重边界，自动滚动。
Auto-cleanup bounded by both age (`RecordingKeepSeconds`) and total disk size (`RecordingDiskSizeLimitMB`).

回放工具见 [[Special:MyLanguage/使用手册 - 数据录制与回放手册|使用手册 - 数据录制与回放手册]]。

== 常见 DObject 槽 / Common slot names ==
{| class="wikitable"
! 名字 / Name !! 发布者 / Producer !! 订阅者 / Subscriber !! 内容 / Payload
|-
| `Lidar2D`（或厂商后缀）|| Medulla 雷达插件 || Detour || 打包的 `LidarOutput`（点云 + tick）
|-
| `pose` || Detour || Clumsy, SimpleComposer || 6-DoF 位姿 + 协方差 + tick
|-
| `MedullaCartLowerIO<tag>` || Medulla CartActivator || SimpleComposer || `[AsLowerIO]` 字段 JSON
|-
| `MedullaCartUpperIO<tag>` || SimpleComposer / Clumsy || Medulla CartActivator || `[AsUpperIO]` 字段 JSON
|-
| 自定义 || 任意 || 任意 || 自定义二进制
|}

== 使用模式 / Patterns ==
=== 写者侧 / Publisher pattern ===
<syntaxhighlight lang="csharp">
public class MyLidar : Lidar2DIOObject
{
void Loop()
{
while (true)
{
var cloud = ReadFromDevice();
cachedLidar = cloud;
frame += 1;
tick = DateTime.Now.Ticks;
output(); // 内部调用 dobj.Post(serializedCloud)
}
}
}
</syntaxhighlight>

=== 读者侧 / Subscriber pattern ===
<syntaxhighlight lang="csharp">
var dobj = new DObject("Lidar2D");
var reader = dobj.Reader(0, 8 * 1024); // expected payload size
while (true)
{
if (dobj.Wait(5000))
{
var bytes = reader();
var output = LidarOutput.Deserialize(bytes);
ProcessFrame(output.points);
}
else
{
Console.WriteLine("Lidar timeout!");
}
}
</syntaxhighlight>

== 注意事项 / Caveats ==
* '''DObject 名 ≤ 32 字符''' —— 超长会截断 / silently truncated.
* '''Post 是阻塞的''' —— 所有订阅者都未释放 Mutex 之前你写不进 / blocks while any subscriber holds the mutex.
* '''Reader 不重试''' —— 槽消失或重建时 reader 失效，需要重新 `new Reader`.
* '''跨主机不工作''' —— 同主机进程间专用 / Single-host only; not designed for cross-machine.
* '''256 MB 是硬限''' —— 大量大尺寸槽要监控用量 / monitor usage if many large slots.

== 相关页面 / See also ==
* [[Special:MyLanguage/DObject|DObject (legacy page)]]
* [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]]
* [[Special:MyLanguage/使用手册 - 数据录制与回放手册|数据录制与回放手册]]
* [[Special:MyLanguage/核心开发指南|核心开发指南]]

[[Category:开发手册]]
[[Category:二次开发相关说明]]

CartDefinition属性参考

2026-05-16T14:00:06Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
本页是底盘适配插件（`: CartDefinition`）所用的 ''全部属性的速查表''。这些属性住在 `CartActivator` 插件，由 LessokajiWeaver 在编译期注入实际行为。

This page is the cheat sheet for all attributes used in cart-adapter plugins (`: CartDefinition`). They live in the `CartActivator` plugin, with actual behaviour injected at compile time by LessokajiWeaver.

定义：`D:\src\M2\OfficialPlugins\CartActivator\Attrs.cs`。
Definitions: `D:\src\M2\OfficialPlugins\CartActivator\Attrs.cs`.

== 字段属性 / Field attributes ==
=== [AsInitParam] ===
'''目标''' / Target: 字段 / field

'''效果''' / Effect: 该字段成为 ''启动配置项''；可通过 startup.iocmd 或 JSON 配置传入；持久化到 LowerIO JSON 流。
The field becomes a ''startup config item''; settable from startup.iocmd or JSON config; persisted to the LowerIO JSON stream.

<syntaxhighlight lang="csharp">
[AsInitParam] public string plcIp = "192.168.0.100";
[AsInitParam] public int plcPort = 502;
[AsInitParam] public float wheelBase = 1320f;
</syntaxhighlight>

设置方式 / How to set:
<syntaxhighlight lang="text">
# startup.iocmd
cart.plcIp = "192.168.0.50"
cart.plcPort = 502
cart Init
</syntaxhighlight>

=== [AsUpperIO] ===
'''目标''' / Target: 字段 / field

'''效果''' / Effect: 上位 IO —— ''命令向下流''。Weaver 把字段重写为 property，setter 自动同步到 DObject `MedullaCartUpperIO<tag>`。
Upper IO — '''commands flowing down'''. Weaver rewrites the field as a property whose setter syncs to DObject `MedullaCartUpperIO<tag>`.

<syntaxhighlight lang="csharp">
[AsUpperIO] public float vCmd; // forward velocity command
[AsUpperIO] public float steerCmd; // steer angle command
[AsUpperIO] public bool brakeOn;
</syntaxhighlight>

调度 / Clumsy 写这些字段；CartDefinition 的 LadderLogic 读后写硬件。
Scheduler / Clumsy writes; the CartDefinition's LadderLogic reads + writes hardware.

=== [AsLowerIO] ===
'''目标''' / Target: 字段 / field

'''效果''' / Effect: 下位 IO —— ''状态向上流''。Weaver 把字段写入自动同步到 DObject `MedullaCartLowerIO<tag>`。
Lower IO — '''status flowing up'''. Field writes auto-sync to DObject `MedullaCartLowerIO<tag>`.

<syntaxhighlight lang="csharp">
[AsLowerIO] public float vEst;
[AsLowerIO] public float steerEst;
[AsLowerIO] public int batteryPercent;
[AsLowerIO] public bool eStop;
</syntaxhighlight>

LadderLogic 读硬件后写这些字段；调度 / Clumsy 订阅 DObject 读。
LadderLogic writes after reading hardware; scheduler / Clumsy subscribes to the DObject.

== 类属性 / Class attributes ==
=== [UseLadderLogic] ===
'''目标''' / Target: 嵌套类 `: LadderLogic<MyCart>` / nested class extending `LadderLogic<MyCart>`

'''效果''' / Effect: 启动一个独立线程 + Timer，按 `IntervalMs` 周期调用嵌套类的 `Operation()`。
Spawns an independent thread + Timer that calls the nested class's `Operation()` every `IntervalMs`.

详见 [[Special:MyLanguage/LadderLogic框架|LadderLogic框架]]。

参数 / Parameters:
{| class="wikitable"
! 字段 / Field !! 默认 !! 含义
|-
| `IntervalMs` (alias `scanInterval`) || 50 || tick 周期 (ms)
|-
| `resume` || true || 异常自动重启
|-
| `resumeRetryDelay` || 1000 || 重启前等多久 (ms)
|-
| `realTime` || false || 保留
|-
| `timeoutInterval` || 10000 || 保留
|}

可以在同一 CartDefinition 上重复声明 —— 多个循环共存。
Can be declared multiple times on the same CartDefinition for multiple concurrent loops.

=== [UseMedullaAPI] ===
'''目标''' / Target: 类 / class

'''效果''' / Effect: 启用 Medulla 高级 API（详细文档见 [[Special:MyLanguage/Medulla-API|Medulla-API]]）。
Enables Medulla higher-level APIs (see linked API page).

=== [UseManualController] ===
'''目标''' / Target: 类 / class

'''效果''' / Effect: 注册手动遥控器接管 —— 启用后操作工可用手柄覆盖自动控制。
Registers manual override — operator can take over autonomous control via a handheld.

== 调用契约 / Calling contract ==
=== 初始化顺序 / Init order ===

io load <plugin>.dll
→ MedullaIO.load() finds MainIOObject → new MainIOObject() (no hardware contact)

cart Init
→ Init() runs → connect to PLC / CAN / serial
→ CartDefinition.createLadders() introspects [UseLadderLogic]
→ for each ladder: spawn timer + thread
→ first Operation(iteration=0)
→ ...

【注意】构造函数必须 ''廉价且无副作用''。硬件接触放在 `Init()` 里。 
The ctor must be cheap and side-effect-free. Hardware contact lives in `Init()`.

=== DObject 同步时机 / DObject sync timing ===
* `[AsUpperIO]` 字段 setter 触发 DObject `Post`（命令向下）
* `[AsLowerIO]` 字段 setter 触发 DObject `Post`（状态向上）
* `[AsInitParam]` 一次性 JSON 注入；运行时改 ''不会''重新初始化硬件

第三条意味着：运行时改 `[AsInitParam]` 字段不会自动重连 PLC；需要重新 `cart Init`。 
Changing an `[AsInitParam]` field at runtime won't reconnect the PLC; you must re-`cart Init`.

== 还可以用 IOObject 系列属性 / IOObject attributes also apply ==
`CartDefinition` 继承 `IOObject`，所以 `[IOObjectMonitor] / [IOObjectUtility] / [IOObjectWebUtility] / [IOObjectWatch]` 都能用 —— 详见 [[Special:MyLanguage/IOObject属性参考|IOObject属性参考]]。

`CartDefinition` inherits from `IOObject`, so `[IOObjectMonitor] / [IOObjectUtility] / [IOObjectWebUtility] / [IOObjectWatch]` apply. See the IOObject reference.

== 常见错误 / Gotchas ==
* '''`[AsUpperIO]` 标在 `readonly` 字段上''' → 编译过，运行时 `MissingMethodException`（Weaver 注入 setter 与 readonly 冲突）。 
`[AsUpperIO]` on a `readonly` field → compiles, runtime `MissingMethodException`. Make it mutable.
* '''忘了 `cart Init`''' → ladder 没启动，但插件加载成功，看起来"工作"但 Lower IO 不更新。
* '''Init 抛异常''' → 部分 ladder 起来部分没起来；难以排查。在 Init 里捕获异常，设 `eStop = true` 而不是抛。 
Catch exceptions in `Init()`; set `eStop = true` instead of throwing.
* '''字段名冲突''' → 同名 `[AsUpperIO]` 和 `[AsLowerIO]` 用不同 setter，运行时迷惑。约定：上位字段加 `Cmd` 后缀，下位加 `Est` 后缀。 
Same-named fields with different IO directions confuse the runtime. Convention: upper = `*Cmd`, lower = `*Est`.

== 相关页面 / See also ==
* [[Special:MyLanguage/LadderLogic框架|LadderLogic框架]]
* [[Special:MyLanguage/IOObject属性参考|IOObject属性参考]]
* [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]
* [[Special:MyLanguage/叉车适配案例|叉车适配案例]]
* [[Special:MyLanguage/插件契约与打包约定|插件契约与打包约定]]

[[Category:二次开发相关说明]]
[[Category:开发手册]]

地纹SLAM

2026-05-16T11:44:38Z

Artheru：Redirect

#REDIRECT [[地纹SLAM技术概述]]

纯二维码导航

2026-05-16T11:43:15Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
"纯二维码导航"是 [[Special:MyLanguage/二维码识别导航|二维码识别导航]] 的极简变体：完全不使用激光 / 地纹 / 天花板 SLAM，仅靠地面二维码作为唯一定位源。它对仓库 / 工厂的改造代价最低，但限制也最多。

"Pure-QR navigation" is the minimal form of [[Special:MyLanguage/二维码识别导航|QR-based navigation]]: no laser SLAM, no ground-texture, no ceiling SLAM — only on-floor QR tags. It has the lowest deployment cost but the most restrictions.

== 适用场景 / When to use ==
* 单线性产线 / 单环路（车少、路径少）
* 改造成本 ''硬约束''的项目（不能停产装激光、不能挂相机）
* 简单业务，定位精度要求 ≥ ±20 mm 即可

== 与其它方案的对比 / vs others ==
{| class="wikitable"
! 项 / Item !! 纯二维码 / Pure-QR !! 二维码 + SLAM 混合 / Hybrid !! [[Special:MyLanguage/色带和磁条导航|色带 / 磁条]]
|-
| 部署成本 / Deploy cost || 最低 || 中 || 中
|-
| 路径灵活度 / Path freedom || 中（受二维码布点约束）|| 高 || 低（必须沿线）
|-
| 高速行驶 / High speed || 困难（视场必须见 ≥ 1 标签）|| 简单 || 简单
|-
| 重定位 / Re-loc || 即时（任一标签都行）|| 即时 || 困难
|-
| 维护 / Maintenance || 二维码贴布需保持完整 || 二维码 + SLAM 地图 || 色带 / 磁条
|-
| 失效 / Failure mode || 看不到标签 = 停车 || SLAM 兜底 || 离线 = 停车
|}

== 系统要求 / System requirements ==
* '''二维码密度''': 每 1.0–1.5 m 一个标签（车速 ≤ 1 m/s）；要求 ''任意时刻视场至少有 1 个标签''。
* '''标签精度''': 边长 100–150 mm；位姿标定误差 ≤ ±5 mm。
* '''下视相机''': 全局快门，30–60 FPS，IR 环形灯。
* '''地面平整度''': 起伏 ≤ ±5 mm（俯仰会让相机视场偏离）。
* '''车体速度上限''': 1 m/s（高速会因相机视场过短而丢标签）。

== 工作模式 / Operating modes ==
=== 站点对站点 / Site-to-site ===
每个 ''任务''指定 ''目标站点（一个二维码）''。AGV：
# 当前视场识别一个标签 X，反推车体位姿；
# 已知目标站点 Y 的二维码位置；
# 沿 X → Y 的预设路径走（每个相邻标签间是直线段）；
# 沿途连续识别中间标签做小修正；
# 抵达 Y 二维码时停车。

Each task names a target site (a QR). AGV reads its current tag X, computes pose, plans path along predefined tag-graph to Y, follows tag-by-tag updates, stops at Y.

=== 完全跟踪 / Continuous track ===
更高速场景：AGV 把多个标签 ''并行''识别，做平均位姿，连续控制车体姿态。仅当相机分辨率足够 + 标签间距足够小时可用。

For higher speeds: detect multiple tags simultaneously and average. Requires high camera resolution and dense tag layout.

== MDCS 集成 / MDCS integration ==
* '''Detour''': 只配 QR backend，关闭其它 SLAM。位姿协方差完全来自 QR PnP。
* '''Clumsy''': 巡线 Movement 一致；不同的是 ''没有 SLAM 兜底''，丢失任一标签 5 s 后必须停车。
* '''SimpleComposer''': 路径图直接对应 ''标签图''，每个标签 = 一个站点；段是相邻标签间的直线。
* '''调度''': DPS 交管仍然适用。

== 故障与恢复 / Failure & recovery ==
* '''丢标签''' / Tag-loss: 任何 ''2 s 内''看不到标签 → 减速；''5 s''仍无标签 → 停车 + 报警，等人工把车搬到任一标签上。
* '''标签污损''' / Tag damage: 每周巡检；自动检测置信度突然下降的标签并报告。
* '''误识别''' / Misread: PnP 重投影残差 > 2 像素的检测视为不可信。

* Tag-loss within 2 s → slow down; > 5 s → stop and alarm; operator must re-place on any tag.
* Weekly tag audit + automatic confidence-drop detection.
* PnP reprojection residual > 2 px is rejected.

== 部署建议 / Deployment tips ==
* 在交叉口前后各 3 个标签 ''密集''布点。
* 取放工位 ''正上方'' 1 个标签 + 距离 200 mm 外再 1 个，确保对位精确。
* 避免在车道狭窄处只有 1 个标签 —— 必须 ≥ 2 个冗余。
* 使用 ''可清洁覆盖膜''保护标签；磨损先损坏覆盖膜，不损坏标签本体。

== 已知边界 / Known limits ==
* 不能 ''高速跑长直线''：标签间距与车速成反比。
* 不能在 ''反光地面''（如抛光大理石）上用：相机看不清标签。
* 不能 ''跨楼层''：每层都要独立标签图。
* 现场如有大量振动 / 油污落到标签 → 频繁损耗，不建议。

== 相关页面 / See also ==
* [[Special:MyLanguage/二维码识别导航|二维码识别导航]]
* [[Special:MyLanguage/色带和磁条导航|色带和磁条导航]]
* [[Special:MyLanguage/使用手册 - 在地纹导航中使用二维码快速找回定位|地纹导航中使用二维码快速找回定位]]

[[Category:定位导航相关手册]]

清洁机器人

2026-05-16T11:43:12Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
清洁机器人是 MDCS 在 ''商业清洁 / 工业清洁''场景的应用：把自动驾驶 + 清洁工具（拖布、刷子、吸水扒、消毒喷雾）集成在一台 AGV 上，自动覆盖大面积地面。MDCS 提供其底盘 / 定位 / 调度的基础设施；清洁工具的协议是 ''厂商私有''，通过 Medulla 适配。

A cleaning robot is the MDCS application in ''commercial / industrial cleaning'': autonomous driving + cleaning tools (mop, brush, squeegee, disinfectant sprayer) on one AGV for large-area floor coverage. MDCS provides chassis / localisation / scheduling; cleaning-tool protocols are vendor-specific and adapted via Medulla.

== 业务场景 / Scenarios ==
* 大型仓库 / 工厂车间地面拖洗
* 商超 / 机场 / 地铁站清洁
* 食品厂 GMP 区域消毒
* 医院床下消毒
* 矿区粉尘清扫

== 与其它 AGV 的区别 / vs other AGV roles ==
{| class="wikitable"
! 项 / Item !! 清洁机器人 / Cleaning !! 仓储 AGV
|-
| 主要任务 / Primary task || ''面''覆盖 (full-coverage path) || ''点对点''
|-
| 路径 / Path || 弓形 / 螺旋 / 边缘 || A* / 流场
|-
| 速度 / Speed || 0.3–1 m/s || 1–2 m/s
|-
| 携带 / Payload || 水 / 化学品 || 货
|-
| 清洁完成度 / Completeness || 决定客户验收 || N/A
|-
| 失效成本 / Failure cost || 漏清污染 || 任务延误
|}

== 全覆盖规划 / Full-coverage planning ==
清洁机器人的核心是 ''覆盖路径''而不是 ''最短路径''。MDCS 在 SimpleCore 中支持几种覆盖策略：

The core problem is '''coverage planning''', not shortest-path:

{| class="wikitable"
! 策略 / Strategy !! 适用 / Suitable !! 实现 / Implementation
|-
| Boustrophedon (弓形) || 矩形区 / rectangular zones || 分解为 cell + 每 cell 弓形
|-
| 边缘 + 内填 / Wall-follow + fill || 边界复杂 || 先沿边走一圈，再做内填
|-
| 螺旋 / Spiral || 圆形 / 自由场景 || 从中心向外螺旋
|-
| 自适应 / Adaptive || 动态污染 || 用相机识别脏污点，热点优先
|}

== Medulla 适配清洁工具 / Adapting cleaning tools ==
清洁工具的典型 IO 表（以拖洗机为例）：
Typical IO map for a mop-and-scrub robot:

<syntaxhighlight lang="csharp">
public class CleaningBot : CartDefinition
{
// 底盘 IO（同标准差速 / 全向车）

// 清洁工具 IO
[AsUpperIO] public bool mopOn; // 拖布旋转
[AsUpperIO] public bool sprayOn; // 喷水
[AsUpperIO] public bool squeegeeOn; // 吸水扒
[AsUpperIO] public bool vacuumOn; // 吸尘
[AsUpperIO] public bool disinfectantOn; // 消毒液
[AsUpperIO] public float brushDownPressure; // 刷盘压力

[AsLowerIO] public float cleanWaterL;
[AsLowerIO] public float dirtyWaterL;
[AsLowerIO] public bool filterOK; // 过滤器堵塞？
[AsLowerIO] public bool detergentLow;
[AsLowerIO] public int brushHours; // 刷盘运行小时
}
</syntaxhighlight>

== 调度集成 / Scheduling integration ==
清洁机器人的任务通常是 ''区域型''而非 ''点型''。SimpleComposer 任务接口需要支持：
Cleaning jobs are ''area-typed'', not ''point-typed''. SimpleComposer needs:

* '''ZoneMission''' — 指定要清洁的 ''多边形区域''
* '''CoverageStrategy''' — 选择上面表中的策略
* '''ScheduleConstraints''' — 时间窗（如商超开门前清完）
* '''RechargeAndRefill''' — 自动充电 + 加水 + 倒污水

== 相关问题 / Related concerns ==
=== 与人共用空间 / Sharing space with humans ===
清洁机器人 ''常在有人区域工作''，激光雷达 + 视觉 ''必须''有人员识别：
* 检测到人员 1.5 m 内 → 减速
* 检测到人员 0.5 m 内 → 停车 + 让行
* 完成任务后倒车回到工作面继续

Cleaning robots typically share space with humans. Lidar + vision MUST detect people: ≥ 1.5 m → slow; ≤ 0.5 m → stop and yield; resume after clear.

=== 湿地面 / Wet floors ===
* 拖洗后地面湿，AGV 自身行驶时可能打滑；速度降至 0.3 m/s。
* 警告标识：在湿地面边缘自动放置 ''警示锥''（高端机型）。

=== 与电梯协同 / Elevator coordination ===
跨楼层清洁需要 ''呼梯协议''（HTTP 调用电梯控制器）。属于 MDCS 之外的集成；SimpleComposer 提供 hook 点。
Multi-floor cleaning needs an elevator-calling protocol (HTTP to the lift controller). MDCS provides a hook; the actual protocol is integration-specific.

== 相关页面 / See also ==
* [[Special:MyLanguage/全向车适配案例|全向车适配案例]]
* [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]
* [[Special:MyLanguage/可达性状态编程|可达性状态编程]]
* [[Special:MyLanguage/绕障行走|绕障行走]]

[[Category:特殊技术方案]]

流场规划

2026-05-16T11:43:11Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
流场规划（Flow-field planning）是 [[Special:MyLanguage/DPS调度算法详解|DPS]] 之外的另一种调度内核选项。它把仓库 / 工厂的地面预计算为一个 ''矢量场''（每格指向"应该走的方向"），车辆按场行驶。流场对 ''车辆数极多 / 任务动态高''的场景有显著优势 —— 不需要为每辆车单独跑 A*。

Flow-field planning is an alternative scheduling-kernel option to [[Special:MyLanguage/DPS调度算法详解|DPS]]. The warehouse / factory floor is pre-computed as a '''vector field''' (each cell points the way to go); vehicles simply follow the field. Flow-field is advantageous for ''very large fleets / very dynamic tasks'' — no per-car A* required.

== 适用场景 / When to use ==
{| class="wikitable"
! 项 / Item !! DPS !! 流场 / Flow-field
|-
| 车队规模 / Fleet size || ≤ ~30 || 30 – 数千 / 30 – thousands
|-
| 任务动态性 / Task dynamics || 中等 || 极高（每秒大量任务）
|-
| 死锁保证 / Deadlock-free || 是 / Yes (algorithmic) || 经验性，需调（empirical）
|-
| 通道宽度 / Lane width || 单车通过即可 || ≥ 2 车并行
|-
| 离线计算 / Offline cost || 低 / Low || 高（重映射地图需要重算流场）
|-
| 路径最优性 / Path optimality || 全局最优 || 接近最优（流场近似）
|}

典型用例：电商物流仓（一日万级任务、数百 KIVA 车）；不适合：单线性产线（车数 < 10）、复杂场景多车型混跑（建议 DPS）。

Typical use: e-commerce sortation warehouses (tens of thousands of tasks/day, hundreds of KIVAs). Not for: small linear production lines (DPS is simpler), heavily mixed-vehicle complex layouts.

== 算法原理 / Algorithm overview ==
=== 离线 / Offline ===
# 把地面离散为格点（典型 100 × 100 mm）。
# 对每个 ''目标站点'' T，求解到 T 的距离场（Dijkstra / 平面波传播）。
# 每个格的 ''流向''= 距离场负梯度方向。
# 多种 ''场层''可叠加：单车流场、紧急通道流场、双向回路流场。

=== 在线 / Online ===
# 车收到任务（目标站点 T）→ 选 ''T 对应的流场层''。
# 车每个 tick 查当前位置所在格的 ''流向 + 速度上限''，作为局部目标。
# 实时局部避让在 Clumsy [[Special:MyLanguage/绕障行走|绕障行走]] 中处理。
# 当场内多车密集时，启用 ''拥挤检测'': 车队主动减速或绕到旁路流场层。

=== 死锁与无死锁 / Deadlock & no-deadlock ===
流场本身 ''不能算法上保证''无死锁。MDCS 通过两个补丁来规避：
* '''拥挤检测 + 调速''': 一个区域车辆密度超过阈值后，进入流量限制。
* '''DPS 兜底''': 在 ''关键路口 / 工位口''仍用 DPS 锁，保证局部无死锁。

The flow field itself does '''not''' algorithmically prevent deadlock. MDCS uses two patches:
* Density-triggered congestion detection + rate limiting.
* DPS fallback on critical intersections and station mouths.

== 数据结构 / Data structures ==
<syntaxhighlight lang="csharp">
public class FlowFieldLayer
{
public int Id;
public int TargetSiteId;
public byte[,] FlowDir; // 每格存方向编码 0..7（8 个邻居方向） / 8-way direction encoding
public ushort[,] SpeedCap; // mm/s
public float[,] Distance; // 距离场（用于优先级 / 比较）
public bool[,] Reserved; // 为应急通道保留？
}
</syntaxhighlight>

存储格式：二进制紧凑布局（每格 ≤ 8 字节）；100 m × 100 m 工地约 80 MB / 流场。
Storage: binary-packed (≤ 8 bytes / cell); ~80 MB / flow-field for a 100 × 100 m site.

== 在 MDCS 中启用 / Enabling in MDCS ==
* SimpleComposer 配置 → 调度内核 → 切换为"流场"。
* 必须先用 [[Special:MyLanguage/开发手册 - SimpleComposer界面开发 - CAD工具|CAD 工具]]为每个目标站点跑离线流场生成。
* 启用后 DPS 仍在路口 / 工位口生效；车体行驶段交给流场。

== 与 DPS 的混合 / Hybrid with DPS ==
推荐配置（大规模仓储）：
* '''行驶段''' = 流场（粗粒度引导）
* '''路口段''' = DPS（保证无死锁）
* '''工位口''' = DPS + 可达性状态（确保进出顺序）

Recommended hybrid (large warehouses):
* '''Traverse segments''' = flow-field (coarse guidance).
* '''Intersections''' = DPS (algorithmic deadlock-free).
* '''Station mouths''' = DPS + reachability state (ordering).

== 限制 / Caveats ==
* 地图变化（增删站点 / 路径）要 ''重新生成所有流场''；典型 5–30 分钟离线。
* 流场对 ''朝向''是无知的 —— 阿克曼车辆需用流场 + ''曲率惩罚''搜索局部可行路径。
* 多车型流场：每种车型一套（包络不同）。

* Map changes force a full off-line regeneration of every flow-field (5–30 min).
* Flow-fields are heading-agnostic — Ackermann vehicles need a local pass with curvature penalties.
* Per vehicle-type: one flow-field set each (different envelopes).

== 相关页面 / See also ==
* [[Special:MyLanguage/DPS调度算法详解|DPS调度算法详解]]
* [[Special:MyLanguage/调度内核运行原理|调度内核运行原理]]
* [[Special:MyLanguage/基于网络流的业务规划器|基于网络流的业务规划器]]
* [[Special:MyLanguage/使用手册 - 寻路启发器功能|寻路启发器功能]]
* [[Special:MyLanguage/Simple软件架构|Simple软件架构]]

[[Category:技术报告]]

汽车面差检测

2026-05-16T11:43:11Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
"汽车面差检测"是 MDCS 在汽车主机厂的特色应用：在车身总装下线时，AGV 携带 3D 扫描设备绕车一圈，自动测量 ''相邻钣金件之间的间隙（gap）与高低差（flush）''，结果实时与设计公差比较，给出可视化的质量报告。

"Automotive panel-gap inspection" is an MDCS application in vehicle assembly: at end-of-line, an AGV with a 3D scanner circles the car body, automatically measuring ''gaps and flushness between adjacent panels'' and comparing against design tolerances in real time, producing a visual quality report.

== 应用背景 / Why ==
* 传统人工卡尺测量 ''慢、漏检、主观'';
* 固定龙门 3D 扫描设备 ''成本高、占用厂房''；
* AGV 移动检测：低成本、高覆盖、可批量。

* Manual feeler-gauge measurement is slow, inconsistent, subjective.
* Fixed gantry 3D scanners are expensive and floor-space heavy.
* An AGV-mounted scanner is cheap, comprehensive, batch-friendly.

== 系统组成 / Components ==
{| class="wikitable"
! 部件 / Part !! 规格 / Spec
|-
| AGV || 全向或差速车，载重 ≥ 100 kg，运动平稳 / Omni or diff drive, payload ≥ 100 kg
|-
| 3D 扫描仪 / 3D scanner || 线激光或结构光，精度 ≤ 0.05 mm
|-
| 多自由度云台 / Multi-DOF gimbal || 让扫描器对准车身曲面 / orient scanner to panel surface
|-
| 车型识别 / Vehicle ID || 二维码 / RFID 读取来车的车型 + VIN
|-
| 标定 / Calibration || 扫描器外参 + 车型 CAD 对齐
|-
| 上位系统 / Back-end || 公差库 + 报告生成 + MES 对接
|}

== 工作流程 / Workflow ==
# 车下线后停在指定工位，触发 AGV 启动检测任务。
# AGV 读取车型 + VIN，加载对应 CAD 与公差库。
# AGV 按预设路径绕车（前 / 侧 / 尾），每个测点暂停，云台精对位扫描器。
# 3D 扫描器拍摄局部点云，识别两块钣金件的特征边沿。
# 边沿之间的 ''最小距离'' = 间隙；切线高度差 = 高低差。
# 与公差比较，标记 OK / NG。
# 完成后生成 ''彩虹图''报告（绿 = OK，红 = NG，灰 = 无数据），并发到 MES。

# Vehicle stops at the inspection station; AGV starts.
# AGV reads VIN, loads matching CAD + tolerances.
# AGV follows a per-model path: stop, orient, scan at each measurement point.
# Extract edge features of adjacent panels.
# Min distance between edges → gap; tangent height difference → flush.
# Compare to tolerance; tag OK / NG.
# Generate rainbow report (green / red / grey) and post to MES.

== 关键算法 / Algorithms ==
* '''边沿提取''' / Edge extraction: 从扫描点云中通过 ''法线突变''检测钣金件边沿。
* '''特征匹配''' / Feature matching: 把当前扫描特征与 CAD 中的 ''nominal'' 特征关联。
* '''3D 配准''' / 3D registration: ICP 把扫描结果对齐到车身 CAD 坐标。
* '''间隙计算''' / Gap computation: 两条边沿点云的 ''最小距离''；高低差用法向投影。
* '''统计''' / Stats: 多次重复测同一点的 σ；σ 大于阈值的测点视为不可信，标记 ''待复测''。

== MDCS 集成 / MDCS integration ==
* '''Detour 端''': AGV 全程需要 < ±10 mm 定位（在工位附近）；常用激光 SLAM + 反光板。
* '''Clumsy 端''': 自定义 `PanelInspect` Movement，控制云台 + 扫描器 + 在每个测点停 1 s。
* '''Medulla 端''': 扫描器作为 [[Special:MyLanguage/3D相机适配|3D 相机插件]]，提供 ''点云 + 触发同步''。
* '''SimpleComposer 端''': 业务插件 `BodyInspector`，定义车型 ↔ 测点 ↔ 公差的映射。
* '''上位 MES''': REST API 接收报告 + 触发返工流程。

== 精度链 / Precision chain ==
最终测量精度受三方约束：
{| class="wikitable"
! 误差源 / Error source !! 典型量级 / Typical
|-
| Detour 定位 / Localisation || ±5 mm
|-
| 云台机械重复 / Gimbal repeatability || ±0.05 mm
|-
| 扫描器 ''自身''精度 / Scanner intrinsic || ±0.05 mm
|-
| 标定残差 / Calibration residual || ±0.1 mm
|-
| 车体晃动 / Vehicle micro-motion || ±0.1 mm
|}

合成误差 ~0.3 mm，符合 OEM 通用 ±0.5 mm 间隙公差。

Synthesised error ≈ 0.3 mm, satisfies typical OEM ±0.5 mm tolerance.

== 限制 / Limitations ==
* '''反光车漆''' / Specular paint: 黑车与镜面漆面扫描效果差；建议下线前喷防反光临时涂层。
* '''新车型上线''' / New vehicle model intro: 必须先用 CMM 标定一份 ''golden'' 测点；流程不可省。
* '''扫描器与车体距离敏感''': 距离 < ±3 mm 内才能保精度；云台机械刚度要求高。
* '''节拍''' / Throughput: 完整一台车测 ~60–120 测点，AGV 节拍 ≈ 3–5 min；汽车工厂线节拍紧时需要多 AGV 并行。

== 相关页面 / See also ==
* [[Special:MyLanguage/3D相机适配|3D相机适配]]
* [[Special:MyLanguage/3D激光雷达适配|3D激光雷达适配]]
* [[Special:MyLanguage/标定与校准|标定与校准]]
* [[Special:MyLanguage/全息座舱|全息座舱]] — 相关 3D 重建应用

[[Category:特殊技术方案]]

如何使用CycleGUI快速开发UI界面

2026-05-16T11:43:04Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
[[Special:MyLanguage/CycleGUI|CycleGUI]] 是 MDCS 自研的 ''按需协程''GUI 框架。本页给开发者一份 ''最小学习路径''：开一个画面、画一点云、加一个按钮、读一个输入。

[[Special:MyLanguage/CycleGUI|CycleGUI]] is MDCS's lazy-coroutine GUI framework. This page is the minimum learning path: open a panel, draw a cloud, add a button, accept an input.

== 1. 开一个画面 / Open a panel ==
<syntaxhighlight lang="csharp">
using CycleGUI;

// 任何线程都可以 / from any thread
var painter = UI.GetPainter("my-debug");
painter.DrawText("Hello from algorithm thread");
</syntaxhighlight>

`UI.GetPainter(name)` 拿到一个 ''命名画板''；后续所有 `painter.DrawXxx` 累积到同一画面。
`UI.GetPainter(name)` returns a ''named painter''; subsequent `DrawXxx` calls accumulate into the same view.

== 2. 画点云 / Draw a point cloud ==
<syntaxhighlight lang="csharp">
var painter = UI.GetPainter("lidar-frame");
foreach (var pt in cachedLidar)
{
var c = pt.intensity > 0.8 ? Color.Red : Color.White;
painter.DrawDot3D(c,
new Vector3((float)(pt.d * Math.Cos(pt.th)),
(float)(pt.d * Math.Sin(pt.th)),
0));
}
</syntaxhighlight>

CycleGUI 把所有 `Draw` 命令存到 ''当前画面''；在 GUI 主线程下一次重绘时一次性渲染。
CycleGUI buffers all `Draw` commands for the current frame and renders them when the UI thread next repaints.

== 3. 加一个按钮 / Add a button ==
按钮 + 通用 UI 控件用 ''协程''风格 —— 把 UI 逻辑写成 `IEnumerable<Cycle>` 由框架托管：
Buttons and other widgets use coroutines:

<syntaxhighlight lang="csharp">
UI.CastCoroutine(MyControl());

IEnumerable<Cycle> MyControl()
{
while (true)
{
var panel = UI.GetPanel("control");
if (panel.Button("Start scan"))
{
StartScan(); // 调用算法
}
if (panel.Button("Stop"))
{
StopScan();
}
yield return Cycle.Next; // 等下一帧
}
}
</syntaxhighlight>

`UI.CastCoroutine` 把一个 `IEnumerable<Cycle>` 投递给 GUI 主线程；它只在需要重绘时被推进。
`UI.CastCoroutine` posts a coroutine to the UI thread; it advances only on repaint.

== 4. 读一个输入 / Read an input ==
<syntaxhighlight lang="csharp">
IEnumerable<Cycle> ConfigPanel()
{
int speed = 600;
while (true)
{
var p = UI.GetPanel("config");
speed = p.IntInput("speed (mm/s)", speed, min: 0, max: 2000);
p.Text($"Current speed = {speed}");

if (p.Button("Apply"))
{
Configuration.conf.basicSpeed = speed;
}
yield return Cycle.Next;
}
}
</syntaxhighlight>

== 5. 等用户输入 / Wait for user input ==
有时算法要等用户点确认才继续 —— 用 `yield return WaitForButton(...)`：

Sometimes the algorithm has to wait for user confirmation:

<syntaxhighlight lang="csharp">
IEnumerable<Cycle> ApprovalFlow()
{
while (true)
{
var p = UI.GetPanel("approve");
p.Text("Pending: cart approach to station-17");

yield return p.WaitForButton("Approve"); // 阻塞协程直到点击
ConfirmApproach();

yield return Cycle.Seconds(1);
}
}
</syntaxhighlight>

== 6. 跨线程 / 跨进程 / Cross-thread / cross-process ==
* CycleGUI 自动把任意线程的 `Draw` 调用 ''marshal''到 UI 主线程。
* 同一 CycleGUI 服务可被多个进程连接；每个进程独立维护自己的 painter，UI 端可同时显示。

CycleGUI auto-marshals `Draw` calls onto the UI thread from any thread. Multiple processes can connect to one CycleGUI server simultaneously; each has its own painter, all visible together.

== 7. 录制与回放 / Record & replay ==
<syntaxhighlight lang="csharp">
UI.StartRecording("session.cgr");
// ... 跑算法 + 各种 Draw ...
UI.StopRecording();

// 离线回放
UI.Replay("session.cgr");
</syntaxhighlight>

== 最佳实践 / Best practices ==
* '''命名 painter / panel''' 反映 ''数据来源''（如 `lidar-front`、`slam-map`），不要根据 UI 位置命名。
* '''协程内不要 sleep'''；改用 `yield return Cycle.Seconds(N)` 让框架调度。
* '''重命名 painter 会丢历史''' —— 如果用户在多次会话间想保留视图开关状态，名称保持稳定。
* '''数据多时考虑节流''' —— 即便是协程按需调用，每帧画百万点云仍会卡；用空间下采样或频率限制。

== 与 Detour / Clumsy / SimpleComposer 的集成 / Integration ==
* Detour: SLAM 中间状态默认在 `detour-slam` painter；可在 Detour UI 中开关。
* Clumsy: Movement 内部可调 `UI.GetPainter("movement-debug")` 加自定义可视化。
* SimpleComposer: CAD 画布本身就是一个 CycleGUI 实例，自定义工具通过协程加新的 layer。

== 相关页面 / See also ==
* [[Special:MyLanguage/CycleGUI|CycleGUI]]
* [[Special:MyLanguage/开发手册 - SimpleComposer界面开发 - CAD工具|开发手册 - SimpleComposer界面开发 - CAD工具]]
* [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]]

[[Category:二次开发相关说明]]

天花板SLAM

2026-05-16T11:43:04Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
天花板 SLAM（Ceiling SLAM）使用 ''向上''的相机或 2D 激光，把天花板上的稳定特征（横梁、风口、灯具、消防喷淋、棋盘形吊顶板）作为视觉地标。在地面繁忙、特征频繁变动的仓储 / 生产场景下，天花板往往比地面更稳定，因此天花板 SLAM 是一种 ''与地面隔离''的高鲁棒定位手段。

Ceiling SLAM uses an upward-facing camera or 2D laser. The ceiling — beams, vents, sprinklers, lights, tile grids — is usually stable when the floor is hectic; ceiling SLAM is a high-robustness localisation source ''decoupled from floor traffic''.

== 适用场景 / Use cases ==
* '''生产线 + 高人流仓库''': 地面物动态，天花板稳定。
* '''室外搬运转入室内''': 室内激光 SLAM 漂，天花板辅助。
* '''特定吊顶纹路'''（如等距格栅）: 几何对位精度高。

== 硬件 / Hardware ==
{| class="wikitable"
! 部件 / Part !! 典型规格 / Typical
|-
| 相机 / Camera || 向上工业相机 + 广角镜头 / upward industrial camera + wide-angle lens
|-
| 视场 / FOV || 2 × 2 m 在 5 m 净高时 / 2×2 m FOV at 5 m clear height
|-
| 帧率 / Frame rate || 30 – 60 FPS
|-
| 光照 / Lighting || 多数室内自然光足够；强反差或弱光要加 LED 补光
|-
| 替代：2D 激光向上 / Alt: 2D upward laser || 用于无相机方案 / camera-less alternative
|}

== 算法 / Algorithm ==
=== 视觉变体 / Visual variant ===
1. 特征提取（ORB / KAZE）
2. 视差 + IMU 估姿（相机模型为针孔）
3. 关键帧 + Bundle Adjustment
4. 全局闭环（词袋）

=== 几何变体（吊顶板）/ Geometric variant (drop-ceiling) ===
吊顶板的等距格栅是 ''周期性几何信号''：
* 检测格栅交点 → 局部坐标系下规则点阵
* 用相位匹配（FFT）求当前帧相对地图的位移
* 周期性歧义通过 ''临近格唯一标记''（如不同形状的喷淋头）解消

The regular grid in drop-ceiling tiles is a periodic geometric signal. Detect grid intersections → regular point lattice → phase matching (FFT) for translation. Periodic ambiguity is resolved by unique markers (sprinklers, vent shapes).

== 与激光 SLAM 的融合 / Fusion with laser SLAM ==
天花板 SLAM 输出位姿 + 协方差送入 Detour 的 [[Special:MyLanguage/Detour软件架构|TightCoupler]]：
* 地面激光主导时 → 天花板做约束。
* 地面失效（特征不足、动态过多）→ 天花板上升为主源。
* 二者完全独立的故障模式 → 总体鲁棒性提升。

Ceiling pose + covariance feeds Detour's TightCoupler:
* Laser dominates by default; ceiling adds constraints.
* When laser degrades, ceiling promotes to primary.
* Independent failure modes → overall robustness gains.

== 配置 / Configuration ==
* 在 Detour 配置中启用 `useCeilingSlam = true`。
* 在 [[Special:MyLanguage/开发手册 - SimpleComposer界面开发 - CAD工具|CAD]] 中标注 ''天花板可定位区域''（部分区域无天花板，如龙门吊正下方）。
* 录制天花板地图：与激光 SLAM 同时跑一次完整覆盖，离线后处理。

== 常见问题 / Common issues ==
* '''高反光天花板''' / Reflective ceiling: 在 LED 灯下完全反射，特征丢；用偏振镜或拍其它角度。
* '''天花板临时遮挡''' / Temporary occlusion: 吊车 / 维护工人；触发临时切换到激光主源。
* '''高度差异区''' / Height changes: 经过低净高区域时相机参数（视场覆盖面积）变化；用多模型自适应或离散段地图。

== 与天眼系统的区别 / vs Skyeye ==
{| class="wikitable"
! 项 / Item !! 天花板 SLAM !! [[Special:MyLanguage/天眼系统|天眼系统]]
|-
| 视角 / Viewpoint || AGV 向上看天花板 || 天花板向下看 AGV / 货物
|-
| 角色 / Role || 本车定位 || 全局监控 / 装卸车协作
|-
| 设备 / Equipment || 装在每辆 AGV 上 || 固定吊装在天花板
|-
| 用途 / Use || SLAM | || 装卸车、堆码识别
|}

== 相关页面 / See also ==
* [[Special:MyLanguage/Detour软件架构|Detour软件架构]]
* [[Special:MyLanguage/多定位源的自动综合|多定位源的自动综合]]
* [[Special:MyLanguage/具有高鲁棒性的激光SLAM算法|具有高鲁棒性的激光SLAM算法]]
* [[Special:MyLanguage/天眼系统|天眼系统]]

[[Category:定位导航相关手册]]

天眼系统

2026-05-16T11:43:03Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
天眼系统（Skyeye）是 MDCS 中的 ''高位 3D 视觉''组件：在装卸车口、密集仓储区等关键位置吊装俯拍 3D 相机，把全局货物 / 堆码 / 车辆状态实时回传给 SimpleComposer，让多 AGV 协同完成单车感知盲区的作业。

Skyeye is MDCS's '''overhead 3D vision''' subsystem: ceiling-mounted 3D cameras at critical points (loading docks, dense storage) provide a global view of cargo / stacks / vehicles to SimpleComposer in real time, enabling multi-AGV cooperation where individual AGVs can't see.

== 系统组件 / Components ==
{| class="wikitable"
! 部件 / Part !! 规格 / Spec
|-
| 高位 3D 相机 / Overhead 3D camera || ToF 或结构光，安装高度 ≥ 4 m / ToF or structured light, ≥ 4 m mount
|-
| 推理服务 / Inference service || 把 3D 点云转 ''格点占用 + 朝向''，发布到 SimpleComposer
|-
| 数据通道 / Channel || HTTP / WebSocket / DObject 共享内存
|-
| 标定 / Calibration || 相机外参对齐到仓库世界坐标系
|-
| SimpleComposer SkyeyeStrategy 插件 || 调度策略：[[Special:MyLanguage/联动天眼系统进行装卸车|联动天眼系统进行装卸车]]
|}

== 典型应用 / Typical use cases ==
* '''半挂车装车 / 卸车''' — 见 [[Special:MyLanguage/联动天眼系统进行装卸车|联动天眼系统进行装卸车]]
* '''集装箱卸货'''
* '''密集堆垛区智能堆码''' — 见 [[Special:MyLanguage/识别料框并堆垛拆垛|识别料框并堆垛拆垛]]
* '''高架仓拣选辅助''' — 全局看哪一架还有空位
* '''异常监控''' — 货物倒塌、人员闯入、设备故障

== 数据契约 / Data contract ==
天眼推理服务发布 ''帧''级数据：
The inference service publishes per-frame data:

<syntaxhighlight lang="json">
{
"ts": 1715843200,
"areaId": "DOCK_NORTH",
"frame": 12345,
"objects": [
{ "id": 17, "type": "wood_pallet",
"x": 850, "y": 600, "z": 230, "theta": 0.04,
"size": {"w": 1100, "l": 1100, "h": 150},
"conf": 0.91 },
{ "id": 18, "type": "kit_bin",
"x": 1820, "y": 600, "z": 250, "theta": 0.0, "conf": 0.88 }
],
"grid": {
"cellSize": 200,
"cells": [ /* ... */ ]
}
}
</syntaxhighlight>

== 与 AGV 自身感知的协同 / Cooperation with on-AGV sensing ==
天眼提供 ''全局'' + ''粗精度''（≈ ±50 mm），AGV 自身激光 / 3D 提供 ''局部'' + ''细精度''（≈ ±10 mm）。MDCS 把它们结合：

Skyeye gives '''global + coarse''' (≈ ±50 mm); on-AGV sensing gives '''local + fine''' (≈ ±10 mm). They combine:

* '''分工 / Division of labour''': Skyeye 告诉 AGV "去哪"；AGV 自己 "怎么去 + 精对位"。
* '''冲突仲裁 / Conflict resolution''': 二者分歧时，''以局部传感为准 + 让 Skyeye 重扫''。
* '''时间同步 / Time sync''': NTP / PTP，误差 < 100 ms。

== 标定 / Calibration ==
天眼相机的外参 = ''相机到仓库世界坐标系''变换。标定流程：
Calibration of the camera-to-world transform:

# 在相机视场内放 N ≥ 4 个 ''已知位置''的标定靶（地面贴 AprilTag）。
# 相机扫一帧 → 检测靶位置（相机坐标系）。
# 用标定靶世界坐标 + 相机坐标做最小二乘 → 外参。
# 误差 ≤ 20 mm 视为合格。

# Place N ≥ 4 known-pose calibration targets in the FOV.
# Scan; detect their positions in the camera frame.
# Least-squares from world ↔ camera point pairs → extrinsics.
# Acceptable error ≤ 20 mm.

详见 [[Special:MyLanguage/标定与校准|标定与校准]]。

== 部署 / Deployment ==
* 推荐每个装卸口 ''≥ 1''台天眼，重要节点 2 台冗余。
* 安装位置：避开起吊 / 叉车作业的物理路径。
* 数据带宽：单 3D 相机 ~30 Mbps，多相机用千兆以太 / 私有 VLAN。
* 推理服务部署：本地 GPU 工控机（推荐）或边缘 / 云（按延迟需求）。

== 失败模式 / Failure modes ==
{| class="wikitable"
! 失败 / Failure !! 处理 / Recovery
|-
| 相机断电 / Camera offline || SimpleComposer 标该区域 ''Skyeye-down''，暂停天眼依赖任务
|-
| 标定漂 / Drift || 自动重扫 ''参考靶''；偏差 > 50 mm 触发人工复测
|-
| 视觉遮挡 / Occlusion (overhead crane, banner) || 切到激光 SLAM + 局部 AGV 感知
|-
| 误识别 / False detection || 置信度阈值 + 多帧一致性 + 人工标注的负例反馈
|}

== 相关页面 / See also ==
* [[Special:MyLanguage/联动天眼系统进行装卸车|联动天眼系统进行装卸车]]
* [[Special:MyLanguage/自动装卸车应用|自动装卸车应用]]
* [[Special:MyLanguage/3D相机适配|3D相机适配]]
* [[Special:MyLanguage/天花板SLAM|天花板SLAM]] — 注意视角相反

[[Category:特殊技术方案]]

多定位源的自动综合

2026-05-16T11:43:02Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
"多定位源的自动综合"是 Detour 把多种定位手段（激光 SLAM、地纹 SLAM、天花板 SLAM、二维码、IMU、轮编里程计、RTK、UWB）融合为单一 6-DoF 位姿的机制。核心是 TightCoupler —— 一个紧耦合的位姿图优化器，根据每个观测源的协方差自动加权。

"Auto multi-source positioning fusion" is Detour's mechanism for merging multiple localisation sources (laser SLAM, ground-texture SLAM, ceiling SLAM, QR, IMU, wheel odometry, RTK, UWB) into a single 6-DoF pose. The core is the TightCoupler — a tightly-coupled pose-graph optimiser that weights each source by its covariance.

实现位置：`D:\src\Detour\DetourCore\Algorithms\TightCoupler.ExternalCoupler.cs`。
Implementation: `D:\src\Detour\DetourCore\Algorithms\TightCoupler.ExternalCoupler.cs`.

== 为什么需要 / Why fuse ==
任何单一定位源都有 ''盲点''：
Every single source has '''blind spots''':

{| class="wikitable"
! 源 / Source !! 强 / Strength !! 弱 / Weakness
|-
| 激光 SLAM || 几何信息丰富的工业场景精度高 / High accuracy in geom-rich industrial sites || 长走廊 / 镜面 / 重对称场景退化
|-
| 地纹 SLAM || 平整地面 mm 量级 / Sub-cm on smooth floors || 湿水 / 油污地遮挡
|-
| 天花板 SLAM || 地面动态时仍稳 / Stable when floor is busy || 高反射 / 低净高场景
|-
| 二维码 || 已知二维码处亚厘米 / Sub-cm where tags present || 视场无二维码时无输出
|-
| IMU + 轮编里程计 || 高频、低延迟 / High-rate, low-latency || 累积漂移，无全局信息
|-
| RTK GNSS || 室外厘米级 / Outdoor cm-level || 室内不可用
|-
| UWB || 室内 ~10 cm / Indoor ~10 cm || 多径效应 + 基站布设成本
|}

''多源融合''让强项互补、弱项互救：例如长走廊上激光退化、地纹接管；天眼区有遮挡时二维码补全。
Fusion lets strengths complement and weaknesses recover: e.g. laser drops in long corridors while ground-texture takes over; QR catches up where ceiling is occluded.

== 紧耦合 / Tight coupling ==
"紧耦合"是与"松耦合"对比的术语：
"Tight" vs "loose" coupling:

* '''松耦合 / Loose''': 每个源独立产生 ''位姿''，最后用 EKF 加权平均位姿。简单但损失原始观测信息。
* '''紧耦合 / Tight''': 每个源的 ''原始观测''（约束）进入同一个位姿图，统一优化。MDCS 使用紧耦合。

Loose: each source emits a pose; EKF averages them. Tight: each source's raw observation enters one pose graph; everything optimised jointly. MDCS uses tight coupling.

== 外部反馈接口 / External-feed API ==
非 Detour 内置的定位源（轮编里程计 / IMU / RTK / UWB / 第三方视觉）通过 `TightCoupler.PostExternalFeed()` 接入：

Non-built-in sources (wheel odom / IMU / RTK / UWB / third-party vision) enter Detour through `TightCoupler.PostExternalFeed()`:

<syntaxhighlight lang="csharp">
TightCoupler.PostExternalFeed(new ExternalFeed
{
name = "wheel_imu_2",
counter = tick++,
hasTranslation = true,
hasRotation = true,
is2D = true, // 2D 平面运动 / 2D planar
integrated = true, // 这是个 ''累积'' 量 / cumulative
toRemap = false, // 不是绝对参考系 / not absolute frame
startingTick = baselineTick,// 累积起算的基准 tick / baseline
x = odomX, y = odomY, th = odomTh
}, name: "WheelImu");
</syntaxhighlight>

主要字段：
* `hasTranslation / hasRotation` — 提供的自由度
* `is2D / is3D` — 平面 vs 3D
* `integrated` — 累积量（必须配合 `startingTick`）还是单帧量
* `toRemap` — true 表示绝对参考系（如 RTK），融合时需要做全局重映射

== 自动加权 / Automatic weighting ==
TightCoupler 不需要手动设置每个源的权重；权重 = 协方差矩阵的逆。每个源必须 ''诚实''汇报自己的协方差：

TightCoupler doesn't require hand-tuned per-source weights. Weight = covariance inverse. Each source must report its covariance honestly:

* 激光 SLAM：Hessian 求逆给出
* 二维码：从 PnP 重投影残差估计
* IMU / 里程计：从硬件规格 + 时间间隔估计
* RTK：从 GNSS 接收机 reported DOP

错报协方差是 ''融合崩坏''的最常见原因 —— 一个谎报"我超准"的源会 ''统治''融合结果。
Mis-reporting covariance is the single most common cause of fusion blow-ups — a source claiming to be much more accurate than reality will dominate.

== 故障处理 / Failure handling ==
* '''源静默''' / Source silence: 超时 → 该源从下一帧的位姿图中 ''删除''，不影响其它源。
* '''源剧烈跳变''' / Wild source jump: TightCoupler 内置 ''卡方检验''，跳变 > 5σ 的观测直接丢弃。
* '''融合发散''' / Fusion divergence: 残差持续上升 → 触发 ''软重启''（保留主导源，重置其它源的位姿先验）。

== 调试 / Debugging ==
Detour UI 的"融合面板"显示：
The Detour UI's "fusion panel" shows:

* 每个源的最新观测时刻 + 协方差
* 当前主导源
* 残差直方图
* 协方差膨胀 / 收缩历史

打开 ''单源调试模式''可以 ''强制只用一个源''跑定位（用于诊断单源故障）。

A "single-source debug mode" forces the fusion to use only one source — handy for diagnosing a misbehaving one.

== 相关页面 / See also ==
* [[Special:MyLanguage/Detour软件架构|Detour软件架构]]
* [[Special:MyLanguage/Detour激光SLAM算法详解|Detour激光SLAM算法详解]]
* [[Special:MyLanguage/Detour地面纹理SLAM算法详解|Detour地面纹理SLAM算法详解]]
* [[Special:MyLanguage/二维码识别导航|二维码识别导航]]
* [[Special:MyLanguage/天花板SLAM|天花板SLAM]]
* [[Special:MyLanguage/使用手册 - 同时使用激光、地纹、二维码、轮编里程计和IMU进行鲁棒定位|使用手册 - 同时使用激光、地纹、二维码、轮编里程计和IMU进行鲁棒定位]]
* [[Special:MyLanguage/输入GPS外部定位|输入GPS外部定位]]

[[Category:定位导航相关手册]]

复合卷料机械手叉车

2026-05-16T11:43:01Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
"复合卷料机械手叉车"是 MDCS 中的复合机器人形态：把 ''叉车''+''机械手''+''卷料专用夹具''组合在一台 AGV 上，实现卷料（钢卷、纸卷、塑料卷、布卷等）的自动取放与上下料。它是 ''叉车适配 + 卷料夹具适配 + 机械手协同''的综合案例。

The "composite coil-handling robotic forklift" combines '''forklift''' + '''robotic arm''' + '''coil-specific gripper''' on one AGV to autonomously handle coils (steel, paper, plastic, fabric, …). It's the composite of [[Special:MyLanguage/叉车适配案例|forklift adaptation]] + coil-gripper adaptation + manipulator coordination.

== 业务场景 / Business scenarios ==
* '''钢卷仓库''' / Steel-coil yard: 单卷重 5–25 t，堆叠 3–5 层
* '''造纸 / 卷烟生产线''' / Paper / cigarette lines: 中等卷重，节拍紧
* '''汽车冲压线''' / Auto stamping: 卷料上料 + 废料下料
* '''纺织''' / Textile: 布卷搬运 + 上下料

== 硬件组成 / Hardware ==
{| class="wikitable"
! 部件 / Part !! 规格 / Spec
|-
| 底盘 / Chassis || 重载叉车 / 牵引车 / heavy-load forklift or tractor
|-
| 机械手 / Arm || 6-DoF 工业臂或 SCARA / 6-DoF or SCARA
|-
| 卷料夹具 / Coil gripper || V 形托架 + 夹紧机构 / V-cradle + clamp; 或 ''C 形钩'' / C-hook
|-
| 视觉 / Vision || 3D 相机扫卷端面识别中心 + 直径 / 3D camera for coil-end ID
|-
| 激光雷达 / Lidar || 前向 + 侧向（多激光融合）
|-
| 负载传感 / Load sensor || 称重模块；溢出阈值即报警
|}

机械手的关注点：足够长以触到地面卷 + 提到货架；足够强以拿动单卷重量；末端夹具与卷料 V 形配合好。
Key arm requirements: long enough to reach a floor coil and lift to rack, strong enough for single-coil weight, end-effector matches the V-cradle profile.

== 1. Medulla 适配 / Medulla side ==
比标准叉车多了机械手 + 卷料夹具的 IO：
On top of a standard forklift, add IO for the arm + the coil-specific gripper:

<syntaxhighlight lang="csharp">
public class CoilFork : CartDefinition
{
// 底盘 IO（同 LB14 forklift）/ Chassis IO same as a regular forklift...

// 机械手 IO / Arm IO
[AsUpperIO] public float[] armJointTgt = new float[6];
[AsUpperIO] public bool gripperClose;
[AsLowerIO] public float[] armJointEst = new float[6];
[AsLowerIO] public bool gripperClosed;
[AsLowerIO] public float coilWeight;

// 卷料夹具 IO / Coil gripper IO
[AsUpperIO] public bool vCradleLift; // V 托架升起
[AsUpperIO] public bool clampOn; // 夹紧
[AsLowerIO] public bool clampForceOK; // 夹紧力到位
[AsLowerIO] public bool coilDetected; // 卷在槽内

[AsInitParam] public string armConfig = "armconfigs/UR10.json";
}
</syntaxhighlight>

== 2. Clumsy 自动驾驶适配 / Clumsy side ==
卷料场景多了几个特定 Movement：
A few coil-specific Movements:

* `CoilApproach` — 用 3D 相机识别卷端面，AGV 居中对位
* `CoilPickWithArm` — 机械手放 V 托架 → 卷滚入托架 → 升起 → 夹紧
* `CoilPlaceOnRack` — 把卷放到 V 形支架 (rack saddle)
* `CoilDestackFromGround` — 地面堆叠的卷分层取下

<syntaxhighlight lang="csharp">
public void PickCoilFromGround(double sx, double sy, int srcId)
{
Queue(
async () => DriveTask.WaitDriveTask(new SteeringLineFollowing
{ srcX = currentX, srcY = currentY,
dstX = sx, dstY = sy, basespeed = 400 }.Follow()),
async () =>
{
// 3D 相机识别卷
DriveTask.WaitDriveTask(new CoilApproach
{ stopDist = 600, coilDiamMax = 1500 }.Get());
},
async () =>
{
// 机械手伸出 + V 托架放到卷下
await MoveArmTo(grabPose);
SetUpperIO("vCradleLift", false);
await Task.Delay(500);
DriveTask.WaitDriveTask(new ForwardTracker
{ dstAhead = 800, basespeed = 100 }.Get()); // 微推让卷滚入托架
},
async () =>
{
SetUpperIO("vCradleLift", true);
await WaitForLowerIO("coilDetected", 4000);
SetUpperIO("clampOn", true);
await WaitForLowerIO("clampForceOK", 3000);
});
}
</syntaxhighlight>

== 3. SimpleComposer 端 / SimpleComposer side ==
* '''带卷包络''' / Loaded envelope: 卷直径影响 ''车体外缘''，必须声明对应大包络。
* '''可达性约束''' / Reachability: 持卷在低净高区段降速 + 禁止某些急转。
* '''机械手姿态约束''' / Arm pose: 行驶时机械手必须收回到 ''行驶姿态''；离开取放工位前不允许行驶。

* The carrying envelope expands with coil diameter; declare an alternate envelope.
* Reachability prohibits sharp turns + low-clearance corridors when carrying.
* Arm pose must be 'stow' before driving; refuse motion otherwise.

== 4. 安全 / Safety ==
* '''卷脱落自动停车''' / Coil-drop auto-stop: `coilDetected` 在搬运中突然为 false → e-stop。
* '''机械手碰撞监测''' / Arm collision: 关节力矩 > 阈值 → e-stop。
* '''负载超限''' / Overload: 单卷 > 设计载重 → 拒绝取。
* '''人员靠近''' / Personnel proximity: 工作半径内 1.5 m 任何动态物体 → e-stop。

== 5. 节拍 / Throughput ==
单卷搬运参考节拍：
Per-coil cycle:

{| class="wikitable"
! 阶段 / Stage !! 时间 / Time
|-
| 巡线到取卷工位 / Travel to source || 30–60 s
|-
| 3D 视觉识别 + 对位 / 3D recognition || 5–10 s
|-
| 机械手取卷 / Arm pickup || 15–25 s
|-
| 巡线到目标工位 / Travel to dest. || 30–60 s
|-
| 机械手放卷 / Arm place || 15–25 s
|-
| 离开 / Withdraw || 10–15 s
|-
| 单次总节拍 / Per-coil total || 1.5–3 min
|}

== 相关页面 / See also ==
* [[Special:MyLanguage/叉车适配案例|叉车适配案例]]
* [[Special:MyLanguage/全向车适配案例|全向车适配案例]]
* [[Special:MyLanguage/使用叉车自动取托盘功能|使用叉车自动取托盘功能]]
* [[Special:MyLanguage/3D相机适配|3D相机适配]]
* [[Special:MyLanguage/识别料框并堆垛拆垛|识别料框并堆垛拆垛]]

[[Category:特殊技术方案]]

基于网络流的业务规划器

2026-05-16T11:43:01Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
"业务规划器"是调度链路最上层的决策器：把 ''业务任务列表''（订单、生产工单）映射成 ''AGV 任务集合''。基于网络流的实现把这一映射建模为 ''最大流 / 最小费用流''问题，让规划在大规模、多约束、多目标的场景下仍然高效收敛。

The '''business planner''' is the topmost decision layer in the scheduling chain: it maps ''business jobs'' (orders, production work-orders) onto ''AGV tasks''. The network-flow implementation casts this as a ''max-flow / min-cost flow'' problem so planning stays tractable at large scale with many constraints and objectives.

== 适用 / When applicable ==
* 货 ↔ AGV ↔ 工位三方匹配（混型货物多）/ Goods ↔ AGV ↔ work-station three-way matching with mixed cargo types.
* 业务有明确成本指标（节拍、能耗、磨损分布）/ Business has clear cost metrics (cycle time, energy, wear distribution).
* 任务量 ≥ 100 / 小时 / Task volume ≥ 100 / hour.

简单单线场景不需要网络流 —— 用 ''FIFO + 简单贪心''即可。

For small linear deployments, FIFO + greedy is fine.

== 网络流模型 / Network-flow model ==
最经典模型（最小费用最大流）：

S (源 / source)
│
▼ cap=1 cost=0 (每个 AGV 一条供给边)
┌───────────────────────────────────┐
│ Layer 1: AGV agent nodes │
└───────────────────────────────────┘
│ cap=∞ cost=c_ij
▼ (c_ij = AGV_i 执行 task_j 的成本)
┌───────────────────────────────────┐
│ Layer 2: Task nodes (each task = 1 node) │
└───────────────────────────────────┘
│ cap=1 cost=0
▼
T (汇 / sink)

求解 min-cost flow → 哪 AGV 做哪个任务的指派。

Solve min-cost flow → which AGV does which task.

成本 c_ij 通常包含：
The cost c_ij typically includes:

* 当前位置到取货点的距离（行驶时间）/ distance from current position to pickup
* AGV 当前剩余电量与任务能耗的匹配度 / battery vs energy required
* 当前车型与货物匹配度（如：托盘叉车不能搬料筐）/ vehicle-cargo compatibility
* 公平性惩罚（让 ''每辆车工作量'' 均衡）/ workload-fairness penalty
* 时间窗（任务必须 N 秒内取走）/ time-window pressure

== 求解器 / Solvers ==
SimpleCore 支持几种规模 / 方案：

{| class="wikitable"
! 规模 / Scale !! 算法 / Algorithm !! 复杂度 / Complexity
|-
| < 200 任务 || SSP (Successive Shortest Paths) || O(F · (n + m) log n)
|-
| 200 – 2000 任务 || Cost-scaling / Network Simplex || O(n³)
|-
| > 2000 任务 || LP 松弛 + 圆整 / LP relaxation + rounding || 近似 / Approximate
|-
| 任意 || 增量重规划 / Incremental replanning || 上次解 + δ
|}

== 增量重规划 / Incremental replanning ==
业务规划不能 ''每秒重头跑'' —— 上一次的解大部分可用。MDCS 采用 ''增量更新''：
* 新任务进入 → 加节点 + 增广路径。
* AGV 完成任务 → 移除节点 + 重路由其它任务。
* AGV 故障 → 标该供给边 cap=0，对其原任务重新分配。

The business planner doesn't replan from scratch each second — most of the previous solution stays valid. MDCS uses incremental updates: add tasks via augmenting paths; remove completed tasks; on AGV failure, zero its supply edge and reassign its tasks.

== 与调度内核的关系 / Relation to the scheduler kernel ==
业务规划器 ''上接''业务系统（WMS / ERP），''下接''调度内核（DPS / 流场）：

WMS / ERP
│ 订单 / 工单
▼
[业务规划器 / Business planner] ← 本页 / this page
│ 任务对 AGV 的指派
▼
[调度内核 / Scheduler kernel]
- DPS（[[Special:MyLanguage/DPS调度算法详解|DPS调度算法详解]]）
- 流场（[[Special:MyLanguage/流场规划|流场规划]]）
│ 每辆车的具体路径
▼
[Car.actualSendScript] → 单车执行

业务规划只关心 ''谁做什么''，不关心具体路径与交管。

The business planner only decides ''who does what''. Paths and traffic control are the scheduler kernel's job.

== 调试与可视化 / Debug & visualisation ==
* 在 SimpleComposer 中开 ''Planner Trace''：每次规划的所有边 + cost + 求得流值都可视化。
* 增量重规划失败时，规划器会 ''回退到全量重跑''并打印 ''diff''。
* 性能采样：每 N 次规划记 ''解时间 + 任务数 + 改变的边数''。

== 相关页面 / See also ==
* [[Special:MyLanguage/调度内核运行原理|调度内核运行原理]]
* [[Special:MyLanguage/DPS调度算法详解|DPS调度算法详解]]
* [[Special:MyLanguage/流场规划|流场规划]]
* [[Special:MyLanguage/Simple软件架构|Simple软件架构]]
* [[Special:MyLanguage/使用手册 - 车队管控|使用手册 - 车队管控]]

[[Category:技术报告]]

具有高鲁棒性的激光SLAM算法

2026-05-16T11:42:58Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
MDCS 中"激光 SLAM 鲁棒性"指的是在 ''特征贫乏''、''动态多''、''环境光干扰''、''传感器噪声''等不友好条件下仍能稳定输出位姿的能力。本页列出 Detour 激光 SLAM 用到的关键鲁棒性技巧（与 [[Special:MyLanguage/Detour激光SLAM算法详解|算法细节]] 是不同维度的视角）。

"Robustness" in MDCS laser SLAM means stable pose output even when the environment is featureless, dynamic-heavy, glare-prone, or sensor-noisy. This page lists the key techniques Detour uses (an orthogonal view to the [[Special:MyLanguage/Detour激光SLAM算法详解|algorithmic details]]).

== 关键技巧 / Key techniques ==
=== 1. 多分辨率扫描匹配 / Multi-resolution scan matching ===
从粗到细搜索位姿：先在 10 cm 分辨率上找候选 → 再 2 cm → 再 5 mm。等效于 ''分支限界''，避免直接在原始分辨率求全局最优时的指数代价。

Coarse-to-fine pose search (10 cm → 2 cm → 5 mm). Branch-and-bound equivalent; avoids the exponential cost of direct fine-grained search.

=== 2. 紧耦合 IMU 预积分 / Tight-coupled IMU pre-integration ===
把 IMU 数据从激光帧之间积分得到 ''相对位姿先验''，作为扫描匹配的初值。在动态环境（车辆运动 + 旋转剧烈）下，避免位姿跳变。

Integrate IMU between laser frames to give the scan matcher a relative-pose prior. Prevents pose jumps in dynamic-heavy / high-yaw conditions.

=== 3. 动态障碍过滤 / Dynamic obstacle filtering ===
* '''占用一致性''': 维护"长期占用率"地图，与当前帧异常突现的点视为动态点丢弃。
* '''可见性约束''': 与上一帧比较 —— 一个点如果在上一帧应被现帧雷达看到却没有，视为动态。
* '''速度约束''': 同一区域连续帧出现的点云速度估计 > 步行速度 → 滤除。

* Occupancy consistency: maintain a long-term occupancy map; reject points appearing where the map says 'free'.
* Visibility check: a point present in the previous frame but absent now (or vice versa, in expected region) is dynamic.
* Velocity gate: estimated cloud velocity > walking speed → reject.

=== 4. 反光板辅助 / Reflector assistance ===
在长直走廊 / 镜面 / 重度对称的场景下，铺 ''高反光板''作为人工地标，几何匹配亚厘米精度。详见 [[Special:MyLanguage/使用手册 - 激光SLAM＋反光板建图手册|激光 SLAM + 反光板建图手册]]。

In long corridors / mirrored / heavily symmetric scenes, deploy high-reflectivity panels as artificial landmarks for sub-cm geometric matching.

=== 5. 自适应协方差 / Adaptive covariance ===
扫描匹配的输出位姿同时附带 ''协方差矩阵''（来自 Hessian 求逆）。当协方差大 → TightCoupler 自动降权，让 IMU / 里程计主导；协方差小 → 激光主导。

The scan matcher outputs not only a pose but its covariance (from Hessian inverse). When uncertainty is high, TightCoupler down-weights laser and lets IMU / odom dominate; when low, laser leads.

=== 6. 多源融合 / Multi-source fusion ===
激光不是唯一定位源 —— 与 [[Special:MyLanguage/地纹SLAM技术概述|地纹]]、[[Special:MyLanguage/天花板SLAM|天花板]]、[[Special:MyLanguage/二维码识别导航|二维码]]、IMU、RTK、UWB 紧耦合（[[Special:MyLanguage/多定位源的自动综合|多定位源的自动综合]]）。

=== 7. 局部 / 全局重定位 / Local / global re-localisation ===
"丢线"分两级：
* '''局部丢失''' (协方差 > 阈值持续 N 帧) → 小搜索半径重定位
* '''全局丢失''' (局部重定位失败 > T 秒) → 全图分支限界搜索（[[Special:MyLanguage/激光SLAM建图|建图]] 提供的初始地图）

"Lost" comes in two grades: local (covariance > threshold for N frames) → small search radius; global (local recovery fails > T seconds) → full-map branch-and-bound.

=== 8. 长期地图自更新 / Long-term map self-update ===
环境会变（货架挪位、临时区域开通）。Detour 定期把"明显持久的占用变化"合并到地图：可选 ''自动''（默认关）或 ''手动审批''（推荐）。

Environments drift. Detour can fold "obviously persistent occupancy changes" back into the map — manual approval (default) or auto-merge (opt-in).

=== 9. 弱场景预测 / Weak-scene prediction ===
建图后离线分析地图：每个格点 ''几何信息量''有多大（垂直墙体的距离、特征覆盖角度）。低信息量区域在 UI 上显示为黄色，提示开发者 ''加反光板''或 ''减少在此区段做精动作''。

Off-line analysis after mapping: per-cell ''geometric information score'' (perpendicular wall distance, feature angular coverage). Low-score regions show yellow in the UI — hint to add reflectors or avoid precise work there.

== 不属于 SLAM 的鲁棒性 / Things outside SLAM proper ==
有些鲁棒性是 ''上层组件''的责任，不应混入 SLAM：

* '''传感器故障切换''' / Sensor failover: Medulla 监测雷达 watchdog；超时切到备份雷达。
* '''突遇人员''': Clumsy 局部 e-stop（[[Special:MyLanguage/绕障行走|绕障行走]]）。
* '''任务级回退''': SimpleCore 收到位姿 ''totally lost''事件 → 全局停车，操作工介入。

* Sensor failover: Medulla's watchdog flips to a backup lidar.
* Sudden people: Clumsy's local e-stop.
* Mission-level fallback: SimpleCore halts the fleet when localisation is utterly lost; operator intervention.

== 调试与验证 / Validation ==
* '''SLAM 健康指标''': Detour UI 显示协方差、闭环数 / s、动态过滤丢点率、活跃 SLAM 后端。
* '''回放''': 用 [[Special:MyLanguage/使用手册 - 数据录制与回放手册|数据录制与回放]] 在离线复现疑难帧。
* '''Stress test''': 在仓库引入有意的扰动（多人通过、临时叉车），观察 SLAM 输出的位姿连续性。

== 相关页面 / See also ==
* [[Special:MyLanguage/Detour激光SLAM算法详解|Detour激光SLAM算法详解]]
* [[Special:MyLanguage/激光SLAM的能力边界|激光SLAM的能力边界]]
* [[Special:MyLanguage/激光SLAM建图|激光SLAM建图]]
* [[Special:MyLanguage/多定位源的自动综合|多定位源的自动综合]]
* [[Special:MyLanguage/使用手册 - 分析定位问题|使用手册 - 分析定位问题]]

[[Category:技术报告]]

二维码识别导航

2026-05-16T11:42:55Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
二维码导航（QR-based navigation）把 ''二维码''作为地面 / 立面的人工地标，车上相机识别二维码 ID + 几何位姿，反推车体绝对位姿。它是 MDCS 中 ''最简单、最低成本''的定位方案，但对地面平整度与维护有较高要求。

QR-code navigation uses QR tags on the floor or walls as artificial landmarks. An on-board camera reads tag ID + geometric pose, inverting to get the vehicle's absolute pose. It's the simplest, lowest-cost localisation option in MDCS, but demands smooth floors and ongoing tag maintenance.

== 与其它方案的对比 / vs alternatives ==
{| class="wikitable"
! 项 / Item !! 二维码 / QR !! [[Special:MyLanguage/色带和磁条导航|色带 / 磁条]] !! 激光 SLAM
|-
| 路径自由度 / Path freedom || 极高（不需要连续轨道）|| 强制沿铺设线 || 自由
|-
| 部署成本 / Deploy cost || 低（贴二维码）|| 中（贴色带 / 磁条）|| 高（建图 + 调试）
|-
| 维护 / Maintenance || 高（二维码易磨损）|| 中 || 低
|-
| 定位精度 / Pose precision || ±10 mm / 0.5° (单二维码) || ±5 mm 横向 || ±5–20 mm
|-
| 地面平整度要求 / Flatness || 高（防相机俯仰误差）|| 中 || 低
|-
| 复用激光的能力 / Reuse with SLAM || 无 || 无 || N/A
|}

== 硬件 / Hardware ==
* '''相机''': 下视工业相机 + LED 环形灯（防自然光干扰）
* '''二维码''': 5–15 cm 边长；推荐用 ArUco（识别速度 + 编码效率）或 AprilTag（鲁棒性最高）
* '''贴布''': 镭雕金属牌或防水贴纸 + 透明保护层
* '''分辨率''': 相机像素 / 二维码尺寸需保证 ≥ 20 像素 / 二维码方格边长

== 算法 / Algorithm ==
=== 检测与解码 / Detection & decode ===
1. 灰度化 + 自适应阈值 → 边缘检测
2. 多边形拟合，筛选有 ''4 角 + 内方框''的候选
3. 透视变换矫正
4. 解码 ID（ArUco / AprilTag）

=== 位姿解算 / Pose estimation ===
已知二维码的 ''边长'' L 和 ''4 个角点''像素坐标 → PnP 求解相机相对二维码位姿。再用 ''二维码 → 世界''变换（预先标定的二维码绝对位姿）反推车体在世界的位姿。

Given the tag's edge length L and its four corner pixel coordinates, PnP solves the camera-relative pose. Multiplying by the tag-to-world transform (calibrated up-front) gives the vehicle's world pose.

=== 多二维码融合 / Multi-tag fusion ===
单帧中若同时见到 N ≥ 2 个二维码，做 ''最小二乘''融合，精度提升 √N。

If multiple tags are visible in one frame, fuse them by least squares; precision scales as √N.

== 部署 / Deployment ==
'''布点规则 / Tag placement rules''':
* 关键停靠位（取放料工位、充电位）正下方贴
* 长直走廊每 1.5–3 m 一个
* 分叉前后各贴一对
* 高速段（> 1 m/s）二维码间距应 < 1 m

'''标定 / Calibration''':
* 每个二维码贴完后，用 ''标尺 + 总站''测其绝对位姿，写入 Detour 配置。
* 标定误差直接进入定位结果，必须 ≤ 5 mm / 0.2°。
* 详见 [[Special:MyLanguage/纯二维码导航|纯二维码导航]] 与 [[Special:MyLanguage/使用手册 - 在地纹导航中使用二维码快速找回定位|地纹导航中使用二维码快速找回定位]]。

'''维护 / Maintenance''':
* 每周检查关键二维码完整性。
* 磨损 / 部分遮挡 → 立即更换。
* 二维码贴布建议用 ''可剥离强力胶''加可清洁透明膜保护。

== MDCS 集成 / MDCS integration ==
二维码定位作为 Detour 的一个 ''SLAM 后端''：
* `useQRSlam = true` 在 Detour 配置中启用
* 二维码地图存为 JSON（每条目：tagId + (x, y, z, th)）
* TightCoupler 把 QR 位姿与激光 / IMU 融合

QR localisation enters Detour as a SLAM backend. Enable `useQRSlam = true`; provide a JSON tag map (tagId + 4-DoF world pose). TightCoupler fuses QR with laser / IMU.

== 与"纯二维码导航"的区别 / vs pure-QR navigation ==
* '''混合模式'''（本页）: QR 作为 Detour 的一个观测源，与 SLAM 共存。
* '''纯二维码''': 只用二维码定位，无 SLAM；车体每帧必须看到 ≥ 1 个二维码。见 [[Special:MyLanguage/纯二维码导航|纯二维码导航]]。

The hybrid mode (this page) lets QR coexist with SLAM. ''Pure''-QR mode (linked page) uses no SLAM and requires the camera to see ≥ 1 tag every frame.

== 常见问题 / Common issues ==
* '''二维码反光''' / Glare: 调相机角度 + LED 偏振。
* '''叉车叉齿挡住''' / Forks blocking view: 相机不要装在叉齿下方。
* '''高速运动模糊''' / Motion blur: 相机用 ''全局快门''与短曝光（< 1 ms）。
* '''标定漂''' / Pose drift due to calibration: 每月做一次随机抽检（5 个二维码）。

== 相关页面 / See also ==
* [[Special:MyLanguage/纯二维码导航|纯二维码导航]]
* [[Special:MyLanguage/色带和磁条导航|色带和磁条导航]]
* [[Special:MyLanguage/使用手册 - 在地纹导航中使用二维码快速找回定位|在地纹导航中使用二维码快速找回定位]]
* [[Special:MyLanguage/多定位源的自动综合|多定位源的自动综合]]
* [[Special:MyLanguage/Detour软件架构|Detour软件架构]]

[[Category:定位导航相关手册]]

Simple软件架构

2026-05-16T11:42:54Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
Simple 是 MDCS 的车队层，分为两部分：
'''SimpleCore'''（核心算法库 —— 交管、寻路、包络、可达性、调度内核），
'''SimpleComposer'''（基于 SimpleCore 的 UI 壳 + 插件宿主）。

Simple is the fleet layer of MDCS, split in two parts:
'''SimpleCore''' (the algorithm library — traffic control, pathfinding, envelopes, reachability, scheduling kernel) and
'''SimpleComposer''' (a UI shell + plugin host built on top of SimpleCore).

== SimpleCore ==
完全独立的 .NET 库（`D:\src\Simple\SimpleCore\`），可被任何应用引用。它定义了：

A standalone .NET library at `D:\src\Simple\SimpleCore\`, embeddable in any application. It defines:

{| class="wikitable"
! 模块 / Module !! 用途 / Use
|-
| `AbstractCar` (`PropType\AbstractCar.cs:346`) || 调度可见的车的最小契约 / minimal contract for a scheduled vehicle
|-
| `AGVInterface` (`BasicProps\AGVInterface.cs`) || 任务脚本（TopazScript）调用的车 API / car API called by mission scripts
|-
| `DPSPlanner` || [[Special:MyLanguage/DPS调度算法详解|DPS]] 多车死锁规划 / DPS multi-car deadlock-free planner
|-
| `Envelope` || 车体包络 + 站点占用判定 / envelope + site-occupancy logic
|-
| `Reachability` || 可达性状态机 / reachability state machine — see [[Special:MyLanguage/可达性状态编程|可达性状态编程]]
|-
| `FlowFieldPlanner` || [[Special:MyLanguage/流场规划|流场规划]] / flow-field planner
|-
| `NetworkFlowBizPlanner` || [[Special:MyLanguage/基于网络流的业务规划器|基于网络流的业务规划器]] / network-flow business planner
|-
| `World` || 地图（站点 + 路径段 + 区域）/ map (sites + path segments + zones)
|-
| `TopazEngine` || 任务脚本解释器 / mission-script interpreter
|}

SimpleCore 不依赖 Windows、UI、SimpleComposer、Clumsy 或 Medulla —— 可在 Linux 工控机上单独跑。
SimpleCore depends on none of Windows, UI, SimpleComposer, Clumsy or Medulla — it runs standalone on Linux IPCs.

== SimpleComposer ==
基于 SimpleCore 的 ''标准车队管理 UI''，位于 `D:\src\Simple\SimpleComposer\`。它提供：

The standard fleet-management UI built on SimpleCore. It provides:

* '''CAD 工具''' / CAD tool — 见 [[Special:MyLanguage/开发手册 - SimpleComposer界面开发 - CAD工具|开发手册 - CAD工具]]
* '''车型插件接口''' / car-type plugin interface — `Car` 与 `ClumsyCar` 子类化点
* '''任务脚本编辑器''' / mission-script editor
* '''实时监控面板''' / live monitoring panel — 包络、锁、车辆状态
* '''仿真''' / simulation — 整套调度算法可在不接真车的情况下跑

`SimpleComposer.RCS.Car` (`D:\src\Simple\SimpleComposer\RCS\Car.cs:33`) 是车的 ''Composer 端基类''，封装 SimpleCore 的 `AbstractCar` 加上 UI 字段、地图坐标转换、可视化属性。`ClumsyCar` (`D:\src\Simple\SimpleComposer\RCS\ClumsyCar.cs:34`) 是它的子类，专为跑 MDCS 车载的车设计；自评估车（PLC / 磁条 / 二维码）则直接继承 `Car` 并实现 nested `AGV : AGVInterface`。

`SimpleComposer.RCS.Car` is the Composer-side base — `AbstractCar` + UI fields + coordinate transforms + render props. `ClumsyCar` extends it for vehicles running MDCS on-board. Self-evaluating cars subclass `Car` directly with a nested `AGV : AGVInterface`.

== 数据流 / Data flow ==

业务系统 (WMS / ERP) → SimpleComposer 任务接收
│
▼
SimpleComposer 任务编排 (CarProgram)
│
▼
SegmentPlan.Compile → TopazScript
│
▼
Car.actualSendScript(script)
├─ ClumsyCar: HTTP POST 到车载 → TopazEngine on-board
└─ 自评估车: 本地 SelfEvaluating(agv, script) → 厂商命令
│
▼ (周期心跳)
Car.keepAlive() ← 车体上报 (x, y, th, siteId, ...)

详见 [[Special:MyLanguage/AGV任务运行逻辑|AGV任务运行逻辑]] 与 [[Special:MyLanguage/调度内核运行原理|调度内核运行原理]]。

== 算法层次 / Algorithm layering ==
{| class="wikitable"
! 层 / Layer !! 关切 / Concern !! 内核 / Engine
|-
| 业务规划 / Business || 哪台车做哪个任务 || `NetworkFlowBizPlanner`
|-
| 路径规划 / Pathfinding || 当前任务沿哪条路径 || A* / 流场（[[Special:MyLanguage/流场规划|流场规划]]）+ 启发器
|-
| 交管 / Traffic control || 多车并存如何避碰 || DPS（[[Special:MyLanguage/DPS调度算法详解|DPS算法]]）
|-
| 可达性 / Reachability || 当前状态下哪些路径有效 || 状态机（[[Special:MyLanguage/可达性状态编程|可达性状态编程]]）
|-
| 包络 / Envelope || 车体当前占用哪些站点 || 几何 + Reachability 联动
|}

== 插件类型 / Plugin types ==
SimpleComposer 支持三类插件：
SimpleComposer supports three plugin classes:

# '''车型插件''' / Car-type — 派生 `ClumsyCar` 或 `Car`，加 `[CarType]` 属性。新车上线主用。
# '''业务插件''' / Business — 派生 `BusinessLogic`，定义自定义任务类型、字段、动作。
# '''CAD 工具插件''' / CAD-tool — 派生 `CADToolPlugin`，给 CAD 画布加自定义可视化与编辑工具。

详见 [[Special:MyLanguage/使用手册 - Simple:从使用到开发|使用手册 - Simple:从使用到开发]] 和 [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|如何基于SimpleCore核心库进行调度系统开发]]。

== 关键决策 / Key design choices ==
* '''SimpleCore 与 SimpleComposer 解耦''' —— SimpleCore 是纯算法库；SimpleComposer 可被替换。
* '''TopazScript 中间表达''' —— 任务脚本而不是 RPC，让 ClumsyCar 与自评估车共用同一编译产物。
* '''DPS 预先规划交管''' —— 牺牲灵活性换 ''可证明的无死锁''；动态场景多时切流场。
* '''可达性是状态机而不是布尔''' —— 同一物理车在 ''带载 / 不带载 / 高位 / 电量低''等状态下走不同路径。

== 相关页面 / See also ==
* [[Special:MyLanguage/AGV任务运行逻辑|AGV任务运行逻辑]]
* [[Special:MyLanguage/调度内核运行原理|调度内核运行原理]]
* [[Special:MyLanguage/DPS调度算法详解|DPS调度算法详解]]
* [[Special:MyLanguage/流场规划|流场规划]]
* [[Special:MyLanguage/基于网络流的业务规划器|基于网络流的业务规划器]]
* [[Special:MyLanguage/Simple-API|Simple-API]]
* [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|如何基于SimpleCore核心库进行调度系统开发]]
* [[Special:MyLanguage/开发手册 - SimpleComposer界面开发 - CAD工具|开发手册 - SimpleComposer界面开发 - CAD工具]]

[[Category:开发手册]]

Medulla软件架构

2026-05-16T11:42:53Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
Medulla 是 MDCS 的硬件层：它把异构硬件（电机控制器、PLC、传感器、相机、雷达）抽象成 ''IOObject'' 与 ''字段''，并提供跨进程共享内存（DObject）让上层算法订阅数据，无关进程或语言。

Medulla is the hardware-abstraction layer of MDCS: it wraps heterogeneous hardware (motor controllers, PLCs, sensors, cameras, lidars) into '''IOObject''' instances exposing typed fields, and exposes them across processes via the '''DObject''' shared-memory bus.

== 关键概念 / Key concepts ==
{| class="wikitable"
! 概念 / Concept !! 含义 / Meaning
|-
| `IOObject` || 一切硬件抽象的基类 / base class for everything: lidars, cameras, carts. File: `D:\src\M2\MedullaCore\Types\IO.cs:47`
|-
| Sub-classes || `Lidar2DIOObject`, `Lidar3DIOObject`, `CartDefinition`, camera `MainIOObject`
|-
| `[AsInitParam]` || 启动配置字段 / start-time config field (JSON-serialised)
|-
| `[AsUpperIO]` / `[AsLowerIO]` || 上 / 下位 IO 字段 / command-down / status-up field
|-
| `[UseLadderLogic]` || 周期性控制循环（默认 50 ms）/ cyclic control loop (default 50 ms)
|-
| `[IOObjectMonitor]` || 注册字段到监控面板 / dashboard registration
|-
| `[IOObjectUtility]` / `WebUtility` || 注册方法为 UI 按钮 / web API / register as UI button / web endpoint
|-
| `DObject` || 命名共享内存（跨进程）/ named shared memory (cross-process). 详见 [[Special:MyLanguage/DObject|DObject]]
|-
| `LadderLogic<T>` || 周期性回调宿主 / cyclic-callback host
|}

== 体系结构 / Architecture ==

Plugin DLL (CartDef, Lidar2DIOObject, ...)
│ reflection-loaded by name (no [Plugin] attr)
▼
MedullaCore: IOObject lifecycle, threading, DObject pub/sub
│
▼
DObject (shared memory, cross-process)
▲ ▲
│ │
Detour, Clumsy, SimpleComposer — subscribers

Medulla 既是 ''加载器'' 又是 ''运行时''：插件 DLL 通过 `io load plugins/X.dll` 启动命令载入；反射查找入口类（`MainIOObject` 或 `CartDefinition` 派生），实例化，调用 `Init()`，启动配置的 LadderLogic 周期线程。

Medulla is both loader and runtime: plugin DLLs are loaded via the `io load plugins/X.dll` startup command; reflection finds the entry type (named `MainIOObject` or derived from `CartDefinition`), instantiates it, calls `Init()`, and spawns the configured LadderLogic threads.

== 插件加载示例 / Plugin loading example ==
<syntaxhighlight lang="text">
# startup.iocmd
lidar = io load plugins/MyLidar.dll
lidar Start 192.168.0.2 2110

cart = io load plugins/MyCart.dll
cart Init
</syntaxhighlight>

`io load` 把 DLL 反射扫描后实例化入口类；其余命令通过赋值（左侧）保存引用，并把命令转发给该实例。

`io load` reflection-scans the DLL, instantiates the entry type, and the variable assignment keeps a reference. Subsequent commands forward to the instance.

== 上下位 IO 数据流 / Upper / lower IO data flow ==
见 [[Special:MyLanguage/车体抽象原理|车体抽象原理]]。简而言之：
* '''上位''' IO（`[AsUpperIO]`）= 调度 / Clumsy 写入命令；Medulla 转发到硬件。
* '''下位''' IO（`[AsLowerIO]`）= Medulla 读硬件状态；调度 / Clumsy 订阅。
* '''初始化参数''' IO（`[AsInitParam]`）= 启动时一次性 JSON 注入。
* '''监控'''（`[IOObjectMonitor]`）= 显示在 Medulla 仪表盘 + 暴露给 Web API。

== LadderLogic 周期循环 / Ladder cycles ==
LadderLogic 是 Medulla 提供的 ''周期性控制循环''宿主。一个 `CartDefinition` 可以有多个 LadderLogic 嵌套类，每个 `[UseLadderLogic(IntervalMs = N)]`：

A `CartDefinition` may declare multiple nested LadderLogic classes, each at a configured tick rate:

<syntaxhighlight lang="csharp">
[UseLadderLogic(IntervalMs = 50)]
public class ControlLoop : LadderLogic<MyCart>
{
public override void Run(MyCart self)
{
// 写 UpperIO → 读硬件 → 更新 LowerIO
}
}

[UseLadderLogic(IntervalMs = 200)]
public class BatteryMonitor : LadderLogic<MyCart>
{
public override void Run(MyCart self)
{
// 较慢的循环，例如电池电压采样
}
}
</syntaxhighlight>

== DObject 共享内存 / DObject IPC ==
DObject 是 Medulla 提供的 ''命名共享内存 pub/sub''：发布者写一个二进制 blob，订阅者按名字订阅，等到下一帧再读。Detour 用 DObject 读雷达数据；SimpleComposer 用 DObject 读车辆状态。详见 [[Special:MyLanguage/DObject|DObject]]。

DObject is the named binary pub/sub channel. The publisher writes a blob, subscribers wait on the name and consume. Used by Detour for lidar, SimpleComposer for vehicle state. See the dedicated page.

== 与 Medulla 1（旧版）的区别 / vs legacy Medulla ==
* `D:\src\M2\` 是 Medulla2（当前在用），`D:\src\Medulla\` 是 ''legacy''。
* Medulla2 引入了：DObject 替代旧 IPC、属性化 IO 表（`[AsUpperIO]` 等）、`LessokajiWeaver` 编译后处理生成代理类。
* 已 ''不要''使用 legacy Medulla 编写新插件。

== 相关页面 / See also ==
* [[Special:MyLanguage/Medulla|Medulla]] — 主页 / canonical entry
* [[Special:MyLanguage/Medulla-API|Medulla-API]]
* [[Special:MyLanguage/DObject|DObject]]
* [[Special:MyLanguage/车体抽象原理|车体抽象原理]]
* [[Special:MyLanguage/如何适配新的雷达|如何适配新的雷达]]
* [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]]

[[Category:开发手册]]

LessokajiWeaver编译后处理工具

2026-05-16T11:42:52Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
LessokajiWeaver 是 MDCS 用到的 ''编译后处理''工具链（基于 Fody）。它在 C# 程序集编译完成后做 IL 注入，自动生成 ''字段代理类''、''属性序列化代码''、''反射加速''等基础设施代码，让插件作者只需写少量声明性属性，剩下的"管道"由 Weaver 自动织入。

LessokajiWeaver is MDCS's post-compile IL-weaving toolchain (Fody-based). It runs after C# assembly compilation and injects IL to generate ''field-proxy classes'', ''property serialisation'', ''reflection accelerators'', etc. Plugin authors write a few declarative attributes; the plumbing is woven in automatically.

== 主要场景 / Main scenarios ==
{| class="wikitable"
! 场景 / Scenario !! Weaver 做的 / What Weaver does
|-
| Medulla `[AsUpperIO]` / `[AsLowerIO]` 字段 || 生成代理 setter / getter，自动同步到 DObject
|-
| Medulla `[AsInitParam]` || 生成 JSON 序列化代码，绑定到启动配置加载
|-
| Medulla `[IOObjectMonitor]` || 注册到监控面板 + Web API
|-
| CycleGUI `[Cyclic]` 协程方法 || 自动包装为 IEnumerable<Cycle> 安全宿主
|-
| Clumsy `[MovementTest]` || 注册到测试 UI 面板
|-
| 多语言（i18n）字符串字段 || 生成查表逻辑（见 [[Special:MyLanguage/自动I18N（多语言功能）|自动 I18N]]）
|}

== 工作流程 / Pipeline ==

开发者 .cs → csc 编译 → .dll
│
▼
LessokajiWeaver.Fody (post-build)
│
▼
织入后的 .dll
│
▼
Medulla / Clumsy 运行时加载

工程引用方式（已由 [[Special:MyLanguage/MDCS-plugin-helper|MDCS-plugin-helper]] 模板自动配置）：

In a plugin's .csproj (auto-configured by the plugin-helper template):

<syntaxhighlight lang="xml">
<ItemGroup>
<PackageReference Include="Fody" Version="6.x" />
<Reference Include="LessokajiWeaver.Fody">
<HintPath>..\tools\LessokajiWeaver.Fody.dll</HintPath>
</Reference>
<Reference Include="LessokajiWeaverUtilities">
<HintPath>..\tools\LessokajiWeaverUtilities.dll</HintPath>
</Reference>
</ItemGroup>
</syntaxhighlight>

`FodyWeavers.xml` 在工程根目录：
<syntaxhighlight lang="xml">
<Weavers>
<LessokajiWeaver/>
</Weavers>
</syntaxhighlight>

== 为什么用 Weaver / Why weave ==
不用 Weaver 也能用反射做同样的事，但每次访问字段都付反射开销（~100x getter）。Weaver 在编译期把反射调用 ''变成普通 IL''，运行时零开销：

Without Weaver you'd use reflection at runtime, paying ~100× cost per access. Weaver moves the reflection to compile-time, generating direct IL with zero runtime overhead:

<syntaxhighlight lang="csharp">
// 开发者写：
[AsUpperIO]
public float vCmd;

// 编译后 Weaver 注入相当于：
private float _vCmd;
public float vCmd
{
get => _vCmd;
set
{
_vCmd = value;
IOSync.PostToDObject(this, "vCmd", value); // 自动 IPC
}
}
</syntaxhighlight>

== 调试 / Debugging ==
* 织入失败：检查 `bin\<config>\` 下是否有 `FodyWeavers.xml` 编译报错；通常是属性用法错误（如把 `[AsUpperIO]` 加在 readonly 字段上）。
* 织入产物可视化：用 ILSpy / dnSpy 打开织入后的 dll，查看 setter / getter 注入逻辑。
* 性能 / Performance: Weaver 不引入额外运行时依赖；增加的体积通常 < 5%。

== 兼容性 / Compatibility ==
* .NET Framework 4.6.2+ / .NET 6+
* 必须用 ''Release 模式''发布插件（Weaver 在 Debug 也运行，但 Debug 会保留更多调试符号导致体积偏大）。
* 与 ''AOT 编译''不兼容（IL 注入依赖 JIT）。

== 与 LessokajiWeaverUtilities 的关系 / Utilities ==
`LessokajiWeaverUtilities.dll` 是 Weaver 注入代码运行时依赖的小库（attribute 定义 + 工具方法）。插件 csproj 必须引用，但开发者一般不直接调用。

`LessokajiWeaverUtilities.dll` is the runtime support library (attribute definitions + helpers). Plugin csproj must reference it but developers rarely call into it directly.

== 相关页面 / See also ==
* [[Special:MyLanguage/Medulla|Medulla]] / [[Special:MyLanguage/Medulla软件架构|Medulla软件架构]]
* [[Special:MyLanguage/自动I18N（多语言功能）|自动I18N（多语言功能）]]
* [[Special:MyLanguage/如何使用LessokajiWeaver的多语言功能|如何使用LessokajiWeaver的多语言功能]]
* [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]

[[Category:二次开发相关说明]]

Detour软件架构

2026-05-16T11:42:51Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
Detour 是 MDCS 的定位系统：它整合 ''激光 SLAM''、''地纹 SLAM''、''天花板 SLAM''、''二维码导航'' 等多种定位手段，输出统一的 6-DoF 位姿给上层（Clumsy 自动驾驶 / SimpleComposer 调度）。Detour 不接受外部插件 —— 它通过 [[Special:MyLanguage/DObject|DObject]] 共享内存订阅 Medulla 发布的传感器数据，并通过 ''外部反馈接口''接收里程计 / IMU / RTK / UWB。

Detour is the MDCS positioning subsystem. It fuses laser SLAM, ground-texture SLAM, ceiling SLAM, QR navigation, and other localisation sources into a unified 6-DoF pose for the upper layers (Clumsy autopilot / SimpleComposer fleet). Detour does not accept plugins — it consumes Medulla sensor publications via DObject, and external poses (odometry / IMU / RTK / UWB) via the external-feed API.

== 子模块 / Subsystems ==
{| class="wikitable"
! 模块 / Module !! 文件 / File !! 用途 / Use
|-
| Lidar consumer || `D:\src\Detour\DetourCore\CartDefinition\Lidar.cs:302-311` || 从 Medulla DObject 订阅雷达帧
|-
| Tight coupler || `D:\src\Detour\DetourCore\Algorithms\TightCoupler.ExternalCoupler.cs` || 接收外部位姿、做紧耦合融合
|-
| Laser SLAM || `D:\src\Detour\DetourCore\Algorithms\LaserSLAM*` || 见 [[Special:MyLanguage/Detour激光SLAM算法详解|Detour 激光 SLAM 算法详解]]
|-
| Ground-texture SLAM || `D:\src\Detour\DetourCore\Algorithms\GroundTexture*` || 见 [[Special:MyLanguage/Detour地面纹理SLAM算法详解|地面纹理 SLAM 算法详解]]
|-
| QR / fiducial || `D:\src\Detour\DetourCore\Algorithms\QR*` || 见 [[Special:MyLanguage/二维码识别导航|二维码识别导航]]
|-
| Multi-source fuser || `TightCoupler` || 见 [[Special:MyLanguage/多定位源的自动综合|多定位源的自动综合]]
|}

== 数据流 / Data flow ==

Medulla 传感器插件
│ output() → DObject(name)
▼
Detour 订阅:
- LidarConsumer.ReadLidar()
- CameraConsumer (ground-texture / ceiling / QR)
│
▼
各 SLAM 后端 (laser / texture / ceiling / QR)
│ 每个产生一组 ''观测约束''
▼
TightCoupler (位姿图优化)
│ + 外部反馈 (PostExternalFeed)
▼
统一位姿 (x, y, z, th, pitch, roll, tick)
│ 发布到 DObject "pose"
▼
Clumsy / SimpleComposer 订阅

== 外部反馈 / External feeds ==
非传感器位姿（轮编里程计 / IMU / RTK / UWB / 二次定位源）通过 ''外部反馈''进入 Detour：

Non-sensor poses (wheel odometry, IMU, RTK, UWB, secondary sources) enter Detour through the ''external-feed'' API:

<syntaxhighlight lang="csharp">
TightCoupler.PostExternalFeed(new ExternalFeed
{
name = "wheel_imu",
counter = tick++,
hasTranslation = true,
hasRotation = true,
is2D = true,
integrated = true, // 积分量 / cumulative
x = odom_x, y = odom_y, th = odom_th
}, "WheelOdom");
</syntaxhighlight>

字段含义见 `TightCoupler.ExternalCoupler.cs`：`hasTranslation/hasRotation`（包含的自由度）、`integrated`（积分量 vs 单帧量）、`toRemap`（绝对参考系下，需要全局重映射）、`startingTick`（首帧基准）。

Field semantics in `TightCoupler.ExternalCoupler.cs`: `hasTranslation/hasRotation` (DOFs), `integrated` (cumulative vs single-frame), `toRemap` (absolute, needs global remap), `startingTick` (reference baseline).

== 多 SLAM 共存策略 / Multi-SLAM coexistence ==
* '''并行运行''': 默认每种 SLAM 后端都开，各产生自己的观测约束。
* '''置信加权''': TightCoupler 根据每个后端的协方差矩阵做加权融合。
* '''场景切换''': 某个后端连续 ''N 帧''置信度 < 阈值 → 临时禁用其约束。
* '''硬切换''': 用户可在 UI 中强制选择"单一定位源"模式（调试用）。

* All SLAM backends run in parallel by default.
* TightCoupler weights by per-backend covariance.
* A backend that's degraded for N frames is temporarily disabled.
* A user can force single-source mode (debug).

== 定位输出 / Positioning output ==
Detour 把当前最优位姿写到 ''pose'' 命名的 DObject：

The current best pose is published to a DObject named `pose`:

<syntaxhighlight lang="csharp">
public struct DetourPose
{
public double x, y, z; // mm
public double th; // 偏航 / yaw rad
public double pitch, roll; // rad
public long tick; // 时间戳 / system tick
public double cov_xy; // 平面协方差 / planar covariance
public double cov_th; // 偏航协方差 / yaw covariance
public string activeBackend; // 当前主用 SLAM 后端
}
</syntaxhighlight>

== 与 Medulla 的关系 / Relation to Medulla ==
Detour ''不是'' Medulla 的插件；它是独立的 .NET 进程，与 Medulla 同主机但不同进程，二者只通过 DObject 共享内存通讯。这种设计使得 Detour 可以独立部署 / 升级 / 切换 SLAM 算法而不影响 Medulla。

Detour is '''not''' a Medulla plugin. It's a separate .NET process on the same host, communicating with Medulla only via DObject shared memory. This decoupling lets Detour deploy / upgrade / swap SLAM algorithms independently.

== DetourStandalone 与 DetourLite / Standalone & Lite variants ==
* '''DetourStandalone''': 完整 Detour，含全部 SLAM + UI。详见 [[Special:MyLanguage/DetourStandalonePluginGuide|DetourStandalonePluginGuide]]。
* '''DetourLite''': 精简版，只含必要功能 + 检查表自检。见 [[Special:MyLanguage/DetourLite检查表|DetourLite 检查表]]。

== 相关页面 / See also ==
* [[Special:MyLanguage/Detour|Detour]]
* [[Special:MyLanguage/Detour简介|Detour简介]]
* [[Special:MyLanguage/Detour-API|Detour-API]]
* [[Special:MyLanguage/Detour激光SLAM算法详解|Detour激光SLAM算法详解]]
* [[Special:MyLanguage/Detour地面纹理SLAM算法详解|Detour地面纹理SLAM算法详解]]
* [[Special:MyLanguage/多定位源的自动综合|多定位源的自动综合]]

[[Category:开发手册]]

Detour激光SLAM算法详解

2026-05-16T11:42:50Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
Detour 的激光 SLAM 是 MDCS 中最常用的主定位源：在仓库 / 工厂场景下，2D 激光雷达 ≥ 270° 视场扫到墙 / 立柱 / 货架轮廓，配合 IMU + 轮编里程计做紧耦合，构建 ''占用栅格 + 位姿图'' 地图，运行时做 ''扫描匹配 + 全局重定位''。

Detour's laser SLAM is the most-used primary localisation source in MDCS. In warehouse / factory scenes a ≥ 270° FOV 2D lidar scans walls / pillars / rack outlines; with tight-coupled IMU + wheel odometry it builds an ''occupancy grid + pose graph'' and at runtime runs ''scan matching + global re-localisation''.

详见 [[Special:MyLanguage/具有高鲁棒性的激光SLAM算法|具有高鲁棒性的激光 SLAM 算法]] 中关于鲁棒性技巧的展开。
See [[Special:MyLanguage/具有高鲁棒性的激光SLAM算法|robust-laser-SLAM]] for the robustness toolbox.

== 算法栈 / Algorithm stack ==
{| class="wikitable"
! 阶段 / Stage !! 算法 / Algorithm !! 输入 / Input !! 输出 / Output
|-
| 建图 / Mapping || GraphSLAM + 多分辨率 ICP 闭环 || 录制的雷达 + IMU + 里程计序列 || 占用栅格 + 位姿图 (.map)
|-
| 重定位 / Re-localisation || 多分辨率分支限界 || 当前一帧雷达 + 粗位姿先验 || 6-DoF 位姿（含协方差）
|-
| 跟踪 / Tracking || 高斯-牛顿扫描匹配 || 当前帧 + 上一帧位姿 || 增量位姿
|-
| 反光板模式 / Reflector mode || 反光板高强度过滤 + 几何匹配 || 当前帧 ''反光板点''的子集 + 反光板地图 || 高精度位姿（< 5 mm / 0.1°）
|}

== 构图流程 / Mapping pipeline ==
# '''数据录制 / Record''': 在场地中匀速、覆盖全部走廊地推 AGV / 推车，录制激光 + IMU + 里程计同步流。
# '''粗轨迹 / Coarse trajectory''': 用扫描匹配 + 里程计积分得粗轨迹。
# '''闭环检测 / Loop closure''': 多分辨率分支限界寻找回环候选；通过几何一致性筛选。
# '''位姿图优化 / Pose-graph optimisation''': g2o / Ceres 优化关键帧位姿。
# '''栅格化 / Rasterise''': 将所有关键帧的点云投影到全局栅格，生成可视化地图。
# '''编辑 / Edit''': 用 [[Special:MyLanguage/激光地图编辑指南|激光地图编辑指南]] 中的工具人工修正动态障碍、空洞等。

# Record laser + IMU + odom synchronously at moderate speed covering all corridors.
# Get a coarse trajectory via scan matching + odometry integration.
# Loop-closure search with multi-res branch-and-bound.
# Pose-graph optimisation (g2o / Ceres).
# Rasterise to a global occupancy grid.
# Manually edit to remove dynamic / artifacts.

== 运行时跟踪 / Runtime tracking ==
* 每帧雷达进来 → 用上一帧的位姿做先验 → 扫描匹配（高斯-牛顿）求增量位姿。
* 协方差由 Hessian 求逆给出；置信度低时 TightCoupler 自动降权。
* 当 IMU 里程计 + 激光观测出现 > 阈值偏差 → 触发"局部丢失"，进入 ''局部重定位''（小搜索半径）。
* 局部重定位失败超过 N 秒 → 全局重定位（用 [[Special:MyLanguage/激光SLAM建图|地图]] 全局搜索）。

== 反光板模式 / Reflector mode ==
对极简洁、特征贫乏的场景（如纯白墙仓库），可以铺设 ''高反光板''作为人工地标。Detour 自动从激光帧中按 ''强度阈值''过滤出反光板点，做几何配对得到亚厘米级位姿。

For featureless environments (white-wall warehouses) deploy high-reflectivity panels as artificial landmarks. Detour filters them by intensity and matches geometrically for sub-cm pose.

* 反光板布局要求 ≥ 3 个 ''非共线'' 反光板可见。
* 强度阈值在 Detour 配置中调（雷达适配时 `ReflexRange` 已归一化）。
* 详见 [[Special:MyLanguage/使用手册 - 激光SLAM＋反光板建图手册|激光 SLAM + 反光板建图手册]]。

== 关键参数 / Key parameters ==
{| class="wikitable"
! 参数 / Param !! 含义 / Meaning !! 默认 / Default
|-
| `scanMatchMaxIter` || 扫描匹配最大迭代次数 || 30
|-
| `scanMatchInitRange` || 初始搜索半径 (m) || 0.5
|-
| `loopClosureScore` || 闭环最低分数 || 0.7
|-
| `relocBranchDepth` || 重定位分支限界深度 || 6
|-
| `relocCovThresh` || 重定位接受的最大协方差 || 0.01 m² / 0.001 rad²
|-
| `reflexMinIntensity` || 反光板最低强度 || 0.7 (归一化后)
|}

== 已知能力边界 / Known limits ==
* 长直走廊（特征沿一个方向变化弱）易沿 Y 漂移；用反光板或 [[Special:MyLanguage/地纹SLAM技术概述|地纹]] 互补。
* 强动态环境（大量行人 / 叉车）需要 ''动态过滤''或 SLAM 限速（建图时 ≤ 0.5 m/s）。
* 户外阳光直射会使部分点云缺失；用激光遮光罩或避免高峰时段。
* 极端反光（镜面、塑料蒙皮）导致虚假点；建图前现场预查。

详见 [[Special:MyLanguage/激光SLAM的能力边界|激光 SLAM 的能力边界]]。

== 相关页面 / See also ==
* [[Special:MyLanguage/激光SLAM建图|激光SLAM建图]]
* [[Special:MyLanguage/激光SLAM的能力边界|激光SLAM的能力边界]]
* [[Special:MyLanguage/激光地图编辑指南|激光地图编辑指南]]
* [[Special:MyLanguage/具有高鲁棒性的激光SLAM算法|具有高鲁棒性的激光SLAM算法]]
* [[Special:MyLanguage/Detour软件架构|Detour软件架构]]
* [[Special:MyLanguage/多定位源的自动综合|多定位源的自动综合]]

[[Category:技术报告]]

Detour地面纹理SLAM算法详解

2026-05-16T11:42:50Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
地面纹理 SLAM（Ground-Texture SLAM）使用向下的高分辨率工业相机，把地面的微观纹理（划痕、混凝土颗粒、油渍、地砖缝）作为 ''全场景同质''的视觉地标，做位姿估计与建图。在激光 SLAM 表现差的场景（特征贫乏、动态多、地面平整）下效果显著。

Ground-texture SLAM uses a downward-facing high-res industrial camera and treats the floor's micro-features (scratches, concrete grit, oil stains, tile joints) as ''everywhere-homogeneous'' visual landmarks. It excels where laser SLAM is weak: featureless walls, heavy dynamic obstacles, but smooth uniform floors.

入门见 [[Special:MyLanguage/地纹SLAM技术概述|地纹 SLAM 技术概述]]；本页讲算法细节。
For an intro see [[Special:MyLanguage/地纹SLAM技术概述|the ground-texture SLAM overview]]; this page covers the algorithmic core.

== 算法原理 / Algorithm overview ==
{| class="wikitable"
! 模块 / Module !! 说明 / Description
|-
| 特征提取 / Feature extraction || ORB / FAST + BRIEF（每帧 ~500 个点）/ ORB / FAST + BRIEF (~500 features per frame)
|-
| 帧间匹配 / Frame matching || Hamming 距离 KNN + 比率测试 / KNN matching with ratio test
|-
| 位姿估计 / Pose estimation || PnP（2D-to-2D 因深度近似常数）/ 2D-2D PnP since depth ≈ const
|-
| 关键帧筛选 / Keyframe selection || 平移 ≥ 30 mm 或转角 ≥ 5° / displacement ≥ 30 mm or yaw ≥ 5°
|-
| 局部建图 / Local mapping || 关键帧池 + Bundle Adjustment / keyframe pool + BA
|-
| 全局闭环 / Global loop closure || 词袋（BoVW）/ Bag of Visual Words
|-
| 位姿图优化 / Pose-graph || g2o / Ceres
|}

== 硬件配置 / Hardware setup ==
{| class="wikitable"
! 部件 / Part !! 典型规格 / Typical
|-
| 相机 / Camera || 工业 USB3 全局快门，120 FPS，1 MP
|-
| 安装高度 / Mount height || 80–150 mm 距地 / ground-clearance
|-
| 视场 / FOV || 200 × 150 mm 实测覆盖区
|-
| 照明 / Lighting || 自带 LED 环形灯，确保不被外光影响
|-
| 防护 / Protection || 抗油 / 抗尘罩，定期清洁
|}

== 与激光 SLAM 的差异 / vs laser SLAM ==
{| class="wikitable"
! 项 / Item !! 激光 SLAM !! 地纹 SLAM
|-
| 主感知 / Primary sensing || 2D 距离扫描 / 2D ranges || 向下相机图像 / downward image
|-
| 全局位姿误差 / Global error || cm 量级（受墙体不规则影响）|| mm 量级（局部很准）
|-
| 全局漂移 / Global drift || 受闭环密度影响 || 重度依赖关键帧密度
|-
| 弱场景 / Weak case || 长走廊 / 反光板缺 || 极平整无纹理地面（如新漆面）
|-
| 重定位 / Re-loc || 全局粗定位足够 || 需要预先扫描全场地图
|-
| 计算需求 / Compute || CPU 中等 || CPU + GPU（GPU 加速特征匹配）；见 [[Special:MyLanguage/使用手册 - 如何在核显工控机上运行地纹导航|核显工控机]]
|}

== 工作流程 / Workflow ==

# 用专用扫描车在工地上 ''慢速、完全覆盖''采集地纹（推荐 ≤ 0.5 m/s）。
# 后处理生成 ''地纹地图''（特征点数据库 + 关键帧池）；典型大小 1 GB / 1000 m²。
# 上线时车上跑实时定位：每帧提特征 → 与本地关键帧匹配 → 估姿 → 周期性查全局 BoVW 做闭环。
# Detour TightCoupler 把地纹位姿与激光 / IMU 融合。

# Slowly traverse the entire site (≤ 0.5 m/s) to capture textures.
# Off-line build the ''texture map'' (feature DB + keyframe pool); typically ~1 GB per 1000 m².
# At runtime: extract features per frame → match to local keyframes → estimate pose → periodically query global BoVW for loop-closure.
# Detour's TightCoupler fuses ground-texture pose with laser + IMU.

== 关键参数 / Key parameters ==
* `featurePerFrame`: 500 (上下限 200–1000)
* `keyframeSpacing`: 30 mm
* `bowVocabSize`: 5000 个视觉单词
* `localBaWindow`: 10 关键帧
* `loopClosureMinScore`: 0.6

== 适用与不适用 / Applicability ==
'''适合 / Use when''':
* 地面有微观纹理（混凝土、地砖、橡胶颗粒）
* 工作面平整、车体俯仰/翻滚小
* 激光 SLAM 表现差（长走廊、镜面墙）

'''不适合 / Avoid when''':
* 地面持续湿水、油污（特征被遮）
* 地面定期翻新（特征漂变快）
* 上下楼梯 / 大坡度

== 快速找回定位 / Re-localisation in ground texture ==
地纹场景下"丢失定位"恢复较难，因为没有全局粗位姿。MDCS 推荐 ''二维码辅助''方案：在关键位置贴二维码作为 ''重定位锚点''。具体见 [[Special:MyLanguage/使用手册 - 在地纹导航中使用二维码快速找回定位|使用手册 - 在地纹导航中使用二维码快速找回定位]]。

In ground-texture mode, recovery is hard. The recommended pattern is QR-assisted re-localisation: paste QR tags at strategic points as anchors. See the dedicated guide.

== 相关页面 / See also ==
* [[Special:MyLanguage/地纹SLAM技术概述|地纹SLAM技术概述]]
* [[Special:MyLanguage/使用手册 - 如何在核显工控机上运行地纹导航|使用手册 - 如何在核显工控机上运行地纹导航]]
* [[Special:MyLanguage/使用手册 - 在地纹导航中使用二维码快速找回定位|地纹导航中使用二维码快速找回定位]]
* [[Special:MyLanguage/Detour软件架构|Detour软件架构]]
* [[Special:MyLanguage/多定位源的自动综合|多定位源的自动综合]]

[[Category:技术报告]]

CycleGUI

2026-05-16T11:42:49Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
CycleGUI 是 MDCS 自研的 ''回合式 GUI 框架''：算法代码可以在任何线程、任何时间 ''cast'' 一个协程到 GUI 主线程；协程仅在 ''需要刷新界面''时被唤醒。这种"按需协程"模型让算法核心可以无负担地嵌入实时调试与可视化代码。

CycleGUI is MDCS's homegrown '''cyclic-coroutine GUI framework'''. Algorithm code on any thread can ''cast'' a coroutine onto the GUI thread; the coroutine wakes only when its visuals need refreshing. The "lazy coroutine" model lets the algorithm core embed live-debug code without performance cost.

== 设计动机 / Why ==
* 机器人算法（SLAM、规划、运动控制）需要 ''频繁、灵活''地可视化中间状态。
* 传统 GUI 框架要求把算法搬到 GUI 主线程或用观察者模式回调 —— 都侵入性强。
* CycleGUI 反转控制：算法在原线程跑，GUI 框架托管协程，只在 GUI 需要重绘时调用协程。
* 让 ''调试代码''与 ''算法代码''几乎无成本共存。

* Robotics algorithms (SLAM, planning, motion) need to visualise intermediate state often and flexibly.
* Conventional GUI frameworks force the algorithm onto the UI thread or use observer callbacks — both invasive.
* CycleGUI inverts control: the algorithm stays on its thread; the GUI framework hosts the coroutine and pulls it only on repaint.
* Debug code and algorithm code coexist with near-zero cost.

== 使用模型 / Usage model ==

算法代码 (任意线程)
│
▼
UI.GetPainter("topic1")
│
▼
painter.DrawDot3D(color, position); ← 任意时刻调用
painter.DrawLine3D(...);
│
▼
CycleGUI 主线程（按需）
│
▼
渲染到屏幕

详见 [[Special:MyLanguage/如何使用CycleGUI快速开发UI界面|如何使用CycleGUI快速开发UI界面]] 的具体 API。
For specific APIs see [[Special:MyLanguage/如何使用CycleGUI快速开发UI界面|the usage guide]].

== 核心抽象 / Core abstractions ==
* '''Painter''' — 一个命名的绘制目标（topic）；多次 `DrawXxx` 累积到同一画面。
* '''Layer''' — 多个 Painter 组合成一层；可控可见性。
* '''Cyclic coroutine''' — 一段被框架托管的 `IEnumerable<Cycle>`，每次 ''帧重绘''被执行一次。
* '''Two-way binding''' — UI 控件（按钮、滑条、输入框）通过协程的 `yield return WaitForXxx` 与算法同步。

== 在 MDCS 中的应用 / Use within MDCS ==
* '''Detour''': 可视化 SLAM 中间状态（关键帧、闭环候选、协方差椭圆）。
* '''Clumsy''': 在 Movement 内部可视化 lidar 帧、检测器输出、目标姿态。
* '''SimpleComposer''': CAD 工具 + 调度时的车流可视化。
* '''仿真 / 回放''': 把回放数据投射到同一套 CycleGUI 视图。

== 实现位置 / Where ==
源码：`D:\src\CycleGUI\`（独立仓库）。MDCS 通过 NuGet 引用。
Source: `D:\src\CycleGUI\` (standalone repo); MDCS depends via NuGet.

== 关键特性 / Key features ==
* '''零侵入''': 不强制让算法上 GUI 线程。
* '''跨进程''': 一个 GUI 可以同时呈现多个进程的画面。
* '''可录制''': 所有 Painter 调用可序列化 → 离线回放。
* '''Web 版'''（实验）: 把绘制指令转 WebGL，浏览器查看。

* Zero-intrusion — algorithm doesn't migrate to the UI thread.
* Cross-process — one GUI can render from multiple processes.
* Recordable — all Painter calls serialise; replay off-line.
* Web flavour (experimental) — render commands → WebGL, view in browser.

== 与其它框架的对比 / Comparison ==
{| class="wikitable"
! 项 / Item !! CycleGUI !! ImGui !! Qt
|-
| 协程模型 / Coroutine || 是（按需唤醒）/ Yes (lazy) || 否（每帧重画）|| 否（事件驱动）
|-
| 跨进程 / Cross-process || 内建 || 需 RPC || 复杂
|-
| GUI 主线程要求 / UI-thread req || 无（cast 自动派发）|| 有 || 有
|-
| 学习曲线 / Curve || 中 || 低 || 高
|}

== 相关页面 / See also ==
* [[Special:MyLanguage/如何使用CycleGUI快速开发UI界面|如何使用CycleGUI快速开发UI界面]]
* [[Special:MyLanguage/开发手册 - SimpleComposer界面开发 - CAD工具|开发手册 - SimpleComposer界面开发 - CAD工具]]
* [[Special:MyLanguage/LessokajiWeaver编译后处理工具|LessokajiWeaver编译后处理工具]]

[[Category:二次开发相关说明]]

车体抽象原理

2026-05-16T11:26:59Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
MDCS 把"一台 AGV"抽象为三个层次的协作：'''Medulla'''（硬件层 / IO 平台），'''Clumsy'''（车体行为层 / 自动驾驶），'''Simple'''（车队层 / 调度与交管）。每层各自定义"车"的一个侧面，通过明确的数据契约串联。理解这套分层是开发 MDCS 插件、写适配代码与调试问题的前提。

MDCS abstracts "an AGV" through three cooperating layers: '''Medulla''' (hardware / IO), '''Clumsy''' (vehicle behaviour / autopilot), '''Simple''' (fleet / scheduling). Each layer defines one facet of the vehicle and they connect through well-defined data contracts. Understanding this stack is foundational for any plugin / adaptation work.

== 三层结构 / Three-layer view ==

┌─────────────────────────────────────────────────────────────┐
│ Simple (Fleet plane) │
│ • SimpleComposer.RCS.Car / ClumsyCar / 自评估车 subclass │
│ • SimpleCore — DPS 交管 / 寻路 / 包络 / 可达性 │
│ • TopazScript 任务脚本 │
└────────────────┬────────────────────────────────────────────┘
│ 任务 / TopazScript / mission script
│ 上报 / Status (x,y,th,siteId,batt,...)
┌────────────────▼────────────────────────────────────────────┐
│ Clumsy (Vehicle behaviour plane) │
│ • SimpleAgvInterface.Queue(...) │
│ • MovementDefinition: SteeringLineFollowing, │
│ AutoFetchGood, AutoShelfFetching, ... │
│ • DriveTask.WaitDriveTask(IEnumerable<bool>) │
│ • PilotDefinition<T> 自动驾驶宿主 │
└────────────────┬────────────────────────────────────────────┘
│ UpperIO 意图（vCmd, steerCmd, forkTgt, ...）
│ LowerIO 反馈（vEst, sensors, e-stop, ...）
┌────────────────▼────────────────────────────────────────────┐
│ Medulla (Hardware plane) │
│ • CartDefinition + [AsUpperIO]/[AsLowerIO]/[AsInitParam] │
│ • LadderLogic 周期性控制循环 (~50 ms) │
│ • IOObject 体系（Lidar, Camera, Cart 都是） │
│ • DObject 跨进程共享内存 │
└─────────────────────────────────────────────────────────────┘

== 各层的责任 / Layer responsibilities ==
=== Medulla — 硬件层 / Hardware plane ===
- 抽象具体硬件（CAN / Modbus / S7 / RS485 / USB）成 ''IO 字段''。
- 同步把上位指令写到硬件，把硬件状态读到字段。
- 不做"决策"，不知道"任务"。
- 关键文件：`D:\src\M2\OfficialPlugins\CartActivator\CartDefinition.cs`、`Attrs.cs`。
- 关键属性：`[AsUpperIO]`（命令向下流）、`[AsLowerIO]`（状态向上流）、`[AsInitParam]`（启动配置）、`[UseLadderLogic]`（周期循环）。

- Abstracts hardware (CAN / Modbus / S7 / RS485 / USB) into ''IO fields''.
- Writes commands down, reads state up, on a fixed tick.
- Makes no "decisions" and is unaware of tasks.
- Source: `D:\src\M2\OfficialPlugins\CartActivator\CartDefinition.cs` / `Attrs.cs`.

=== Clumsy — 车体行为层 / Vehicle behaviour plane ===
- 把"动作"（直行、原地转、自动取货、绕障）封装为 `MovementDefinition` 子类。
- 把 Movement 组合成"业务动作"如 `Fetch / Put / ExitSite`，挂在 `SimpleAgvInterface` 上。
- 不知道车队全局，只看到本车的位置、速度、IO。
- 任务通过 `SimpleAgvInterface.Queue(...)` 流水线执行。
- 关键文件：`D:\src\Clumsy\ClumsyCore\Pilot\MovementDefinition.cs:41`、`D:\src\Clumsy\ClumsyCore\Pilot\PilotDefinition.cs:91-122`、`D:\src\Clumsy\ClumsyCore\Interfaces\SimpleAgvInterface.cs`。

- Packages a motion primitive as a `MovementDefinition` subclass with `IEnumerable<bool> Get()` ticked at `DriveTaskInterval` ms.
- Composes business actions (`Fetch / Put / ExitSite`) on top of `SimpleAgvInterface`.
- Sees only this vehicle's state.

=== Simple — 车队层 / Fleet plane ===
- SimpleCore 提供调度内核：[[Special:MyLanguage/DPS调度算法详解|DPS]] 交管、寻路、包络、可达性、[[Special:MyLanguage/流场规划|流场]]。
- SimpleComposer 提供 UI 壳与车型 / 业务插件接口。
- 给单车下发的是 TopazScript（高层意图脚本），由 ClumsyCar 转给车载 Clumsy，或由自评估车在本地翻译为 RFID / Modbus。
- 关键文件：`D:\src\Simple\SimpleComposer\RCS\Car.cs:33` / `ClumsyCar.cs:34`、`D:\src\Simple\SimpleCore\PropType\AbstractCar.cs:346`、`BasicProps\AGVInterface.cs`。

- SimpleCore: scheduling kernel (DPS traffic, pathfinding, envelopes, reachability, flow-field).
- SimpleComposer: UI shell + plugin host for car types and business scripts.
- Dispatches TopazScript mission scripts; ClumsyCar HTTP-posts to the on-board Clumsy adapter, while self-evaluating cars run `SelfEvaluating(agv, script)` locally and translate to vendor commands.

== 上下位 IO 数据流 / Upper / Lower IO data flow ==
=== UpperIO（命令下行）/ Upper IO (commands going down) ===
'''上位''' = 调度 / Clumsy → 车体。典型上位字段：

* `vCmd`, `steerCmd` — 速度 / 转向
* `forkHeightTgt`, `forkTiltTgt` — 叉齿
* `brakeOn`, `hornOn`, `ledColor`
* `jackTarget` — 顶升机构

=== LowerIO（状态上行）/ Lower IO (status going up) ===
'''下位''' = 车体 → Clumsy / 调度。典型下位字段：

* `vEst`, `steerEst` — 实测速度 / 转向
* `forkHeight`, `forkAtTarget`
* `batteryPercent`, `eStop`, `loadKg`
* 各类传感器（接近开关、负载、温度等）

=== 为什么要分上下位 / Why split upper vs lower ===
MDCS 强制 ''命令 / 状态''解耦，使得：
* Clumsy 可以在上位写完命令后 ''立即向上汇报已下发''，不必等硬件确认；
* Medulla 的硬件层故障（如 PLC 通讯断）不会污染上层任务状态；
* 测试时可把整车换成模拟器，只要 IO 字段一致，上层代码无感知。

The split enforces command/state decoupling: Clumsy reports "issued" immediately without waiting for hardware ack; Medulla failures don't poison higher-layer mission state; in simulation a vehicle can be swapped for a simulator as long as the IO fields match — the upper stack is unaware.

== 任务下发完整链路 / Full mission-dispatch path ==

# SimpleComposer 把业务任务 ''编译''为 TopazScript（路径分段 + 可执行动作）。 SimpleComposer compiles a business job into TopazScript (path segments + executable actions).
# `Car.actualSendScript(script)` 被调度调用。 The scheduler calls `Car.actualSendScript(script)`.
# '''ClumsyCar 分支''': HTTP POST 到车载 Clumsy；车载 `SelfEvaluating(agv, script)` 解释脚本 → 调 `AGV.Fetch / Put / Go` → `Queue(...)` → `Movement.Get()` → `DriveTask` → Medulla UpperIO。 ''ClumsyCar branch'': HTTP-POST to the on-board adapter; on-board `SelfEvaluating` interprets the script, calls AGV methods, queues Movements, drives Medulla IO.
# '''自评估车分支''': 调度本地运行 `SelfEvaluating(agv, script)`；nested `AGV : AGVInterface` 把 `agv.Go(...)` 翻译为 RFID / Modbus 命令发给车体 PLC。 ''Self-eval branch'': scheduler runs `SelfEvaluating` locally; the nested `AGV : AGVInterface` translates calls to vendor commands.
# 任意时刻车体心跳上报 `(x, y, th, siteId, ...)`；调度据此更新地图、推进任务。 Heartbeat from the vehicle continuously reports pose + state; the scheduler updates and advances.

== 实施建议 / Practical guidance ==
* '''先 Medulla''': 没硬件，上层一切免谈。先让 IO 表跑通（手动 set `vCmd=200` 看车动）。
* '''再 Clumsy''': IO 跑通后写 1 个 `SimpleAgvInterface` 子类、跑直线巡线。
* '''最后 Simple''': Clumsy 单车可控之后接入 SimpleComposer，做调度。
* '''测试每层''': Medulla 可以独立测；Clumsy 可以用 IO 模拟器（脚本里直接 set / get 字段）；SimpleCore 有单机调度仿真。

* Order: Medulla → Clumsy → Simple. Don't write Simple-side code if Medulla isn't proven yet.
* Test each layer in isolation: Medulla via manual IO sets, Clumsy with an IO simulator, SimpleCore in standalone simulation.

== 相关页面 / See also ==
* [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]
* [[Special:MyLanguage/Medulla|Medulla]] / [[Special:MyLanguage/Medulla-API|Medulla-API]]
* [[Special:MyLanguage/Clumsy-API|Clumsy-API]]
* [[Special:MyLanguage/Simple-API|Simple-API]]
* [[Special:MyLanguage/DObject|DObject]]
* [[Special:MyLanguage/AGV任务运行逻辑|AGV任务运行逻辑]]
* [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|如何基于SimpleCore核心库进行调度系统开发]]

[[Category:通识和入门教学]]
[[Category:开发手册]]

色带和磁条导航

2026-05-16T11:26:57Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
色带和磁条导航是工业 AGV 最经典、最低成本的导航方式：在地面铺设一条 ''视觉色带''或 ''磁条''，车上装传感器实时测量与色带 / 磁条中线的横向偏差，反馈到转向回路实现自动巡线。MDCS 把这类车视为 [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|自评估车]]：车体自行处理巡线，调度只下发"去哪个站点"的高层意图。

Tape and magnetic-strip navigation is the most classic, lowest-cost industrial AGV navigation: lay coloured tape (vision) or a magnetic strip on the floor; the AGV uses a sensor to measure lateral offset from the strip and steers to keep it centred. MDCS treats these as [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|self-evaluating vehicles]]: the cart does its own line-following, the fleet just dispatches "go to site X" intents.

== 适用 / Use cases ==
* 低成本固定路径（仓储入库、装配线物料补给）
* 强干扰环境（金属反射多、纹理少，激光 SLAM 表现差）
* 老线改造（已有色带 / 磁条线路，复用基础设施）
* 安全要求极高、需要 ''物理路径''可视可控的场景

* Low-cost fixed routes (binning, assembly-line restock).
* Environments hostile to laser SLAM (heavy metal reflection, no texture).
* Brown-field upgrades where tape / magnet routes already exist.
* Safety-critical use cases that demand a physically visible / controllable path.

== 系统组成 / System composition ==
{| class="wikitable"
! 部件 / Part !! 色带导航 / Tape !! 磁条导航 / Magnetic strip
|-
| 路径基础设施 / Path media || 反光色带、贴在地面 / reflective coloured tape on the floor || 磁条，1–3 mm 厚，可埋入地面或贴面 / magnetic strip 1–3 mm thick
|-
| 车上传感器 / On-board sensor || 线扫相机或多点光电 / line camera or photo-array || 磁导航传感器（霍尔阵列）/ Hall-array
|-
| 站点标记 / Site marker || 二维码 / 反光异型 / RFID tag near the tape || RFID 标签（最常见）/ RFID tag
|-
| 控制器 / Controller || 厂商 PLC / MCU || 厂商 PLC / MCU
|-
| 通讯 / Comm to fleet || Wi-Fi + RFID 站点回报 || Wi-Fi + RFID 站点回报
|-
| 路径修改 / Route change || 重铺色带 || 重铺磁条
|}

色带导航的优点：易铺设、易看见、可临时改路径；缺点：易污损。 
磁条优点：耐用，污垢不影响；缺点：金属物体附近误读，改线难。

== MDCS 适配 / MDCS adaptation ==
'''要点''': 这类车在 SimpleCore / SimpleComposer 中是 ''自评估车''（不跑 MDCS 车载），调度的工作止于"高层意图 + 站点回报"。

The vehicle is a '''self-evaluating car''' from MDCS's point of view: no on-board Clumsy, no Medulla. The scheduler's job is to send intent and observe site reports.

最小集成：
Minimal integration:

# 在 SimpleComposer 中声明一个 `Car` 子类（不是 ClumsyCar），含 nested `AGV : AGVInterface`。
# `AGV.Go(srcId, dstId)` 把 ''站点意图''翻译为 ''RFID 命令帧''（或 Modbus 寄存器写入），通过 Wi-Fi 发送到车上 PLC。
# 车上 PLC 用 RFID 读到的站点 ID 自决定 ''下一步''（前进 / 等待 / 转向 / 停止），并把 RFID + 状态周期上报。
# 在 `Car.keepAlive()` 中解析回报，更新 `(x, y, th, siteId, batt, error)`。
# 站点上锁仍由 SimpleCore 的 `TryLock / Leave` 控制，但 ''是否真的进入''取决于车体识别到 RFID 标签。

模板代码（重要细节见 `D:\src\cookbook\adaption-reference\苏州凌鸟\Scenes\AMRScene1\Cars\MNavCar.cs` 293 行）：

<syntaxhighlight lang="csharp">
[CarType(Name = "TapeAGV", Title = "色带 / 磁条 AGV / Tape or magstrip AGV")]
public class TapeAGV : Car
{
public string plcIp;
public int rfidLastSeen;
public DateTime lastHeartbeat = DateTime.Now;

public class AGV : AGVInterface
{
private readonly TapeAGV car;
public AGV(TapeAGV c) { car = c; }

public void Go(double sx, double sy, int srcId,
double dx, double dy, int dstId, int routeId)
{
Queue(
async () => { TryLock(srcId, routeId); },
async () =>
{
// 把"去往 dstId"翻译为 RFID 帧
await car.SendRfidGoCommand(dstId);
// 等车真的到了
while (car.rfidLastSeen != dstId) await Task.Delay(100);
},
async () => { Leave(srcId); });
}
}

public override async Task keepAlive()
{
var status = await ReadPLC(plcIp);
// 把 PLC 状态映射到 Car
UpdatePose(status.X, status.Y, status.Heading);
rfidLastSeen = status.LastRfid;
lastHeartbeat = DateTime.Now;
}
}
</syntaxhighlight>

== 站点定位 / Site localisation ==
色带 / 磁条本身只能告诉车 ''横向偏差''，不能告诉车 ''我在路径上哪一段''。所以这类车必须沿路径布 ''RFID 标签''作为站点：
* 每个分叉前后必有 RFID。
* 长直线段每 5–10 m 一个 RFID 用于精确位姿恢复。
* 终点 / 工位前 RFID 触发停车 / 入位逻辑。

Tape / strip only gives ''lateral offset''. RFID tags along the path provide ''which site I'm at'' — one before/after each branch, one every 5–10 m on long straight, one at each terminal / work position.

== 与 MDCS 其它定位的混用 / Hybrid with other localisation ==
有些项目把色带 / 磁条导航 ''作为 SLAM 失败时的 fallback''：平时跑 [[Special:MyLanguage/激光SLAM建图|激光 SLAM]]，在已知劣化区段（如户外、强光、临时遮挡）切到磁条 fallback。技术上可行，但工程实现复杂（两套传感器、两套控制律、切换瞬间的姿态一致性）；除非现场要求否则不推荐。

Some projects use tape / magstrip as a SLAM ''fallback'' on known-degraded segments. Technically feasible, engineering-complex (two sensors, two controllers, transition continuity). Avoid unless the deployment really demands it.

== 调试与维护 / Debug & maintenance ==
* '''色带磨损''' / Tape wear: 每 3–6 个月巡线一次，发现 ≥ 5 cm 连续缺失立即重贴。
* '''磁条覆盖物''' / Magstrip cover: 磁条要避免被金属覆盖（货叉车叉齿掉落 / 临时金属板）。
* '''RFID 标签丢失''' / RFID loss: 每天上电后做一次 ''全路径轮询''；任何标签失效立即报警。
* '''传感器外参''' / Sensor extrinsics: 磁导航传感器中心要对齐车体中线 ±5 mm；偏太多巡线会偏。

== 失败模式 / Failure modes ==
* '''丢线''' / Loss of tape: 车体应停 + 灯闪 + 报告 SimpleComposer。
* '''RFID 漏读''' / RFID miss: 心跳里包含 ''last_rfid + age''；调度可据此判断车是否仍在路径。
* '''重定位''' / Re-localise: 没有重定位概念 —— 失线后只能人工把车搬到任一 RFID 上。

== 相关页面 / See also ==
* [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|如何基于SimpleCore核心库进行调度系统开发]]
* [[Special:MyLanguage/纯二维码导航|纯二维码导航]] — 类似思路，地标改为二维码
* [[Special:MyLanguage/巡线行走|巡线行走]] — MDCS Clumsy 巡线（基于位姿，不依赖物理标记）

[[Category:定位导航相关手册]]

绕障行走

2026-05-16T11:26:53Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
"绕障行走"指 AGV 在 [[Special:MyLanguage/巡线行走|巡线行走]] 的基础上叠加 ''局部障碍感知与降速 / 短距偏避''能力。MDCS 中的绕障 ''不是动态重规划''（那是调度层 SimpleCore 的工作），而是 ''线段内的安全反应''：当前向激光检测到障碍时，先减速到停，必要时小幅横向避让；如果障碍持续存在 > 阈值时间，调度会接管做全局重路径。

"Obstacle-aware line following" adds ''local obstacle perception with deceleration and small lateral avoidance'' on top of [[Special:MyLanguage/巡线行走|line following]]. MDCS does '''not''' do dynamic global re-planning here — that's SimpleCore's job. The Movement-level logic is ''in-segment safety reaction'': decelerate-to-stop on a detected obstacle, optionally small lateral nudge; if the obstacle persists beyond a threshold, the scheduler takes over with a full reroute.

== 与全局重规划的分工 / Division with global replanning ==
{| class="wikitable"
! 层 / Layer !! 触发 / Trigger !! 反应 / Reaction
|-
| Clumsy Movement (本页) || 前向激光 ROI 内有点 / Front lidar ROI has points || 减速 / 停车 / 小幅横向避让
|-
| SimpleCore 调度 || 障碍持续 > T_obstacle_stale (默认 8 s) || 重新规划该车的路径段
|-
| 全局地图重建 || 障碍很久不消失（> T_map_invalid） || 标记地图段为永久不可达
|}

The split is deliberate: Movement-level responses must be ≤ tens of milliseconds; scheduler-level replanning is hundreds of milliseconds and global. They cooperate via the per-segment "stuck" flag.

== 关键参数 / Key parameters ==
绕障字段附加在 `SteeringLineFollowing` 之上（或它的"绕障变体"`SteeringLineFollowingWithAvoid`）：

These fields are layered on top of `SteeringLineFollowing` (or its avoidance-aware sibling `SteeringLineFollowingWithAvoid`):

{| class="wikitable"
! 字段 / Field !! 默认 / Default !! 含义 / Meaning
|-
| `obstacleROIStart` / `obstacleROIEnd` || 视场前向 ±15° || 障碍检测的角度区间 / FOV slice for obstacle detection
|-
| `obstacleROILength` || 1500 mm || 检测距离上限 / max distance considered
|-
| `obstacleSlowDist` || 1500 mm || 进入此距离开始降速 / start decelerating
|-
| `obstacleStopDist` || 400 mm || 在此距离停车 / hard stop
|-
| `obstacleMinPoints` || 4 || 多少个点视为"真障碍"（去抗 ghost）
|-
| `lateralAvoid` || `false` || 是否允许小幅横向偏避（仅全向车 / 双阿克曼蟹行可用）
|-
| `lateralAvoidMax` || 250 mm || 横向最大偏移 / max lateral nudge
|-
| `stuckTimeoutMs` || 8000 || 持续受阻多久后向调度告警 / report-stuck timeout
|}

== 工作机制 / How it works ==
1. 每个 tick 读最新激光点云 `cachedLidar`（参见 [[Special:MyLanguage/2D激光雷达适配|2D 激光适配]]）。
2. 用 ROI 过滤：只关心角度在 `[obstacleROIStart, obstacleROIEnd]`、距离在 `[0, obstacleROILength]` 的点。
3. 统计 ROI 内点数 ≥ `obstacleMinPoints` 时认定"有障碍"，记录 ''最近距离'' d_obs。
4. 计算速度上限：
- d_obs ≥ obstacleSlowDist → basespeed
- obstacleStopDist < d_obs < obstacleSlowDist → 线性插值降速
- d_obs ≤ obstacleStopDist → 0（停车）
5. 如果 `lateralAvoid = true` 且持续受阻 > 500 ms，启用 ''小幅横向偏避''：把虚拟前瞻点向无障碍一侧偏 `lateralAvoidMax`，重新做纯跟踪。
6. 如果连续受阻 > `stuckTimeoutMs`，把 ''segment stuck'' 标志置 true → SimpleCore 调度立即重新寻路。

1. Each tick read `cachedLidar` from the front lidar.
2. ROI filter on the angle/distance slice.
3. Points ≥ `obstacleMinPoints` → mark obstacle, record nearest distance d_obs.
4. Speed cap: linear ramp between `obstacleStopDist` (0) and `obstacleSlowDist` (basespeed).
5. If `lateralAvoid` is on, after 500 ms of blockage shift the look-ahead point sideways.
6. After `stuckTimeoutMs` continuous blockage, flag the segment as stuck → scheduler replans.

== 调用样例 / Example ==
<syntaxhighlight lang="csharp">
public void DriveAvoiding(double sx, double sy, double dx, double dy)
{
Queue(async () =>
{
DriveTask.WaitDriveTask(new SteeringLineFollowingWithAvoid
{
srcX = sx, srcY = sy, dstX = dx, dstY = dy,
basespeed = 800,

obstacleSlowDist = 1500,
obstacleStopDist = 400,
obstacleMinPoints = 4,
lateralAvoid = false, // 普通阿克曼车关闭
stuckTimeoutMs = 8000
}.Follow());
});
}
</syntaxhighlight>

== 调试要点 / Tuning ==
* '''误触发停车''' / False positives → 增大 `obstacleMinPoints`（地面反射或飞虫的少量点会被忽略）。
* '''反应迟钝''' / Slow to react → 减小 `obstacleSlowDist` 接近 `obstacleStopDist`，但太接近会跌停（无平滑减速）。
* '''横向避让撞两侧''' / Lateral nudge into walls → 减小 `lateralAvoidMax`；或在调度可达性中声明 ''两侧不可避''。
* '''反复 stuck / replan 抖动''' / Flap between stuck / unstuck → 增大 `stuckTimeoutMs`，避免短暂遮挡引发重路径。

== 全向车与蟹行避让 / Omni & crab avoidance ==
全向车与双阿克曼车型可以 ''真'' 横向避让（不改变车头朝向就能侧移）。对应 Movement 是 `OmniLineFollowingWithAvoid` 与 `CrabLineFollowingWithAvoid`，它们的 `lateralAvoidMax` 可以放宽到 600 mm。

Omni and double-Ackermann vehicles can truly translate laterally without yawing. Use `OmniLineFollowingWithAvoid` / `CrabLineFollowingWithAvoid`; `lateralAvoidMax` can be opened up to 600 mm safely.

== 安全 / Safety ==
绕障 Movement '''不是安全 e-stop''' —— 它的反应时间是 50 ms 量级（Movement tick），而安全 e-stop 必须 < 10 ms 并 ''独立于 Movement 逻辑''。`obstacleStopDist` 之外还必须有：

The Movement is '''not''' a safety e-stop — its reaction is at the ~50 ms tick. Always provide:

* 激光雷达紧急停止区（< 300 mm 内任何点）—— 接到 Medulla 上位 `eStop` 信号上。
* 物理安全条 / 急停按钮。
* SIL-2 / PL-d 的功能安全设备（重载场景）。

== 相关页面 / See also ==
* [[Special:MyLanguage/巡线行走|巡线行走]]
* [[Special:MyLanguage/车体抽象原理|车体抽象原理]]
* [[Special:MyLanguage/可达性状态编程|可达性状态编程]]
* [[Special:MyLanguage/使用手册 - 寻路启发器功能|寻路启发器功能]] — 调度侧重规划

[[Category:运动控制使用手册]]

牵引车适配案例

2026-05-16T11:26:53Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
牵引车（也称双阿克曼车型、tow-truck、tractor）的关键特征是 ''有非完整约束''（不能瞬时横移），加上 ''后挂多节拖车''时存在 ''逆向跟踪难''与 ''折叠/失稳'' 风险。MDCS 通过专用 Movement 与额外的拖车包络处理这些问题。

The tractor / double-Ackermann (tow-truck) vehicle has '''non-holonomic constraints''' (can't translate laterally) and, when towing trailers, the difficulties of reverse-tracking, jackknife avoidance, and trailer swing. MDCS handles these via dedicated Movements and trailer envelopes.

参考：浙江中力 (`D:\src\cookbook\adaption-reference\浙江中力\`) 等拖车 / 牵引适配案例。
References: Zhejiang Zhongli (`adaption-reference\浙江中力\`) and similar.

== 车型变体 / Variants ==
{| class="wikitable"
! 子型 / Sub-type !! 说明 / Description
|-
| 单阿克曼 / Single-Ackermann || 前轮转向，后轮驱动，无拖车 / Front-steer, rear-drive, no trailer
|-
| 双阿克曼 / Double-Ackermann || 前后都可转向（蟹行）/ Both axles steer (can crab-walk)
|-
| 牵引 + 1 挂 / Tractor + 1 trailer || 单个铰接点 / single hitch
|-
| 牵引 + N 挂 / Tractor + N trailers || 多铰接，每节带额外的运动学约束
|-
| 双向牵引 / Bidirectional tractor || 前后都能作为牵引头 / can lead from either end
|}

== 1. Medulla 适配 / Medulla side ==
关键 IO（以双阿克曼为例）：

<syntaxhighlight lang="csharp">
public class TowCart : CartDefinition
{
[AsInitParam] public string canIface = "can0";
[AsInitParam] public float wheelBase = 1450; // mm
[AsInitParam] public float trackFront = 1100;
[AsInitParam] public float trackRear = 1100;
[AsInitParam] public bool doubleAckermann = true;

[AsUpperIO] public float vCmd;
[AsUpperIO] public float steerFrontCmd; // 前轮转角 / rad
[AsUpperIO] public float steerRearCmd; // 后轮转角 / rad (sign for crab vs co-turn)
[AsUpperIO] public bool brakeOn;
[AsUpperIO] public bool hitchEngaged; // 挂钩控制 / hitch control

[AsLowerIO] public float vEst;
[AsLowerIO] public float steerFrontEst, steerRearEst;
[AsLowerIO] public float hitchAngle1, hitchAngle2, hitchAngle3; // 每节拖车的折角
[AsLowerIO] public bool hitchOK;
[AsLowerIO] public bool eStop;
}
</syntaxhighlight>

铰接角 / Hitch angles：每节拖车与前一节的相对角度，是逆向跟踪与失稳预警的关键状态。`hitchAngleN` 用 IMU 双轴或单点编码器测。

The hitch angle of each trailer relative to the one in front is the key state for reverse-tracking and jackknife warning. Measure via dual-axis IMUs or a hitch encoder.

== 2. Clumsy 自动驾驶适配 / Clumsy side ==
=== 关键 Movement ===
{| class="wikitable"
! Movement !! 用途 / Use
|-
| `SteeringLineFollowing` || 正向行驶（单 / 双阿克曼通用）/ forward driving
|-
| `SteeringLineFollowingReverse` || 逆向行驶（带 trailer）/ reverse with trailer
|-
| `CrabLineFollowing` || 蟹行（仅双阿克曼）/ crab walk (double-Ackermann only)
|-
| `TractorTurnAround` || 调头动作（多段曲线）/ multi-segment U-turn
|-
| `JackknifeGuard` || 守护线程：检测 hitch 角度过大时刹停 / guard thread for excessive hitch angle
|}

=== 逆向跟踪（reverse-track with trailer）===
带 N 节拖车做逆向跟踪时，运动学是 ''非线性、不稳定''。MDCS 采用：

Reverse-tracking with N trailers is nonlinear and unstable. MDCS uses:

# 在路径规划时 ''禁止''带挂逆向超过 5 m。
# 仅允许在专用的 ''逆向缓冲区''做带挂倒车，且车速 ≤ 100 mm/s。
# 控制器：以 ''最后一节拖车''的姿态为状态，通过非线性逆向控制律解算前轴转角。
# 任何 hitch 角度 ≥ 30° 立即停车 + 报警。

# Path planning forbids reverse-with-trailer > 5 m.
# Reverse-with-trailer only permitted in dedicated reverse buffer zones at ≤ 100 mm/s.
# Controller takes the rear-most trailer pose as the state and inverts to front-axle angle.
# Any hitch angle ≥ 30° → e-stop + alarm.

=== 调头 / U-turn ===
不带挂的牵引车 ''必须用最小转弯半径以内的曲线段拼接''来调头，常见 K-turn 或 U-turn。MDCS 的 `TractorTurnAround` Movement 包含一个解析的多段 Dubin's 路径生成器，已考虑 wheelBase + minTurnRadius。

A tractor without a trailer needs a multi-segment path within its minimum turning radius. The `TractorTurnAround` Movement uses an analytic Dubin's path generator parameterised by wheelBase and minTurnRadius.

== 3. SimpleComposer 端 / SimpleComposer side ==
=== 拖车包络 / Trailer envelope ===
牵引 + N 挂的包络必须由 ''拖车折角''计算 —— 直行时是简单的长矩形，弯路时各节会摆向不同方向，整体包络变成 ''扇形''。

The envelope of a tractor + N trailers is shaped by '''hitch angles'''. Straight-line travel gives a long rectangle; turning causes each segment to swing differently, producing a fan-shaped envelope. SimpleComposer dynamically recomputes this from hitch-angle readings.

=== 调度约束 / Scheduling constraints ===
* ''最小转弯半径''声明在车型属性中，调度寻路时排除半径过小的弯。
* ''带挂''与 ''不带挂''是两种不同的可达性状态（[[Special:MyLanguage/可达性状态编程|可达性状态编程]]）。
* 拖车数量影响交管锁；多挂车一次锁连续多个站点。

* Minimum turn radius declared in car props; pathfinder excludes tighter turns.
* Towing vs not-towing are two reachability states.
* Multi-trailer cars take multi-site locks at once.

== 4. 标定与调试 / Calibration & tuning ==
# '''前轮 / 后轮转角极性''' / Steer polarity: 单独测各轴的左 / 右极性，确认与 IMU 一致。
# '''单阿克曼直线度''' / Single-Ackermann straight: 直行 10 m 后侧向偏差 < 30 mm。
# '''双阿克曼蟹行''' / Crab walk: 命令 30° 蟹行 5 m，实际方向偏差 < 1°。
# '''拖车铰接角度''' / Hitch zero: 静态直拖时 hitchAngle 应 = 0；偏 > 1° 必须重做 IMU 零点。
# '''极限工况''' / Boundary: 满载 + 满拖 + 最小半径转弯，确认无失稳。

# Steer polarity per axle; confirm IMU sign agreement.
# Single-Ack straight-line: < 30 mm drift over 10 m.
# Double-Ack crab-walk: 30° crab × 5 m → heading drift < 1°.
# Hitch zero: static straight tow → hitchAngle = 0 ± 1°.
# Boundary: fully-loaded, full trailer train, min-radius turn → no jackknife.

== 5. 常见问题 / Common pitfalls ==
* '''逆向失控''' / Reverse instability: 拖车超 2 节时控制律不收敛；改成 ''分段倒车''（每次只倒 0.5 m 复位）。
* '''弯道挂车摆动''' / Trailer swing on curves: 把 `basespeed` 在弯道前先降到 50%，并加大 ''弯道前提早转向''时间。
* '''hitch 编码器漂''' / Hitch encoder drift: 检查机械连接 + IMU 零点；每天上电后做一次自检。
* '''带挂掉头空间不足''' / Insufficient room for U-turn: 调度寻路前必须知道拖车节数，否则 `TractorTurnAround` 会规划出穿墙路径。

== 6. 双向牵引 / Bidirectional tractor ==
双向牵引车前后都可拖挂；切换"主拉端"时，Detour 的车体坐标需要同步 ''翻转 180°''，并切换前向 / 后向激光雷达为 SLAM 主源。

A bidirectional tractor can pull from either end. When swapping the "lead end", flip the vehicle frame 180° in Detour and switch the primary SLAM lidar from front to rear.

== 相关页面 / See also ==
* [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]
* [[Special:MyLanguage/叉车适配案例|叉车适配案例]]
* [[Special:MyLanguage/全向车适配案例|全向车适配案例]]
* [[Special:MyLanguage/潜伏顶升车(KIVA类小车)适配案例|潜伏顶升车(KIVA类小车)适配案例]]
* [[Special:MyLanguage/可达性状态编程|可达性状态编程]]
* [[Special:MyLanguage/使用手册 - Simple:包络如何定义|Simple:包络如何定义]]

[[Category:开发手册]]

潜伏顶升车(KIVA类小车)适配案例

2026-05-16T11:26:51Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
潜伏顶升车（也称 KIVA 类小车、料架搬运车）是从料架下方钻入、顶升后整体搬运料架到目的地的低矮 AGV。结构最简，但对 ''Detour 定位精度''与 ''[[Special:MyLanguage/使用自动对准料架功能|自动对准料架]]'' 算法要求最高。

The lift-AGV (also "KIVA-class" after Amazon's KIVA) is a low-profile AGV that slides under a rack, jacks it up, and carries it. Mechanically simplest, but most demanding on [[Special:MyLanguage/Detour简介|Detour]] precision and the [[Special:MyLanguage/使用自动对准料架功能|rack-alignment]] algorithm.

参考：浙江迈睿 KIVA 适配（`D:\src\cookbook\adaption-reference\浙江迈睿\CartAdapters\kiva\`）以及苏州艾吉威的对应 ClumsyPilot 实现。
References: Zhejiang Mairui KIVA adapter (`D:\src\cookbook\adaption-reference\浙江迈睿\CartAdapters\kiva\`) plus Suzhou Eswei's ClumsyPilot.

== 硬件清单 / Hardware ==
{| class="wikitable"
! 部件 / Part !! 典型规格 / Typical spec
|-
| 底盘 / Chassis || 双驱动差速（差速旋转） / Two-wheel differential
|-
| 驱动电机 / Drive motor || BLDC 200–600 W × 2
|-
| 顶升机构 / Jack || 电动丝杆 / liquid jack；行程 30–100 mm
|-
| 雷达 / Lidar || 顶面双向 2D（前后扫描）或单向 + 360° 反光板
|-
| IMU / IMU || 6-DoF，必备
|-
| 接近开关 / Proximity || 料架腿检测辅助 / aux for leg detection
|-
| 通讯 / Comm || 工控 PC 本体 + Wi-Fi 5
|}

不需要叉齿 / 倾角 / 复杂 PLC，硬件 IO 极少；MDCS 适配的核心难度在 ''钻入精度''与 ''带架原地旋转''。

No fork / tilt / complex PLC; minimal hardware IO. The MDCS adaptation difficulty is in ''slide-under accuracy'' and ''in-place rotation while carrying''.

== 1. Medulla 适配 / Medulla side ==
最小 IO 表 / Minimal IO surface:

<syntaxhighlight lang="csharp">
public class KivaCart : CartDefinition
{
[AsInitParam] public string motorPort = "COM3";
[AsInitParam] public float wheelBase = 460; // mm, between drive wheels
[AsInitParam] public float jackStroke = 80; // mm

[AsUpperIO] public float vLeft, vRight; // 双驱差速指令 / per-wheel cmd
[AsUpperIO] public float jackTarget; // 0 = down, jackStroke = up
[AsUpperIO] public bool led; // 顶部状态灯 / status LED

[AsLowerIO] public float vLeftEst, vRightEst;
[AsLowerIO] public float jackHeight;
[AsLowerIO] public bool jackAtTarget;
[AsLowerIO] public bool eStop;
[AsLowerIO] public int batteryPercent;
[AsLowerIO] public bool legProx; // 接近开关：腿在我下面 / leg under me
}
</syntaxhighlight>

ladder logic 同样 50 ms 周期；KIVA 一般通过厂商 USB-CAN 或 RS485 与轮控板通讯（具体协议见厂商手册）。

The ladder logic runs at 50 ms; talk to the wheel controllers over the vendor's USB-CAN or RS485 channel.

== 2. Clumsy 自动驾驶适配 / Clumsy side ==
关键 Movement / Key movements:

* `SteeringLineFollowing` — 巡线到 ''料架前 anchor''
* `AutoShelfFetching_ManyLegs` — 自动钻入并对准料架（见 [[Special:MyLanguage/使用自动对准料架功能|使用自动对准料架功能]]）
* `JackUp(targetHeight)` — 顶升包封，等待 `jackAtTarget` 为 true
* `InPlaceRotate(angle)` — 带架原地差速旋转（必须在 jack-up 后启用 ''带载包络''）

<syntaxhighlight lang="csharp">
public class AGV : SimpleAgvInterface
{
public void PickRack(double anchorX, double anchorY, double rackX, double rackY)
{
Queue(
async () =>
{
DriveTask.WaitDriveTask(new SteeringLineFollowing
{
srcX = currentX, srcY = currentY,
dstX = anchorX, dstY = anchorY,
basespeed = 800
}.Follow());
},
async () =>
{
// Slide under + auto-align (从 anchor 切到 rack centre)
DriveTask.WaitDriveTask(new AutoShelfFetching_ManyLegs
{
aX = anchorX, aY = anchorY,
bX = rackX, bY = rackY,
initSpeed = 600, inShelfSpeed = 200,
stopDist = 30, width = Configuration.conf.rackLegSpan,
startingSlot = 10
}.Get());
},
async () =>
{
// Jack up
SetUpperIO("jackTarget", Configuration.conf.jackStroke);
await WaitForLowerIO("jackAtTarget", 4000);
carryingRack = true;
});
}

public void DropRack(double targetX, double targetY)
{
Queue(
async () =>
{
DriveTask.WaitDriveTask(new SteeringLineFollowing
{
srcX = currentX, srcY = currentY,
dstX = targetX, dstY = targetY,
basespeed = 500 // 带载减速 / slow when loaded
}.Follow());
},
async () =>
{
SetUpperIO("jackTarget", 0);
await WaitForLowerIO("jackAtTarget", 4000);
carryingRack = false;
},
async () =>
{
// 后退 200 mm 退出料架 / withdraw 200 mm
DriveTask.WaitDriveTask(new SteeringLineFollowingReverse
{
srcX = targetX, srcY = targetY,
dstX = targetX - 0.2 * Math.Cos(currentTh),
dstY = targetY - 0.2 * Math.Sin(currentTh),
basespeed = 200
}.ReverseFollow());
});
}
}
</syntaxhighlight>

== 3. SimpleComposer 端 / SimpleComposer side ==
顶升车 ClumsyCar 子类需要 ''携带料架时的扩展包络''（料架长宽通常大于车体）：

The ClumsyCar subclass needs an alternate ''carried-rack envelope'' (rack is wider/longer than the AGV):

<syntaxhighlight lang="csharp">
[CarType(Name = "KivaCart", Title = "KIVA 顶升车 / KIVA lift-AGV")]
public class KivaCar : ClumsyCar
{
public bool carryingRack => /* 从车上心跳读 / from heartbeat */;

public override Envelope GetActiveEnvelope()
{
return carryingRack ? carriedRackEnvelope : base.GetActiveEnvelope();
}
}
</syntaxhighlight>

== 4. 标定与调试 / Calibration & tuning ==
# '''轮距与轮径标定''' / Track + wheel diameter: 做正反 5 m 直线，比较 Detour 估的位移与实际，差异 > 2% 必须改 wheel radius 配置。
# '''差速旋转误差''' / Rotation error: 原地转 360° × 10，累计偏差 < 5°。误差大 → 轮距错。
# '''料架腿检测先验''' / Leg priors: 真测料架腿距，写入 `width`。
# '''顶升时长''' / Jack timing: `inshelfMillis` 比顶升时长长 1 s，避免还没顶完就开走。
# '''反光板 / SLAM 切换''' / Reflector / SLAM switch: 反光板辅助定位时务必检查 KIVA 顶面雷达视野，料架钻入后是否仍能看到反光板。

# Wheel-track + diameter cal: drive 5 m fwd/back; if Detour pose differs > 2%, fix the radius.
# Rotation error: spin 360° ×10 in place; cumulative drift < 5° is acceptable.
# Leg priors: write real measured leg span into the `width` field.
# Jack timing: `inshelfMillis` should be 1 s longer than the jack-up time.
# SLAM vs reflector: confirm the top-mounted lidar still sees reflectors after the rack is on top.

== 5. 常见问题 / Common pitfalls ==
* '''钻入时撞腿''' / Hits leg on entry: 检测器 `blobDist` 太大或 anchor 站点离料架太近。
* '''顶升后偏摆''' / Sway after jack: 料架重心偏，或 jack 行程未完全到位；查 `jackAtTarget` 信号。
* '''带架转弯失败''' / Rotation fails with rack: 带载包络未启用，调度允许了无法通过的窄通道。
* '''返回原料架放回失败''' / Re-dock to same rack fails: anchor 与 rack 站点坐标在 SLAM 漂移后不一致；定期 [[Special:MyLanguage/标定与校准|重标定]]。

== 6. 通讯与节拍 / Comm & throughput ==
* 控制周期：50 ms（Medulla LadderLogic）/ Control cycle: 50 ms.
* 心跳：100 ms（向 SimpleComposer 报位置 + jackHeight）/ Heartbeat: 100 ms.
* 取放节拍参考：单次（取-搬-放）约 35–50 s（含 anchor 站到 anchor 站直线 8 m）。

== 相关页面 / See also ==
* [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]
* [[Special:MyLanguage/叉车适配案例|叉车适配案例]]
* [[Special:MyLanguage/全向车适配案例|全向车适配案例]]
* [[Special:MyLanguage/牵引车适配案例|牵引车适配案例]]
* [[Special:MyLanguage/使用自动对准料架功能|使用自动对准料架功能]]
* [[Special:MyLanguage/自动识别工位并取放货|自动识别工位并取放货]]

[[Category:开发手册]]

巡线行走

2026-05-16T11:26:50Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
"巡线行走"是 MDCS Clumsy 最基础的运动原语：给一个起点 (srcX, srcY) 和终点 (dstX, dstY)，AGV 沿直线段从起点驶到终点。它由 `SteeringLineFollowing`（正向）和 `SteeringLineFollowingReverse`（反向）两个 `MovementDefinition` 子类实现，所有其它复杂动作（取放货、绕障、双车联动）都是在它之上组合而成。

"Line following" is the most basic Clumsy motion primitive: given (srcX, srcY) and (dstX, dstY), the AGV runs a straight segment between them. It's implemented by `SteeringLineFollowing` (forward) and `SteeringLineFollowingReverse` (reverse), both `MovementDefinition` subclasses. Every higher action (pick/place, obstacle avoidance, twin-car coordination) composes on top.

文件 / Files: `D:\src\Clumsy\ClumsyCore\Legacy\SteeringLineFollowing.cs`、`SteeringLineFollowingReverse.cs`。

== 使用场景 / When to use ==
* 站点对点的直线行驶（无需绕障 / 无需精对位）。
* 取放货的 ''粗对位''阶段（开 [[Special:MyLanguage/自动识别工位并取放货|工位识别]] 之前的逼近）。
* 反向出库（用 `Reverse` 变体）。
* 简单调度的最小可用配置。

* Point-to-point straight driving on uncongested aisles.
* Coarse-approach stage before [[Special:MyLanguage/自动识别工位并取放货|station-aware pickup]].
* Reverse withdraw (the `Reverse` variant).
* Minimum config for a quick-running scheduler.

== 关键字段 / Key fields ==
{| class="wikitable"
! 字段 / Field !! 类型 !! 含义 / Meaning
|-
| `srcX`, `srcY` || `double` || 起点 / segment start (mm)
|-
| `dstX`, `dstY` || `double` || 终点 / segment end (mm)
|-
| `basespeed` || `int` || 巡航速度 / cruise speed (mm/s)
|-
| `lookAhead` || `float` || 纯跟踪前瞻距离 / pure-pursuit look-ahead (mm)
|-
| `dFactor` || `float` || 横向偏差转化为转向的增益 / lateral-error → steer gain
|-
| `slowdown` || `bool` || 临近终点时降速 / decelerate near goal (true by default)
|-
| `finSpeed` || `int` || 终点最低速度（slowdown 触发后）/ final speed when slowdown active
|-
| `slowdownDist` || `float` || 进入减速段的距离阈值 / decel-zone size (mm)
|}

`SteeringLineFollowingReverse` 字段完全一致；语义为车头朝向 ''不变''、车体后退到目标。
`SteeringLineFollowingReverse` has the same fields; the car drives in reverse while keeping its heading unchanged.

== 工作机制 / How it works ==
1. `MovementDefinition.Get()` 是一个 ''可枚举的 bool 序列''，每个 tick 返回一次 `true`（表示继续），直到完成时返回 `false` / 退出枚举。
2. `DriveTask.WaitDriveTask(IEnumerable<bool>)` 把这个序列每隔 `Configuration.conf.DriveTaskInterval` ms 调一次，并阻塞调用方直到序列结束。
3. 每个 tick 内部：
- 读当前位姿 `(x, y, th)`（来自 Detour，已订阅）。
- 计算前瞻点（沿目标线段往前 `lookAhead`）。
- 用纯跟踪法求转向角；`vCmd` 取 `basespeed`（若进入减速段则衰减到 `finSpeed`）。
- 写到 Medulla 上位 IO。
4. 当车体距 `(dstX, dstY)` 小于阈值（默认 50 mm），返回 `false` 结束。

1. `MovementDefinition.Get()` returns an `IEnumerable<bool>` ticked once per control cycle; `true` = keep going, end-of-iteration = done.
2. `DriveTask.WaitDriveTask(...)` ticks at `Configuration.conf.DriveTaskInterval` ms and blocks the caller until the iteration ends.
3. Each tick: read pose → compute look-ahead point → pure-pursuit steer → write `vCmd` / `steerCmd`.
4. Exits when within ~50 mm of `(dstX, dstY)`.

== 调用样例 / Example ==
<syntaxhighlight lang="csharp">
public void DriveStraight(double sx, double sy, double dx, double dy)
{
Queue(async () =>
{
DriveTask.WaitDriveTask(new SteeringLineFollowing
{
srcX = sx, srcY = sy,
dstX = dx, dstY = dy,
basespeed = 600,
lookAhead = 500,
dFactor = 1.2f,
slowdown = true,
finSpeed = 100
}.Follow());
});
}
</syntaxhighlight>

== 调试要点 / Tuning ==
{| class="wikitable"
! 现象 / Symptom !! 调整 / Adjustment
|-
| 路径偏移 / Drifts off the line || 增大 `dFactor`（默认 1.2），但太大会震荡
|-
| 在终点震荡 / Oscillates at goal || 启用 `slowdown` 并增大 `slowdownDist`
|-
| 终点冲过 / Overshoots || 降低 `basespeed` 或减小 `finSpeed`
|-
| 弯道内切 / Cuts inside corner (短线段段拼接时) || 减小 `lookAhead`
|-
| 慢速时跟不准 / Poor tracking at low speed || `dFactor` 与速度成反比；低速时增大
|-
| 反向跑歪 / Reverse drifts || 检查后向激光雷达视野；可能未启用，导致姿态误差累积
|}

== 与其它 Movement 的衔接 / Composing with other Movements ==
* 取货 / 放货前的接近 — 后接 `AutoFetchGood` / `AutoShelfFetching_ManyLegs`。
* 绕障 — 见 [[Special:MyLanguage/绕障行走|绕障行走]]。
* 反向出库 — 用 `SteeringLineFollowingReverse`，搭配同样的字段。
* 长路径 — SimpleComposer 调度会把长路径切成若干段 LineFollowing 拼接，每段一个 `srcX/Y → dstX/Y`。

== 注意 / Caveat ==
LineFollowing 是 ''几何意义''上的直线段跟踪，''与车型无关''。但具体 Movement 内部隐含假设：阿克曼 / 差速车型可以 ''转向即改向''。对全向车应改用 `OmniLineFollowing`（见 [[Special:MyLanguage/全向车适配案例|全向车适配案例]]），它允许车身朝向独立于运动方向。

`SteeringLineFollowing` is a geometric line-segment tracker but implicitly assumes Ackermann / differential kinematics. For omni vehicles use `OmniLineFollowing` (heading independent of motion direction) — see the omni case study.

== 相关页面 / See also ==
* [[Special:MyLanguage/绕障行走|绕障行走]]
* [[Special:MyLanguage/车体抽象原理|车体抽象原理]]
* [[Special:MyLanguage/Clumsy-API|Clumsy-API]]

[[Category:运动控制使用手册]]

如何基于SimpleCore核心库进行调度系统开发

2026-05-16T11:26:47Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
MDCS 的车队调度被分为两层：'''SimpleCore'''（核心算法库，包含交管、寻路、包络、可达性、DPS 等内核算法）与 '''SimpleComposer'''（基于 SimpleCore 的 UI 壳层，包含 CAD 工具、可视化、插件宿主）。本页面对开发者：你想自己写一个调度应用（或在 SimpleComposer 之外用 SimpleCore 内核）该如何开始。

MDCS fleet management is split into two layers: '''SimpleCore''' (algorithm library — traffic control, pathfinding, envelopes, reachability, DPS) and '''SimpleComposer''' (a UI shell built on SimpleCore — CAD tool, visualisation, plugin host). This page targets developers writing their own scheduling app on top of SimpleCore, or extending SimpleComposer with a custom car / mission type.

== 何时基于 SimpleCore 开发 / When to use SimpleCore directly ==
{| class="wikitable"
! 场景 / Scenario !! 建议 / Recommendation
|-
| 集成进非 SimpleComposer 的现成系统 || 直接用 SimpleCore，把 UI 留给原系统
|-
| 给 SimpleComposer 加车型 / 业务 || 写插件在 SimpleComposer 上挂载，不必自己写调度
|-
| 算法研究（新交管 / 新寻路） || SimpleCore，作为算法宿主
|-
| 单工位单车 || 都不需要，写一个小循环够了
|}

== 核心抽象 / Core abstractions ==
=== Car 体系 / Car hierarchy ===
SimpleCore 把"车"按照 ''是否使用 MDCS 车载系统'' 分为两支：
SimpleCore splits "cars" into two branches by whether they use the MDCS on-vehicle stack:

{| class="wikitable"
! 类 / Class !! 文件 / File !! 用途 / Use
|-
| `AbstractCar` || `D:\src\Simple\SimpleCore\PropType\AbstractCar.cs:346` || 调度可见的车的最小契约 / minimal scheduling contract
|-
| `Car` || `D:\src\Simple\SimpleComposer\RCS\Car.cs:33` || SimpleComposer 中的"车"基类 / Composer-side base
|-
| `ClumsyCar : Car` || `D:\src\Simple\SimpleComposer\RCS\ClumsyCar.cs:34` || 跑 MDCS 车载（Medulla + Clumsy）的车 / runs full MDCS on-vehicle stack
|-
| 自评估 `Car`（自定义子类）/ Self-eval `Car` (custom subclass) || 各 vendor 适配代码 / vendor adapters || PLC / 磁导航 / 二维码类无车载 PC 的车 / cars without on-board MDCS (PLC, magstrip, QR)
|-
| `AGVInterface` || `D:\src\Simple\SimpleCore\BasicProps\AGVInterface.cs` || 任务脚本调用的 API / API surface called by mission scripts
|}

=== AGVInterface 与 Queue 机制 ===
`AGVInterface` 暴露给任务脚本（TopazScript）的核心方法是 `Queue(params Func<Task>[] actions)` —— ''超标量'' 异步流水线：

The core method on `AGVInterface` exposed to mission scripts is `Queue(params Func<Task>[] actions)` — a "super-scalar" async pipeline:

* 每个 Func 是一个 ''行 / row''，按提交顺序进入流水线。
* 同一行内的代码顺序执行。
* 上一行未完成前，下一行不会开始 —— 但下一行可在上一行最后一个 await 后立即 schedule，达成宏观流水。
* `WaitAsync(int pipe)` 让调用方等到指定行完成再继续。

* Each Func is a '''row''' in the pipeline.
* Code within a row runs sequentially.
* The next row only starts after the previous row's last await, but its prelude can overlap, giving macro-level pipelining.
* `WaitAsync(int pipe)` lets the caller wait for a specific row.

=== TryLock / Leave — 交管 / Traffic control ===
`TryLock(int siteID)` / `Leave(int siteID)` 是 SimpleCore 交管在 ''每个 mission 脚本里''的钩子。任务脚本在进入一个交管区前必须 `TryLock`；离开时 `Leave`。SimpleCore 的内核保证：

`TryLock(siteID)` / `Leave(siteID)` are SimpleCore's traffic-control hooks ''per mission script''. Scripts must `TryLock` before entering a controlled segment and `Leave` on exit. SimpleCore's kernel guarantees:

* 无死锁（DPS 算法，见 [[Special:MyLanguage/DPS调度算法详解|DPS调度算法详解]]） Deadlock freedom (via DPS — see the DPS page).
* 公平（按到达顺序授予锁） Fairness — locks granted in arrival order.
* 兼容性（同一锁可被声明 ''可兼容车型'' 一起持有） Compatibility — a lock can be held simultaneously by compatible car types.

== 写一个 ClumsyCar 子类 / Subclassing ClumsyCar ==
ClumsyCar 用于车上跑完整 MDCS（Clumsy 自动驾驶 + Medulla 硬件抽象）的情况。最小子类骨架：

ClumsyCar is the right base when the vehicle runs the full MDCS stack on-board. Minimal subclass:

<syntaxhighlight lang="csharp">
using SimpleComposer.RCS;

namespace Vendor.Carts
{
[CarType(Name = "MyCart", Title = "我的车型 / MyCart")]
public class MyCart : ClumsyCar
{
public MyCart() : base()
{
conf = "configs/MyCart.config";
api_retries = 3;
}

public override async Task actualSendScript(string script)
{
// 把 TopazScript 通过 HTTP 发到车载 Clumsy 适配器 / POST to on-board Clumsy adapter
var url = $"http://{address}:30080/run";
var resp = await HttpClient.PostAsync(url, new StringContent(script));
resp.EnsureSuccessStatusCode();
}

public override async Task keepAlive()
{
// 心跳 + 状态轮询 / heartbeat + status poll
var status = await HttpClient.GetStringAsync($"http://{address}:30080/status");
UpdateStatusFromJson(status);
}
}
}
</syntaxhighlight>

参考样例（80 行可读完）：`D:\src\cookbook\adaption-reference\法睿兰达\CartAdapters\FY2208008\Scenes\AMRScene\ProjNameCar.cs`。
Reference (80 lines, easy to read end-to-end): `D:\src\cookbook\adaption-reference\法睿兰达\CartAdapters\FY2208008\Scenes\AMRScene\ProjNameCar.cs`.

== 写一个自评估 Car 子类 / Subclassing Car for self-eval vehicles ==
自评估车（磁导航 / 色带 / PLC 控制 / 二维码等）的车载没有 MDCS，调度只能发"高层意图"，由 ''SimpleCore 侧'' 的 AGV 接口翻译成厂商命令，再通过 RFID / Modbus / HTTP 下发。

Self-evaluating vehicles (magnetic-strip, tape, PLC-controlled, QR-only) don't run MDCS on-board. The scheduler dispatches "high-level intents", and a ''fleet-side'' `AGV : AGVInterface` translates them into vendor commands (RFID frames, Modbus, HTTP) and reads back `(x, y, th, siteID)` via `keepAlive()`.

经典样例：`D:\src\cookbook\adaption-reference\苏州凌鸟\Scenes\AMRScene1\Cars\MNavCar.cs`（293 行，含双向导航 + RFID 命令队列 + 启发式约束容器 `MNavCarHeuristics`）。

Canonical example: `D:\src\cookbook\adaption-reference\苏州凌鸟\Scenes\AMRScene1\Cars\MNavCar.cs` (293 lines — two-way navigation, RFID command queue, `MNavCarHeuristics` for no-go turns / forced reversals).

骨架 / Skeleton:

<syntaxhighlight lang="csharp">
[CarType(Name = "MyMagCart", Title = "磁导航车 / Magnetic-strip cart")]
public class MyMagCart : Car
{
public string address;
public int rfidPort = 502;

public class AGV : AGVInterface
{
private readonly MyMagCart car;
public AGV(MyMagCart c) { car = c; }

public override bool TryLock(int siteID, int route_id) { /* SimpleCore 内置 / inherit */ return base.TryLock(siteID, route_id); }
public override bool Leave(int siteID) { return base.Leave(siteID); }

public void Go(double sx, double sy, int sid, double dx, double dy, int did, int routeId)
{
Queue(
async () =>
{
// 在锁拿到后才发指令 / send intent only after lock granted
if (!TryLock(did, routeId)) return;
car.SendRFIDGoCommand(did);
},
async () =>
{
// 等到车真的到了 / wait until reported arrival
while (car.lastReportedSiteId != did) await Task.Delay(100);
Leave(sid);
});
}
}

public override async Task actualSendScript(string script) { /* 自评估车通常不发 TopazScript */ }
public override async Task keepAlive()
{
// Modbus / TCP 读位置并写入 (x, y, th, siteId) / poll position
var (x, y, th, siteId) = await PollPLCAsync(address);
UpdatePose(x, y, th); lastReportedSiteId = siteId;
}
}
</syntaxhighlight>

== 任务下发 / Mission dispatch flow ==

调度内核 → SegmentPlan.Compile() → TopazScript（一段脚本）
↓
CarProgram.script (放入 Car.status.programs.forecasted)
↓
Car.actualSendScript(script)
↓ (ClumsyCar) ↓ (self-eval)
HTTP POST 到车载直接在调度侧本地跑 SelfEvaluating(agv, script)
↓ ↓
车载 SelfEvaluating(agv, script) AGV.Go / AGV.Queue 等映射到 RFID/Modbus 命令
↓
Clumsy Movement 执行 → 物理运动

== Reachability 与包络 / Reachability & envelope ==
SimpleCore 提供 ''可达性状态机''（见 [[Special:MyLanguage/可达性状态编程|可达性状态编程]]）与 ''包络声明''（见 [[Special:MyLanguage/使用手册 - Simple:包络如何定义|包络如何定义]]）。你的 Car 子类一般只需要：

* 声明默认包络（无载货状态的车体包络）。
* 在带载 / 升叉 / 顶升等状态时声明 ''备用包络''，由 `HaveExtraEnvelope` 状态触发。
* 在不可达的路径段上声明 ''可达性规则''（例如：单向通道、最低剩余电量、强制掉头）。

A Car subclass typically: (1) declares the empty envelope, (2) declares alternate envelopes triggered by carry / fork-up / jack-up states, (3) declares reachability rules on path segments (one-way, min battery, mandatory reverse-out).

== 用作算法宿主：在 SimpleComposer 之外用 SimpleCore ==
SimpleCore 是普通 .NET 库（`D:\src\Simple\SimpleCore\`），可以独立引用。最小集成：

<syntaxhighlight lang="csharp">
using SimpleCore;

var world = new World(); // 加载站点 + 路径图 / load sites + path graph
world.LoadFromJson(File.ReadAllText("map.json"));

var car1 = new MyAbstractCarImpl(); // 实现 AbstractCar 接口
var car2 = new MyAbstractCarImpl();
world.AddCar(car1); world.AddCar(car2);

var planner = new DPSPlanner(world);
var mission = planner.Plan(
from: world.GetSite("A"),
to: world.GetSite("Z"));

foreach (var step in mission.Steps)
{
Console.WriteLine($"car={step.Car} site={step.Site} action={step.Action}");
}
</syntaxhighlight>

= 算法 / Algorithms =
SimpleCore 内置：
SimpleCore ships with:

* DPS 调度（动态规划交管）—— `[[Special:MyLanguage/DPS调度算法详解|DPS调度算法详解]]`
* 寻路启发器 —— `[[Special:MyLanguage/使用手册 - 寻路启发器功能|寻路启发器功能]]`
* 流场规划 —— `[[Special:MyLanguage/流场规划|流场规划]]`
* 网络流业务规划 —— `[[Special:MyLanguage/基于网络流的业务规划器|基于网络流的业务规划器]]`

== 调试 / Debugging ==
* 用 [[Special:MyLanguage/CycleGUI|CycleGUI]] 把交管锁、车辆状态、路径片段实时画出来。
* SimpleComposer 的 ''Trace 面板'' 显示每条任务的 Queue 行执行轨迹。
* 死锁怀疑时打开 ''DPS 决策可视化''（DPS 算法会输出每次决策的剪枝树）。

* Use [[Special:MyLanguage/CycleGUI|CycleGUI]] to render locks, car state, path segments live.
* SimpleComposer's ''Trace panel'' shows the Queue-row execution timeline per mission.
* When deadlock is suspected, enable ''DPS decision visualisation''.

== 相关页面 / See also ==
* [[Special:MyLanguage/AGV任务运行逻辑|AGV任务运行逻辑]]
* [[Special:MyLanguage/调度内核运行原理|调度内核运行原理]]
* [[Special:MyLanguage/DPS调度算法详解|DPS调度算法详解]]
* [[Special:MyLanguage/Simple-API|Simple-API]]
* [[Special:MyLanguage/开发手册 - SimpleComposer界面开发 - CAD工具|SimpleComposer界面开发]]
* [[Special:MyLanguage/使用手册 - Simple:从使用到开发|Simple:从使用到开发]]

[[Category:二次开发相关说明]]
[[Category:开发手册]]

叉车适配案例

2026-05-16T11:26:45Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
叉车（含牵引车、堆高车）是仓储 AMR 中最复杂的车型 —— 既要做 [[Special:MyLanguage/巡线行走|巡线行走]]、又要做 [[Special:MyLanguage/自动识别托盘取放货|托盘取放]]、再加上叉齿升降与平衡。本页用一台真实在产叉车（凌鸟 LB14）的源码 (`D:\src\cookbook\adaption-reference\苏州凌鸟\CartAdapters\LB14\`，~330 行可读) 串起完整适配流程。

Forklifts (incl. tractors, stackers) are the most complex class of warehouse AMR — they do [[Special:MyLanguage/巡线行走|line-following]], [[Special:MyLanguage/自动识别托盘取放货|pallet pick-and-place]], plus fork lift / tilt control and balance. This page walks through a real adaptation using Linbir LB14 source (`D:\src\cookbook\adaption-reference\苏州凌鸟\CartAdapters\LB14\`, ~330 LOC) as the running example.

== 硬件清单 / Hardware ==
{| class="wikitable"
! 部件 / Part !! 典型规格 / Typical spec
|-
| 底盘 / Chassis || 三轮（前驱单舵 + 后双轮被动）/ Three-wheel (front steer + 2 rear passive)
|-
| 驱动电机 / Drive motor || 永磁同步 1.5–4 kW
|-
| 转向编码器 / Steer encoder || 绝对值，分辨率 ≥ 14 bit
|-
| 叉齿马达 / Fork motor || 液压泵 + 阀，行程 100–3000 mm
|-
| 倾角传感 / Tilt sensor || IMU + 阀块行程编码
|-
| 前向激光 / Front lidar || 2D，高度对齐叉孔 / 2D at fork height
|-
| 后向激光（含侧扫）/ Rear lidar || 用于反向行驶 + 双车联动 V 槽观测 / reverse + V-groove for [[Special:MyLanguage/双车/多车联动|twin-car coordination]]
|-
| 负载传感 / Load sensor || 叉齿底油压或称重模块 / hydraulic pressure or load-cell
|-
| 通讯 / Comm || PLC 经 RS485 / Modbus 或专用 CAN / PLC via RS485 / Modbus, or proprietary CAN
|}

== 1. Medulla 适配 / Medulla side ==
关键文件：`D:\src\cookbook\adaption-reference\苏州凌鸟\CartAdapters\LB14\MedullaAdapter\`
- `LB14Cart.cs` — `CartDefinition` 子类，声明 IO 与 LadderLogic
- `Omron485.cs` / `OmronRoutine.cs` — RS485 报文层（与欧姆龙 PLC 通讯）
- `LB14Remote.cs` — 与厂商遥控手柄的协议

最少需要的 IO 声明 / Minimum IO surface:

<syntaxhighlight lang="csharp">
public class LB14Cart : CartDefinition
{
[AsInitParam] public string plcIp = "192.168.0.100";
[AsInitParam] public int plcPort = 502;
[AsInitParam] public float wheelBase = 1320; // mm
[AsInitParam] public float forkOffset = 760; // tine root to drive wheel

// 上位 IO（调度 / Clumsy 下发的意图）/ Upper IO (intent flowing down)
[AsUpperIO] public float vCmd; // 前进速度 / forward velocity (mm/s)
[AsUpperIO] public float steerCmd; // 转向角 / steer angle (rad)
[AsUpperIO] public float forkHeightTgt; // 叉齿目标高度 / fork target height
[AsUpperIO] public float forkTiltTgt; // 叉门架倾角 / fork tilt
[AsUpperIO] public bool brakeOn;
[AsUpperIO] public bool hornOn;

// 下位 IO（硬件回报的状态）/ Lower IO (status rising up)
[AsLowerIO] public float vEst;
[AsLowerIO] public float steerEst;
[AsLowerIO] public float forkHeight;
[AsLowerIO] public bool forkAtTarget;
[AsLowerIO] public float loadKg;
[AsLowerIO] public bool eStop;
[AsLowerIO] public int batteryPercent;

public override void Init()
{
// 1) 连接 PLC，握手 / connect & handshake
plcConn = OmronRoutine.Connect(plcIp, plcPort);

// 2) 注册看门狗 / register watchdog (LadderLogic ticks every ~50 ms)
plcConn.AttachStateCallback(OnPLCStatus);
}

[UseLadderLogic(IntervalMs = 50)]
public class ControlLoop : LadderLogic<LB14Cart>
{
public override void Run(LB14Cart self)
{
// 把 Upper IO 写到 PLC
self.plcConn.WriteRegisters(
vCmd: (int)(self.vCmd * 10),
steerCmd: (int)(self.steerCmd * 10000),
forkTgt: (int)self.forkHeightTgt
);
// 读 Lower IO
var s = self.plcConn.ReadStatus();
self.vEst = s.vEst / 10f;
self.steerEst = s.steerEst / 10000f;
self.forkHeight = s.forkHeight;
self.forkAtTarget = s.forkAtTarget;
self.loadKg = s.loadKg;
self.eStop = s.eStop;
self.batteryPercent = s.battery;
}
}
}
</syntaxhighlight>

== 2. Clumsy 自动驾驶适配 / Clumsy autopilot side ==
关键文件：`D:\src\cookbook\adaption-reference\苏州凌鸟\CartAdapters\LB14\ClumsyPilot\`
- `AGV.cs` (255 行) — `SimpleAgvInterface` 子类，业务级动作 `Fetch / Put / ExitSite / ReverseGo1`
- `Movements.cs` — 叉车特有的 `MovementDefinition` 子类
- `Configs.cs` / `CSGTypeF3CDef.cs` — 参数配置

叉车特有的 Movement / Movements specific to forklifts:

<syntaxhighlight lang="csharp">
public class AGV : SimpleAgvInterface
{
public int baseSpeed = (int) Configuration.conf.basicSpeed;
private SteeringLineFollowing lastDriver;
private SteeringLineFollowingReverse lastDriverR;

// 取货 / Fetch
public void Fetch(double srcX, double srcY, int srcid,
double dstX, double dstY, int dstid,
double pivotX, double pivotY)
{
Queue(
async () =>
{
// 1) 巡线到 srcX/Y（叉孔正前方）
DriveTask.WaitDriveTask(new SteeringLineFollowing
{
srcX = currentX, srcY = currentY,
dstX = srcX, dstY = srcY,
basespeed = baseSpeed
}.Follow());
},
async () =>
{
// 2) 升叉到取货高度
SetUpperIO("forkHeightTgt", Configuration.conf.fetchHeight);
await WaitForLowerIO("forkAtTarget", timeout: 5000);
},
async () =>
{
// 3) 自动识别托盘并对位
DriveTask.WaitDriveTask(new AutoFetchGood
{
aX = srcX, aY = srcY, bX = dstX, bY = dstY,
initSpeed = 500, inShelfSpeed = 150, stopDist = 80
}.Get());
},
async () =>
{
// 4) 升叉离地 50 mm
SetUpperIO("forkHeightTgt", forkHeight + 50);
await WaitForLowerIO("forkAtTarget", 4000);
},
async () =>
{
// 5) 倒退离开工位
DriveTask.WaitDriveTask(new SteeringLineFollowingReverse
{
srcX = dstX, srcY = dstY,
dstX = srcX, dstY = srcY,
basespeed = (int)(baseSpeed * 0.6)
}.ReverseFollow());
});
}
}
</syntaxhighlight>

== 3. SimpleComposer 端 / SimpleComposer side ==
ClumsyCar 子类的最简实现见 [[Special:MyLanguage/如何基于SimpleCore核心库进行调度系统开发|SimpleCore 开发指南]]。叉车多了一个 ''带载包络'' 状态：

A ClumsyCar subclass is minimal; the extra piece for forklifts is a '''carrying-load envelope''' state:

<syntaxhighlight lang="csharp">
[CarType(Name = "LB14", Title = "凌鸟LB14 叉车 / Linbir LB14 forklift")]
public class LB14 : ClumsyCar
{
public override Envelope GetActiveEnvelope()
{
if (carryingLoad)
return loadedEnvelope; // 带载包络 / loaded envelope (longer)
if (forkHeight > 500)
return highRiseEnvelope; // 高位包络（重心抬高）
return base.GetActiveEnvelope();
}
}
</syntaxhighlight>

== 4. 调试与标定 / Calibration & tuning ==
按下列顺序：
Order:

# '''基本运动''' / Basic motion: 站点对点行驶，调 `basespeed`、`steerCmd` 极性。
# '''激光雷达外参''' / Lidar extrinsics: 用 [[Special:MyLanguage/标定激光雷达外参|标定激光雷达外参]]。
# '''叉齿水平''' / Fork-tine horizontality: 用水平仪 + IMU 读数对齐。
# '''托盘检测先验''' / Pallet priors: 真实托盘测量 `pocketWidth`，写入 CAD。
# '''带载试运行''' / Loaded run-in: 不同载重 + 偏心载下跑同一路径，确认偏移收敛。
# '''高位放料''' / High-rise placement: 仅在 0–500–1500–2500 mm 多个高度测稳定性。

== 5. 常见问题 / Common pitfalls ==
* '''液压响应滞后导致超调''' / Hydraulic lag → 在 Movement 中加 ''下一目标提前 200 ms'' 的预设。
* '''叉孔对齐偏''' / Pocket misalign → 90% 是激光雷达水平度问题。
* '''带载横向漂''' / Lateral drift loaded → 检查 `wheelBase`、`forkOffset` 标定。
* '''反向行驶失败''' / Reverse line-follow fails → 后向激光遮挡或 `lastDriverR` 没设置成员。
* '''高位倒料''' / Tip-over at height → 高位包络未声明，调度允许了限速过高的路径。

== 6. 双车联动叉车 / Twin-car forklifts ==
叉车做 [[Special:MyLanguage/双车/多车联动|双车联动]] 时，作为 ''领头''常见，跟随车需用后向激光雷达观测领头叉车背面的 V 槽。详见双车联动页。

When a forklift participates in [[Special:MyLanguage/双车/多车联动|twin-car coordination]], it is typically the leader; the follower observes the leader's rear-mounted V-groove via rear lidar. See the twin-car page for details.

== 相关页面 / See also ==
* [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]] — 入门
* [[Special:MyLanguage/潜伏顶升车(KIVA类小车)适配案例|潜伏顶升车(KIVA类小车)适配案例]]
* [[Special:MyLanguage/全向车适配案例|全向车适配案例]]
* [[Special:MyLanguage/牵引车适配案例|牵引车适配案例]]
* [[Special:MyLanguage/使用叉车自动取托盘功能|使用叉车自动取托盘功能]]
* [[Special:MyLanguage/使用叉车料架堆叠功能|使用叉车料架堆叠功能]]

[[Category:开发手册]]

全向车适配案例

2026-05-16T11:26:44Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
全向车（mecanum 麦克纳姆轮或 4 独立舵轮）能 ''任意方向平移 + 独立旋转''，无非完整约束，适合狭窄场景。MDCS 中典型全向车是大重载（10 T+）平板搬运车，常出现在 [[Special:MyLanguage/双车/多车联动|双车联动]] 场景。

Omni vehicles (mecanum-wheel or 4-independent-steered-wheel) can ''translate in any direction + rotate independently'' — no non-holonomic constraints, ideal for tight spaces. The typical MDCS omni is a 10 t+ heavy-load flat-bed for [[Special:MyLanguage/双车/多车联动|twin-car]] operations.

参考：浙江联核（`D:\src\cookbook\adaption-reference\浙江联核\new\`）、卓一全向叉车（`D:\src\cookbook\adaption-reference\卓一\zhuoyiomniforklift\`）。
References: Zhejiang Lianhe (`adaption-reference\浙江联核\new\`), Zhuoyi omni-forklift.

== 硬件清单 / Hardware ==
{| class="wikitable"
! 部件 / Part !! 麦克纳姆 / Mecanum !! 四舵轮 / 4-steered
|-
| 驱动轮数 / Drive wheels || 4 (左前 / 右前 / 左后 / 右后全独立) || 4 独立驱动 + 4 独立转向
|-
| 编码器 / Encoders || 每轮一个 / 1 per wheel || 每轮 2 个（驱 + 转）
|-
| IMU || 必备 / required || 必备 / required
|-
| 控制板 / Controller || 单板可控 4 路 BLDC || 通常每对驱 / 转一对一块板
|-
| 重载承重 / Payload || 0.3–3 T || 5–20 T
|-
| 适用场景 / Use case || 中等重量、清洁机器人 || 重载、长货物
|}

== 1. Medulla 适配 / Medulla side ==
全向车的关键是 ''速度合成''：把 `(vx, vy, omega)` 拆成 4 路轮速 / 转向角，下发到电机。这通常在 LadderLogic 内做：

The crux is ''velocity synthesis'': decompose `(vx, vy, omega)` into 4-wheel speeds / steer angles. Do it inside the LadderLogic loop:

<syntaxhighlight lang="csharp">
public class OmniCart : CartDefinition
{
[AsInitParam] public string canDevice = "USBCAN0";
[AsInitParam] public float wheelBase = 1600; // mm (front-rear distance)
[AsInitParam] public float trackWidth = 1200; // mm
[AsInitParam] public float wheelRadius = 100; // mm

// 上位 IO — 三轴速度
[AsUpperIO] public float vxCmd; // 前向 / forward
[AsUpperIO] public float vyCmd; // 横向 / lateral (left positive)
[AsUpperIO] public float omegaCmd; // 转向角速度 / yaw rate

// 下位 IO — 4 路状态
[AsLowerIO] public float vEstW1, vEstW2, vEstW3, vEstW4;
[AsLowerIO] public bool eStop;

[UseLadderLogic(IntervalMs = 50)]
public class Loop : LadderLogic<OmniCart>
{
public override void Run(OmniCart s)
{
// 麦克纳姆轮 inverse kinematics（标准 4 轮，X 型布局）
var L = (s.wheelBase + s.trackWidth) / 2f;
var w1 = s.vxCmd - s.vyCmd - L * s.omegaCmd; // 左前
var w2 = s.vxCmd + s.vyCmd + L * s.omegaCmd; // 右前
var w3 = s.vxCmd + s.vyCmd - L * s.omegaCmd; // 左后
var w4 = s.vxCmd - s.vyCmd + L * s.omegaCmd; // 右后

// 转换到 RPM 并下发
s.can.SendWheelRPM(
w1 / s.wheelRadius,
w2 / s.wheelRadius,
w3 / s.wheelRadius,
w4 / s.wheelRadius);

// 读回 4 路速度
var status = s.can.ReadStatus();
s.vEstW1 = status.w1; s.vEstW2 = status.w2;
s.vEstW3 = status.w3; s.vEstW4 = status.w4;
s.eStop = status.eStop;
}
}
}
</syntaxhighlight>

四舵轮变体在上述基础上再加 4 路 steer angle，并把 (vx, vy, omega) → (4 个轮速 + 4 个转向角) 的解算改为 ''每个轮的方向''指向行驶切线 + ''每个轮的轮速'' 等于切线速率。

The 4-steered variant adds 4 steer-angle outputs and solves so each wheel's direction points tangent to its instantaneous motion arc.

== 2. Clumsy 自动驾驶适配 / Clumsy side ==
全向车需要 ''全向版本''的 Movement —— 不能直接用 `SteeringLineFollowing`（它假设阿克曼 / 差速）。建议家族：

Omni vehicles need ''omni variants'' of the Movements — `SteeringLineFollowing` assumes Ackermann / differential. The recommended family:

* `OmniLineFollowing` — 直线，可指定 ''移动朝向''与 ''车头朝向''独立
* `OmniArcFollowing` — 圆弧
* `OmniInPlaceRotate` — 不动平移、原地旋转
* `OmniSlotFollowing` — 替代 `SlotFollowing` 用于料架跟随

差异点：全向车可以 ''横向接近'' 工位（车头不变向，车身横向移动到工位），常用于狭窄取料场景。

The signature feature: omni can ''side-approach'' a station (car heading fixed, body slides sideways onto target), useful in narrow pick aisles.

<syntaxhighlight lang="csharp">
public void SideApproachShelf(double sx, double sy, double tx, double ty)
{
Queue(async () =>
{
DriveTask.WaitDriveTask(new OmniLineFollowing
{
srcX = sx, srcY = sy, dstX = tx, dstY = ty,
holdHeading = currentTh, // 保持车头方向
basespeed = 300
}.Follow());
});
}
</syntaxhighlight>

== 3. SimpleComposer 端 / SimpleComposer side ==
全向车的包络是 ''圆盘形''（旋转无差异），调度需要的可达性比阿克曼车型多很多。建议在 SimpleComposer 中给全向车型设置：
* 较小的包络半径（无前后偏置）
* 更宽松的可达性（无需考虑转向半径）

The omni envelope is a disk (rotation symmetric); reachability is much more permissive than Ackermann. Configure: small disk envelope, no turning-radius constraint in pathfinding.

== 4. 标定与调试 / Calibration & tuning ==
# '''轮间距与轮径''' / Track + wheel radius —— 每轮独立测，麦克纳姆轮的 ''滚轴角度''（45° 或 -45°）必须配对正确。
# '''轮间打滑''' / Slip: 同向运行时四轮速差应 < 2%。
# '''横向移动直线度''' / Sideway straightness: 横移 5 m，偏离 < 50 mm。否则有一轮打滑或方向错。
# '''带载性能''' / Loaded behaviour: 满载时麦克纳姆轮容易"挤压"地面，横向速度损耗严重，要建立载重-补偿表。

# Per-wheel track + radius — for mecanum the ''roller angle'' (±45°) sign must be correct per corner.
# Slip: in straight-fwd motion, the 4-wheel speed spread < 2%.
# Side-shift straightness: 5 m of pure lateral; lateral deviation < 50 mm.
# Loaded behaviour: heavy loads cause mecanum rollers to scrub; build a load → speed-compensation table.

== 5. 常见问题 / Common pitfalls ==
* '''横向移动不直''' / Side motion drifts: 通常是滚轴角度对应错（左前 / 右前 / 左后 / 右后 4 个角的滚轴角应为 -45° / +45° / +45° / -45° X 型布局）。
* '''重载时减速过快''' / Decelerates too fast loaded: 载重 → 加速度上限映射需重做。
* '''原地旋转有平移''' / In-place rotation drifts: 轮径 / 轮间距标定不准。
* '''麦克纳姆滚轴磨损快''' / Mecanum rollers wear quickly: 改 4 舵轮设计或限制带载横移用例。

== 6. 在双车联动中作为成员 / In twin-car coordination ==
[[Special:MyLanguage/双车/多车联动|重载双车联动]] 默认全向车作为主从两台。全向车的 V 形特征槽通常装在车体侧面（联动时两车横向并排，槽侧对槽侧）。

The default twin-car coordination configuration uses two omni AGVs side-by-side, with V-grooves on the lateral faces (side-to-side, not tail-to-tail) so each can observe the other while moving.

== 相关页面 / See also ==
* [[Special:MyLanguage/MDCS引擎适配机器人入门教学|MDCS引擎适配机器人入门教学]]
* [[Special:MyLanguage/叉车适配案例|叉车适配案例]]
* [[Special:MyLanguage/潜伏顶升车(KIVA类小车)适配案例|潜伏顶升车(KIVA类小车)适配案例]]
* [[Special:MyLanguage/牵引车适配案例|牵引车适配案例]]
* [[Special:MyLanguage/双车/多车联动|双车/多车联动]]

[[Category:开发手册]]

识别料框并堆垛拆垛

2026-05-16T11:15:22Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
"识别料框并堆垛拆垛"是面向 ''金属 / 塑料料框'' 的自动化动作集合：识别料框上沿与开口、堆码到指定高度、按节拍拆垛到指定层。料框相比标准托盘特征更复杂（边沿薄、四角圆滑、可能堆叠 4–6 层），因此需要 3D 感知 + 多帧融合。

"Kit-bin stacking / de-stacking" handles ''metal / plastic kit-bins'' — pickup, stack to a target height, or remove top bins to a target tier. Bins are harder than pallets to detect (thin lips, rounded corners, stacks up to 4–6 layers), so we use 3D sensing + multi-frame fusion.

== 与料架 / 托盘的区别 / Difference from racks / pallets ==
{| class="wikitable"
! 项 / Item !! 标准托盘 / Pallet !! 料框 / Kit-bin
|-
| 几何特征 / Features || 两个叉孔 + 边沿 || 上沿矩形 + 内空腔 + 边沿圆弧
|-
| 叉齿可入位 / Fork pockets || 是 / Yes || 否（叉齿夹外沿或抓取）/ No (clamp or grab)
|-
| 堆叠层数 / Stack height || 2–3 层 / 2–3 || 4–6 层 / 4–6
|-
| 主用感知 / Sensing || 2D 激光 || 3D 激光 / 深度相机 + 2D 辅助
|-
| 主用 Detector || `LidarDetectPallet` || `LidarDetect3DBin`, `CamDetectBinRim`
|}

== 工作流程 / Pipeline ==
=== 堆垛 / Stack ===
# 巡线到 ''下层 Anchor'' 站点（距堆位约 1.5 m）。
# 3D 激光扫描堆区，提取 ''最顶层料框''的上沿矩形（4 个角点 + 1 个朝向）。
# 计算放置位姿 = 最顶层上沿姿态 + 设计层高（典型 250 mm）。
# 升叉到 ''计算放置高度 + 30 mm''；可升降激光重新检测目标层确认。
# 横向 + 朝向精对位（≤ ±10 mm / ±0.5°）。
# 缓慢降叉直到接触检测信号（如 `forkLoadDetected` 反转）。
# 倒车离开。

=== 拆垛 / De-stack ===
# 巡线到 ''下层 Anchor'' 站点。
# 3D 扫描 → 选定 ''要取的层''（默认最顶层；可指定）。
# 升叉到 ''目标层下沿 - 10 mm''。
# 抓取机构闭合 / 叉齿前推；触发 `binGripDetected`。
# 升叉 50 mm 提离堆。
# 倒车离开。
# 巡线到目标释放位 → 落料 → 完成。

<syntaxhighlight lang="csharp">
// Stacking step 3 sketch
var top = new LidarDetect3DBin
{
expectedWidth = 600,
expectedDepth = 400,
minConfidence = 0.7f
}.Detect(latest3DCloud);

var placeX = top.X;
var placeY = top.Y;
var placeZ = top.Z + binLayerHeight + 30; // 30 mm safety margin

await Lift(placeZ);
await DriveTask.WaitDriveTask(new BinPlaceMovement
{
targetX = placeX, targetY = placeY,
targetTheta = top.Theta
}.Get());
await Lift(placeZ - binLayerHeight - 30); // settle
await OpenGrip();
await Reverse(1.5);
</syntaxhighlight>

== 多帧融合 / Multi-frame fusion ==
单帧 3D 激光的上沿点云因遮挡 / 反射常有缺失。MDCS 采用 ''K 帧合并 + 矩形拟合''：

A single 3D frame often misses bin rims due to occlusion / reflection. MDCS uses ''K-frame merge + rectangle fit'':

# 在 Approach 站点静态停车，连续读 K 帧（典型 K = 5）。
# 合并点云后去除地面 + 远处点 ROI 过滤。
# 在 ROI 内做矩形 RANSAC 拟合，输出矩形中心 + 朝向 + 平面高度。
# 若 ''confidence < 0.7''，把车前进 100 mm 再扫一轮（避免遮挡）。

== 关键 Detector / Key detectors ==
{| class="wikitable"
! Detector !! 文件 / File !! 用途 / Use
|-
| `LidarDetect3DBin` || `Clumsy\ClumsyDance\Detectors\LidarDetect3DBin.cs` || 3D 激光：从单 / 多帧扫描中提 bin
|-
| `CamDetectBinRim` || `Clumsy\ClumsyDance\Detectors\CamDetectBinRim.cs` || 深度相机 + 2D 辅助
|-
| `LidarDetect2DTier` || `Clumsy\ClumsyDance\Detectors\LidarDetect2DTier.cs` || 升降 2D 激光：按高度切层
|}

== 调试要点 / Tuning ==
* '''3D 点云稀疏 / 3D cloud too sparse''' → 增加 K 帧合并数，或检查 3D 雷达 [[Special:MyLanguage/3D激光雷达适配|适配]] 中的扫描频率。
* '''料框边沿反光强烈 / Rim glints''' → 调高强度阈值，过滤 specular spike。
* '''抓取后晃动 / Bin swings after grab''' → 检查抓爪夹紧力；落料前留 2 s 稳定时间。
* '''层高漂移 / Tier-height drift over many stacks''' → 每次堆完做一次重新 3D 扫描，更新堆顶基准。

== 安全 / Safety ==
* 堆叠中倒塌风险随堆高指数上升；4 层以上必须 ''每次堆完都重新读 IMU 与上沿姿态''，姿态偏差 > 1° 立即停。
* 料框拆垛过程中下层料框可能因震动错位，必须在 ''每次拆垛后''重新扫一次堆顶。

== 相关页面 / See also ==
* [[Special:MyLanguage/自动识别工位并取放货|自动识别工位并取放货]]
* [[Special:MyLanguage/使用叉车料架堆叠功能|使用叉车料架堆叠功能]]
* [[Special:MyLanguage/托盘识别|托盘识别]]
* [[Special:MyLanguage/3D激光雷达适配|3D激光雷达适配]]

[[Category:特殊技术方案]]
[[Category:运动控制使用手册]]

设备跟随联动

2026-05-16T11:15:21Z

Artheru：Initial bilingual draft (auto-published)

<languages/>

== 概述 / Overview ==
"设备跟随联动"指 AGV 跟随 ''非 AGV 设备''（手推叉车、人工拖车、卷料车、料箱等）协同移动的功能。与 [[Special:MyLanguage/双车/多车联动|双车 / 多车联动]] 的区别：本场景中 ''领头是设备 / 人''，不属于 MDCS 调度网络，没有可控信号；跟随车只能依靠 ''视觉 + 激光''观测领头物体并跟随。

"Device-following coordination" lets an AGV shadow a '''non-AGV device''' (manual trolley, hand-pushed forklift, coil cart, kit-box, …). Compared to [[Special:MyLanguage/双车/多车联动|twin-car coordination]], the leader here is a piece of equipment or a person — it's outside the MDCS scheduling network and has no controllable signal. The follower can only ''observe'' the leader via vision / lidar and respond.

== 应用场景 / Scenarios ==
* '''人工卸车 + AGV 接驳''': 工人在卡车上把货物推到边沿，AGV 在地面跟随接货位。
* '''卷料车跟随 / Coil-cart shadowing''': 操作工推卷料车从一道工序到下一道，AGV 跟随承担载货。
* '''跨工序流转 / Inter-process transfer''': 装配线上的料箱由工艺人员沿不规则路径推动，AGV 自动跟随至工位。
* '''拖车协同 / Trailer-tow assist''': 牵引车前牵，AGV 在后段加推支撑（适用于长拖车）。

== 与已有联动方案的差异 / What makes it different ==
{| class="wikitable"
! 项 / Item !! 双车联动 / Twin-car !! 设备跟随联动 / Device-follow
|-
| 领头 / Leader || 同样是 MDCS AGV / Another MDCS AGV || 任意非 AGV 设备 / 人 / Any device / human
|-
| 通讯 / Comms || AP Wi-Fi 心跳 / AP heartbeat || 无通讯，纯视觉 + 激光 / None — vision / lidar only
|-
| 任务下发 / Task dispatch || 调度直接派单 / Scheduler dispatches both || 领头无法接收任务；调度只能管跟随车
|-
| 路径 / Path || 调度规划 / Scheduler-planned || 领头自由路径 / Leader free-form
|-
| 速度 / Speed || 调度约束 / Scheduler-bounded || 跟随者跟领头实时速度（带上限）/ Follower matches leader (with cap)
|-
| 失联处理 / Lost-leader || 联动解体 / Decouple || 跟随者就地停 / Stop in place
|}

== 实现方案 / Implementation ==
=== 感知 / Perception ===
跟随车需要在领头设备上识别一个稳定的 ''视觉锚点'' — 几种可选：
The follower needs a stable ''visual anchor'' on the leader. Options:

* '''V 槽 / V-groove''' — 在设备背面装 1 个 V 槽（同 [[Special:MyLanguage/双车/多车联动|双车联动]]）。2D 激光检测，最便宜可靠。
* '''AprilTag / ArUco''' — 在设备背面贴一个易识别 fiducial；前向相机检测。
* '''3D 模板''' — 用 3D 点云模板匹配（领头形状已知，如标准卷料车）。
* '''腿对检测 / Leg-pair''' — 领头有两条立柱（如标准托盘车），用 `LidarDetectTray` 检测。

推荐组合：V 槽 + AprilTag 冗余；任一可识别即继续，两者全丢 ≥ 2 s 则停车。

Recommended combination: V-groove + AprilTag redundancy. If either is found, continue. If both lose lock for ≥ 2 s, stop.

=== 跟随控制器 / Follow controller ===
跟随车的运动控制本质是一个 ''常距点对点跟踪器''，目标点 = 领头锚点 - (固定偏移)。
The follower's motion control is essentially a constant-distance point tracker, with the target = leader anchor − fixed offset.

<syntaxhighlight lang="csharp">
public class DeviceFollow : MovementDefinition
{
public float standoff = 1500; // 距领头多远 / standoff (mm)
public float maxSpeed = 600;
public float ahesionGain = 0.8f; // 横向 / 朝向校正强度

public override IEnumerable<bool> Get()
{
var detector = new LidarDetectTray
{
blobDist = 100,
BlobPtCount = 3
};

var lostFrames = 0;
while (true)
{
var lead = detector.DetectLeader(); // 领头锚点
if (lead == null)
{
if (++lostFrames > 50) // 50 ticks ≈ 2 s
{
DriveStop();
yield break;
}
yield return true;
continue;
}
lostFrames = 0;

var dist = lead.Range;
var lateral = lead.Lateral;
var theta = lead.Heading;

// 控制律 / control law
var fwd = MathF.Min(maxSpeed, (dist - standoff) * 1.2f);
var turn = -(lateral * ahesionGain + theta * 0.5f);

SetDriveCommand(fwd, turn);
yield return true;
}
}
}
</syntaxhighlight>

=== 安全与边界 / Safety guards ===
* '''跟随距离上下限 / Standoff bounds''': 太近会撞领头，太远会丢锁；推荐 1.0–2.5 m。
* '''加速度上限 / Accel bound''': 领头突然提速时跟随车不能瞬时跟上；加上 0.5 m/s² 上限。
* '''转向角速度上限 / Angular vel bound''': 领头急转 → 跟随车保持不超过 0.5 rad/s。
* '''与人接触 / Contact with humans''': 跟随车的紧急停止线必须独立于跟随逻辑；激光雷达 1 m 内有任何障碍物立即触发 e-stop。

== 调度集成 / Scheduling integration ==
* SimpleComposer 把"跟随设备" 状态视为一个特殊 mission：调度不规划跟随车的路径，只是 ''把跟随车锁定''在跟随状态。
* `Car.CurrentMission = Following("DeviceXX")`；调度看到这个状态时不会派其它任务给该 AGV。
* 跟随过程中跟随车汇报自己的实时位姿；调度可视化展示 ''领头-跟随'' 链路。

SimpleComposer treats "follow-device" as a special mission state. The scheduler does not plan a path; it just locks the AGV into following mode and won't dispatch other tasks until the follow ends.

== 启动 / 结束 / Start & end ==
* '''启动 / Start''': 通过 SimpleComposer 上的"启动设备跟随"按钮；选定要跟随的设备类型；车开始尝试识别。
* '''确认 / Confirm''': 识别到锚点后车体调整姿态并停在 standoff 距离上；车灯绿色提示。
* '''结束 / End''': 操作工通过手柄按"结束跟随"，或跟随车到达预设终点站点（参数化）。

== 调试要点 / Tuning ==
* '''跟随抖动 / Jitter''': 调低 `ahesionGain`，或在检测端加 EWMA 滤波。
* '''领头突然消失 / Sudden lost-lock''': 缩短 `lostFrames` 阈值（默认 50 ticks ≈ 2 s）。
* '''拐弯时甩出 / Slips on turn''': 把 `maxSpeed` 降到 400 mm/s，或在领头加 AprilTag 增强检测稳定性。

== 相关页面 / See also ==
* [[Special:MyLanguage/双车/多车联动|双车 / 多车联动]]
* [[Special:MyLanguage/联动天眼系统进行装卸车|联动天眼系统进行装卸车]]
* [[Special:MyLanguage/巡线行走|巡线行走]] — 跟随的退化情况

[[Category:特殊技术方案]]

自动识别托盘取放货

2026-05-16T11:15:20Z

Artheru：Initial bilingual draft (auto-published)

<languages/>
== 概述 / Overview ==
"自动识别托盘取放货"是 [[Special:MyLanguage/自动识别工位并取放货|自动识别工位并取放货]] 的特例：工位本身是一个独立的托盘（pallet）而非固定货架，车体到位后通过激光雷达识别托盘的 ''两个插孔''（叉车场景）或 ''两个边缘特征''（顶升 / 平板场景），完成对位 + 升降 + 离场。

"Auto-pallet pick & place" specialises [[Special:MyLanguage/自动识别工位并取放货|station-aware pick & place]] to pallets. The "station" is the pallet itself, not a fixed rack. Once the vehicle is roughly in front, the lidar locates the pallet's '''two fork-pockets''' (forklifts) or its '''two side edges''' (lift / flat-bed vehicles), then the car runs the alignment / lift / withdraw sequence.

== 与货架取放的差异 / Difference from rack pick ==
{| class="wikitable"
! 项 / Item !! 货架（KIVA 类）/ Rack (KIVA) !! 托盘 / Pallet
|-
| 特征点 / Features || 4 条立腿 / 4 legs || 2 个叉孔或 2 条边 / 2 fork pockets or 2 edges
|-
| 进入方向 / Entry side || 任意（钻入式）/ any (slide-under) || 固定一侧（短边）/ fixed short edge
|-
| 升降高度 / Lift travel || 30–80 mm（顶升）/ 30–80 mm (jack) || 100–1800 mm（叉齿）/ 100–1800 mm (forks)
|-
| 误差容忍 / Tolerance || ±30 mm / ±2° || ±15 mm / ±1.5°（叉孔机械约束）
|-
| 主用 Movement || `AutoShelfFetching_ManyLegs` || `AutoFetchGood`, `PutGood`
|-
| 主用 Detector || `LidarDetectTray` (3-腿) / 4-腿 || `LidarDetectPallet`, `LidarBlobPairDetector`
|}

托盘场景对车体姿态的容忍度比货架低，因为叉齿与叉孔的机械配合余量只有 10–15 mm；调试时务必先用 [[Special:MyLanguage/标定与校准|标定与校准]] 把外参打齐。

Pallet pickup tolerates less pose error than rack pickup because the fork-pocket/fork-tine clearance is only 10–15 mm. Always level the lidar and verify extrinsics via [[Special:MyLanguage/标定与校准|the calibration guide]] before tuning.

== 工作流程 / Pipeline ==
# '''粗对位 / Coarse approach''': SimpleComposer 把 AGV 派到托盘前的 ''anchor 站点''，使用普通巡线 / 路径跟踪。 SimpleComposer dispatches the AGV to the anchor site in front of the pallet; ordinary line / path follow.
# '''粗检测 / Coarse detect''': 启动 `LidarDetectPallet`，从前方激光帧中找出托盘的两个特征（叉孔中心 or 边缘中点）的近似位置。 Start `LidarDetectPallet` to extract approximate centers of the two pallet features from one or two lidar frames.
# '''精对位跟踪 / Fine alignment''': 用检测出的两个点拟合托盘中轴线，`AutoFetchGood`（或 `PutGood`）开启跟踪，逼近期望停靠位姿。 Fit the pallet's midline from the two feature points; `AutoFetchGood` (or `PutGood`) opens a tracking thread to drive toward the docking pose.
# '''升降 / Lift''': 到位后通过 `[[Special:MyLanguage/Medulla-API|Medulla 上位 IO]]` 触发叉齿 / 顶升机构动作。 On dock, fire the fork / jack actuator through Medulla upper-IO.
# '''离场 / Withdraw''': 倒车（叉车）或推车前进（顶升）退出托盘正前方区域。 Reverse out (forklift) or roll forward (jack) to clear.

<syntaxhighlight lang="csharp">
public void PickPallet(double approachX, double approachY, double palletX, double palletY)
{
Queue(
async () =>
{
// 1. Coarse approach
DriveTask.WaitDriveTask(new SteeringLineFollowing
{
srcX = currentX, srcY = currentY,
dstX = approachX, dstY = approachY,
basespeed = 800
}.Follow());
},
async () =>
{
// 2 + 3. Detect + fine alignment (encapsulated in AutoFetchGood)
DriveTask.WaitDriveTask(new AutoFetchGood
{
aX = approachX, aY = approachY,
bX = palletX, bY = palletY,
initSpeed = 500,
inShelfSpeed= 150,
stopDist = 80, // tight: pocket / tine clearance
width = 800 // pallet pocket span
}.Get());
},
async () =>
{
// 4. Lift via Medulla upper-IO (fork at 200 mm)
MedullaAPI.SetUpperIO("forkHeight", 200);
await WaitForUpperIO("forkAtTarget", timeoutMs: 5000);
},
async () =>
{
// 5. Withdraw 1.5 m
DriveTask.WaitDriveTask(new SteeringLineFollowingReverse
{
srcX = palletX, srcY = palletY,
dstX = approachX, dstY = approachY,
basespeed = 400
}.ReverseFollow());
});
}
</syntaxhighlight>

== 调试要点 / Tuning ==
* '''叉孔检测假阳性 / False positive on fork pockets''': 缩窄 `LidarDetectPallet.widthMin/widthMax` 区间至 ±50 mm。
* '''托盘姿态偏 / Pallet pose drift''': 检查激光雷达水平度，重做 [[Special:MyLanguage/标定激光雷达外参|外参标定]]。
* '''叉齿与叉孔刮擦 / Tines scrape pocket walls''': 适当增大 `stopDist`（保留 20–30 mm 余量），或把 `inShelfSpeed` 降到 100 mm/s。
* '''码垛环境光斑干扰 / Beam glints in stacking yards''': 给托盘正面贴一段宽 50 mm 的吸光胶带可显著改善。

== 相关页面 / See also ==
* [[Special:MyLanguage/自动识别工位并取放货|自动识别工位并取放货]]
* [[Special:MyLanguage/托盘识别|托盘识别]] — 检测器的纯算法细节
* [[Special:MyLanguage/使用叉车自动取托盘功能|使用叉车自动取托盘功能]] — 终端使用手册视角
* [[Special:MyLanguage/识别料框并堆垛拆垛|识别料框并堆垛拆垛]]

[[Category:运动控制使用手册]]