# AXIS 主控制按钮调用链与 WASM 完善指南

生成时间：2026-07-07

分析范围：

- LinuxCNC 源码：`/home/mes123456/cnc_wams/linuxcnc`
- WASM 迁移工程：`/home/mes123456/cnc_wams/wasm-port`
- Web 5 轴仿真工程：`/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan`

本文重点分析 AXIS 主界面的“急停、上电、Home、执行、暂停、单步执行”的调用链、状态机制、按钮前置条件，以及对 WASM/Web 项目的完善建议。

## 1. 总体架构结论

LinuxCNC 中 AXIS 按钮不是直接操作运动控制，而是走统一命令/状态通道：

```text
AXIS Python/Tk 按钮
  -> linuxcnc.command() Python C 扩展
  -> NML 命令对象 EMC_TASK_*/EMC_JOINT_*
  -> emcCommand NML 通道
  -> task 主循环 emcTaskPlan()/emcTaskIssueCommand()
  -> taskintf.cc 转为 EMCMOT_* motion 命令
  -> motion 实时侧 command.c/control.c/homing.c
  -> motion/status + task/status 合成为 emcStatus
  -> linuxcnc.stat().poll() 供 AXIS 刷新 UI
```

核心状态不是由按钮自行保存，而是由 `emcStatus` 聚合：

- `emcStatus->task.state`：任务状态，GUI 显示为 `STATE_ESTOP`、`STATE_ESTOP_RESET`、`STATE_ON` 等。
- `emcStatus->task.mode`：任务模式，`MODE_MANUAL`、`MODE_AUTO`、`MODE_MDI`。
- `emcStatus->task.interpState`：解释器状态，`INTERP_IDLE`、`INTERP_READING`、`INTERP_PAUSED`、`INTERP_WAITING`。
- `emcStatus->task.task_paused`：task 层暂停标志。
- `emcStatus->motion.traj.paused`：motion 轨迹规划器暂停标志。
- `emcStatus->motion.traj.single_stepping`：task/GUI 可见的单步执行标志。
- `emcStatus->motion.joint[n].homed`：每个 joint 的回零状态。
- `emcStatus->motion.traj.enabled`：motion 是否上使能，用于推导 task 是否 `STATE_ON`。

需要特别注意：LinuxCNC 的 task 层主要是 C++，motion 层主要是 C。用户所说的 C++ 实现，在源码中实际跨越 `emctask*.cc`、`taskintf.cc` 和 motion 的 `command.c`、`homing.c`。

## 2. AXIS UI 按钮入口

AXIS 主界面位于：

- `linuxcnc/bin/axis`

关键辅助函数：

```python
def manual_ok(do_poll=True):
    if do_poll: s.poll()
    if s.task_state != linuxcnc.STATE_ON: return False
    return s.interp_state == linuxcnc.INTERP_IDLE or (
        s.task_mode == linuxcnc.MODE_MDI and
        s.queued_mdi_commands < vars.max_queued_mdi_commands.get()
    )

def ensure_mode(m, *p):
    s.poll()
    if s.task_mode == m or s.task_mode in p: return True
    c.mode(m)
    c.wait_complete()
    s.poll()
    return True
```

源码位置：`linuxcnc/bin/axis:986-1015`。

这说明 AXIS 侧前置条件分两层：

1. UI 层用 `s.poll()` 读当前状态，避免明显非法操作。
2. task/motion 层仍会再次校验，非法命令会拒绝或报错。

## 3. Python C 扩展到 NML 命令

AXIS 使用 `linuxcnc.command()`。该对象由 `linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc` 暴露，关键映射如下：

| AXIS 调用 | C 扩展函数 | NML 命令 |
| --- | --- | --- |
| `c.state(STATE_*)` | `state()` | `EMC_TASK_SET_STATE` |
| `c.mode(MODE_*)` | `mode()` | `EMC_TASK_SET_MODE` |
| `c.home(joint)` | `home()` | `EMC_JOINT_HOME` |
| `c.auto(AUTO_RUN, line)` | `emcauto()` | `EMC_TASK_PLAN_RUN` |
| `c.auto(AUTO_PAUSE)` | `emcauto()` | `EMC_TASK_PLAN_PAUSE` |
| `c.auto(AUTO_RESUME)` | `emcauto()` | `EMC_TASK_PLAN_RESUME` |
| `c.auto(AUTO_STEP)` | `emcauto()` | `EMC_TASK_PLAN_STEP` |

源码依据：

- `mode()` 创建 `EMC_TASK_SET_MODE`：`linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc:1691-1705`
- `state()` 创建 `EMC_TASK_SET_STATE`：`linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc:1815-1829`
- `home()` 创建 `EMC_JOINT_HOME`：`linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc:1941-1945`
- `emcauto()` 分发 `RUN/PAUSE/RESUME/STEP`：`linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc:2093-2116`

## 4. task 主循环的命令调度

task 主循环在 `linuxcnc/src/emc/task/emctaskmain.cc`：

```text
emcCommandBuffer->read()
  -> emcTaskPlan()
  -> emcTaskExecute()
  -> emcMotionUpdate(&emcStatus->motion)
  -> emcTaskUpdate(&emcStatus->task)
  -> 写 emcStatus 顶层 command/status/echo_serial_number
```

源码位置：`linuxcnc/src/emc/task/emctaskmain.cc:3301-3478`。

`emcTaskPlan()` 按三类状态进行门禁：

1. `task.state`：`OFF`、`ESTOP`、`ESTOP_RESET`、`ON`
2. `task.mode`：`MANUAL`、`AUTO`、`MDI`
3. `task.interpState`：`IDLE`、`READING`、`PAUSED`、`WAITING`

因此，AXIS UI 的按钮条件必须与 `emcTaskPlan()` 的状态表一致，不能只看 `runState` 这类 Web 自定义状态。

## 5. 急停按钮

### 5.1 AXIS UI 调用链

源码：`linuxcnc/bin/axis:2243-2248`

```python
def estop_clicked(event=None):
    s.poll()
    if s.task_state == linuxcnc.STATE_ESTOP:
        c.state(linuxcnc.STATE_ESTOP_RESET)
    else:
        c.state(linuxcnc.STATE_ESTOP)
```

按钮语义：

- 当前是 `STATE_ESTOP`：发送 `STATE_ESTOP_RESET`，表示解除急停。
- 其他任意状态：发送 `STATE_ESTOP`，进入急停。

### 5.2 NML/task 调用链

```text
c.state(STATE_ESTOP or STATE_ESTOP_RESET)
  -> emcmodule.cc state()
  -> EMC_TASK_SET_STATE
  -> emcTaskPlan()
  -> emcTaskIssueCommand()
  -> emcTaskSetState()
```

`EMC_TASK_SET_STATE` 被 task 作为 immediate command 接收：

- 非 ON 状态也允许接收：`emctaskmain.cc:795-829`
- ON/MANUAL 允许：`emctaskmain.cc:897-956`
- ON/AUTO/IDLE 允许：`emctaskmain.cc:1026-1075`
- ON/AUTO/READING 允许：`emctaskmain.cc:1137-1174`
- ON/AUTO/PAUSED 允许：`emctaskmain.cc:1206-1251`

### 5.3 C++ task 状态处理

`emcTaskSetState(ESTOP)` 源码：`linuxcnc/src/emc/task/emctask.cc:353-365`

执行内容：

- `emcMotionAbort()`：中止 motion。
- `emcSpindleAbort()`：中止主轴。
- `emcAuxEstopOn()`：IO 急停输出置位。
- `emcTrajDisable()`：下发 motion disable。
- 关闭 flood coolant。
- `emcTaskAbort()`：清解释器队列、清 pause/step 状态。
- `emcIoAbort(TASK_STATE_ESTOP)`。
- `emcJointUnhome(-2)`：清除 `VOLATILE_HOME` joint 的 homed。
- `emcTaskPlanSynch()`：同步解释器。

`emcTaskSetState(ESTOP_RESET)` 源码：`linuxcnc/src/emc/task/emctask.cc:342-350`

执行内容：

- `emcAuxEstopOff()`：解除 IO 急停。
- `emcTaskAbort()`：清程序运行状态。
- `emcIoAbort(TASK_STATE_ESTOP_RESET)`。
- `emcSpindleAbort()`。
- `emcTaskPlanSynch()`。

### 5.4 状态记录方式

task 并不简单把 `task.state = ESTOP` 固定写死，而是周期性通过 `determineState()` 从 IO 和 motion 推导：

源码：`linuxcnc/src/emc/task/emctask.cc:418-428`

规则：

| IO 急停 | motion enabled | 推导状态 |
| --- | --- | --- |
| true | 任意 | `ESTOP` |
| false | false | `ESTOP_RESET` |
| false | true | `ON` |

`emcTaskUpdate()` 每周期写入 `stat->state`：`linuxcnc/src/emc/task/emctask.cc:688-699`。

这意味着 Web/WASM 中不能只维护一个 `estopActive` 布尔值；应该同时维护：

- IO estop 状态；
- motion enable 状态；
- task 推导状态；
- volatile home 清除动作。

## 6. 上电/下电按钮

### 6.1 AXIS UI 调用链

源码：`linuxcnc/bin/axis:2250-2260`

```python
def onoff_clicked(event=None):
    s.poll()
    if s.task_state == linuxcnc.STATE_ESTOP_RESET:
        c.state(linuxcnc.STATE_ON)
        ...
    else:
        c.state(linuxcnc.STATE_OFF)
```

按钮语义：

- 只有 `STATE_ESTOP_RESET` 才能上电。
- 其他状态一律发送 `STATE_OFF`。
- 因此 `STATE_ESTOP` 下点电源不是“上电”，而是进入 OFF/保持不可上电语义；必须先通过急停按钮解除急停到 `ESTOP_RESET`。

### 6.2 task 调用链

```text
c.state(STATE_ON/OFF)
  -> EMC_TASK_SET_STATE
  -> emcTaskSetState(ON/OFF)
```

`emcTaskSetState(ON)` 源码：`linuxcnc/src/emc/task/emctask.cc:336-340`

执行内容：

- `emcTrajEnable()`。
- 关闭 flood coolant。

`emcTrajEnable()` 源码：`linuxcnc/src/emc/task/taskintf.cc:1396-1400`

```text
emcTrajEnable()
  -> emcmotCommand.command = EMCMOT_ENABLE
  -> usrmotWriteEmcmotCommand()
```

motion 侧 `EMCMOT_ENABLE` 源码：`linuxcnc/src/emc/motion/command.c:1370-1384`

执行内容：

- 如果 HAL `motion.enable` 输入为 false，报错：`can't enable motion, enable input is false`。
- 否则设置 `emcmotInternal->enabling = 1`，实际使能在 motion 控制周期中完成。

`emcTaskSetState(OFF)` 源码：`linuxcnc/src/emc/task/emctask.cc:323-333`

执行内容：

- `emcMotionAbort()`。
- `emcSpindleAbort()`。
- `emcTrajDisable()`。
- `emcIoAbort(TASK_STATE_OFF)`。
- `emcTaskAbort()`。
- `emcJointUnhome(-2)` 清 volatile home。
- `emcTaskPlanSynch()`。

motion 侧 `EMCMOT_DISABLE` 源码：`linuxcnc/src/emc/motion/command.c:1357-1368`

执行内容：

- 设置 `emcmotInternal->enabling = 0`。
- 对 inverse-only kinematics，还会退出 teleop/coord。

### 6.3 状态记录方式

上电后并不是由 task 直接写 `STATE_ON`，而是 motion 报告 enabled 后，`determineState()` 推导为 `ON`。

motion 状态更新路径：

```text
motion command/control 周期更新 emcmotStatus.motionFlag
  -> taskintf.cc emcMotionUpdate()
  -> emcTrajUpdate()
  -> stat->traj.enabled
  -> emcTaskUpdate()
  -> determineState()
```

关键源码：

- `emcMotionUpdate()` 读取 `emcmotStatus`：`linuxcnc/src/emc/task/taskintf.cc:2057-2102`
- `emcTrajUpdate()` 写 `stat->enabled`：`linuxcnc/src/emc/task/taskintf.cc:1639-1652`
- `determineState()` 推导状态：`linuxcnc/src/emc/task/emctask.cc:418-428`

## 7. Home 按钮

### 7.1 AXIS UI 调用链

Home All 源码：`linuxcnc/bin/axis:2732-2740`

```python
def home_all_joints(event=None):
    if not manual_ok(): return
    ensure_mode(linuxcnc.MODE_MANUAL)
    ...
    go_home(-1)
```

单 joint Home 源码：`linuxcnc/bin/axis:2747-2767`

关键条件：

- `manual_ok()` 必须为真，即 machine 为 `STATE_ON`，解释器 idle 或 MDI 队列可接受。
- 切到 `MODE_MANUAL`。
- 已 homed 时弹窗确认是否 re-home。
- 非 identity kinematics 下，单轴/单 joint 选择有额外限制。
- 最终 `go_home(num)` 调 `c.home(num)`。

### 7.2 NML/task/motion 调用链

```text
c.home(-1 或 joint)
  -> emcmodule.cc home()
  -> EMC_JOINT_HOME
  -> emcTaskPlan()
  -> emcTaskIssueCommand()
  -> emcJointHome()
  -> EMCMOT_JOINT_HOME
  -> motion command.c
  -> do_home_joint()
  -> homing.c 状态机
```

`EMC_JOINT_HOME` 只在 ON/MANUAL 中直接允许：`linuxcnc/src/emc/task/emctaskmain.cc:897-956`。

`emcJointHome()` 源码：`linuxcnc/src/emc/task/taskintf.cc:796-805`

执行内容：

- 检查 joint 范围。
- 下发 `EMCMOT_JOINT_HOME`。

motion 侧 `EMCMOT_JOINT_HOME` 源码：`linuxcnc/src/emc/motion/command.c:1411-1439`

motion 前置条件：

- `emcmotStatus->motion_state == EMCMOT_MOTION_FREE`，必须处于 joint/free 模式。
- `motion.homing-inhibit` 不能为 true。
- 当前不能已有 homing 流程在跑。
- `GET_MOTION_ENABLE_FLAG()` 必须为 true。
- 负 joint 表示 home all。

### 7.3 homing 状态机

`do_home_joint()` 最终进入 `linuxcnc/src/emc/motion/homing.c`。

核心状态记录：

- `H[joint].homing`
- `H[joint].homed`
- `H[joint].home_state`
- `H[joint].joint_in_sequence`
- `joint.free_tp.enable`

输出 HAL pin：

源码：`linuxcnc/src/emc/motion/homing.c:541-573`

- `joint.N.homing`
- `joint.N.homed`
- `joint.N.home-state`
- `joint.N.index-enable`

完成逻辑：

源码：`linuxcnc/src/emc/motion/homing.c:1376-1385`

- `homing = 0`
- `homed = 1`
- `home_state = HOME_IDLE`
- `joint_in_sequence = 0`

异常中止：

源码：`linuxcnc/src/emc/motion/homing.c:1387-1397`

- 所有 joint `homing = 0`
- 所有 joint `homed = 0`
- 所有 `free_tp.enable = 0`
- `home_state = HOME_IDLE`

### 7.4 状态记录方式

task 通过 `emcMotionUpdate()` 将 motion homed 状态复制到 `emcStatus->motion.joint[n].homed`，AXIS 的 `s.homed[n]` 来自这里。

`task` 的 `all_homed()` 直接查 `emcStatus->motion.joint[i].homed`，源码：`linuxcnc/src/emc/task/emctaskmain.cc:151-152`。

## 8. 执行 Run 按钮

### 8.1 AXIS UI 调用链

源码：`linuxcnc/bin/axis:2379-2393`

```python
def task_run(*event):
    res = run_warn()
    ...
    ensure_mode(linuxcnc.MODE_AUTO)
    c.auto(linuxcnc.AUTO_RUN, program_start_line)
    program_start_line = 0
```

AXIS UI 层条件：

- 会执行 `run_warn()`，处理文件变更、保存、运行前警告等。
- `ensure_mode(MODE_AUTO)` 切入 AUTO。
- 然后发送 `AUTO_RUN`。

真正硬条件在 task 层：

- machine 必须 ON。
- AUTO 模式下允许。
- 未 homed 且没有 `no_force_homing` 时拒绝。
- 程序文件应已打开；未打开时会尝试打开 `emcStatus->task.file`。

### 8.2 task 调用链

```text
c.auto(AUTO_RUN, line)
  -> EMC_TASK_PLAN_RUN
  -> emcTaskPlan() 按状态门禁
  -> emcTaskIssueCommand()
  -> case EMC_TASK_PLAN_RUN
```

`EMC_TASK_PLAN_RUN` 在 ON/AUTO/IDLE 中允许：`linuxcnc/src/emc/task/emctaskmain.cc:1015-1075`。

核心处理源码：`linuxcnc/src/emc/task/emctaskmain.cc:2318-2335`

执行内容：

- 如果未 homed 且 `!no_force_homing`，报错：`Can't run a program when not homed`。
- 清 `motion.traj.single_stepping`。
- 清 `stepping`、`steppingWait`。
- 必要时 `emcTaskPlanOpen(emcStatus->task.file)`。
- 记录 `programStartLine = run_msg->line`。
- 设置 `emcStatus->task.interpState = READING`。
- 设置 `emcStatus->task.task_paused = 0`。

### 8.3 解释器和 motion 下发

Run 后 `emcTaskPlan()` 进入 `READING`，周期性调用 readahead 逻辑读取 G-code。解释器通过 canonical 函数把运动命令排入 `interp_list`，`emcTaskExecute()` 再把 motion 命令下发到 motion。

运动命令如直线/圆弧最终在 motion `command.c` 中以 `EMCMOT_SET_LINE`、`EMCMOT_SET_CIRCLE` 等处理。运动状态通过 `emcmotStatus.id`、`depth`、`activeDepth`、`paused`、`current_vel` 等回传。

### 8.4 状态记录方式

Run 后主要状态变化：

| 字段 | 变化 |
| --- | --- |
| `task.mode` | `AUTO` |
| `task.interpState` | `READING` |
| `task.task_paused` | `0` |
| `motion.traj.single_stepping` | `0` |
| `motion.traj.queue/activeQueue` | 随 motion 队列变化 |
| `motion.traj.id/tag` | 跟随当前运动段与源代码 state tag |

`emcStatus->task.status` 顶层状态由 `emctaskmain.cc:3458-3476` 合成：有错误为 `ERROR`，全部完成且解释器 idle 为 `DONE`，否则为 `EXEC`。

## 9. 暂停 Pause 按钮

### 9.1 AXIS UI 调用链

源码：`linuxcnc/bin/axis:2402-2406`

```python
def task_pause(*event):
    if s.task_mode != linuxcnc.MODE_AUTO or s.interp_state not in (
        linuxcnc.INTERP_READING,
        linuxcnc.INTERP_WAITING
    ):
        return
    ensure_mode(linuxcnc.MODE_AUTO)
    c.auto(linuxcnc.AUTO_PAUSE)
```

AXIS Pause 的严格条件：

- `task_mode == MODE_AUTO`
- `interp_state in (INTERP_READING, INTERP_WAITING)`
- 不是仅凭 `runState == running`

工具栏合并暂停/恢复 `task_pauseresume()` 源码：`linuxcnc/bin/axis:2433-2443`

- 仅 `MODE_AUTO` 或 `MODE_MDI` 可操作。
- 如果 `s.paused` 为真，发送 resume。
- 否则如果解释器不是 idle，发送 pause。

### 9.2 task/motion 调用链

```text
c.auto(AUTO_PAUSE)
  -> EMC_TASK_PLAN_PAUSE
  -> emcTaskPlan()
  -> emcTaskIssueCommand()
  -> emcTrajPause()
  -> EMCMOT_PAUSE
  -> tpPause()
```

task 处理源码：`linuxcnc/src/emc/task/emctaskmain.cc:2337-2345`

执行内容：

- `emcTrajPause()`
- 若当前不是 `PAUSED`，保存 `interpResumeState = interpState`
- `task.interpState = PAUSED`
- `task.task_paused = 1`

`emcTrajPause()` 源码：`linuxcnc/src/emc/task/taskintf.cc:1417-1421`

motion 侧 `EMCMOT_PAUSE` 源码：`linuxcnc/src/emc/motion/command.c:1234-1240`

执行内容：

- `tpPause(&coord_tp)`
- `emcmotStatus->paused = 1`

### 9.3 状态记录方式

Pause 后必须同时体现：

- `task.interpState = PAUSED`
- `task.task_paused = 1`
- `motion.traj.paused = 1`
- `interpResumeState` 保存暂停前的 `READING` 或 `WAITING`

Web 项目必须避免只改 UI `runState = paused`，否则 resume/step 会缺少 LinuxCNC 必需的恢复上下文。

## 10. 单步 Step 按钮

### 10.1 AXIS UI 调用链

源码：`linuxcnc/bin/axis:2395-2400`

```python
def task_step(*event):
    if s.task_mode != linuxcnc.MODE_AUTO or s.interp_state != linuxcnc.INTERP_IDLE:
        o.set_highlight_line(None)
        if run_warn(): return
    ensure_mode(linuxcnc.MODE_AUTO)
    c.auto(linuxcnc.AUTO_STEP)
```

AXIS Step 的含义不是“前端播放下一帧”，而是向 task 发送 `EMC_TASK_PLAN_STEP`。task 根据解释器状态决定：

- AUTO/IDLE：先启动程序，再立刻暂停，进入单步准备态。
- AUTO/READING 或 WAITING：设置 single stepping，下一段读入/执行后停住。
- AUTO/PAUSED：若 motion 队列中有暂停运动，发 `EMCMOT_STEP` 让 motion 走到下一段；否则恢复解释器状态继续读。

### 10.2 task 处理

AUTO/IDLE 中 `STEP` 源码：`linuxcnc/src/emc/task/emctaskmain.cc:1078-1091`

执行内容：

- 构造 `taskPlanRunCmd.line = 0`
- 调 `emcTaskIssueCommand(&taskPlanRunCmd)` 启动程序
- `emcTrajPause()`
- 保存 `interpResumeState`
- `task.interpState = PAUSED`
- `task.task_paused = 1`

AUTO/READING 中 `STEP` 源码：`linuxcnc/src/emc/task/emctaskmain.cc:1178-1182`

执行内容：

- `motion.traj.single_stepping = 1`
- `stepping = 1`
- `steppingWait = 0`

AUTO/PAUSED 中 `STEP` 源码：`linuxcnc/src/emc/task/emctaskmain.cc:1254-1266`

执行内容：

- `motion.traj.single_stepping = 1`
- `stepping = 1`
- 如果 `motion.traj.paused && queue > 0`，调用 `emcTrajStep()`
- 否则 `task.interpState = interpResumeState`
- `task.task_paused = 1`

AUTO/WAITING 中 `STEP` 源码：`linuxcnc/src/emc/task/emctaskmain.cc:1330-1334`

执行内容同 READING：设置单步标志。

### 10.3 motion 处理

`emcTrajStep()` 源码：`linuxcnc/src/emc/task/taskintf.cc:1438-1442`

motion 侧 `EMCMOT_STEP` 源码：`linuxcnc/src/emc/motion/command.c:1265-1273`

处理逻辑：

- 如果 motion 当前 paused：
  - 记录 `idForStep = emcmotStatus->id`
  - `emcmotStatus->stepping = 1`
  - resume 轨迹规划器，使其执行到 id 变化或下一步边界再停。

### 10.4 状态记录方式

单步相关字段：

- task 侧静态变量：`stepping`、`steppingWait`
- task 可见状态：`emcStatus->motion.traj.single_stepping`
- motion 状态：`emcmotStatus->stepping`、`idForStep`、`paused`
- 解释器状态：`PAUSED` 或恢复到 `interpResumeState`

Web 中若只实现“数组 frameIndex++”，不能等价于 LinuxCNC Step。正确做法是把 Step 作为 task 命令，驱动 task/motion 的 pause/step 状态机。

## 11. Resume 补充

虽然用户重点列出“急停、上电、Home、执行、暂停、单步执行”，但暂停机制必须包含 Resume 才完整。

AXIS `task_resume()` 源码：`linuxcnc/bin/axis:2424-2431`

条件：

- `s.paused` 为真。
- `task_mode` 是 `AUTO` 或 `MDI`。
- 发送 `AUTO_RESUME`。

task 处理源码：`linuxcnc/src/emc/task/emctaskmain.cc:2369-2376`

执行内容：

- `emcTrajResume()`
- `task.interpState = interpResumeState`
- `task.task_paused = 0`
- `motion.traj.single_stepping = 0`
- 清 `stepping`、`steppingWait`

motion 侧 `EMCMOT_RESUME` 源码：`linuxcnc/src/emc/motion/command.c:1256-1263`

执行内容：

- `emcmotStatus->stepping = 0`
- `tpResume()`
- `emcmotStatus->paused = 0`

## 12. 按钮前置条件汇总

| 按钮 | AXIS UI 前置条件 | task/motion 硬条件 | 执行后状态 |
| --- | --- | --- | --- |
| 急停 | 无；读 `s.task_state` 决定 reset 或 estop | `EMC_TASK_SET_STATE` 在多数状态允许 | `ESTOP` 分支 abort、disable、IO estop on；reset 分支 IO estop off、abort、同步解释器 |
| 上电 | 只有 `STATE_ESTOP_RESET` 发送 ON，否则发送 OFF | ON 要 motion enable 输入为真；OFF 总是 abort/disable | ON 后由 `motion.traj.enabled` 推导 `STATE_ON`；OFF 后推导 `ESTOP_RESET` 或 OFF 语义并清 volatile home |
| Home | `manual_ok()`；切 `MODE_MANUAL`；必要时 re-home 确认 | motion 必须 FREE、enabled、未 homing、未 inhibit | `joint.N.homing` 过程态；完成 `joint.N.homed=1`；失败清 homed |
| Run | `run_warn()`；切 `MODE_AUTO` | ON/AUTO/IDLE；已 homed 或 no_force_homing；程序打开 | `interpState=READING`，`task_paused=0`，motion 队列开始增长 |
| Pause | `MODE_AUTO` 且 `INTERP_READING/WAITING` | `EMC_TASK_PLAN_PAUSE`；motion `EMCMOT_PAUSE` | `interpState=PAUSED`，`task_paused=1`，`motion.paused=1`，保存 resume state |
| Step | 切 `MODE_AUTO`；非 idle 时可先 run_warn | 按 AUTO/IDLE/READING/PAUSED/WAITING 分支处理 | 设置 `single_stepping`；必要时 `EMCMOT_STEP`；保持/进入 paused |
| Resume | `paused` 且 `MODE_AUTO/MDI` | `EMC_TASK_PLAN_RESUME`；motion `EMCMOT_RESUME` | 恢复 `interpResumeState`，清 `task_paused/single_stepping/stepping` |

## 13. WASM-port 完善建议

当前 `wasm-port` 已有 task/HAL WASM 入口：

- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
- `wasm-port/runtime/sdk/src/linuxcnc-task-hal.js`

但是 `linuxcnc_task_hal_wasm.cpp` 仍是 `linuxcnc_task_motion_hal_wasm_phase4_minimal`，存在明显过渡实现：

- 用字符串搜索和手写 JSON 解析命令。
- 自己维护 `TaskRuntime.state/mode/interp_state/task_paused/single_stepping`。
- 从 G-code 文本中用简单规则派生 motion，存在 G-code 语义重实现风险。
- `readiness()` 中仍标记 `nativeTaskReady:false`、`nativeHalSyncReady:false`。

这与 `wasm-port/AGENTS.md` 的要求冲突风险较高：项目应复用 LinuxCNC source，不应扩展项目自写 CNC 语义。

建议按以下阶段完善。

### 13.1 第一阶段：把状态枚举和门禁表固化为 LinuxCNC 镜像

目标：先不改大架构，但移除随意字符串状态。

建议：

1. 在 `runtime/core/linuxcnc_wrap` 增加 task 状态模型头文件，例如 `linuxcnc_task_state_model.hh`。
2. 用与 LinuxCNC 一致的枚举名：`ESTOP`、`ESTOP_RESET`、`ON`、`MANUAL`、`AUTO`、`MDI`、`IDLE`、`READING`、`PAUSED`、`WAITING`。
3. 实现一个 `task_accepts_command(state, mode, interp, command)`，逐项映射 `emcTaskPlan()` 的允许表。
4. 所有 `lctask_send_command_json()` 先走该门禁表，返回明确错误码和错误文本。
5. 增加测试覆盖：
   - ESTOP 下仅允许 state/mode/config 等 immediate 命令。
   - ON/MANUAL 下允许 HOME，不允许 AUTO RUN。
   - ON/AUTO/IDLE 下允许 RUN/STEP。
   - ON/AUTO/READING 下允许 PAUSE/STEP，不允许 HOME。
   - ON/AUTO/PAUSED 下允许 RESUME/STEP。

### 13.2 第二阶段：替换手写 G-code motion 派生

当前 `enqueue_linear_move_from_line()` 和 Web 侧 `buildSourceLineMotionSegments()` 都会从 G-code 行解析轴和 feed，这属于语义漂移高风险点。

正确方向：

1. G-code 到 canonical motion 必须由 vendored LinuxCNC interpreter 产生。
2. task/HAL runtime 只消费 LinuxCNC canonical 输出或已验证的 motion plan，不自行解释 G-code。
3. 对没有 motion plan 的程序，应返回“需要 interpreter plan”错误，而不是 fallback 解析 `G0/G1`。
4. `buildTaskHalProgramMotionPlan()` 可保留为 host 边界适配器，但输入必须来自 LinuxCNC interpreter runtime 的 canonical events，而不是源码行正则解析。

### 13.3 第三阶段：引入 vendored task/motion 源码闭环

最终目标不是仿照 `emctaskmain.cc` 写一份 JS/C++ 状态机，而是逐步把 vendored LinuxCNC task/motion 代码纳入 WASM：

1. 将 `emc/nml_intf/emc_nml.hh` 中的命令/状态结构作为 WASM 内部 ABI 参考。
2. 用内存队列替代 NML transport，但保留 `EMC_TASK_*` / `EMCMOT_*` 命令类型。
3. 将 `taskintf.cc` 的 `emcTrajEnable/Pause/Resume/Step/Home` 路由接到 `linuxcnc_motion_runtime.c`。
4. 将 `emcTaskSetState()`、`emcTaskSetMode()`、`emcTaskAbort()` 的语义直接迁移或编译进 WASM。
5. motion runtime 应逐步引入 `command.c`、`homing.c`、`control.c` 中真实状态更新，而不是只暴露“看起来相同”的 JSON status。

### 13.4 第四阶段：状态发布完全对齐 `emcStatus`

WASM SDK `readStatus()` 应输出与 Python `linuxcnc.stat()` 结构同构的字段：

- `task.state`
- `task.mode`
- `task.interpState`
- `task.execState`
- `task.taskPaused`
- `motion.traj.enabled`
- `motion.traj.paused`
- `motion.traj.singleStepping`
- `motion.traj.queue`
- `motion.traj.id`
- `motion.joint[n].homed`
- `motion.joint[n].homing`
- `motion.joint[n].homeState`
- `echoSerialNumber`
- `commandType`

这样 Web 项目可以直接消费 LinuxCNC 状态，而不是维护第二套状态。

## 14. web-rtcp-5axis-xyzbc-trt-sim-plan 完善建议

当前 Web 项目已有：

- `app/src/state/linuxcnc-task-policy.js`
- `app/src/state/store.js`
- `app/src/runtime/linuxcnc-task-hal-runtime.js`
- browser/node 对按钮路径的验证

这已经完成一部分 AXIS 对标，但还需要继续收敛。

### 14.1 状态源优先级必须调整

建议状态优先级：

```text
taskHalStatus.ui/task/motion 原生状态
  > LinuxCNC interpreter canonical events
  > Web UI 派生状态
```

Web store 中 `machine.taskState/mode/interpState/runState` 应逐渐变成 task/HAL 状态的投影，而不是独立真相源。

### 14.2 按钮 action 应发送 LinuxCNC 命令，不直接改业务状态

按钮处理建议统一为：

```text
UI click
  -> gateLinuxCncTaskAction()
  -> taskHalRuntime.sendCommand({ type: "EMC_TASK_*" })
  -> taskHalRuntime.runCycles()
  -> taskHalRuntime.readStatus()
  -> store 接收 STATUS_SYNC
  -> UI 渲染
```

避免：

- click 后直接 `runState = "running"`；
- click 后直接 `machine.allHomed = true`；
- pause/step 直接操作播放帧；
- power 直接改 `powerOn` 而不等 motion enabled/status。

### 14.3 补齐 Home 状态过程态

Web 当前常见实现是 `HOME` 后立即 `allHomed=true`。LinuxCNC 真实机制是：

```text
EMC_JOINT_HOME
  -> joint.N.homing = true
  -> home_state 多阶段变化
  -> joint.N.homed = true
```

建议 Web 状态增加：

- `machine.joints[n].homing`
- `machine.joints[n].homed`
- `machine.joints[n].homeState`
- `machine.homingActive`
- `machine.allHomed`

按钮门禁：

- homing 过程中禁止再次 Home。
- Run 前使用 `allHomed || noForceHoming`。
- OFF/ESTOP 时清 volatile home，而不是无条件清所有 home；如果当前模型无法区分 volatile，先在文档和状态字段中标注“volatile home 简化”。

### 14.4 补齐 Step 的 LinuxCNC 语义

Web 需要区分三种 Step：

1. 程序 idle 首次 step：等价于 RUN 后立即 PAUSE。
2. 程序 running 中 step：设置 single stepping，等待下一段边界停住。
3. 程序 paused 中 step：若 motion queue 有内容，发送 motion step；否则恢复 interpreter 读下一段。

建议在 `linuxcnc-task-policy.js` 中把 `STEP` 门禁拆开：

- `canStepFromIdle`
- `canStepWhileReading`
- `canStepWhilePaused`
- `canStepWhileWaiting`

并在 status 中显示：

- `task.singleStepping`
- `motion.stepping`
- `motion.idForStep`
- `motion.paused`

### 14.5 Pause/Resume 继续保持 AXIS 门禁

已完成的严格对标应继续保留：

- `PAUSE`：仅 `STATE_ON + MODE_AUTO + INTERP_READING/WAITING`。
- `PAUSE_RESUME`：仅 `MODE_AUTO/MDI`；paused 时 resume；非 idle 时 pause。
- `RESUME`：必须 `paused && MODE_AUTO/MDI`。

后续测试不要只断言按钮可点击，应断言 task/HAL status：

- pause 后 `task.interpState=PAUSED`
- pause 后 `task.taskPaused=true`
- pause 后 `motion.paused=true`
- resume 后恢复 `interpResumeState`
- step 后 `singleStepping=true`

### 14.6 5 轴 XYZBC-TRT 特有要求

5 轴仿真不应把主按钮逻辑和 RTCP/kinematics 逻辑混在一起。建议分层：

1. task/motion 状态机：只负责开关机、home、run、pause、step。
2. kinematics/RTCP：只负责 XYZBC-TRT 位置变换和 TCP 显示。
3. interpreter/remap：负责 M428/M429/M430、switchkins、G-code 语义。
4. UI：只渲染状态并发送命令。

Run 前置条件除 LinuxCNC 通用条件外，还应检查：

- 选定 profile 的 INI 已加载；
- machine files 已 staged；
- 当前 G-code 已 open 到 task/HAL session；
- kinematics runtime 与 task/HAL runtime readiness 均为 true；
- 如果程序依赖 switchkins/remap，HAL `motion.switchkins-type` 同步状态应可观测。

## 15. 推荐验证矩阵

### 15.1 LinuxCNC 行为矩阵

用本地 LinuxCNC 源码为基准建立 golden matrix：

| 初始状态 | 命令 | 期望 |
| --- | --- | --- |
| ESTOP/MANUAL/IDLE | ESTOP button | `STATE_ESTOP_RESET` |
| ESTOP_RESET/MANUAL/IDLE | Power | `STATE_ON` |
| ESTOP/MANUAL/IDLE | Power | 不上电，走 OFF 分支 |
| ON/MANUAL/IDLE | Home All | `joint.*.homing -> homed` |
| ON/AUTO/IDLE + unhomed | Run | 拒绝，提示未 homed |
| ON/AUTO/IDLE + homed | Run | `interpState=READING` |
| ON/AUTO/READING | Pause | `interpState=PAUSED`、`motion.paused=true` |
| ON/AUTO/PAUSED | Resume | 恢复 reading/waiting |
| ON/AUTO/IDLE + homed | Step | run + pause，single step 准备 |
| ON/AUTO/PAUSED + queue>0 | Step | `EMCMOT_STEP`，执行下一段后停 |

### 15.2 wasm-port 测试建议

新增或扩展：

- `tests/wasm/node/verify_task_state_matrix.mjs`
- `tests/wasm/node/verify_task_home_state_machine.mjs`
- `tests/wasm/node/verify_task_pause_resume_step.mjs`

每个测试不要只看返回码，要读 `lctask_read_status_json()`：

- task 字段；
- motion 字段；
- HAL pins；
- events；
- command echo。

### 15.3 Web 测试建议

在现有 `verify_xyzbc_trt_web_app.mjs` 和 browser smoke 上补齐：

- ESTOP/RESET/POWER 不允许绕过；
- Home 有过程态；
- Run 未 homed 拒绝；
- Pause idle 拒绝；
- Pause manual 拒绝；
- Step idle 首次启动后暂停；
- Step paused 推进一段；
- Resume 清 single stepping；
- Store 状态与 taskHalStatus 一致。

## 16. 实施优先级

建议按以下顺序推进：

1. `wasm-port` 先消除 task/HAL runtime 中的 G-code 正则解析 fallback，要求 motion plan 必须来自 LinuxCNC interpreter canonical output。
2. `wasm-port` 把 `lctask_send_command_json()` 改为显式命令结构解析和 LinuxCNC 状态门禁表。
3. `wasm-port` 补齐 `task/motion/joint` 状态字段，使 `readStatus()` 接近 `linuxcnc.stat()`。
4. Web store 改为 taskHalStatus 投影源，减少直接改 `runState/machine` 的分支。
5. Web Home/Step 加过程态和真实 task/motion 状态断言。
6. 再继续推进 vendored `emctask.cc/taskintf.cc/command.c/homing.c` 的更直接编译或等价适配。

最终目标：Web 按钮只是 AXIS 的浏览器外壳，状态机和 CNC 语义来自 LinuxCNC 源码或其受控 WASM 适配层。