wangdequan/KDL_WORK

Fork 0

Files

wangdequan fe13b081e3 Initial working1 implementation docs

2026-06-27 07:26:48 -04:00

13 KiB

Raw Blame History

01-项目功能内容

版本：0.3
日期：2026-06-27
对标文档：

/home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md
/home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md

1. 项目定位

本目录用于把 GRL 编程语法规范和 KDL WASM 计算接口设计落成实施计划。实施目标是形成一套互相闭合的语言层和运动计算层：

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 是用于离线编程和虚拟调试的通用机器人程序语言，必须满足：

支持目标点、路径、工艺、IO、等待、流程控制、报警、仿真执行、报告和后处理。
可由规划点、CAD 曲线、工艺模板或 AI 规划器自动生成程序。
可转换为 ABB RAPID、FANUC LS/TP 风格文本、KUKA KRL。
可反向导入品牌程序，恢复为统一 IR、GRL 和 OLP 对象模型。
程序文本稳定、可读、可 diff。
编译后生成统一可执行 IR，虚拟控制器不依赖品牌控制器细节。

2.2 语法必须覆盖

文件工程结构：
- 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
词法：
- UTF-8。
- 小写关键字。
- 大小写敏感标识符。
- snake_case 推荐。
- 单行和多行注释。
- 带单位数值。
- 保留关键字表。
顶层结构：
- language grl 0.1
- module
- import
- persistent/const/var
- target
- path
- operation
- proc
- func
- trap
- task
- post_hint
类型系统：
- 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
数据声明：
- tool
- frame
- joint_target
- pose_target
- pose
- poseq
- robot_config
- 偏移表达式 offset、offset_in
速度和过渡：
- joint(percent)
- joint(angle/s)
- linear(length/s)
- angular(angle/s)
- 可选 acc
- fine
- z(distance)
- cnt(percent)
- continuous
运动指令：
- 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
Path：
- path
- defaults
- source
- point
- event before/after/at
- run_path
Operation：
- operation
- kind
- path
- process
- start_action
- end_action
- run_operation
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
流程控制：
- if/elseif/else
- while
- for
- switch/case/default
- break
- continue
- label
- jump
子程序和函数：
- proc
- func
- call
- return
- 参数方向 in/out/inout
- 作用域和名称解析。
异常、报警和中断：
- alarm
- raise
- try/catch/finally
- trap
- interrupt
- enable/disable interrupt
多任务语法：
- task ... cycle ...
- 首版只定义语法，不要求完整实时调度。
品牌扩展：
- post_hint abb/fanuc/kuka
- @brand.abb
- @brand.fanuc
- @brand.kuka
- 无法支持的品牌扩展必须进入转换报告。

2.3 GRL P0

按语法规范第 24 章，P0 必须实现：

language、module、proc。
const、var、persistent。
tool、frame、speed、zone。
joint_target、pose_target。
movej、movel、movec。
path、point、event、run_path。
operation、run_operation。
if、elseif、else、while、for、switch。
call、return、break、continue。
proc 参数方向 in/out/inout。
func、函数调用表达式和返回值检查。
io.do/di、wait、pulse。
AST、语义检查、IR、source map。
ABB、FANUC、KUKA 后处理原型。

2.4 GRL P1

按语法规范第 24 章，P1 扩展：

label/jump 和品牌标签程序导入。
trap、interrupt。
多任务 task。
更完整的 IO 类型。
工艺模板库。
品牌程序导入。
复杂品牌扩展和转换报告。

3. KDL WASM 功能范围

3.1 目标

KDL WASM 是 GRL、虚拟控制器、离线编程、路径验证和轨迹回放共用的运动学与轨迹计算内核。接口设计从 GRL 语义反推，不直接暴露 KDL C++ 类。

KDL WASM 负责：

joint_target、pose_target 的目标点解析和可达性验证。
tool、frame、offset、offset_in 的位姿变换。
movej 关节角度差分运行。
movel TCP 直线运行。
movec TCP 圆弧运行。
path、run_path、operation 的批量轨迹生成和批量诊断。
速度、加速度、zone、采样周期、节拍估算。
当前 TCP、当前关节、轨迹采样点、报警诊断。

KDL WASM 不负责：

GRL 词法和语法解析。
程序流程控制、变量、IO、wait、子程序调用。
碰撞检测和几何布尔运算。
真实品牌控制器完整 look-ahead 和伺服细节。
OPFS 项目文件管理。

3.2 顶层 TypeScript API

必须实现 KdlWasmApi 中的异步接口：

生命周期：
- init
- dispose
机器人模型：
- loadRobotFromUrdf
- createRobotFromModel
- destroyRobot
- getRobotInfo
- getJointLimits
位姿变换：
- normalizePose
- composePose
- inversePose
- applyToolAndFrame
- applyOffset
运动学：
- fk
- fkAllLinks
- jacobian
- ik
- ikBatch
检查：
- checkJointLimits
- checkVelocityLimits
- checkSingularity
- checkReachability
- checkReachabilityBatch
梯形速度：
- makeTrapProfile
- sampleTrapProfile
轨迹规划：
- planMoveJ
- planMoveL
- planMoveC
- planPath
- validatePath
- estimateCycleTime
- resampleTrajectory

3.3 KDL P0

按 KDL WASM 接口设计第 22 章，P0 必须暴露：

init
loadRobotFromUrdf
createRobotFromModel
destroyRobot
getRobotInfo
getJointLimits
normalizePose
composePose
inversePose
applyOffset
applyToolAndFrame
fk
fkAllLinks
jacobian
ik
ikBatch
checkJointLimits
checkSingularity
checkReachability
checkReachabilityBatch
makeTrapProfile
sampleTrapProfile
planMoveJ
planMoveL
planMoveC
planPath
validatePath
estimateCycleTime
resampleTrajectory

3.4 KDL P1

按 KDL WASM 接口设计第 22 章，P1 扩展：

planBlendPath
planMoveSpline
checkCollisionInputPoses，只提供 link poses，不做碰撞本身。
optimizeSeedSequence
compareTrajectory
外部轴协调相关函数。

4. 共享数据和单位

4.1 单位

GRL 编译器内部必须统一：

物理量	内部单位
长度	meter
角度	radian
时间	second
质量	kilogram
线速度	meter/second
角速度	radian/second
加速度	meter/second^2 或 radian/second^2

4.2 位姿

内部统一为：

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 目标点

必须统一到：

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 速度和过渡必须编译为：

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 语义诊断至少覆盖：

未定义符号。
重复声明。
类型不匹配。
单位错误。
目标点类型不适合运动指令。
movec 缺 via 或三点退化。
工具、坐标系、速度、zone 不可解析。
IO 地址非法。
参数数量、类型、方向错误。
func 返回路径错误或包含非法副作用。
break/continue/jump 位置非法。
Path 为空或点名重复。
Operation 引用不存在的 Path。
后处理品牌不支持所用语义。

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：

if/elseif/else
while/for/switch
proc/func/call/return
io.do/di/ai/ao
wait/pulse/timer
alarm/raise/try/catch
operation.process

6. 验收口径

6.1 GRL P0 验收

EBNF 覆盖语法规范第 22 章。
语法规范第 23 章完整示例可解析。
AST 保留 source range、单位原文、规范化值和品牌 metadata。
语义检查覆盖语法规范第 21 章全部检查项。
path 可编译为 PathPlanRequest。
operation 可展开为 start action、path、end action。
movej/movel/movec 可编译为对应 KDL request。
ABB、FANUC、KUKA 后处理原型有 golden file。

6.2 KDL P0 验收

P0 29 个函数全部在 TypeScript API 和 Worker RPC 中可调用。
URDF 到 KDL Chain joint 顺序稳定。
FK 与 golden 或原生 KDL 结果对比在容差内。
IK 后 FK 回代误差小于容差。
Jacobian 尺寸和奇异性指标正确。
梯形速度曲线长距离/短距离测试通过。
planMoveJ 关节同起同停。
planMoveL TCP 直线误差小于容差。
planMoveC 圆心、半径、弧长、圆弧误差正确，共线返回 KDL_ARC_DEGENERATE。
planPath/validatePath 保留 segment、target 和 source map。
错误处理不抛裸字符串，返回结构化 KdlError 或 MotionDiagnostic。

6.3 集成验收

GRL movej/movel/movec 编译为 KDL request 并生成轨迹。
GRL path 编译为 PathPlanRequest 并生成整条路径。
run_operation 展开后 KDL 只处理 motion segment。
if/for/switch/call/wait/io 不直接调用 KDL，但能影响虚拟控制器何时调用运动函数。
长路径批量验证有性能记录。
Worker 初始化、崩溃恢复和取消请求测试通过。

13 KiB Raw Blame History Unescape Escape