🧠 ROS2 MCAP --> LeRobot 数据集完整转换指南（星海图 Galaxea R1Lite 实战）

很多人在第一次把机器人实采数据接入 LeRobot 时，都会被卡在：

• ROS msg 找不到
• pandas / numpy 地狱
• converter 能跑但接口不匹配
• 同样的命令，别人能跑我不能

本文基于 R1Lite + ROS2 Humble + Galaxea Toolkit 的真实环境，给出一套从零到成功的完整流程。

---

一、最终目标

把：xxx_RAW.mcap
转换为：lerobot dataset 格式

用于：

• policy 训练
• replay
• 统计

二、系统整体依赖关系（理解这张图非常重要）

MCAP 数据
↓
dataset_converter.py
↓ 需要
├── ROS2 python (rclpy)
├── 自定义消息 hdas_msg
└── Galaxea 版本的 LeRobot（支持 task 参数）
↓
生成 LeRobot dataset

（只要缺一个，就会报错。）

三、环境准备

必须满足

Ubuntu 22.04

ROS2 Humble

Python 3.10

一个干净的 conda 环境

创建环境

conda create -n mcap_convert python=3.10 -y
conda activate mcap_convert

四、安装 正确版本 的 LeRobot（最关键）

⚠️⚠️⚠️
官方 HuggingFace 的 LeRobot 不能用。
Galaxea 的 converter 依赖的是：

LeRobotDataset.add_frame(..., task=...)

只有他们 fork 的版本才支持。

安装方式（推荐 zip，避免 git 网络问题）

wget https://codeload.github.com/OpenGalaxea/GalaxeaLeRobot/zip/refs/heads/main -O galaxea_lerobot.zip
unzip galaxea_lerobot.zip

python -m pip uninstall -y lerobot
python -m pip install -e ~/GalaxeaLeRobot-main

验证（必须成功）

python -c "import inspect; from lerobot.datasets.lerobot_dataset import LeRobotDataset; print(inspect.signature(LeRobotDataset.add_frame))"

应该看到

(self, frame: dict, task: str, timestamp: ...)

五、编译 hdas_msg（第二大雷点）

mcap 里的 topic 使用了厂商自定义消息。

如果不编译 → 必然报错：

No module named 'hdas_msg'

建 workspace

mkdir -p ~/hdas_msg_ws/src
ln -s ~/projects/lerobot/GalaxeaLeRobotToolkit/src/msg/hdas ~/hdas_msg_ws/src/hdas_msg

编译

cd ~/hdas_msg_ws
source /opt/ros/humble/setup.bash
colcon build --symlink-install

验证

source ~/hdas_msg_ws/install/setup.bash
python -c "import hdas_msg; print(hdas_msg.__file__)"

六、开始转换

每次运行前都要：

source /opt/ros/humble/setup.bash
source ~/hdas_msg_ws/install/setup.bash

单个raw

python -m dataset_converter \
  --input_dir "..._RAW" \
  --output_dir "~/lerobot_out" \
  --robot_type "R1Lite" \
  --dataset_name "demo"

批量转换

只要把 input_dir 指向父目录即可。

python -m dataset_converter \
  --input_dir "/mnt/e/.../20260205" \
  --output_dir "~/lerobot_out" \
  --robot_type "R1Lite" \
  --dataset_name "all"

七、成功标志

你会看到类似于

Processed xx episodes
Merged xx episodes with xxxx frames

数据在

lerobot_out/xxx/

八、踩坑总结（最重要）

坑 1：装了官方 lerobot

表现：

unexpected keyword argument 'task'

解决：→ 换 Galaxea 版本。

坑 2：没 build hdas_msg

表现：

No module named hdas_msg

解决：→ colcon build。

坑 3：只 source humble，没 source overlay

表现：
明明 build 了，还是 import 不到。

解决：

source ~/hdas_msg_ws/install/setup.bash

坑 4：git clone 很慢

解决：
→ 用 zip 下载。