robot_action_composer

运动生成与 task_queue YAML 编排：技能注册表把 YAML 块变成 StageTarget 序列，再通过 ROS2RobotInterface 执行。可选的 LeRobot 数据集录制是 extra，不是核心路径。

文档所依据的分支

本文档对照分支 feature/dex-grasp-generator（尖端提交 2026-09-20）。该分支新于 main；请以它为准，不要跟 main。

仓库： fiveages-sim/robot_action_composer @ feature/dex-grasp-generator

README： README.md on this branch

没有 ActionSequence / actions.MoveJ / CustomAction 这类 API。技能是 YAML 里的注册名（task_queue → skill）。完整参数说明见 docs/SKILLS_REFERENCE.md。

用途

在 lerobot_ros2 单体仓库中，本包承担：

  • 运动层（motion_generation）：把任务几何与机器人约束变成 StageTarget 序列，并通过 ROS2RobotInterface 执行（笛卡尔 / 双臂同步 / MoveJ 等）。

  • 编排层（task_runtime）：用技能注册表与运行时上下文执行 task_queue（YAML 块列表）；合并 skill_defaults / skill_params。

  • 周边：Isaac Sim 实体位姿、仿真 reset、可选的 LeRobot 录制。

本包不实现 OCS2 / MPC 或 Nav2 服务器本体；它们仍走已有 ROS 2 接口。纯运动/队列路径只依赖 ROS2RobotInterface（ctx.interface），不依赖 LeRobot 的 ROS2Robot 类。

前置要求

与 lerobot_ros2 单体仓库 README 的基线一致：

  • Python 3.12

  • ROS 2 Jazzy，并已 source 对应的 install/setup.bash（或 overlay），使 rclpy 来自该发行版

安装

典型路径是在 lerobot_ros2 检出中安装（composer 位于 submodules/robot_action_composer）：

./init.sh all-motion          # interface + robot_action_composer
./init.sh install-lerobot     # extra: PyTorch + lerobot + plugins (record / infer)
# or once: ./init.sh all

./init.sh all-motion 会创建环境并安装这两个本地包。composer pyproject.toml 中的可选 extra：[recording]（LeRobot / lerobot_robot_ros2）、[grasp]（viser>=0.2，抓取生成 UI）。该 extra 不是 fa-py-libraries 的 ./run.sh viser 启动器。

安装后可用的控制台脚本：motion-generation、ros2-stack、grasp-generation、check-isaac-pose、check-robot-status。

手动回退

在单体仓库根目录、环境已激活后。优先用 uv 和 --no-deps，以免从 PyPI 拉 rclpy。composer README 也写了只在项目虚拟环境内 pip install -e submodules/ros2_robot_interface 再 pip install -e submodules/robot_action_composer（系统 pip 会碰到 PEP 668）。

uv pip install -e submodules/ros2_robot_interface --no-deps
uv pip install -e submodules/robot_action_composer --no-deps
uv pip install "viser>=0.2"   # optional; grasp-generation UI

分层

motion_generation：每一段运动长什么样、怎么发到机器人。

  • sequence/：StageTarget / ArmTarget / ArmStage，以及 build_single_arm_pick_sequence 等 builder，还有 execute_stage_sequence（调用 ROS2RobotInterface、到位等待、夹爪节拍）。

  • tasks/：在 sequence 之上的几何封装（交接、双臂搬运、并行抓取、抽屉、抓放、数据集录制用的 MoveJ 返回）。

task_runtime：按队列调用哪些技能、顺序如何、合并后的参数是什么。

  • runner.run_task_queue：连接机器人 → FSM → 可选环境 reset → 构造 QueueRuntimeContext → 顺序执行 task_queue 各块（支持 ParallelSpec）→ get_skill → execute_stage_sequence。

  • registry.py：register_skill(name, fn) / get_skill(name)；未知技能名会抛出 KeyError（错误信息含已注册名列表）。

  • 每个技能签名：(ctx, params) -> (list[StageTarget], ExecutionMeta)。无笛卡尔阶段的块返回空列表（纯导航、纯 MoveJ、仅副作用）。

YAML 发现会扫描 task_configs/**/*.yaml 与 robots/*/（可选一层厂商分组 robots/<Vendor>/<Robot>/）。见 docs/TASK_CONFIG_YAML.md 与 docs/ROBOT_CONFIG.md。

技能（注册名）

不要发明 Python 版 MoveJ / GripperOpen Action 类。YAML 块把 skill: 写成注册名。分类（示例来自 README 索引；参数见 SKILLS_REFERENCE）：

分类

示例技能

单臂

single_arm.pick, single_arm.place, single_arm.move_to_pose, single_arm.move_relative, single_arm.move_to_object, single_arm.goto_cache_pose, single_arm.drawer.pull_open, single_arm.drawer.close_push

双臂

dual_arm.carry, dual_arm.parallel_pick, dual_arm.handover, dual_arm.place, dual_arm.bimanual_align, dual_arm.goto_cache_pose

导航

nav.navigate_to_pose, nav.navigate_to_object, nav.navigate_relative, nav.send_nav_goal, nav.wait_nav_arrived

关节

joint.movej_to_config, joint.goto_cached_joints

会话 / 机器人 / 环境

session.scratch_put, robot.cache_ee_pose, robot.cache_joint_state, robot.send_mode_command, env.randomize_object_local_xyz

完整列表、默认值与 YAML 示例：docs/SKILLS_REFERENCE.md。

CLI 要点

在含 robots/ 的工作区目录下运行（README 使用 lerobot_ros2 树中的 examples/IsaacSim）。下列参数来自 composer README；完整集合以该文件为准。

# Task queue
motion-generation
motion-generation --robot dobot_cr5 --task-key pick_place --scene default
motion-generation --workspace /path/to/workspace --robot dobot_cr5 --task-key pick_place
motion-generation --lang zh
motion-generation --robot fiveages_w2 --task-key transfer_blade --ensure-ros2-stack

# ROS 2 stack (see docs/ROS2_STACK.md)
ros2-stack --lang zh launch
ros2-stack logs --robot fiveages_w2 -f
ros2-stack stop --robot fiveages_w2
ros2-stack status --robot fiveages_w2 --group "projets/siemens/Wind turbo blade"

# Grasp generation UI (does not replace the two CLIs above)
grasp-generation serve --robot fiveages_w2 --workspace examples/IsaacSim

# Isaac Sim entity pose (needs /get_entity_state)
check-isaac-pose /World/robot/FiveAges_W2/LinkHou_S2/base_footprint/base_link
check-isaac-pose /World/scene/boxes/white_box_05 \
  --relative-to /World/robot/FiveAges_W2/LinkHou_S2/base_footprint/base_link

# Current joints / EE pose (pasteable into YAML)
check-robot-status
check-robot-status --robot fiveages_w2 --workspace examples/IsaacSim
check-robot-status --wait 3.0 --show-joint-names

motion-generation 默认 workspace_dir 为当前工作目录。语言优先级：--lang > MOTION_GENERATION_LANG > .motion_last.json > 系统 LANG。ensure_ros2_stack 等偏好缓存在工作区根目录的 .motion_last.json（已 gitignore）。

仓库内文档（本分支）

参数和 CLI 的包内文档（完整列表以这些为准）：

文档

内容

docs/SKILLS_REFERENCE.md

各技能参数、默认值与 YAML 示例

docs/TASK_CONFIG_YAML.md

任务 YAML 格式、skill_defaults / skill_params、加载与合并

docs/ROBOT_CONFIG.md

robot.yaml / lerobot_config.py 与 robots/ 目录约定

docs/ROS2_STACK.md

场景级运控/导航启动（.meta/ros2_stack.yaml、ros2-stack）

docs/GRASP_GENERATION.md

抓取生成 UI 与冒烟

Isaac Sim 环境、USD、工作空间步骤（若存在）见单体仓库 examples/IsaacSim/README.md。