491 lines
13 KiB
Markdown
491 lines
13 KiB
Markdown
# 01-项目功能内容
|
||
|
||
版本：0.3
|
||
日期：2026-06-27
|
||
对标文档：
|
||
|
||
1. `/home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md`
|
||
2. `/home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md`
|
||
|
||
## 1. 项目定位
|
||
|
||
本目录用于把 GRL 编程语法规范和 KDL WASM 计算接口设计落成实施计划。实施目标是形成一套互相闭合的语言层和运动计算层：
|
||
|
||
```text
|
||
GRL Source
|
||
-> Lexer / Parser
|
||
-> AST
|
||
-> Symbol Table
|
||
-> Semantic Analyzer
|
||
-> Executable IR / MotionSegmentRequest
|
||
-> KdlWorkerClient
|
||
-> KDL WASM
|
||
-> TrajectoryResult / PathValidationResult / Diagnostics
|
||
```
|
||
|
||
Web UI、OPFS、碰撞检测和真实控制器通信不作为独立实施主线；相关内容只在两份对标文档明确要求的 GRL 工程结构、轨迹 trace、虚拟控制器调用关系、后处理或测试场景中进入范围。
|
||
|
||
## 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. 共享数据和单位
|
||
|
||
### 4.1 单位
|
||
|
||
GRL 编译器内部必须统一：
|
||
|
||
| 物理量 | 内部单位 |
|
||
| --- | --- |
|
||
| 长度 | meter |
|
||
| 角度 | radian |
|
||
| 时间 | second |
|
||
| 质量 | kilogram |
|
||
| 线速度 | meter/second |
|
||
| 角速度 | radian/second |
|
||
| 加速度 | meter/second^2 或 radian/second^2 |
|
||
|
||
### 4.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`。
|
||
|
||
### 4.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;
|
||
}
|
||
```
|
||
|
||
### 4.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`。
|
||
|
||
### 4.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. 后处理品牌不支持所用语义。
|
||
|
||
## 5. 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`
|
||
|
||
## 6. 验收口径
|
||
|
||
### 6.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。
|
||
|
||
### 6.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`。
|
||
|
||
### 6.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 初始化、崩溃恢复和取消请求测试通过。
|