228 lines
7.4 KiB
Markdown
228 lines
7.4 KiB
Markdown
# 02-项目程序开发详细步骤
|
||
|
||
## 开发原则
|
||
|
||
1. 以 LinuxCNC 源码语义为准：`axis -> emcmodule.cc -> emctaskmain.cc -> taskintf.cc -> motion`。
|
||
2. Run 按钮只发送命令并渲染状态，不直接把 Web 状态改成 running。
|
||
3. WASM wrapper 可以适配 ABI，但不能发明第二套 CNC task 状态机。
|
||
4. 每一步都要有 Node WASM 测试、Web Node 测试或浏览器 trace 证据。
|
||
5. 每轮结束必须更新推进台账、任务矩阵和验收证据。
|
||
|
||
## 步骤 1：建立 Run 状态门禁表
|
||
|
||
目标文件：
|
||
|
||
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
|
||
- `wasm-port/tests/wasm/node/verify_task_state_matrix.mjs`
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/state/linuxcnc-task-policy.js`
|
||
|
||
开发动作：
|
||
|
||
1. 固化 LinuxCNC 风格枚举：
|
||
- task state：`ESTOP`、`ESTOP_RESET`、`ON`
|
||
- task mode：`MANUAL`、`AUTO`、`MDI`
|
||
- interp state：`IDLE`、`READING`、`PAUSED`、`WAITING`
|
||
2. 增加 `task_accepts_command(state, mode, interp, command)` 或等价函数。
|
||
3. 对 `EMC_TASK_PLAN_RUN` 实现硬门禁：
|
||
- 必须 `state=ON`
|
||
- 必须 `mode=AUTO`
|
||
- 必须 `interpState=IDLE`
|
||
- 必须 homed 或 `no_force_homing`
|
||
- 必须有已打开程序或可用 canonical plan
|
||
4. Web policy 使用同一组条件做按钮 enable/disable，但最终以 WASM 返回为准。
|
||
|
||
验收：
|
||
|
||
- ESTOP 下 Run 返回拒绝。
|
||
- ESTOP_RESET 下 Run 返回拒绝。
|
||
- ON/MANUAL 下 Run 需要先切 AUTO。
|
||
- ON/AUTO/IDLE 且未 homed 时 Run 返回未回零错误。
|
||
- ON/AUTO/IDLE 且 homed、有程序时 Run 被接受。
|
||
|
||
## 步骤 2：补齐程序 open 与 canonical plan 边界
|
||
|
||
目标文件：
|
||
|
||
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
|
||
- `wasm-port/runtime/sdk/src/linuxcnc-task-hal.js`
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/runtime/linuxcnc-task-hal-runtime.js`
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/state/store.js`
|
||
|
||
开发动作：
|
||
|
||
1. 明确 task/HAL session 的程序来源：
|
||
- 当前 G-code 文件路径或虚拟文件名。
|
||
- LinuxCNC interpreter canonical events。
|
||
- motion plan id/version。
|
||
2. 移除或隔离从 G-code 文本正则派生 motion 的 fallback。
|
||
3. 无 canonical plan 时，Run 返回明确错误，例如 `INTERPRETER_PLAN_REQUIRED`。
|
||
4. status JSON 输出：
|
||
- `task.file`
|
||
- `task.programOpen`
|
||
- `task.programStartLine`
|
||
- `task.planId`
|
||
- `task.errorText`
|
||
|
||
验收：
|
||
|
||
- 未 open 程序时 Run 不进入 running。
|
||
- 有 canonical plan 时 Run 记录 `programStartLine`。
|
||
- Web 能显示或记录拒绝原因，store 不伪造 running。
|
||
|
||
## 步骤 3：实现 Run 命令后的 task 状态变化
|
||
|
||
目标文件：
|
||
|
||
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
|
||
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c`
|
||
- `wasm-port/tests/wasm/node/verify_task_hal_wasm.mjs`
|
||
|
||
开发动作：
|
||
|
||
1. `EMC_TASK_PLAN_RUN` 分支对齐 LinuxCNC：
|
||
- 清 `taskPaused`
|
||
- 清 `singleStepping`
|
||
- 清 step 相关等待状态
|
||
- 设置 `programStartLine`
|
||
- 设置 `interpState=READING`
|
||
- 设置 `execState=EXEC` 或等价执行态
|
||
2. 把 canonical motion events 下发到 motion runtime 队列。
|
||
3. motion runtime 输出：
|
||
- `queueDepth`
|
||
- `activeDepth`
|
||
- `motion.id`
|
||
- `motion.programLine`
|
||
- `motion.currentVel`
|
||
4. 执行完成后 task 状态回到：
|
||
- `interpState=IDLE`
|
||
- `execState=DONE`
|
||
- `taskPaused=false`
|
||
|
||
验收：
|
||
|
||
- Run 后读 status 可见 `READING` 或执行中的 `WAITING`。
|
||
- motion queue 开始消费。
|
||
- current line 或 motion id 单调推进。
|
||
- 完成后进入 done/idle。
|
||
|
||
## 步骤 4：Web store 改为 task/HAL status 投影
|
||
|
||
目标文件：
|
||
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/state/store.js`
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/runtime/linuxcnc-task-hal-runtime.js`
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/tests/node/verify_run_feedback_loop.mjs`
|
||
|
||
开发动作：
|
||
|
||
1. 点击 Run 后只做：
|
||
- policy 检查
|
||
- `taskHalRuntime.sendCommand(MODE_AUTO)`
|
||
- `taskHalRuntime.sendCommand(EMC_TASK_PLAN_RUN)`
|
||
- `runCycles/readStatus`
|
||
2. `runState` 映射规则：
|
||
- `interpState=READING/WAITING` 且未 paused -> `running`
|
||
- `interpState=PAUSED` 或 `motion.paused=true` -> `paused`
|
||
- `interpState=IDLE` 且 exec done -> `idle/done`
|
||
- 有 error -> `error`
|
||
3. 删除或隔离点击 Run 后直接写 `running` 的分支。
|
||
4. 当前行、DRO、TCP、RTCP 显示优先使用 task/HAL status 和 kinematics runtime 的结果。
|
||
|
||
验收：
|
||
|
||
- WASM 拒绝 Run 时 Web 不进入 running。
|
||
- WASM 接受 Run 后 Web 才进入 running。
|
||
- status loop 中断或错误时 UI 进入明确错误态，不保持假 running。
|
||
|
||
## 步骤 5：Home 过程态补齐为 Run 前置条件
|
||
|
||
目标文件：
|
||
|
||
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp`
|
||
- `wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c`
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/state/store.js`
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/tests/node/verify_run_feedback_loop.mjs`
|
||
|
||
开发动作：
|
||
|
||
1. joint status 增加：
|
||
- `homing`
|
||
- `homed`
|
||
- `homeState`
|
||
2. Home All 后不要立即只写 `allHomed=true`，应经历至少一个可观测过程态。
|
||
3. Run 前使用 `allHomed || noForceHoming`。
|
||
4. OFF/ESTOP 时按当前模型清理 volatile home；如果暂不能区分 volatile，必须在 status 和决策记录中标注简化。
|
||
|
||
验收：
|
||
|
||
- 未 homed Run 被拒绝。
|
||
- Home 过程中 Run 被拒绝。
|
||
- Home 完成后 Run 可进入执行。
|
||
|
||
## 步骤 6：执行过程 Pause/Resume/Step 回归
|
||
|
||
目标文件：
|
||
|
||
- `wasm-port/tests/wasm/node/verify_task_hal_wasm.mjs`
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/tests/node/verify_run_feedback_loop.mjs`
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/tools/trace-pause-position-json.mjs`
|
||
- `web-rtcp-5axis-xyzbc-trt-sim-plan/tools/verify-estop-power-home-run-pause-50ms.mjs`
|
||
|
||
开发动作：
|
||
|
||
1. 在 Run 成功后执行 Pause，断言：
|
||
- `task.interpState=PAUSED`
|
||
- `task.taskPaused=true`
|
||
- `motion.paused=true`
|
||
2. Resume 后断言：
|
||
- 恢复 `interpResumeState`
|
||
- `taskPaused=false`
|
||
- `motion.paused=false`
|
||
3. Step 后断言：
|
||
- `singleStepping=true` 或 step 过程字段可观测
|
||
- 只推进一个 motion id/程序行
|
||
- 回到 paused
|
||
|
||
验收：
|
||
|
||
- working8 已有暂停证据继续通过。
|
||
- working9 新增 Run 前置、Run 后执行推进、Run 中暂停/恢复/单步证据。
|
||
|
||
## 步骤 7：构建与回归命令
|
||
|
||
WASM 推荐命令：
|
||
|
||
```bash
|
||
cd /home/mes123456/cnc_wams/wasm-port
|
||
./tools/build_task_hal_wasm.sh
|
||
node tests/wasm/node/verify_task_hal_wasm.mjs
|
||
node tests/wasm/node/verify_task_state_matrix.mjs
|
||
```
|
||
|
||
Web 推荐命令：
|
||
|
||
```bash
|
||
cd /home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan
|
||
npm --prefix app run build
|
||
node tests/node/verify_run_feedback_loop.mjs
|
||
APP_URL_PATH=/web-rtcp-5axis-xyzbc-trt-sim-plan/app/dist/index.html node tools/trace-pause-position-json.mjs
|
||
RUN_STABLE_BEFORE_FIRST_PAUSE_MS=3000 node tools/verify-estop-power-home-run-pause-50ms.mjs
|
||
```
|
||
|
||
预期证据关键词：
|
||
|
||
- `linuxcnc_task_runtime_smoke=ok`
|
||
- `task_state_matrix=ok`
|
||
- `run_feedback_status_loop_smoke=ok`
|
||
- `pause_position_status=passed-position-frozen`
|
||
- `verification_status=passed`
|
||
|
||
## 步骤 8：记录与关闭
|
||
|
||
每完成一个编号任务：
|
||
|
||
1. 更新 `03-推进台账.md`。
|
||
2. 更新 `04-任务矩阵.md` 状态。
|
||
3. 把命令、输出摘要、trace 路径、截图目录写入 `05-验收证据.md`。
|
||
4. 如果改变技术方向，追加 `06-决策记录.md`。
|