lerobot_ros2

LeRobot 与 ROS 2 的集成单体仓库。LeRobot 通过 ROS 2 话题与机器人通信。

文档所依据的分支

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

仓库： fiveages-sim/lerobot_ros2 @ feature/sim-grasp-datagen

README： README.md on this branch

用途

本仓库是单体工程，不是在仓库根目录执行一次 pip install -e . 就能装好的包。它包含：

  • submodules/ros2_robot_interface：独立 ROS 2 机器人接口包

  • submodules/robot_action_composer：任务队列 YAML 与运动生成（见 robot_action_composer）

  • lerobot_robot_ros2：LeRobot 的 ROS 2 机器人插件（ROS2Robot / ROS2RobotConfig / ROS2RobotInterfaceConfig）

  • lerobot_camera_ros2：LeRobot 的 ROS 2 相机插件

LeRobot 核心库从 PyPI 安装。默认版本钉在 .fa-env.toml 中的 lerobot==0.5.1（首次由 .fa-env.toml.example 生成）。

前置要求

  • ROS 2（测试版本：Jazzy）

  • Python 3.12

  • uv（推荐）或 Conda

安装

先带 submodule 克隆，再用 init.sh。不要把仓库根目录的 pip install -e . 当作安装路径。

git clone --recursive git@github.com:fiveages-sim/lerobot_ros2.git
cd lerobot_ros2

# uv if needed: curl -LsSf https://astral.sh/uv/install.sh | sh

./init.sh all
# motion / task queue only (no LeRobot):  ./init.sh all-motion
# recording / inference plugins:          ./init.sh install-lerobot
source .venv/bin/activate   # default backend=uv

./init.sh 不带参数会进入交互菜单（子模块、环境、安装、backend、ROS 2 工作空间）。README 中常用的非交互命令：

命令

作用

./init.sh all

子模块 + 环境 + 任务编排 + LeRobot 插件

./init.sh all-motion

仅子模块 + 环境 + ros2_robot_interface + robot_action_composer

./init.sh install-lerobot

PyTorch + PyPI lerobot + lerobot_robot_ros2 / lerobot_camera_ros2

./init.sh set-backend uv

写入 .fa-env.toml 中的 backend（uv 或 conda）

运行时配置在本地 .fa-env.toml（已 gitignore；从示例复制）。README 中记录的键：

配置项

说明

backend

uv 或 conda

[conda].name

conda 环境名（默认 lerobot-ros2）

[uv].venv

uv 虚拟环境路径（默认 .venv）

[lerobot].version

PyPI lerobot 版本（默认 0.5.1）

[ros2].workspace

ROS 2 工作空间；激活环境时自动 source

个人覆盖：.fa-env.local.toml。环境说明：docs/ENV_THIS_CHECKOUT.md。在本检出的 .venv 里用 uv pip，不要用系统 pip（PEP 668）。不要把 ros2-stack / grasp-generation 装进 submodules/hug/.venv（HUG 的 Python 3.10 环境）。

手动回退

仅在必须时才跳过 init.sh。README 的 uv 路径：用 --system-site-packages 创建 .venv，本地包加 --no-deps，避免 pip 从 PyPI 拉 rclpy。ROS Python 包来自已 source 的 Jazzy overlay。

git clone --recursive git@github.com:fiveages-sim/lerobot_ros2.git
cd lerobot_ros2
git submodule update --init --recursive

uv venv --python python3.12 --system-site-packages .venv
source .venv/bin/activate

uv pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 \
  --index-url https://download.pytorch.org/whl/cu128
uv pip install "lerobot==0.5.1"

uv pip install -e submodules/ros2_robot_interface --no-deps
uv pip install numpy pyyaml
uv pip install -e submodules/robot_action_composer --no-deps
uv pip install "viser>=0.2"   # optional grasp-generation UI (PyPI viser, not ros2-viser launch)
uv pip install -e lerobot_robot_ros2 --no-deps
uv pip install -e lerobot_camera_ros2 --no-deps

使用：ROS2Robot

对外的机器人插件是 lerobot_robot_ros2，不是名为 lerobot_ros2 的根包。示例来自 README：

from lerobot_robot_ros2 import ROS2Robot, ROS2RobotConfig, ROS2RobotInterfaceConfig

config = ROS2RobotConfig(
    id="my_robot",
    ros2_interface=ROS2RobotInterfaceConfig(
        joint_states_topic="/joint_states",
        end_effector_pose_topic="/left_current_pose",
        end_effector_target_topic="/left_target",
    ),
)

robot = ROS2Robot(config)
robot.connect()
# ...
robot.disconnect()

更多示例见本分支的 examples/。lerobot_robot_ros2 依赖本地已安装的 ros2-robot-interface（先装 submodules/ros2_robot_interface）。

相机插件

lerobot_camera_ros2 默认使用 manual 图像转换（不依赖 cv_bridge），以便配合 lerobot==0.5.1 与 numpy 2.x。若环境支持 cv_bridge，会自动尝试使用。强制走 manual 路径：

export LEROBOT_ROS2_DISABLE_CV_BRIDGE=1

uv 路径还需系统已安装 ffmpeg（例如 sudo apt install ffmpeg）。install-plugins 会额外安装 scipy>=1.14，避免 --system-site-packages 下系统 SciPy 与 numpy 2.x 不兼容。

仓库内文档（本分支）

文档

内容

docs/ENV_THIS_CHECKOUT.md

只在本仓库检出环境中开发与安装

docs/HUG_SUBMODULE.md

HUG 子模块说明

docs/WUJI_RETARGETING.md

Wuji 重定向

Composer GRASP_GENERATION.md

运控 + 抓取冒烟（lerobot README 中的链接）

仿真抓取交接 / 末端对齐说明也在本分支的 docs/SIM_GRASP_*.md。