14 KiB
14 KiB
三轴 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
本规格把“完全对标”定义为同一个案例的三层可观察等价：
- 功能等价：运动、解释器、HAL、IO、工具、主轴、冷却、回零、限位、急停、MDI、程序控制和恢复的结果、错误和边界一致。
- 流程等价：从选择 INI 到配置解析、资源装载、HAL/Task/IO 启动、显示启动、运行、停止和清理的阶段、顺序、诊断和状态迁移一致。
- 界面等价：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 流程
- 解析
axis.ini，展开#INCLUDE，检查版本和 config。 - 读取
PARAMETER_FILE、EMCMOT、EMCIO、TASK、DISPLAY、NML 和 TRAJ/KINS。 cd INI_DIR，解析INTRO_GRAPHIC，启动 AXIS splash。- 启动
linuxcncsvr、RTAPI/HAL、IO、HALUI。 - 按
[HAL]HALFILE顺序加载core_sim.hal、sim_spindle_encoder.hal、axis_manualtoolchange.hal、simulated_home.hal、check_xyz_constraints.hal、cooling.hal。 - 启动
milltask，执行 HALCMD，最后启动 AXIS 面板。 - 用户执行 home/jog/MDI/program/tool/spindle/coolant/probe/estop/recover。
- 关闭 AXIS 后执行 Cleanup、保存参数、停止 HAL/RTAPI、删除 NML/锁文件。
3.2 Web 流程
- exact-path loader 建立 bundle，补齐运行时生成资源并记录 hash。
- WorkspaceRuntime 挂载，INI/include/resource graph 解析完成后才允许 startup。
- WASM core 创建并加载 workspace；HAL preflight 依照 native 文件顺序执行。
- Dedicated Worker attach Task，发布
CAPABILITIES/SESSION_READY。 LOAD_WORKSPACE进入TASK_READY，React AppShell 绑定 snapshot/event。- 所有用户操作经
command-envelope.v1进入 Worker；固定 tick 更新 interpreter→TP→IK→motion→HAL→IO→publish。 - 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 表示）：
- 启动案例并确认 AXIS panel/Worker
TASK_READY。 - 三轴全 home，记录每轴 home 状态和位置。
- X/Y/Z 增量 jog，记录 commanded/actual/relative DRO、速度和 endpoint hash。
- 切换 Manual→MDI，执行
G21 G90、G0 X0 Y0 Z0、G1 X10 Y5 F120、M2，比较 modal、轨迹和当前行。 - Auto 运行同一程序，执行 pause/resume/step/abort/restart，比较 task/program 状态。
- 设置 spindle RPM/direction、等待 at-speed、切换 mist/flood/lube，执行 tool prepare/change/abort。
- 注入 limit、following error、probe、coolant/IO fault 和 ESTOP，比较错误键、禁用控件、recover 结果。
- 创建 checkpoint，继续一步，再恢复；比较连续和恢复 endpoint/event/state hash。
- 退出/重启，确认参数/工具 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。