# 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。

页面临时上下文使用 Worker-only OPFS 双槽位 JSON；它不进入 CNC protocol sequence，也不保存运动 authority。断电 checkpoint 由 Worker 写入 OPFS，下一次 LOAD_WORKSPACE 时再提交给 LinuxCNC WASM 校验和恢复。