382 lines
32 KiB
HTML
382 lines
32 KiB
HTML
<!doctype html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<title>xyzbc-trt Web 数控仿真系统设计任务书和技术方案</title>
|
||
<style>
|
||
@page { size: A4; margin: 18mm 16mm; }
|
||
body {
|
||
font-family: "Noto Sans CJK SC", "Microsoft YaHei", Arial, sans-serif;
|
||
color: #172033;
|
||
line-height: 1.55;
|
||
font-size: 10.8pt;
|
||
}
|
||
h1 { font-size: 24pt; margin: 0 0 10pt; color: #0f172a; }
|
||
h2 { font-size: 17pt; margin: 22pt 0 8pt; border-bottom: 1.2pt solid #94a3b8; padding-bottom: 4pt; color: #0f172a; }
|
||
h3 { font-size: 13pt; margin: 16pt 0 6pt; color: #1e293b; }
|
||
p { margin: 5pt 0; }
|
||
.cover {
|
||
min-height: 215mm;
|
||
display: block;
|
||
padding-top: 45mm;
|
||
}
|
||
.cover .subtitle { font-size: 15pt; color: #334155; margin-top: 10pt; }
|
||
.meta { margin-top: 35pt; border-collapse: collapse; width: 100%; }
|
||
.meta td { border: 1pt solid #cbd5e1; padding: 8pt; font-size: 11pt; }
|
||
.page-break { page-break-before: always; }
|
||
.note {
|
||
border-left: 4pt solid #2563eb;
|
||
background: #eff6ff;
|
||
padding: 8pt 10pt;
|
||
margin: 8pt 0 10pt;
|
||
}
|
||
.warn {
|
||
border-left: 4pt solid #f97316;
|
||
background: #fff7ed;
|
||
padding: 8pt 10pt;
|
||
margin: 8pt 0 10pt;
|
||
}
|
||
table { border-collapse: collapse; width: 100%; margin: 8pt 0 12pt; }
|
||
th, td { border: 1pt solid #cbd5e1; padding: 6pt 7pt; vertical-align: top; }
|
||
th { background: #e2e8f0; font-weight: 700; }
|
||
code, pre {
|
||
font-family: "DejaVu Sans Mono", Consolas, monospace;
|
||
font-size: 9.2pt;
|
||
}
|
||
pre {
|
||
background: #0f172a;
|
||
color: #e5e7eb;
|
||
padding: 9pt;
|
||
white-space: pre-wrap;
|
||
border-radius: 4pt;
|
||
margin: 8pt 0 12pt;
|
||
}
|
||
.figure { margin: 12pt 0 16pt; text-align: center; page-break-inside: avoid; }
|
||
.figure img { max-width: 100%; height: auto; border: 1pt solid #cbd5e1; }
|
||
.caption { color: #475569; font-size: 9.5pt; margin-top: 5pt; text-align: center; }
|
||
ul { margin-top: 4pt; }
|
||
li { margin: 3pt 0; }
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<section class="cover">
|
||
<h1>xyzbc-trt Web 数控仿真系统<br>设计任务书和技术方案</h1>
|
||
<p class="subtitle">完全对标 LinuxCNC <code>xyzbc-trt</code> 五轴 table rotary/tilting 仿真配置</p>
|
||
<table class="meta">
|
||
<tr><td>原型系统</td><td><code>/home/mes123456/cnc_wams/linuxcnc</code></td></tr>
|
||
<tr><td>启动命令</td><td><code>/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment linuxcnc /home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini</code></td></tr>
|
||
<tr><td>目标产物</td><td>浏览器端 Web 数控仿真界面、五轴机床模型、switchkins 逻辑、路径预览与执行对比 JSON</td></tr>
|
||
<tr><td>文档位置</td><td><code>/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/doc</code></td></tr>
|
||
<tr><td>编制日期</td><td>2026-07-02</td></tr>
|
||
</table>
|
||
</section>
|
||
|
||
<section class="page-break">
|
||
<h2>1. 项目目标</h2>
|
||
<p>本项目建设一个 Web 数控仿真系统，功能和行为完全对标 LinuxCNC 真实运行配置 <code>xyzbc-trt.ini</code>。Web 系统不是展示页，而是首屏即进入数控仿真工作台，提供程序加载、预览、DRO、MDI、PyVCP 等价控件、五轴机床运动显示、switchkins 模式切换、刀具路径采样、执行过程记录和误差对比。</p>
|
||
<p>对标基线以已编译成功并能运行的 <code>/home/mes123456/cnc_wams/linuxcnc</code> 为准，历史旧 LinuxCNC 目录不再作为本方案的运行基线。</p>
|
||
<div class="note">
|
||
<p>核心验收原则：同一份配置、同一份 G-code、同一运动学模式、同一采样周期、同一 JSON 字段，分别采集 LinuxCNC 真实系统和 Web 仿真系统的预览路径与执行路径，逐点比对位置、姿态、运动学模式和 HAL 状态。</p>
|
||
</div>
|
||
|
||
<h2>2. 原型系统运行证据</h2>
|
||
<h3>2.1 当前启动命令</h3>
|
||
<pre>/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment linuxcnc \
|
||
/home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini</pre>
|
||
|
||
<h3>2.2 当前关键进程</h3>
|
||
<table>
|
||
<tr><th>进程</th><th>对标含义</th></tr>
|
||
<tr><td><code>scripts/linuxcnc xyzbc-trt.ini</code></td><td>LinuxCNC 主启动入口，Web 端需实现等价启动会话和配置装载流程。</td></tr>
|
||
<tr><td><code>linuxcncsvr</code></td><td>NML/状态服务，Web 端需提供统一运行状态中心。</td></tr>
|
||
<tr><td><code>rtapi_app load tpmod</code></td><td>运动规划模块，Web 端需实现轨迹规划与采样接口。</td></tr>
|
||
<tr><td><code>milltask</code></td><td>任务解释和程序执行，Web 端需实现程序状态机、运行、暂停、复位、MDI。</td></tr>
|
||
<tr><td><code>halui</code></td><td>HAL UI 指令通道，Web 端需复刻 PyVCP 按钮到 MDI 命令的连接。</td></tr>
|
||
<tr><td><code>hal_manualtoolchange</code></td><td>手动换刀流程，Web 端需提供换刀提示和工具状态。</td></tr>
|
||
<tr><td><code>xyzbc-trt-gui</code></td><td>Vismach 五轴机床模型，Web 端需使用 Three.js 对标机床结构和运动。</td></tr>
|
||
<tr><td><code>axis -ini xyzbc-trt.ini</code></td><td>AXIS 主界面，Web 端需对标界面信息架构和操作入口。</td></tr>
|
||
</table>
|
||
|
||
<h3>2.3 当前界面截图</h3>
|
||
<div class="figure">
|
||
<img src="assets/xyzbc-trt-axis-window.png" alt="xyzbc-trt AXIS window">
|
||
<div class="caption">图 1：通过真实 LinuxCNC 会话抓取的 AXIS 主界面，包含预览、DRO、PyVCP SWITCHKINS 面板、程序区和状态栏。</div>
|
||
</div>
|
||
|
||
<div class="figure">
|
||
<img src="assets/xyzbc-trt-desktop.png" alt="xyzbc-trt desktop screenshot">
|
||
<div class="caption">图 2：桌面级运行截图，用于保留真实执行环境和窗口布局证据。</div>
|
||
</div>
|
||
|
||
<h3>2.4 HAL 状态基线</h3>
|
||
<table>
|
||
<tr><th>HAL 项</th><th>当前值或连接</th><th>Web 对标要求</th></tr>
|
||
<tr><td><code>motion.switchkins-type</code></td><td><code>0</code>，由 <code>:kinstype-select</code> 驱动</td><td>实现 <code>0:IDENTITY</code>、<code>1:XYZBC</code>、<code>2:USERK</code> 三态切换。</td></tr>
|
||
<tr><td><code>kinstype.is-0/1/2</code></td><td><code>TRUE/FALSE/FALSE</code></td><td>驱动 Web PyVCP multilabel 的当前模式显示。</td></tr>
|
||
<tr><td><code>joint.0..4.pos-fb</code></td><td>X/Y/Z/B/C 五轴反馈均为 <code>0</code></td><td>映射到 Web DRO、机床模型关节和路径采样。</td></tr>
|
||
<tr><td><code>motion.tooloffset.z</code></td><td>连接 <code>:tool-offset</code></td><td>影响 TCP 刀尖位置和机床模型刀具长度。</td></tr>
|
||
<tr><td><code>xyzbc-trt-kins.x-offset</code></td><td><code>-20</code></td><td>Web 运动学参数必须使用同值。</td></tr>
|
||
<tr><td><code>xyzbc-trt-kins.z-offset</code></td><td><code>-15</code></td><td>Web 运动学参数必须使用同值。</td></tr>
|
||
<tr><td><code>xyzbc-trt-kins.conventional-directions</code></td><td><code>FALSE</code></td><td>Web 端旋转方向和矩阵约定必须一致。</td></tr>
|
||
</table>
|
||
</section>
|
||
|
||
<section class="page-break">
|
||
<h2>3. 完全对标范围</h2>
|
||
<table>
|
||
<tr><th>LinuxCNC 文件或模块</th><th>真实功能</th><th>Web 对标实现</th></tr>
|
||
<tr><td><code>xyzbc-trt.ini</code></td><td>定义 AXIS、PyVCP、KINS、HAL、TRAJ、TASK、EMCIO、轴和关节参数。</td><td>实现 INI 解析器，生成 Web 会话配置、轴参数、速度限制、文件引用和 UI 初始状态。</td></tr>
|
||
<tr><td><code>xyzbc-trt.xml</code></td><td>定义 SWITCHKINS multilabel、IDENTITY、TCP:XYZBC、userk、vismach-clear 按钮。</td><td>实现 PyVCP 等价面板，按钮通过 Web HAL 总线触发 MDI 命令或清除轨迹。</td></tr>
|
||
<tr><td><code>switchkins_postgui.hal</code></td><td>把 PyVCP 控件接到 <code>halui.mdi-command-00/01/02</code> 和 <code>vismach.plotclear</code>。</td><td>实现 postgui HAL 装配层，保证 UI 控件不直接改状态，而是经 HAL 语义连接。</td></tr>
|
||
<tr><td><code>LIB:basic_sim.tcl</code></td><td>生成仿真 HAL 基础链路。</td><td>在 Web 中建立基础 HAL 信号、仿真 joint、motion、halui、pyvcp、vismach 命名空间。</td></tr>
|
||
<tr><td><code>xyzbc-trt-kins.so</code></td><td>XYZBC table rotary/tilting 运动学和 switchkins。</td><td>实现或移植为 WASM/TypeScript 运动学模块，支持 identity、XYZBC TCP、userk。</td></tr>
|
||
<tr><td><code>xyzbc-trt-gui</code></td><td>Vismach 三维机床模型，随 HAL 引脚运动。</td><td>使用 Three.js 建立桌台、转台、倾斜轴、主轴、刀具、工件和路径轨迹。</td></tr>
|
||
<tr><td><code>xyzbc_switchkins.ngc</code></td><td>默认打开的演示程序，调用 <code>xyzbc_switchkins_sub</code>。</td><td>Web 端默认加载同一程序，预览曲线和执行曲线可导出 JSON。</td></tr>
|
||
<tr><td><code>remap_subs/*.ngc</code></td><td>M428/M429/M430 以及演示子程序。</td><td>支持 remap 调用或预编译宏展开，保证模式切换轨迹一致。</td></tr>
|
||
<tr><td><code>xyzbc-trt.tbl</code></td><td>刀具表。</td><td>Web 端提供刀具表加载、显示、选择、tooloffset 影响。</td></tr>
|
||
<tr><td><code>xyzbc.var</code></td><td>RS274 参数文件。</td><td>Web 端持久化参数，支持会话恢复和对标导出。</td></tr>
|
||
</table>
|
||
|
||
<h2>4. Web 界面设计任务书</h2>
|
||
<h3>4.1 首屏布局</h3>
|
||
<p>Web 应用启动后直接进入数控仿真界面，不设置营销式首页。首屏按 AXIS 的工作流组织：</p>
|
||
<ul>
|
||
<li>顶部：文件、机器、视图、帮助菜单，以及急停、上电、打开文件、运行、暂停、单步、停止、视图方向、清扫轨迹等图标按钮。</li>
|
||
<li>左侧：Manual Control 与 MDI 标签页，包含 Joint 0 到 4 选择、连续/增量点动、Home、Touch Off、Tool Touch Off、主轴控制和倍率滑块。</li>
|
||
<li>中间：Preview/DRO/程序标签页，预览页显示 Three.js 五轴机床、工件、刀具、坐标轴、尺寸标注和刀具路径。</li>
|
||
<li>右侧：SWITCHKINS 面板，显示 <code>0:IDENTITY</code>、<code>1:XYZBC</code>、<code>2:USERK</code>，并提供 <code>IDENTITY</code>、<code>TCP:XYZBC</code>、<code>userk</code>、<code>vismach-clear</code> 按钮。</li>
|
||
<li>底部：G-code 程序区、Active G-Codes、状态栏、错误和日志输出。</li>
|
||
</ul>
|
||
|
||
<h3>4.2 视觉和交互要求</h3>
|
||
<table>
|
||
<tr><th>界面区域</th><th>对标要求</th><th>验收证据</th></tr>
|
||
<tr><td>AXIS 工具栏</td><td>保留关键数控操作入口，按钮使用明确图标和 tooltip。</td><td>截图比对，操作事件 JSON。</td></tr>
|
||
<tr><td>DRO</td><td>显示 X/Y/Z/B/C、joint 或 world 坐标、实际/命令位置。</td><td><code>uiState.dro</code> 与 LinuxCNC status 对比。</td></tr>
|
||
<tr><td>PyVCP</td><td>按钮和 multilabel 文案、状态、HAL 连线语义一致。</td><td><code>halPins.kinstype</code> 和 <code>uiState.pyvcp</code>。</td></tr>
|
||
<tr><td>Preview</td><td>显示默认程序的圆形/螺旋路径、刀尖、刀轴、XYZBC 坐标。</td><td><code>previewPath.samples</code> 和截图。</td></tr>
|
||
<tr><td>Vismach 等价模型</td><td>五轴结构、B/C 旋转、X/Y/Z 平移、tooloffset、x/z offset 生效。</td><td>模型姿态 JSON 和截图。</td></tr>
|
||
</table>
|
||
|
||
<div class="figure">
|
||
<img src="assets/xyzbc-trt-web-architecture.png" alt="web architecture">
|
||
<div class="caption">图 3：LinuxCNC 原型系统与 Web 仿真系统的模块级对标关系。</div>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="page-break">
|
||
<h2>5. 技术方案</h2>
|
||
<h3>5.1 总体架构</h3>
|
||
<table>
|
||
<tr><th>层级</th><th>模块</th><th>职责</th></tr>
|
||
<tr><td>文件层</td><td>OPFS/IndexedDB 工作区</td><td>保存 <code>ini/xml/hal/ngc/tbl/var/json</code>，支持导入 LinuxCNC 原始目录。</td></tr>
|
||
<tr><td>解析层</td><td>INI/XML/HAL/NGC/TBL/VAR parser</td><td>结构化解析配置、控件、信号、程序和参数，禁止手工硬编码配置结果。</td></tr>
|
||
<tr><td>运行层</td><td>Task/Interp/Motion/HAL runtime</td><td>复刻 LinuxCNC 任务状态机、G-code 解释、运动规划、HAL pin/net。</td></tr>
|
||
<tr><td>运动学层</td><td>xyzbc-trt-kins</td><td>实现 identity、XYZBC TCP、userk，输出关节、世界坐标、刀尖和刀轴。</td></tr>
|
||
<tr><td>界面层</td><td>React/Vue/Svelte 或原生组件</td><td>对标 AXIS、PyVCP、DRO、MDI、程序窗口、状态栏。</td></tr>
|
||
<tr><td>三维层</td><td>Three.js</td><td>五轴机床、工件、刀具、路径、坐标系、清轨迹和相机视图。</td></tr>
|
||
<tr><td>证据层</td><td>Evidence JSON + Compare report</td><td>采集真实系统和 Web 系统，按同周期逐点比对。</td></tr>
|
||
</table>
|
||
|
||
<h3>5.2 switchkins 逻辑</h3>
|
||
<p>Web 端必须复刻原型中的 switchkins 控制链路：PyVCP 按钮触发 <code>halui.mdi-command-00/01/02</code>，MDI 执行 <code>M429/M428/M430</code>，remap 子程序改变 <code>motion.analog-out-03</code>，再驱动 <code>motion.switchkins-type</code>。UI 当前模式由 <code>kinstype.is-0/1/2</code> 反向驱动，而不是由按钮直接写 UI 标签。</p>
|
||
<table>
|
||
<tr><th>按钮</th><th>HAL 目标</th><th>MDI 命令</th><th>目标模式</th></tr>
|
||
<tr><td><code>IDENTITY</code></td><td><code>halui.mdi-command-00</code></td><td><code>M429</code></td><td><code>0:IDENTITY</code></td></tr>
|
||
<tr><td><code>TCP:XYZBC</code></td><td><code>halui.mdi-command-01</code></td><td><code>M428</code></td><td><code>1:XYZBC</code></td></tr>
|
||
<tr><td><code>userk</code></td><td><code>halui.mdi-command-02</code></td><td><code>M430</code></td><td><code>2:USERK</code></td></tr>
|
||
<tr><td><code>vismach-clear</code></td><td><code>vismach.plotclear</code></td><td>无</td><td>清除三维路径显示。</td></tr>
|
||
</table>
|
||
|
||
<h3>5.3 五轴运动学和模型</h3>
|
||
<p>Web 端机床模型采用 XYZBC table rotary/tilting 结构。X 对应 table-x，Y 对应 saddle-y，Z 对应 spindle-z，B 对应 tilt-b，C 对应 rotate-c。运动学参数使用原型系统当前 HAL 值：<code>x-offset=-20</code>、<code>z-offset=-15</code>、旋转点均为 <code>0</code>、<code>conventional-directions=false</code>。刀具长度来自 <code>motion.tooloffset.z</code>。</p>
|
||
<p>三维模型不只显示程序预览曲线，还必须在执行时按采样点刷新桌台、转台、主轴和刀具姿态。执行暂停、复位、清轨迹、模式切换后，模型状态和 JSON 状态必须同步。</p>
|
||
|
||
<h3>5.4 路径采样和 JSON 比对</h3>
|
||
<div class="warn">
|
||
<p>曲线采样周期固定为 <code>samplePeriodMs = 20</code>，即 50 Hz。LinuxCNC 真实系统和 Web 仿真系统必须使用相同采样周期、相同 sampleIndex、相同时间基准和相同坐标字段，禁止一端 10 ms、另一端 20 ms 或使用不同插补点。</p>
|
||
</div>
|
||
<div class="figure">
|
||
<img src="assets/xyzbc-trt-json-compare-flow.png" alt="json compare flow">
|
||
<div class="caption">图 4：刀具预览路径和执行路径 JSON 的同周期采样与逐点比对流程。</div>
|
||
</div>
|
||
|
||
<h3>5.5 Evidence JSON 字段规范</h3>
|
||
<pre>{
|
||
"schema": "xyzbc-trt-evidence/v1",
|
||
"source": "linuxcnc-native | web-sim",
|
||
"samplePeriodMs": 20,
|
||
"linuxcncRoot": "/home/mes123456/cnc_wams/linuxcnc",
|
||
"ini": "configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini",
|
||
"program": "./demos/xyzbc_switchkins.ngc",
|
||
"runtime": {
|
||
"taskState": 1,
|
||
"interpState": 1,
|
||
"axisMask": 55,
|
||
"kinstype": 0
|
||
},
|
||
"halPins": {
|
||
"motion.switchkins-type": 0,
|
||
"xyzbc-trt-kins.x-offset": -20,
|
||
"xyzbc-trt-kins.z-offset": -15,
|
||
"xyzbc-trt-kins.conventional-directions": false
|
||
},
|
||
"previewPath": {
|
||
"coordinateSystem": "XYZBC",
|
||
"samples": [
|
||
{
|
||
"sampleIndex": 0,
|
||
"timeMs": 0,
|
||
"line": 1,
|
||
"joint": {"x": 0, "y": 0, "z": 0, "b": 0, "c": 0},
|
||
"world": {"x": 0, "y": 0, "z": 0, "b": 0, "c": 0},
|
||
"toolTip": {"x": 0, "y": 0, "z": 0},
|
||
"toolAxis": {"i": 0, "j": 0, "k": 1},
|
||
"kinstype": 0
|
||
}
|
||
]
|
||
},
|
||
"executionPath": {
|
||
"samples": []
|
||
},
|
||
"screenshots": []
|
||
}</pre>
|
||
|
||
<h3>5.6 对比报告字段</h3>
|
||
<table>
|
||
<tr><th>字段</th><th>说明</th></tr>
|
||
<tr><td><code>sampleCount.native/web</code></td><td>真实系统和 Web 系统采样点数量。</td></tr>
|
||
<tr><td><code>maxPositionError</code></td><td>X/Y/Z/B/C 最大逐点误差。</td></tr>
|
||
<tr><td><code>rmsPositionError</code></td><td>路径整体均方根误差。</td></tr>
|
||
<tr><td><code>maxToolTipError</code></td><td>TCP 刀尖位置最大误差。</td></tr>
|
||
<tr><td><code>maxToolAxisErrorDeg</code></td><td>刀轴方向最大角度误差。</td></tr>
|
||
<tr><td><code>firstMismatch</code></td><td>首个超差点的 sampleIndex、line、timeMs、native/web 值。</td></tr>
|
||
<tr><td><code>uiEquivalence</code></td><td>AXIS/PyVCP/DRO/状态栏截图和 DOM 状态对比。</td></tr>
|
||
<tr><td><code>pass</code></td><td>是否通过设定阈值。</td></tr>
|
||
</table>
|
||
</section>
|
||
|
||
<section class="page-break">
|
||
<h2>6. 开发任务分解</h2>
|
||
<table>
|
||
<tr><th>阶段</th><th>任务</th><th>交付物</th><th>验收方式</th></tr>
|
||
<tr><td>阶段 1</td><td>导入并解析 <code>xyzbc-trt.ini</code>、XML、HAL、TBL、VAR、NGC 文件。</td><td>结构化配置 JSON、文件依赖图。</td><td>与 <code>xyzbc-trt-runtime-files.md</code> 逐项核对。</td></tr>
|
||
<tr><td>阶段 2</td><td>搭建 AXIS 等价 Web UI 和 PyVCP 面板。</td><td>首屏数控工作台。</td><td>与真实 AXIS 截图逐区比对。</td></tr>
|
||
<tr><td>阶段 3</td><td>实现 HAL 总线、halui、switchkins 状态机和 remap 命令链路。</td><td>HAL 状态面板、MDI 命令记录。</td><td>按钮触发 M429/M428/M430 后状态一致。</td></tr>
|
||
<tr><td>阶段 4</td><td>实现 XYZBC 运动学和 Three.js Vismach 等价模型。</td><td>五轴机床模型、刀具和工件。</td><td>X/Y/Z/B/C 点动与 HAL pin 一致。</td></tr>
|
||
<tr><td>阶段 5</td><td>实现 G-code 预览路径、执行路径、暂停/复位/单步。</td><td>预览轨迹、执行轨迹、状态机。</td><td>默认程序 <code>xyzbc_switchkins.ngc</code> 可回放。</td></tr>
|
||
<tr><td>阶段 6</td><td>实现 native 和 web evidence JSON，固定 20 ms 采样周期。</td><td><code>native-evidence.json</code>、<code>web-evidence.json</code>。</td><td>字段、单位、sampleIndex 对齐。</td></tr>
|
||
<tr><td>阶段 7</td><td>实现 compare-report 自动生成。</td><td><code>compare-report.json</code>、HTML 报告。</td><td>误差统计和首个差异点可追溯。</td></tr>
|
||
</table>
|
||
|
||
<h2>7. 验收标准</h2>
|
||
<table>
|
||
<tr><th>类别</th><th>必须通过的标准</th></tr>
|
||
<tr><td>路径标准</td><td>所有文档、配置和运行基线均指向 <code>/home/mes123456/cnc_wams/linuxcnc</code>。</td></tr>
|
||
<tr><td>界面标准</td><td>Web 首屏包含 AXIS 主要工作区、PyVCP SWITCHKINS 面板、预览区、DRO、程序区和状态栏。</td></tr>
|
||
<tr><td>功能标准</td><td>默认加载 <code>xyzbc_switchkins.ngc</code>，支持 MDI、模式切换、清轨迹、点动、倍率、刀具和参数。</td></tr>
|
||
<tr><td>运动学标准</td><td>identity、XYZBC TCP、userk 模式状态和轨迹计算与真实系统一致。</td></tr>
|
||
<tr><td>JSON 标准</td><td>预览路径和执行路径同时导出，采样周期统一为 20 ms，字段一致。</td></tr>
|
||
<tr><td>比对标准</td><td>能输出最大误差、RMS 误差、首个差异点、截图和通过/失败结论。</td></tr>
|
||
<tr><td>证据标准</td><td>每次验收保存 LinuxCNC 原始截图、Web 截图、native JSON、web JSON、compare report。</td></tr>
|
||
</table>
|
||
|
||
<h2>8. 风险和控制措施</h2>
|
||
<table>
|
||
<tr><th>风险</th><th>影响</th><th>控制措施</th></tr>
|
||
<tr><td>LinuxCNC 内部解释器和 Web 解释器细节不一致</td><td>路径点或模式切换时序不同。</td><td>优先移植或复用 LinuxCNC 解析/运动学逻辑，保留 native evidence 作为回归基准。</td></tr>
|
||
<tr><td>采样周期不一致</td><td>曲线无法逐点比较。</td><td>强制配置 <code>samplePeriodMs=20</code>，JSON schema 校验不允许缺省。</td></tr>
|
||
<tr><td>Three.js 模型和 Vismach 结构偏差</td><td>视觉对标通过但运动不一致。</td><td>每个关节都绑定 HAL pin，模型矩阵由运动学输出驱动。</td></tr>
|
||
<tr><td>UI 直接改状态绕过 HAL</td><td>无法对标真实控制链路。</td><td>PyVCP 控件只发 HAL/MDI 事件，状态由 HAL pin 回读。</td></tr>
|
||
<tr><td>路径或旧目录混入</td><td>证据不可复现。</td><td>文档和脚本统一扫描旧路径，禁止使用历史旧 LinuxCNC 目录。</td></tr>
|
||
</table>
|
||
|
||
<h2>9. 附录：对标文件清单</h2>
|
||
<table>
|
||
<tr><th>文件</th><th>用途</th></tr>
|
||
<tr><td><code>/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan/doc/xyzbc-trt-runtime-files.md</code></td><td>当前运行配置文件说明和路径基线。</td></tr>
|
||
<tr><td><code>/home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini</code></td><td>主 INI 配置。</td></tr>
|
||
<tr><td><code>xyzbc-trt.xml</code></td><td>PyVCP SWITCHKINS 面板。</td></tr>
|
||
<tr><td><code>switchkins_postgui.hal</code></td><td>PyVCP 与 HALUI、Vismach 清轨迹连接。</td></tr>
|
||
<tr><td><code>demos/xyzbc_switchkins.ngc</code></td><td>默认加载的演示程序。</td></tr>
|
||
<tr><td><code>remap_subs/428remap.ngc</code>、<code>429remap.ngc</code>、<code>430remap.ngc</code></td><td>switchkins 模式切换 remap。</td></tr>
|
||
<tr><td><code>xyzbc-trt.tbl</code></td><td>刀具表。</td></tr>
|
||
<tr><td><code>xyzbc.var</code></td><td>参数文件。</td></tr>
|
||
<tr><td><code>bin/xyzbc-trt-gui</code></td><td>Vismach 原型模型入口。</td></tr>
|
||
<tr><td><code>rtlib/xyzbc-trt-kins.so</code></td><td>真实五轴运动学模块。</td></tr>
|
||
</table>
|
||
</section>
|
||
|
||
<section class="page-break">
|
||
<h2>10. xyzbc-trt 程序逻辑全量分析</h2>
|
||
<p>下面按“文件装载 - 运动学 - HAL - 界面 - 执行 - 证据”的顺序，把 <code>xyzbc-trt</code> 的实际逻辑拆开说明。这里不是抽象架构，而是与当前源码、HAL pin 和界面行为一一对应的执行逻辑。</p>
|
||
<h3>10.1 启动入口逻辑</h3>
|
||
<table>
|
||
<tr><th>步骤</th><th>逻辑</th><th>结果</th></tr>
|
||
<tr><td>1</td><td><code>rip-environment</code> 先建立 run-in-place 环境，确保本地 <code>bin/</code>、<code>lib/</code>、<code>rtlib/</code>、<code>bin/python</code> 可被当前会话找到。</td><td>执行路径完全指向 <code>/home/mes123456/cnc_wams/linuxcnc</code>。</td></tr>
|
||
<tr><td>2</td><td><code>linuxcnc xyzbc-trt.ini</code> 读取主 INI，按段装载 DISPLAY、RS274NGC、KINS、HAL、TRAJ、TASK、EMCIO。</td><td>界面、运动学和程序执行进入同一会话。</td></tr>
|
||
<tr><td>3</td><td>AXIS、PyVCP、Vismach、halui、milltask、linuxcncsvr、rtapi_app 同时被拉起。</td><td>形成“界面 + 任务 + 运动 + 证据”闭环。</td></tr>
|
||
</table>
|
||
<p>这个启动链路的关键点是：界面不是单独运行的，而是被 INI 文件和 HAL 图驱动。Web 端要完全对标，就不能把预览、模式切换、DRO、刀具、执行按钮做成彼此割裂的前端组件，而要让它们共享同一个运行态和信号总线。</p>
|
||
<h3>10.2 配置装载逻辑</h3>
|
||
<table>
|
||
<tr><th>文件</th><th>逻辑作用</th><th>Web 对标要点</th></tr>
|
||
<tr><td><code>xyzbc-trt.ini</code></td><td>定义机器类型、显示方式、五轴坐标、最大速度、轴/关节限制、默认程序、运动学模块和 HAL 连线。</td><td>必须解析成结构化会话配置，不能只读出少量文本字段。</td></tr>
|
||
<tr><td><code>xyzbc-trt.xml</code></td><td>定义 SWITCHKINS 面板和按钮文案。</td><td>按钮状态要由 HAL 输出决定，multilabel 要能随 kinstype 更新。</td></tr>
|
||
<tr><td><code>switchkins_postgui.hal</code></td><td>把按钮接到 MDI 命令，把清轨迹接到 <code>vismach.plotclear</code>。</td><td>Web 端的按钮必须走同样的“事件 - HAL - MDI - 状态”链路。</td></tr>
|
||
<tr><td><code>xyzbc_switchkins.ngc</code></td><td>默认加载的程序是演示切换程序，既包含路径，也包含模式切换场景。</td><td>Web 必须默认回放同一程序并记录同一套证据字段。</td></tr>
|
||
</table>
|
||
<h3>10.3 switchkins 运动学逻辑</h3>
|
||
<p><code>xyzbc-trt-kins</code> 通过 <code>switchkinsSetup()</code> 绑定三个运动学分支：</p>
|
||
<ul>
|
||
<li><code>type0</code>：在当前配置里被重定义为 <code>identity</code>，用于启动后的关节直接操控。</li>
|
||
<li><code>type1</code>：<code>xyzbc-trt-kins</code> 本体，执行 XYZBC table rotary/tilting 的 TCP 运动学。</li>
|
||
<li><code>type2</code>：用户自定义运动学 <code>userk</code>。</li>
|
||
</ul>
|
||
<p>源码里明确设置了 <code>kinsname = "xyzbc-trt-kins"</code>、<code>halprefix = "xyzbc-trt-kins"</code>、<code>required_coordinates = "xyzbc"</code>、<code>allow_duplicates = 1</code>，这意味着它既是一个五轴模块，也是一个允许坐标字母重复映射的 switchkins 模块。<code>identityfirst</code> 参数把启动默认值切换成 identity，而不是让机床类型本体成为 type0，这正是 sim 配置的关键差异。</p>
|
||
<div class="figure">
|
||
<img src="assets/xyzbc-trt-logic-map.png" alt="xyzbc-trt logic map">
|
||
<div class="caption">图 5：`xyzbc-trt` 程序逻辑总图，展示从文件装载到证据采样的完整执行链。</div>
|
||
</div>
|
||
<p>switchkins 内部的逻辑顺序很重要：先由 <code>rtapi_app_main()</code> 创建 HAL 组件和输出 pin，再调用 <code>kinematicsSwitch(0)</code> 设定初始模式，然后把三个 setup 函数分别执行一遍，最后 <code>hal_ready()</code>。这意味着 Web 端在启动时也必须先完成状态总线和模式初始化，再挂载界面和三维模型，不能反过来。</p>
|
||
<h3>10.4 正逆运动学逻辑</h3>
|
||
<table>
|
||
<tr><th>函数</th><th>逻辑</th><th>对标意义</th></tr>
|
||
<tr><td><code>xyzbcKinematicsForward()</code></td><td>根据 X/Y/Z/B/C 和 offset、tooloffset、旋转点、方向约定计算 TCP 世界坐标与姿态。</td><td>Web 端预览路径和三维模型必须采用同一套正解公式。</td></tr>
|
||
<tr><td><code>xyzbcKinematicsInverse()</code></td><td>根据目标 TCP 位姿反推关节角和关节位移，再写回 mapped joints。</td><td>MDI、点动、程序执行时的运动控制必须能从目标位姿反推关节。</td></tr>
|
||
<tr><td><code>conventional-directions</code></td><td>默认关闭时，旋转轴方向与 conventional 约定相反。</td><td>Web 模型如果方向画反，视觉上会“像”，但运动学会错，必须严格对齐。</td></tr>
|
||
</table>
|
||
<p>在当前配置里，B/C 轴是主运动学轴，A/U/V/W 只是可选字母。前向解使用主关节 <code>JX/JY/JZ/JB/JC</code> 计算 TCP 位姿；逆解再根据目标位姿回算这些主关节。这个路径对 Web 端非常关键，因为预览路径不能只画“刀尖折线”，还要把每个采样点对应的关节姿态也算出来，否则无法和真实系统逐点比对。</p>
|
||
<h3>10.5 HAL 和状态逻辑</h3>
|
||
<table>
|
||
<tr><th>HAL 语义</th><th>逻辑</th><th>Web 对标实现</th></tr>
|
||
<tr><td><code>motion.switchkins-type</code></td><td>当前运动学类型输入，浮点值被截断为整数 0/1/2。</td><td>前端 switchkins 状态必须是整数型并保持和任务状态一致。</td></tr>
|
||
<tr><td><code>kinstype.is-0/1/2</code></td><td>当前模式输出，供 GUI、指示灯、程序逻辑读取。</td><td>Web 端要提供同样的可读状态给 PyVCP 等价面板和检测逻辑。</td></tr>
|
||
<tr><td><code>motion.analog-out-03</code></td><td>通过 M68/MDI 等方式写入，间接控制 kinstype。</td><td>Web 端模式切换必须保留“间接驱动”语义，不可直接写最终状态。</td></tr>
|
||
<tr><td><code>halui.mdi-command-00/01/02</code></td><td>PyVCP 按钮发出的 MDI 入口。</td><td>按钮点击后必须先变成命令，再进入状态机。</td></tr>
|
||
</table>
|
||
<p><code>switchkins.c</code> 的实现说明了一个很重要的行为：模式切换后先清除 <code>use_lastpose</code>，再根据当前模式把对应的 <code>kinstype.is.N</code> 置位。也就是说，Web 仿真不能把“当前模式”当作普通表单状态，它必须是一次完整状态机切换，切换后还要在 UI 上立即反映。</p>
|
||
<h3>10.6 UI 与三维模型逻辑</h3>
|
||
<p><code>axis.py</code> 的行为说明 AXIS 窗口里存在“轴模式”和“关节模式”的切换；当配置处于非 trivkins 或特殊 kinstype 时，按钮和焦点会根据当前运动模式自动切换到关节/轴对应控件。Web 端要对标的不只是布局，还有这个控件激活规则。</p>
|
||
<p><code>xyzbc-trt-gui.py</code> 则把 Vismach 模型拆成可响应的 HAL 变换链：<code>tool-offset</code> 作用于刀具，<code>spindle-z</code> 作用于主轴头，<code>tilt-b</code> 作用于倾斜轴，<code>rotate-c</code> 作用于回转台，<code>table-x</code> 和 <code>saddle-y</code> 则驱动横向与纵向运动。这个顺序决定了几何层级关系，所以 Web 端模型必须按同样层级搭建，而不是把每个零件独立摆放。</p>
|
||
<h3>10.7 程序执行与同步逻辑</h3>
|
||
<table>
|
||
<tr><th>阶段</th><th>逻辑</th><th>结果</th></tr>
|
||
<tr><td>预览</td><td>读取 <code>xyzbc_switchkins.ngc</code>，在预览区生成 G-code 轨迹和位置采样。</td><td>得到 previewPath JSON。</td></tr>
|
||
<tr><td>切换</td><td>通过 M428/M429/M430 或等价按钮改变 switchkins 模式，并执行同步命令。</td><td>运动学和解释器状态对齐。</td></tr>
|
||
<tr><td>执行</td><td>根据当前模式执行程序，同时刷新关节反馈和 TCP 位姿。</td><td>得到 executionPath JSON。</td></tr>
|
||
<tr><td>比对</td><td>用固定 20 ms 采样周期对比预览和执行曲线。</td><td>输出 compare-report.json。</td></tr>
|
||
</table>
|
||
<p>同步逻辑是这个程序最容易被误解的地方：切换模式不是单独改一个 pin 就结束了，必须让解释器和 motion 同步，否则 G-code 看到的坐标语义和 motion 看到的坐标语义会不同。这个要求在文档中已经被固化为“预览路径和执行路径统一采样周期，并在切换时强制同步”。</p>
|
||
<h3>10.8 异常和约束逻辑</h3>
|
||
<ul>
|
||
<li>如果 <code>motion.switchkins-type</code> 没有连接，只有 type0 默认运动学可用，这属于兼容旧配置的行为。</li>
|
||
<li>如果切换到身份不匹配的运动学类型，程序逻辑必须在 G-code 中先检查 <code>kinstype.is.N</code> 或等价输入，再决定是否继续。</li>
|
||
<li>如果当前系统的坐标偏置、刀补、外部偏置在切换后不一致，必须先清理或重置偏置，再切换模式。</li>
|
||
<li>如果 Web 端和 LinuxCNC 真实系统的采样周期不一致，则即使图形看起来接近，也不能通过对标验收。</li>
|
||
</ul>
|
||
<p>总的来说，<code>xyzbc-trt</code> 的逻辑不是“一个五轴模型 + 一个预览窗口”，而是“配置驱动的状态机 + 可切换运动学 + HAL 事件 + 三维可视化 + 路径证据”的组合。Web 端要做到完全对标，必须把这五件事统一成一条链。</p>
|
||
</section>
|
||
</body>
|
||
</html>
|