Upload project files
This commit is contained in:
wangdequan
405
working1/01-项目功能内容.md
Normal file
405
working1/01-项目功能内容.md
Normal file
@@ -0,0 +1,405 @@
|
||||
# 01-项目功能内容
|
||||
|
||||
版本：0.1
|
||||
日期：2026-06-27
|
||||
|
||||
## 1. 总体需求
|
||||
|
||||
以 ABB IRB120 3/58 的 URDF fixture 为真实 6 轴工业机器人基准，构建一套端到端全面测试能力：
|
||||
|
||||
1. 编写通用机器人语言 GRL 测试程序，覆盖运动、路径、IO、等待、工艺、报警和异常。
|
||||
2. 在项目运行时加载 ABB120 URDF，执行 FK、IK、Jacobian、限位、轨迹规划、虚拟控制器运行和调试。
|
||||
3. 将同一 GRL/IR 输出为 ABB RAPID、FANUC LS 风格和 KUKA KRL 风格程序，并生成转换报告。
|
||||
4. 建立离线编程全面测试，包括资源建模、路径生成、可达性、节拍、碰撞、IO/Wait、品牌导入导出、报告和客户交付包。
|
||||
5. 用 HTML 实现本项目虚拟控制器界面，对标 ABB RobotStudio 的 Station、Controller、RAPID、Simulation、Virtual FlexPendant 等工作流。
|
||||
6. 补齐 GRL 运算表达式能力，覆盖 ABB、FANUC、KUKA 三类机器人语言共同具备的算术、比较、逻辑和常用数学函数，并能在运动参数编译期求值。
|
||||
|
||||
## 2. ABB120 URDF 基准
|
||||
|
||||
基准机器人来自 `/home/meswork/kdl_work/kdl-wasm/web/tests/fixtures/abbIrb120.ts` 中的 `ABB_IRB120_3_58_URDF`。
|
||||
|
||||
| 项 | 值 |
|
||||
| --- | --- |
|
||||
| robotId | `abb_irb120_3_58` |
|
||||
| baseLink | `base_link` |
|
||||
| tipLink | `tool0` |
|
||||
| DOF | 6 |
|
||||
| active joints | `joint_1` 到 `joint_6` |
|
||||
| fixed links | `base`、`flange`、`tool0` |
|
||||
| URDF 来源 | ROS-Industrial ABB IRB120 3/58 xacro 派生，当前 fixture 省略 mesh、material、inertial、xacro-only 元素 |
|
||||
|
||||
关节限位以 fixture 为准：
|
||||
|
||||
| 关节 | lower rad | upper rad | velocity rad/s |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| `joint_1` | -2.87979 | 2.87979 | 4.36332 |
|
||||
| `joint_2` | -1.91986 | 1.91986 | 4.36332 |
|
||||
| `joint_3` | -1.91986 | 1.22173 | 4.36332 |
|
||||
| `joint_4` | -2.79253 | 2.79253 | 5.58505 |
|
||||
| `joint_5` | -2.094395 | 2.094395 | 5.58505 |
|
||||
| `joint_6` | -6.98132 | 6.98132 | 7.33038 |
|
||||
|
||||
标准测试关节位：
|
||||
|
||||
| 名称 | rad |
|
||||
| --- | --- |
|
||||
| `home` | `[0, 0, 0, 0, 0, 0]` |
|
||||
| `pick` | `[0.2, -0.35, 0.45, 0.1, -0.2, 0.3]` |
|
||||
| `place` | `[-0.35, -0.25, 0.35, -0.25, 0.15, -0.4]` |
|
||||
| `approach` | `[0, -0.4, 0.5, 0, 0.2, 0]` |
|
||||
|
||||
## 3. 通用机器人测试程序集
|
||||
|
||||
测试程序以 GRL 为主，命名建议为 `A120_XX_*.grl`。所有程序必须能解析为 AST、编译为 Semantic IR、进入 KDL bridge，并保留 source map。
|
||||
|
||||
### 3.1 `A120_00_Smoke.grl`
|
||||
|
||||
目标：最小链路冒烟测试。
|
||||
|
||||
覆盖点：
|
||||
|
||||
1. 语言头、module、speed、zone、target。
|
||||
2. `movej home`。
|
||||
3. FK、限位检查、轨迹规划和 ABB 后处理。
|
||||
|
||||
验收：程序运行完成，无 error diagnostic；ABB/FANUC/KUKA 输出均非空。
|
||||
|
||||
### 3.2 `A120_10_JointPickPlace.grl`
|
||||
|
||||
目标：关节空间 pick/place 主流程。
|
||||
|
||||
基准程序：
|
||||
|
||||
```grl
|
||||
language grl 0.1
|
||||
module A120JointPickPlace
|
||||
const speed v_fast = joint(40 %)
|
||||
const speed v_slow = joint(20 %)
|
||||
const zone z10 = z(10 mm)
|
||||
|
||||
target home = joint_target { joints: [0 deg, 0 deg, 0 deg, 0 deg, 0 deg, 0 deg] }
|
||||
target approach = joint_target { joints: [0 deg, -22.918312 deg, 28.647890 deg, 0 deg, 11.459156 deg, 0 deg] }
|
||||
target pick = joint_target { joints: [11.459156 deg, -20.053523 deg, 25.783101 deg, 5.729578 deg, -11.459156 deg, 17.188734 deg] }
|
||||
target place = joint_target { joints: [-20.053523 deg, -14.323945 deg, 20.053523 deg, -14.323945 deg, 8.594367 deg, -22.918312 deg] }
|
||||
|
||||
path pick_place {
|
||||
defaults { speed: v_fast, zone: z10 }
|
||||
point p_home movej home zone fine
|
||||
point p_approach movej approach
|
||||
event before p_pick io.do[1] = true
|
||||
point p_pick movej pick speed v_slow zone fine
|
||||
point p_place movej place
|
||||
event after p_place io.do[1] = false
|
||||
}
|
||||
|
||||
proc main()
|
||||
run_path pick_place
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
验收：`planPath` 产生 4 段 MOVEJ，终点关节等于 `place`，IO 事件进入 trace。
|
||||
|
||||
### 3.3 `A120_20_CartesianBlend.grl`
|
||||
|
||||
目标：笛卡尔运动和 blend 规则测试。
|
||||
|
||||
覆盖点：
|
||||
|
||||
1. 由 `home/pick/place` FK 自动生成 reachable pose targets。
|
||||
2. `movel` 接近点、工件点和离开点。
|
||||
3. `movec` 中间点和终点。
|
||||
4. `zone fine` 与 `z(10 mm)` 对比。
|
||||
|
||||
验收：每个 pose target 通过 IK；笛卡尔段输出最大 TCP 直线误差和圆弧误差。
|
||||
|
||||
### 3.4 `A120_30_IOWaitPulse.grl`
|
||||
|
||||
目标：IO、等待、脉冲和 timeout。
|
||||
|
||||
覆盖点：
|
||||
|
||||
1. `io.do[n] = true/false`。
|
||||
2. `wait io.di[n] == true timeout 2 s`。
|
||||
3. `pulse io.do[n] duration 100 ms`。
|
||||
4. timeout 后 alarm 或 fallback path。
|
||||
5. IO script 驱动 DI 上升沿、下降沿和 changed。
|
||||
|
||||
验收：虚拟控制器可显示 wait 表达式、已等待时间、剩余 timeout、相关 IO 最近变化和脚本状态。
|
||||
|
||||
### 3.5 `A120_40_ErrorDiagnostics.grl`
|
||||
|
||||
目标：故障路径和诊断稳定性。
|
||||
|
||||
覆盖点：
|
||||
|
||||
1. 超出关节限位目标。
|
||||
2. 明确不可达 pose target。
|
||||
3. 奇异姿态或接近奇异姿态。
|
||||
4. 未定义 target/path/operation。
|
||||
5. wait timeout。
|
||||
|
||||
验收：每类故障都有稳定 code、severity、source map 和报告条目。
|
||||
|
||||
### 3.6 `A120_50_OperationProcess.grl`
|
||||
|
||||
目标：工艺 operation 和离线编程对象闭环。
|
||||
|
||||
覆盖点：
|
||||
|
||||
1. `path`、`operation`、`run_operation`。
|
||||
2. start/end action，如夹爪、吹气、扫码、视觉等待。
|
||||
3. 工艺参数进入报告和交付包。
|
||||
4. OLP 对象模型可反向生成 GRL。
|
||||
|
||||
验收：`operation` 展开为 action + path + action，报告包含工艺步骤、节拍和 IO 事件。
|
||||
|
||||
## 4. GRL 运算功能需求
|
||||
|
||||
目标：将“运算功能”作为 GRL 语言和语义基础能力补齐，而不是只让 parser 能读。首版按 ABB RAPID、FANUC LS/KAREL、KUKA KRL 的公共数学子集建模，保证同一 GRL 程序可以稳定编译到统一 IR，再由后处理器输出三品牌程序。
|
||||
|
||||
### 4.1 语法范围
|
||||
|
||||
GRL 表达式必须支持：
|
||||
|
||||
1. 算术：一元 `+`、一元 `-`、`+`、`-`、`*`、`/`、`mod`。
|
||||
2. 比较：`==`、`!=`、`<`、`<=`、`>`、`>=`。
|
||||
3. 逻辑：`and`、`or`、`not`，可兼容 `&&`、`||`、`!` 作为输入别名，IR 中统一为 GRL 关键字。
|
||||
4. 括号：`(...)` 明确优先级。
|
||||
5. 函数调用：沿用当前 `callee(args...)` 形式。
|
||||
6. 现有结构表达式：array、object、call、identifier、offset 表达式必须继续兼容。
|
||||
|
||||
优先级从高到低：
|
||||
|
||||
| 层级 | 运算 |
|
||||
| --- | --- |
|
||||
| 1 | 函数调用、对象、数组、括号、offset |
|
||||
| 2 | 一元 `+`、`-`、`not`、`!` |
|
||||
| 3 | `*`、`/`、`mod` |
|
||||
| 4 | `+`、`-` |
|
||||
| 5 | `<`、`<=`、`>`、`>=` |
|
||||
| 6 | `==`、`!=` |
|
||||
| 7 | `and`、`&&` |
|
||||
| 8 | `or`、`||` |
|
||||
|
||||
### 4.2 函数和常量
|
||||
|
||||
首版内置常量：
|
||||
|
||||
| 名称 | 含义 |
|
||||
| --- | --- |
|
||||
| `pi` | 圆周率 |
|
||||
| `e` | 自然常数 |
|
||||
|
||||
首版内置函数：
|
||||
|
||||
| 类别 | 函数 |
|
||||
| --- | --- |
|
||||
| 三角函数 | `sin`、`cos`、`tan`、`asin`、`acos`、`atan`、`atan2` |
|
||||
| 数值函数 | `sqrt`、`abs`、`pow`、`min`、`max`、`clamp`、`floor`、`ceil`、`round` |
|
||||
|
||||
三角函数语义：
|
||||
|
||||
1. `sin/cos/tan` 接收角度量；带 `deg` 或 `rad` 单位时归一化为弧度，纯数按弧度处理。
|
||||
2. `asin/acos/atan/atan2` 返回角度量；在 `pose(...)` 姿态项或 `joint_target.joints` 等角度上下文中可直接使用。
|
||||
3. 函数必须做定义域检查，例如 `sqrt(-1)`、`acos(2)` 必须产生 diagnostic。
|
||||
|
||||
### 4.3 编译期求值位置
|
||||
|
||||
常量表达式必须在编译阶段求值，并把结果写入 Semantic IR / KDL request，而不是把表达式字符串传到运动规划层。
|
||||
|
||||
必须支持的求值位置：
|
||||
|
||||
1. 数据声明 initializer：`const`、`persistent`、需要静态初值的 `var`。
|
||||
2. `speed`：`linear(...)`、`joint(...)`、`acc ...` 参数。
|
||||
3. `zone`：`fine`、`z(...)`、`cnt(...)`。
|
||||
4. `pose(...)`、`poseq(...)`、`robot_config(...)`。
|
||||
5. `joint_target { joints: [...] }`。
|
||||
6. `pose_target { pose: ... }`。
|
||||
7. `tool { tcp: ..., mass: ... }`。
|
||||
8. `frame { origin: ... }`。
|
||||
9. path defaults/source 属性。
|
||||
10. path point 内联 `speed`、`zone`、`tool`、`frame`、`via`、`target` 参数。
|
||||
11. path event 的 `distance`。
|
||||
12. `wait ... timeout ...` 和 `pulse ... duration ...` 中的时间常量。
|
||||
13. operation process 中需要数值常量的工艺参数。
|
||||
|
||||
比较和逻辑表达式也必须进入 AST。纯常量比较/逻辑可在编译期折叠；依赖 IO、变量或运行态状态的条件先保留为结构化控制表达式，供虚拟控制器和后续品牌映射使用。
|
||||
|
||||
### 4.4 单位和数值语义
|
||||
|
||||
数值求值采用统一 SI 归一化：
|
||||
|
||||
| GRL 输入 | IR/KDL 归一化 |
|
||||
| --- | --- |
|
||||
| `mm` | m |
|
||||
| `mm/s` | m/s |
|
||||
| `mm/s2` | m/s2 |
|
||||
| `deg` | rad |
|
||||
| `rad` | rad |
|
||||
| `%` | 0 到 1 的比例 |
|
||||
| `s` | s |
|
||||
| `ms` | s |
|
||||
| `kg` | kg |
|
||||
|
||||
规则：
|
||||
|
||||
1. 同维度数值可以相加、相减，结果保留该维度并归一化。
|
||||
2. 纯数可以参与乘除；维度乘除首版只允许编译器明确支持的上下文，避免产生复杂复合单位。
|
||||
3. 不同维度相加或比较必须报错，例如 `10 mm + 2 s`。
|
||||
4. 构造器可以提供默认上下文单位：`linear(...)` 默认 `mm/s`，`z(...)` 默认 `mm`，`pose(...)` 前三项默认 `mm`、后三项默认 `deg`，`joint_target.joints` 默认 `deg`，`duration/timeout` 默认 `s`。
|
||||
5. 因此 `linear(100 + 50 mm/s)` 在 `linear` 速度上下文中等价于 `linear(150 mm/s)`；推荐生成器输出时使用显式单位，减少人工歧义。
|
||||
|
||||
### 4.5 示例
|
||||
|
||||
```grl
|
||||
language grl 0.1
|
||||
module MathMotion
|
||||
const num blend_base = 5 + 5
|
||||
const speed v_pick = linear(100 + 50 mm/s)
|
||||
const speed v_safe = linear(max(50 mm/s, 200 mm/s / 2))
|
||||
const zone z_app = z(clamp(blend_base mm, 1 mm, 50 mm))
|
||||
|
||||
target home = joint_target {
|
||||
joints: [0 deg, (10 + 5) deg, -90 deg, 0 deg, 0 deg, 0 deg]
|
||||
}
|
||||
target pick = pose_target {
|
||||
pose: pose(400 + 50 mm, 20 * 2 mm, sqrt(90000) mm, 0 deg, 0 deg, atan2(1, 1))
|
||||
}
|
||||
|
||||
path main_path {
|
||||
defaults { speed: v_pick, zone: z_app }
|
||||
point p0 movej home speed linear(100 + 50 mm/s) zone z(clamp(8 mm, 1 mm, 20 mm))
|
||||
point p1 movel pick
|
||||
}
|
||||
end
|
||||
```
|
||||
|
||||
编译期结果要求：
|
||||
|
||||
1. `v_pick` 进入 IR 后为 `linear`，速度 `0.15 m/s`。
|
||||
2. `z_app` 进入 IR 后为 `distance`，距离 `0.01 m`。
|
||||
3. `home.joints[1]` 进入 IR 后为 `15 deg` 对应的弧度值。
|
||||
4. `pick.pose.position[0]` 进入 IR 后为 `0.45 m`。
|
||||
5. path point 内联 speed/zone 同样求值后进入 KDL request。
|
||||
|
||||
### 4.6 诊断需求
|
||||
|
||||
运算功能必须输出稳定 diagnostic：
|
||||
|
||||
| code | 场景 |
|
||||
| --- | --- |
|
||||
| `GRL_EXPR_PARSE` | 表达式语法错误或括号不匹配。 |
|
||||
| `GRL_EXPR_UNKNOWN_SYMBOL` | 常量求值遇到未知标识符。 |
|
||||
| `GRL_EXPR_UNKNOWN_FUNCTION` | 未知函数。 |
|
||||
| `GRL_EXPR_ARITY` | 函数参数数量错误。 |
|
||||
| `GRL_EXPR_DOMAIN` | 数学定义域错误。 |
|
||||
| `GRL_EXPR_DIV_ZERO` | 除零。 |
|
||||
| `GRL_EXPR_UNIT_MISMATCH` | 单位维度不兼容。 |
|
||||
| `GRL_EXPR_NON_CONSTANT` | 需要常量的位置出现运行时表达式。 |
|
||||
| `GRL_EXPR_UNSUPPORTED_RUNTIME` | 后续品牌映射暂不支持的复杂运行时表达式。 |
|
||||
|
||||
每个 diagnostic 必须包含 severity、message、source range，并能通过 source map 定位到 GRL 源文件行列。
|
||||
|
||||
### 4.7 跨品牌边界
|
||||
|
||||
首版跨品牌输出不直接翻译复杂表达式字符串，而是优先输出编译期折叠后的常量：
|
||||
|
||||
1. `linear(100 + 50 mm/s)` 输出为各品牌可表达的具体速度值。
|
||||
2. `z(clamp(...))` 输出为具体 ABB zone、FANUC CNT 或 KUKA 近似 blend。
|
||||
3. runtime 条件表达式如果后处理器无法保真映射，必须进入转换报告，不得静默丢失。
|
||||
4. 品牌专用数学函数或控制器变量不作为首版目标，后续通过 post/import report 增量支持。
|
||||
|
||||
## 5. 程序运行需求
|
||||
|
||||
运行器必须支持以下流程：
|
||||
|
||||
1. 加载 ABB120 URDF fixture，生成 `NormalizedRobotModel` 和 RobotHandle。
|
||||
2. 编译 GRL：Lexer、Parser、Semantic Analyzer、IR、source map。
|
||||
3. 对每个 target/path/operation 生成 KDL request。
|
||||
4. 执行 KDL：FK、fkAllLinks、Jacobian、IK、limit、singularity、planMoveJ、planMoveL、planMoveC、planPath、validatePath。
|
||||
5. 执行虚拟控制器：load、run、pause、step、stop、reset、breakpoint、motion queue、IO、wait、pulse、trace。
|
||||
6. 输出结构化 job：`job_id`、输入文件、运行参数、诊断、轨迹、trace、报告、截图路径。
|
||||
|
||||
## 6. 跨品牌程序转换需求
|
||||
|
||||
同一 Semantic IR 必须输出：
|
||||
|
||||
| 品牌 | 输出文件 | 核心指令 |
|
||||
| --- | --- | --- |
|
||||
| ABB | `.mod` | `MoveJ`、`MoveL`、`MoveC`、`SetDO`、`WaitUntil`、`PulseDO` |
|
||||
| FANUC | `.ls` | `J`、`L`、`C`、`DO[]`、`WAIT`、`PULSE` |
|
||||
| KUKA | `.src`，必要时 `.dat` | `PTP`、`LIN`、`CIRC`、`$OUT[]`、`WAIT FOR` |
|
||||
|
||||
转换报告必须记录：
|
||||
|
||||
1. 速度、zone、tool、frame 映射。
|
||||
2. 近似语义，如 ABB zone 到 FANUC CNT、KUKA C_DIS。
|
||||
3. 不支持语义，如复杂 trap、多任务、品牌专用工艺包。
|
||||
4. source map：GRL 行列、path point、operation、品牌输出行号。
|
||||
5. 回读校验：品牌文本重新导入后，target/path/motion 顺序与原 IR 等价或输出差异报告。
|
||||
|
||||
## 7. 离线编程全面测试需求
|
||||
|
||||
全面测试必须覆盖：
|
||||
|
||||
1. 项目建模：Station、Robot、Tool、Frame、Target、Path、Operation、Program、Report。
|
||||
2. 工作区：OPFS-like 保存、bundle 导入导出、损坏检测、迁移。
|
||||
3. 几何和路径：点、边、曲线生成 Path；路径采样和姿态策略。
|
||||
4. 可达性：单点、批量、路径段、operation。
|
||||
5. 轨迹：节拍、速度、加速度、采样、重采样、blend 近似。
|
||||
6. 碰撞：机器人自身、工具、工件、夹具、禁入区的基础碰撞时间点。
|
||||
7. IO/Wait：脚本、timeout、边沿、trace、报告。
|
||||
8. 品牌链路：GRL 到三品牌、三品牌导入、交叉品牌再导出。
|
||||
9. 客户交付：源程序、品牌程序、IO map、校准数据、报告 HTML/PDF、trace、截图。
|
||||
10. 自动化证据：命令输出、job JSON、report JSON、HTML 页面、截图、PDF。
|
||||
|
||||
## 8. HTML 虚拟控制器需求
|
||||
|
||||
### 8.1 对标范围
|
||||
|
||||
对标 ABB RobotStudio 的工作方式，而不是复制视觉资产。公开参考资料包括 ABB RobotStudio Suite 官方页面和 RobotStudio Operating Manual 2026.2。参考点：
|
||||
|
||||
1. Station / Graphics：机器人、工具、工件、路径和碰撞对象。
|
||||
2. Controller：虚拟控制器状态、RobotWare/robot model 信息、权限和运行控制。
|
||||
3. RAPID / Program Editor：程序树、模块、当前行、诊断、断点。
|
||||
4. Simulation：播放、暂停、单步、重置、速度倍率、时间轴。
|
||||
5. Virtual FlexPendant：模式、Motors On、PP to Main、Start、Stop、Hold、Jog、IO、Alarms。
|
||||
|
||||
### 8.2 页面信息架构
|
||||
|
||||
首屏必须直接进入工程工作台，不做营销页。
|
||||
|
||||
建议 HTML 布局：
|
||||
|
||||
1. 顶部命令栏：项目、导入、保存、运行、暂停、停止、单步、导出报告。
|
||||
2. 左侧对象树：Station、Robot、Tool、Frame、Target、Path、Operation、Program、Reports。
|
||||
3. 中央工作区：3D/2D station viewport、路径轨迹、机器人姿态、碰撞和选中对象。
|
||||
4. 右侧虚拟示教器：状态灯、模式、关节/TCP、Jog、速度倍率、程序指针、报警。
|
||||
5. 底部面板：日志、诊断、IO、Wait、Motion Queue、Trace、报告。
|
||||
6. 编辑区：GRL/RAPID/FANUC/KUKA 多标签查看，source map 双向定位。
|
||||
|
||||
### 8.3 交互需求
|
||||
|
||||
1. 加载 ABB120 测试项目后，页面显示机器人模型、程序树和默认 `main` 程序。
|
||||
2. 点击 Run 后，虚拟控制器状态变化，程序指针、motion queue、IO trace 和时间轴同步更新。
|
||||
3. 点击 Step 时执行单条 IR 指令。
|
||||
4. 点击 path point 时，编辑器跳转 GRL source map，3D/2D viewport 高亮目标。
|
||||
5. wait 卡住时，右侧面板显示 wait 条件、当前子表达式值、相关 IO 最近变化、timeout 倒计时和手动置位动作。
|
||||
6. 后处理导出后，ABB/FANUC/KUKA 代码可在标签页查看并下载。
|
||||
7. 报告页可打开 HTML 报告，并能导出 PDF 或打印。
|
||||
|
||||
### 8.4 技术边界
|
||||
|
||||
1. 首版可以是 HTML + CSS + TypeScript 的静态工作台页面，接入现有 facade 和 runtime。
|
||||
2. 3D 视图可先使用简化连杆模型；如果引入 Three.js，应验证桌面和移动视口截图非空、机器人正确入框。
|
||||
3. 不承诺复刻 ABB RobotStudio 的真实 RobotWare、完整 RAPID 解释器、真实安全系统、真实控制器通信。
|
||||
4. 不复制 ABB 商标、图标、界面皮肤或专有资源。
|
||||
|
||||
## 9. 非目标
|
||||
|
||||
1. 不以 FANUC 二进制 TP 为首版输入。
|
||||
2. 不实现完整 CAD kernel。
|
||||
3. 不实现品牌控制器 look-ahead 完全复刻。
|
||||
4. 不将浏览器虚拟控制器声明为真实机器人安全控制器。
|
||||
5. 不绕过 ABB、FANUC、KUKA 的真实控制器安全、权限和认证流程。
|
||||
Reference in New Issue
Block a user