# lerobot2ros

**Repository Path**: chenxin852/lerobot2ros

## Basic Information

- **Project Name**: lerobot2ros
- **Description**: Move LeRobot to ROS2: Node-based: hardware message publishing, teleoperation, data recording, policy reasoning, etc.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-20
- **Last Updated**: 2025-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LeRobot2ROS: 一个用于ROS 2的LeRobot通用机器人框架

[![ROS 2](https://img.shields.io/badge/ROS%202-Humble-blue)](https://docs.ros.org/en/humble/index.html)
[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-310/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

**LeRobot2ROS** 致力于提供一个标准化的、高性能的桥梁，旨在将 [LeRobot](https://github.com/huggingface/lerobot) 库中先进的预训练策略部署到任何支持ROS 2的机器人上。本框架为研究人员和开发者提供了一套即插即用的解决方案，能够将前沿的AI决策能力无缝集成至其机器人系统中。

![系统架构图](./docs/images/01.jpg)

---

## 🌟 核心特性

-   **标准化接口**: 传感器输入采用ROS 2标准消息，机器人动作指令采用专用的自定义消息，确保了广泛的兼容性和清晰的API定义。
-   **配置驱动**: 仅需修改YAML配置文件，即可轻松切换不同的LeRobot策略模型或适应不同的硬件配置，无需改动任何代码。
-   **端到端工作流**: 包含数据采集 (`data_recorder_node`) 与策略部署 (`policy_inference_node`) 的完整工具链，覆盖了从专家演示到自主执行的模仿学习全流程。
-   **多机分布式支持**: 原生支持分布式系统，允许将感知、决策和控制等计算任务分散到同一ROS 2域下的不同主机上。

## 🛠️ 环境依赖与预备工作

1.  **系统环境**:
    -   Ubuntu 22.04
    -   ROS 2 Humble Hawksbill
    -   Python 3.10+

2.  **`lerobot` 环境**:
    -   本项目依赖于 `lerobot` 库的有效安装。请遵循 [LeRobot官方安装指南](https://huggingface.co/docs/lerobot/index) 进行安装。
    -   **关键修改**: 为支持实时数据采集，安装`lerobot`后，需要对源码进行一处微小修改。请注释掉以下文件中的两行代码：
        ```python
        # 文件路径: /path/to/your/lerobot/src/lerobot/datasets/lerobot_dataset.py
        
        # line 906: 注释掉此行断言
        # assert len(parquet_files) == self.num_episodes
        
        # line 908: 注释掉此行断言
        # assert len(video_files) == (self.num_episodes - self.episodes_since_last_encoding) * len(self.meta.video_keys)
        ```
    
3.  **colcon 编译**:
    -   **报错修改**: 为顺利编译，请在自己编译时所在的python环境中按 `requirements.txt` 要求安装相应库及指定版本。

## 🚀 快速开始

### 1. 安装与编译
```bash
# 1. 创建并进入您的ROS 2工作区
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src

# 2. 克隆本仓库
# 建议将 move_lerobot_to_ros2 重命名为 lerobot2ros
git clone https://gitee.com/haoyu0225/lerobot2ros.git

# 3. 配置项目路径
# 重要：请指定您本地lerobot库的安装路径
# 编辑 `lerobot2ros/config/paths.yaml` 文件，设置 `lerobot_path` 变量。
gedit lerobot2ros/config/paths.yaml 

# 4. 安装ROS依赖
cd ~/ros2_ws
rosdep install -i --from-path src -y

# 5. 编译工作区
colcon build --symlink-install
```

### 2. 系统配置
	在运行任何节点之前，请通过编辑  `lerobot2ros/config/config.py` 来适配您的系统配置。该文件集中管理了所有关键参数：
		硬件配置: 相机、机器人状态等相关话题名称。
		数据集录制: 录制数据集的输出路径及元数据。
		策略推理: 需要部署的LeRobot策略在Hugging Face Hub上的仓库ID。
    	
### 3. Sourcing 工作区环境
	在每个新打开的终端中，您都必须source工作区的配置文件，以使ROS 2能够找到您编译的包
```bash
source ~/ros2_ws/install/setup.bash
```

## 📦 核心组件及其功能

本仓库包含多个关键节点，共同构成了一套完整的遥操作、数据采集和策略推理的机器人系统。

-   **so101_leader_startup.py**: 主臂控制器
	功能: 启动主操作臂（leader arm）的驱动节点。该节点读取主臂的状态，并将其作为动作指令发布到 /robot/command 话题。
	 用途: 用于专家演示遥操作和数据采集。

-   **so101_follower_startup.py**: 从臂控制器
	功能: 启动从动臂（follower arm）及其相机的驱动节点。该节点订阅 /robot/command 话题，并执行接收到的指令，从而精确模仿主臂的动作。
	用途: 机器人的主要执行单元，在遥操作和自主推理两种模式下都会使用。

-   **data_recorder_node.py**: 数据采集节点
	功能: 数据采集的核心组件。该节点监听并同步来自从臂和相机的ROS话题，将专家演示的操作（观测-动作对）记录为数据集。
	关键特性: 输出的数据集格式与lerobot库完全兼容，可直接用于训练新的策略。

-   **policy_inference_node.py**: AI决策中枢
	功能: 自主系统的大脑。该节点订阅机器人的实时状态（如相机图像、关节角度），将其输入到预训练的LeRobot策略模型中，并将模型推理出的动作指令发布到 /robot/command 话题，以驱动从臂执行任务。
	用途: 替换 so101_leader_startup.py 节点，使机器人具备自主操作能力。

## 🌐 分布式部署 (多机配置)

若需将不同功能的节点运行在不同的主机上，请在每一台主机上遵循以下步骤：
   1. 网络连通性: 确保所有主机都连接到同一个局域网（LAN），并且可以互相ping通。
   2. 设置 ROS_DOMAIN_ID: 在您shell的配置文件（通常是~/.bashrc）中添加相同的域ID，以确保所有节点都加入同一个ROS 2域。
```bash
# 在所有主机的 ~/.bashrc 文件末尾添加此行
export ROS_DOMAIN_ID=42

# 重新加载配置或打开新终端使其生效
source ~/.bashrc
```

## 🤝 贡献

欢迎任何形式的贡献！如果您有任何问题或建议，请随时提交Issue或Pull Request。

## 📄 开源许可

本项目遵循 Apache 2.0 开源许可协议。详情请见 LICENSE 文件。