Advance simulation parity and 3-axis tutorial coverage
This commit is contained in:
155
docs/linuxcnc-web-wasm-axis-3axis-complete-parity.md
Normal file
155
docs/linuxcnc-web-wasm-axis-3axis-complete-parity.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 三轴 AXIS 案例完整对标规格
|
||||
|
||||
**文档状态**：Historical draft; superseded by `linuxcnc-web-wasm-3axis-tutorial-parity.md`
|
||||
**选定案例**：`linuxcnc/configs/sim/axis/axis.ini`
|
||||
**机床类型**：3 轴笛卡尔仿真机，`trivkins`，`X Y Z`，3 joints
|
||||
**LinuxCNC 源版本**：`linuxcnc/VERSION` 中的锁定版本
|
||||
**Context**：`linuxcnc-2.10.0-pre0-wasm-m1-py-c1`
|
||||
**执行入口**：`nextTask1.md`
|
||||
|
||||
本规格把“完全对标”定义为同一个案例的三层可观察等价：
|
||||
|
||||
1. **功能等价**：运动、解释器、HAL、IO、工具、主轴、冷却、回零、限位、急停、MDI、程序控制和恢复的结果、错误和边界一致。
|
||||
2. **流程等价**：从选择 INI 到配置解析、资源装载、HAL/Task/IO 启动、显示启动、运行、停止和清理的阶段、顺序、诊断和状态迁移一致。
|
||||
3. **界面等价**：AXIS 面板中的可见控件、标签、状态、快捷操作、禁用条件、错误显示和 3D/轨迹反馈均有 Web 对应物，并驱动同一 Worker 权威状态。
|
||||
|
||||
Web 使用 React、Dedicated Worker、WASM、WorkspaceRuntime 和 Three.js；不要求复制 GTK/Tk 的进程或窗口实现，但不允许删减用户可观察的 AXIS 功能、流程或状态。
|
||||
|
||||
## 1. 证据边界
|
||||
|
||||
### 1.1 入口与 exact resources
|
||||
|
||||
| 类型 | exact path |
|
||||
|---|---|
|
||||
| INI | `linuxcnc/configs/sim/axis/axis.ini` |
|
||||
| parameter file | `linuxcnc/configs/sim/axis/sim.var` |
|
||||
| tool table | `linuxcnc/configs/sim/axis/sim.tbl` |
|
||||
| local HAL | `linuxcnc/configs/sim/axis/cooling.hal` |
|
||||
| shared intro | `linuxcnc/linuxcnc.gif` |
|
||||
| HALLIB HAL | `linuxcnc/lib/hallib/core_sim.hal`、`sim_spindle_encoder.hal`、`axis_manualtoolchange.hal`、`simulated_home.hal`、`check_xyz_constraints.hal` |
|
||||
|
||||
`axis.ini` 的 `HALFILE` 顺序、`TOOL_TABLE`、`PARAMETER_FILE`、`INTRO_GRAPHIC` 和 `[TRAJ]/[KINS]/[AXIS_*]/[JOINT_*]` 值必须按源文件逐行记录 source hash、line 和 data hash。不得用其它案例的同 basename 文件替代缺失资源。
|
||||
|
||||
### 1.2 正确 native runner
|
||||
|
||||
native 验证必须：
|
||||
|
||||
- 只把上表中案例声明的文件复制到隔离、可写的案例目录；不复制整个 `configs/sim/axis` 目录。
|
||||
- cwd 保持仓库根，使用系统 `HALLIB_DIR` 解析 `LIB:` HAL。
|
||||
- 使用真实 `DISPLAY` 执行 `linuxcnc -r <case_dir>/axis.ini`；`-k` 只能用于保留 HAL 错误诊断，不得把它当作无错误成功。
|
||||
- 成功条件必须包含可见 AXIS 窗口：WM title 类似 `AXIS <version> on LinuxCNC-HAL-SIM-AXIS`、WM class 为 `axis / Axis`，几何尺寸至少 `600x400`。
|
||||
- `timeout`、`Starting LinuxCNC`、`task:` 或后台进程存活都不能单独算成功。
|
||||
|
||||
native runner 需要记录：命令、cwd、DISPLAY、LinuxCNC 版本、窗口 title/class/geometry、启动阶段、stdout/stderr hash、生成的 `.var/.bak/position.txt` 和首个错误。
|
||||
|
||||
## 2. 功能对标矩阵
|
||||
|
||||
| 功能域 | LinuxCNC 源程序 | Web/WASM 对应 | 完成证据 |
|
||||
|---|---|---|---|
|
||||
| INI/include/资源 | `scripts/linuxcnc.in`、`src/libnml/inifile/**`、`src/emc/ini/**` | `ini-parser.mjs`、`resource-resolver.mjs`、`sim-case-loader.mjs` | exact graph、source line、resource hash、missing/optional 诊断 |
|
||||
| 启动状态 | `scripts/linuxcnc.in` 2.x/4.x 阶段、`emctaskmain.cc`、`taskclass.cc` | `configuration-startup.mjs`、`SimSession` | `NEW→MOUNTED→PARSED→RESOLVED→CORE_CREATED→HAL_READY→TASK_READY` 与 native 阶段映射 |
|
||||
| Task/模式 | `emctaskmain.cc`、`taskclass.cc`、`emccanon.cc` | `sim_task`、`task-state.mjs`、`sim-session.mjs` | MANUAL/MDI/AUTO、READY/RUNNING/PAUSED/STOPPED/ESTOP/FAULT、状态 hash |
|
||||
| RS-274 | `src/emc/rs274ngc/interp_*.cc`、`rs274ngc_pre.cc` | WASM interpreter、`program-runtime.mjs` | G0/G1、G20/G21、G90/G91、feed、M2、参数、错误行和 modal hash |
|
||||
| TP/motion | `src/emc/tp/**`、`src/emc/motion/{motion,control,homing}.c` | `sim_motion`、固定 tick scheduler、WASM core | 1x/fast tick、位置/速度/加速度、following error、limit、checkpoint parity |
|
||||
| trivkins | `src/emc/kinematics/trivkins.c`、`kins_util.c` | `sim_kinematics` trivkins module | XYZ pose↔joint identity、3 joint mapping、flags、边界和 source hash |
|
||||
| HAL | `src/hal/hal_lib.c`、`src/hal/utils/halcmd*`、`.comp` manifest | `hal-configuration.mjs`、`hal-runtime.mjs` | 6 HAL files、threads/functions/pins/signals、load order、unsupported command diagnostics |
|
||||
| 模拟主轴 | `lib/hallib/core_sim.hal`、`sim_spindle_encoder.hal`、`src/hal/components/sim_spindle.comp` | `DeviceIoRuntime`、spindle model | command RPM、mass/limit/at-speed、encoder/index、固定 tick hash |
|
||||
| 回零/限位 | `lib/hallib/simulated_home.hal`、`motion/homing.c` | virtual home switches、`sim_motion.home` | X/Y/Z home sequence、shared switches、home result、limit error |
|
||||
| 工具/换刀 | `src/emc/tooldata/**`、`src/emc/iotask/ioControl.cc`、`axis_manualtoolchange.hal` | tool table parser、virtual tool IO | `sim.tbl` entries、prepare/change/prepared/changed/abort/fault、pocket/tool state |
|
||||
| 冷却/IO | `cooling.hal`、`ioControl.cc`、virtual IO source | `DeviceIoRuntime.coolantCommand` | mist/flood/lube request、pin absence/error、interlock/estop behavior |
|
||||
| 探针/故障 | `src/hal/components/sphereprobe.comp`、motion limits、IO errors | virtual probe/limit/fault paths | probe pose latch、nonfinite/limit/estop/fault/recover |
|
||||
| 参数文件 | `rs274ngc_pre.cc::restore_parameters/save_parameters` | workspace runtime-generated `.var` and OPFS commit | missing/empty/startup/exit-save semantics、exact path/data hash |
|
||||
| 清理/恢复 | `linuxcnc.in::Cleanup`、task/interpreter exit | checkpoint、journal、replay、WorkspaceRuntime | stop/abort/estop/recover、event cursor、endpoint hash equality、无重复副作用 |
|
||||
|
||||
功能任务不得只验证“命令返回 verified”；必须比较最终 pose/joints、task/program/tool/device/HAL 状态和 state hash，并保留错误路径。
|
||||
|
||||
## 3. 流程对标矩阵
|
||||
|
||||
### 3.1 native 流程
|
||||
|
||||
1. 解析 `axis.ini`，展开 `#INCLUDE`，检查版本和 config。
|
||||
2. 读取 `PARAMETER_FILE`、EMCMOT、EMCIO、TASK、DISPLAY、NML 和 TRAJ/KINS。
|
||||
3. `cd INI_DIR`，解析 `INTRO_GRAPHIC`，启动 AXIS splash。
|
||||
4. 启动 `linuxcncsvr`、RTAPI/HAL、IO、HALUI。
|
||||
5. 按 `[HAL]HALFILE` 顺序加载 `core_sim.hal`、`sim_spindle_encoder.hal`、`axis_manualtoolchange.hal`、`simulated_home.hal`、`check_xyz_constraints.hal`、`cooling.hal`。
|
||||
6. 启动 `milltask`，执行 HALCMD，最后启动 AXIS 面板。
|
||||
7. 用户执行 home/jog/MDI/program/tool/spindle/coolant/probe/estop/recover。
|
||||
8. 关闭 AXIS 后执行 Cleanup、保存参数、停止 HAL/RTAPI、删除 NML/锁文件。
|
||||
|
||||
### 3.2 Web 流程
|
||||
|
||||
1. exact-path loader 建立 bundle，补齐运行时生成资源并记录 hash。
|
||||
2. WorkspaceRuntime 挂载，INI/include/resource graph 解析完成后才允许 startup。
|
||||
3. WASM core 创建并加载 workspace；HAL preflight 依照 native 文件顺序执行。
|
||||
4. Dedicated Worker attach Task，发布 `CAPABILITIES`/`SESSION_READY`。
|
||||
5. `LOAD_WORKSPACE` 进入 `TASK_READY`，React AppShell 绑定 snapshot/event。
|
||||
6. 所有用户操作经 `command-envelope.v1` 进入 Worker；固定 tick 更新 interpreter→TP→IK→motion→HAL→IO→publish。
|
||||
7. checkpoint/journal/replay 代替 native 退出时文件/进程清理；提交 `.var/.tbl` 变更必须可恢复。
|
||||
|
||||
两条流程必须有阶段映射表、seq/tick 对账、首个 divergence、source line 和 hash；不能用流程末尾的 READY 结果掩盖中途阶段差异。
|
||||
|
||||
## 4. AXIS 界面对标矩阵
|
||||
|
||||
### 4.1 必须覆盖的可见区域
|
||||
|
||||
| AXIS 区域 | Web 对应 | 必须验证 |
|
||||
|---|---|---|
|
||||
| File/Machine/View/Help 菜单 | AppShell command/navigation menus | 菜单项、禁用条件、错误提示、快捷键语义 |
|
||||
| DRO X/Y/Z、machine/relative/commanded/actual | authoritative snapshot panel | 三轴数值、单位、位置反馈模式、tick 更新和 hash |
|
||||
| Manual/F3、MDI/F5、Auto tabs | Radix/Web tabs | tab order、aria-controls、模式切换、运行中禁用规则 |
|
||||
| G-code editor/program list | Web editor/project workflow | load/edit/reload/run/line seek、当前行、错误行 |
|
||||
| Preview/Gremlin plot | Three.js machine view | nonblank canvas、轨迹、坐标系、刀具/机床 pose 与 Worker 一致 |
|
||||
| Jog controls/increments | manual control panel | X/Y/Z jog、continuous/incremental、速度、stop、home |
|
||||
| Home Axis/Unhome/limits | axis controls | 每轴 home sequence、limit override、blocked reason |
|
||||
| Feed/spindle overrides | sliders/step controls | range、实时反映、非有限/超限拒绝 |
|
||||
| Spindle/coolant | device panel | RPM/direction/at-speed、mist/flood/lube、故障和 interlock |
|
||||
| Tool table/tool touch off | tool panel | tool/pocket/offset、prepare/change、probe/touch-off、错误可见 |
|
||||
| ESTOP/OFF/ON/Recover | safety controls | ESTOP latch、动作禁用、recover 后状态和 event cursor |
|
||||
| status/error/operator messages | state/error panel | native message key/source line/code、可追踪 hash |
|
||||
| keyboard shortcuts | Web keyboard command map | F3/F5、jog、run/pause/abort、焦点和重复触发规则 |
|
||||
|
||||
### 4.2 界面完成条件
|
||||
|
||||
- DOM controls、labels、ARIA tab/tabpanel 关系和 keyboard map 全部通过。
|
||||
- 每个控件都绑定一个 Worker command 或明确的 `HOST_EXCLUDED/REAL-EXCLUDED` 诊断；不得存在“看得见但无效”的装饰控件。
|
||||
- 控件 enable/disable 条件来自同一 Task/IO authoritative snapshot；不能由 React 本地猜测状态。
|
||||
- 桌面与移动 viewport 均验证布局不重叠；Three.js canvas 必须有非空像素和可变 pose。
|
||||
- AXIS 与 Web 对同一操作序列输出相同的可观察状态字段、错误键和 checkpoint endpoint hash；UI 像素差异必须单独记录，不能掩盖行为差异。
|
||||
|
||||
## 5. 任务分解
|
||||
|
||||
| ID | 任务 | 主要输入 | 主要输出/验收 | 依赖 |
|
||||
|---|---|---|---|---|
|
||||
| `AXIS3-00` | 锁定案例和 native runner | `axis.ini`、exact resources、`scripts/linuxcnc.in` | 可见 AXIS 窗口证据、窗口 geometry、source/resource hashes、native log | 无 |
|
||||
| `AXIS3-01` | 完整 source/resource graph | INI、HAL、tool/var、HALLIB、`inifile`/`resource-resolver` 源 | 0 unresolved exact resources；include/HAL 顺序、optional/shared asset 和 runtime file policy | AXIS3-00 |
|
||||
| `AXIS3-02` | native/Web startup phase parity | `linuxcnc.in`、`taskclass.cc`、`ioControl.cc`、`configuration-startup.mjs` | 阶段映射、首个 divergence、每阶段 hash；两端 `TASK_READY` | AXIS3-01 |
|
||||
| `AXIS3-03` | 3-axis trivkins/motion parity | `trivkins.c`、motion/homing/TP 源、axis/joint INI | home、jog、limit、following error、1x/fast endpoint parity | AXIS3-02 |
|
||||
| `AXIS3-04` | RS-274/program/MDI parity | `rs274ngc/interp_*`、G-code tests、`program-runtime.mjs` | modal/units/G0/G1/M2、MDI、pause/resume/abort/restart、line diagnostics | AXIS3-03 |
|
||||
| `AXIS3-05` | HAL/IO/tool/spindle/coolant parity | 6 HAL files、tooldata/ioControl、sim components | HAL records、spindle encoder/at-speed、tool lifecycle、coolant/IO/probe/fault matrix | AXIS3-02, AXIS3-03 |
|
||||
| `AXIS3-06` | workspace/parameter/tool persistence parity | `restore_parameters/save_parameters`、tooldata writer、WorkspaceRuntime/OPFS | startup empty/missing semantics、exit commit、journal/checkpoint/replay、no duplicate side effects | AXIS3-04, AXIS3-05 |
|
||||
| `AXIS3-07` | AXIS shell and navigation parity | `axis.py`、AXIS Tcl/Python UI source、React AppShell | menus, tabs, labels, shortcuts, focus, accessibility and enable gates | AXIS3-02 |
|
||||
| `AXIS3-08` | controls and machine-view parity | AXIS controls/Gremlin/graphics、Three.js panels | DRO, jog/home, overrides, tool/spindle/coolant/estop panels, nonblank 3D/plot and mobile layout | AXIS3-03, AXIS3-05, AXIS3-07 |
|
||||
| `AXIS3-09` | integrated native/WASM/Worker/UI acceptance | all previous reports, browser visual/performance/recovery evidence | one deterministic operation script; native window + Worker endpoint + UI DOM/canvas + recovery hash; explicit blockers | AXIS3-00..08 |
|
||||
|
||||
每个任务必须新增或更新一个专项测试和自哈希报告；状态只能是 `queued → in_progress → verified` 或 `in_progress → blocked`。`verified` 只表示该层和依赖层通过，不代表 LinuxCNC 全功能 release。
|
||||
|
||||
## 6. 统一验收操作序列
|
||||
|
||||
对 native AXIS 和 Web Worker 使用同一逻辑操作序列（时间由逻辑 tick 表示）：
|
||||
|
||||
1. 启动案例并确认 AXIS panel/Worker `TASK_READY`。
|
||||
2. 三轴全 home，记录每轴 home 状态和位置。
|
||||
3. X/Y/Z 增量 jog，记录 commanded/actual/relative DRO、速度和 endpoint hash。
|
||||
4. 切换 Manual→MDI，执行 `G21 G90`、`G0 X0 Y0 Z0`、`G1 X10 Y5 F120`、`M2`，比较 modal、轨迹和当前行。
|
||||
5. Auto 运行同一程序，执行 pause/resume/step/abort/restart，比较 task/program 状态。
|
||||
6. 设置 spindle RPM/direction、等待 at-speed、切换 mist/flood/lube，执行 tool prepare/change/abort。
|
||||
7. 注入 limit、following error、probe、coolant/IO fault 和 ESTOP，比较错误键、禁用控件、recover 结果。
|
||||
8. 创建 checkpoint，继续一步，再恢复；比较连续和恢复 endpoint/event/state hash。
|
||||
9. 退出/重启，确认参数/工具 workspace commit、journal cursor 和面板初始状态一致。
|
||||
|
||||
## 7. 不得伪装成完整对标的边界
|
||||
|
||||
- native 安装包与锁定源码版本不一致时，必须记录版本差异；不能把安装包行为当作官方 source oracle。
|
||||
- 实时内核、RTAPI 真实调度、PCI/串口/真实硬件和宿主动态 loader 保留 `REAL-EXCLUDED` 或 `HOST_EXCLUDED`。
|
||||
- Firefox/Safari minimum matrix、OPFS 物理崩溃恢复和官方 LinuxCNC 全状态 oracle 未完成前，整体验收保持 `blocked/STOP_RELEASE`。
|
||||
- AXIS 面板可见是 native 启动必要证据，但不等于功能、流程和 Web UI 三层都已对齐；三层报告必须同时 verified。
|
||||
Reference in New Issue
Block a user