wangdequan/cnc_wams
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: sync latest run execution updates

Browse Source
This commit is contained in:
wangdequan
2026-06-22 21:47:16 -04:00
parent 0b1aad39e1
commit 8d3177cb73
92 changed files with 22837 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

726
web-rtcp-5axis-sim-plan/feed-rate-run-fix/README.md Normal file
View File

@@ -0,0 +1,726 @@
# G-code F 进给速度驱动 RUN 执行修复文档
生成时间：2026-06-22
## 1. 问题结论
当前 `RUN` 链路已经能完成：
```text
1. 打开 LinuxCNC G-code 程序。
2. 通过 task/HAL runtime 推进状态。
3. 更新当前行、高亮行、DRO、axisPose、执行轨迹和 task/HAL feedback。
```
但当前 `RUN` **还没有按 G-code 的真实进给速度执行**。
当前关键问题：
```text
G-code interpreter 能解析 F。
execution-timing.js 能基于 F / 距离 / INI 限速做 feed-based timing estimate。
但是 task/HAL RUN 执行链路没有把 F 用作真实运行速度。
C++ wrapper 层固定写入 velocity=60。
activeLine 按 task cycle 推进一行，而不是按 段距离 / F / elapsed time 推进。
```
因此现有浏览器 RUN 证据只能证明：
```text
task/HAL feedback 正在产生；
UI 当前行与 task/HAL active line 同步；
DRO 与 runtime axisPose 同步；
执行轨迹可见；
```
不能证明：
```text
程序按 G-code F 进给速度、G93/G94 模态、rapid/feed 区分、override、段距离真实定时执行。
```
## 2. 当前源码证据
### 2.1 固定 velocity=60
文件：
```text
wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp
```
函数：
```text
enqueue_linear_move_from_line(TaskRuntime &state, const std::string &line)
```
当前逻辑：
```cpp
command << ",\"velocity\":60}";
```
影响：
```text
1. 每条 G-code 运动行传给 motion runtime 的速度都是 60 units/s。
2. JS 状态层把 currentVel * 60 转成 mm/min。
3. 在 mm 单位下 UI 看到的速度固定为 3600 mm/min。
4. G-code 行中的 F159 / F318 / F636 等不会影响 RUN 实际速度。
```
### 2.2 按 task cycle 推进一行
文件：
```text
wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp
```
函数：
```text
lctask_run_cycles(long task_period_ns, long servo_period_ns, int task_cycles)
```
当前逻辑：
```cpp
for (int i = 0; i < task_cycles; ++i) {
state.task_cycle += 1;
if (state.interp_state == "READING" && state.next_program_line < state.opened_line_count) {
enqueue_linear_move_from_line(state, state.program_lines[state.next_program_line]);
...
}
lcmot_step_servo(...);
}
```
影响：
```text
1. 每个 task cycle 至多 enqueue 一条程序行。
2. active line 由 cycle 数推进。
3. 长段、短段、F 快、F 慢不会改变行推进节奏。
4. 这不是真实 LinuxCNC planner/task/motion 的时间语义。
```
### 2.3 interpreter 已有 F 信息
文件：
```text
web-rtcp-5axis-sim-plan/app/src/runtime/linuxcnc-interpreter-runtime.js
```
已有能力：
```text
1. feedRatesBySourceLine(programText) 从 G-code 中提取 F。
2. parseLinuxCncCanonicalMotion(...) 把 activeFeedRate 写入 motion event 的 feedRate。
3. linearUnitsBySourceLine(...) 跟踪 G20/G21。
```
输出 motion event 已包含：
```js
{
type,
line,
axes,
feedRate,
linearUnits,
...
}
```
### 2.4 timing estimate 已有 F 计算
文件：
```text
web-rtcp-5axis-sim-plan/app/src/runtime/execution-timing.js
```
已有能力：
```text
1. 按 motion event feedRate 计算 requestedLinearVelocity。
2. 按 profile/INI max velocity 限速。
3. 按 linear distance / angular distance 计算 segment durationSeconds。
4. 处理 feedOverride / rapidOverride。
```
但当前边界是：
```text
semanticBoundary = linuxcnc_canonical_motion_timing_estimate_not_planner_queue
```
说明它是估算，不是 task/HAL RUN 的权威执行节奏。
## 3. 修复目标
### 3.1 必须达成
修复后 `RUN` 必须满足：
```text
1. G-code 中 F 值进入 task/HAL RUN 执行链路。
2. G94 units/min 模式下，feed move 的速度来自当前 modal F。
3. G0/STRAIGHT_TRAVERSE 使用 rapid velocity / rapid override / INI max velocity。
4. activeLine 按 elapsed execution time 与当前段完成度推进。
5. 长距离低 F 段明显运行更久。
6. 短距离高 F 段明显更快完成。
7. UI currentVelocity 不再固定 3600 mm/min。
8. DRO/axisPose 可以在段内插值，而不是只在行边界跳变。
9. 现有 RUN gate、task/HAL session、status loop、STOP/ABORT/STEP 不回退。
```
### 3.2 第一阶段不强求
以下可以作为第二阶段：
```text
1. 完整 LinuxCNC trajectory planner queue 动力学一致性。
2. 加速度/jerk/圆弧真实插补完全对齐 LinuxCNC。
3. G93 inverse-time feed 的完整五轴角度/线性混合真实语义。
4. 硬件 realtime HAL 驱动。
```
但第一阶段至少不能继续固定 `velocity=60`。
## 4. 推荐实现方案
### 4.1 不要继续在 C++ wrapper 中逐行粗解析 G-code
当前 C++ wrapper 的 `enqueue_linear_move_from_line()` 是字符串扫描：
```text
查找 XYZABC 字母；
strtod 读取数值；
没有模态；
没有 F；
没有 G90/G91；
没有 G20/G21；
没有 G93/G94；
没有 G0/G1/G2/G3 区分；
```
这个方向继续扩展会很脆弱。
推荐改为：
```text
JS interpreter runtime 继续负责生成 canonical motion events。
JS 侧把 canonical motion + timing segments 传入 task/HAL runtime session。
C++ task/HAL wrapper 不再直接解析 G-code 行来生成 velocity。
C++ task/HAL wrapper 按已解析 motion segment 执行。
```
### 4.2 新增 task/HAL program motion plan
在 `wasm-port/runtime/sdk/src/linuxcnc-task-hal.js` 增加可选 API：
```js
loadProgramMotionPlan({
programPath,
motion,
timing,
linearUnits,
})
```
在 C++ wrapper 增加导出：
```cpp
int lctask_load_program_motion_plan_json(const char *plan_json);
```
motion plan 中至少包含：
```json
{
"programPath": "...",
"segments": [
{
"line": 8,
"type": "STRAIGHT_FEED",
"motionClass": "feed",
"axes": { "x": 6.302, "y": -11.560, "z": 27.743, "a": -71.841, "c": -35.930 },
"startAxes": { "...": 0 },
"feedRate": 318,
"linearUnits": "mm",
"velocityMmPerMin": 318,
"durationSeconds": 0.42,
"startSeconds": 1.25,
"elapsedSeconds": 1.67
}
]
}
```
### 4.3 C++ task runtime 状态新增字段
`TaskRuntime` 增加：
```cpp
struct MotionSegment {
int line = 0;
std::string type;
std::string motion_class;
double start_seconds = 0.0;
double duration_seconds = 0.0;
double velocity_mm_per_min = 0.0;
std::map<std::string, double> start_axes;
std::map<std::string, double> end_axes;
};
std::vector<MotionSegment> motion_plan;
int active_segment_index = 0;
double run_elapsed_seconds = 0.0;
double run_start_seconds = 0.0;
```
### 4.4 RUN 周期推进改为按 elapsed time
当前：
```text
每 task cycle enqueue 一行。
```
修复后：
```text
每次 lctask_run_cycles 根据 task_period_ns * task_cycles 增加 run_elapsed_seconds。
根据 run_elapsed_seconds 找到 active segment。
按 segment progress 插值 axisPose。
把 currentVel/requestedVel 设置为 segment.velocityMmPerMin / 60。
activeLine = segment.line。
segment 完成后才进入下一 segment。
```
伪代码：
```cpp
int lctask_run_cycles(long task_period_ns, long servo_period_ns, int task_cycles)
{
const double delta_seconds = (task_period_ns / 1e9) * task_cycles;
state.run_elapsed_seconds += delta_seconds;
const MotionSegment *segment = find_segment_at_time(state.motion_plan, state.run_elapsed_seconds);
if (!segment) {
state.interp_state = "IDLE";
state.exec_state = "DONE";
return step_servo(...);
}
const double local = state.run_elapsed_seconds - segment->start_seconds;
const double progress = clamp(local / segment->duration_seconds, 0.0, 1.0);
AxisPose pose = interpolate(segment->start_axes, segment->end_axes, progress);
forward_motion_sample({
line: segment->line,
axes: pose,
currentVel: segment->velocity_mm_per_min / 60.0,
requestedVel: segment->velocity_mm_per_min / 60.0,
inPosition: progress >= 1.0
});
step_servo(...);
}
```
### 4.5 motion runtime command schema
当前 motion command 是：
```json
{
"type": "EMC_TRAJ_LINEAR_MOVE",
"line": 12,
"x": 1,
"velocity": 60
}
```
建议新增或扩展为：
```json
{
"type": "EMC_TRAJ_LINEAR_SAMPLE",
"line": 12,
"x": 1.2,
"y": 3.4,
"z": 5.6,
"a": -70,
"c": 20,
"currentVel": 5.3,
"requestedVel": 5.3,
"segmentProgress": 0.35,
"source": "feed_timed_motion_plan"
}
```
如果不想新增 command type，也可以继续使用 `EMC_TRAJ_LINEAR_MOVE`，但必须：
```text
1. velocity 来自 segment.velocityMmPerMin / 60。
2. axes 是当前插值位置，而不是只用 segment end。
3. status 能保留 line/progress/currentVel。
```
## 5. G94 速度规则
### 5.1 G94 units per minute
在 `TRAJ.LINEAR_UNITS=mm` 时：
```text
F318 => 318 mm/min
```
在 `TRAJ.LINEAR_UNITS=inch` 或 G20 active 时：
```text
F10 => 10 inch/min => 254 mm/min
```
计算：
```text
velocity_mm_per_min = feedRate * linearUnitScaleToMm * feedOverride
duration_seconds = linearDistanceMm / (velocity_mm_per_min / 60)
```
### 5.2 Rapid
G0 / `STRAIGHT_TRAVERSE`：
```text
velocity_mm_per_min = min(INI max velocity, profile max velocity) * rapidOverride
duration_seconds = distance / velocity
```
### 5.3 Angular axes
第一阶段可沿用 `execution-timing.js` 现有策略：
```text
linearSeconds = linearDistanceMm / linearVelocity
angularSeconds = angularDistanceDeg / angularVelocity
durationSeconds = max(linearSeconds, angularSeconds)
```
这至少能避免旋转轴运动被零时长吞掉。
### 5.4 G93 inverse time
LinuxCNC impeller 程序包含：
```text
G93
...
G1 ... F159
```
G93 的 F 不是 units/min，而是 inverse time。第一阶段有两种策略：
```text
方案 A：先检测 G93，明确标注 unsupported，RUN gate 阻止真实 feed mode 运行。
方案 B：实现基础 inverse-time：duration_minutes = 1 / F，duration_seconds = 60 / F。
```
推荐：
```text
第一阶段实现方案 B。
```
原因：
```text
1. test_linuxcnc_source/impeller-7bl-xyzac.ngc 使用 G93。
2. 如果不支持 G93，就无法验证用户当前指定测试文件的真实进给语义。
3. 对 inverse-time，F 直接定义该运动块完成时间，适合第一阶段验证。
```
需要在 interpreter motion event 中增加：
```js
feedMode: "inverse-time" | "units-per-minute"
```
或至少在 timing 阶段通过 source line 扫描维护 G93/G94 模态。
## 6. 代码修改落点
### 6.1 `linuxcnc-interpreter-runtime.js`
新增：
```text
feedModeBySourceLine(programText)
```
识别：
```text
G93 => inverse-time
G94 => units-per-minute
```
motion event 增加：
```js
feedMode: activeFeedMode
```
### 6.2 `execution-timing.js`
修改 `buildTimingSegment(...)`：
```text
if event.feedMode === "inverse-time":
durationSeconds = 60 / feedRate
velocityMmPerMin = linearDistanceMm / durationSeconds * 60
else:
保持 G94 units/min 逻辑
```
注意：
```text
1. G93 中 F 必须大于 0。
2. G93 中如果缺 F，应保留上一个 modal F 或报错，按 LinuxCNC 语义确认。
3. velocity 仍要可被 INI max velocity 限制还是忠实 inverse-time，需要明确。第一阶段建议记录 requested 与 capped 两个值。
```
### 6.3 `store.js`
在 `initializeTaskHalSession` 后或 `RUN_INTERPRETER_PROGRAM` 完成后，把当前 `programExecution.motion` 与 `programExecutionTiming.segments` 传给 task/HAL runtime：
```js
await state.taskHalRuntime.loadProgramMotionPlan({
programPath: session.programPath,
motion: state.programExecution.motion,
timing: state.programExecutionTiming,
linearUnits: state.profile.traj.linearUnits,
});
```
需要保证：
```text
1. LOAD_LINUXCNC_GCODE_SOURCE 后 interpreter 已完成。
2. task/HAL openProgram 的 programPath 与 motion plan programPath 一致。
3. 如果 motion plan 不存在，RUN gate 应阻止“真实进给速度 RUN”，不能悄悄回退 velocity=60。
```
### 6.4 `linuxcnc-task-hal.js`
新增 SDK 方法：
```js
loadProgramMotionPlan(plan) {
const rc = callWithJson(mod, "lctask_load_program_motion_plan_json", plan);
if (rc !== 0) throw new Error(...);
}
```
### 6.5 `linuxcnc_task_hal_wasm.hh`
新增声明：
```cpp
int lctask_load_program_motion_plan_json(const char *plan_json);
```
### 6.6 `linuxcnc_task_hal_wasm.cpp`
新增：
```text
1. MotionSegment 数据结构。
2. 简单 JSON plan parser，或复用现有轻量 json_number_after 风格解析数组。
3. lctask_load_program_motion_plan_json。
4. lctask_run_cycles 按 elapsed time 找 segment。
5. 删除或隔离 fixed velocity=60 的 fallback。
```
要求：
```text
fixed velocity=60 只能作为 explicit fixture fallback。
真实 RUN 路径不允许使用它。
```
## 7. 测试计划
### 7.1 Node 单元测试：F 值改变 duration
新增测试：
```text
web-rtcp-5axis-sim-plan/tests/node/verify_feed_rate_execution_timing.mjs
```
用例：
```gcode
G90 G94
G1 X10 F60
G1 X20 F600
M2
```
期望：
```text
第一段 10mm @ 60mm/min => 10s。
第二段 10mm @ 600mm/min => 1s。
duration ratio ≈ 10:1。
```
### 7.2 Node 单元测试：G93 inverse time
用例：
```gcode
G90 G93
G1 X10 F2
G1 X20 F10
M2
```
期望：
```text
F2 => 60/2 = 30s。
F10 => 60/10 = 6s。
```
### 7.3 task/HAL runtime 测试：速度不固定
新增或扩展：
```text
web-rtcp-5axis-sim-plan/tests/node/verify_run_feedback_loop.mjs
```
断言：
```text
1. RUN feedback currentVelocityMmPerMin 不等于固定 3600。
2. 不同 F 段采样到不同 requested/current velocity。
3. activeLine 不再每 task cycle 固定递增一行。
4. 慢速段停留采样数 > 快速段。
```
### 7.4 浏览器证据测试
扩展：
```text
qa/web-rtcp-5axis-site-test/capture-test-linuxcnc-source-run.mjs
```
新增报告字段：
```text
feedMode
feedRate
segmentDurationSeconds
segmentProgress
requestedVelocityMmPerMin
currentVelocityMmPerMin
```
报告验收：
```text
1. impeller G93 行显示 inverse-time。
2. 采样 velocity 随当前 segment 变化。
3. 当前行停留时间与 F 值/段时长一致。
4. Word 报告中列出 F、feedMode、duration、velocity 的采样表。
```
## 8. 验收标准
修复完成必须通过：
```bash
node web-rtcp-5axis-sim-plan/tests/node/verify_feed_rate_execution_timing.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_run_feedback_loop.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_linear_unit_conversion.mjs
npm --prefix web-rtcp-5axis-sim-plan/app run build
npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
node qa/web-rtcp-5axis-site-test/capture-test-linuxcnc-source-run.mjs
```
并满足：
```text
1. 不再出现所有 RUN 样本 velocity=3600 的固定速度现象。
2. C++ task/HAL RUN 主路径不再写死 velocity=60。
3. G94 F60/F600 用例体现 10:1 段时长差异。
4. G93 F2/F10 用例体现 5:1 段时长差异。
5. test_linuxcnc_source/impeller-7bl-xyzac.ngc 的 RUN 报告包含 feedMode/feedRate/duration 证据。
6. STOP/ABORT/STEP 现有测试不回退。
```
## 9. 风险与注意事项
### 9.1 不要伪造 LinuxCNC 语义
如果还没有完整 planner，就必须在状态中明确：
```text
semanticBoundary = feed_timed_canonical_motion_runtime
```
不要标称为真实 LinuxCNC planner。
### 9.2 不要把 estimate 当作硬件实时
第一阶段可以做到：
```text
canonical motion + feed mode + timing driven browser simulation
```
不能声称：
```text
hardware realtime LinuxCNC execution
```
### 9.3 G93 是当前 impeller 文件的关键
`test_linuxcnc_source/impeller-7bl-xyzac.ngc` 开头有：
```gcode
M428 ;TCP:xyzac
G93
S600 M3
```
因此如果不处理 G93，针对该文件的“真实 F 速度”验证仍然不完整。
## 10. 建议实施顺序
```text
1. 给 interpreter motion event 增加 feedMode。
2. 给 execution-timing.js 增加 G93 duration。
3. 写 verify_feed_rate_execution_timing.mjs，先证明 timing 正确。
4. 给 task/HAL SDK/WASM 增加 loadProgramMotionPlan。
5. 改 lctask_run_cycles，按 elapsed time 和 segment progress 推进。
6. 改 store，把 motion plan 注入 task/HAL session。
7. 扩展 verify_run_feedback_loop，证明 velocity 不固定、慢段停留更久。
8. 扩展浏览器 RUN 报告，输出 feedMode/feedRate/duration/progress。
9. 重跑 build、smoke、浏览器报告。
10. 更新 working_run 和 gptlog-process。
```