Mag2Car（FASS 2.0）使用指南

适用对象：第一次接触磁导航 + FASS 2.0 的调试/实施人员

插件：`StandardScene.Magnetic.dll`

车型：`Mag2Car`

最后更新：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-典型场景配置示例)

1. [LoopMission 环线任务](#9-loopmission-环线任务)
2. [任务状态机与协议下发](#10-任务状态机与协议下发)
3. [状态查看与手动操作](#11-状态查看与手动操作)
4. [常见问题排查](#12-常见问题排查)
5. [参数推荐与检查清单](#13-参数推荐与检查清单)
6. [术语表](#14-术语表)

1. 这套系统能做什么

Mag2Car 是 StandardScene **磁导航平台插件**里的 FASS 2.0 车型，主要能力：

同一插件内还有 **MagCar（FASS 1.0 TCP）**，两者可并存，注意车型和 Mission 不要配混。

2. 5 分钟快速上手

步骤 1：加载插件

确认场景已加载 scene.mag（StandardScene.Magnetic.scene.json），提供：

• 车型：MagCar、Mag2Car
• 进程：EventCarMission、Mag2LoopMission

步骤 2：添加一辆车

1. 在场景中添加车型 **Mag2Car**
2. 填写基本参数（UDP 模式示例）：

步骤 3：确认在线

• 车体开始 UDP 上报后，车辆状态应显示「上线」
• keepAlive 日志出现 keepAlive udp ok
• 枚举里 Protocol = FASS2.0/UDP

步骤 4：手动走一步（验证通讯）

在车辆方法里点 **「查询状态」**，再点 **「启动」**，确认有日志且无报错。

步骤 5：跑一段路径

**方式 A — 手动 Go（Web/调度下发）**

用系统自带的「去某站」功能，内部会编译脚本，例如：

agv.Mag2Go(1, 2, 0.2);
agv.Mag2Go(2, 5, 0.2);

**方式 B — LoopMission 环线**

1. 添加 **LoopMission** 或 **磁导航FASS2环线**
2. 配置 tasklist.json
3. 启动进程
4. 车到站后自动分配 goalSite 并导航

3. 整体架构（新手必读）

┌─────────────────────────────────────────────────────────┐
│  业务层：LoopMission / 手动 Go / 脚本                    │
│  （分配 goalSite 或编译多行 Mag2Go）                  │
└────────────────────────┬────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Mag2Car 执行层                                      │
│  · 脚本拦截（Loop + goalSite）→ 一次全程任务              │
│  · Fass2TaskBuilder：路径 + fields → 节点序列             │
│  · Fass2TaskStateMachine：滑动窗口下发 + 动作闭环         │
└────────────────────────┬────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────┐
│  协议层：Fass2Protocol + Fass2UdpHub                     │
│  · 收 100B 状态 → 回 0x10                                │
│  · 发 0x01/0xB1/0xA1 到 address:Port                    │
└────────────────────────┬────────────────────────────────┘
                         ▼
                    AGV 车体

**关键理解：**

• **LoopMission（Core）** 只负责「给谁分配哪个目标站」（写 goalSite 标签）
• **Mag2Car** 负责「怎么走过去」（拼包、下发、等到站）
• **阶段 4** 后，Loop 不再逐行执行多段脚本，而是**拦截为一次全程任务**（可关）

4. 场景与进程配置

4.1 插件清单

文件：StandardScene.Magnetic.scene.json

{
  "carTypes": [ "MagCar", "Mag2Car" ],
  "missionTypes": [ "EventCarMission", "Mag2LoopMission" ]
}

4.2 选哪个 Mission？

新手建议：Mag2Car 环线用 **`LoopMission`** 或 **`磁导航FASS2环线`** 均可。

4.3 tasklist.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. 车辆参数说明

在场景编辑器中选中 Mag2Car，常用字段如下。

5.1 通讯

5.2 任务与状态机

5.3 地图节点映射

5.4 调试

6. 通讯模式：UDP 与 TCP

6.1 UDP/PCB（推荐，现场 FASS 2.0 新车默认）

车体 ──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 端口核对清单

7. 三种移动方式对比

方式 1：多段脚本（传统）

**触发**：手动 Go、EnableLoopTaskDrive=false 时的 Loop、任意编译脚本。

**流程**：

FindRoute → Compile → 多行脚本：
  agv.Mag2Go(1,2,speed);
  agv.Mag2Go(2,3,speed);
  ...
→ SelfEvaluating 逐行执行
→ 每行：锁终点 → 发 0xB1 → 等到站 → 释放起点

**特点**：每**条边**一段任务，多次 taskId，与交管「逐段锁点」一致。

方式 2：Loop 全程任务（阶段 4，默认）

**触发**：goalSite 标签 + 编译脚本含 Mag2Go + EnableLoopTaskDrive=true。

**流程**：

LoopMission 写 goalSite
→ GoSite 仍 Compile 多行脚本（Core 不变）
→ actualSendScript 拦截，不逐行执行
→ ExecuteGoalTaskAsync(当前站 → goalSite)
→ 状态机一次规划全程，滑动窗口发 0xB1

**特点**：业务上一次任务，协议上仍遵守每帧 ≤10 站。

方式 3：单段 Mag2Go（脚本一行）

**触发**：脚本里只有一行，或无 goalSite 的测试。

**流程**：与方式 1 的单行相同，状态机只跑 src → dst 一段。

对比表

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 一致）：

状态机到站后，会比对车体上报状态帧中**同一节点块**的字段是否达到期望值；未达标则补发 0xA1。

8.2 站点 fields 详细说明

8.2.1 节点与调度类

`TagValue`（int，可选）

`goSite`（int，可选）

`Fass2_WaitMode`（string，预留）

8.2.2 `Fass2_StartStop` — 启停模式（byte）

映射协议字段：StartStop（节点块第 5 字节）

**默认规则**（未显式配置 Fass2_StartStop 时，Fass2TaskBuilder 自动决定）：

**动作完成判定**：若配置了非过站值，状态机要求上报 Node.StartStop 与期望值一致，且车体非运行态（State≠1），才推进下一段。

**与 Fass2_PrecisionStop 关系**：

• 可直接写 Fass2_StartStop = 22
• 或末站写 Fass2_PrecisionStop = true，由组包器自动设为 22

8.2.3 `Fass2_PrecisionStop` — 精准停（bool）

8.2.4 `Fass2_Byroad` — 分叉选择（byte）

映射协议字段：Byroad

8.2.5 `Fass2_Direction` — 车头旋转（byte）

映射协议字段：Direction

8.2.6 `Fass2_Orientation` — 行驶朝向（byte）

映射协议字段：Orientation

8.2.7 `Fass2_Lift` — 顶升/举升（byte）

映射协议字段：Lift

8.2.8 `Fass2_Roll` — 滚筒（byte）

映射协议字段：Roll

8.2.9 `Fass2_Charge` — 充电（byte）

映射协议字段：Charge

8.2.10 `Fass2_Rest` — 休眠（byte）

映射协议字段：Rest

8.2.11 `Fass2_Obstacle` — 避障区（byte）

映射协议字段：Obstacle

8.2.12 `Fass2_Audio` / `Fass2_Light` — 声光（byte）

取值以车体协议为准，一般为模式/曲目/灯色编号。

8.2.13 `Fass2_Clamp` — 夹抱（byte）

映射协议字段：Clamp

8.2.14 `Fass2_Tray` — 托盘（byte）

映射协议字段：Tray

8.2.15 `Fass2_Shutdown` — 关机（byte）

映射协议字段：Shutdown

8.2.16 站点 fields 速查总表

8.3 路径 Track fields 详细说明

路径 fields 主要影响**进入该站的那段边**（距离、速度、朝向、分叉）。

**距离 Distance**：由地图坐标自动计算（上一站与本站欧氏距离，mm 取整），一般无需手配。

8.4 组包优先级与默认规则

当同一协议字段在站点和边都有配置时：

站点 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。

8.5 典型场景配置示例

场景 A：通道过站（无动作）

站点 fields：**无需配置**（中间站默认 StartStop=1）

场景 B：普通停车工位

Fass2_StartStop = 2

场景 C：精准对接工位（末站）

Fass2_PrecisionStop = true

或

Fass2_StartStop = 22

场景 D：顶升装卸工位

Fass2_StartStop = 2
Fass2_Lift = 1        # 到站升起到位

离站下一任务可在目标站配 Fass2_Lift = 2 下降，或通过后续路径站点 fields 覆盖。

场景 E：充电工位

Fass2_StartStop = 2
Fass2_Charge = 2      # 开始充电

场景 F：Y 型磁分叉口

**站点**（推荐在岔口站配）：

Fass2_Byroad = 1      # 选择磁条 1

或在该站**进入边**上配：

magSelect = 1
# 或
Fass2_Byroad = 1

场景 G：磁地标与站 ID 不同

**站点**：

TagValue = 10086

**车辆**：

UseTagValueAsNode = true

场景 H：Loop 默认下一跳

**站点 3**（车到 3 后若 tasklist 无匹配，自动去 5）：

goSite = 5

场景 I：完整工位（停车 + 顶升 + 精准）

TagValue = 2001
Fass2_StartStop = 22
Fass2_Lift = 1
Fass2_Obstacle = 2

**配置禁忌（新手易错）**：

9. LoopMission 环线任务

9.1 运行流程

1. 车到站 N，LoopMission 检测可用
2. 匹配 tasklist：currentStationId = N → 分配 targetStationId
3. 写 tags：goalSite = 目标站 ID
4. LoopStartAction 调用 GoSite
5. Mag2Car 拦截 → 全程任务到 goalSite
6. 到达后 GoSite 清理 goalSite / occupied / loopAssigned
7. 下一轮任务匹配

9.2 相关 tags

9.3 与 Core 的关系

• **不需要改 Core**；LoopMission 逻辑完全沿用
• 磁导航FASS2环线 仅为场景标识，行为与 LoopMission 相同
• 真正区别在 **车型** 是否 Mag2Car 且 EnableLoopTaskDrive=true

9.4 关闭 Loop 拦截（恢复多段脚本）

EnableLoopTaskDrive = false

Loop 仍走 Compile 多行 Mag2Go，每行一段边。

10. 任务状态机与协议下发

10.1 状态流转

Idle → Planning → Moving → AtStation → SegmentDone → … → Complete
                                              ↓
                                            Fault（急停/故障/超时）

10.2 单帧最多 10 站 — 不冲突

• **规划**：全程可能有 20+ 站，存在内存 Plan 里
• **下发**：每次只发滑动窗口 min(LockCount, 剩余, 10) 站
• **推进**：当前站动作完成 → CurrentIndex++ → 再发下一段
• **同一 taskId**：全程复用，周期重发当前窗口

示例（15 站路径，LockCount=4）：

第1次 0xB1：站 1,2,3,4
到站 1 后：  站 2,3,4,5
到站 2 后：  站 3,4,5,6
…直到 goalSite

若车体需要首帧更多预发，可将 LockCount 调至 **10**（不超过协议上限）。

10.3 动作闭环

到站后比对上报 25B 节点与期望：

10.4 车辆状态枚举（调试看）

10.5 重启恢复（可选）

任务上下文会写入 car.tags（Fass2Task_* 前缀）。重启后 keepAlive 尝试恢复，需等车体再次 UDP 上报后状态机继续推进。

11. 状态查看与手动操作

车辆右键方法（界面中）：

日志前缀：[Mag2Car:车名(id)]，任务状态机：task-sm。

12. 常见问题排查

Q1：车显示离线（UDP）

Q2：发了 0xB1 车不动

Q3：Loop 不分配任务

Q4：到站但不继续

Q5：Loop 和多段脚本哪个在生效？

看日志：

• loop goal drive intercept → 全程任务（阶段 4）
• script begin + 多行 Mag2Go → 多段脚本

Q6：与 MagCar 混用注意事项

• EventCarMission **只控制 MagCar**
• 同场景两种车型时，tasklist 和车辆类型要对应
• FASS 1.0 用 MagCar，FASS 2.0 用 Mag2Car

13. 参数推荐与检查清单

13.1 首次联调推荐配置

CommMode              = Udp
EnableTaskStateMachine = true
EnableLoopTaskDrive   = true
LockCount             = 4        （车体需更多预发可改 10）
StartBeforeMove       = true
EnableDetailLog       = true
LogRawFrame           = true
MoveTimeoutSeconds    = 120

13.2 上线前检查清单

• [ ] 插件 StandardScene.Magnetic.dll 已加载
• [ ] 车型为 Mag2Car（不是 MagCar）
• [ ] VehicleCode、IP、端口与车体一致
• [ ] UDP 能收到 100B，日志有 0x10 应答
• [ ] 关键站点 TagValue / Fass2_* 已配置
• [ ] LoopMission 已启动，tasklist.json 路径正确
• [ ] 单车手动 Go 一站成功后再开环线

14. 术语表

附录：相关源码路径

*文档随代码演进，若参数或行为有变更，以源码为准。*