566 lines
14 KiB
Markdown
566 lines
14 KiB
Markdown
# 02 RUN 前置条件、详细测试与编写步骤
|
||
|
||
生成时间：2026-06-22
|
||
|
||
## 1. 核心原则
|
||
|
||
`RUN` 不是孤立按钮逻辑。对五轴机床，必须先确定 LinuxCNC 机床上下文，再执行程序。
|
||
|
||
正确顺序是：
|
||
|
||
```text
|
||
明确 INI 文件
|
||
-> 确定机床类型、坐标轴、joint、HAL、remap、tool-table
|
||
-> 确定五轴运动学算法和 switchkins 映射
|
||
-> 验证 kinematics WASM 和 task/HAL runtime 已处在同一机床上下文
|
||
-> 加载并打开 G-code
|
||
-> RUN 发送 LinuxCNC task command
|
||
-> 持续 runCycles/readStatus 或 worker push feedback
|
||
-> UI 只消费 task/HAL/motion feedback
|
||
```
|
||
|
||
不能先写一个通用 `RUN`，再猜测当前机床是什么。否则 `activeLine`、DRO、RTCP、A/B/C 旋转轴、TCP 补偿和 switchkins 状态都可能来自不同来源。
|
||
|
||
## 2. 必须先确认的机床上下文
|
||
|
||
当前项目内可作为 `RUN` 上下文的五轴 profile 只有两个：
|
||
|
||
| profile | LinuxCNC INI | 机床类型 | 坐标 | kinematics module |
|
||
| --- | --- | --- | --- | --- |
|
||
| `xyzac-trt` | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini` | table rotary tilting | `XYZAC` | `xyzac-trt` |
|
||
| `xyzbc-trt` | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini` | table rotary tilting | `XYZBC` | `xyzbc-trt` |
|
||
|
||
源码落点：
|
||
|
||
```text
|
||
app/src/profiles/index.js
|
||
app/src/profiles/xyzac-trt.js
|
||
app/src/profiles/xyzbc-trt.js
|
||
app/src/runtime/linuxcnc-ini-runtime.js
|
||
app/src/runtime/linuxcnc-kinematics-runtime.js
|
||
wasm-port/runtime/sdk/src/linuxcnc-kinematics.js
|
||
```
|
||
|
||
### 2.1 `xyzac-trt`
|
||
|
||
必须确认：
|
||
|
||
```text
|
||
profile id: xyzac-trt
|
||
INI: configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
|
||
[EMC] MACHINE: sim-xyzac-trt-kins (switchkins)
|
||
[TRAJ] COORDINATES: XYZAC
|
||
[KINS] KINEMATICS: xyzac-trt-kins sparm=identityfirst
|
||
WASM module id: xyzac-trt
|
||
WASM file: linuxcnc_xyzac_trt_kinematics.wasm
|
||
LinuxCNC source: src/emc/kinematics/xyzac-trt-kins.c
|
||
shared source: src/emc/kinematics/trtfuncs.c
|
||
switchkins source: src/emc/kinematics/switchkins.c
|
||
```
|
||
|
||
switchkins 映射：
|
||
|
||
```text
|
||
M429 -> switchkins type 0 -> identity
|
||
M428 -> switchkins type 1 -> tcp-xyzac
|
||
M430 -> switchkins type 2 -> userk
|
||
HAL link: motion.analog-out-03 => motion.switchkins-type
|
||
```
|
||
|
||
### 2.2 `xyzbc-trt`
|
||
|
||
必须确认：
|
||
|
||
```text
|
||
profile id: xyzbc-trt
|
||
INI: configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
|
||
[EMC] MACHINE: sim-xyzbc-trt-kins (switchkins)
|
||
[TRAJ] COORDINATES: XYZBC
|
||
[KINS] KINEMATICS: xyzbc-trt-kins sparm=identityfirst
|
||
WASM module id: xyzbc-trt
|
||
WASM file: linuxcnc_xyzbc_trt_kinematics.wasm
|
||
LinuxCNC source: src/emc/kinematics/xyzbc-trt-kins.c
|
||
shared source: src/emc/kinematics/trtfuncs.c
|
||
switchkins source: src/emc/kinematics/switchkins.c
|
||
```
|
||
|
||
switchkins 映射：
|
||
|
||
```text
|
||
M429 -> switchkins type 0 -> identity
|
||
M428 -> switchkins type 1 -> tcp-xyzbc
|
||
M430 -> switchkins type 2 -> userk
|
||
HAL link: motion.analog-out-03 => motion.switchkins-type
|
||
```
|
||
|
||
## 3. RUN 前置状态检查
|
||
|
||
`RUN` action 进入真正执行前，应要求这些状态全部明确：
|
||
|
||
```text
|
||
state.profile.id 是 xyzac-trt 或 xyzbc-trt
|
||
state.profile.iniPath 非空且已加载
|
||
state.iniConfigReadiness.loaded === true
|
||
state.iniConfigReadiness.ready === true
|
||
state.iniConfigReadiness.coordinates 与 profile.traj.coordinates 一致
|
||
state.profile.kinematicsModuleId 与 INI [KINS] KINEMATICS 推导结果一致
|
||
state.kinematicsRuntimeReadiness.loaded === true
|
||
state.kinematicsRuntimeReadiness.moduleId === state.profile.kinematicsModuleId
|
||
state.rtcpFrame.sourceMode === source-derived-kinematics-wasm
|
||
state.machineFileStaging.status === staged
|
||
state.taskHalRuntimeReadiness.taskRuntimeReady === true
|
||
state.taskHalRuntimeReadiness.motionRuntimeReady === true
|
||
state.taskHalRuntimeReadiness.halRuntimeReady === true
|
||
state.taskHalSession.programPath 指向当前选中的 G-code
|
||
```
|
||
|
||
如果任一项不满足，`RUN` 应返回明确 operatorMessage，不应进入 fixture line playback 后伪装成真实运行。
|
||
|
||
建议阻断消息：
|
||
|
||
```text
|
||
run blocked: LinuxCNC INI not loaded
|
||
run blocked: machine profile and INI coordinates mismatch
|
||
run blocked: LinuxCNC kinematics runtime not ready
|
||
run blocked: task/HAL runtime not ready
|
||
run blocked: no machine-file G-code opened for task/HAL session
|
||
```
|
||
|
||
## 4. 详细测试计划
|
||
|
||
### 4.1 INI/profile 解析测试
|
||
|
||
目标：证明 `RUN` 使用的不是手写机床参数，而是明确 LinuxCNC INI。
|
||
|
||
测试文件建议：
|
||
|
||
```text
|
||
tests/node/verify_run_preconditions.mjs
|
||
```
|
||
|
||
断言：
|
||
|
||
```text
|
||
1. 读取 xyzac-trt.ini，parseLinuxCncIni() 返回:
|
||
profileId=xyzac-trt
|
||
machineName=sim-xyzac-trt-kins (switchkins)
|
||
traj.coordinates=XYZAC
|
||
kinematics.name=xyzac-trt-kins
|
||
kinematicsModuleId=xyzac-trt
|
||
validation.ready=true
|
||
|
||
2. 读取 xyzbc-trt.ini，parseLinuxCncIni() 返回:
|
||
profileId=xyzbc-trt
|
||
machineName=sim-xyzbc-trt-kins (switchkins)
|
||
traj.coordinates=XYZBC
|
||
kinematics.name=xyzbc-trt-kins
|
||
kinematicsModuleId=xyzbc-trt
|
||
validation.ready=true
|
||
|
||
3. applyIniConfigToProfile() 后:
|
||
profile.traj.coordinates 与 INI 一致
|
||
profile.kinematicsModuleId 与 INI 推导结果一致
|
||
axisLimits 和 jointConfig 来自 INI
|
||
```
|
||
|
||
命令：
|
||
|
||
```bash
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_run_preconditions.mjs
|
||
```
|
||
|
||
通过标准：
|
||
|
||
```text
|
||
run_preconditions_ini_profile_smoke=ok
|
||
```
|
||
|
||
### 4.2 运动学模块确认测试
|
||
|
||
目标：证明当前机床的五轴运动学算法已经按 INI/profile 加载。
|
||
|
||
断言：
|
||
|
||
```text
|
||
1. createLinuxCncKinematicsRuntime({ moduleId: "xyzac-trt" }) 成功。
|
||
2. readiness.moduleId === "xyzac-trt"。
|
||
3. wasmFile === "linuxcnc_xyzac_trt_kinematics.wasm"。
|
||
4. frameForJoints([10,20,30,25,40]) 返回 moduleId=xyzac-trt。
|
||
5. switchKinematics(1) 后 switchkinsType=1，frame source 仍是 linuxcnc_kinematics_wasm_c_abi。
|
||
|
||
6. 对 xyzbc-trt 重复同样测试。
|
||
```
|
||
|
||
已有相关测试：
|
||
|
||
```bash
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_kinematics_runtime.mjs
|
||
```
|
||
|
||
新增 RUN 前置测试应把这个结果纳入 `RUN` gate，而不是只作为独立 smoke。
|
||
|
||
### 4.3 machine-file staging 测试
|
||
|
||
目标：证明 `RUN` 打开的程序、INI、remap、tool table 是同一个 LinuxCNC 机床目录上下文。
|
||
|
||
断言：
|
||
|
||
```text
|
||
1. stageProfileMachineFiles(profile) 成功。
|
||
2. save.files 中包含:
|
||
- 当前 profile 的 INI
|
||
- 当前 profile 的 tool table
|
||
- remap_subs/428remap.ngc
|
||
- remap_subs/429remap.ngc
|
||
- remap_subs/430remap.ngc
|
||
- 当前 profile 的 demo G-code
|
||
3. buildTaskHalSessionFromMachineFiles() 生成:
|
||
profileId 与 state.profile.id 一致
|
||
iniPath 与 profile.iniPath 一致
|
||
programPath 指向当前 selectedGcodeSourceRel
|
||
```
|
||
|
||
已有相关测试：
|
||
|
||
```bash
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_machine_file_staging.mjs
|
||
```
|
||
|
||
### 4.4 RUN 连续 feedback 测试
|
||
|
||
目标：证明点击 `RUN` 后，不是只推进一次 `taskCycles=5`，而是持续从 task/HAL/motion 获取反馈。
|
||
|
||
测试程序：
|
||
|
||
```ngc
|
||
G90 G21
|
||
M429
|
||
G0 X0 Y0 Z5 A0 C0
|
||
M428
|
||
G1 X10 Y0 Z5 A10 C20 F600
|
||
G1 X10 Y10 Z0 A20 C30 F300
|
||
M429
|
||
G1 X0 Y0 Z5 A0 C0 F600
|
||
M30
|
||
```
|
||
|
||
对 `xyzbc-trt` 时把 A 轴替换为 B 轴：
|
||
|
||
```ngc
|
||
G90 G21
|
||
M429
|
||
G0 X0 Y0 Z5 B0 C0
|
||
M428
|
||
G1 X10 Y0 Z5 B10 C20 F600
|
||
G1 X10 Y10 Z0 B20 C30 F300
|
||
M429
|
||
G1 X0 Y0 Z5 B0 C0 F600
|
||
M30
|
||
```
|
||
|
||
采集至少 8 个 feedback tick，断言：
|
||
|
||
```text
|
||
1. 每个 tick 的 sourceMode 都是 linuxcnc-task-motion-hal-wasm。
|
||
2. taskCycle 或 servoCycle 单调递增。
|
||
3. activeLine 随 feedback 推进，不停留在 RUN 后第一帧。
|
||
4. axisPose 来自同一 tick 的 task/HAL status.ui.axisPose。
|
||
5. currentVelocityMmPerMin 来自同一 tick 的 motion currentVel。
|
||
6. M428 后 kinsType 切到 tcp-xyzac 或 tcp-xyzbc。
|
||
7. M429 后 kinsType 回到 identity。
|
||
8. UI 当前高亮行、DRO、runtime feedback 文本读取的是同一个 feedback snapshot。
|
||
9. 程序完成后 runState 变为 complete 或 idle，不继续显示 running。
|
||
```
|
||
|
||
失败判定：
|
||
|
||
```text
|
||
RUN 后 servoCycle 只增加一次，然后 0.5s/2s/5s 不变。
|
||
activeLine 固定在某一行不再推进。
|
||
axisPose 从 HOME 位姿被 task-local 0 值覆盖。
|
||
programRuntimeFeedback.sourceMode 不是 linuxcnc-task-motion-hal-wasm。
|
||
RTCP 状态与当前 G-code 的 M428/M429 不一致。
|
||
```
|
||
|
||
### 4.5 浏览器端测试
|
||
|
||
建议扩展：
|
||
|
||
```text
|
||
qa/web-rtcp-5axis-site-test/capture-toolpath-preview-cases.mjs
|
||
```
|
||
|
||
新增 case：
|
||
|
||
```text
|
||
07-run-preconditions-and-feedback
|
||
```
|
||
|
||
浏览器断言：
|
||
|
||
```text
|
||
1. 首屏等待 state.iniConfigReadiness.loaded === true。
|
||
2. 选择 xyzac-trt，确认 titlebar/profile/INI/kinematics module 都是 xyzac-trt。
|
||
3. 点击 POWER、HOME、AUTO。
|
||
4. 加载上述短 G-code。
|
||
5. 点击 RUN。
|
||
6. 采集 t=0.2s、0.5s、1.0s、2.0s、5.0s 状态。
|
||
7. 断言 task/servo cycle 单调递增。
|
||
8. 断言 UI `.gcode-row.active` 的 data-program-line 等于 state.activeLine。
|
||
9. 断言 DRO X/Y/Z/A/C 等于 state.programRuntimeFeedback.axisPose。
|
||
10. 断言 canvas dataset 的 RTCP 状态与 state.rtcpState 一致。
|
||
```
|
||
|
||
输出证据：
|
||
|
||
```text
|
||
qa/web-rtcp-5axis-site-test/output/run-preconditions-feedback.json
|
||
qa/web-rtcp-5axis-site-test/screenshots/run-preconditions-feedback/*.png
|
||
```
|
||
|
||
## 5. 编写 RUN 程序的实现步骤
|
||
|
||
### Step 1: 增加 `validateRunPreconditions(state)`
|
||
|
||
位置建议：
|
||
|
||
```text
|
||
app/src/state/store.js
|
||
```
|
||
|
||
职责：
|
||
|
||
```text
|
||
1. 检查 INI 已加载。
|
||
2. 检查 profile 与 INI 坐标一致。
|
||
3. 检查 profile.kinematicsModuleId 与 kinematics runtime moduleId 一致。
|
||
4. 检查 kinematics runtime ready。
|
||
5. 检查 task/HAL runtime ready。
|
||
6. 检查 machine file staging ready。
|
||
7. 检查 taskHalSession.programPath 指向当前 G-code。
|
||
```
|
||
|
||
返回结构：
|
||
|
||
```js
|
||
{
|
||
ok: true,
|
||
profileId: "xyzac-trt",
|
||
iniPath: ".../xyzac-trt.ini",
|
||
coordinates: "XYZAC",
|
||
kinematicsModuleId: "xyzac-trt"
|
||
}
|
||
```
|
||
|
||
失败时：
|
||
|
||
```js
|
||
{
|
||
ok: false,
|
||
operatorMessage: "run blocked: LinuxCNC INI not loaded"
|
||
}
|
||
```
|
||
|
||
### Step 2: `RUN` action 先调用前置检查
|
||
|
||
当前 `RUN` 不能直接进入：
|
||
|
||
```text
|
||
runTaskHalCommandSequence([...], { taskCycles: 5 })
|
||
```
|
||
|
||
应先：
|
||
|
||
```text
|
||
1. gateLinuxCncTaskAction(state, action)
|
||
2. validateRunPreconditions(state)
|
||
3. initializeTaskHalSession({ openProgram: true }) 如需要
|
||
4. 确认 readStatus() 的 openProgram/programPath 与 state.activeProgram 对齐
|
||
```
|
||
|
||
未满足前置条件时，只设置 `operatorMessage`，不推进任何 line/sample。
|
||
|
||
### Step 3: 拆分 task command 与执行 pump
|
||
|
||
`RUN` 应只发送 LinuxCNC task 命令：
|
||
|
||
```text
|
||
EMC_TASK_SET_STATE ON
|
||
EMC_TASK_SET_MODE AUTO
|
||
EMC_TASK_PLAN_RUN line = activeLine - programStartLine
|
||
```
|
||
|
||
然后启动 feedback pump：
|
||
|
||
```text
|
||
while running:
|
||
taskHalRuntime.runCycles({ taskCycles: batchSize })
|
||
status = taskHalRuntime.readStatus()
|
||
dispatch TASK_HAL_STATUS_APPLIED(status)
|
||
append feedback history
|
||
if complete/paused/aborted/stopped:
|
||
stop pump
|
||
```
|
||
|
||
说明：
|
||
|
||
```text
|
||
这里的 pump 可以在 store 主线程调度，也可以放到 worker 内部 postMessage 推送。
|
||
关键不是 timer 本身，而是每个 tick 都必须由 task/HAL/motion runtime 的 runCycles/readStatus 产生反馈。
|
||
```
|
||
|
||
### Step 4: 增加 RUN pump 状态
|
||
|
||
建议 state 增加：
|
||
|
||
```js
|
||
taskHalRunPump: {
|
||
active: false,
|
||
sequence: 0,
|
||
profileId: null,
|
||
iniPath: null,
|
||
kinematicsModuleId: null,
|
||
tickCount: 0,
|
||
lastStatusAt: null,
|
||
lastError: null
|
||
}
|
||
```
|
||
|
||
同时增加：
|
||
|
||
```js
|
||
programRuntimeFeedbackHistory: []
|
||
```
|
||
|
||
历史最多保留 100 到 500 条，避免浏览器长程序内存无限增长。
|
||
|
||
### Step 5: `TASK_HAL_STATUS_APPLIED` 只消费 status
|
||
|
||
`applyTaskHalStatusPatch()` 应继续负责：
|
||
|
||
```text
|
||
activeLine
|
||
axisPose
|
||
kinsType
|
||
rtcpState
|
||
runState
|
||
feed.currentVelocity
|
||
programRuntimeFeedback
|
||
```
|
||
|
||
但需要补充：
|
||
|
||
```text
|
||
1. programRuntimeFeedbackHistory append 当前 feedback。
|
||
2. 记录 feedback.profileId、iniPath、kinematicsModuleId。
|
||
3. 对 ui.axisPoseFrame 做严格处理，避免 task-local 0 值覆盖 HOME/work pose。
|
||
4. 运行态 axisPose、velocity、DTG、activeLine 必须来自同一个 status snapshot。
|
||
```
|
||
|
||
### Step 6: STOP/ABORT/PAUSE/RESUME 控制 pump
|
||
|
||
行为要求：
|
||
|
||
```text
|
||
STOP/ABORT:
|
||
send EMC_TASK_ABORT
|
||
stop pump
|
||
read final status
|
||
|
||
PAUSE:
|
||
send EMC_TASK_PLAN_PAUSE
|
||
pump 可停止或降频读取 paused status
|
||
runState=paused
|
||
|
||
RESUME:
|
||
send EMC_TASK_PLAN_RESUME
|
||
restart pump
|
||
|
||
STEP:
|
||
不走 fixture sample playback
|
||
发送/推进一个明确的 task cycle batch
|
||
readStatus 一次
|
||
runState=stepping 或 paused
|
||
```
|
||
|
||
### Step 7: UI 显示执行历史
|
||
|
||
在 `app/src/ui/gmoccapy-shell.js` 的 info/sidebar 区域增加：
|
||
|
||
```text
|
||
Last feedback:
|
||
sourceMode / sample / line / taskCycle / servoCycle / velocity / kinsType
|
||
|
||
Run history:
|
||
最近 10 条 line/tick
|
||
```
|
||
|
||
UI 只显示 `programRuntimeFeedbackHistory`，不自行推导行号或坐标。
|
||
|
||
### Step 8: 移除真实 RUN 的 fixture fallback 混淆
|
||
|
||
保留 fallback 可以用于开发，但必须明确标记：
|
||
|
||
```text
|
||
programExecutionSourceMode=fixture-line-playback
|
||
operatorMessage=LinuxCNC task/HAL unavailable; fixture playback only
|
||
fullLinuxCncProgramExecutionReady=false
|
||
```
|
||
|
||
在真实 `taskHalRuntime.loaded === true` 且前置条件失败时，不应退回 fixture playback。
|
||
|
||
## 6. 开发验收命令
|
||
|
||
基础检查：
|
||
|
||
```bash
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_run_preconditions.mjs
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_kinematics_runtime.mjs
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_machine_file_staging.mjs
|
||
node web-rtcp-5axis-sim-plan/tests/node/verify_linuxcnc_task_hal_runtime.mjs
|
||
npm --prefix web-rtcp-5axis-sim-plan/app run build
|
||
```
|
||
|
||
完整 node smoke：
|
||
|
||
```bash
|
||
npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
|
||
```
|
||
|
||
浏览器 smoke：
|
||
|
||
```bash
|
||
bash web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_shell_browser.sh
|
||
bash web-rtcp-5axis-sim-plan/tests/browser/verify_gmoccapy_dist_browser.sh
|
||
```
|
||
|
||
QA 证据采集：
|
||
|
||
```bash
|
||
node qa/web-rtcp-5axis-site-test/capture-toolpath-preview-cases.mjs
|
||
```
|
||
|
||
## 7. 完成标准
|
||
|
||
`RUN` 可以判定为完善，必须同时满足：
|
||
|
||
```text
|
||
1. 每次 RUN 都能追溯到明确 INI。
|
||
2. 每次 RUN 都能说明机床类型和坐标轴。
|
||
3. 每次 RUN 都能说明使用哪个 LinuxCNC 五轴 kinematics module。
|
||
4. M428/M429/M430 的 switchkins 状态来自 LinuxCNC remap/HAL/task feedback 链。
|
||
5. activeLine、DRO、速度、DTG、程序时间来自同一个 task/HAL/motion feedback snapshot。
|
||
6. RUN 后 taskCycle/servoCycle 随时间持续推进，直到 paused/stopped/complete。
|
||
7. UI 高亮行和执行历史能复现逐行执行过程。
|
||
8. fallback playback 不能冒充 LinuxCNC task/HAL runtime。
|
||
```
|
||
|
||
未满足以上条件时，状态应继续标记为：
|
||
|
||
```text
|
||
fullLinuxCncProgramExecutionReady=false
|
||
hardwareDrive=false
|
||
hostRealtimeKernel=false
|
||
externalUserMProcessReady=false
|
||
```
|