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

7.6 KiB
Raw Permalink Blame History

3axis Tutorial 案例对标实施文档

唯一案例：linuxcnc/configs/sim/axis/vismach/3axis-tutorial 入口 INI：linuxcnc/configs/sim/axis/vismach/3axis-tutorial/3axis-tutorial.ini 机床：3 轴笛卡尔、trivkins、X/Y/Z、3 joints、AXIS + Vismach 范围：LinuxCNC 源程序案例与 Web/WASM 仿真的功能、流程、界面三层对标 状态：单案例执行、功能、流程、界面、真实 individual home、真实 change_button tool ACK 和恢复证据已闭合；完整 235-case/release 仍不在本案例范围

完成总报告：coverage/axis3-tutorial-complete.report.json

下一阶段总控方案：linuxcnc-web-wasm-3axis-tutorial-complete-parity-plan.md。

状态机契约：linuxcnc-web-wasm-3axis-tutorial-state-machine.md。

持久化图片证据：native AXIS native-axis.png、Chromium desktop chromium-desktop.png、Chromium mobile chromium-mobile.png。

后续工作只允许围绕这个案例展开。其它 configs/sim 案例、全量 matrix、其它机床族和 release closure 不属于本任务。

1. 已锁定的 exact 输入

案例目录中仅以下四个文件由 native runner 复制到隔离可写目录：

文件 用途
3axis-tutorial.ini AXIS、Task、RS-274、HAL、TRAJ、KINS、AXIS/JOINT limits
3axis-tutorial.hal trivkins/motion/ddt/hypot、estop、manual toolchange、Vismach pins
3axis-tutorial LinuxCNC Vismach Python model；Web 侧对应 Three.js model adapter
tool.tbl 工具表和 tool-change 输入

运行时生成的 3axis-tutorial_mm.var、.bak、position_mm.txt 不复制为 source fixture，由 LinuxCNC/Web workspace 在运行时创建或提交。INTRO_GRAPHIC = linuxcnc.gif 通过 linuxcnc/linuxcnc.gif 共享资产语义解析。

源程序关联：

  • 启动：linuxcnc/scripts/linuxcnc.in、linuxcnc/scripts/update_ini。
  • INI：linuxcnc/src/libnml/inifile/**、linuxcnc/src/emc/ini/**。
  • Task/IO：linuxcnc/src/emc/task/**、linuxcnc/src/emc/iotask/ioControl.cc、linuxcnc/src/emc/tooldata/**。
  • Motion/Kinematics：linuxcnc/src/emc/motion/**、linuxcnc/src/emc/kinematics/trivkins.c、linuxcnc/src/emc/tp/**。
  • HAL：案例 3axis-tutorial.hal、linuxcnc/src/hal/hal_lib.c、linuxcnc/src/hal/utils/halcmd*、linuxcnc/src/hal/components/{ddt,hypot,sim_home_switch}.comp。
  • Vismach：linuxcnc/configs/sim/axis/vismach/3axis-tutorial/3axis-tutorial、linuxcnc/lib/python/vismach.py、linuxcnc/lib/python/hal.py、linuxcnc/lib/python/linuxcnc.py。
  • AXIS UI：linuxcnc/src/emc/usr_intf/axis/scripts/axis.py、linuxcnc/lib/python/rs274/glcanon.py。

2. 正确 native 执行规约

执行器为 scripts/run_axis3_tutorial_native.py，报告为 coverage/axis3-tutorial-native-run.report.json。

  1. 创建临时可写目录。
  2. 只复制上表四个 exact source files。
  3. 在副本上运行官方 update_ini -f，因为源 INI 的 VERSION = 1.0 会触发 LinuxCNC 的配置升级流程。
  4. 保持 LinuxCNC 源程序目录 /home/mes006/linuxcncWebWASM/linuxcnc cwd、系统 HALLIB_DIR、真实 DISPLAY。
  5. 先退出旧 LinuxCNC 服务（linuxcncsvr、rtapi_app、milltask、halui、axis）并确认 /tmp/linuxcnc.lock 不再被活动服务持有；然后在 /home/mes006/linuxcncWebWASM/linuxcnc 源程序目录执行 linuxcnc <case_dir>/3axis-tutorial.ini。
  6. 轮询 X11 window tree；只有 WM class axis / Axis、标题含 3axis-tutorial、几何至少 600x400 才算成功。
  7. 记录 update hash、source hash、生成文件、native log hash 和启动诊断。

已验证结果：AXIS 2.10.0~pre1 窗口 1300x1293，标题 AXIS ... on 3axis-tutorial，LinuxCNC task 正常运行，生成 parameter/position 文件。

3. Web/WASM 对标流程

Web loader 固定入口为同一 3axis-tutorial.ini：

  1. 解析 exact INI 和 3axis-tutorial.hal。
  2. 获取 tool.tbl、共享 intro graphic 和 Vismach Python executable。
  3. 对缺失 3axis-tutorial_mm.var 生成空 parameter workspace file，并记录 data_hash。
  4. 将案例 loadusr -W ./3axis-tutorial 识别为唯一的 WEB-EQUIV Vismach adapter；任意其它 loadusr 仍 blocked。
  5. 用同一 trivkins、3 joints、X/Y/Z 配置启动 Worker。
  6. Three.js 使用 Worker 的 joints/pose/toolpath snapshot，不直接运行宿主 Python GUI。

4. 功能对标任务

ID 任务 完成条件
TUTORIAL-00 锁定案例和 native runner native AXIS 可见窗口 verified；exact source/update/generated hashes 有报告
TUTORIAL-01 exact resource/INI graph INI、HAL、tool、var、intro、Vismach executable 路径和 source line 全部可追踪
TUTORIAL-02 HAL/Vismach adapter 3axis-tutorial.hal 的 loadrt/addf/net/loadusr 通过 Web 等价 adapter；非该程序的宿主 loader 仍 blocked
TUTORIAL-03 Task startup Worker 阶段映射到 TASK_READY；startup hash 与资源 hash 稳定
TUTORIAL-04 三轴 motion home、X/Y/Z jog、速度/加速度、limit、following error、trivkins pose/joint 一致
TUTORIAL-05 RS-274/MDI mm units、G90/G91、G0/G1、feed、M2、MDI、pause/resume/step/abort/restart 一致
TUTORIAL-06 Tool/IO tool.tbl、prepare/change、source hal_manualtoolchange.change_button ACK、spindle/at-speed、冷却、probe、estop/recover 一致
TUTORIAL-07 Vismach model Python model 的 jointX/Y/Z、toollength、tooldiameter pin 语义映射到 Three.js，姿态不跳变
TUTORIAL-08 AXIS UI 菜单、DRO、Manual/MDI、G-code、Preview、jog/home、tool/spindle/coolant/estop、错误和快捷键对标
TUTORIAL-09 persistence/recovery var/tool/position workspace commit、checkpoint、journal、replay、重启恢复无重复副作用
TUTORIAL-10 integrated acceptance native panel、Worker state、Three.js canvas、DOM controls、operation/event/checkpoint hashes 同一操作序列通过

每项必须有专项测试、正常/边界/错误样本、source/data hash 和 self-hashed report。不能用 timeout、后台 task: 或静态 catalog READY 代替真实结果。

5. 统一对标操作序列

  1. native/Web 启动并确认 AXIS panel / Worker TASK_READY。
  2. 按源 AXIS 语义依次执行 Z、X、Y individual home，记录 X/Y/Z pose、joint 和 homed 状态。
  3. 分别 jog X/Y/Z，记录 position/velocity/limit。
  4. 加载并运行 G21 G90、G0 X0 Y0 Z0、G1 X10 Y5 F120、G1 Z-1、M2。
  5. 执行 MDI、pause、resume、step、abort、restart。
  6. prepare/change tool 1，启停主轴，等待 at-speed，切换 coolant。
  7. 注入 limit、following error、probe 和 ESTOP，检查错误码、禁用控件和 recover。
  8. checkpoint 后继续一个 tick，再恢复并比较 endpoint/event/state hash。
  9. 退出并重启，比较 var/position/tool workspace state。

6. 明确边界

  • 3axis-tutorial Python 模型在 Web 中是源码驱动的 WEB-EQUIV Three.js adapter，不运行宿主 Python 进程。
  • POSIX fallback 只说明 native 仿真可以运行，不是实时内核或硬件验证。
  • AXIS native window 是启动成功必要条件；完整对标仍需功能、流程、界面三层分别通过。
  • 其它案例、浏览器矩阵、OPFS 物理崩溃、官方 oracle 和 release acceptance 不在本案例任务范围内。
Reference in New Issue View Git Blame Copy Permalink