wangdequan/linuxcncWebWASM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
23d07e72d17067022b27f6e039bcb0054a46c242
linuxcncWebWASM/docs/linuxcnc-web-wasm-3axis-tutorial-complete-parity-plan.md

13 KiB
Raw Blame History

3axis Tutorial 全功能对标总方案

0. 目标和执行边界

唯一目标案例：

/home/mes006/linuxcncWebWASM/linuxcnc/configs/sim/axis/vismach/3axis-tutorial

入口文件：

linuxcnc/configs/sim/axis/vismach/3axis-tutorial/3axis-tutorial.ini

目标不是“再做一个示例”，而是把该案例在 LinuxCNC 中可观察的配置、启动、运动、解释器、HAL、工具、主轴、冷却、探针、Vismach、AXIS UI、持久化和恢复行为逐项映射到 WASM + Dedicated Worker + React + Three.js。后续任务不得切换到其它 configs/sim 案例；其它案例只能作为通用模块回归输入，不能作为本案例完成证据。

明确排除：实时内核调度、真实硬件、PCI/串口设备、宿主动态 loader、宿主 Python GUI 进程。排除项必须有 REAL-EXCLUDED/HOST_EXCLUDED 诊断，不得静默删除功能。

1. 锁定输入和执行规约

1.1 Exact 输入

输入 作用 规则
3axis-tutorial.ini AXIS、Task、RS-274、TRAJ、EMCIO、KINS、AXIS/JOINT limits 原路径、原始字节和 source line 保留
3axis-tutorial.hal trivkins/motmod/ddt/hypot、反馈环、手动换刀、Vismach pins 按原顺序解析 loadrt/addf/net/loadusr
3axis-tutorial Vismach Python model 和 5 个 HAL pins Web 使用源码驱动 WEB-EQUIV adapter，不运行宿主 Python
tool.tbl T1/T2/T3/T99999 工具、长度和直径 exact path；工具状态必须可恢复
linuxcnc/linuxcnc.gif DISPLAY.INTRO_GRAPHIC 仅作为 shared display asset
runtime .var/.bak/position_mm.txt 参数、备份、位置持久化 运行时生成，写入 workspace journal，不作为 source fixture

1.2 Native 标准命令

每次运行前必须停止本 runner 或历史运行留下的 linuxcncsvr、rtapi_app、milltask、halui、iocontrol、axis，确认没有活动进程持有 /tmp/linuxcnc.lock；只允许在 lock 无活动持有者时删除 stale lock。

然后固定使用：

cd /home/mes006/linuxcncWebWASM/linuxcnc
linuxcnc <isolated-case-dir>/3axis-tutorial.ini

成功条件同时包括：

  • update_ini -f 在隔离目录成功；
  • AXIS WM class 为 axis / Axis；
  • 标题含 3axis-tutorial；
  • 窗口至少 600x400；
  • native log 没有未分类首错；
  • 记录生成的 .var/.bak/position_mm.txt；
  • 退出后 LinuxCNC 服务和 lock 清理完成。

禁止用 timeout、Starting LinuxCNC、后台 task:、进程存在或 lock 文件存在替代窗口证据。

2. 全功能对标清单

2.1 配置、资源和流程

  1. VERSION/MACHINE/DEBUG 解析和 update_ini 迁移。
  2. [DISPLAY]：AXIS、cycle time、relative/actual 初始显示、feed/spindle override、increments、program prefix、intro graphic、file filters。
  3. [RS274NGC]：参数文件路径、缺失文件空初始化、保存和 .bak 策略。
  4. [EMCMOT]/[TASK]/[EMCIO]：motmod、milltask、io、cycle/servo period、tool table、tool-change position。
  5. [TRAJ]：3 axes、XYZ、mm/degree、速度、加速度、position file、arc blend 参数。
  6. [KINS]/[AXIS_X/Y/Z]/[JOINT_0/1/2]：trivkins identity、limits、velocity、acceleration、scale、FERROR、MIN_FERROR、home offset。
  7. HAL 文件和 LIB:/相对路径解析保持 exact path、行号、顺序、缺失诊断。
  8. 启动状态映射：NEW -> MOUNTED -> PARSED -> RESOLVED -> CORE_CREATED -> HAL_READY -> TASK_READY。
  9. 退出状态映射：停止、HAL unload、服务退出、参数/位置提交和 journal close。

2.2 运动、Task 和解释器

  1. MANUAL/MDI/AUTO 模式和 READY/RUNNING/PAUSED/STOPPED/ESTOP/FAULT 状态。
  2. X/Y/Z 全部 home、独立 jog、连续/增量 jog、stop、速度/加速度、override。
  3. trivkins pose/joint identity、commanded/actual/relative DRO。
  4. X [-500,500]、Y [-100,100]、Z [-240,0.001] limits。
  5. following error、limit fault、fault latch、recover 和禁用条件。
  6. G20/G21、G90/G91、G0/G1、F feed、G17/G40/G49/G54/G64、G10/G92、M2/M30、参数表达式和错误列。
  7. PROGRAM_LOAD/RUN/PAUSE/RESUME/STEP/SEEK/ABORT/RESTART、MDI 队列和活动程序期间 MDI 拒绝。
  8. fixed tick 1x/fast/step 与 pause/recovery endpoint parity。

2.3 HAL、工具、主轴、冷却、探针和故障

  1. trivkins、motmod、6 个 ddt、2 个 hypot 的 component/thread/function 记录。
  2. 三轴 motor-pos-cmd 到 motor-pos-fb 的 loopback。
  3. velocity/acceleration 派生信号 Xvel/Yvel/Zvel/XYvel/XYZvel。
  4. estop loopback、hal_manualtoolchange prepare/change/changed 生命周期。
  5. Vismach pins：jointX/jointY/jointZ/toollength/tooldiameter，pin direction/type 和 net 连接。
  6. T1/T2/T3/T99999 prepare、pocket、change、abort、fault、clear。
  7. spindle direction/RPM、ramp、at-speed、encoder/index、inhibit、orient、fault。
  8. mist/flood/lube request、interlock、coolant fault 和恢复。
  9. probe arm/input/trip/latched position/disarm；没有 source pin 时保留 capability boundary。
  10. ESTOP、door/interlock、following-error、limit、tool/spindle/coolant fault 的错误码、message key、状态 hash 和 UI gate。

2.4 Vismach 和 AXIS UI

  1. frame/base/column/top、X table/work、Y assembly、Z frame/spindle、CAT30/tool/tooltip 的几何层次。
  2. HalTranslate 对 jointX/Y/Z 的轴向变换和工具长度/直径变化。
  3. tool cylinder 半径、z offset、当前工具和 tooltip 连续性。
  4. AXIS File/Machine/View/Help 菜单、快捷键、toolbar icon、F3 Manual、F5 MDI、Preview、DRO、G-code editor、active G-codes。
  5. DRO machine/relative、actual/commanded、mm/inch、tick/hash。
  6. Three.js canvas 非空像素、pose/joint/toolpath/limits/layers、desktop/mobile 不重叠。
  7. 控件 enable/disable 必须来自 Worker snapshot；所有不可用操作必须显示诊断。

2.5 持久化、恢复和证据治理

  1. .var 缺失/空文件/参数写入/.bak 生成/重启恢复。
  2. position_mm.txt 保存、读取、恢复和错误处理。
  3. tool.tbl 读取、工具状态更新、workspace commit 和重启恢复。
  4. checkpoint、event cursor、journal、trace import、replay endpoint equality。
  5. recovery 不重复已提交副作用；坏 checkpoint、seq gap、tick regression、未知 event 必须 fail-closed。
  6. 每个报告保存 context id、输入 hash、输出 hash、命令、首个 divergent phase/tick、失败样本和 self-hash。

3. 实施任务和依赖

ID 实施结果 主要输出 依赖
TUTORIAL-00 锁定源目录、隔离副本、服务清理和 native AXIS runner native report + AXIS screenshot 无
TUTORIAL-01 exact INI/HAL/resource graph 和 runtime file policy resource graph report 00
TUTORIAL-02 HAL manifest、loadrt/addf/net、Vismach WEB-EQUIV adapter HAL adapter report 01
TUTORIAL-03 startup phase、TASK_READY、loader/startup hash startup report 01/02
TUTORIAL-04 home/jog/limit/FERROR/trivkins fixed tick motion report 03
TUTORIAL-05 RS-274/G-code/MDI/program controls program report 04
TUTORIAL-06 tool/spindle/coolant/probe/ESTOP/IO full matrix tool-io report 03/05
TUTORIAL-07 Vismach geometry graph、pin-to-pose、tool continuity model report + canvas samples 02/04/06
TUTORIAL-08 AXIS menus、DRO、tabs、editor、gates、mobile layout DOM/visual report 03/05/07
TUTORIAL-09 var/tool/position commit、checkpoint/journal/replay persistence report 05/06/08
TUTORIAL-10 same operation sequence native/Worker/UI integrated acceptance complete scoped report 00..09
TUTORIAL-11 probe and complete tool-offset behavior closure probe/tool report + native/Worker diff 06/09/10
TUTORIAL-12 native/Web same-sequence recorder and first-divergence report sequence ledger + endpoint comparison 10/11
TUTORIAL-13 persistence restart with explicit service/lock cleanup and visual recovery evidence restart report + screenshots 09/12
TUTORIAL-14 final selected-case acceptance freeze and evidence index signed/self-hashed closure index 11/12/13

当前 TUTORIAL-00..10 的已验证报告必须继续复用；下一阶段从 TUTORIAL-11 开始，不得重复创建其它案例任务。

当前执行状态：TUTORIAL-11 verified；TUTORIAL-12 verified with source-defined individual Z/X/Y homing and real change_button ACK；TUTORIAL-13 verified after replay-order fix；TUTORIAL-14 verified as selected-case closure index. Firefox/Safari、OPFS physical crash、realtime hardware 和 full release 仍是独立外部边界。

4. 统一实施顺序

每个任务执行以下固定步骤：

  1. 读取 nextTask1.md、context lock 和本任务直接输入。
  2. 服务清理；native exact command；保留截图、日志和 source hash。
  3. 先新增失败边界测试，再实现最小 vertical slice。
  4. Worker 使用真实 WASM 和固定 logical tick；不使用 mock Worker 作为完成证据。
  5. React 只消费 Worker authoritative state；UI gate、错误和状态不能本地猜测。
  6. 运行任务专项测试、native CTest、WASM build、selected-case Worker/App 回归。
  7. 生成 self-hashed report，记录正常、边界、错误、非有限、容量、暂停/恢复/终止和确定性 hash。
  8. 只有当前任务达到验收条件才更新指针；若输入、oracle 或环境缺失，保留 blocked 和 failure sample。

5. 验证计划

5.1 基线和构建

python3 scripts/validate_baseline.py
python3 scripts/validate_task_pointer.py nextTask1.md
scripts/build-wasm.sh
ctest --test-dir build-native --output-on-failure
cd web/react && npm run typecheck && npm run build

5.2 Native 验证

python3 scripts/run_axis3_tutorial_native.py \
  --output coverage/axis3-tutorial-native-run.report.json \
  --screenshot coverage/axis3-tutorial-visual/native-axis.png
python3 scripts/test_axis3_tutorial_native.py

必须检查：窗口 class/title/geometry、服务清理、lock、exact source hashes、生成文件、首错和截图 hash。

5.3 Worker/WASM 验证

node web/worker/test_axis3_selected_case.mjs
node web/worker/test_axis3_tutorial_hal_adapter.mjs
node web/worker/test_axis3_tutorial_startup.mjs
node web/worker/test_axis3_tutorial_motion.mjs
node web/worker/test_axis3_tutorial_program.mjs
node web/worker/test_axis3_tutorial_tool_io.mjs       # TUTORIAL-06/11
node web/worker/test_axis3_tutorial_persistence.mjs   # TUTORIAL-09/13
node web/worker/test_axis3_tutorial_sequence.mjs     # TUTORIAL-12

每个 Worker endpoint 必须同时记录 task/program/motion/joints/devices/hal/authoritative/state_hash，不能只断言 status=verified。

5.4 React/Chromium 验证

npm --prefix web/react run preview -- --port 5174
python3 scripts/generate_gui_browser_visual_report.py
python3 scripts/test_gui_browser_visual_report.py

桌面 1440x900 和移动 390x844 都必须有：DOM marker、4 tabs/tabpanel 关系、至少 20 toolbar icons、ARIA labels、非空截图、Three.js canvas、case selector、DRO、G-code、Manual/MDI 和无重叠布局。

5.5 Integrated acceptance

python3 scripts/generate_axis3_tutorial_complete_report.py
python3 scripts/test_axis3_tutorial_complete_report.py
python3 scripts/validate_baseline.py
python3 scripts/validate_task_pointer.py nextTask1.md

统一逻辑序列：启动 -> 全轴 home -> X/Y/Z jog -> override -> MDI -> G-code load/run -> pause/resume/step -> abort/restart -> tool prepare/change -> spindle/at-speed -> coolant -> probe -> limit/FERROR/ESTOP -> checkpoint -> 继续一个 tick -> recover -> persistence restart。native、Worker 和 UI 必须使用同一操作 ID 顺序；时间只用 logical tick。

6. 通过、阻塞和停止条件

通过

  • exact path 和 source hash 一致；
  • native AXIS 窗口真实可见；
  • Worker TASK_READY 且 HAL blocked count 为 0；
  • native/Worker endpoint 和恢复 hash 可解释；
  • UI 证据有持久化图片、DOM hash 和 canvas 非空；
  • report self-hash 和 pointer validation 通过。

保持 blocked

  • native 服务或 lock 未清理；
  • 首个 divergent tick/phase 未定位；
  • probe/tool offset 没有 source 或实现契约；
  • checkpoint/event/hash 不可验证；
  • 只能依赖墙钟、随机数、宿主 Python、mock Worker 或真实硬件；
  • Firefox/Safari/OPFS/oracle 外部条件缺失。

不得宣称

该方案的 verified 只代表固定 3axis-tutorial 选定案例范围。它不代表 LinuxCNC 全功能、235-case acceptance、实时硬件、Firefox/Safari release 或 owner/license gate 已完成。

7. 当前证据索引

  • 总报告：coverage/axis3-tutorial-complete.report.json
  • Native：coverage/axis3-tutorial-native-run.report.json
  • Resource graph：coverage/axis3-tutorial-resource-graph.report.json
  • Program：coverage/axis3-tutorial-program.report.json
  • Chromium visual：coverage/gui-browser-visual-fe-m4.report.json
  • 图片目录：coverage/axis3-tutorial-visual/
  • 接续入口：nextTask1.md
Reference in New Issue View Git Blame Copy Permalink