Skip to content

[Wayfinder] 机械臂、导轨与 Deck 设备点位资产模型 #214

Description

@TablewareBox

Outcome

冻结一套可移植、可调试、可版本化的点位资产模型,使同一份设备包同时覆盖:

  • 单机械臂;
  • 机械臂 + 单轴导轨;
  • 以 Deck 上稳定设备身份为索引的设备局部点位;
  • 不隶属于 Deck 设备的全局点位;
  • 堆栈、货架等规则阵列的少量标定与批量派生。

本票只负责 Wayfinder 计划、协议 Grill、边界冻结和交付拆分。Grill 完成前不修改代码。

Source anchors

  • 当前示例:Uni-Lab-OS/unilab_robot_template@e8964842c4da3d123323cc46cfa565678c909849:config/arm_point_set.v2.example.yaml
  • 当前解析器:Uni-Lab-OS/unilab_robot_template@e8964842c4da3d123323cc46cfa565678c909849:packages/unilab-robot-contracts/src/unilab_robot_contracts/targets.py
  • 现场普通点:GET http://zhlg1509460.bohrium.tech:50001/api/points/robot/robot-main.tool-change.ready
  • 现场阵列点:GET http://zhlg1509460.bohrium.tech:50001/api/points/robot/robot-main.area-6-1
  • 现场阵列定义:GET http://zhlg1509460.bohrium.tech:50001/api/points/grids
  • 读取时间:2026-08-13(Asia/Shanghai)。现场 HTTP 数据是需求证据,不是不可变发布资产。

Evidence summary

tool-change.ready 同时包含:

  • TCP 位姿 pose=[x_mm,y_mm,z_mm,rx_deg,ry_deg,rz_deg]
  • 可选关节位姿 joint=[j1_deg,...,j6_deg]
  • tool/user/acc/vel/cp 上下文;
  • workstation=area-1role=readystatus=validated

area-6-1group-rack 的派生点,使用 grid_affine(group-rack: r1c1)。现场 group-rack 为 4×3 阵列,只示教 P25、P34、P36 三个锚点,其余单元由三点仿射计算并允许每格残差修正。这证明阵列不应复制 12 份完整手工点位。

当前 arm-point-set/v2 只支持:

  • targets.<group>.waypoints.<name>
  • joint_positions | cartesian_pose | cartesian_delta
  • 单一机械臂 compatible_model_reftool_context_ref
  • 稳定引用 <group>.<waypoint>

它不能表达导轨目标、Deck 设备索引、保留的全局作用域或阵列生成。因此只改示例 YAML 会生成解析器无法读取的伪配置。

Candidate boundary

1. 不把 Deck 设备当成库存库位(Site)

点位文件中的设备索引表示“哪个物理设备/区域拥有这些运动目标”,不是库存权威(Inventory Authority)中的库位(Site)。最终由部署所有的库位访问绑定(SiteAccessBinding)把稳定 Site 映射到已发布点位引用。

2. 不把导轨伪装成机械臂第七关节

机械臂目标和导轨目标属于不同执行端口。候选点位资产可以在同一设备作用域下组合引用二者,但解析后必须保持:

  • arm target → RobotExecutionBackend;
  • rail target → RailAxisPort;
  • 顺序与互锁 → 工作单元协调器(WorkCell Coordinator)。

点位资产不拥有执行调度或硬件互锁权威。

3. 全局是保留作用域,不是假设备

机械臂归零、机械臂待机、导轨归零等目标进入 global。它们不挂在任一 Deck 设备下,也不创建虚假的 Device/Site。

4. 阵列使用生成式定义

候选方向:

  • rows/cols 与稳定 cell key;
  • 至少三个现场锚点;
  • 明确的仿射生成规则;
  • 可选 per-cell residual;
  • 生成结果包含来源链、revision/digest 和稳定 target ref;
  • 调试界面只要求“示教锚点 → 预览全阵列 → 必要时微调单格”,不要求逐格重复示教。

Decisions to grill

  1. Schema 边界:原地扩展 unilab.arm-point-set/v2,还是新增能表达 WorkCell 的版本化 Schema?
  2. 设备索引身份:使用稳定 device_ref/member_ref,还是现场可读名称?
  3. 复合点位:同一设备访问目标如何组合 rail target、arm target、approach/interaction/retract?
  4. 全局作用域:全局目标是否允许同时拥有 arm 与 rail 子目标?
  5. 阵列算法:三点仿射 + 单格残差是否为 v1 唯一算法,还是一开始支持更多生成器?
  6. 单位与姿态:作者态是否接受现场 mm/deg/XYZ Euler,发布态是否统一为 SI/quaternion?
  7. 身份与迁移:如何从 arm-point-set/v2 迁移并保持已有引用可追踪?
  8. 资格与发布:阵列锚点、生成单元和残差分别需要什么验证证据?

Delivery plan

  1. 冻结规范词汇与权威边界。
  2. 冻结新版 Schema、稳定引用和兼容策略。
  3. 冻结阵列生成、预览、单格修正与发布流程。
  4. unilab_robot_template 中修改 contracts、resolver、示例资产和测试。
  5. 如确有需要,再为 SZLab 增加部署绑定样例;不把现场专用判断放进共享机械臂合同。
  6. 后续另拆 Workbench/FE 调试交付票;本票不把 UI 当作点位真值源。

Acceptance gates

  • 同一合同可描述单机械臂和机械臂 + 导轨,缺少 rail 时无需空占位。
  • Deck 设备改显示名或排序不改变稳定点位身份。
  • global 不伪装成 Device 或 Site。
  • 4×3 货架可由三个锚点和可选单格残差确定性生成。
  • 所有生成点均可追溯到 anchor、generator revision、correction 和资产 digest。
  • 循环引用、缺失锚点、重复 cell、越界残差、模型不兼容均失败关闭。
  • arm 与 rail 分别交给各自执行端口;点位解析不会绕过协调器和硬件互锁。
  • 已有 arm-point-set/v2 有明确的继续支持或迁移方案,不能静默改义。
  • 测试覆盖普通点、全局点、复合点、阵列生成、残差、迁移和非法输入。
  • 在人工 Grill 冻结前,不修改生产代码。

Related Wayfinder maps

Current status

  • 阶段:协议定义(Protocol definition)
  • 状态:等待人工逐项 Grill
  • 代码:未修改

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature:workcell-compositionWorkCell 组合定义、注册编译、可见性与 Action 发布ready-for-agentFully specified and ready for an AFK agentstage:implementationImplementing a frozen protocolwayfinder:map跨仓 Wayfinder 总导航wayfinder:task为后续决策解除阻塞的 Wayfinder 任务票

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions