+适用对象：第一次接触磁导航 + FASS 2.0 的调试/实施人员
+插件：`StandardScene.Magnetic.dll`
+车型：`MagFass2Car`
+最后更新：2026-07
- [8.1 节点块结构](#81-协议节点块25-字节结构)
+- [8.2 站点 fields 详细说明](#82-站点-fields-详细说明)
+- [8.3 路径 Track fields 详细说明](#83-路径-track-fields-详细说明)
+- [8.4 组包优先级与默认规则](#84-组包优先级与默认规则)
+- [8.5 典型场景配置示例](#85-典型场景配置示例)
+MagFass2Car 是 StandardScene **磁导航平台插件**里的 FASS 2.0 车型，主要能力：
| 能力 | +说明 | +
|---|---|
| 路径下发 | +通过 0xB1 下发站点序列（每帧最多 10 站） |
+
| 动作下发 | +通过 0xA1 补发站点动作（顶升、充电等） |
+
| 状态接收 | +UDP 模式：车体主动上报 100B，调度回 0x10 |
+
| 站点业务 | +从地图 fields 读取启停、分叉、顶升等，拼进任务 |
+
| 环线配合 | +与 Core LoopMission 配合，自动跑 goalSite |
+
| 任务闭环 | +状态机判断到站 + 动作是否完成，再发下一段 | +
同一插件内还有 **MagCar（FASS 1.0 TCP）**，两者可并存，注意车型和 Mission 不要配混。
确认场景已加载 scene.mag（StandardScene.Magnetic.scene.json），提供：
MagCar、MagFass2CarEventCarMission、MagFass2LoopMissionMagFass2Car**| 参数 | +示例值 | +含义 | +
|---|---|---|
address |
+192.168.1.100 |
+车体 IP | +
Port |
+5000 |
+下发命令的目标端口 | +
ListenPort |
+20103 |
+调度监听车体上报的端口 | +
VehicleCode |
+1 |
+车体编号，须与上报帧一致 | +
CommMode |
+Udp |
+PCB/UDP 模式（推荐） | +
keepAlive 日志出现 keepAlive udp okProtocol = FASS2.0/UDP在车辆方法里点 **「查询状态」**，再点 **「启动」**，确认有日志且无报错。
+**方式 A — 手动 Go（Web/调度下发）**
+用系统自带的「去某站」功能，内部会编译脚本，例如：
+
+agv.MagFass2Go(1, 2, 0.2);
+agv.MagFass2Go(2, 5, 0.2);
+**方式 B — LoopMission 环线**
+LoopMission** 或 **磁导航FASS2环线**tasklist.jsongoalSite 并导航
+┌─────────────────────────────────────────────────────────┐
+│ 业务层：LoopMission / 手动 Go / 脚本 │
+│ （分配 goalSite 或编译多行 MagFass2Go） │
+└────────────────────────┬────────────────────────────────┘
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ MagFass2Car 执行层 │
+│ · 脚本拦截（Loop + goalSite）→ 一次全程任务 │
+│ · Fass2TaskBuilder：路径 + fields → 节点序列 │
+│ · Fass2TaskStateMachine：滑动窗口下发 + 动作闭环 │
+└────────────────────────┬────────────────────────────────┘
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ 协议层：Fass2Protocol + Fass2UdpHub │
+│ · 收 100B 状态 → 回 0x10 │
+│ · 发 0x01/0xB1/0xA1 到 address:Port │
+└────────────────────────┬────────────────────────────────┘
+ ▼
+ AGV 车体
+**关键理解：**
+goalSite 标签）文件：StandardScene.Magnetic.scene.json
+{
+ "carTypes": [ "MagCar", "MagFass2Car" ],
+ "missionTypes": [ "EventCarMission", "MagFass2LoopMission" ]
+}
+| Mission | +来源 | +适用 | +
|---|---|---|
LoopMission |
+Core | +通用环线，MagFass2Car 同样可用 | +
磁导航FASS2环线（MagFass2LoopMission） |
+Magnetic 插件 | +逻辑与 LoopMission 相同，名称标识磁导航 FASS2 场景 | +
FASS车辆事件进程（EventCarMission） |
+Magnetic 插件 | +**仅 MagCar（FASS 1.0）**，不驱动 MagFass2Car | +
+新手建议：MagFass2Car 环线用 **`LoopMission`** 或 **`磁导航FASS2环线`** 均可。
+{
+ "tasks": [
+ {
+ "id": "loop-1-2",
+ "startType": "AutoLoop",
+ "kind": "Loop",
+ "currentStationId": 1,
+ "targetStationId": 2,
+ "priority": 1,
+ "trafficControl": 2
+ },
+ {
+ "id": "loop-2-1",
+ "startType": "AutoLoop",
+ "kind": "Loop",
+ "currentStationId": 2,
+ "targetStationId": 1,
+ "priority": 1,
+ "trafficControl": 2
+ }
+ ]
+}
+含义：车到站 1 → 自动分配目标站 2；到站 2 → 自动分配目标站 1，形成环线。
+在场景编辑器中选中 MagFass2Car，常用字段如下。
| 字段 | +默认 | +说明 | +
|---|---|---|
CommMode |
+Udp |
+Udp=PCB 被动收状态；Tcp=PLC 主动查询 |
+
address |
+— | +车体 IP | +
Port |
+5000 |
+命令下发端口 | +
ListenPort |
+20103 |
+调度 UDP 监听端口 | +
VehicleCode |
+0 |
+必须与车体上报的 Car 字段一致 |
+
UdpOfflineTimeoutMs |
+15000 |
+超过此时间未收到上报视为离线 | +
| 字段 | +默认 | +说明 | +
|---|---|---|
EnableTaskStateMachine |
+true |
+开启任务状态机（推荐） | +
EnableLoopTaskDrive |
+true |
+Loop 场景拦截多段脚本，改全程任务 | +
LockCount |
+4 |
+每次 0xB1 滑动窗口站数（≤10） |
+
TaskResendIntervalMs |
+500 |
+周期重发 0xB1 间隔 |
+
ActionRetryIntervalMs |
+1000 |
+动作未完成时 0xA1 重试间隔 |
+
MoveTimeoutSeconds |
+120 |
+单次移动超时（秒） | +
StartBeforeMove |
+true |
+移动前发 0x01 启动 |
+
| 字段 | +默认 | +说明 | +
|---|---|---|
UseTagValueAsNode |
+false |
+true 时用站点 TagValue 作为协议 Node 号 |
+
| 字段 | +默认 | +说明 | +
|---|---|---|
EnableDetailLog |
+true |
+详细日志 | +
LogRawFrame |
+true |
+打印收发十六进制 | +
+车体 ──UDP──► 调度 ListenPort（100B 状态）
+调度 ──UDP──► 车体 address:Port（0x10 应答）
+调度 ──UDP──► 车体 address:Port（0xB1/0xA1/0x01，独立发送）
+特点：
+0x10**（已由 Fass2UdpHub 自动处理）0x00 查询，同步收 100BCommMode = Tcp，配置 ConnectTimeoutMs 等| 检查项 | +操作 | +
|---|---|
| 车体上报发到哪 | +确认发往调度机 ListenPort |
+
| 调度命令发到哪 | +确认 address:Port 与车体监听一致 |
+
| 编号一致 | +VehicleCode = 上报帧内 Car 字段 |
+
| 防火墙 | +放行 UDP 双向 | +
**触发**：手动 Go、EnableLoopTaskDrive=false 时的 Loop、任意编译脚本。
**流程**：
+
+FindRoute → Compile → 多行脚本：
+ agv.MagFass2Go(1,2,speed);
+ agv.MagFass2Go(2,3,speed);
+ ...
+→ SelfEvaluating 逐行执行
+→ 每行：锁终点 → 发 0xB1 → 等到站 → 释放起点
+**特点**：每**条边**一段任务，多次 taskId，与交管「逐段锁点」一致。
**触发**：goalSite 标签 + 编译脚本含 MagFass2Go + EnableLoopTaskDrive=true。
**流程**：
+
+LoopMission 写 goalSite
+→ GoSite 仍 Compile 多行脚本（Core 不变）
+→ actualSendScript 拦截，不逐行执行
+→ ExecuteGoalTaskAsync(当前站 → goalSite)
+→ 状态机一次规划全程，滑动窗口发 0xB1
+**特点**：业务上一次任务，协议上仍遵守每帧 ≤10 站。
+**触发**：脚本里只有一行，或无 goalSite 的测试。
**流程**：与方式 1 的单行相同，状态机只跑 src → dst 一段。
| 维度 | +多段脚本 | +Loop 全程任务 | +
|---|---|---|
| 规划范围 | +每条边 | +当前站 → goalSite | +
| taskId | +每段一个 | +全程一个 | +
| 交通锁 | +每段锁终点 | +只锁 goalSite | +
| 适用 | +手动调试、兼容旧逻辑 | +环线自动跑 | +
| 开关 | +EnableLoopTaskDrive=false |
+EnableLoopTaskDrive=true（默认） |
+
任务组包时，调度读取地图中站点（Site）和路径（Track）的 fields 键值，合并写入 FASS 2.0 的 0xB1 节点块（每站 25 字节）。
**配置位置**：地图编辑器 → 选中站点或路径 → 属性/fields 面板 → 添加键值对。
+**命名约定**：
+Fass2_ 开头（代码常量见 Fass2SiteFields.cs）Fass2_Lift = 1true / false 或 1 / 0每个站点在 0xB1 中对应一个节点，主要字段如下（与 Fass2NodeMessage 一致）：
| 偏移 | +字段 | +类型 | +来源 | +
|---|---|---|---|
| 0–1 | +Node |
+ushort | +站点 TagValue 或 site.id |
+
| 2–3 | +Distance |
+ushort | +上一站到本站的边长（mm 量级） | +
| 4 | +StartStop |
+byte | +站点 Fass2_StartStop / 默认规则 |
+
| 5 | +Direction |
+byte | +站点或边 fields | +
| 6 | +Orientation |
+byte | +边朝向计算或站点覆盖 | +
| 7 | +Byroad |
+byte | +分叉选择，站点或边 | +
| 8–9 | +Speed |
+ushort | +边 Speed 换算（0.1 m/min 单位） |
+
| 10 | +Obstacle |
+byte | +站点 | +
| 11 | +Audio |
+byte | +站点 | +
| 12 | +Light |
+byte | +站点 | +
| 13 | +Charge |
+byte | +站点 | +
| 14 | +Rest |
+byte | +站点 | +
| 15 | +Lift |
+byte | +站点 | +
| 16 | +Clamp |
+byte | +站点 | +
| 17 | +Tray |
+byte | +站点 | +
| 18 | +Roll |
+byte | +站点 | +
| 19 | +Shutdown |
+byte | +站点 | +
状态机到站后，会比对车体上报状态帧中**同一节点块**的字段是否达到期望值；未达标则补发 0xA1。
| 项目 | +说明 | +
|---|---|
| 映射协议字段 | +Node（节点号） |
+
| 何时配置 | +磁导航地标号与地图 site.id **不一致**时必须配置 |
+
| 车辆开关 | +MagFass2Car.UseTagValueAsNode = true |
+
| 示例 | +TagValue = 10086 |
+
| 注意 | +未配置且 UseTagValueAsNode=false 时，直接用 site.id 作为节点号 |
+
| 项目 | +说明 | +
|---|---|
| 映射协议字段 | +无（不参与 0xB1 组包） | +
| 用途 | +LoopMission 在该站无任务匹配时，读取此字段作为默认下一目标 | +
| 读取方 | +Core AbstractLoopMission.LoopStartAction |
+
| 示例 | +站 3 配 goSite = 5，车到站 3 且无 tasklist 匹配时，自动写 goalSite=5 |
+
| 项目 | +说明 | +
|---|---|
| 映射协议字段 | +无（当前版本不直接写入节点块） | +
| 规划值 | +None / Button / Plc / Api |
+
| 当前状态 | +字段已定义，**等待放行联动逻辑待扩展**；可通过修改 Fass2_StartStop 或外部改 fields 触发重发 |
+
映射协议字段：StartStop（节点块第 5 字节）
| 值 | +含义（对齐 FASS 2.0 字典） | +典型场景 | +
|---|---|---|
1 |
+过站（不停） | +路径中间站、通道站 | +
2 |
+普通停车 | +工位、等待点、装卸点 | +
11 |
+管控启动 | +管控区入口，需授权后启动 | +
12 |
+管控停止 | +管控区停车等待 | +
22 |
+精准停止 | +装配、对接，精度要求高 | +
**默认规则**（未显式配置 Fass2_StartStop 时，Fass2TaskBuilder 自动决定）：
| 站点位置 | +默认 StartStop |
+
|---|---|
| 中间站 | +1（过站） |
+
| 末站（goalSite） | +2（停车） |
+
末站 + Fass2_PrecisionStop=true |
+22（精准停） |
+
**动作完成判定**：若配置了非过站值，状态机要求上报 Node.StartStop 与期望值一致，且车体非运行态（State≠1），才推进下一段。
**与 Fass2_PrecisionStop 关系**：
Fass2_StartStop = 22Fass2_PrecisionStop = true，由组包器自动设为 22| 项目 | +说明 | +
|---|---|
| 类型 | +true / false / 1 / 0 |
+
| 效果 | +仅对**路径末站**生效，等价于 StartStop = 22 |
+
| 优先级 | +低于显式 Fass2_StartStop（若同时配置，以 Fass2_StartStop 为准） |
+
| 示例 | +装配工位末站：Fass2_PrecisionStop = true |
+
映射协议字段：Byroad
| 项目 | +说明 | +
|---|---|
| 取值范围 | +通常 0–3，表示磁分叉/岔路选择序号 |
+
| 站点 vs 边 | +站点显式配置优先；未配置时继承**进入该站的边** Fass2_Byroad 或 magSelect |
+
| 典型场景 | +Y 型路口、多磁条岔口 | +
| 完成判定 | +若期望值非 0，上报 Node.Byroad 须一致 |
+
映射协议字段：Direction
| 项目 | +说明 | +
|---|---|
| 含义 | +到站后车头旋转指令（具体角度定义以车体协议为准） | +
| 站点 vs 边 | +站点配置覆盖边配置 | +
| 完成判定 | +上报 Node.Direction 与期望值一致 |
+
映射协议字段：Orientation
| 项目 | +说明 | +
|---|---|
| 含义 | +进出该站时的前进/后退/横移朝向（0–255，对应 0°–360° 量化） | +
| 默认 | +由边几何计算：atan2(Δy, Δx) + Reverse + CarDirectionBias |
+
| 覆盖 | +站点或边显式配置 Fass2_Orientation 时直接使用 |
+
| 完成判定 | +非 0 期望值时须上报一致 | +
映射协议字段：Lift
| 值 | +含义（对齐 backend 字典） | +
|---|---|
1 |
+上升到位 | +
2 |
+下降到位 | +
3 |
+上升中 | +
4 |
+下降中 | +
| 项目 | +说明 | +
|---|---|
| 典型场景 | +顶升搬运、装卸高度切换 | +
| 配置建议 | +工位停车（StartStop=2）+ Fass2_Lift=1 或 2 |
+
| 完成判定 | +上报 Node.Lift 等于配置值；未完成自动 0xA1 补发 |
+
| 注意 | +一般配**到位值**（1/2），不要配中间态（3/4）除非明确需要 | +
映射协议字段：Roll
| 项目 | +说明 | +
|---|---|
| 用途 | +滚筒输送启停/方向 | +
| 取值 | +以现场车体协议为准（写入节点块第 19 字节） | +
| 完成判定 | +期望值非 0 时须上报一致 | +
映射协议字段：Charge
| 值 | +含义 | +
|---|---|
1 |
+停止充电 | +
2 |
+开始充电 | +
| 项目 | +说明 | +
|---|---|
| 典型场景 | +充电站、LoopMission 充电触发任务 |
+
| 配置建议 | +充电工位：Fass2_StartStop=2 + Fass2_Charge=2 |
+
| 离站 | +下一任务或离站前可配 Fass2_Charge=1 |
+
映射协议字段：Rest
| 值 | +含义 | +
|---|---|
1 |
+停止睡眠 | +
2 |
+开始睡眠 | +
| 项目 | +说明 | +
|---|---|
| 典型场景 | +长时间待机工位、低功耗停车区 | +
映射协议字段：Obstacle
| 项目 | +说明 | +
|---|---|
| 用途 | +切换车体避障区域/模式 | +
| 取值 | +以车体协议定义为准（区域编号） | +
| 典型场景 | +进入狭窄通道、人机混行区 | +
| 字段 | +协议字段 | +用途 | +
|---|---|---|
Fass2_Audio |
+Audio |
+提示音、播报 | +
Fass2_Light |
+Light |
+警示灯、状态灯 | +
取值以车体协议为准，一般为模式/曲目/灯色编号。
+映射协议字段：Clamp
| 项目 | +说明 | +
|---|---|
| 用途 | +夹紧/松开机构 | +
| 典型场景 | +夹抱式 AGV、治具锁紧 | +
映射协议字段：Tray
| 项目 | +说明 | +
|---|---|
| 用途 | +托盘旋转/伸缩等机构 | +
| 典型场景 | +多工位转台、托盘调角 | +
映射协议字段：Shutdown
| 项目 | +说明 | +
|---|---|
| 用途 | +到站后车体软关机/深度待机 | +
| 注意 | +与全局 0x06 关机指令不同；此为**任务节点内**动作 |
+
| 风险 | +配置后车体可能下线，需人工或远程重启 | +
| 字段键 | +类型 | +协议字段 | +是否参与动作闭环 | +
|---|---|---|---|
TagValue |
+int | +Node |
+否（仅节点映射） | +
goSite |
+int | +— | +否（Loop 调度用） | +
Fass2_StartStop |
+byte | +StartStop |
+是 | +
Fass2_PrecisionStop |
+bool | +StartStop→22 |
+是 | +
Fass2_Byroad |
+byte | +Byroad |
+是（非 0 时） | +
Fass2_Direction |
+byte | +Direction |
+是（非 0 时） | +
Fass2_Orientation |
+byte | +Orientation |
+是（非 0 时） | +
Fass2_Lift |
+byte | +Lift |
+是（非 0 时） | +
Fass2_Roll |
+byte | +Roll |
+是（非 0 时） | +
Fass2_Charge |
+byte | +Charge |
+是（非 0 时） | +
Fass2_Obstacle |
+byte | +Obstacle |
+是（非 0 时） | +
Fass2_Audio |
+byte | +Audio |
+是（非 0 时） | +
Fass2_Light |
+byte | +Light |
+是（非 0 时） | +
Fass2_Rest |
+byte | +Rest |
+是（非 0 时） | +
Fass2_Clamp |
+byte | +Clamp |
+是（非 0 时） | +
Fass2_Tray |
+byte | +Tray |
+是（非 0 时） | +
Fass2_Shutdown |
+byte | +Shutdown |
+是（非 0 时） | +
Fass2_WaitMode |
+string | +— | +预留 | +
路径 fields 主要影响**进入该站的那段边**（距离、速度、朝向、分叉）。
+| 字段键 | +类型 | +映射 | +详细说明 | +
|---|---|---|---|
Speed |
+float | +Speed |
+边速度。≤1 按 **m/s**（协议值 = speed×600）；>1 按 **m/min**（协议值 = speed×10）。未配置默认 0.2 m/s |
+
Reverse |
+bool | +Orientation |
+true 时朝向 +180° |
+
CarDirectionBias |
+float | +Orientation |
+朝向偏置（度），叠加到几何朝向 | +
EnableCarAbsoluteDirection |
+bool | +Orientation |
+true 时用 CarAbsoluteDirection 代替几何计算 |
+
CarAbsoluteDirection |
+float | +Orientation |
+绝对朝向（度，0–360） | +
Fass2_Byroad |
+byte | +Byroad |
+边级分叉；站点未配 Fass2_Byroad 时生效 |
+
magSelect |
+byte | +Byroad |
+磁导航 coder 分叉序号；Fass2_Byroad 为空时作为 Byroad 备选 |
+
Fass2_Direction |
+byte | +Direction |
+边级车头旋转；站点未覆盖时生效 | +
Fass2_Orientation |
+byte | +Orientation |
+边级朝向；站点未覆盖时生效 | +
Magnet |
+bool | +— | +true 启用 MagneticTrackCoder（agv.MagGo 等），与 MagFass2Go 模板独立 |
+
ReverseDst |
+int | +— | +倒车目的地站 ID；磁 coder 跳过该边 | +
**距离 Distance**：由地图坐标自动计算（上一站与本站欧氏距离，mm 取整），一般无需手配。
当同一协议字段在站点和边都有配置时：
+
+站点 Fass2_* > 边 Fass2_* > 边通用字段（Speed/Reverse/magSelect）> 系统默认
+**StartStop 决定逻辑**：
+1. 若站点有 Fass2_StartStop → 直接用
+2. 否则若是路径末站且 Fass2_PrecisionStop=true → 22
+3. 否则若是路径末站 → 2
+4. 否则 → 1（过站）
+**Byroad 决定逻辑**：
+1. 站点 Fass2_Byroad
+2. 边 Fass2_Byroad
+3. 边 magSelect
+4. 0
+**fields 变化重发**：任务执行中，若**尚未到达的站点** Fass2_* 签名变化，状态机会从当前站重新 BuildTaskPlan 并分配新 taskId。
站点 fields：**无需配置**（中间站默认 StartStop=1）
+Fass2_StartStop = 2
+
+Fass2_PrecisionStop = true
+或
+
+Fass2_StartStop = 22
+
+Fass2_StartStop = 2
+Fass2_Lift = 1 # 到站升起到位
+离站下一任务可在目标站配 Fass2_Lift = 2 下降，或通过后续路径站点 fields 覆盖。
+Fass2_StartStop = 2
+Fass2_Charge = 2 # 开始充电
+**站点**（推荐在岔口站配）：
+
+Fass2_Byroad = 1 # 选择磁条 1
+或在该站**进入边**上配：
+
+magSelect = 1
+# 或
+Fass2_Byroad = 1
+**站点**：
+
+TagValue = 10086
+**车辆**：
+
+UseTagValueAsNode = true
+**站点 3**（车到 3 后若 tasklist 无匹配，自动去 5）：
+
+goSite = 5
+
+TagValue = 2001
+Fass2_StartStop = 22
+Fass2_Lift = 1
+Fass2_Obstacle = 2
+**配置禁忌（新手易错）**：
+| 错误 | +后果 | +建议 | +
|---|---|---|
中间站误配 StartStop=2 |
+路径中间不必要的停车 | +仅工位/末站停车 | +
Lift=3/4（运动中）作为目标 |
+动作可能永不完成 | +用到位值 1/2 |
+
TagValue 重复 |
+节点映射错乱 | +全图唯一 | +
只配站点不配 UseTagValueAsNode |
+下发节点号仍是 site.id | +成对配置 | +
+1. 车到站 N，LoopMission 检测可用
+2. 匹配 tasklist：currentStationId = N → 分配 targetStationId
+3. 写 tags：goalSite = 目标站 ID
+4. LoopStartAction 调用 GoSite
+5. MagFass2Car 拦截 → 全程任务到 goalSite
+6. 到达后 GoSite 清理 goalSite / occupied / loopAssigned
+7. 下一轮任务匹配
+| 标签 | +含义 | +
|---|---|
goalSite |
+当前要去的目标站 ID | +
loopAssigned |
+分配时间戳 | +
occupied |
+车辆占用中，值如 go5 |
+
LoopMission 逻辑完全沿用磁导航FASS2环线 仅为场景标识，行为与 LoopMission 相同MagFass2Car 且 EnableLoopTaskDrive=true
+EnableLoopTaskDrive = false
+Loop 仍走 Compile 多行 MagFass2Go，每行一段边。
+Idle → Planning → Moving → AtStation → SegmentDone → … → Complete
+ ↓
+ Fault（急停/故障/超时）
+Plan 里min(LockCount, 剩余, 10) 站CurrentIndex++ → 再发下一段示例（15 站路径，LockCount=4）：
+第1次 0xB1：站 1,2,3,4
+到站 1 后： 站 2,3,4,5
+到站 2 后： 站 3,4,5,6
+…直到 goalSite
+若车体需要首帧更多预发，可将 LockCount 调至 **10**（不超过协议上限）。
到站后比对上报 25B 节点与期望：
+| 场景 | +完成条件 | +
|---|---|
| 过站 | +到达节点且非运行态（State≠1） |
+
| 停车 | +StartStop 匹配 |
+
| 顶升/充电等 | +对应字段在状态帧中达标 | +
| 未完成 | +自动补发 0xA1，按 ActionRetryIntervalMs 节流 |
+
| 枚举键 | +含义 | +
|---|---|
TaskPhase |
+任务阶段（Idle/Moving/AtStation/…） | +
TaskGoal |
+目标站 ID | +
TaskIndex |
+当前站点索引 | +
State |
+车体状态文字 | +
CurrentNode |
+当前节点号 | +
Task |
+车体上报的任务号 | +
任务上下文会写入 car.tags（Fass2Task_* 前缀）。重启后 keepAlive 尝试恢复，需等车体再次 UDP 上报后状态机继续推进。
车辆右键方法（界面中）：
+| 方法 | +协议 | +用途 | +
|---|---|---|
| 查询状态 | +0x00 |
+TCP 模式主动查；UDP 模式看缓存 | +
| 启动 | +0x01 |
+启动车体 | +
| 停止 | +0x02 |
+停止 | +
| 急停 | +0x03 |
+急停 | +
| 重置UDP监听 | +— | +重新注册 UDP 会话 | +
| 重置TCP连接 | +— | +关闭长连接（TCP 模式） | +
日志前缀：[MagFass2Car:车名(id)]，任务状态机：task-sm。
| 可能原因 | +处理 | +
|---|---|
| 车体未上报 | +查车体是否发往 ListenPort |
+
VehicleCode 不匹配 |
+对照上报帧 Car 字段 |
+
| 超时 | +调大 UdpOfflineTimeoutMs 或查网络 |
+
| IP/端口错误 | +核对 address、Port |
+
| 可能原因 | +处理 | +
|---|---|
| 未启动 | +确认 StartBeforeMove 或手动点启动 |
+
| 节点号不对 | +检查 UseTagValueAsNode 与 TagValue |
+
| TCP/UDP 模式搞反 | +确认 CommMode |
+
| 状态机 Fault | +看 TaskPhase、TaskFault |
+
| 可能原因 | +处理 | +
|---|---|
| 进程未启动 | +启动 LoopMission / 磁导航FASS2环线 | +
| tasklist 不匹配 | +currentStationId 要等于车所在站 |
+
| 车不可用 | +Commons.SelectCar 条件 |
+
已有 goalSite |
+等上一次完成 | +
| 可能原因 | +处理 | +
|---|---|
| 动作未完成 | +看 Lift/StartStop 等是否与配置一致 |
+
| 状态机 AtStation | +等 0xA1 或检查车体动作 |
+
| 超时 | +调大 MoveTimeoutSeconds |
+
看日志：
+loop goal drive intercept → 全程任务（阶段 4）script begin + 多行 MagFass2Go → 多段脚本EventCarMission **只控制 MagCar**MagCar，FASS 2.0 用 MagFass2Car
+CommMode = Udp
+EnableTaskStateMachine = true
+EnableLoopTaskDrive = true
+LockCount = 4 （车体需更多预发可改 10）
+StartBeforeMove = true
+EnableDetailLog = true
+LogRawFrame = true
+MoveTimeoutSeconds = 120
+StandardScene.Magnetic.dll 已加载MagFass2Car（不是 MagCar）VehicleCode、IP、端口与车体一致0x10 应答TagValue / Fass2_* 已配置tasklist.json 路径正确| 术语 | +解释 | +
|---|---|
0xB1 |
+路径/任务下发命令，最多 10 个站点节点 | +
0xA1 |
+单站点动作下发 | +
0x10 |
+UDP 状态应答（时间戳） | +
goalSite |
+LoopMission 给车分配的目标站标签 | +
LockCount |
+每次下发的滑动窗口站数 | +
TaskBuilder |
+将地图路径+fields 拼成节点序列 | +
状态机 |
+控制规划→下发→到站→推进的自动流程 | +
| PCB/UDP | +车体主动上报，调度被动接收 | +
| PLC/TCP | +调度主动查询车体 | +
| 模块 | +路径 | +
|---|---|
| 车型 | +CarTypes/MagFass2Car.cs |
+
| 协议 | +Protocol/Fass2Protocol.cs、Fass2UdpHub.cs |
+
| 组包 | +Tasking/Fass2TaskBuilder.cs |
+
| 状态机 | +Tasking/Fass2TaskStateMachine.cs |
+
| 动作判定 | +Tasking/Fass2ActionResolver.cs |
+
| 环线 Mission | +Chained/MagFass2LoopMission.cs |
+
| 站点字段常量 | +Tasking/Fass2SiteFields.cs |
+
*文档随代码演进，若参数或行为有变更，以源码为准。*
+ + + \ No newline at end of file diff --git a/StandardScene.Magnetic/docs/MagFass2Car使用指南.md b/StandardScene.Magnetic/docs/MagFass2Car使用指南.md new file mode 100644 index 0000000..308521e --- /dev/null +++ b/StandardScene.Magnetic/docs/MagFass2Car使用指南.md @@ -0,0 +1,1006 @@ +# MagFass2Car（FASS 2.0）使用指南 + +> 适用对象：第一次接触磁导航 + FASS 2.0 的调试/实施人员 +> 插件：`StandardScene.Magnetic.dll` +> 车型：`MagFass2Car` +> 最后更新：2026-07 + +--- + +## 目录 + +1. [这套系统能做什么](#1-这套系统能做什么) +2. [5 分钟快速上手](#2-5-分钟快速上手) +3. [整体架构（新手必读）](#3-整体架构新手必读) +4. [场景与进程配置](#4-场景与进程配置) +5. [车辆参数说明](#5-车辆参数说明) +6. [通讯模式：UDP 与 TCP](#6-通讯模式udp-与-tcp) +7. [三种移动方式对比](#7-三种移动方式对比) +8. [地图配置：站点与路径](#8-地图配置站点与路径) + - [8.1 节点块结构](#81-协议节点块25-字节结构) + - [8.2 站点 fields 详细说明](#82-站点-fields-详细说明) + - [8.3 路径 Track fields 详细说明](#83-路径-track-fields-详细说明) + - [8.4 组包优先级与默认规则](#84-组包优先级与默认规则) + - [8.5 典型场景配置示例](#85-典型场景配置示例) +9. [LoopMission 环线任务](#9-loopmission-环线任务) +10. [任务状态机与协议下发](#10-任务状态机与协议下发) +11. [状态查看与手动操作](#11-状态查看与手动操作) +12. [常见问题排查](#12-常见问题排查) +13. [参数推荐与检查清单](#13-参数推荐与检查清单) +14. [术语表](#14-术语表) + +--- + +## 1. 这套系统能做什么 + +`MagFass2Car` 是 StandardScene **磁导航平台插件**里的 FASS 2.0 车型，主要能力： + +| 能力 | 说明 | +|------|------| +| 路径下发 | 通过 `0xB1` 下发站点序列（每帧最多 10 站） | +| 动作下发 | 通过 `0xA1` 补发站点动作（顶升、充电等） | +| 状态接收 | UDP 模式：车体主动上报 100B，调度回 `0x10` | +| 站点业务 | 从地图 `fields` 读取启停、分叉、顶升等，拼进任务 | +| 环线配合 | 与 Core `LoopMission` 配合，自动跑 `goalSite` | +| 任务闭环 | 状态机判断到站 + 动作是否完成，再发下一段 | + +同一插件内还有 **`MagCar`（FASS 1.0 TCP）**，两者可并存，注意车型和 Mission 不要配混。 + +--- + +## 2. 5 分钟快速上手 + +### 步骤 1：加载插件 + +确认场景已加载 `scene.mag`（`StandardScene.Magnetic.scene.json`），提供： + +- 车型：`MagCar`、`MagFass2Car` +- 进程：`EventCarMission`、`MagFass2LoopMission` + +### 步骤 2：添加一辆车 + +1. 在场景中添加车型 **`MagFass2Car`** +2. 填写基本参数（UDP 模式示例）： + +| 参数 | 示例值 | 含义 | +|------|--------|------| +| `address` | `192.168.1.100` | 车体 IP | +| `Port` | `5000` | 下发命令的目标端口 | +| `ListenPort` | `20103` | 调度监听车体上报的端口 | +| `VehicleCode` | `1` | 车体编号，须与上报帧一致 | +| `CommMode` | `Udp` | PCB/UDP 模式（推荐） | + +### 步骤 3：确认在线 + +- 车体开始 UDP 上报后，车辆状态应显示「上线」 +- `keepAlive` 日志出现 `keepAlive udp ok` +- 枚举里 `Protocol` = `FASS2.0/UDP` + +### 步骤 4：手动走一步（验证通讯） + +在车辆方法里点 **「查询状态」**，再点 **「启动」**，确认有日志且无报错。 + +### 步骤 5：跑一段路径 + +**方式 A — 手动 Go（Web/调度下发）** +用系统自带的「去某站」功能，内部会编译脚本，例如： + +```text +agv.MagFass2Go(1, 2, 0.2); +agv.MagFass2Go(2, 5, 0.2); +``` + +**方式 B — LoopMission 环线** +1. 添加 **`LoopMission`** 或 **`磁导航FASS2环线`** +2. 配置 `tasklist.json` +3. 启动进程 +4. 车到站后自动分配 `goalSite` 并导航 + +--- + +## 3. 整体架构（新手必读） + +```text +┌─────────────────────────────────────────────────────────┐ +│ 业务层：LoopMission / 手动 Go / 脚本 │ +│ （分配 goalSite 或编译多行 MagFass2Go） │ +└────────────────────────┬────────────────────────────────┘ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ MagFass2Car 执行层 │ +│ · 脚本拦截（Loop + goalSite）→ 一次全程任务 │ +│ · Fass2TaskBuilder：路径 + fields → 节点序列 │ +│ · Fass2TaskStateMachine：滑动窗口下发 + 动作闭环 │ +└────────────────────────┬────────────────────────────────┘ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ 协议层：Fass2Protocol + Fass2UdpHub │ +│ · 收 100B 状态 → 回 0x10 │ +│ · 发 0x01/0xB1/0xA1 到 address:Port │ +└────────────────────────┬────────────────────────────────┘ + ▼ + AGV 车体 +``` + +**关键理解：** + +- **LoopMission（Core）** 只负责「给谁分配哪个目标站」（写 `goalSite` 标签） +- **MagFass2Car** 负责「怎么走过去」（拼包、下发、等到站） +- **阶段 4** 后，Loop 不再逐行执行多段脚本，而是**拦截为一次全程任务**（可关） + +--- + +## 4. 场景与进程配置 + +### 4.1 插件清单 + +文件：`StandardScene.Magnetic.scene.json` + +```json +{ + "carTypes": [ "MagCar", "MagFass2Car" ], + "missionTypes": [ "EventCarMission", "MagFass2LoopMission" ] +} +``` + +### 4.2 选哪个 Mission？ + +| Mission | 来源 | 适用 | +|---------|------|------| +| `LoopMission` | Core | 通用环线，MagFass2Car 同样可用 | +| `磁导航FASS2环线`（`MagFass2LoopMission`） | Magnetic 插件 | 逻辑与 LoopMission 相同，名称标识磁导航 FASS2 场景 | +| `FASS车辆事件进程`（`EventCarMission`） | Magnetic 插件 | **仅 MagCar（FASS 1.0）**，不驱动 MagFass2Car | + +> 新手建议：MagFass2Car 环线用 **`LoopMission`** 或 **`磁导航FASS2环线`** 均可。 + +### 4.3 tasklist.json 最小示例 + +```json +{ + "tasks": [ + { + "id": "loop-1-2", + "startType": "AutoLoop", + "kind": "Loop", + "currentStationId": 1, + "targetStationId": 2, + "priority": 1, + "trafficControl": 2 + }, + { + "id": "loop-2-1", + "startType": "AutoLoop", + "kind": "Loop", + "currentStationId": 2, + "targetStationId": 1, + "priority": 1, + "trafficControl": 2 + } + ] +} +``` + +含义：车到站 1 → 自动分配目标站 2；到站 2 → 自动分配目标站 1，形成环线。 + +--- + +## 5. 车辆参数说明 + +在场景编辑器中选中 `MagFass2Car`，常用字段如下。 + +### 5.1 通讯 + +| 字段 | 默认 | 说明 | +|------|------|------| +| `CommMode` | `Udp` | `Udp`=PCB 被动收状态；`Tcp`=PLC 主动查询 | +| `address` | — | 车体 IP | +| `Port` | `5000` | 命令下发端口 | +| `ListenPort` | `20103` | 调度 UDP 监听端口 | +| `VehicleCode` | `0` | 必须与车体上报的 `Car` 字段一致 | +| `UdpOfflineTimeoutMs` | `15000` | 超过此时间未收到上报视为离线 | + +### 5.2 任务与状态机 + +| 字段 | 默认 | 说明 | +|------|------|------| +| `EnableTaskStateMachine` | `true` | 开启任务状态机（推荐） | +| `EnableLoopTaskDrive` | `true` | Loop 场景拦截多段脚本，改全程任务 | +| `LockCount` | `4` | 每次 `0xB1` 滑动窗口站数（≤10） | +| `TaskResendIntervalMs` | `500` | 周期重发 `0xB1` 间隔 | +| `ActionRetryIntervalMs` | `1000` | 动作未完成时 `0xA1` 重试间隔 | +| `MoveTimeoutSeconds` | `120` | 单次移动超时（秒） | +| `StartBeforeMove` | `true` | 移动前发 `0x01` 启动 | + +### 5.3 地图节点映射 + +| 字段 | 默认 | 说明 | +|------|------|------| +| `UseTagValueAsNode` | `false` | `true` 时用站点 `TagValue` 作为协议 `Node` 号 | + +### 5.4 调试 + +| 字段 | 默认 | 说明 | +|------|------|------| +| `EnableDetailLog` | `true` | 详细日志 | +| `LogRawFrame` | `true` | 打印收发十六进制 | + +--- + +## 6. 通讯模式：UDP 与 TCP + +### 6.1 UDP/PCB（推荐，现场 FASS 2.0 新车默认） + +```text +车体 ──UDP──► 调度 ListenPort（100B 状态） +调度 ──UDP──► 车体 address:Port（0x10 应答） +调度 ──UDP──► 车体 address:Port（0xB1/0xA1/0x01，独立发送） +``` + +特点： + +- 调度**不主动轮询**，靠车体上报驱动状态机 +- 每收到一帧状态，**必须回 `0x10`**（已由 `Fass2UdpHub` 自动处理） +- 下发命令**不等待同步应答**（异步） + +### 6.2 TCP/PLC（调试/兼容） + +- 调度主动发 `0x00` 查询，同步收 100B +- 适合仿真器或无 UDP 上报的环境 +- 设置 `CommMode = Tcp`，配置 `ConnectTimeoutMs` 等 + +### 6.3 端口核对清单 + +| 检查项 | 操作 | +|--------|------| +| 车体上报发到哪 | 确认发往调度机 `ListenPort` | +| 调度命令发到哪 | 确认 `address:Port` 与车体监听一致 | +| 编号一致 | `VehicleCode` = 上报帧内 `Car` 字段 | +| 防火墙 | 放行 UDP 双向 | + +--- + +## 7. 三种移动方式对比 + +### 方式 1：多段脚本（传统） + +**触发**：手动 Go、`EnableLoopTaskDrive=false` 时的 Loop、任意编译脚本。 + +**流程**： + +```text +FindRoute → Compile → 多行脚本： + agv.MagFass2Go(1,2,speed); + agv.MagFass2Go(2,3,speed); + ... +→ SelfEvaluating 逐行执行 +→ 每行：锁终点 → 发 0xB1 → 等到站 → 释放起点 +``` + +**特点**：每**条边**一段任务，多次 `taskId`，与交管「逐段锁点」一致。 + +--- + +### 方式 2：Loop 全程任务（阶段 4，默认） + +**触发**：`goalSite` 标签 + 编译脚本含 `MagFass2Go` + `EnableLoopTaskDrive=true`。 + +**流程**： + +```text +LoopMission 写 goalSite +→ GoSite 仍 Compile 多行脚本（Core 不变） +→ actualSendScript 拦截，不逐行执行 +→ ExecuteGoalTaskAsync(当前站 → goalSite) +→ 状态机一次规划全程，滑动窗口发 0xB1 +``` + +**特点**：业务上一次任务，协议上仍遵守每帧 ≤10 站。 + +--- + +### 方式 3：单段 MagFass2Go（脚本一行） + +**触发**：脚本里只有一行，或无 `goalSite` 的测试。 + +**流程**：与方式 1 的单行相同，状态机只跑 `src → dst` 一段。 + +--- + +### 对比表 + +| 维度 | 多段脚本 | Loop 全程任务 | +|------|----------|---------------| +| 规划范围 | 每条边 | 当前站 → goalSite | +| taskId | 每段一个 | 全程一个 | +| 交通锁 | 每段锁终点 | 只锁 goalSite | +| 适用 | 手动调试、兼容旧逻辑 | 环线自动跑 | +| 开关 | `EnableLoopTaskDrive=false` | `EnableLoopTaskDrive=true`（默认） | + +--- + +## 8. 地图配置：站点与路径 + +任务组包时，调度读取地图中站点（Site）和路径（Track）的 `fields` 键值，合并写入 FASS 2.0 的 `0xB1` 节点块（每站 25 字节）。 + +**配置位置**：地图编辑器 → 选中站点或路径 → 属性/fields 面板 → 添加键值对。 + +**命名约定**： + +- 业务动作字段统一以 `Fass2_` 开头（代码常量见 `Fass2SiteFields.cs`） +- 值为**十进制整数**字符串，例如 `Fass2_Lift` = `1` +- 布尔字段写 `true` / `false` 或 `1` / `0` + +--- + +### 8.1 协议节点块（25 字节结构） + +每个站点在 `0xB1` 中对应一个节点，主要字段如下（与 `Fass2NodeMessage` 一致）： + +| 偏移 | 字段 | 类型 | 来源 | +|------|------|------|------| +| 0–1 | `Node` | ushort | 站点 `TagValue` 或 `site.id` | +| 2–3 | `Distance` | ushort | 上一站到本站的边长（mm 量级） | +| 4 | `StartStop` | byte | 站点 `Fass2_StartStop` / 默认规则 | +| 5 | `Direction` | byte | 站点或边 fields | +| 6 | `Orientation` | byte | 边朝向计算或站点覆盖 | +| 7 | `Byroad` | byte | 分叉选择，站点或边 | +| 8–9 | `Speed` | ushort | 边 `Speed` 换算（0.1 m/min 单位） | +| 10 | `Obstacle` | byte | 站点 | +| 11 | `Audio` | byte | 站点 | +| 12 | `Light` | byte | 站点 | +| 13 | `Charge` | byte | 站点 | +| 14 | `Rest` | byte | 站点 | +| 15 | `Lift` | byte | 站点 | +| 16 | `Clamp` | byte | 站点 | +| 17 | `Tray` | byte | 站点 | +| 18 | `Roll` | byte | 站点 | +| 19 | `Shutdown` | byte | 站点 | + +状态机到站后，会比对车体上报状态帧中**同一节点块**的字段是否达到期望值；未达标则补发 `0xA1`。 + +--- + +### 8.2 站点 fields 详细说明 + +#### 8.2.1 节点与调度类 + +##### `TagValue`（int，可选） + +| 项目 | 说明 | +|------|------| +| 映射协议字段 | `Node`（节点号） | +| 何时配置 | 磁导航地标号与地图 `site.id` **不一致**时必须配置 | +| 车辆开关 | `MagFass2Car.UseTagValueAsNode = true` | +| 示例 | `TagValue = 10086` | +| 注意 | 未配置且 `UseTagValueAsNode=false` 时，直接用 `site.id` 作为节点号 | + +##### `goSite`（int，可选） + +| 项目 | 说明 | +|------|------| +| 映射协议字段 | 无（不参与 0xB1 组包） | +| 用途 | LoopMission 在该站无任务匹配时，读取此字段作为默认下一目标 | +| 读取方 | Core `AbstractLoopMission.LoopStartAction` | +| 示例 | 站 3 配 `goSite = 5`，车到站 3 且无 tasklist 匹配时，自动写 `goalSite=5` | + +##### `Fass2_WaitMode`（string，预留） + +| 项目 | 说明 | +|------|------| +| 映射协议字段 | 无（当前版本不直接写入节点块） | +| 规划值 | `None` / `Button` / `Plc` / `Api` | +| 当前状态 | 字段已定义，**等待放行联动逻辑待扩展**；可通过修改 `Fass2_StartStop` 或外部改 fields 触发重发 | + +--- + +#### 8.2.2 `Fass2_StartStop` — 启停模式（byte） + +映射协议字段：`StartStop`（节点块第 5 字节） + +| 值 | 含义（对齐 FASS 2.0 字典） | 典型场景 | +|----|---------------------------|----------| +| `1` | 过站（不停） | 路径中间站、通道站 | +| `2` | 普通停车 | 工位、等待点、装卸点 | +| `11` | 管控启动 | 管控区入口，需授权后启动 | +| `12` | 管控停止 | 管控区停车等待 | +| `22` | 精准停止 | 装配、对接，精度要求高 | + +**默认规则**（未显式配置 `Fass2_StartStop` 时，`Fass2TaskBuilder` 自动决定）： + +| 站点位置 | 默认 `StartStop` | +|----------|------------------| +| 中间站 | `1`（过站） | +| 末站（goalSite） | `2`（停车） | +| 末站 + `Fass2_PrecisionStop=true` | `22`（精准停） | + +**动作完成判定**：若配置了非过站值，状态机要求上报 `Node.StartStop` 与期望值一致，且车体非运行态（`State≠1`），才推进下一段。 + +**与 `Fass2_PrecisionStop` 关系**： + +- 可直接写 `Fass2_StartStop = 22` +- 或末站写 `Fass2_PrecisionStop = true`，由组包器自动设为 `22` + +--- + +#### 8.2.3 `Fass2_PrecisionStop` — 精准停（bool） + +| 项目 | 说明 | +|------|------| +| 类型 | `true` / `false` / `1` / `0` | +| 效果 | 仅对**路径末站**生效，等价于 `StartStop = 22` | +| 优先级 | 低于显式 `Fass2_StartStop`（若同时配置，以 `Fass2_StartStop` 为准） | +| 示例 | 装配工位末站：`Fass2_PrecisionStop = true` | + +--- + +#### 8.2.4 `Fass2_Byroad` — 分叉选择（byte） + +映射协议字段：`Byroad` + +| 项目 | 说明 | +|------|------| +| 取值范围 | 通常 `0`–`3`，表示磁分叉/岔路选择序号 | +| 站点 vs 边 | 站点显式配置优先；未配置时继承**进入该站的边** `Fass2_Byroad` 或 `magSelect` | +| 典型场景 | Y 型路口、多磁条岔口 | +| 完成判定 | 若期望值非 0，上报 `Node.Byroad` 须一致 | + +--- + +#### 8.2.5 `Fass2_Direction` — 车头旋转（byte） + +映射协议字段：`Direction` + +| 项目 | 说明 | +|------|------| +| 含义 | 到站后车头旋转指令（具体角度定义以车体协议为准） | +| 站点 vs 边 | 站点配置覆盖边配置 | +| 完成判定 | 上报 `Node.Direction` 与期望值一致 | + +--- + +#### 8.2.6 `Fass2_Orientation` — 行驶朝向（byte） + +映射协议字段：`Orientation` + +| 项目 | 说明 | +|------|------| +| 含义 | 进出该站时的前进/后退/横移朝向（0–255，对应 0°–360° 量化） | +| 默认 | 由边几何计算：`atan2(Δy, Δx)` + `Reverse` + `CarDirectionBias` | +| 覆盖 | 站点或边显式配置 `Fass2_Orientation` 时直接使用 | +| 完成判定 | 非 0 期望值时须上报一致 | + +--- + +#### 8.2.7 `Fass2_Lift` — 顶升/举升（byte） + +映射协议字段：`Lift` + +| 值 | 含义（对齐 backend 字典） | +|----|--------------------------| +| `1` | 上升到位 | +| `2` | 下降到位 | +| `3` | 上升中 | +| `4` | 下降中 | + +| 项目 | 说明 | +|------|------| +| 典型场景 | 顶升搬运、装卸高度切换 | +| 配置建议 | 工位停车（`StartStop=2`）+ `Fass2_Lift=1` 或 `2` | +| 完成判定 | 上报 `Node.Lift` 等于配置值；未完成自动 `0xA1` 补发 | +| 注意 | 一般配**到位值**（1/2），不要配中间态（3/4）除非明确需要 | + +--- + +#### 8.2.8 `Fass2_Roll` — 滚筒（byte） + +映射协议字段：`Roll` + +| 项目 | 说明 | +|------|------| +| 用途 | 滚筒输送启停/方向 | +| 取值 | 以现场车体协议为准（写入节点块第 19 字节） | +| 完成判定 | 期望值非 0 时须上报一致 | + +--- + +#### 8.2.9 `Fass2_Charge` — 充电（byte） + +映射协议字段：`Charge` + +| 值 | 含义 | +|----|------| +| `1` | 停止充电 | +| `2` | 开始充电 | + +| 项目 | 说明 | +|------|------| +| 典型场景 | 充电站、`LoopMission` 充电触发任务 | +| 配置建议 | 充电工位：`Fass2_StartStop=2` + `Fass2_Charge=2` | +| 离站 | 下一任务或离站前可配 `Fass2_Charge=1` | + +--- + +#### 8.2.10 `Fass2_Rest` — 休眠（byte） + +映射协议字段：`Rest` + +| 值 | 含义 | +|----|------| +| `1` | 停止睡眠 | +| `2` | 开始睡眠 | + +| 项目 | 说明 | +|------|------| +| 典型场景 | 长时间待机工位、低功耗停车区 | + +--- + +#### 8.2.11 `Fass2_Obstacle` — 避障区（byte） + +映射协议字段：`Obstacle` + +| 项目 | 说明 | +|------|------| +| 用途 | 切换车体避障区域/模式 | +| 取值 | 以车体协议定义为准（区域编号） | +| 典型场景 | 进入狭窄通道、人机混行区 | + +--- + +#### 8.2.12 `Fass2_Audio` / `Fass2_Light` — 声光（byte） + +| 字段 | 协议字段 | 用途 | +|------|----------|------| +| `Fass2_Audio` | `Audio` | 提示音、播报 | +| `Fass2_Light` | `Light` | 警示灯、状态灯 | + +取值以车体协议为准，一般为模式/曲目/灯色编号。 + +--- + +#### 8.2.13 `Fass2_Clamp` — 夹抱（byte） + +映射协议字段：`Clamp` + +| 项目 | 说明 | +|------|------| +| 用途 | 夹紧/松开机构 | +| 典型场景 | 夹抱式 AGV、治具锁紧 | + +--- + +#### 8.2.14 `Fass2_Tray` — 托盘（byte） + +映射协议字段：`Tray` + +| 项目 | 说明 | +|------|------| +| 用途 | 托盘旋转/伸缩等机构 | +| 典型场景 | 多工位转台、托盘调角 | + +--- + +#### 8.2.15 `Fass2_Shutdown` — 关机（byte） + +映射协议字段：`Shutdown` + +| 项目 | 说明 | +|------|------| +| 用途 | 到站后车体软关机/深度待机 | +| 注意 | 与全局 `0x06` 关机指令不同；此为**任务节点内**动作 | +| 风险 | 配置后车体可能下线，需人工或远程重启 | + +--- + +#### 8.2.16 站点 fields 速查总表 + +| 字段键 | 类型 | 协议字段 | 是否参与动作闭环 | +|--------|------|----------|------------------| +| `TagValue` | int | `Node` | 否（仅节点映射） | +| `goSite` | int | — | 否（Loop 调度用） | +| `Fass2_StartStop` | byte | `StartStop` | 是 | +| `Fass2_PrecisionStop` | bool | `StartStop`→22 | 是 | +| `Fass2_Byroad` | byte | `Byroad` | 是（非 0 时） | +| `Fass2_Direction` | byte | `Direction` | 是（非 0 时） | +| `Fass2_Orientation` | byte | `Orientation` | 是（非 0 时） | +| `Fass2_Lift` | byte | `Lift` | 是（非 0 时） | +| `Fass2_Roll` | byte | `Roll` | 是（非 0 时） | +| `Fass2_Charge` | byte | `Charge` | 是（非 0 时） | +| `Fass2_Obstacle` | byte | `Obstacle` | 是（非 0 时） | +| `Fass2_Audio` | byte | `Audio` | 是（非 0 时） | +| `Fass2_Light` | byte | `Light` | 是（非 0 时） | +| `Fass2_Rest` | byte | `Rest` | 是（非 0 时） | +| `Fass2_Clamp` | byte | `Clamp` | 是（非 0 时） | +| `Fass2_Tray` | byte | `Tray` | 是（非 0 时） | +| `Fass2_Shutdown` | byte | `Shutdown` | 是（非 0 时） | +| `Fass2_WaitMode` | string | — | 预留 | + +--- + +### 8.3 路径 Track fields 详细说明 + +路径 fields 主要影响**进入该站的那段边**（距离、速度、朝向、分叉）。 + +| 字段键 | 类型 | 映射 | 详细说明 | +|--------|------|------|----------| +| `Speed` | float | `Speed` | 边速度。`≤1` 按 **m/s**（协议值 = speed×600）；`>1` 按 **m/min**（协议值 = speed×10）。未配置默认 0.2 m/s | +| `Reverse` | bool | `Orientation` | `true` 时朝向 +180° | +| `CarDirectionBias` | float | `Orientation` | 朝向偏置（度），叠加到几何朝向 | +| `EnableCarAbsoluteDirection` | bool | `Orientation` | `true` 时用 `CarAbsoluteDirection` 代替几何计算 | +| `CarAbsoluteDirection` | float | `Orientation` | 绝对朝向（度，0–360） | +| `Fass2_Byroad` | byte | `Byroad` | 边级分叉；站点未配 `Fass2_Byroad` 时生效 | +| `magSelect` | byte | `Byroad` | 磁导航 coder 分叉序号；`Fass2_Byroad` 为空时作为 Byroad 备选 | +| `Fass2_Direction` | byte | `Direction` | 边级车头旋转；站点未覆盖时生效 | +| `Fass2_Orientation` | byte | `Orientation` | 边级朝向；站点未覆盖时生效 | +| `Magnet` | bool | — | `true` 启用 `MagneticTrackCoder`（`agv.MagGo` 等），与 `MagFass2Go` 模板独立 | +| `ReverseDst` | int | — | 倒车目的地站 ID；磁 coder 跳过该边 | + +**距离 `Distance`**：由地图坐标自动计算（上一站与本站欧氏距离，mm 取整），一般无需手配。 + +--- + +### 8.4 组包优先级与默认规则 + +当同一协议字段在站点和边都有配置时： + +```text +站点 Fass2_* > 边 Fass2_* > 边通用字段（Speed/Reverse/magSelect）> 系统默认 +``` + +**`StartStop` 决定逻辑**： + +```text +1. 若站点有 Fass2_StartStop → 直接用 +2. 否则若是路径末站且 Fass2_PrecisionStop=true → 22 +3. 否则若是路径末站 → 2 +4. 否则 → 1（过站） +``` + +**`Byroad` 决定逻辑**： + +```text +1. 站点 Fass2_Byroad +2. 边 Fass2_Byroad +3. 边 magSelect +4. 0 +``` + +**fields 变化重发**：任务执行中，若**尚未到达的站点** `Fass2_*` 签名变化，状态机会从当前站重新 `BuildTaskPlan` 并分配新 `taskId`。 + +--- + +### 8.5 典型场景配置示例 + +#### 场景 A：通道过站（无动作） + +站点 fields：**无需配置**（中间站默认 `StartStop=1`） + +--- + +#### 场景 B：普通停车工位 + +```text +Fass2_StartStop = 2 +``` + +--- + +#### 场景 C：精准对接工位（末站） + +```text +Fass2_PrecisionStop = true +``` +或 +```text +Fass2_StartStop = 22 +``` + +--- + +#### 场景 D：顶升装卸工位 + +```text +Fass2_StartStop = 2 +Fass2_Lift = 1 # 到站升起到位 +``` + +离站下一任务可在目标站配 `Fass2_Lift = 2` 下降，或通过后续路径站点 fields 覆盖。 + +--- + +#### 场景 E：充电工位 + +```text +Fass2_StartStop = 2 +Fass2_Charge = 2 # 开始充电 +``` + +--- + +#### 场景 F：Y 型磁分叉口 + +**站点**（推荐在岔口站配）： + +```text +Fass2_Byroad = 1 # 选择磁条 1 +``` + +或在该站**进入边**上配： + +```text +magSelect = 1 +# 或 +Fass2_Byroad = 1 +``` + +--- + +#### 场景 G：磁地标与站 ID 不同 + +**站点**： + +```text +TagValue = 10086 +``` + +**车辆**： + +```text +UseTagValueAsNode = true +``` + +--- + +#### 场景 H：Loop 默认下一跳 + +**站点 3**（车到 3 后若 tasklist 无匹配，自动去 5）： + +```text +goSite = 5 +``` + +--- + +#### 场景 I：完整工位（停车 + 顶升 + 精准） + +```text +TagValue = 2001 +Fass2_StartStop = 22 +Fass2_Lift = 1 +Fass2_Obstacle = 2 +``` + +--- + +**配置禁忌（新手易错）**： + +| 错误 | 后果 | 建议 | +|------|------|------| +| 中间站误配 `StartStop=2` | 路径中间不必要的停车 | 仅工位/末站停车 | +| `Lift=3/4`（运动中）作为目标 | 动作可能永不完成 | 用到位值 `1`/`2` | +| `TagValue` 重复 | 节点映射错乱 | 全图唯一 | +| 只配站点不配 `UseTagValueAsNode` | 下发节点号仍是 site.id | 成对配置 | + +--- + +## 9. LoopMission 环线任务 + +### 9.1 运行流程 + +```text +1. 车到站 N，LoopMission 检测可用 +2. 匹配 tasklist：currentStationId = N → 分配 targetStationId +3. 写 tags：goalSite = 目标站 ID +4. LoopStartAction 调用 GoSite +5. MagFass2Car 拦截 → 全程任务到 goalSite +6. 到达后 GoSite 清理 goalSite / occupied / loopAssigned +7. 下一轮任务匹配 +``` + +### 9.2 相关 tags + +| 标签 | 含义 | +|------|------| +| `goalSite` | 当前要去的目标站 ID | +| `loopAssigned` | 分配时间戳 | +| `occupied` | 车辆占用中，值如 `go5` | + +### 9.3 与 Core 的关系 + +- **不需要改 Core**；`LoopMission` 逻辑完全沿用 +- `磁导航FASS2环线` 仅为场景标识，行为与 `LoopMission` 相同 +- 真正区别在 **车型** 是否 `MagFass2Car` 且 `EnableLoopTaskDrive=true` + +### 9.4 关闭 Loop 拦截（恢复多段脚本） + +``` +EnableLoopTaskDrive = false +``` + +Loop 仍走 Compile 多行 `MagFass2Go`，每行一段边。 + +--- + +## 10. 任务状态机与协议下发 + +### 10.1 状态流转 + +```text +Idle → Planning → Moving → AtStation → SegmentDone → … → Complete + ↓ + Fault（急停/故障/超时） +``` + +### 10.2 单帧最多 10 站 — 不冲突 + +- **规划**：全程可能有 20+ 站，存在内存 `Plan` 里 +- **下发**：每次只发滑动窗口 `min(LockCount, 剩余, 10)` 站 +- **推进**：当前站动作完成 → `CurrentIndex++` → 再发下一段 +- **同一 taskId**：全程复用，周期重发当前窗口 + +示例（15 站路径，`LockCount=4`）： + +```text +第1次 0xB1：站 1,2,3,4 +到站 1 后： 站 2,3,4,5 +到站 2 后： 站 3,4,5,6 +…直到 goalSite +``` + +若车体需要首帧更多预发，可将 `LockCount` 调至 **10**（不超过协议上限）。 + +### 10.3 动作闭环 + +到站后比对上报 25B 节点与期望： + +| 场景 | 完成条件 | +|------|----------| +| 过站 | 到达节点且非运行态（`State≠1`） | +| 停车 | `StartStop` 匹配 | +| 顶升/充电等 | 对应字段在状态帧中达标 | +| 未完成 | 自动补发 `0xA1`，按 `ActionRetryIntervalMs` 节流 | + +### 10.4 车辆状态枚举（调试看） + +| 枚举键 | 含义 | +|--------|------| +| `TaskPhase` | 任务阶段（Idle/Moving/AtStation/…） | +| `TaskGoal` | 目标站 ID | +| `TaskIndex` | 当前站点索引 | +| `State` | 车体状态文字 | +| `CurrentNode` | 当前节点号 | +| `Task` | 车体上报的任务号 | + +### 10.5 重启恢复（可选） + +任务上下文会写入 `car.tags`（`Fass2Task_*` 前缀）。重启后 `keepAlive` 尝试恢复，需等车体再次 UDP 上报后状态机继续推进。 + +--- + +## 11. 状态查看与手动操作 + +车辆右键方法（界面中）： + +| 方法 | 协议 | 用途 | +|------|------|------| +| 查询状态 | `0x00` | TCP 模式主动查；UDP 模式看缓存 | +| 启动 | `0x01` | 启动车体 | +| 停止 | `0x02` | 停止 | +| 急停 | `0x03` | 急停 | +| 重置UDP监听 | — | 重新注册 UDP 会话 | +| 重置TCP连接 | — | 关闭长连接（TCP 模式） | + +日志前缀：`[MagFass2Car:车名(id)]`，任务状态机：`task-sm`。 + +--- + +## 12. 常见问题排查 + +### Q1：车显示离线（UDP） + +| 可能原因 | 处理 | +|----------|------| +| 车体未上报 | 查车体是否发往 `ListenPort` | +| `VehicleCode` 不匹配 | 对照上报帧 `Car` 字段 | +| 超时 | 调大 `UdpOfflineTimeoutMs` 或查网络 | +| IP/端口错误 | 核对 `address`、`Port` | + +### Q2：发了 0xB1 车不动 + +| 可能原因 | 处理 | +|----------|------| +| 未启动 | 确认 `StartBeforeMove` 或手动点启动 | +| 节点号不对 | 检查 `UseTagValueAsNode` 与 `TagValue` | +| TCP/UDP 模式搞反 | 确认 `CommMode` | +| 状态机 Fault | 看 `TaskPhase`、`TaskFault` | + +### Q3：Loop 不分配任务 + +| 可能原因 | 处理 | +|----------|------| +| 进程未启动 | 启动 LoopMission / 磁导航FASS2环线 | +| tasklist 不匹配 | `currentStationId` 要等于车所在站 | +| 车不可用 | `Commons.SelectCar` 条件 | +| 已有 `goalSite` | 等上一次完成 | + +### Q4：到站但不继续 + +| 可能原因 | 处理 | +|----------|------| +| 动作未完成 | 看 `Lift`/`StartStop` 等是否与配置一致 | +| 状态机 AtStation | 等 `0xA1` 或检查车体动作 | +| 超时 | 调大 `MoveTimeoutSeconds` | + +### Q5：Loop 和多段脚本哪个在生效？ + +看日志： + +- `loop goal drive intercept` → 全程任务（阶段 4） +- `script begin` + 多行 `MagFass2Go` → 多段脚本 + +### Q6：与 MagCar 混用注意事项 + +- `EventCarMission` **只控制 MagCar** +- 同场景两种车型时，tasklist 和车辆类型要对应 +- FASS 1.0 用 `MagCar`，FASS 2.0 用 `MagFass2Car` + +--- + +## 13. 参数推荐与检查清单 + +### 13.1 首次联调推荐配置 + +```text +CommMode = Udp +EnableTaskStateMachine = true +EnableLoopTaskDrive = true +LockCount = 4 （车体需更多预发可改 10） +StartBeforeMove = true +EnableDetailLog = true +LogRawFrame = true +MoveTimeoutSeconds = 120 +``` + +### 13.2 上线前检查清单 + +- [ ] 插件 `StandardScene.Magnetic.dll` 已加载 +- [ ] 车型为 `MagFass2Car`（不是 `MagCar`） +- [ ] `VehicleCode`、IP、端口与车体一致 +- [ ] UDP 能收到 100B，日志有 `0x10` 应答 +- [ ] 关键站点 `TagValue` / `Fass2_*` 已配置 +- [ ] LoopMission 已启动，`tasklist.json` 路径正确 +- [ ] 单车手动 Go 一站成功后再开环线 + +--- + +## 14. 术语表 + +| 术语 | 解释 | +|------|------| +| `0xB1` | 路径/任务下发命令，最多 10 个站点节点 | +| `0xA1` | 单站点动作下发 | +| `0x10` | UDP 状态应答（时间戳） | +| `goalSite` | LoopMission 给车分配的目标站标签 | +| `LockCount` | 每次下发的滑动窗口站数 | +| `TaskBuilder` | 将地图路径+fields 拼成节点序列 | +| `状态机` | 控制规划→下发→到站→推进的自动流程 | +| PCB/UDP | 车体主动上报，调度被动接收 | +| PLC/TCP | 调度主动查询车体 | + +--- + +## 附录：相关源码路径 + +| 模块 | 路径 | +|------|------| +| 车型 | `CarTypes/MagFass2Car.cs` | +| 协议 | `Protocol/Fass2Protocol.cs`、`Fass2UdpHub.cs` | +| 组包 | `Tasking/Fass2TaskBuilder.cs` | +| 状态机 | `Tasking/Fass2TaskStateMachine.cs` | +| 动作判定 | `Tasking/Fass2ActionResolver.cs` | +| 环线 Mission | `Chained/MagFass2LoopMission.cs` | +| 站点字段常量 | `Tasking/Fass2SiteFields.cs` | + +--- + +*文档随代码演进，若参数或行为有变更，以源码为准。* diff --git a/StandardScene.Magnetic/docs/MagFass2Car使用指南.pdf b/StandardScene.Magnetic/docs/MagFass2Car使用指南.pdf new file mode 100644 index 0000000000000000000000000000000000000000..aeec0adaea6762adc7ee244ba884339ad94a5689 GIT binary patch literal 1025376 zcma&N1CT92(