530 lines
24 KiB
Markdown
530 lines
24 KiB
Markdown
# `xyzac-trt.ini` 控制面板、数据流、控制约束与 Web/WASM 设计基础
|
||
|
||
更新时间：2026-08-25
|
||
|
||
本文专门分析：
|
||
|
||
```text
|
||
linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini
|
||
```
|
||
|
||
目标不是复刻一个静态 AXIS 外观，而是为 Web/WASM 控制台建立可验证的功能、数据、控制和权限模型。所有“按钮是否可点”的结论都必须来自 LinuxCNC authoritative task/motion/HAL 状态；React/浏览器只能投影状态并发出带 gate 的命令。
|
||
|
||
相关运行入口和基础说明：
|
||
|
||
- [`run-5axis-rtcp.sh`](../run-5axis-rtcp.sh)
|
||
- [`5axis-rtcp-shortcut.md`](5axis-rtcp-shortcut.md)
|
||
- [`gmoccapy-control-panel-data-control-flow.md`](gmoccapy-control-panel-data-control-flow.md)
|
||
- [`5axis-rtcp-running.png`](5axis-rtcp-running.png)
|
||
|
||
## 1. 案例边界
|
||
|
||
### 1.1 入口配置
|
||
|
||
`xyzac-trt.ini` 的关键配置如下：
|
||
|
||
| INI 段 | 字段 | 功能 |
|
||
|---|---|---|
|
||
| `[EMC]` | `MACHINE = sim-xyzac-trt-kins (switchkins)` | 案例名称和 switchkins 语义 |
|
||
| `[DISPLAY]` | `DISPLAY = axis` | 主控制面板是 AXIS/Tk，不是 GMOCCAPY |
|
||
| `[DISPLAY]` | `OPEN_FILE = ./demos/xyzac_switchkins.ngc` | 启动后预置的 G-code 文件 |
|
||
| `[DISPLAY]` | `PYVCP = ./xyzac-trt.xml` | 右侧 SWITCHKINS/vismach-clear 面板 |
|
||
| `[DISPLAY]` | `JOG_AXES = XYZC` | 手动点动显示 X/Y/Z/C；A 仍属于五轴运动学 |
|
||
| `[DISPLAY]` | `PROGRAM_PREFIX = ../../nc_files` | 默认程序搜索目录 |
|
||
| `[DISPLAY]` | `POSITION_OFFSET = RELATIVE` | DRO 默认显示相对坐标 |
|
||
| `[DISPLAY]` | `POSITION_FEEDBACK = ACTUAL` | DRO 使用 actual position |
|
||
| `[RS274NGC]` | `SUBROUTINE_PATH = ./remap_subs` | M428/M429/M430 和 helix 子程序路径 |
|
||
| `[RS274NGC]` | `HAL_PIN_VARS = 1` | 允许 remap 访问 HAL pin |
|
||
| `[RS274NGC]` | `REMAP = M428/M429/M430` | kinematics 状态切换入口 |
|
||
| `[RS274NGC]` | `PARAMETER_FILE = xyzac.var` | RS274 参数持久化 |
|
||
| `[KINS]` | `KINEMATICS = xyzac-trt-kins sparm=identityfirst` | 5 关节 XYZAC，0=identity，1=TRT，2=userk |
|
||
| `[KINS]` | `JOINTS = 5` | X/Y/Z/A/C 五个 joint |
|
||
| `[HAL]` | `HALFILE = LIB:basic_sim.tcl` | 生成仿真 motion/HAL/模拟设备 |
|
||
| `[HAL]` | `POSTGUI_HALFILE = switchkins_postgui.hal` | GUI 创建后连接 PyVCP 控件 |
|
||
| `[HAL]` | `motion.analog-out-03 => motion.switchkins-type` | remap 写入 switchkins 的控制通道 |
|
||
| `[HAL]` | `loadusr -W xyzac-trt-gui` | 独立 Vismach 五轴模型进程 |
|
||
| `[TRAJ]` | `COORDINATES = XYZAC` | 解释器和轨迹规划的笛卡尔坐标集合 |
|
||
| `[EMCIO]` | `TOOL_TABLE = xyzac-trt.tbl` | 工具长度/直径等数据 |
|
||
|
||
### 1.2 三个界面实体
|
||
|
||
```text
|
||
AXIS 主窗口
|
||
├── Tk 菜单、工具栏、Manual Control、MDI、Preview、DRO、G-code view
|
||
├── PyVCP xyzac-trt.xml（右侧 SWITCHKINS 面板）
|
||
└── AXIS 内部 Python/Tk command + linuxcnc.stat 状态轮询
|
||
|
||
xyzac-trt-gui 进程
|
||
└── Python vismach 模型，仅消费 HAL joint feedback/tool-offset/offset
|
||
|
||
LinuxCNC runtime
|
||
├── linuxcncsvr / NML
|
||
├── milltask / RS274NGC interpreter
|
||
├── motmod / TP / switchkins / xyzac-trt-kins
|
||
└── HAL / simulated home / spindle / tool-change / PyVCP pins
|
||
```
|
||
|
||
AXIS 是控制和状态投影者，PyVCP 是 HAL 控件，Vismach 是可视化消费者；三者都不是独立的运动 authority。
|
||
|
||
## 2. 启动与初始化数据流
|
||
|
||
```text
|
||
run-5axis-rtcp.sh
|
||
│
|
||
▼
|
||
/usr/bin/linuxcnc -r xyzac-trt.ini
|
||
│
|
||
├── 读取 [DISPLAY]/[TASK]/[HAL]/[KINS]/[TRAJ]
|
||
├── 启动 linuxcncsvr
|
||
├── 启动 milltask
|
||
├── 运行 basic_sim.tcl 生成 HAL
|
||
├── loadusr xyzac-trt-gui
|
||
├── 执行 switchkins_postgui.hal
|
||
└── 启动 /usr/bin/axis -ini xyzac-trt.ini
|
||
│
|
||
├── open_file_guts(OPEN_FILE)
|
||
├── 创建 Tk/AXIS widgets
|
||
├── 读取 linuxcnc.stat
|
||
└── 周期刷新 DRO/preview/gates
|
||
```
|
||
|
||
### 2.1 AXIS 初始化的责任
|
||
|
||
主要来源：
|
||
|
||
```text
|
||
linuxcnc/src/emc/usr_intf/axis/scripts/axis.py
|
||
```
|
||
|
||
核心职责：
|
||
|
||
1. 解析 INI 和显示选项。
|
||
2. 初始化 `linuxcnc.command()`、`linuxcnc.stat()` 和 HAL component。
|
||
3. 根据 `COORDINATES=XYZAC` 建立 axis/joint 映射。
|
||
4. 读取 `OPEN_FILE`，通过 `open_file_guts()` 和 `c.program_open()` 载入程序。
|
||
5. 读取 G-code，运行 canon/preview 生成程序轨迹。
|
||
6. 周期 `s.poll()`，将 position、joint position、homed、limit、tool、G/M code、task/interpreter state 投影到 Tk 变量。
|
||
7. 根据 `running()`、`manual_ok()`、`all_homed()` 和 task/motion 状态决定按钮是否响应。
|
||
|
||
### 2.2 Vismach 初始化的责任
|
||
|
||
`linuxcnc/src/hal/user_comps/vismach/xyzac-trt-gui.py` 创建 HAL component：
|
||
|
||
```text
|
||
xyzac-trt-gui.table-x HAL_FLOAT IN
|
||
xyzac-trt-gui.saddle-y HAL_FLOAT IN
|
||
xyzac-trt-gui.spindle-z HAL_FLOAT IN
|
||
xyzac-trt-gui.tilt-a HAL_FLOAT IN
|
||
xyzac-trt-gui.rotate-c HAL_FLOAT IN
|
||
xyzac-trt-gui.y-offset HAL_FLOAT IN
|
||
xyzac-trt-gui.z-offset HAL_FLOAT IN
|
||
xyzac-trt-gui.tool-offset HAL_FLOAT IN
|
||
```
|
||
|
||
模型通过 `HalTranslate`/`HalRotate` 将这些输入转换为 OpenGL 模型姿态。它不发 `program_run`、`jog`、`home` 或 kinematics 命令。
|
||
|
||
## 3. AXIS 主控制面板功能
|
||
|
||
### 3.1 顶部菜单和工具栏
|
||
|
||
AXIS/Tk 主面板通常提供：
|
||
|
||
| 类别 | 典型动作 | LinuxCNC command/效果 |
|
||
|---|---|---|
|
||
| 文件 | Open | `program_open(path)`，更新 loaded file 和 preview |
|
||
| AUTO 按钮组 | `hbtb_auto` / `btn_load` | AXIS 的 Open/Load 文件入口；只在程序未运行时打开文件选择器 |
|
||
| 文件 | Reload | 重新读取当前文件；运行中拒绝 |
|
||
| 文件 | Recent files | 偏好文件保存最近路径，最多 10 项 |
|
||
| 文件 | Edit | 调用 `EDITOR`/外部编辑器；不改变 runtime authority |
|
||
| 程序 | Run | `c.mode(MODE_AUTO)` + `c.auto(AUTO_RUN, start_line)` |
|
||
| 程序 | Step | `c.auto(AUTO_STEP)` |
|
||
| 程序 | Pause | `c.auto(AUTO_PAUSE)` |
|
||
| 程序 | Resume | `c.auto(AUTO_RESUME)` |
|
||
| 程序 | Stop | `c.abort()`，同时设置 GUI abort 状态 |
|
||
| 程序 | Run from line | 设置 first line 后再 AUTO_RUN，风险高于普通 Run |
|
||
| 机床 | Power | `c.state(STATE_ON/OFF)` |
|
||
| 机床 | E-stop | `c.state(STATE_ESTOP/STATE_ESTOP_RESET)` 或硬件链路 |
|
||
| 机床 | Home/Unhome | `c.home(joint)` / `c.unhome(joint)` |
|
||
| 机床 | Spindle | `c.spindle(...)` 或 MDI/halui |
|
||
| 机床 | Feed/rapid/spindle override | `c.feedrate()`/`c.maxvel()` 或相应 HAL/command |
|
||
| 辅助 | HAL show/tooleditor | 外部工具或 tool data action |
|
||
| 视图 | Perspective/X/Y/Z/clear plot | 只改变 view/preview，不改变运动状态 |
|
||
|
||
菜单图标不是 authority。每个动作必须以 command result 和下一次 status snapshot 确认。
|
||
|
||
### 3.2 Manual Control
|
||
|
||
Manual 页包含：
|
||
|
||
- X/Y/Z/A/C 轴选择；`JOG_AXES=XYZC` 会影响默认可点动轴列表。
|
||
- Continuous/incremental jog 选择。
|
||
- jog speed、angular jog speed。
|
||
- Home All、单轴 Home、Unhome。
|
||
- Touch Off、Tool Touch Off。
|
||
- feed/rapid/spindle override。
|
||
- spindle start/stop/reverse。
|
||
|
||
AXIS 的 `manual_ok()` 条件：
|
||
|
||
```text
|
||
task_state == STATE_ON
|
||
并且当前没有 AUTO/MDI 正在运行
|
||
并且 interp_state == INTERP_IDLE
|
||
或当前为 MDI 且 queued_mdi_commands < max_queued_mdi_commands
|
||
```
|
||
|
||
`jog_on()` 还要满足当前 tab 是 manual、轴/joint 映射有效、没有 active limit 阻止动作。Web/WASM 应把这些结果作为 gate reason 返回，不仅仅把 HTML button 设为 disabled。
|
||
|
||
### 3.3 MDI
|
||
|
||
MDI 入口通过 `ensure_mdi()`：
|
||
|
||
1. 检查 `manual_ok()`。
|
||
2. 关闭 teleop 或切换到合适 motion mode。
|
||
3. `c.mode(MODE_MDI)`。
|
||
4. 用户输入字符串后调用 `c.mdi(command)`。
|
||
5. interpreter 执行后由 `stat.interp_state`、`queued_mdi_commands`、位置和错误通道反馈。
|
||
|
||
MDI 不是任意字符串的本地脚本执行器。Web/WASM 必须保留 G-code parser、能力边界、长度限制、错误码和 operation id。
|
||
|
||
### 3.4 Preview/DRO/G-code view
|
||
|
||
AXIS 周期更新同时刷新：
|
||
|
||
- `stat.actual_position` / `joint_actual_position` → DRO。
|
||
- `stat.g5x_offset` / `g92_offset` / `rotation_xy` / `tool_offset` → 坐标投影。
|
||
- `stat.gcodes` / `stat.mcodes` / `settings` → G-code 信息。
|
||
- canon/preview → 静态程序路径。
|
||
- `motion_line` / `running_line` → 当前行高亮。
|
||
- `joint.pos-fb` → Vismach 模型。
|
||
|
||
静态 preview 和 realtime/live plot 必须分开建模；Web 端不能用 JS 重新解析一份程序来代替 WASM canonical motion。
|
||
|
||
## 4. `xyzac-trt.xml` SWITCHKINS 面板
|
||
|
||
### 4.1 控件定义
|
||
|
||
PyVCP XML 定义：
|
||
|
||
| 控件文本 | HAL pin | 目标 |
|
||
|---|---|---|
|
||
| `IDENTITY` | `pyvcp.type0-button` | 触发 `halui.mdi-command-00` → M429 |
|
||
| `TCP:XYZAC` | `pyvcp.type1-button` | 触发 `halui.mdi-command-01` → M428 |
|
||
| `userk` | `pyvcp.type2-button` | 触发 `halui.mdi-command-02` → M430 |
|
||
| 多标签 | `kinstype.is-0/1/2` | 显示当前 switchkins type |
|
||
| `vismach-clear` | `pyvcp.vismach-clear` | 连接 `vismach.plotclear` |
|
||
|
||
`switchkins_postgui.hal` 将按钮连接到 HALUI MDI command：
|
||
|
||
```text
|
||
pyvcp.type0-button → halui.mdi-command-00
|
||
pyvcp.type1-button → halui.mdi-command-01
|
||
pyvcp.type2-button → halui.mdi-command-02
|
||
```
|
||
|
||
这意味着浏览器端的“TCP:XYZAC”按钮不能直接写 `motion.switchkins-type`，应走同等的受控 command/remap 路径，并等待确认状态。
|
||
|
||
### 4.2 switchkins 状态模型
|
||
|
||
```text
|
||
type 0 / M429 → identity
|
||
type 1 / M428 → xyzac TRT TCP/RTCP
|
||
type 2 / M430 → userk
|
||
```
|
||
|
||
`xyzac-trt-kins.c` 在 `sparm=identityfirst` 下将 type 0 绑定 identity，type 1 绑定 `trtKinematicsSetup + xyzacKinematicsForward/Inverse`，type 2 绑定 userk。配置注释和实现必须同时读取，不能只依据面板标签。
|
||
|
||
## 5. 五轴 RTCP 控制流
|
||
|
||
### 5.1 M428/M429 remap
|
||
|
||
`428remap.ngc` 的关键操作：
|
||
|
||
```text
|
||
验证 motion.switchkins-type HAL pin 存在
|
||
M68 E3 Q1 写 motion.analog-out-03 = 1
|
||
M66 E0 L0 同步等待
|
||
读取 motion.switchkins-type，必须等于 1
|
||
```
|
||
|
||
`429remap.ngc` 相同，但写入 `Q0`。失败时输出 debug STOP 并结束子程序；Web/WASM 需要把这些失败变成稳定的错误码，而不是只显示“按钮没有反应”。
|
||
|
||
### 5.2 典型 helix 数据流
|
||
|
||
`helix_ac.ngc` 的典型顺序：
|
||
|
||
```text
|
||
M429 identity
|
||
G0 / G10 L20 机床坐标定位和设置工作偏置
|
||
M428 XYZAC TRT / TCP
|
||
G0 A... C... 改变刀轴姿态
|
||
G2 ... 在 RTCP 运动学下插补
|
||
M429 切回 identity
|
||
G0 ... 安全返回
|
||
M428 如后续仍需 TCP
|
||
```
|
||
|
||
这里的关键不是“同时有 A/C 数字”，而是同一轨迹块由 XYZAC inverse kinematics 将 TCP pose 转换为五个 joint 命令。姿态变化可能导致 X/Y/Z 补偿变化；因此前端必须同时展示笛卡尔 pose、joint positions、active kinematics mode 和 tool offset。
|
||
|
||
### 5.3 Vismach 数据流
|
||
|
||
```text
|
||
joint.0.pos-fb → table-x → HalTranslate
|
||
joint.1.pos-fb → saddle-y → HalTranslate
|
||
joint.2.pos-fb → spindle-z → HalTranslate
|
||
joint.3.pos-fb → tilt-a → HalRotate(A)
|
||
joint.4.pos-fb → rotate-c → HalRotate(C)
|
||
motion.tooloffset.z → tool-offset → HalTranslate(tool)
|
||
y/z-offset → rotary geometry placement
|
||
```
|
||
|
||
Vismach 只读 HAL input。Web/WASM 的 Three.js adapter 应消费 authoritative `visual.pose`/`joints`/`toolpath`，而不是在 React 中根据 A/C 自行推算补偿。
|
||
|
||
## 6. 按钮互相制约条件
|
||
|
||
下表是 AXIS/LinuxCNC 语义的最小可执行门控。`running` 表示 AUTO 或 MDI 且 `interp_state != INTERP_IDLE`。
|
||
|
||
| 按钮/动作 | 必须满足 | 典型阻塞原因 |
|
||
|---|---|---|
|
||
| E-stop | 始终可用 | transport/session 不可用 |
|
||
| Power ON/OFF | 非 ESTOP；不在禁止转换状态 | `ESTOP_ACTIVE` |
|
||
| Reset | machine ON、非 running、无 active limit | `LIMIT_ACTIVE` / `INTERP_RUNNING` |
|
||
| Manual jog | `STATE_ON`、MANUAL、非 running、未 fault | `MACHINE_OFF` / `MODE_REQUIRED` |
|
||
| Home all | `manual_ok()`；必要时确认重复 homing | `NOT_ON` / `RUNNING` |
|
||
| 单轴 Home | `manual_ok()`；非 identity 时通常必须 joint mode；重复坐标字母禁用单轴 home | `JOINT_MODE_REQUIRED` |
|
||
| MDI | machine ON；队列未满；idle 或当前 MDI | `MDI_QUEUE_FULL` / `INTERP_RUNNING` |
|
||
| Open file | 解释器 idle；AXIS `open_file_guts` 临时切 MANUAL 后恢复原 mode | `INTERP_RUNNING` |
|
||
| Load program | machine ON、idle | `MACHINE_OFF` |
|
||
| Reload | idle 且已有 loaded file | `TASKFILE_MISSING` |
|
||
| Run | machine ON、idle、已有程序 | `TASKFILE_MISSING` / `INTERP_RUNNING` |
|
||
| Run from line | Run 条件 + 有明确 highlight line | `HIGHLIGHT_MISSING` |
|
||
| Step | machine ON 且有程序；进入 AUTO | `TASKFILE_MISSING` |
|
||
| Pause | machine ON 且 interpreter READING/WAITING | `PAUSE_STATE_GATE` |
|
||
| Resume | machine ON 且 interpreter PAUSED | `RESUME_STATE_GATE` |
|
||
| Stop/Abort | machine ON 且 running；abort 可以强制恢复状态 | `STOP_STATE_GATE` |
|
||
| Touch Off | manual_ok、MANUAL、允许的 motion mode | `JOINT_MODE_REQUIRED` |
|
||
| Tool Touch Off | Touch Off 条件 + 有当前工具 | `TOOL_MISSING` |
|
||
| TCP:XYZAC/M428 | remap HAL pin 存在、HAL net 正确、当前程序允许切换 | `MISSING_HAL_PIN` / `WRONG_SWITCHKINS_TYPE` |
|
||
| Identity/M429 | 同上，切换后必须确认 type=0 | `WRONG_SWITCHKINS_TYPE` |
|
||
| Vismach clear | 只清显示 plot，不改变 task/motion | 不应改变机床状态 |
|
||
|
||
### 6.1 重要状态互斥
|
||
|
||
```text
|
||
ESTOP → 禁止所有运动、模式、MDI、RTCP 切换
|
||
OFF → 可以复位/上电，禁止 Run/Jog/Home/MDI
|
||
ON + 未 homed → 允许 Manual/Home，禁止 AUTO/MDI（除非配置 NO_FORCE_HOMING）
|
||
RUNNING → 禁止 Open/Reload/Edit/MDI/Jog/Home；允许 Pause/Stop/状态观察
|
||
PAUSED → 允许 Resume/Stop；禁止 MDI/Jog/重新加载
|
||
RTCP type switch → 应在 interpreter idle、安全位置、无活动轨迹时执行
|
||
```
|
||
|
||
## 7. 当前 Web/WASM 的对应实现
|
||
|
||
### 7.1 已存在的通用契约
|
||
|
||
当前 Web 代码已经提供可复用基础：
|
||
|
||
| 文件 | 作用 |
|
||
|---|---|
|
||
| `web/app/axis-contract.mjs` | `AXIS_COMMANDS`、状态归一化、纯 gate 函数 |
|
||
| `web/app/axis-operation-controller.mjs` | operation id、gate 检查、command trace、错误保留 |
|
||
| `web/react/src/protocol.ts` | `MessageEnvelope`、`SimSnapshotV1`、`PanelSnapshotV1`、`AxisStateView` |
|
||
| `web/react/src/store.ts` | Worker message → authoritative snapshot/projected UI state |
|
||
| `web/react/src/worker-client.ts` | Dedicated Worker transport、seq、session/context、错误处理 |
|
||
| `web/react/src/visual-workflow.ts` | AXIS/GMOCCAPY/Vismach 的 visual source 分类 |
|
||
|
||
现有 `AXIS_COMMANDS` 已覆盖 `PROGRAM_LOAD/RUN/STEP/PAUSE/RESUME/ABORT/RESTART`、`MDI_EXECUTE`、`JOG_START/STOP`、`HOME`、`ESTOP`、`RESET`、override、spindle、coolant、tool 和 probe。
|
||
|
||
### 7.2 `xyzac-trt` 需要的新增协议字段
|
||
|
||
建议在现有 `PanelSnapshotV1` 上 additive 扩展，不破坏 `sim_task.v1`：
|
||
|
||
```json
|
||
{
|
||
"configuration": {
|
||
"case_path": "linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzac-trt.ini",
|
||
"coordinates": ["X", "Y", "Z", "A", "C"],
|
||
"kinematics": "xyzac-trt-kins",
|
||
"topology": "table-tilting-A/table-rotary-C",
|
||
"joint_count": 5,
|
||
"program_prefix": "../../nc_files"
|
||
},
|
||
"kinematics": {
|
||
"family": "switchkins",
|
||
"active_type": 1,
|
||
"active_name": "xyzac-trt",
|
||
"available": [
|
||
{"type": 0, "name": "identity", "command": "M429"},
|
||
{"type": 1, "name": "xyzac-trt", "command": "M428"},
|
||
{"type": 2, "name": "userk", "command": "M430"}
|
||
],
|
||
"transition": "idle_only"
|
||
},
|
||
"motion": {
|
||
"axes": {"x": 0, "y": 0, "z": 10, "a": 0, "c": 0},
|
||
"joints": [0, 0, 10, 0, 0],
|
||
"tool_offset": {"z": 0},
|
||
"rotation_center": {"x": 0, "y": 0, "z": 0},
|
||
"axis_offsets": {"y": 20, "z": 10}
|
||
}
|
||
}
|
||
```
|
||
|
||
字段的 authoritative 来源必须来自 WASM kinematics/motion snapshot 或受控 native oracle；不能由 A/C slider 在浏览器中自行补偿。
|
||
|
||
### 7.3 命令映射建议
|
||
|
||
| Web action | protocol command | xyzac 行为 |
|
||
|---|---|---|
|
||
| `PROGRAM_LOAD` | `PROGRAM_LOAD` | 载入程序、canonical preview、重置 active segment |
|
||
| `PROGRAM_RUN` | `PROGRAM_RUN` | 进入 AUTO，固定 tick 推进 interpreter/TP |
|
||
| `PROGRAM_PAUSE` | `PROGRAM_PAUSE` | 保留当前 segment/kinematics type |
|
||
| `PROGRAM_RESUME` | `PROGRAM_RESUME` | 继续同一 program state |
|
||
| `PROGRAM_ABORT` | `PROGRAM_ABORT` | 停止并返回稳定 STOPPED/IDLE |
|
||
| `MDI_EXECUTE` | `MDI_EXECUTE` | 用于 `M428`/`M429`/`M430`，必须有 idle gate |
|
||
| `KINEMATICS_SELECT` | 建议新增 | payload `{type:0\|1\|2}`，内部走 remap/受控 HAL，不直接写 pin |
|
||
| `JOG_START` | `JOG_START` | 仅允许合法 axis/joint；XYZAC 的 A/C 速度单位独立校验 |
|
||
| `HOME` | `HOME` | 返回每个 joint homed 状态和错误 |
|
||
| `VISMACH_CLEAR` | `VISUAL_CLEAR` | 只清可视化轨迹，不清 task/motion/program |
|
||
|
||
### 7.3.1 当前 Web 实现的五轴缺口
|
||
|
||
现有通用 AXIS contract 已有大量三轴/通用动作，但对本案例仍有明确缺口，不能把“按钮存在”当成已实现：
|
||
|
||
| 缺口 | 当前状态 | 五轴实现要求 |
|
||
|---|---|---|
|
||
| `KINEMATICS_SELECT` | `AXIS_COMMANDS` 尚未定义 | 新增受 gate 的 type 0/1/2 命令，禁止前端直接写 HAL |
|
||
| `POWER` | `axisGate()` 有 `power` 分支，但 `AXIS_COMMANDS` 没有对应 action | 补齐 command map 和 Worker handler，保持 OFF/ESTOP 语义 |
|
||
| `VISUAL_CLEAR` | 原生 PyVCP 有 `vismach-clear`，通用 Web command 尚未固定 | 作为 visual-only command，不能改 program/motion hash |
|
||
| A/C jog | 当前 React 示例轴选择主要是 X/Y/Z | 增加 A/C angular units、limits、jog speed 和 joint/teleop gate |
|
||
| XYZAC pose | `PanelSnapshotV1.visual.pose` 目前是通用 Record | 增加明确 `a/c`、joint vector、kinematics type 和 tool-offset 字段 |
|
||
| rotation centers | 当前通用 snapshot 没有 TRT rotation-point 完整字段 | 将 x/y/z rotation point、y/z offset 纳入 configuration/authoritative |
|
||
| switchkins recovery | 通用 recovery 有 task/program，但没有 active kinematics mode | checkpoint 必须保存 type、remap transition、source line、joint/pose hash |
|
||
|
||
### 7.4 Worker snapshot 到 React
|
||
|
||
```text
|
||
WASM/native runtime
|
||
└── task + interpreter + motion + joints + kinematics + HAL + devices
|
||
│
|
||
▼
|
||
protocol.v1 STATE_SNAPSHOT / COMMAND_RESULT
|
||
│
|
||
▼
|
||
store.ts projection()
|
||
├── axis_state
|
||
├── gates
|
||
├── task/program
|
||
├── motion.axes / motion.joints
|
||
├── authoritative.planner / authoritative.kinematics
|
||
└── visual.pose / visual.toolpath
|
||
│
|
||
▼
|
||
React DRO / controls / Three.js Vismach
|
||
```
|
||
|
||
React 控件的 `disabled` 只是 projection；真正 gate 必须在 Worker/runtime 再检查一次。`AxisOperationController` 已提供 operation id、拒绝原因和 trace 结构，五轴切换应复用此机制。
|
||
|
||
## 8. Web/WASM 不应直接照搬的部分
|
||
|
||
| 原生机制 | Web/WASM 处理 |
|
||
|---|---|
|
||
| Tk widget/菜单 | React button/menu/keyboard command，但保留 source control id 和 tooltip 语义 |
|
||
| LinuxCNC NML | Dedicated Worker protocol envelope + session/seq/operation_id |
|
||
| HAL pin `motion.switchkins-type` | Worker-owned runtime capability；浏览器不能任意写 HAL pin |
|
||
| `loadusr -W xyzac-trt-gui` | Worker/Three.js Vismach adapter；visual-only，不是 authority |
|
||
| `OPEN_FILE` | Worker workspace resolver + exact path/resource closure |
|
||
| `G-code preview` | WASM canonical interpreter/TP segments；不能用 JS preview 冒充 |
|
||
| `linuxcnc.stat()` polling | fixed-tick STATE_SNAPSHOT/EVENT，带 state_hash |
|
||
| M428/M429 remap | WASM remap/interpreter capability，记录切换、错误和首个 divergent tick |
|
||
| POSIX realtime/HAL hardware | SIM-DEVICE 或 REAL-EXCLUDED，不能静默当成 Web 等价 |
|
||
|
||
## 9. 推荐的 Web 端组件拆分
|
||
|
||
```text
|
||
XyzacTrtCaseResolver
|
||
├── exact ini/hal/remap/resource resolver
|
||
└── startup diagnostics
|
||
|
||
XyzacTrtControlStore
|
||
├── axis_state / task / interp / homed / limits
|
||
├── kinematics.active_type
|
||
├── gates and gate reasons
|
||
└── command trace
|
||
|
||
XyzacTrtOperationController
|
||
├── PROGRAM_LOAD/RUN/PAUSE/RESUME/ABORT
|
||
├── MDI M428/M429/M430
|
||
├── JOG/HOME/override
|
||
└── transition checks: idle, no fault, valid capability
|
||
|
||
XyzacTrtPanel
|
||
├── mode/task controls
|
||
├── XYZAC DRO and joint view
|
||
├── TCP/identity/userk segmented control
|
||
├── gate-aware MDI/run/jog/home buttons
|
||
└── alarms and diagnostics
|
||
|
||
XyzacTrtVismach
|
||
├── pose/joints/toolpath from authoritative snapshot
|
||
├── A/C table rotation
|
||
├── tool-offset rendering
|
||
└── canvas/WebGL pixel/interaction checks
|
||
```
|
||
|
||
## 10. 验收和测试矩阵
|
||
|
||
### 正常流程
|
||
|
||
1. 加载 `xyzac_switchkins.ngc`。
|
||
2. 验证 `XYZAC` 五个轴和五个 joints 出现在 snapshot。
|
||
3. 验证 preview segment/source line/hash。
|
||
4. `M429` → active type 0。
|
||
5. `M428` → active type 1，等待确认后再允许 TCP 轨迹。
|
||
6. 运行包含 A/C 变化的 helix；比较 Cartesian pose、joint positions、tool offset。
|
||
7. `M429` 安全返回；验证 no duplicate segment/no stale active segment。
|
||
|
||
### 边界和拒绝
|
||
|
||
| 测试 | 期望 |
|
||
|---|---|
|
||
| ESTOP 时 M428 | blocked，不改变 kinematics type |
|
||
| interpreter running 时 M428 | blocked 或排队策略明确，不能隐式切换 |
|
||
| 缺 `HAL_PIN_VARS=1` | remap 错误码 `M428:Missing...`，保留证据 |
|
||
| 缺 `motion.switchkins-type` net | `WRONG_SWITCHKINS_TYPE`/source diagnostic |
|
||
| A/C 超限 | limit/fault snapshot，禁止继续运动 |
|
||
| tool offset 非有限值 | fail closed，不能送入 kinematics |
|
||
| pause 后 resume | segment、kinematics type、state hash 连续 |
|
||
| abort 后 reload | program/task/preview 清理顺序确定 |
|
||
| Worker restart | checkpoint 恢复 kinematics type、program line、joint/pose hash |
|
||
| Vismach clear | 只清 visual layer，task/program/state_hash 不变 |
|
||
|
||
### 必须保存的证据
|
||
|
||
- context id、case path、INI/HAL/remap source hash。
|
||
- command envelope、operation id、gate result、command result。
|
||
- 每个固定 tick 的 task/interp/motion/kinematics state hash。
|
||
- Cartesian pose、XYZAC joint vector、tool offset、active segment/source line。
|
||
- 首个 divergent tick、错误码、资源缺失分类。
|
||
- native/WASM/Worker 对照结果；不以单一截图替代。
|
||
|
||
## 11. 已知限制
|
||
|
||
- 当前 `xyzac-trt.ini` 是 AXIS + PyVCP + 独立 Vismach 的 LinuxCNC 原生案例；Web/WASM 尚未声明其完整五轴 RTCP parity 已完成。
|
||
- 当前环境使用 POSIX non-realtime；不提供实时硬件周期、延迟和驱动证明。
|
||
- `xyzac-trt-gui` 只可视化 joint feedback/tool offset；它不是 canonical motion authority。
|
||
- 官方 kinematics oracle 缺失时，native/WASM 结果只能作为实现证据，不能伪称官方 golden。
|
||
- `xyzac-trt` 配置中的 `x-rot-point/y-rot-point/z-rot-point` 在示例中固定为 0，且注释说明当前 Vismach GUI 不支持通过 GUI 调整；Web 端必须把它作为配置/能力字段，而不是随意暴露可写 slider。
|
||
|
||
## 12. 后续实现顺序
|
||
|
||
1. 建立 exact-path `xyzac-trt.ini` resolver 和 resource graph。
|
||
2. 在 Worker/WASM 建立 additive `kinematics` snapshot 与 `KINEMATICS_SELECT` command。
|
||
3. 将 M428/M429/M430 的 remap 行为接入固定 tick interpreter，先做拒绝和错误边界。
|
||
4. 将 XYZAC Cartesian/joint/tool-offset canonical snapshot 接到 Three.js Vismach adapter。
|
||
5. 实现 gate matrix：ESTOP/OFF/ON/HOME/IDLE/RUNNING/PAUSED/limit/fault。
|
||
6. 完成 program load/run/pause/resume/abort/restart + RTCP switch recovery 测试。
|
||
7. 运行 native/Worker/browser 三方对照，并记录首个差异 tick。
|
||
8. 只有 source/resource/oracle/recovery/浏览器边界均有证据后，才可提升为 selected-case verified；不能从一个 AXIS 截图直接宣称全 LinuxCNC 五轴 parity。
|