Artheru：Initial bilingual draft (auto-published)

2026-05-16T14:00:06Z

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:开发手册]]

CartDefinition属性参考 - 版本历史

Artheru：​Initial bilingual draft (auto-published)

Artheru：Initial bilingual draft (auto-published)