28 KiB
来源 DOCX：
../doc/xyzbc-trt-web-cnc-simulation-design-task-and-technical-plan.docx整合时间：2026-07-02。本文保留 DOCX 的任务书、技术方案、程序逻辑分析和状态联锁内容，图片引用到
../doc/assets/。
xyzbc-trt Web 数控仿真系统
设计任务书和技术方案
完全对标 LinuxCNC xyzbc-trt 五轴 table rotary/tilting 仿真配置
| 项目 | 内容 |
|---|---|
| 原型系统 | /home/mes123456/cnc_wams/linuxcnc |
| 启动命令 | /home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment linuxcnc /home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini |
| 目标产物 | 浏览器端 Web 数控仿真界面、五轴机床模型、switchkins 逻辑、路径预览与执行对比 JSON |
| 文档位置 | /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/doc |
| 编制日期 | 2026-07-02 |
1. 项目目标
本项目建设一个 Web 数控仿真系统，功能和行为完全对标 LinuxCNC 真实运行配置 xyzbc-trt.ini。Web 系统不是展示页，而是首屏即进入数控仿真工作台，提供程序加载、预览、DRO、MDI、PyVCP 等价控件、五轴机床运动显示、switchkins 模式切换、刀具路径采样、执行过程记录和误差对比。
对标基线以已编译成功并能运行的 /home/mes123456/cnc_wams/linuxcnc 为准，旧路径 历史旧 LinuxCNC 目录 不再作为本方案的运行基线。
核心验收原则：同一份配置、同一份 G-code、同一运动学模式、同一采样周期、同一 JSON 字段，分别采集 LinuxCNC 真实系统和 Web 仿真系统的预览路径与执行路径，逐点比对位置、姿态、运动学模式和 HAL 状态。
2. 原型系统运行证据
2.1 当前启动命令
| /home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment linuxcnc \ /home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini |
|---|
2.2 当前关键进程
| 进程 | 对标含义 |
|---|---|
| scripts/linuxcnc xyzbc-trt.ini | LinuxCNC 主启动入口，Web 端需实现等价启动会话和配置装载流程。 |
| linuxcncsvr | NML/状态服务，Web 端需提供统一运行状态中心。 |
| rtapi_app load tpmod | 运动规划模块，Web 端需实现轨迹规划与采样接口。 |
| milltask | 任务解释和程序执行，Web 端需实现程序状态机、运行、暂停、复位、MDI。 |
| halui | HAL UI 指令通道，Web 端需复刻 PyVCP 按钮到 MDI 命令的连接。 |
| hal_manualtoolchange | 手动换刀流程，Web 端需提供换刀提示和工具状态。 |
| xyzbc-trt-gui | Vismach 五轴机床模型，Web 端需使用 Three.js 对标机床结构和运动。 |
| axis -ini xyzbc-trt.ini | AXIS 主界面，Web 端需对标界面信息架构和操作入口。 |
图 1：真实 LinuxCNC 会话抓取的 AXIS 主界面，包含预览、DRO、PyVCP SWITCHKINS 面板、程序区和状态栏。
图 2：桌面级运行截图，用于保留真实执行环境和窗口布局证据。
2.3 HAL 状态基线
| HAL 项 | 当前值或连接 | Web 对标要求 |
|---|---|---|
| motion.switchkins-type | 0，由 :kinstype-select 驱动 | 实现 0:IDENTITY、1:XYZBC、2:USERK 三态切换。 |
| kinstype.is-0/1/2 | TRUE/FALSE/FALSE | 驱动 Web PyVCP multilabel 的当前模式显示。 |
| joint.0..4.pos-fb | X/Y/Z/B/C 五轴反馈均为 0 | 映射到 Web DRO、机床模型关节和路径采样。 |
| motion.tooloffset.z | 连接 :tool-offset | 影响 TCP 刀尖位置和机床模型刀具长度。 |
| xyzbc-trt-kins.x-offset | -20 | Web 运动学参数必须使用同值。 |
| xyzbc-trt-kins.z-offset | -15 | Web 运动学参数必须使用同值。 |
| xyzbc-trt-kins.conventional-directions | FALSE | Web 端旋转方向和矩阵约定必须一致。 |
3. 完全对标范围
| LinuxCNC 文件或模块 | 真实功能 | Web 对标实现 |
|---|---|---|
| xyzbc-trt.ini | 定义 AXIS、PyVCP、KINS、HAL、TRAJ、TASK、EMCIO、轴和关节参数。 | 实现 INI 解析器，生成 Web 会话配置、轴参数、速度限制、文件引用和 UI 初始状态。 |
| xyzbc-trt.xml | 定义 SWITCHKINS multilabel、IDENTITY、TCP:XYZBC、userk、vismach-clear 按钮。 | 实现 PyVCP 等价面板，按钮通过 Web HAL 总线触发 MDI 命令或清除轨迹。 |
| switchkins_postgui.hal | 把 PyVCP 控件接到 halui.mdi-command-00/01/02 和 vismach.plotclear。 | 实现 postgui HAL 装配层，保证 UI 控件不直接改状态，而是经 HAL 语义连接。 |
| LIB:basic_sim.tcl | 生成仿真 HAL 基础链路。 | 建立基础 HAL 信号、仿真 joint、motion、halui、pyvcp、vismach 命名空间。 |
| xyzbc-trt-kins.so | XYZBC table rotary/tilting 运动学和 switchkins。 | 实现或移植为 WASM/TypeScript 运动学模块，支持 identity、XYZBC TCP、userk。 |
| xyzbc-trt-gui | Vismach 三维机床模型，随 HAL 引脚运动。 | 使用 Three.js 建立桌台、转台、倾斜轴、主轴、刀具、工件和路径轨迹。 |
| xyzbc_switchkins.ngc | 默认打开的演示程序，调用 xyzbc_switchkins_sub。 | Web 端默认加载同一程序，预览曲线和执行曲线可导出 JSON。 |
| remap_subs/*.ngc | M428/M429/M430 以及演示子程序。 | 支持 remap 调用或预编译宏展开，保证模式切换轨迹一致。 |
| xyzbc-trt.tbl / xyzbc.var | 刀具表和 RS274 参数文件。 | Web 端加载、显示、持久化并参与 tooloffset 和程序执行。 |
图 3：LinuxCNC 原型系统与 Web 仿真系统的模块级对标关系。
4. Web 界面设计任务书
4.1 首屏布局
顶部：文件、机器、视图、帮助菜单，以及急停、上电、打开文件、运行、暂停、单步、停止、视图方向、清扫轨迹等图标按钮。
左侧：Manual Control 与 MDI 标签页，包含 Joint 0 到 4 选择、连续/增量点动、Home、Touch Off、Tool Touch Off、主轴控制和倍率滑块。
中间：Preview/DRO/程序标签页，预览页显示 Three.js 五轴机床、工件、刀具、坐标轴、尺寸标注和刀具路径。
右侧：SWITCHKINS 面板，显示 0:IDENTITY、1:XYZBC、2:USERK，并提供 IDENTITY、TCP:XYZBC、userk、vismach-clear 按钮。
底部：G-code 程序区、Active G-Codes、状态栏、错误和日志输出。
4.2 视觉和交互要求
| 界面区域 | 对标要求 | 验收证据 |
|---|---|---|
| AXIS 工具栏 | 保留关键数控操作入口，按钮使用明确图标和 tooltip。 | 截图比对，操作事件 JSON。 |
| DRO | 显示 X/Y/Z/B/C、joint 或 world 坐标、实际/命令位置。 | uiState.dro 与 LinuxCNC status 对比。 |
| PyVCP | 按钮和 multilabel 文案、状态、HAL 连线语义一致。 | halPins.kinstype 和 uiState.pyvcp。 |
| Preview | 显示默认程序的圆形/螺旋路径、刀尖、刀轴、XYZBC 坐标。 | previewPath.samples 和截图。 |
| Vismach 等价模型 | 五轴结构、B/C 旋转、X/Y/Z 平移、tooloffset、x/z offset 生效。 | 模型姿态 JSON 和截图。 |
5. 技术方案
5.1 总体架构
| 层级 | 模块 | 职责 |
|---|---|---|
| 文件层 | OPFS/IndexedDB 工作区 | 保存 ini/xml/hal/ngc/tbl/var/json，支持导入 LinuxCNC 原始目录。 |
| 解析层 | INI/XML/HAL/NGC/TBL/VAR parser | 结构化解析配置、控件、信号、程序和参数，禁止手工硬编码配置结果。 |
| 运行层 | Task/Interp/Motion/HAL runtime | 复刻 LinuxCNC 任务状态机、G-code 解释、运动规划、HAL pin/net。 |
| 运动学层 | xyzbc-trt-kins | 实现 identity、XYZBC TCP、userk，输出关节、世界坐标、刀尖和刀轴。 |
| 界面层 | Web UI 组件 | 对标 AXIS、PyVCP、DRO、MDI、程序窗口、状态栏。 |
| 三维层 | Three.js | 五轴机床、工件、刀具、路径、坐标系、清轨迹和相机视图。 |
| 证据层 | Evidence JSON + Compare report | 采集真实系统和 Web 系统，按同周期逐点比对。 |
5.2 switchkins 逻辑
Web 端必须复刻原型中的 switchkins 控制链路：PyVCP 按钮触发 halui.mdi-command-00/01/02，MDI 执行 M429/M428/M430，remap 子程序改变 motion.analog-out-03，再驱动 motion.switchkins-type。UI 当前模式由 kinstype.is-0/1/2 反向驱动，而不是由按钮直接写 UI 标签。
| 按钮 | HAL 目标 | MDI 命令 | 目标模式 |
|---|---|---|---|
| IDENTITY | halui.mdi-command-00 | M429 | 0:IDENTITY |
| TCP:XYZBC | halui.mdi-command-01 | M428 | 1:XYZBC |
| userk | halui.mdi-command-02 | M430 | 2:USERK |
| vismach-clear | vismach.plotclear | 无 | 清除三维路径显示 |
5.3 五轴运动学和模型
Web 端机床模型采用 XYZBC table rotary/tilting 结构。X 对应 table-x，Y 对应 saddle-y，Z 对应 spindle-z，B 对应 tilt-b，C 对应 rotate-c。运动学参数使用原型系统当前 HAL 值：x-offset=-20、z-offset=-15、旋转点均为 0、conventional-directions=false。刀具长度来自 motion.tooloffset.z。
三维模型不只显示程序预览曲线，还必须在执行时按采样点刷新桌台、转台、主轴和刀具姿态。执行暂停、复位、清轨迹、模式切换后，模型状态和 JSON 状态必须同步。
5.4 路径采样和 JSON 比对
曲线采样周期固定为 samplePeriodMs = 20，即 50 Hz。LinuxCNC 真实系统和 Web 仿真系统必须使用相同采样周期、相同 sampleIndex、相同时间基准和相同坐标字段，禁止一端 10 ms、另一端 20 ms 或使用不同插补点。
图 4：刀具预览路径和执行路径 JSON 的同周期采样与逐点比对流程。
5.5 Evidence JSON 字段规范
| { "schema": "xyzbc-trt-evidence/v1", "source": "linuxcnc-native / web-sim", "samplePeriodMs": 20, "linuxcncRoot": "/home/mes123456/cnc_wams/linuxcnc", "ini": "configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini", "program": "./demos/xyzbc_switchkins.ngc", "runtime": {"taskState": 1, "interpState": 1, "axisMask": 55, "kinstype": 0}, "halPins": { "motion.switchkins-type": 0, "xyzbc-trt-kins.x-offset": -20, "xyzbc-trt-kins.z-offset": -15, "xyzbc-trt-kins.conventional-directions": false }, "previewPath": { "coordinateSystem": "XYZBC", "samples": [{ "sampleIndex": 0, "timeMs": 0, "line": 1, "joint": {"x": 0, "y": 0, "z": 0, "b": 0, "c": 0}, "world": {"x": 0, "y": 0, "z": 0, "b": 0, "c": 0}, "toolTip": {"x": 0, "y": 0, "z": 0}, "toolAxis": {"i": 0, "j": 0, "k": 1}, "kinstype": 0 }] }, "executionPath": {"samples": []}, "screenshots": []} |
|---|
5.6 对比报告字段
| 字段 | 说明 |
|---|---|
| sampleCount.native/web | 真实系统和 Web 系统采样点数量。 |
| maxPositionError | X/Y/Z/B/C 最大逐点误差。 |
| rmsPositionError | 路径整体均方根误差。 |
| maxToolTipError | TCP 刀尖位置最大误差。 |
| maxToolAxisErrorDeg | 刀轴方向最大角度误差。 |
| firstMismatch | 首个超差点的 sampleIndex、line、timeMs、native/web 值。 |
| uiEquivalence | AXIS/PyVCP/DRO/状态栏截图和 DOM 状态对比。 |
| pass | 是否通过设定阈值。 |
6. 开发任务分解
| 阶段 | 任务 | 交付物 | 验收方式 |
|---|---|---|---|
| 阶段 1 | 导入并解析 xyzbc-trt.ini、XML、HAL、TBL、VAR、NGC 文件。 | 结构化配置 JSON、文件依赖图。 | 与 xyzbc-trt-runtime-files.md 逐项核对。 |
| 阶段 2 | 搭建 AXIS 等价 Web UI 和 PyVCP 面板。 | 首屏数控工作台。 | 与真实 AXIS 截图逐区比对。 |
| 阶段 3 | 实现 HAL 总线、halui、switchkins 状态机和 remap 命令链路。 | HAL 状态面板、MDI 命令记录。 | 按钮触发 M429/M428/M430 后状态一致。 |
| 阶段 4 | 实现 XYZBC 运动学和 Three.js Vismach 等价模型。 | 五轴机床模型、刀具和工件。 | X/Y/Z/B/C 点动与 HAL pin 一致。 |
| 阶段 5 | 实现 G-code 预览路径、执行路径、暂停/复位/单步。 | 预览轨迹、执行轨迹、状态机。 | 默认程序 xyzbc_switchkins.ngc 可回放。 |
| 阶段 6 | 实现 native 和 web evidence JSON，固定 20 ms 采样周期。 | native-evidence.json、web-evidence.json。 | 字段、单位、sampleIndex 对齐。 |
| 阶段 7 | 实现 compare-report 自动生成。 | compare-report.json、HTML 报告。 | 误差统计和首个差异点可追溯。 |
7. 验收标准
| 类别 | 必须通过的标准 |
|---|---|
| 路径标准 | 所有文档、配置和运行基线均指向 /home/mes123456/cnc_wams/linuxcnc。 |
| 界面标准 | Web 首屏包含 AXIS 主要工作区、PyVCP SWITCHKINS 面板、预览区、DRO、程序区和状态栏。 |
| 功能标准 | 默认加载 xyzbc_switchkins.ngc，支持 MDI、模式切换、清轨迹、点动、倍率、刀具和参数。 |
| 运动学标准 | identity、XYZBC TCP、userk 模式状态和轨迹计算与真实系统一致。 |
| JSON 标准 | 预览路径和执行路径同时导出，采样周期统一为 20 ms，字段一致。 |
| 比对标准 | 能输出最大误差、RMS 误差、首个差异点、截图和通过/失败结论。 |
| 证据标准 | 每次验收保存 LinuxCNC 原始截图、Web 截图、native JSON、web JSON、compare report。 |
8. 风险和控制措施
| 风险 | 影响 | 控制措施 |
|---|---|---|
| LinuxCNC 内部解释器和 Web 解释器细节不一致 | 路径点或模式切换时序不同。 | 优先移植或复用 LinuxCNC 解析/运动学逻辑，保留 native evidence 作为回归基准。 |
| 采样周期不一致 | 曲线无法逐点比较。 | 强制配置 samplePeriodMs=20，JSON schema 校验不允许缺省。 |
| Three.js 模型和 Vismach 结构偏差 | 视觉对标通过但运动不一致。 | 每个关节都绑定 HAL pin，模型矩阵由运动学输出驱动。 |
| UI 直接改状态绕过 HAL | 无法对标真实控制链路。 | PyVCP 控件只发 HAL/MDI 事件，状态由 HAL pin 回读。 |
| 路径或旧目录混入 | 证据不可复现。 | 文档和脚本统一扫描旧路径，禁止使用 历史旧 LinuxCNC 目录。 |
9. 附录：对标文件清单
| 文件 | 用途 |
|---|---|
| /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/doc/xyzbc-trt-runtime-files.md | 当前运行配置文件说明和路径基线。 |
| /home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini | 主 INI 配置。 |
| xyzbc-trt.xml | PyVCP SWITCHKINS 面板。 |
| switchkins_postgui.hal | PyVCP 与 HALUI、Vismach 清轨迹连接。 |
| demos/xyzbc_switchkins.ngc | 默认加载的演示程序。 |
| remap_subs/428remap.ngc、429remap.ngc、430remap.ngc | switchkins 模式切换 remap。 |
| xyzbc-trt.tbl / xyzbc.var | 刀具表和参数文件。 |
| bin/xyzbc-trt-gui | Vismach 原型模型入口。 |
| rtlib/xyzbc-trt-kins.so | 真实五轴运动学模块。 |
10. xyzbc-trt 程序逻辑全量分析
下面按“文件装载 - 运动学 - HAL - 界面 - 执行 - 证据”的顺序，把 xyzbc-trt 的实际逻辑拆开说明。这里不是抽象架构，而是与当前源码、HAL pin 和界面行为一一对应的执行逻辑。
10.1 启动入口逻辑
| 步骤 | 逻辑 | 结果 |
|---|---|---|
| 1 | rip-environment 先建立 run-in-place 环境，确保本地 bin/、lib/、rtlib/、bin/python 可被当前会话找到。 | 执行路径完全指向 /home/mes123456/cnc_wams/linuxcnc。 |
| 2 | linuxcnc xyzbc-trt.ini 读取主 INI，按段装载 DISPLAY、RS274NGC、KINS、HAL、TRAJ、TASK、EMCIO。 | 界面、运动学和程序执行进入同一会话。 |
| 3 | AXIS、PyVCP、Vismach、halui、milltask、linuxcncsvr、rtapi_app 同时被拉起。 | 形成“界面 + 任务 + 运动 + 证据”闭环。 |
这个启动链路的关键点是：界面不是单独运行的，而是被 INI 文件和 HAL 图驱动。Web 端要完全对标，就不能把预览、模式切换、DRO、刀具、执行按钮做成彼此割裂的前端组件，而要让它们共享同一个运行态和信号总线。
10.2 配置装载逻辑
| 文件 | 逻辑作用 | Web 对标要点 |
|---|---|---|
| xyzbc-trt.ini | 定义机器类型、显示方式、五轴坐标、最大速度、轴/关节限制、默认程序、运动学模块和 HAL 连线。 | 必须解析成结构化会话配置，不能只读出少量文本字段。 |
| xyzbc-trt.xml | 定义 SWITCHKINS 面板和按钮文案。 | 按钮状态要由 HAL 输出决定，multilabel 要能随 kinstype 更新。 |
| switchkins_postgui.hal | 把按钮接到 MDI 命令，把清轨迹接到 vismach.plotclear。 | Web 端的按钮必须走同样的“事件 - HAL - MDI - 状态”链路。 |
| xyzbc_switchkins.ngc | 默认加载的程序是演示切换程序，既包含路径，也包含模式切换场景。 | Web 必须默认回放同一程序并记录同一套证据字段。 |
10.3 switchkins 运动学逻辑
xyzbc-trt-kins 通过 switchkinsSetup() 绑定三个运动学分支：
-
type0：在当前配置里被重定义为 identity，用于启动后的关节直接操控。
-
type1：xyzbc-trt-kins 本体，执行 XYZBC table rotary/tilting 的 TCP 运动学。
-
type2：用户自定义运动学 userk。
源码里明确设置了 kinsname = "xyzbc-trt-kins"、halprefix = "xyzbc-trt-kins"、required_coordinates = "xyzbc"、allow_duplicates = 1，这意味着它既是一个五轴模块，也是一个允许坐标字母重复映射的 switchkins 模块。identityfirst 参数把启动默认值切换成 identity，而不是让机床类型本体成为 type0，这正是 sim 配置的关键差异。
图 5：xyzbc-trt 程序逻辑总图，展示从文件装载到证据采样的完整执行链。
switchkins 内部的逻辑顺序很重要：先由 rtapi_app_main() 创建 HAL 组件和输出 pin，再调用 kinematicsSwitch(0) 设定初始模式，然后把三个 setup 函数分别执行一遍，最后 hal_ready()。这意味着 Web 端在启动时也必须先完成状态总线和模式初始化，再挂载界面和三维模型，不能反过来。
10.4 正逆运动学逻辑
| 函数 | 逻辑 | 对标意义 |
|---|---|---|
| xyzbcKinematicsForward() | 根据 X/Y/Z/B/C 和 offset、tooloffset、旋转点、方向约定计算 TCP 世界坐标与姿态。 | Web 端预览路径和三维模型必须采用同一套正解公式。 |
| xyzbcKinematicsInverse() | 根据目标 TCP 位姿反推关节角和关节位移，再写回 mapped joints。 | MDI、点动、程序执行时的运动控制必须能从目标位姿反推关节。 |
| conventional-directions | 默认关闭时，旋转轴方向与 conventional 约定相反。 | Web 模型如果方向画反，视觉上会“像”，但运动学会错，必须严格对齐。 |
在当前配置里，B/C 轴是主运动学轴，A/U/V/W 只是可选字母。前向解使用主关节 JX/JY/JZ/JB/JC 计算 TCP 位姿；逆解再根据目标位姿回算这些主关节。这个路径对 Web 端非常关键，因为预览路径不能只画“刀尖折线”，还要把每个采样点对应的关节姿态也算出来，否则无法和真实系统逐点比对。
10.5 HAL 和状态逻辑
| HAL 语义 | 逻辑 | Web 对标实现 |
|---|---|---|
| motion.switchkins-type | 当前运动学类型输入，浮点值被截断为整数 0/1/2。 | 前端 switchkins 状态必须是整数型并保持和任务状态一致。 |
| kinstype.is-0/1/2 | 当前模式输出，供 GUI、指示灯、程序逻辑读取。 | Web 端要提供同样的可读状态给 PyVCP 等价面板和检测逻辑。 |
| motion.analog-out-03 | 通过 M68/MDI 等方式写入，间接控制 kinstype。 | Web 端模式切换必须保留“间接驱动”语义，不可直接写最终状态。 |
| halui.mdi-command-00/01/02 | PyVCP 按钮发出的 MDI 入口。 | 按钮点击后必须先变成命令，再进入状态机。 |
switchkins.c 的实现说明了一个很重要的行为：模式切换后先清除 use_lastpose，再根据当前模式把对应的 kinstype.is.N 置位。也就是说，Web 仿真不能把“当前模式”当作普通表单状态，它必须是一次完整状态机切换，切换后还要在 UI 上立即反映。
10.6 UI 与三维模型逻辑
axis.py 的行为说明 AXIS 窗口里存在“轴模式”和“关节模式”的切换；当配置处于非 trivkins 或特殊 kinstype 时，按钮和焦点会根据当前运动模式自动切换到关节/轴对应控件。Web 端要对标的不只是布局，还有这个控件激活规则。
xyzbc-trt-gui.py 则把 Vismach 模型拆成可响应的 HAL 变换链：tool-offset 作用于刀具，spindle-z 作用于主轴头，tilt-b 作用于倾斜轴，rotate-c 作用于回转台，table-x 和 saddle-y 则驱动横向与纵向运动。这个顺序决定了几何层级关系，所以 Web 端模型必须按同样层级搭建，而不是把每个零件独立摆放。
10.7 程序执行与同步逻辑
| 阶段 | 逻辑 | 结果 |
|---|---|---|
| 预览 | 读取 xyzbc_switchkins.ngc，在预览区生成 G-code 轨迹和位置采样。 | 得到 previewPath JSON。 |
| 切换 | 通过 M428/M429/M430 或等价按钮改变 switchkins 模式，并执行同步命令。 | 运动学和解释器状态对齐。 |
| 执行 | 根据当前模式执行程序，同时刷新关节反馈和 TCP 位姿。 | 得到 executionPath JSON。 |
| 比对 | 用固定 20 ms 采样周期对比预览和执行曲线。 | 输出 compare-report.json。 |
同步逻辑是这个程序最容易被误解的地方：切换模式不是单独改一个 pin 就结束了，必须让解释器和 motion 同步，否则 G-code 看到的坐标语义和 motion 看到的坐标语义会不同。这个要求在文档中已经被固化为“预览路径和执行路径统一采样周期，并在切换时强制同步”。
10.8 异常和约束逻辑
-
如果 motion.switchkins-type 没有连接，只有 type0 默认运动学可用，这属于兼容旧配置的行为。
-
如果切换到身份不匹配的运动学类型，程序逻辑必须在 G-code 中先检查 kinstype.is.N 或等价输入，再决定是否继续。
-
如果当前系统的坐标偏置、刀补、外部偏置在切换后不一致，必须先清理或重置偏置，再切换模式。
-
如果 Web 端和 LinuxCNC 真实系统的采样周期不一致，则即使图形看起来接近，也不能通过对标验收。
总的来说，xyzbc-trt 的逻辑不是“一个五轴模型 + 一个预览窗口”，而是“配置驱动的状态机 + 可切换运动学 + HAL 事件 + 三维可视化 + 路径证据”的组合。Web 端要做到完全对标，必须把这五件事统一成一条链。
11. 开机、急停、回零与执行状态的联锁逻辑
这一节专门说明机床状态如何影响程序执行。核心不是某一个按钮，而是 ESTOP、Machine Power、Homing、Task Mode、Interp State、Paused、Auto/MDI/Manual 这些状态共同决定“能不能跑、能不能发 MDI、能不能执行程序、能不能继续暂停中的程序”。
| 状态或条件 | 含义 | 对执行的影响 |
|---|---|---|
| ESTOP | 急停被触发，属于最高优先级禁止状态。 | 不能发运行/MDI/自动执行命令；必须先解除急停。 |
| Machine Power ON | 机床上电并使能轨迹规划。 | 没有上电时通常不能进入正常执行。 |
| Homed | 各关节完成回零。 | 未回零时只能做有限的点动或被配置允许的动作；运行 MDI/程序通常需要回零。 |
| Task Mode = MANUAL | 手动模式。 | 适合回零、点动、Touch Off、手动辅助动作；不适合直接跑自动程序。 |
| Task Mode = MDI | 手动数据输入模式。 | 允许执行单行命令或小段命令，但仍受 ESTOP/上电/回零/解释器空闲限制。 |
| Task Mode = AUTO | 自动模式。 | 允许加载并运行 G-code 文件、单步、暂停、恢复、停止。 |
| Interp Idle | 解释器空闲。 | MDI 或启动新的自动程序前通常必须空闲。 |
| Paused | 程序暂停。 | 可以恢复、停止，某些界面允许在暂停态下做受限补位或回退。 |
LinuxCNC 的状态判断在 Python 接口里是明确的：发 MDI 前至少要满足“未急停、已上电、全部关节已回零、解释器空闲、模式是 MDI”；运行程序前也要满足相应条件。AXIS 界面把这些限制做得比较“宽”，会自动切换到所需模式，但本质上仍然是同一组状态联锁。
对于本项目的 Web 仿真，这意味着：按钮是否可点、命令是否被执行、预览和执行是否允许开始，不能由前端自己臆造，而必须由一个统一状态机决定。
11.1 典型状态流转
| 阶段 | 典型动作 | 允许的下一步 |
|---|---|---|
| 上电前 | ESTOP 解除前的初始化。 | 只能显示状态，不能执行加工。 |
| 解除急停 | ESTOP RESET。 | 可以请求 Machine Power ON。 |
| 上电 | Machine Power ON。 | 可以回零、可视情况进入手动或 MDI。 |
| 回零 | Home All / 单轴 Homing。 | 全部回零后，自动/MDI 执行条件才完整。 |
| 切换模式 | MANUAL / MDI / AUTO。 | 可按模式开始点动、发 MDI、或运行程序。 |
| 运行中 | AUTO RUN。 | 可 Pause、Stop、Step 或 Resume。 |
| 暂停中 | AUTO PAUSE。 | 可 Resume 或 Stop；某些界面允许受限补位。 |
11.2 对 XYZBC 五轴程序的具体影响
xyzbc-trt 的默认程序 xyzbc_switchkins.ngc 不是单纯的路径文件，它还演示了 switchkins 切换逻辑。因此在分析程序执行时，必须考虑状态切换的前提条件：急停解除、机器上电、关节回零、模式与解释器状态匹配。尤其是 M428/M429/M430 这样的切换命令，不能在解释器忙、状态未同步或不在合适模式时随意插入。
如果机器处于 ESTOP 或未上电，那么即使 UI 看起来加载了程序，也不能真正开始执行。若未回零，某些运动限制还未生效或未完整生效；如果是 identity 运动学，则回零和点动可能与 XYZBC 模式下的坐标解释不同，UI 必须明确呈现当前 kinstype。
11.3 Web 端需要实现的联锁规则
| Web 控件 | 可用条件 | 禁用时表现 |
|---|---|---|
| 急停释放按钮 | 当前处于 ESTOP。 | 显示为不可执行或已触发状态。 |
| 上电按钮 | 急停已解除。 | 急停未解除时禁止上电。 |
| 回零按钮 | 机器已上电，且对应关节未回零或允许重复回零。 | 未上电时不允许回零。 |
| MDI 输入框 | 非 ESTOP、已上电、已回零、解释器空闲、模式为 MDI。 | 给出原因说明，不发送命令。 |
| 运行/自动按钮 | 非 ESTOP、已上电、已回零、文件已加载且解释器空闲。 | 程序不可启动。 |
| 暂停/继续 | 程序正在运行或已暂停。 | 非运行态时禁用。 |
| switchkins 切换按钮 | 应避免在程序执行中切换；若允许必须先同步并受限处理。 | 运行中直接切换应提示风险或禁止。 |
11.4 与证据 JSON 的关系
为了让真实 LinuxCNC 与 Web 仿真的行为可比，证据 JSON 不能只记录路径点，还要记录机床状态。至少要包含 taskState、taskMode、interpState、paused、estop、enabled、homed、kinstype 和按钮可用性。这样才能解释“为什么这一次能跑、那一次不能跑”。
例如：若 estop=true，那么 previewPath 也许还能生成，但 executionPath 必须为空或者标记为 blocked；若 homed 未满足，则 manual/jog 可以存在，但 auto/mdi/run 不能开始；若 interp_state != INTERP_IDLE，则 MDI 不应该再进入。
11.5 对本项目的落地结论
本项目的 Web 仿真要完全对标 xyzbc-trt，不能只做“路径看起来一样”。必须同时复刻状态机联锁：开机、急停、回零、模式、解释器、暂停与恢复，共同决定后续执行是否允许。否则 Web 端即使曲线绘得对，也无法说明它是 LinuxCNC 真实逻辑的等价实现。