9. lerobot play数据采集#

9.1 环境配置#

9.1.1 软件安装#

根据您的系统配置，选择对应的安装命令：

9.1.1.1 配置一：x86_64 + Ubuntu 24.04#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 创建 Python 3.12 虚拟环境
conda create -y -n lerobot python=3.12

# 激活环境
conda activate lerobot

# 安装系统依赖库
conda install -c conda-forge libstdcxx-ng

# 安装 ffmpeg（LeRobot 支持 4.5.6.7 系列，推荐使用 7.1.1 版本）
conda install ffmpeg=7.1.1 -c conda-forge

# 安装 AirBot 核心软件包
pip install airbot_hardware_py-<version>.whl
pip install lerobot_play-<version>.whl -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install airbot_state_machine-<version>.whl -i https://pypi.tuna.tsinghua.edu.cn/simple

9.1.1.2 配置二：x86_64 + Ubuntu 22.04#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 创建 Python 3.10 虚拟环境
conda create -y -n lerobot python=3.10

# 激活环境
conda activate lerobot

# 安装系统依赖库
conda install -c conda-forge libstdcxx-ng

# 安装 ffmpeg（LeRobot 支持 4.5.6.7 系列，推荐使用 7.1.1 版本）
conda install ffmpeg=7.1.1 -c conda-forge

# 安装 AirBot 核心软件包
pip install airbot_hardware_py-<version>.whl
pip install lerobot_play-<version>.whl -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install airbot_state_machine-<version>.whl -i https://pypi.tuna.tsinghua.edu.cn/simple

# Ubuntu 24.04 → Python 3.12
conda create -y -n lerobot python=3.12

# Ubuntu 22.04 → Python 3.10  
conda create -y -n lerobot python=3.10

# 安装编译工具和 evdev
conda install -c conda-forge gcc_linux-64 gxx_linux-64 evdev

# 重新安装 lerobot_play
pip install lerobot_play-<*>.whl

9.1.2 硬件配置#

9.1.2.1 硬件清单#

9.1.2.2 机械臂绑定#

9.1.2.2.1 检查设备识别#

请确保系统能够识别到机械臂，运行以下命令检查 CAN 接口：

ip link | grep can

9.1.2.2.2 绑定指令#

执行以下命令进行机械臂绑定：

sudo bind_airbot_device can_left

sudo bind_airbot_device rm

9.1.2.3 相机设备查询#

使用以下命令分别查询 USB 摄像头和 RealSense 深度相机的设备信息：

# 查询 USB 相机设备号和配置信息
lerobot-find-cameras opencv

# 查询 RealSense 相机设备号和配置信息
lerobot-find-cameras realsense

如果执行上述 RealSense 查询时出现错误：

Error finding RealSense cameras: failed to set power state

请运行以下命令配置 udev 权限：

# 创建 RealSense udev 规则
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="8086", MODE="0666", GROUP="video"' | sudo tee /etc/udev/rules.d/99-realsense.rules

# 重新加载 udev 规则
sudo udevadm control --reload-rules
sudo udevadm trigger

配置完成后，请重新插拔 RealSense 相机或重启系统以使规则生效。

9.2 修改配置文件#

在开始采集数据前，需对硬件设备与数据集参数进行配置。配置文件分为四部分：从臂设置（robot）、主臂设置（teleop）、采集设置（run） 和 数据集设置（dataset）。

快速开始

根据您的硬件组合，可直接下载对应的配置文件模板：

硬件配置	下载链接
Play单臂	config_Play.yaml
PTK	config_PTK.yaml
TOK2	config_TOK2.yaml
TOK4	config_TOK4.yaml

9.2.1 从臂设置（robot）#

从臂配置包含 设备参数 和 相机参数 两部分：

9.2.1.1 设备参数配置#

从臂类型对应说明：
• airbot_play_follower：AIRBOT Play 机械臂 + G2 夹爪
• airbot_PTK_follower：PTK 系列
• airbot_TOK2_follower：TOK2 系列
• airbot_TOK4_follower：TOK4 系列

9.2.1.2 相机参数配置#

支持多相机配置，包括两种类型：

完整的从臂配置设置如下：

robot:
  type: airbot_play_follower
  port: can0
  id: airbot_play_follower
  cameras:
    # RealSense相机配置示例
    right_hand_camera:                       # 相机名称，可自由设置
    type: realsense                          # 相机类别
    serial_number_or_name: "243322072684"    # 相机SN码
    width: 640
    height: 480
    fps: 30
    color_mode: RGB                          # 颜色模式
    use_depth: false                         # 是否启用深度图像，默认关闭
    rotation: NO_ROTATION                    # 是否需要旋转
    # USB相机配置示例
    env_cam_A:                               # 相机名称，可自由设置
    type: opencv                             # 相机类别
    index_or_path: "/dev/video2"             # 相机端口号
    width: 640
    height: 480
    fps: 25
    rotation: NO_ROTATION                    # 是否需要旋转

9.2.2 主臂设置（teleop）#

teleop:
  type: airbot_play_with_E2_leader
  port: can1
  id: airbot_play_with_E2_leader

主臂类型对应说明：
• airbot_replay：AIRBOT replay示教臂
• airbot_play_with_E2_leader：AIRBOT Play机械臂 + E2示教器
• airbot_PTK_leader：PTK 系列
• airbot_TOK2_leader：TOK2 系列
• airbot_TOK4_leader：TOK4 系列

9.2.3 采集设置（run）#

run:
  fps: 30
  display_data: false
  num_episodes: 25
  episode_time_sec: 60
  reset_time_sec: 60
  single_task: "Grab the black cube"

9.2.4 数据集设置（dataset）#

dataset:
  repo_id: test_playe2
  video: true
  num_image_writer_processes: 0
  num_image_writer_threads_per_camera: 4
  video_encoding_batch_size: 1
  push_to_hub: false

9.3 数据采集流程#

9.3.1 采集步骤#

9.3.1.1 启动采集程序#

# 进入conda环境
conda activate lerobot
python3 -m lerobot_play.record --yaml <path to your config yaml>

9.3.1.2 执行任务#

1. 手动操作主臂：使用主臂（teleop）控制从臂完成指定任务
2. 开始采集：按下空格键开始数据采集
3. 保存单轮数据：每轮任务完成后，按一下 →（右箭头键）保存当前数据

   ⚠️ 注意：按下后需等待 一段时间 进行数据落盘。期间机械臂处于非受控状态，切勿放下主臂airbot replay！落盘完成后，可继续采集。

4. 重置当前轮次：若演示过程中出现失误，按一下 ←（左箭头键）丢弃本轮数据，并重新开始当前轮次（轮次编号不变）

5. 提前退出 ：若已完成所需轮次或需中断采集，按下 Esc 键立即退出。系统会保存所有已成功完成的轮次。

   💡 快捷键速查

   按键	功能
   空格	开始当前轮次的数据采集
   →	保存当前轮次，进入下一轮准备
   ←	丢弃当前轮次，重新开始本轮
   Esc	提前终止整个采集任务

   按键无响应？

   LeRobot 的键盘监听依赖 X11。若使用 Wayland（Ubuntu 22.04+ 默认），按键可能无效。

   # 编辑 GDM 配置
   sudo nano /etc/gdm3/custom.conf
   
   # 找到并取消注释以下行，设置为 false
   WaylandEnable=false
   
   # 保存后重启或注销重新登录
   sudo reboot
   echo $XDG_SESSION_TYPE
   # 正常应输出：x11
   

9.3.1.3 重置环境#

• 环境复位：每轮开始前，需手动将实验环境恢复至初始状态，包括：
  • 物体放回起始位置
  • 夹爪复位到初始状态
  • 相机视野内物品摆放整齐
• 等待时间：系统会根据配置文件中的 reset_time_sec 参数等待环境重置，在此期间可完成准备工作

9.3.1.4 数据保存位置#

默认存储路径
/home/discover/.cache/huggingface/lerobot/<repo_id>/

⚠️ 重要：每次新采集必须修改 dataset.repo_id，否则同名数据集会被覆盖，导致历史数据丢失。

9.3.2 数据集后处理#

采集完成后，可使用 LeRobot 工具对数据集进行修改和处理。

9.3.2.1 支持的操作#

• 删除指定轮次：移除质量较差的演示数据
• 数据集分割：按比例划分训练/验证/测试集
• 数据集合并：整合多个相关数据集
• 特征管理：增加或删除数据字段

9.3.2.2 使用方法#

具体操作方法和 API 文档请参考 LeRobot 官方文档。

提示：建议在修改前备份原始数据集。

9.3.3 数据可视化#

数据采集完成后，可使用 rerun 工具对数据集进行可视化验证，检查采集质量、任务执行情况以及数据完整性。

9.3.3.1 可视化命令示例#

python3 -m lerobot_play.utils.rerun_vis \
    --repo-id test_playe2 \
    --root /home/discover/.cache/huggingface/lerobot/test_playe2 \
    --robot-type airbot_play_follower \
    --episode-index 0 \
    --max-episodes 1 \
    --batch-size 32 \
    --num-workers 0

9.3.3.2 参数说明#

💡 使用提示
首次加载数据集时可能有短暂卡顿，属于正常现象（需解码视频或读取 HDF5 文件）；
加载完成后即可流畅播放、拖动时间轴、查看多相机视角与关节轨迹。

9.3.4 数据回放#

在完成数据采集后，可将某一轮 episode 在真实机器人上进行动作回放，用于验证数据质量或演示任务。

9.3.4.1 单臂设备Play回放命令#

python3 -m lerobot_play.replay \
    --dataset.repo_id test_playe2 \
    --dataset.root /home/discover/.cache/huggingface/lerobot/test_playe2 \
    --robot.type=airbot_play_follower \
    --robot.port=can0 \
    --robot.id=airbot_play \
    --episode_index=0 \
    --fps=30

9.3.4.2 双臂设备（如PTK）回放命令#

python -m lerobot_play.replay \
    --dataset.repo_id test_03 \
    --dataset.root /home/air/.cache/huggingface/lerobot/test_03 \
    --robot.type=airbot_PTK_follower \
    --robot.left_arm_port=can0 \
    --robot.right_arm_port=can1 \
    --robot.id=PTK_follower \
    --episode_index=0 \
    --fps=30

注意

单臂设备使用 --robot.port；

双臂设备（如 PTK）需分别指定 --robot.left_arm_port 和 --robot.right_arm_port；

所有机器人相关参数（type、id、port）必须与采集时的配置完全一致，否则可能导致数据解析失败或控制异常。