Document AXIS Web WASM control flowcharts

2026-09-03 09:15:25 +08:00
parent 03c7fdf8f0
commit 0f6691a9fc
2 changed files with 273 additions and 0 deletions
--- a/docs/linuxcnc-axis-web-wasm-detailed-flowcharts.md
+++ b/docs/linuxcnc-axis-web-wasm-detailed-flowcharts.md
@@ -0,0 +1,272 @@
+# LinuxCNC AXIS Web/WASM 控制面板详细技术流程图
+
+更新时间：2026-09-03
+
+本文将 LinuxCNC AXIS 的可见控制入口、按钮相互制约关系、WASM 命令、状态回执和显示数据画成可执行流程。目标案例为 XYZAC TRT；所有程序、运动和设备结果必须来自 LinuxCNC WASM，React 只负责输入、传输、投影和显示。
+
+## 1. 总体技术边界
+
+~~~mermaid
+flowchart LR
+    USER[用户] --> APP[React AXIS UI]
+    APP --> CLIENT[WorkerClient]
+    CLIENT --> WORKER[Dedicated Worker]
+    WORKER --> SESSION[SimSession]
+    SESSION --> GATE[WASM Task gate]
+    GATE --> RUNTIME[LinuxCNC WASM runtime]
+    RUNTIME --> INTERP[WASM interpreter]
+    RUNTIME --> TP[LinuxCNC source TP]
+    RUNTIME --> KINS[WASM kinematics]
+    RUNTIME --> IO[WASM HAL/IO]
+    RUNTIME --> SNAP[panel_snapshot]
+    SNAP --> CLIENT
+    CLIENT --> APP
+~~~
+
+## 2. 全部按钮矩阵
+
+| 控件 | WASM 命令 | 前置条件 | 互斥/阻断 | 成功后 |
+| --- | --- | --- | --- | --- |
+| Emergency Stop | ESTOP | session ready | 无，最高优先级 | ESTOP |
+| Release E-stop | ESTOP false | machine=ESTOP | 非 ESTOP 禁用 | ESTOP_RESET |
+| Power On | POWER true | non-estop、无 fault | estop/fault/spindle busy | ON |
+| Power Off | POWER false | ON | OFF 时禁用 | OFF，程序保留 |
+| Reset | RESET | reset gate | WASM gate 决定 | task/IO reset |
+| HOME ALL | HOME all | ON、manual_ok | OFF/ESTOP/运行中 | 五轴 homed |
+| Run | PROGRAM_RUN | ON、homed、loaded | running/paused/aborted | RUNNING |
+| Pause | PROGRAM_PAUSE | RUNNING | 不得和 Resume 并发 | PAUSED，保留 queue |
+| Resume | PROGRAM_RESUME | PAUSED | 不得和 Pause 并发 | RUNNING |
+| Stop | PROGRAM_ABORT | RUNNING/PAUSED | 先停止 poll | STOPPED，queue=0 |
+| Step | PROGRAM_STEP | AUTO、queue idle | running 时禁用 | 单块后 PAUSED |
+| Restart | PROGRAM_RESTART | aborted/completed/loaded | 运行中禁用 | loaded |
+| Manual 页签 | SET_MODE MANUAL | 非运行 | running/paused 阻断 | MANUAL |
+| MDI 页签 | SET_MODE MDI | 非运行 | running/paused 阻断 | MDI |
+| Jog X/Y/Z/A/C | JOG_START | MANUAL、ON、homed | OFF/ESTOP/运行 | WASM TP queue |
+| Jog Stop | JOG_STOP | jog active | 不是 PROGRAM_PAUSE | queue=0 |
+| MDI Go | MDI_EXECUTE | MDI、ON、homed | running/queue full | MDI queue |
+| Spindle CW/CCW | SPINDLE_COMMAND | MANUAL、ON、IO ready | estop/fault | IO spindle state |
+| Spindle Stop | SPINDLE_COMMAND off | spindle gate | 不只改 UI | speed decays |
+| Brake | SPINDLE_BRAKE | spindle gate | IO busy/fault | brake state |
+| Mist/Flood | COOLANT_COMMAND | IO ready | estop/fault | device IO state |
+| Prepare/Change tool | TOOL_PREPARE/CHANGE | tool gate/handshake | running/fault | tool state |
+| Arm/Disarm probe | PROBE_CONFIG | probe gate | estop/fault | probe state |
+| Feed/Spindle/Max override | SET_* | override gate | out of range | WASM override |
+| Clear plot | VISUAL_CLEAR | session ready | 不清 program | visual empty |
+| Views/Zoom/DRO | UI projection | 任意 | 不改 runtime | camera/display |
+| Block delete/Optional pause | disabled | ABI unavailable | 不得 JS 模拟 | blocked_by_abi |
+| Override Limits | disabled | ABI unavailable | 不得 JS 模拟 | blocked_by_abi |
+
+### 2.6 逐控件完整索引
+
+| 区域 | 控件/按钮 | 命令或动作 | 必须启用时 | 必须禁用/互斥时 | 成功/变化后的唯一来源 |
+| --- | --- | --- | --- | --- | --- |
+| File menu | Reload editor | LOAD_WORKSPACE + PROGRAM_LOAD | 非运行、非加载中、load gate | RUNNING/PAUSED/loading | WASM program source、preview、source_hash |
+| File menu | Edit tool data | host boundary notice | 浏览器环境仅提示 | 不得伪造 desktop editor | command status |
+| File menu | Quit | host boundary notice | 浏览器标签页不退出进程 | 始终不可执行 desktop quit | command status |
+| Machine menu | Emergency Stop | ESTOP | session ready | 无互斥，最高优先级 | WASM IO/task ESTOP |
+| Machine menu | Power On/Off | POWER | power gate | estop/fault/busy 或已处于目标状态 | IO ready、axis_state |
+| Machine menu | Reset machine | RESET | reset gate | gate disabled 时 | WASM task/IO reset |
+| Machine menu | Run program | PROGRAM_RUN | run gate | OFF、未回零、running、paused、aborted | task/program RUNNING |
+| Machine menu | Step | PROGRAM_STEP | step gate | RUNNING 或 queue 非空 | 一个 WASM canonical block |
+| Machine menu | Pause | PROGRAM_PAUSE | pause gate | idle、paused、非 AUTO reading | task/program PAUSED |
+| Machine menu | Resume | PROGRAM_RESUME | resume gate | 非 paused | task/program RUNNING |
+| Machine menu | Stop | PROGRAM_ABORT | abort gate | 无活动程序时由 WASM gate 决定 | STOPPED、queue=0 |
+| View menu | Preview | 仅切换右侧 tab | 始终 | 不影响 runtime | visual snapshot |
+| View menu | DRO | 仅切换右侧 tab | 始终 | 不影响 runtime | pose/joints snapshot |
+| View menu | Manual Control | SET_MODE(MANUAL) | 非运行/暂停 | AUTO active | task.mode |
+| View menu | MDI | SET_MODE(MDI) | 非运行/暂停 | AUTO active | task.mode |
+| Toolbar | Open G-code file | file picker -> PROGRAM_LOAD | 非运行、非加载中 | RUNNING/PAUSED/loading | WASM program/preview |
+| Toolbar | Load exact XYZAC case | LOAD_WORKSPACE + PROGRAM_LOAD | load gate | running/loading | configuration/program snapshot |
+| Toolbar | Reopen editor defaults | LOAD_WORKSPACE + PROGRAM_LOAD | load gate、非运行 | running/loading | 默认案例 WASM preview |
+| Toolbar | Run current file | PROGRAM_RUN | run gate | 同 Run program | RUNNING |
+| Toolbar | Execute next line | PROGRAM_STEP | step gate | RUNNING/queue active | PAUSED/current line |
+| Toolbar | Pause/Resume icon | PROGRAM_PAUSE 或 PROGRAM_RESUME | 对应 gate | 状态相反时禁用 | PAUSED/RUNNING |
+| Toolbar | Stop icon | PROGRAM_ABORT | abort gate | 无活动时禁用 | STOPPED/aborted |
+| Toolbar | Block delete | 无当前 ABI | 始终禁用 | 不得 JS 模拟 | blocked_by_abi |
+| Toolbar | Optional pause | 无当前 ABI | 始终禁用 | 不得 JS 模拟 | blocked_by_abi |
+| Toolbar | Zoom in/out | view transform | 始终 | 不改变 runtime | camera zoom |
+| Toolbar | Top view | view=z | 始终 | 不改变 runtime | camera projection |
+| Toolbar | Rotated top view | view=z2 | 始终 | 不改变 runtime | camera projection |
+| Toolbar | Side view | view=x | 始终 | 不改变 runtime | camera projection |
+| Toolbar | Front view | view=y | 始终 | 不改变 runtime | camera projection |
+| Toolbar | Inverted front view | view=y2 | 始终 | 不改变 runtime | camera projection |
+| Toolbar | Perspective view | view=p | 始终 | 不改变 runtime | camera projection |
+| Toolbar | Drag/rotate mode | rotateMode | 始终 | 不改变 runtime | camera pose |
+| Toolbar | Clear live plot | VISUAL_CLEAR | session ready | 不清程序、不改 TP | visual layer |
+| XYZAC | Identity | KINEMATICS_SELECT(0) | queue=0、非运行 | active motion/queue | WASM switchkins active_type=0 |
+| XYZAC | TCP: XYZAC | KINEMATICS_SELECT(1) | queue=0、非运行 | active motion/queue | active_type=1 |
+| XYZAC | User K | KINEMATICS_SELECT(2) | queue=0、非运行 | active motion/queue | active_type=2 |
+| XYZAC | Clear plot | VISUAL_CLEAR | session ready | 不清程序 | visual layer |
+| Manual | Axis X/Y/Z/A/C radio | local selection | manual tab | 不直接产生 motion | next JOG payload |
+| Manual | Jog -/+ | JOG_START | MANUAL、ON、homed | running/MDI/off/estop | WASM TP queue |
+| Manual | Jog Stop | JOG_STOP | jog active/safe stop | 不得转为 PROGRAM_PAUSE | queue=0 |
+| Manual | Increment selector | JOG_START payload | MANUAL | 非法值由 WASM 拒绝 | TP increment |
+| Manual | Home Axis | HOME(axis) | home gate | running/estop/off | home_limit |
+| Manual | Home All | HOME(all=true) | home gate | running/estop/off | homed_axes |
+| Manual | Touch Off | MDI_EXECUTE(G92) | coordinate/MDI gate | running、ABI 不可用 | WASM coordinates |
+| Manual | Tool Touch Off | TOOL_TOUCH_OFF | 完整 ABI 可用时 | 当前配置 blocked_by_abi | WASM tool/coordinate |
+| Manual | Spindle CCW/CW | SPINDLE_COMMAND | MANUAL、IO ready | estop/fault/not ready | io.spindles[0] |
+| Manual | Spindle Stop | SPINDLE_COMMAND off | spindle gate | 不只改 pressed | speed/enable |
+| Manual | Spindle -/+ | SPINDLE_COMMAND delta | spindle gate | 范围错误 | command_rpm |
+| Manual | Brake | SPINDLE_BRAKE | spindle gate | IO busy/fault | brake |
+| Manual | Mist | COOLANT_COMMAND(mist) | coolant gate | estop/fault | device_io.coolant.mist |
+| Manual | Flood | COOLANT_COMMAND(flood) | coolant gate | estop/fault | device_io.coolant.flood |
+| Manual | Prepare T1 | TOOL_PREPARE | tool gate | running/fault | tool.prepared |
+| Manual | Change | TOOL_CHANGE | prepared/handshake | running/unprepared | current_tool/tool_state |
+| Manual | Arm Probe | PROBE_CONFIG(arm) | probe gate | estop/fault | probe.state |
+| Manual | Disarm | PROBE_CONFIG(disarm) | probe gate | estop/fault | probe.state |
+| MDI | Command input | local draft | MDI tab | 不直接执行 | input text |
+| MDI | Go | MDI_EXECUTE | MDI、ON、homed、queue 未满 | running/paused/off/full | WASM interpreter/TP |
+| MDI | History item | 回填 input | 始终 | 不直接执行 | input text |
+| Metrics | Jog Speed | SET_JOG_SCALE | jog gate | out of range | WASM TP scale |
+| Metrics | Feed Override | SET_OVERRIDE | override gate | loading/out of range | WASM feed override |
+| Metrics | Spindle Override | SET_SPINDLE_OVERRIDE | override gate | out of range | WASM spindle override |
+| Metrics | Max Velocity | SET_MAX_VELOCITY | override gate | out of range | WASM TP velocity |
+| Metrics | path/live/limits/velocity/offsets/extents | visual layer toggle | 始终 | 不改 runtime | existing snapshot fields |
+| Program | Load | PROGRAM_LOAD | load gate、非运行 | running/paused/loading | WASM source/preview |
+| Program | Run | PROGRAM_RUN | run gate | same Run constraint | program status |
+| Program | Step | PROGRAM_STEP | step gate | running/queue active | paused/current line |
+| Program | Editor text | local draft | 非运行可编辑 | 不等于 runtime load | PROGRAM_LOAD 后才生效 |
+| Program | Preview/DRO tab | local tab | 始终 | 不影响 runtime | existing snapshot |
+
+### 2.7 按钮互斥总图
+
+~~~mermaid
+flowchart TD
+    WASM[WASM snapshot] --> IOREADY{io.ready 且非 estop?}
+    IOREADY -->|否| SAFE[仅 ESTOP/Release/Power/Load 等安全动作]
+    IOREADY -->|是| MACHINE{machine_state=ON?}
+    MACHINE -->|否| POWER[Power On]
+    MACHINE -->|是| HOMED{homed_axes 五轴 true?}
+    HOMED -->|否| HOME[HOME ALL / HOME AXIS]
+    HOMED -->|是| MODE{task.mode}
+    MODE -->|MANUAL| MANUAL[JOG / spindle / coolant / tool / probe]
+    MODE -->|MDI| MDI[MDI Go / queued MDI]
+    MODE -->|AUTO| AUTO[Run / Pause / Resume / Step / Abort]
+    MANUAL --> RUNNING{program active?}
+    MDI --> RUNNING
+    RUNNING -->|是| BLOCKMAN[阻断 JOG / MDI / HOME / SET_MODE / switchkins]
+    RUNNING -->|否| ALLOWMAN[允许 manual_ok 等价动作]
+    AUTO --> PAUSEQ{program paused?}
+    PAUSEQ -->|否| PAUSE[Pause 可用]
+    PAUSEQ -->|是| RESUME[Resume 可用]
+    AUTO --> ABORT[Abort/Stop 始终受 abort gate]
+    ABORT --> ABORTED[program=aborted]
+    ABORTED --> RELOAD[Restart / Program Load]
+    RELOAD --> LOADED[program=loaded]
+    LOADED --> RUNQ{run gate enabled?}
+    RUNQ -->|是| RUN[Run]
+    RUNQ -->|否| WAIT[保持禁用并显示 gate reason]
+~~~
+
+### 2.8 按钮互斥规则的优先级
+
+发生多个条件时按下面优先级处理，优先级高的条件覆盖低优先级：
+
+1. ESTOP 和 fault：停止运动，禁用所有非安全运动/设备按钮。
+2. protocol/schema/sequence/tick 错误：拒绝当前命令，不执行副作用。
+3. machine OFF 或未上电：只允许 Power、Release/ESTOP、Reset、Load 等安全/准备动作。
+4. 未回零：允许 HOME，禁止依赖机床坐标的 JOG、MDI 和程序运行。
+5. AUTO/MDI 解释器运行：允许 Pause/Resume/Abort/Power Off/ESTOP，禁止 Manual、MDI、JOG、HOME、switchkins。
+6. PAUSED：只允许 Resume、Abort、Power、ESTOP 和只读 snapshot，禁止自动 SET_MODE。
+7. program aborted：必须 Restart 或重新 Load，禁止直接 Run。
+8. ABI unavailable：按钮必须保持 disabled，显示 blocked_by_abi，不得由 JavaScript 替代。
+
+任何按钮由禁用变为可用，都必须先收到新的 WASM snapshot；React 不得仅依据点击事件自行解除互斥。
+
+## 3. 机床状态图
+
+~~~mermaid
+stateDiagram-v2
+    [*] --> OFF
+    OFF --> ESTOP: ESTOP
+    ESTOP --> ESTOP_RESET: release
+    ESTOP_RESET --> ON: POWER ON
+    OFF --> ON: POWER ON
+    ON --> HOME: HOME ALL
+    HOME --> IDLE: all homed
+    IDLE --> RUNNING: RUN
+    RUNNING --> PAUSED: PAUSE
+    PAUSED --> RUNNING: RESUME
+    RUNNING --> STOPPED: ABORT
+    PAUSED --> STOPPED: ABORT
+    STOPPED --> ON: recovery/load/restart
+    RUNNING --> OFF: POWER OFF
+    PAUSED --> OFF: POWER OFF
+~~~
+
+## 4. 通用命令流
+
+~~~mermaid
+flowchart TD
+    CLICK[用户操作] --> OP[operation_id]
+    OP --> ENV[protocol envelope]
+    ENV --> VALIDATE[validate schema/context/seq/tick]
+    VALIDATE -->|error| PERR[protocol ERROR]
+    VALIDATE -->|ok| ACCEPT[WASM sim_protocol_accept]
+    ACCEPT --> GATE[WASM Task gate]
+    GATE -->|disabled| REJECT[gate_reason + ERROR]
+    GATE -->|enabled| EVENT[event log + timeline]
+    EVENT --> HANDLER[WASM handler]
+    HANDLER -->|error| FAIL[rollback + ERROR]
+    HANDLER -->|success| SNAP[WASM snapshot/hash]
+    SNAP --> RESULT[COMMAND_RESULT]
+    RESULT --> REDUCER[React reducer]
+    REDUCER --> UI[显示状态]
+~~~
+
+## 5. 固定 tick
+
+~~~mermaid
+flowchart TD
+    STEP[SIM_STEP] --> TASK[WASM Task/program]
+    TASK --> INTERP[interpreter canonical]
+    INTERP --> TP[LinuxCNC source TP]
+    TP --> KINS[IK/switchkins/RTCP]
+    KINS --> MOTION[motion queue]
+    MOTION --> FEEDBACK[FK/feedback]
+    FEEDBACK --> LIMIT[home/limit]
+    LIMIT --> HAL[HAL/PLC]
+    HAL --> IO[spindle/coolant/tool/probe]
+    IO --> TRACE[execution trace]
+    TRACE --> SNAP[pose/joints/velocity/current line/queue/hash]
+~~~
+
+## 6. AXIS 对照
+
+| AXIS 源入口 | Web/WASM |
+| --- | --- |
+| manual_ok | WASM command gate |
+| ensure_mode | SET_MODE |
+| open_file_guts | PROGRAM_LOAD transaction |
+| reload_file | PROGRAM_RESTART/Reopen |
+| task_run | PROGRAM_RUN |
+| task_pause | PROGRAM_PAUSE |
+| task_resume | PROGRAM_RESUME |
+| task_stop | PROGRAM_ABORT |
+| task_step | PROGRAM_STEP |
+| jog_on/jog_off_actual | JOG_START/JOG_STOP |
+| spindle_forward_toggle | SPINDLE_COMMAND |
+| brake_on/off | SPINDLE_BRAKE |
+| mist_toggle/flood_toggle | COOLANT_COMMAND |
+| send_mdi_command | MDI_EXECUTE |
+| clear_live_plot | VISUAL_CLEAR |
+
+## 7. 验收
+
+~~~mermaid
+flowchart LR
+    SOURCE[AXIS source/config lock] --> NATIVE[native LinuxCNC]
+    SOURCE --> WASM[WASM C tests]
+    WASM --> WORKER[Worker tests]
+    WORKER --> REACT[React build]
+    REACT --> BROWSER[Chromium audit]
+    NATIVE --> COMPARE[逐字段/逐 tick compare]
+    WASM --> COMPARE
+    WORKER --> COMPARE
+    BROWSER --> COMPARE
+    COMPARE -->|all formal oracle| CANDIDATE[release candidate]
+    COMPARE -->|difference| STOP[STOP_RELEASE]
+~~~
+
+当前浏览器审计要求：WASM authority 标记正确、browser_errors=0、所有按钮有 command result 或明确 gate/ABI 原因；面板 verified 不等于完整 TP oracle verified。