531 lines
14 KiB
Markdown
531 lines
14 KiB
Markdown
# 通用机器人项目主要实施步骤
|
||
|
||
版本：0.1
|
||
日期：2026-06-27
|
||
来源：`/home/meswork/kdl_work/work/working1`
|
||
用途：作为阅读参考，概览项目从 KDL WASM 计算接口到 GRL 编译与后处理的主要实施步骤。
|
||
|
||
## 1. 实施主线
|
||
|
||
项目实施分两条主线推进：
|
||
|
||
1. KDL WASM 计算接口线
|
||
- 任务编号：`KW-001` 到 `KW-013`
|
||
- 对标：`KDL_WASM计算接口设计.md`
|
||
- 目标：提供稳定的 Worker API、机器人模型、运动学、轨迹规划、Path 验证、诊断和性能能力。
|
||
|
||
2. GRL 编程语法线
|
||
- 任务编号：`KW-100` 到 `KW-112`
|
||
- 对标：`通用机器人编程语法规范.md`
|
||
- 目标：实现 GRL lexer/parser、AST、语义检查、IR、Path/Operation、IO/wait、后处理和自动生成。
|
||
|
||
两条线的集成点是：GRL 的 `movej/movel/movec/path/operation` 编译为 KDL WASM 的 `MoveJRequest/MoveLRequest/MoveCRequest/PathPlanRequest`，由 KDL WASM 返回轨迹和诊断。
|
||
|
||
## 2. 推荐工程结构
|
||
|
||
```text
|
||
/home/meswork/kdl_work/
|
||
orocos_kinematics_dynamics/
|
||
orocos_kdl/
|
||
kdl-wasm/
|
||
CMakeLists.txt
|
||
bindings/
|
||
kdl_c_api.cpp
|
||
kdl_embind.cpp
|
||
web/
|
||
src/
|
||
kdl/
|
||
kdlClient.ts
|
||
kdl.worker.ts
|
||
rpc.ts
|
||
types.ts
|
||
robot/
|
||
urdfParser.ts
|
||
normalizedRobotModel.ts
|
||
grl/
|
||
lexer/
|
||
parser/
|
||
ast/
|
||
semantic/
|
||
ir/
|
||
generator/
|
||
post/
|
||
abb/
|
||
fanuc/
|
||
kuka/
|
||
tests/
|
||
kdl/
|
||
grl/
|
||
integration/
|
||
post/
|
||
```
|
||
|
||
## 3. 阶段 1：基础工程、Worker RPC 和 GRL 词法骨架
|
||
|
||
关联任务：`KW-001`、`KW-100`、`KW-101`
|
||
|
||
目标：
|
||
|
||
1. 建立 `kdl-wasm` wrapper 工程。
|
||
2. 使用 Emscripten 编译 Orocos KDL，生成 `kdl.js`、`kdl.wasm`、`kdl.d.ts`。
|
||
3. 建立 `KdlRpcRequest/KdlRpcResponse` 和 `KdlWorkerClient`。
|
||
4. KDL WASM 只在 Worker 中运行。
|
||
5. 建立 GRL lexer，支持注释、标识符、字符串、数字、单位和保留关键字。
|
||
6. 建立 GRL parser 和 AST 骨架，支持 `language grl 0.1`、`module`、`import`、顶层声明。
|
||
|
||
输入：
|
||
|
||
1. Orocos KDL 源码。
|
||
2. GRL 源文件。
|
||
|
||
输出：
|
||
|
||
1. KDL WASM 构建产物。
|
||
2. Worker RPC 基础 API。
|
||
3. GRL Tokens 和 AST。
|
||
|
||
验收重点：
|
||
|
||
1. `init()` 返回 `KdlRuntimeInfo`。
|
||
2. Worker 请求有唯一 id。
|
||
3. 错误返回 `{ code, message, diagnostics }`。
|
||
4. GRL 最小文件可解析。
|
||
5. AST 保留 source range、注释位置、单位原文和规范化值。
|
||
|
||
## 4. 阶段 2：机器人模型、GRL 数据声明和共享类型
|
||
|
||
关联任务：`KW-002`、`KW-102`
|
||
|
||
目标：
|
||
|
||
1. TypeScript 解析 URDF XML。
|
||
2. 检查 link/joint 连通性和单位。
|
||
3. 生成 `NormalizedRobotModel`。
|
||
4. WASM 根据标准模型构造 KDL `Tree/Chain`。
|
||
5. 创建 `RobotHandle` 并缓存求解器。
|
||
6. GRL 支持 `const/var/persistent`、基础类型、机器人类型。
|
||
7. GRL 支持 `tool/frame/load/joint_target/pose_target/pose/poseq/robot_config/ext_axis/speed/zone/offset/offset_in`。
|
||
|
||
输入：
|
||
|
||
1. `robot.urdf`
|
||
2. GRL 中的 tool/frame/target/speed/zone 声明。
|
||
|
||
输出：
|
||
|
||
1. `NormalizedRobotModel`
|
||
2. `RobotHandle`
|
||
3. `JointTarget`
|
||
4. `PoseTarget`
|
||
5. `SpeedSpec`
|
||
6. `ZoneSpec`
|
||
7. `OffsetSpec`
|
||
|
||
验收重点：
|
||
|
||
1. URDF joint 顺序稳定。
|
||
2. base/tip 不连通返回 `KDL_INVALID_MODEL`。
|
||
3. `getRobotInfo/getJointLimits` 正确。
|
||
4. GRL target 能编译为 KDL 共享数据结构。
|
||
5. speed/zone 能编译为 `SpeedSpec/ZoneSpec`。
|
||
|
||
## 5. 阶段 3：KDL 基础运动学和 GRL 运动指令
|
||
|
||
关联任务：`KW-003` 到 `KW-006`、`KW-103`
|
||
|
||
目标：
|
||
|
||
1. 实现 KDL `fk`、`fkAllLinks`。
|
||
2. 实现 KDL `ik`、`ikBatch`。
|
||
3. 实现 KDL `jacobian`、`checkSingularity`、`checkJointLimits`、`checkReachability`、`checkReachabilityBatch`、`checkVelocityLimits`。
|
||
4. 实现 KDL `normalizePose`、`composePose`、`inversePose`、`applyToolAndFrame`、`applyOffset`。
|
||
5. GRL 支持 `movej/movel/movec` 和 `set_tool/set_frame/set_speed/set_zone`。
|
||
6. GRL 运动指令编译为 `MotionInstruction`，再映射为 KDL request。
|
||
|
||
输入：
|
||
|
||
1. `RobotHandle`
|
||
2. `JointTarget`
|
||
3. `PoseTarget`
|
||
4. `tool/frame/speed/zone`
|
||
5. GRL 运动语句。
|
||
|
||
输出：
|
||
|
||
1. FK/TCP 位姿。
|
||
2. IK 关节解。
|
||
3. Jacobian 和奇异性诊断。
|
||
4. `MotionInstruction`
|
||
5. `MoveJRequest/MoveLRequest/MoveCRequest`
|
||
|
||
验收重点：
|
||
|
||
1. FK 与 golden 数据或原生 KDL 对比在容差内。
|
||
2. IK 后 FK 回代误差小于容差。
|
||
3. `ikBatch` 返回顺序与输入顺序一致。
|
||
4. 奇异点返回 `KDL_SINGULARITY` warning。
|
||
5. `offset`、`offset_in tool`、`offset_in frame` 结果正确。
|
||
6. GRL 编译到 IR 前能解析确定的 tool、frame、speed、zone。
|
||
|
||
## 6. 阶段 4：梯形速度和三类基础运动轨迹
|
||
|
||
关联任务：`KW-007` 到 `KW-010`
|
||
|
||
目标：
|
||
|
||
1. 实现 `makeTrapProfile` 和 `sampleTrapProfile`。
|
||
2. 实现 `planMoveJ`。
|
||
3. 实现 `planMoveL`。
|
||
4. 实现 `planMoveC`。
|
||
|
||
MOVEJ 重点：
|
||
|
||
1. `joint_target` 直接作为 `qEnd`。
|
||
2. `pose_target` 先 IK 得到 `qEnd`。
|
||
3. 各关节同起同停。
|
||
4. 每个采样点 FK 输出 TCP。
|
||
|
||
MOVEL 重点：
|
||
|
||
1. 起点由 `startJoints` FK 得到。
|
||
2. 目标点应用 tool/frame/offset。
|
||
3. 生成 TCP 直线采样。
|
||
4. 逐点 IK，seed 使用上一采样点关节。
|
||
|
||
MOVEC 重点：
|
||
|
||
1. 起点由当前关节 FK 得到。
|
||
2. via 和 target 应用 tool/frame/offset。
|
||
3. 检查三点重合或近似共线。
|
||
4. 计算圆心、半径、法向、角度、弧长。
|
||
5. `TrajectoryResult.meta.circle` 包含 `CirclePlanMeta`。
|
||
|
||
输入：
|
||
|
||
1. `MoveJRequest`
|
||
2. `MoveLRequest`
|
||
3. `MoveCRequest`
|
||
4. `TrapProfileOptions`
|
||
|
||
输出：
|
||
|
||
1. `TrapProfileResult`
|
||
2. `TrajectoryResult`
|
||
3. `MotionDiagnostic`
|
||
|
||
验收重点：
|
||
|
||
1. 梯形速度曲线长距离为 trapezoid，短距离为 triangle。
|
||
2. 采样首点 `s=0`，末点 `s=1`，`s` 单调递增。
|
||
3. MOVEJ 关节同起同停。
|
||
4. MOVEL TCP 直线误差小于容差。
|
||
5. MOVEC 圆弧元数据正确。
|
||
6. 三点共线返回 `KDL_ARC_DEGENERATE`。
|
||
7. P0 中非 fine zone 返回 `KDL_ZONE_APPROXIMATED`。
|
||
|
||
## 7. 阶段 5：Path、Operation 和批量路径验证
|
||
|
||
关联任务：`KW-011`、`KW-104`、`KW-105`
|
||
|
||
目标：
|
||
|
||
1. GRL 支持 `path/defaults/source/point/event/run_path`。
|
||
2. GRL 支持 `operation/kind/path/process/start_action/end_action/run_operation`。
|
||
3. Path 编译为 `PathPlanRequest`。
|
||
4. Operation 展开为 start action + path + end action。
|
||
5. KDL 实现 `planPath` 和 `validatePath`。
|
||
|
||
输入：
|
||
|
||
1. GRL Path。
|
||
2. GRL Operation。
|
||
3. `MotionSegmentRequest[]`
|
||
4. `PathPlanRequest`
|
||
|
||
输出：
|
||
|
||
1. `PathPlanResult`
|
||
2. `PathValidationResult`
|
||
3. Path source map。
|
||
4. Operation 展开结果。
|
||
|
||
验收重点：
|
||
|
||
1. 空 Path 报错。
|
||
2. 重复 point 名称报错。
|
||
3. `run_path` 可生成 `PathPlanRequest`。
|
||
4. `planPath` 按 segment 顺序规划。
|
||
5. 上一段终点关节作为下一段起点。
|
||
6. 轨迹点合并后重新编号和更新时间。
|
||
7. 保留 `segmentId/targetId/sourceMap`。
|
||
8. `run_operation` 展开后 KDL 只处理 motion segment。
|
||
|
||
## 8. 阶段 6：IO、wait、pulse 和流程控制
|
||
|
||
关联任务：`KW-106`、`KW-107`
|
||
|
||
目标：
|
||
|
||
1. 支持 `io.di/do/ai/ao/gi/go/ri/ro`。
|
||
2. 支持 `io.alias.*`。
|
||
3. 支持 IO 赋值。
|
||
4. 支持 `wait` 条件、`timeout`、`on_timeout alarm/call`。
|
||
5. 支持 `all/any/rising/falling/changed`。
|
||
6. 支持 `pulse`。
|
||
7. 支持 `if/elseif/else`、`while`、`for`、`switch/case/default`。
|
||
8. 支持 `break/continue/label/jump`。
|
||
|
||
输入：
|
||
|
||
1. IO map。
|
||
2. GRL IO/wait/pulse 语句。
|
||
3. GRL 流程控制语句。
|
||
|
||
输出：
|
||
|
||
1. `IoInstruction`
|
||
2. `WaitInstruction`
|
||
3. `BranchInstruction`
|
||
4. pulse IR。
|
||
|
||
验收重点：
|
||
|
||
1. IO 地址按 io_map 或允许范围校验。
|
||
2. wait 条件可编译。
|
||
3. pulse trace 必须包含置位和复位事件。
|
||
4. 条件表达式必须为 bool。
|
||
5. `break/continue` 位置合法。
|
||
6. `switch case` 为常量表达式且不重复。
|
||
7. `jump` 不能跳入非法块结构。
|
||
8. IO、wait、pulse 和流程控制不直接进入 KDL。
|
||
|
||
## 9. 阶段 7：proc、func、异常、报警、中断和多任务语法
|
||
|
||
关联任务：`KW-108`、`KW-109`
|
||
|
||
目标：
|
||
|
||
1. 支持 `proc`、`func`、`call`、`return`。
|
||
2. 支持参数方向 `in/out/inout`。
|
||
3. 实现作用域和名称解析。
|
||
4. 对递归给出 warning 或 error。
|
||
5. 支持 `alarm`、`raise`、`try/catch/finally`。
|
||
6. P1 语法保留 `trap/interrupt/enable/disable/task cycle`。
|
||
|
||
输入：
|
||
|
||
1. GRL 子程序和函数。
|
||
2. GRL 异常和中断语法。
|
||
|
||
输出：
|
||
|
||
1. `CallInstruction`
|
||
2. `ReturnInstruction`
|
||
3. `AlarmInstruction`
|
||
4. 异常处理 IR。
|
||
5. P1 语法 AST。
|
||
|
||
验收重点：
|
||
|
||
1. `out` 参数所有正常返回路径赋值。
|
||
2. `inout/out` 实参必须为左值。
|
||
3. `func` 所有正常返回路径返回兼容类型。
|
||
4. `func` 默认不允许执行运动、wait、pulse、run_path、run_operation。
|
||
5. P0 支持 alarm/raise/try/catch 基础语义。
|
||
6. P1 未实现语义必须在后处理或运行时报明确诊断。
|
||
|
||
## 10. 阶段 8：语义检查、IR、source map 和 KDL 集成
|
||
|
||
关联任务：`KW-110`、`KW-012`
|
||
|
||
目标：
|
||
|
||
1. 实现 Symbol Table。
|
||
2. 实现 Semantic Analyzer。
|
||
3. 生成 Executable IR。
|
||
4. 保留 source map。
|
||
5. 完成 GRL 到 KDL request 的编译桥接。
|
||
6. KDL 实现 `estimateCycleTime` 和 `resampleTrajectory`。
|
||
7. 建立统一诊断分级：error、warning、info。
|
||
|
||
必须检查：
|
||
|
||
1. 标识符重复或未声明。
|
||
2. 类型是否匹配。
|
||
3. 目标点类型是否适合运动指令。
|
||
4. `movec` 是否缺少 via 点。
|
||
5. 圆弧三点是否重合或共线。
|
||
6. 工具、坐标系、速度、过渡是否可解析。
|
||
7. 单位是否正确。
|
||
8. IO 地址是否存在。
|
||
9. 子程序参数数量和类型是否匹配。
|
||
10. `out` 参数是否赋值。
|
||
11. `func` 返回路径是否正确。
|
||
12. `break/continue/jump` 是否合法。
|
||
13. Path 是否为空或点名重复。
|
||
14. Operation 是否引用不存在的 Path。
|
||
15. 目标点是否可达。
|
||
16. 关节是否超限。
|
||
17. 后处理目标品牌是否支持所用语义。
|
||
|
||
输入：
|
||
|
||
1. AST。
|
||
2. Symbol Table。
|
||
3. `RobotHandle`。
|
||
4. KDL 检查结果。
|
||
|
||
输出：
|
||
|
||
1. Executable IR。
|
||
2. KDL request。
|
||
3. `CycleTimeResult`。
|
||
4. `MotionDiagnostic`。
|
||
|
||
验收重点：
|
||
|
||
1. 完整 GRL 示例可编译为 IR。
|
||
2. IR 运动指令可映射到 KDL request。
|
||
3. source map 能定位 GRL 行列、path point、operation。
|
||
4. `estimateCycleTime` 只计算运动时间。
|
||
5. `resampleTrajectory` 时间和点序稳定。
|
||
6. 所有错误返回结构化诊断。
|
||
|
||
## 11. 阶段 9：三品牌后处理原型
|
||
|
||
关联任务：`KW-111`
|
||
|
||
目标：
|
||
|
||
1. ABB RAPID 后处理。
|
||
2. FANUC LS/TP 风格后处理。
|
||
3. KUKA KRL 后处理。
|
||
4. 支持 `post_hint` 和 `@brand.*`。
|
||
5. 生成后处理转换报告。
|
||
|
||
输入：
|
||
|
||
1. Executable IR。
|
||
2. target/tool/frame/speed/zone 数据。
|
||
3. post profile。
|
||
4. brand metadata。
|
||
|
||
输出：
|
||
|
||
1. ABB RAPID 程序。
|
||
2. FANUC LS/TP 风格文本。
|
||
3. KUKA KRL 程序。
|
||
4. 转换报告。
|
||
|
||
验收重点：
|
||
|
||
1. `movej/movel/movec` 三品牌 golden file 通过。
|
||
2. target/tool/frame/speed/zone 映射正确。
|
||
3. IO/wait 基础映射正确。
|
||
4. `post_hint` 和 `@brand.*` 只影响指定品牌。
|
||
5. 不支持语义进入转换报告，不能静默丢失。
|
||
|
||
## 12. 阶段 10：自动生成、往返和性能优化
|
||
|
||
关联任务：`KW-112`、`KW-013`
|
||
|
||
目标：
|
||
|
||
1. 自动生成 GRL 时优先生成 target/path/operation。
|
||
2. 点名稳定。
|
||
3. path defaults 和单点 override 稳定。
|
||
4. source metadata 稳定。
|
||
5. 支持 compact/expanded 输出风格。
|
||
6. 生成 GRL 可再解析回等价对象。
|
||
7. KDL 底层导出稳定 C ABI。
|
||
8. 高频 FK/IK 增加 TypedArray 版本。
|
||
9. RobotHandle 缓存 FK、IK、Jacobian solver。
|
||
10. 长路径分块计算或提供进度。
|
||
|
||
输入：
|
||
|
||
1. 自动编程对象。
|
||
2. Path/Operation 数据。
|
||
3. KDL 批量计算输入。
|
||
|
||
输出：
|
||
|
||
1. 稳定 GRL 文本。
|
||
2. 可回读 AST/IR。
|
||
3. C ABI / Embind API。
|
||
4. TypedArray 批量接口。
|
||
5. 性能报告。
|
||
|
||
验收重点：
|
||
|
||
1. 同一输入重复生成结果一致。
|
||
2. 生成文本可 diff。
|
||
3. 生成文本可解析、语义检查并后处理。
|
||
4. 单机器人 6 轴初始化小于 1 秒。
|
||
5. 单次 FK 小于 1 ms。
|
||
6. 单次 IK 平均小于 10 ms。
|
||
7. 1000 个目标点批量可达性检查在可接受交互时间内完成。
|
||
8. 10 秒轨迹按 4 ms 采样约 2500 点可稳定生成和回放。
|
||
|
||
## 13. 推荐集成顺序
|
||
|
||
```text
|
||
1. KW-001 + KW-100 + KW-101
|
||
基础工程、Worker RPC、Lexer/Parser 骨架。
|
||
|
||
2. KW-002 + KW-102
|
||
URDF/标准模型和 GRL target/tool/frame/speed/zone。
|
||
|
||
3. KW-003 到 KW-006 + KW-103
|
||
运动指令编译到 KDL FK/IK/变换。
|
||
|
||
4. KW-007 到 KW-010
|
||
梯形速度、MOVEJ、MOVEL、MOVEC。
|
||
|
||
5. KW-104 + KW-011
|
||
Path 编译为 PathPlanRequest，KDL 生成整条路径。
|
||
|
||
6. KW-105 + KW-011
|
||
Operation 展开后复用 Path 规划。
|
||
|
||
7. KW-106 到 KW-110
|
||
完成 P0 语义检查和 IR。
|
||
|
||
8. KW-111
|
||
三品牌后处理原型。
|
||
|
||
9. KW-112 + KW-013
|
||
自动生成、往返、性能和批量优化。
|
||
```
|
||
|
||
## 14. 常用验证命令
|
||
|
||
实际命令以工程 `package.json` 和 CMake 配置为准。每个阶段至少应提供等效命令：
|
||
|
||
```bash
|
||
npm run typecheck
|
||
npm run test -- grl
|
||
npm run test -- kdl
|
||
npm run test -- integration
|
||
npm run test -- post
|
||
npm run build
|
||
```
|
||
|
||
KDL WASM 构建：
|
||
|
||
```bash
|
||
cd /home/meswork/kdl_work
|
||
emcmake cmake -S kdl-wasm -B kdl-wasm/build-wasm \
|
||
-DCMAKE_BUILD_TYPE=Release \
|
||
-DKDL_SOURCE_DIR=/home/meswork/kdl_work/orocos_kinematics_dynamics/orocos_kdl
|
||
cmake --build kdl-wasm/build-wasm -j16
|
||
```
|
||
|
||
## 15. 阅读建议
|
||
|
||
1. 先读本文，理解项目主要阶段和集成顺序。
|
||
2. 再读 `通用机器人项目功能与数据流程图.md`，理解功能流和数据流。
|
||
3. 需要接口细节时读 `KDL_WASM计算接口设计.md`。
|
||
4. 需要语言语法和后处理细节时读 `通用机器人编程语法规范.md`。
|
||
5. 需要执行级任务和证据时读 `/home/meswork/kdl_work/work/working1` 下的实施文档。
|