398 lines
16 KiB
Markdown
398 lines
16 KiB
Markdown
# 基于 Web 的 RTCP 五轴联动数控系统仿真实现方案
|
||
|
||
生成时间：2026-06-20 CST
|
||
|
||
## 1. 项目定位
|
||
|
||
本项目建设一个独立的 Web 数控系统仿真界面，重点支持五轴联动与 RTCP/TCP 模式展示。系统以 LinuxCNC 源码、`configs/sim` 案例和 LinuxCNC Python 图形界面程序为参考基础，复用当前项目已经完成的 WASM、OPFS、virtual HAL、AXIS 风格 UI、G-code 执行仿真和 5 轴 source coverage 成果。
|
||
|
||
边界必须清晰：
|
||
|
||
- 这是 Web 数控系统仿真，不是硬实时机床控制器。
|
||
- 浏览器不直接驱动真实伺服、IO 或 Linux kernel realtime ABI。
|
||
- G-code 解释、canonical event、五轴运动学、remap 语义、tool/parameter 行为应尽量保持 LinuxCNC-owned。
|
||
- JavaScript 只做 UI、会话、文件 staging、WASM 调用、状态编排和可视化映射。
|
||
- 前端界面采用原生 HTML/CSS + TypeScript/JavaScript ES modules，不使用 React/Vue 等 UI 框架。
|
||
- LinuxCNC Python GUI 是界面和仿真结构参考，不是浏览器 runtime 依赖；Web 侧不直接运行 Tk/OpenGLTk、PyQt、GTK/Glade 或 native HAL GUI 进程。
|
||
|
||
## 2. 当前项目完成情况基线
|
||
|
||
当前 `wasm-port` 已经具备以下可继承能力：
|
||
|
||
- 浏览器真实仿真页面：`wasm-port/runtime/ui/simulation/index.html` 已实现 AXIS 风格界面、程序选择、编辑器、DRO、状态栏、Three.js 预览、播放控制和 browser smoke。
|
||
- LinuxCNC 解释器 WASM：已有 `createLinuxCncInterpSdk()` 路径，可运行内置和用户输入的 G-code，并输出 LinuxCNC canonical 事件。
|
||
- OPFS/session：已有 INI、参数文件、刀具表、G-code 程序、会话快照的浏览器侧持久化和加载工作流。
|
||
- virtual HAL：已有仿真级 HAL pin/signal/param、halcmd 风格命令、motion feedback stepping 和浏览器状态展示。
|
||
- 5 轴源码覆盖：已 vendored LinuxCNC `5axiskins.c`、`trtfuncs.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c`、`switchkins.*`、`userkfuncs.c` 等，且 source reuse 文档明确这些文件的验证边界。
|
||
- 5 轴案例覆盖：已纳入 LinuxCNC `configs/sim/axis/vismach/5axis/bridgemill`、`table-dual-rotary`、`table-rotary-tilting` 的 INI/HAL/NGC/remap assets。
|
||
- 当前 sim config inventory 基线：`executed=82`、`passed=82`、`skipped=77`、`unexpected_fail=0`；77 个 skipped row 已有实现覆盖账本，但不是全部 promotion。
|
||
- 本地 LinuxCNC 源码中可参考 Python 图形界面：`src/emc/usr_intf/axis/scripts/axis.py`、`lib/python/vismach.py`、`configs/sim/axis/vismach/5axis/*`、`configs/sim/gmoccapy/*`、`configs/sim/qtvcp_screens/*`。
|
||
|
||
未完成或不能直接宣称完成的点：
|
||
|
||
- RTCP/TCP 五轴联动还没有作为独立 Web 产品能力完整闭环。
|
||
- 当前浏览器页面主要是通用 AXIS 风格仿真，还不是专门的五轴/RTCP 操作界面。
|
||
- TRT/bridge 五轴运动学虽然有 source coverage 和 probe 基础，但需要形成面向 UI 的统一五轴 pose/joint/TCP 数据模型。
|
||
- 任意 Python remap、任意 external user-M host process、host tool DB process 等 hard block 仍不能伪装成浏览器 PASS；`tool.tbl` 和白名单 user-M 只允许在 `web_simulation_only` 边界内仿真。
|
||
- Python GUI 的 native 控件、HAL component 进程、Tk/PyQt/GTK 主循环和 OpenGLTk 不能直接作为 Web 运行时使用，需要转换成 Web 组件、Three.js 场景和 virtual HAL 数据绑定。
|
||
|
||
## 3. LinuxCNC 参考案例选择
|
||
|
||
第一阶段建议聚焦 LinuxCNC 已有 5 轴 sample，不泛化到任意机型。
|
||
|
||
优先参考案例：
|
||
|
||
```text
|
||
configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
|
||
configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
|
||
configs/sim/axis/vismach/5axis/bridgemill/5axis.ini
|
||
configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.ini
|
||
```
|
||
|
||
优先参考源码：
|
||
|
||
```text
|
||
src/emc/kinematics/trtfuncs.c
|
||
src/emc/kinematics/xyzac-trt-kins.c
|
||
src/emc/kinematics/xyzbc-trt-kins.c
|
||
src/emc/kinematics/5axiskins.c
|
||
src/emc/kinematics/switchkins.c
|
||
src/emc/kinematics/switchkins.h
|
||
src/emc/kinematics/userkfuncs.c
|
||
src/emc/kinematics/kins_util.c
|
||
```
|
||
|
||
关键 LinuxCNC 机制：
|
||
|
||
- `M428`：切换到 TCP/RTCP 相关五轴运动学模式，示例中设置 `motion.switchkins-type=1`。
|
||
- `M429`：恢复 identity/trivkins 模式，示例中设置 `motion.switchkins-type=0`。
|
||
- `M430`：切换到 user kinematics，作为后续扩展，不作为第一阶段必做。
|
||
- `HAL_PIN_VARS=1`：remap 子程序通过 `_hal[motion.switchkins-type]` 读取 HAL 状态。
|
||
- `M68`/`M66`：设置 analog output 并同步 HAL 状态。
|
||
- TRT 参数：`x-rot-point`、`y-rot-point`、`z-rot-point`、`x/y/z-offset`、`tool-offset`、`conventional-directions`。
|
||
|
||
## 4. Python 图形界面参考范围
|
||
|
||
LinuxCNC 的五轴仿真界面大量使用 Python 图形界面程序和 XML/HAL 配置组合。Web 项目应参考这些界面形态，但不把 Python GUI 作为浏览器依赖。
|
||
|
||
优先参考对象：
|
||
|
||
```text
|
||
src/emc/usr_intf/axis/scripts/axis.py
|
||
lib/python/vismach.py
|
||
configs/sim/axis/vismach/5axis/bridgemill/5axis.xml
|
||
configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.xml
|
||
configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.xml
|
||
configs/sim/axis/vismach/5axis/table-dual-rotary/xyzab-tdr.xml
|
||
configs/sim/axis/vismach/5axis/*/*postgui.hal
|
||
configs/sim/gmoccapy/gmoccapy_XYZAC.ini
|
||
configs/sim/qtvcp_screens/qtdragon/*
|
||
```
|
||
|
||
可借鉴的界面能力：
|
||
|
||
- AXIS 的菜单、工具栏、Manual/MDI、预览、DRO、G-code 高亮、状态栏。
|
||
- vismach 的层级机床模型：`Translate`、`Rotate`、`HalTranslate`、`HalRotate`，通过 HAL pin 驱动几何体姿态。
|
||
- PyVCP XML 的 `SWITCHKINS` 多状态标签、`TCP:XYZAC`/`IDENTITY`/`USERK` 按钮、joint 数值显示和 `vismach-clear` 操作。
|
||
- gmoccapy 的操作员面板、jog increment、override、嵌入式右侧面板和多轴配置。
|
||
- QtVCP/QtDragon 的现代面板布局、探测/刀具/状态区和大屏操作方式。
|
||
- LinuxCNC 文档中已有实际界面截图，可先用 `docs/linuxcnc-gui-reference-gallery.md` 中的图册做界面选型。
|
||
|
||
Web 转换规则：
|
||
|
||
```text
|
||
Python Tk/OpenGLTk/PyQt/GTK 控件 -> Web components
|
||
vismach OpenGL scene graph -> Three.js scene graph
|
||
HAL pin widget binding -> virtual HAL subscription/render binding
|
||
PyVCP XML controls -> declarative Web panel schema
|
||
AXIS/gmoccapy workflow -> browser operator workflow
|
||
native GUI process -> no direct browser dependency
|
||
```
|
||
|
||
前端实现规则：
|
||
|
||
```text
|
||
HTML/CSS: 页面结构、布局、主题、响应式约束
|
||
TypeScript/JavaScript ES modules: UI 控件、状态订阅、WASM/OPFS 调用、事件编排
|
||
Three.js: 五轴机床和刀路 3D 预览
|
||
Web Worker: LinuxCNC interpreter/kinematics WASM 计算隔离
|
||
Vite/esbuild: 只做开发服务器、TypeScript 编译和模块打包
|
||
```
|
||
|
||
禁止引入 React/Vue 等框架作为默认 UI 架构，避免把 CNC runtime 状态包进框架生命周期，增加调试和验证复杂度。
|
||
|
||
## 5. 总体架构
|
||
|
||
建议独立项目采用四层架构。
|
||
|
||
### 5.1 Web UI 层
|
||
|
||
职责：
|
||
|
||
- 五轴数控系统主界面；
|
||
- 程序编辑/加载/保存；
|
||
- 机床配置选择；
|
||
- RTCP 开关状态、kins 类型、刀具长度、旋转中心、A/B/C 角度展示；
|
||
- DRO、关节坐标、工件坐标、TCP 坐标、距离到达、运行状态；
|
||
- 三维机床模型、刀具姿态、刀尖中心点轨迹、已执行轨迹与完整轨迹；
|
||
- 报警、边界、未支持功能提示。
|
||
|
||
界面首选按 `gmoccapy_5_axis.png` 的工业操作台风格实现，并同时吸收 vismach/PyVCP/QtVCP 的界面结构。新项目界面要更偏向“五轴联动仿真工作台”：
|
||
|
||
```text
|
||
顶部：gmoccapy 风格标题栏，显示 machine/profile/session/run state
|
||
左侧：黑底 Three.js 五轴机床和 TCP 刀路预览
|
||
右上：大号绿色 DRO，显示 X/Y/Z/A/B/C、TCP、RTCP、DTG
|
||
中右：G-code 当前行列表和运行进度
|
||
右侧：竖向模式按钮栏，参考 gmoccapy 大按钮
|
||
中下：tool info / G-code properties / RTCP diagnostics tabs
|
||
下方：velocity、rapid/feed override、coolant、spindle 面板
|
||
底部：open、reload、run、stop、pause、step、home、fullscreen
|
||
```
|
||
|
||
额外要求：
|
||
|
||
- 左侧或右侧保留 PyVCP 风格的 `SWITCHKINS` 面板，清楚显示 `IDENTITY`、`TCP:XYZAC`、`TCP:XYZBC`、`USERK`。
|
||
- DRO 同时显示 axis pose、joint pose、TCP pose，不把关节坐标和工件坐标混在一起。
|
||
- Three.js 机床模型按 vismach 层级构建，所有旋转/平移节点都能追溯到 HAL pin 或 kinematics frame。
|
||
- 操作按钮参考 AXIS/gmoccapy 的 F1/F2/home/jog/run/step/stop/reset 逻辑，但只触发仿真 runtime。
|
||
|
||
### 5.2 Web Runtime/Session 层
|
||
|
||
职责：
|
||
|
||
- OPFS 会话管理；
|
||
- INI、HAL、tool table、parameter、G-code 文件 staging；
|
||
- 运行模式管理：standalone、machine-session、5axis-rtcp-session；
|
||
- program run summary；
|
||
- status/event history；
|
||
- diagnostics artifact。
|
||
|
||
已有 `runtime/opfs` 能作为参考，但新目录后续应建立独立命名空间，避免直接把原页面做成越来越大的单文件。
|
||
|
||
### 5.3 LinuxCNC WASM/Source Boundary 层
|
||
|
||
职责：
|
||
|
||
- 调用 LinuxCNC 解释器 WASM；
|
||
- 调用 LinuxCNC 五轴运动学 C/WASM ABI；
|
||
- 提供 `forwardKinematics()`、`inverseKinematics()`、`switchKinsType()` 这类窄接口；
|
||
- 捕获 canonical events、modal state、named parameters、tool offsets；
|
||
- 输出 source-derived motion frames。
|
||
|
||
关键要求：
|
||
|
||
```text
|
||
RTCP/五轴姿态计算必须优先由 vendored LinuxCNC kinematics 源码编译到 WASM 暴露；
|
||
JavaScript 不直接复写 trtfuncs.c / 5axiskins.c 的公式作为最终语义源。
|
||
```
|
||
|
||
### 5.4 Visualization/Playback 层
|
||
|
||
职责：
|
||
|
||
- 将 LinuxCNC 输出的 motion frame 映射为 Three.js 对象；
|
||
- 插值播放已验证 motion events；
|
||
- 显示 TCP 点、刀轴向量、刀具长度补偿、旋转中心、工作台/主轴姿态；
|
||
- 区分 programmed path、joint path、TCP executed path；
|
||
- 显示 RTCP on/off 对比。
|
||
- 用 Three.js 重建 vismach 的机床树，不直接移植 Python OpenGLTk 绘制代码。
|
||
- 支持显示 PyVCP/vismach 示例中的旋转中心、偏置点、真实旋转点、刀具长度和关节反馈。
|
||
|
||
注意：插值只用于显示，不能成为新的运动规划器。
|
||
|
||
## 6. RTCP 功能实现定义
|
||
|
||
本项目中的 RTCP 功能定义为仿真级 RTCP/TCP 能力：
|
||
|
||
- 读取或配置五轴机床类型：XYZAC、XYZBC、XYZBCW、XYZAB 等；
|
||
- 能识别 `M428/M429` 或 UI 切换产生的 kinstype 状态；
|
||
- 在 RTCP 模式下，以刀尖中心点为显示核心，展示旋转轴变化时 TCP 位置保持或按程序轨迹运动；
|
||
- 同时展示关节坐标和笛卡尔/TCP 坐标；
|
||
- 支持刀具长度、旋转中心、偏置参数改变后重新计算预览；
|
||
- 以 LinuxCNC forward/inverse kinematics 结果作为验算基础；
|
||
- 浏览器 smoke 能证明同一段 5 轴程序在 RTCP 模式下产生非空 A/B/C 姿态和 TCP 轨迹。
|
||
|
||
第一阶段不承诺：
|
||
|
||
- 真实伺服周期硬实时；
|
||
- 完整 LinuxCNC task/motion 进程；
|
||
- 任意 Python remap runtime；
|
||
- 任意 external user-M host process；
|
||
- 任意未在白名单内的 user-M 行为；
|
||
- 完整工业级碰撞检测；
|
||
- CAM 后处理器。
|
||
|
||
## 7. 数据模型
|
||
|
||
建议定义统一 frame：
|
||
|
||
```text
|
||
FiveAxisMotionFrame
|
||
sequence
|
||
sourceLine
|
||
time
|
||
kinsType
|
||
rtcpEnabled
|
||
workPose: X/Y/Z/A/B/C/U/V/W
|
||
jointPose: joint[0..N]
|
||
tcpPose: x/y/z + toolAxisVector
|
||
toolOffset
|
||
pivot/rotPoint
|
||
feed
|
||
spindle
|
||
canonicalEventRef
|
||
diagnostics
|
||
```
|
||
|
||
建议定义 machine profile：
|
||
|
||
```text
|
||
FiveAxisMachineProfile
|
||
id
|
||
title
|
||
family: xyzac-trt | xyzbc-trt | bridge-xyzbcw | tdr-xyzab
|
||
iniPath
|
||
coordinates
|
||
joints
|
||
kinematicsSource
|
||
halPins
|
||
remapCodes
|
||
limits
|
||
toolTable
|
||
samplePrograms
|
||
pythonGuiReferences
|
||
pyvcpControls
|
||
vismachModelNodes
|
||
```
|
||
|
||
## 8. 阶段计划
|
||
|
||
### Phase 0：方案和边界文档
|
||
|
||
当前交付。
|
||
|
||
输出：
|
||
|
||
- 独立目录；
|
||
- 实现方案；
|
||
- 技术路线；
|
||
- 明确当前完成情况和未完成边界。
|
||
|
||
### Phase 1：独立 Web 仿真骨架
|
||
|
||
目标：
|
||
|
||
- 新建独立 Web app；
|
||
- 复用或引入现有 SDK/WASM 产物；
|
||
- 页面能加载、选择五轴机床、显示 G-code、运行普通 LinuxCNC-backed 程序；
|
||
- Three.js 显示一个基础五轴机床模型和非空刀路。
|
||
- UI 布局参考 AXIS/gmoccapy，包含菜单、工具栏、Manual/MDI、预览、DRO、G-code、状态栏。
|
||
|
||
验收：
|
||
|
||
- 本地 dev server 可启动；
|
||
- browser smoke 截图非空；
|
||
- 运行现有线性/圆弧/G81 程序不回退。
|
||
|
||
### Phase 2：五轴 profile 和 5 轴 demo 接入
|
||
|
||
目标：
|
||
|
||
- 接入 `xyzac-trt`、`xyzbc-trt` 两个 profile；
|
||
- staging 对应 INI/HAL/tool table/remap_subs/demo；
|
||
- UI 能显示 kinematics 参数、HAL pins、M428/M429 状态；
|
||
- 执行 LinuxCNC 5 轴 sample 或经过裁剪的 representative demo。
|
||
- 解析 PyVCP XML/HAL 参考，生成 `SWITCHKINS`、joint value、offset/rot-point 等 Web 面板。
|
||
|
||
验收：
|
||
|
||
- 能展示 A/C 或 B/C 角度；
|
||
- 能显示 kinstype 0/1 切换；
|
||
- browser smoke 验证 `motion.switchkins-type` 状态。
|
||
|
||
### Phase 3：LinuxCNC 五轴运动学 WASM ABI
|
||
|
||
目标：
|
||
|
||
- 将 `trtfuncs.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c`、`5axiskins.c` 的 forward/inverse 调用通过窄 C ABI 暴露给 Web runtime；
|
||
- 建立 HAL pin shim，为旋转中心、偏置、刀具长度提供输入；
|
||
- 输出 joint/work/TCP frame。
|
||
|
||
验收：
|
||
|
||
- Node smoke：forward -> inverse roundtrip；
|
||
- browser smoke：同一 frame 显示 joint pose、work pose、TCP pose；
|
||
- source sync guard 仍通过。
|
||
|
||
### Phase 4：RTCP/TCP 预览与播放
|
||
|
||
目标：
|
||
|
||
- RTCP mode on/off 可视化；
|
||
- 显示 programmed path、TCP path、joint path；
|
||
- 刀轴方向随 A/B/C 变化；
|
||
- 刀尖中心点轨迹与 LinuxCNC kinematics frame 对齐。
|
||
- Three.js 机床层级与 vismach Python 示例的几何层级一致：工作台、转台、摆头、主轴、刀具和工件分别建模。
|
||
|
||
验收：
|
||
|
||
- RTCP 开启时，旋转轴变化不导致 UI 随机漂移；
|
||
- 对 `M428/M429` 状态有明确显示；
|
||
- 截图 smoke 校验 canvas 非空、刀具姿态非默认、路径点数非零。
|
||
|
||
### Phase 5：操作级数控系统仿真
|
||
|
||
目标：
|
||
|
||
- Manual/MDI、单段、连续、暂停、复位；
|
||
- 程序行高亮、motion segment 高亮；
|
||
- 坐标系、刀具长度、旋转中心参数编辑和重新仿真；
|
||
- OPFS 保存/恢复完整 5 轴会话。
|
||
|
||
验收：
|
||
|
||
- 保存 -> 恢复 -> 重新运行结果一致；
|
||
- UI 提供 operator-facing 状态，不只是 diagnostics dashboard。
|
||
|
||
### Phase 6：扩展验证和发布
|
||
|
||
目标：
|
||
|
||
- 建立 release gate；
|
||
- 建立 regression fixtures；
|
||
- 添加更多 LinuxCNC 5 轴案例；
|
||
- 文档化不支持范围。
|
||
|
||
验收：
|
||
|
||
- `git diff --check`；
|
||
- source/vendor sync；
|
||
- Node/browser smoke；
|
||
- screenshot/canvas-pixel check；
|
||
- release readiness artifact。
|
||
|
||
## 9. 风险与处理
|
||
|
||
主要风险：
|
||
|
||
- 把 RTCP 公式写在 JS 中，破坏 LinuxCNC semantic boundary。
|
||
- 5 轴 demo 依赖 remap/HAL 同步，直接跑全量程序可能遇到 runtime boundary。
|
||
- Vismach Python GUI 不能直接迁移到浏览器。
|
||
- 把 Python GUI 参考误解成要在浏览器中运行 Python/Tk/PyQt，会导致架构失控。
|
||
- WebGL 3D 和 G-code 执行状态容易脱节。
|
||
- 过早承诺完整工业 RTCP 会扩大范围。
|
||
|
||
处理策略：
|
||
|
||
- 第一阶段只做 source-derived kinematics ABI，不做 JS-owned CNC semantics。
|
||
- demo 程序分 representative subset 和 full upstream demo 两级。
|
||
- Vismach 只作为机床结构参考，浏览器用 Three.js 重建可视化，不移植 Python GUI。
|
||
- PyVCP/gmoccapy/QtVCP 只作为 panel schema 和 operator workflow 参考，控件用 Web 原生实现。
|
||
- 所有 UI frame 都要带 canonical/ref 或 kinematics/ref 追踪字段。
|
||
- hard block 保持显式 blocked，不因为 UI 能显示就 promotion。
|
||
|
||
## 10. 结论
|
||
|
||
当前项目已经具备 Web 数控系统仿真的基础设施，但 RTCP 五轴联动还需要单独产品化。下一步应在独立目录中先搭建五轴 Web 仿真骨架，界面形态参考 LinuxCNC 的 AXIS、vismach、PyVCP、gmoccapy 和 QtVCP Python 图形界面，再把 LinuxCNC TRT/bridge 五轴运动学通过 WASM ABI 接入，最后形成 RTCP/TCP 轨迹、关节姿态、刀尖中心点和机床模型同步显示的浏览器仿真界面。
|