781 lines
26 KiB
Markdown
781 lines
26 KiB
Markdown
# 01-项目功能内容
|
||
|
||
版本：0.5
|
||
日期：2026-06-27
|
||
对标文档：
|
||
|
||
1. `/home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md`
|
||
2. `/home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md`
|
||
3. `/home/meswork/kdl_work/work/doc/通用机器人离线编程虚拟控制器技术方案.md`
|
||
4. `/home/meswork/kdl_work/work/doc/通用机器人项目主要实施步骤.md`
|
||
5. `/home/meswork/kdl_work/work/doc/通用机器人项目功能与数据流程图.md`
|
||
6. `/home/meswork/kdl_work/work/doc/通用机器人项目功能与数据流程图-png/flow-01.mmd` 到 `flow-05.mmd`
|
||
7. `/home/meswork/kdl_work/work/doc/通用机器人项目功能与数据流程图-png/flow-01.png` 到 `flow-05.png`
|
||
|
||
## 1. 项目定位
|
||
|
||
本目录用于把 `/home/meswork/kdl_work/work` 下的通用机器人离线编程方案、流程图源码和流程图渲染资产落成实施计划。实施目标是形成一套互相闭合的语言层、运动计算层、虚拟控制器、工作台和工程交付链路：
|
||
|
||
```text
|
||
Project Resources / OPFS Workspace
|
||
-> GRL Source / OLP Object Model / Brand Source
|
||
-> Lexer / Parser / Brand Importer
|
||
-> AST / Brand AST
|
||
-> Symbol Table / Semantic Analyzer
|
||
-> Executable IR / Source Map
|
||
-> Virtual Controller Runtime
|
||
-> Motion Queue / IO Service / Alarm Queue / Trace Buffer
|
||
-> MotionSegmentRequest / PathPlanRequest
|
||
-> KdlWorkerClient / KDL WASM
|
||
-> TrajectoryResult / PathValidationResult / Diagnostics
|
||
-> Post Processor / Reports / Customer Delivery Package
|
||
```
|
||
|
||
首版 MVP 范围包括单机器人 6 轴 URDF、GRL 语言闭环、KDL WASM 运动计算、虚拟控制器运行调试、DI/DO 虚拟 IO、OPFS 项目保存、三品牌后处理原型、至少一种品牌程序导入原型、可达性/节拍报告和客户交付包导出原型。完整碰撞检测、多机器人协调、外部轴同步、完整 CAD kernel、真实控制器通信和品牌控制器 look-ahead 完全复刻为后续扩展，但必须在任务矩阵中有明确归属。
|
||
|
||
## 1.1 `/work` 全功能覆盖索引
|
||
|
||
| 来源资产 | 必须覆盖的功能面 | working 对应任务 |
|
||
| --- | --- | --- |
|
||
| `KDL_WASM计算接口设计.md` | Worker API、URDF、KDL Chain、FK/IK/Jacobian、轨迹、Path、诊断、C ABI、性能 | `KW-001` 到 `KW-013` |
|
||
| `通用机器人编程语法规范.md` | GRL 词法、语法、AST、语义、IR、Path、Operation、IO、流程、后处理、生成器 | `KW-100` 到 `KW-112` |
|
||
| `通用机器人离线编程虚拟控制器技术方案.md` | 商业 OLP、对象模型、虚拟控制器、IO/Wait、OPFS、UI、报告、品牌导入、虚拟调试、几何、碰撞、校准、Sim-to-Real、多机器人、外部轴、真实控制器校验 | `KW-200` 到 `KW-210` |
|
||
| `通用机器人项目主要实施步骤.md` | 阶段 1 到 10 的实施顺序、输入输出、验收重点和常用命令 | `KW-001` 到 `KW-211` |
|
||
| `通用机器人项目功能与数据流程图.md` | 总体功能流、GRL 编译执行流、KDL 计算流、数据传递流、诊断传递流 | `KW-110`、`KW-200` 到 `KW-211` |
|
||
| `flow-01.mmd/png` | 项目资源到 GRL/KDL/后处理的总体功能流程 | `KW-211` |
|
||
| `flow-02.mmd/png` | GRL 编译、IR 执行、KDL 请求和后处理流程 | `KW-110`、`KW-202`、`KW-211` |
|
||
| `flow-03.mmd/png` | KDL RobotHandle、MOVEJ/MOVEL/MOVEC/PATH 计算流程 | `KW-003` 到 `KW-011`、`KW-211` |
|
||
| `flow-04.mmd/png` | Project、Compile、KDL、Runtime、Output 数据流 | `KW-200` 到 `KW-206`、`KW-211` |
|
||
| `flow-05.mmd/png` | Parser、Semantic、KDL、Post Processor 诊断 severity/sourceMap 流程 | `KW-110`、`KW-206`、`KW-211` |
|
||
|
||
## 2. GRL 语言功能范围
|
||
|
||
### 2.1 设计目标
|
||
|
||
GRL 是用于离线编程和虚拟调试的通用机器人程序语言，必须满足：
|
||
|
||
1. 支持目标点、路径、工艺、IO、等待、流程控制、报警、仿真执行、报告和后处理。
|
||
2. 可由规划点、CAD 曲线、工艺模板或 AI 规划器自动生成程序。
|
||
3. 可转换为 ABB RAPID、FANUC LS/TP 风格文本、KUKA KRL。
|
||
4. 可反向导入品牌程序，恢复为统一 IR、GRL 和 OLP 对象模型。
|
||
5. 程序文本稳定、可读、可 diff。
|
||
6. 编译后生成统一可执行 IR，虚拟控制器不依赖品牌控制器细节。
|
||
|
||
### 2.2 语法必须覆盖
|
||
|
||
1. 文件工程结构：
|
||
- `project.json`
|
||
- `robots/*.urdf`
|
||
- `programs/*.grl`
|
||
- `targets/*.json`
|
||
- `paths/*.json`
|
||
- `operations/*.json`
|
||
- `io/io_map.json`
|
||
- `post/{abb,fanuc,kuka}.profile.json`
|
||
- `generated/{abb,fanuc,kuka}/`
|
||
- `reports/*.json`
|
||
|
||
2. 词法：
|
||
- UTF-8。
|
||
- 小写关键字。
|
||
- 大小写敏感标识符。
|
||
- `snake_case` 推荐。
|
||
- 单行和多行注释。
|
||
- 带单位数值。
|
||
- 保留关键字表。
|
||
|
||
3. 顶层结构：
|
||
- `language grl 0.1`
|
||
- `module`
|
||
- `import`
|
||
- `persistent/const/var`
|
||
- `target`
|
||
- `path`
|
||
- `operation`
|
||
- `proc`
|
||
- `func`
|
||
- `trap`
|
||
- `task`
|
||
- `post_hint`
|
||
|
||
4. 类型系统：
|
||
- `bool/int/real/string/time/length/angle/percent`
|
||
- `pose/joint_array/pose_target/joint_target/tool/frame/speed/zone/load/robot_config/ext_axis/path/operation`
|
||
|
||
5. 数据声明：
|
||
- `tool`
|
||
- `frame`
|
||
- `joint_target`
|
||
- `pose_target`
|
||
- `pose`
|
||
- `poseq`
|
||
- `robot_config`
|
||
- 偏移表达式 `offset`、`offset_in`
|
||
|
||
6. 速度和过渡：
|
||
- `joint(percent)`
|
||
- `joint(angle/s)`
|
||
- `linear(length/s)`
|
||
- `angular(angle/s)`
|
||
- 可选 `acc`
|
||
- `fine`
|
||
- `z(distance)`
|
||
- `cnt(percent)`
|
||
- `continuous`
|
||
|
||
7. 运动指令：
|
||
- `movej TargetExpr [speed Speed] [zone Zone] [tool Tool] [frame Frame]`
|
||
- `movel TargetExpr [speed Speed] [zone Zone] [tool Tool] [frame Frame]`
|
||
- `movec via ViaTargetExpr target EndTargetExpr [speed Speed] [zone Zone] [tool Tool] [frame Frame]`
|
||
- `set_tool`
|
||
- `set_frame`
|
||
- `set_speed`
|
||
- `set_zone`
|
||
|
||
8. Path：
|
||
- `path`
|
||
- `defaults`
|
||
- `source`
|
||
- `point`
|
||
- `event before/after/at`
|
||
- `run_path`
|
||
|
||
9. Operation：
|
||
- `operation`
|
||
- `kind`
|
||
- `path`
|
||
- `process`
|
||
- `start_action`
|
||
- `end_action`
|
||
- `run_operation`
|
||
|
||
10. IO 与等待：
|
||
- `io.di/do/ai/ao/gi/go/ri/ro`
|
||
- `io.alias.*`
|
||
- IO 赋值。
|
||
- `wait`
|
||
- `timeout`
|
||
- `on_timeout alarm`
|
||
- `on_timeout call`
|
||
- `all/any/rising/falling/changed`
|
||
- `pulse`
|
||
|
||
11. 流程控制：
|
||
- `if/elseif/else`
|
||
- `while`
|
||
- `for`
|
||
- `switch/case/default`
|
||
- `break`
|
||
- `continue`
|
||
- `label`
|
||
- `jump`
|
||
|
||
12. 子程序和函数：
|
||
- `proc`
|
||
- `func`
|
||
- `call`
|
||
- `return`
|
||
- 参数方向 `in/out/inout`
|
||
- 作用域和名称解析。
|
||
|
||
13. 异常、报警和中断：
|
||
- `alarm`
|
||
- `raise`
|
||
- `try/catch/finally`
|
||
- `trap`
|
||
- `interrupt`
|
||
- `enable/disable interrupt`
|
||
|
||
14. 多任务语法：
|
||
- `task ... cycle ...`
|
||
- 首版只定义语法，不要求完整实时调度。
|
||
|
||
15. 品牌扩展：
|
||
- `post_hint abb/fanuc/kuka`
|
||
- `@brand.abb`
|
||
- `@brand.fanuc`
|
||
- `@brand.kuka`
|
||
- 无法支持的品牌扩展必须进入转换报告。
|
||
|
||
### 2.3 GRL P0
|
||
|
||
按语法规范第 24 章，P0 必须实现：
|
||
|
||
1. `language`、`module`、`proc`。
|
||
2. `const`、`var`、`persistent`。
|
||
3. `tool`、`frame`、`speed`、`zone`。
|
||
4. `joint_target`、`pose_target`。
|
||
5. `movej`、`movel`、`movec`。
|
||
6. `path`、`point`、`event`、`run_path`。
|
||
7. `operation`、`run_operation`。
|
||
8. `if`、`elseif`、`else`、`while`、`for`、`switch`。
|
||
9. `call`、`return`、`break`、`continue`。
|
||
10. `proc` 参数方向 `in/out/inout`。
|
||
11. `func`、函数调用表达式和返回值检查。
|
||
12. `io.do/di`、`wait`、`pulse`。
|
||
13. AST、语义检查、IR、source map。
|
||
14. ABB、FANUC、KUKA 后处理原型。
|
||
|
||
### 2.4 GRL P1
|
||
|
||
按语法规范第 24 章，P1 扩展：
|
||
|
||
1. `label/jump` 和品牌标签程序导入。
|
||
2. `trap`、`interrupt`。
|
||
3. 多任务 `task`。
|
||
4. 更完整的 IO 类型。
|
||
5. 工艺模板库。
|
||
6. 品牌程序导入。
|
||
7. 复杂品牌扩展和转换报告。
|
||
|
||
## 3. KDL WASM 功能范围
|
||
|
||
### 3.1 目标
|
||
|
||
KDL WASM 是 GRL、虚拟控制器、离线编程、路径验证和轨迹回放共用的运动学与轨迹计算内核。接口设计从 GRL 语义反推，不直接暴露 KDL C++ 类。
|
||
|
||
KDL WASM 负责：
|
||
|
||
1. `joint_target`、`pose_target` 的目标点解析和可达性验证。
|
||
2. `tool`、`frame`、`offset`、`offset_in` 的位姿变换。
|
||
3. `movej` 关节角度差分运行。
|
||
4. `movel` TCP 直线运行。
|
||
5. `movec` TCP 圆弧运行。
|
||
6. `path`、`run_path`、`operation` 的批量轨迹生成和批量诊断。
|
||
7. 速度、加速度、zone、采样周期、节拍估算。
|
||
8. 当前 TCP、当前关节、轨迹采样点、报警诊断。
|
||
|
||
KDL WASM 不负责：
|
||
|
||
1. GRL 词法和语法解析。
|
||
2. 程序流程控制、变量、IO、wait、子程序调用。
|
||
3. 碰撞检测和几何布尔运算。
|
||
4. 真实品牌控制器完整 look-ahead 和伺服细节。
|
||
5. OPFS 项目文件管理。
|
||
|
||
### 3.2 顶层 TypeScript API
|
||
|
||
必须实现 `KdlWasmApi` 中的异步接口：
|
||
|
||
1. 生命周期：
|
||
- `init`
|
||
- `dispose`
|
||
|
||
2. 机器人模型：
|
||
- `loadRobotFromUrdf`
|
||
- `createRobotFromModel`
|
||
- `destroyRobot`
|
||
- `getRobotInfo`
|
||
- `getJointLimits`
|
||
|
||
3. 位姿变换：
|
||
- `normalizePose`
|
||
- `composePose`
|
||
- `inversePose`
|
||
- `applyToolAndFrame`
|
||
- `applyOffset`
|
||
|
||
4. 运动学：
|
||
- `fk`
|
||
- `fkAllLinks`
|
||
- `jacobian`
|
||
- `ik`
|
||
- `ikBatch`
|
||
|
||
5. 检查：
|
||
- `checkJointLimits`
|
||
- `checkVelocityLimits`
|
||
- `checkSingularity`
|
||
- `checkReachability`
|
||
- `checkReachabilityBatch`
|
||
|
||
6. 梯形速度：
|
||
- `makeTrapProfile`
|
||
- `sampleTrapProfile`
|
||
|
||
7. 轨迹规划：
|
||
- `planMoveJ`
|
||
- `planMoveL`
|
||
- `planMoveC`
|
||
- `planPath`
|
||
- `validatePath`
|
||
- `estimateCycleTime`
|
||
- `resampleTrajectory`
|
||
|
||
### 3.3 KDL P0
|
||
|
||
按 KDL WASM 接口设计第 22 章，P0 必须暴露：
|
||
|
||
1. `init`
|
||
2. `loadRobotFromUrdf`
|
||
3. `createRobotFromModel`
|
||
4. `destroyRobot`
|
||
5. `getRobotInfo`
|
||
6. `getJointLimits`
|
||
7. `normalizePose`
|
||
8. `composePose`
|
||
9. `inversePose`
|
||
10. `applyOffset`
|
||
11. `applyToolAndFrame`
|
||
12. `fk`
|
||
13. `fkAllLinks`
|
||
14. `jacobian`
|
||
15. `ik`
|
||
16. `ikBatch`
|
||
17. `checkJointLimits`
|
||
18. `checkSingularity`
|
||
19. `checkReachability`
|
||
20. `checkReachabilityBatch`
|
||
21. `makeTrapProfile`
|
||
22. `sampleTrapProfile`
|
||
23. `planMoveJ`
|
||
24. `planMoveL`
|
||
25. `planMoveC`
|
||
26. `planPath`
|
||
27. `validatePath`
|
||
28. `estimateCycleTime`
|
||
29. `resampleTrajectory`
|
||
|
||
### 3.4 KDL P1
|
||
|
||
按 KDL WASM 接口设计第 22 章，P1 扩展：
|
||
|
||
1. `planBlendPath`
|
||
2. `planMoveSpline`
|
||
3. `checkCollisionInputPoses`，只提供 link poses，不做碰撞本身。
|
||
4. `optimizeSeedSequence`
|
||
5. `compareTrajectory`
|
||
6. 外部轴协调相关函数。
|
||
|
||
## 4. 虚拟控制器和 IO 运行时范围
|
||
|
||
### 4.1 控制器职责
|
||
|
||
虚拟控制器真正执行统一 `Executable IR`，而不是直接解释品牌文本。它必须支撑：
|
||
|
||
1. 控制器状态机：`PowerOff/Booting/MotorsOff/Ready/Manual/Auto/Running/Hold/Fault/EmergencyStop`。
|
||
2. 基础命令：`powerOn/powerOff/motorsOn/motorsOff/loadProgram/start/hold/resume/stop/resetFault/stepInto/stepOver/stepMotion`。
|
||
3. 执行模型：Program Counter、Call Stack、Scope Stack、Motion Queue、IO Image、Timer Table、Interrupt Table、Alarm Queue、Trace Buffer、Source Map、Brand Context。
|
||
4. 单主任务首版模型，后续扩展后台任务、多机器人任务、独立 IO 任务和监控任务。
|
||
5. `run_path` 展开为路径点运动和 before/after event。
|
||
6. `run_operation` 展开为 start action、path、end action，并将工艺状态写入 trace。
|
||
7. 品牌程序导入后的 IR 执行，并保留品牌源程序行号和转换报告。
|
||
|
||
### 4.2 IO Service 和 Wait
|
||
|
||
虚拟 IO 是虚拟调试核心能力。首版必须覆盖：
|
||
|
||
1. IO Image、IO Alias Table、IO Event Queue、Wait Registry、Edge Detector、IO Script Engine、IO Trace Logger。
|
||
2. 地址规范：`DI[1] -> io.di[1]`、`DO[1] -> io.do[1]`、`AI/AO/GI/GO/RI/RO` 同规则。
|
||
3. 程序可写 DO、AO、GO、RO；用户和脚本可按配置修改虚拟输入。
|
||
4. 所有读写必须经过 IO Service，并生成 `IoEvent`。
|
||
5. `wait` 执行时立即求值，未满足则创建 `ActiveWait`，由 controller tick 或 IO 变化触发重评估。
|
||
6. `wait timeout`、`pulse duration`、IO script `delay` 均基于虚拟时间；hold 暂停虚拟时间，stop/reset 取消 ActiveWait。
|
||
7. `rising/falling/changed` 边沿只在一个 tick 内有效，并保持同 tick 内事件顺序。
|
||
8. Wait 卡住诊断必须显示等待表达式、子表达式当前值、已等待时间、剩余超时时间、相关 IO 最近变化和 IO 脚本状态。
|
||
|
||
### 4.3 运动队列和 Trace
|
||
|
||
运动运行时必须：
|
||
|
||
1. 将 `MotionInstruction`、Path point、Operation 展开为 `MotionQueueItem`。
|
||
2. 保留 `instructionId/pathId/pathPointId/operationId`。
|
||
3. 调用 KDL 生成轨迹采样后按虚拟时间推进关节和 TCP。
|
||
4. 支持程序文本、路径表、3D 轨迹和报警诊断之间通过 source map 联动定位。
|
||
5. 记录 motion trace、IO trace、wait trace、alarm trace，供报告和回放使用。
|
||
|
||
### 4.4 虚拟调试增强
|
||
|
||
虚拟调试增强必须覆盖：
|
||
|
||
1. 断点。
|
||
2. 单步进入和单步越过。
|
||
3. 运动断点。
|
||
4. 轨迹回放。
|
||
5. 变量 watch。
|
||
6. IO 脚本调试。
|
||
7. GRL、Path、Operation、品牌源程序行号与 IR 的联动调试。
|
||
8. IK、IO、逻辑、后处理和品牌导入错误的跨视图定位。
|
||
|
||
## 5. OLP 工作台、工作区和交付范围
|
||
|
||
### 5.1 OLP 对象模型
|
||
|
||
商业 OLP 工作流以对象树组织项目，而不是只管理文本文件。内部对象模型必须覆盖：
|
||
|
||
1. `RobotModel`
|
||
2. `ToolModel`
|
||
3. `FrameModel`
|
||
4. `TargetModel`
|
||
5. `PathModel`
|
||
6. `PathPointModel`
|
||
7. `OperationModel`
|
||
8. `ProgramModel`
|
||
9. `PostProfile`
|
||
10. Station、Cell、Fixture、Part、Device、Geometry、Calibration、Report。
|
||
|
||
对象模型用途：
|
||
|
||
1. UI 对象树和路径编辑器直接操作。
|
||
2. 从规划点或曲线生成 Path。
|
||
3. 从 Path/Operation 生成 GRL。
|
||
4. 品牌程序导入后尽量恢复 target/path/program。
|
||
5. 后处理和虚拟控制器最终仍以 IR 为准。
|
||
|
||
### 5.2 OPFS 工作区
|
||
|
||
OPFS 项目必须提供稳定布局和显式导入导出能力：
|
||
|
||
```text
|
||
/projects/{projectId}/
|
||
project.json
|
||
station/
|
||
libraries/
|
||
geometry/
|
||
robots/
|
||
programs/
|
||
targets/
|
||
tools/
|
||
frames/
|
||
io/
|
||
generated/
|
||
logs/
|
||
reports/
|
||
calibration/
|
||
snapshots/
|
||
.index.json
|
||
.lock
|
||
```
|
||
|
||
必须实现的工作区能力：
|
||
|
||
1. `listProjects/openProject/createProject`
|
||
2. `readText/writeText`
|
||
3. `readJson/writeJson`
|
||
4. `delete`
|
||
5. `snapshot`
|
||
6. `exportZip/importZip`
|
||
7. 存储占用显示、迁移、损坏检测和备份。
|
||
|
||
### 5.3 Web 工作台
|
||
|
||
第一屏应直接进入离线编程和虚拟调试工作台。必须页面包括：
|
||
|
||
1. 项目管理。
|
||
2. 工作站布局。
|
||
3. 资源库。
|
||
4. 几何与 CAD。
|
||
5. 程序编辑。
|
||
6. 虚拟示教器。
|
||
7. IO 面板。
|
||
8. 运动监控。
|
||
9. 路径编辑器。
|
||
10. Operation 编辑器。
|
||
11. 验证与报告。
|
||
12. 校准与现场回读。
|
||
13. 后处理导出。
|
||
14. 品牌程序导入。
|
||
15. 日志和报警。
|
||
16. Wait 调试面板。
|
||
|
||
UI 验收重点是工作流可用、状态可见、诊断可定位、数据可导出，不以营销展示页作为首屏。
|
||
|
||
### 5.4 品牌导入和后处理闭环
|
||
|
||
除三品牌后处理外，全目录对标要求建立 Brand Importer：
|
||
|
||
```text
|
||
ABB RAPID / FANUC LS / KUKA KRL
|
||
-> Brand Importer
|
||
-> Brand AST
|
||
-> Normalized IR
|
||
-> Reconstructed GRL
|
||
-> Optional OLP Path/Operation Model
|
||
-> Import Report
|
||
```
|
||
|
||
首版建议：
|
||
|
||
1. ABB 解析 `.mod/.sys` 文本中的 `MODULE/PROC/MoveJ/MoveL/MoveC/robtarget/tooldata/wobjdata`。
|
||
2. KUKA 解析 `.src/.dat` 文本中的 `DEF/PTP/LIN/CIRC/E6POS/E6AXIS/$TOOL/$BASE`。
|
||
3. FANUC 解析 LS 风格文本或可读 TP 导出中的 `J/L/C/P[]/PR[]/UTOOL/UFRAME/CALL/LBL/JMP`。
|
||
4. 导入目标是提取目标点、运动序列、工具、坐标系、速度、过渡、主要 IO 和流程控制，转换为统一 IR 并生成转换报告。
|
||
|
||
### 5.5 报告和客户交付
|
||
|
||
报告必须可导出 JSON 和 HTML，覆盖：
|
||
|
||
| 报告 | 内容 |
|
||
| --- | --- |
|
||
| Reachability Report | 不可达点、接近限位点、IK 解 |
|
||
| Collision Report | 碰撞对象、时间、路径点、严重程度 |
|
||
| Cycle Time Report | 总节拍、路径节拍、wait 时间、瓶颈 |
|
||
| IO Report | IO 映射、wait、pulse、脚本触发 |
|
||
| Post Report | 品牌映射、近似处理、不支持项 |
|
||
| Calibration Report | TCP、Frame、Base 偏差 |
|
||
| Import Report | 品牌程序导入结果、丢失语义、恢复对象 |
|
||
|
||
客户交付包必须包含 GRL 源程序、品牌后处理程序、目标点和路径数据、IO map、后处理报告、可达性报告、节拍报告、校准数据和可选仿真 trace。
|
||
|
||
### 5.6 商业级 OLP、Sim-to-Real 和真实项目扩展
|
||
|
||
商业级扩展必须在任务矩阵中保留，不能被 MVP 范围省略：
|
||
|
||
1. 资源库管理：机器人库、工具库、夹具库、工艺模板库、后处理 profile 库。
|
||
2. 几何导入：mesh/CAD 转换文件、点/边/曲线/面法向提取、曲线路径生成。
|
||
3. 碰撞和干涉验证：基础碰撞对象、时间、路径点和严重程度定位。
|
||
4. 校准和 Sim-to-Real：TCP、Frame、Base 校准数据，离线/现场差异比对。
|
||
5. 品牌程序导入后的真实项目回读和交叉品牌再导出风险报告。
|
||
6. 多机器人和外部轴：任务模型、运动组、外部轴协调和复杂工作站支持。
|
||
7. 真实控制器校验流程：导出程序不等于现场可高速运行，必须保留低速验证和校验报告边界。
|
||
8. 完整 CAD kernel、真实控制器通信、高精度轨迹复现作为更后续扩展，但必须有明确非 MVP 边界。
|
||
|
||
## 6. 数据流和线程模型
|
||
|
||
### 6.1 总体数据流
|
||
|
||
全系统数据流以 `Executable IR` 为中枢：
|
||
|
||
1. Project resources 提供 URDF、GRL、targets、paths、operations、io map、post profile。
|
||
2. TypeScript 编译层生成 AST、符号表、语义诊断和 IR。
|
||
3. 只有运动相关 IR 会构造成 KDL request。
|
||
4. KDL Worker 返回轨迹、路径验证、节拍和结构化诊断。
|
||
5. 虚拟控制器消费 IR、轨迹和 IO 事件，生成 trace。
|
||
6. 后处理器消费 IR、OLP 对象模型和 post profile，生成品牌程序和转换报告。
|
||
7. 报告引擎消费诊断、trace、轨迹和对象模型，生成 JSON/HTML 报告。
|
||
|
||
### 6.2 不进入 KDL WASM 的数据流
|
||
|
||
以下语义由编译层或虚拟控制器执行，不传入 KDL：
|
||
|
||
1. `if/elseif/else`
|
||
2. `while/for/switch`
|
||
3. `proc/func/call/return`
|
||
4. `io.do/di/ai/ao`
|
||
5. `wait/pulse/timer`
|
||
6. `alarm/raise/try/catch`
|
||
7. `operation.process`
|
||
8. Brand import context
|
||
9. UI 和 OPFS 工作区状态
|
||
10. 报告生成和客户交付包打包
|
||
|
||
### 6.3 推荐线程模型
|
||
|
||
Web 主线程只负责 UI 交互和轻量状态更新。建议 Worker 划分：
|
||
|
||
1. Parser Worker：tokenize、parse、semantic check、diagnostics。
|
||
2. Controller Worker：interpreter、execution clock、variable state、IO simulation、motion queue。
|
||
3. KDL Worker：WASM 初始化、FK/IK/Jacobian、trajectory sampling。
|
||
4. Storage Worker：OPFS read/write、project snapshot、import/export。
|
||
5. Geometry/Validation Worker：几何采样、碰撞、长路径节拍分析和报告生成。
|
||
|
||
### 6.4 流程图资产同步
|
||
|
||
`work/doc/通用机器人项目功能与数据流程图-png` 下的 `.mmd` 是流程图源，`.png` 是渲染结果。实施文档和后续代码必须保持以下同步关系：
|
||
|
||
1. `flow-01` 对应总体功能流程。
|
||
2. `flow-02` 对应 GRL 编译与执行流程。
|
||
3. `flow-03` 对应 KDL WASM 计算流程。
|
||
4. `flow-04` 对应数据传递流程。
|
||
5. `flow-05` 对应诊断传递流程。
|
||
6. 若流程图源或渲染图更新，`01-项目功能内容.md`、`02-项目程序开发详细步骤.md`、`04-任务矩阵.md` 和 `05-验收证据.md` 必须同步记录影响。
|
||
|
||
## 7. 共享数据和单位
|
||
|
||
### 7.1 单位
|
||
|
||
GRL 编译器内部必须统一：
|
||
|
||
| 物理量 | 内部单位 |
|
||
| --- | --- |
|
||
| 长度 | meter |
|
||
| 角度 | radian |
|
||
| 时间 | second |
|
||
| 质量 | kilogram |
|
||
| 线速度 | meter/second |
|
||
| 角速度 | radian/second |
|
||
| 加速度 | meter/second^2 或 radian/second^2 |
|
||
|
||
### 7.2 位姿
|
||
|
||
内部统一为：
|
||
|
||
```ts
|
||
interface Pose {
|
||
position: [number, number, number];
|
||
quaternion: [number, number, number, number]; // x, y, z, w
|
||
}
|
||
```
|
||
|
||
GRL `pose(x, y, z, rx, ry, rz)` 必须在 TypeScript 编译层规范化为 KDL `Pose`。
|
||
|
||
### 7.3 目标点
|
||
|
||
必须统一到：
|
||
|
||
```ts
|
||
interface PoseTarget {
|
||
id?: string;
|
||
pose: Pose;
|
||
config?: RobotConfiguration;
|
||
tool?: Pose;
|
||
frame?: Pose;
|
||
extAxis?: number[];
|
||
sourceMap?: MotionSourceMap;
|
||
}
|
||
|
||
interface JointTarget {
|
||
id?: string;
|
||
joints: number[];
|
||
extAxis?: number[];
|
||
sourceMap?: MotionSourceMap;
|
||
}
|
||
```
|
||
|
||
### 7.4 速度和 zone
|
||
|
||
GRL 速度和过渡必须编译为：
|
||
|
||
```ts
|
||
type SpeedSpec =
|
||
| { kind: "joint_percent"; value: number }
|
||
| { kind: "joint_abs"; velocity: number; acceleration?: number }
|
||
| { kind: "linear"; velocity: number; acceleration?: number; angularVelocity?: number };
|
||
|
||
type ZoneSpec =
|
||
| { kind: "fine" }
|
||
| { kind: "distance"; value: number }
|
||
| { kind: "cnt"; value: number }
|
||
| { kind: "continuous" };
|
||
```
|
||
|
||
首版 `zone` 只用于诊断和后处理，运动规划按 `fine` 到点执行，并产生 `KDL_ZONE_APPROXIMATED`。
|
||
|
||
### 7.5 诊断
|
||
|
||
所有语言、语义、KDL 和后处理错误必须结构化。KDL 固定 code 至少包含：
|
||
|
||
| code | 含义 |
|
||
| --- | --- |
|
||
| `KDL_INVALID_MODEL` | 机器人模型非法 |
|
||
| `KDL_TARGET_UNREACHABLE` | 目标不可达 |
|
||
| `KDL_IK_FAILED` | IK 求解失败 |
|
||
| `KDL_JOINT_LIMIT` | 关节超限 |
|
||
| `KDL_VELOCITY_LIMIT` | 速度超限 |
|
||
| `KDL_ACCEL_LIMIT` | 加速度超限 |
|
||
| `KDL_SINGULARITY` | 接近奇异 |
|
||
| `KDL_ARC_DEGENERATE` | 圆弧退化 |
|
||
| `KDL_PATH_EMPTY` | 空路径 |
|
||
| `KDL_ZONE_APPROXIMATED` | zone 被近似处理 |
|
||
|
||
GRL 语义诊断至少覆盖：
|
||
|
||
1. 未定义符号。
|
||
2. 重复声明。
|
||
3. 类型不匹配。
|
||
4. 单位错误。
|
||
5. 目标点类型不适合运动指令。
|
||
6. `movec` 缺 via 或三点退化。
|
||
7. 工具、坐标系、速度、zone 不可解析。
|
||
8. IO 地址非法。
|
||
9. 参数数量、类型、方向错误。
|
||
10. `func` 返回路径错误或包含非法副作用。
|
||
11. `break/continue/jump` 位置非法。
|
||
12. Path 为空或点名重复。
|
||
13. Operation 引用不存在的 Path。
|
||
14. 后处理品牌不支持所用语义。
|
||
|
||
## 8. GRL 与 KDL 的调用关系
|
||
|
||
| GRL 语法 | 编译结果 | KDL WASM 函数 |
|
||
| --- | --- | --- |
|
||
| `target home = joint_target` | `JointTarget` | `checkJointLimits` |
|
||
| `target pick = pose_target` | `PoseTarget` | `checkReachability` |
|
||
| `pick offset z 100 mm` | `OffsetSpec` | `applyOffset` |
|
||
| `movej home` | `MoveJRequest` | `planMoveJ` |
|
||
| `movel pick` | `MoveLRequest` | `planMoveL` |
|
||
| `movec via mid target end` | `MoveCRequest` | `planMoveC` |
|
||
| `run_path pick_path` | `PathPlanRequest` | `planPath` |
|
||
| Path 可达性检查 | `PathPlanRequest` | `validatePath` |
|
||
| 节拍报告 | `TrajectoryResult/PathPlanResult` | `estimateCycleTime` |
|
||
|
||
以下 GRL 语义不进入 KDL WASM：
|
||
|
||
1. `if/elseif/else`
|
||
2. `while/for/switch`
|
||
3. `proc/func/call/return`
|
||
4. `io.do/di/ai/ao`
|
||
5. `wait/pulse/timer`
|
||
6. `alarm/raise/try/catch`
|
||
7. `operation.process`
|
||
|
||
## 9. 验收口径
|
||
|
||
### 9.1 GRL P0 验收
|
||
|
||
1. EBNF 覆盖语法规范第 22 章。
|
||
2. 语法规范第 23 章完整示例可解析。
|
||
3. AST 保留 source range、单位原文、规范化值和品牌 metadata。
|
||
4. 语义检查覆盖语法规范第 21 章全部检查项。
|
||
5. `path` 可编译为 `PathPlanRequest`。
|
||
6. `operation` 可展开为 start action、path、end action。
|
||
7. `movej/movel/movec` 可编译为对应 KDL request。
|
||
8. ABB、FANUC、KUKA 后处理原型有 golden file。
|
||
|
||
### 9.2 KDL P0 验收
|
||
|
||
1. P0 29 个函数全部在 TypeScript API 和 Worker RPC 中可调用。
|
||
2. URDF 到 KDL Chain joint 顺序稳定。
|
||
3. FK 与 golden 或原生 KDL 结果对比在容差内。
|
||
4. IK 后 FK 回代误差小于容差。
|
||
5. Jacobian 尺寸和奇异性指标正确。
|
||
6. 梯形速度曲线长距离/短距离测试通过。
|
||
7. `planMoveJ` 关节同起同停。
|
||
8. `planMoveL` TCP 直线误差小于容差。
|
||
9. `planMoveC` 圆心、半径、弧长、圆弧误差正确，共线返回 `KDL_ARC_DEGENERATE`。
|
||
10. `planPath/validatePath` 保留 segment、target 和 source map。
|
||
11. 错误处理不抛裸字符串，返回结构化 `KdlError` 或 `MotionDiagnostic`。
|
||
|
||
### 9.3 集成验收
|
||
|
||
1. GRL `movej/movel/movec` 编译为 KDL request 并生成轨迹。
|
||
2. GRL `path` 编译为 `PathPlanRequest` 并生成整条路径。
|
||
3. `run_operation` 展开后 KDL 只处理 motion segment。
|
||
4. `if/for/switch/call/wait/io` 不直接调用 KDL，但能影响虚拟控制器何时调用运动函数。
|
||
5. 长路径批量验证有性能记录。
|
||
6. Worker 初始化、崩溃恢复和取消请求测试通过。
|
||
|
||
### 9.4 虚拟控制器和 IO 验收
|
||
|
||
1. 控制器状态机支持上电、使能、加载、启动、暂停、继续、停止、报警复位和单步。
|
||
2. 程序运行时能显示当前行、变量、调用栈、IO、报警、TCP、关节、当前 Path/Point/Operation。
|
||
3. `run_path` 和 `run_operation` 可在 Motion Queue 中保留 source map 并驱动轨迹回放。
|
||
4. `wait` 能显示表达式、关联 IO、已等待时间和剩余 timeout。
|
||
5. 用户可通过 IO 面板手动满足 wait。
|
||
6. IO 脚本可模拟夹具反馈并自动满足 wait。
|
||
7. wait timeout 可产生报警或执行 on_timeout。
|
||
8. pulse 输出按虚拟时间自动复位。
|
||
9. IO trace、motion trace 和 alarm trace 顺序稳定。
|
||
|
||
### 9.5 工作区、UI、报告和交付验收
|
||
|
||
1. 用户能在浏览器中新建、保存、打开、导入和导出项目。
|
||
2. 用户能导入 URDF，定义工具、工件坐标、目标点、Path 和 Operation。
|
||
3. 用户能从 Path/Operation 生成 GRL，并手工编辑 GRL。
|
||
4. 系统能实时显示语法和语义错误。
|
||
5. 同一个 Path/Program 能导出 ABB、FANUC、KUKA 三种目标文本和后处理报告。
|
||
6. 至少一种品牌程序能导入、转换为 IR 并在虚拟控制器中运行。
|
||
7. 能生成可达性报告、节拍报告、IO/Wait 报告、后处理报告。
|
||
8. 能导出包含源程序、品牌程序、IO map 和报告的客户交付包。
|
||
9. 自动测试覆盖解析器、KDL WASM、虚拟控制器、IO/Wait、后处理和品牌导入。
|
||
|
||
### 9.6 商业级扩展和流程图资产验收
|
||
|
||
1. 虚拟调试支持断点、运动断点、轨迹回放、变量 watch 和跨源定位。
|
||
2. 资源库、工艺模板、几何导入和曲线路径生成有对象模型和测试。
|
||
3. 基础碰撞检测可定位对象、时间和路径点。
|
||
4. TCP、Frame、Base 校准数据可保存、应用并进入报告。
|
||
5. 多机器人、外部轴、真实控制器校验流程有任务拆解、边界说明和扩展验收。
|
||
6. `flow-01` 到 `flow-05` 的 Mermaid 源图和 PNG 渲染图纳入覆盖证据。
|
||
7. 流程图资产与功能文档、任务矩阵、验收证据之间无断链。
|