Skip to main content

基于 LeRobot 的 StarAI 机械臂入门教程

跟随臂 Viola领导臂 Violin跟随臂 Cello
fig1fig2fig3
淘宝来一单 🖱️

产品介绍​

  1. 开源 & 便于二次开发 本系列舵机由华馨京科技提供，是一套开源、便于二次开发的6+1自由度机器臂解决方案。
  2. 支持 LeRobot 平台集成 专为与 LeRobot 平台 集成而设计。该平台提供 PyTorch 模型、数据集与工具，面向现实机器人任务的模仿学习（包括数据采集、仿真、训练与部署）。
  3. 丰富的学习资源 提供全面的开源学习资源，包括环境搭建，安装与调试与自定义夹取任务案例帮助用户快速上手并开发机器人应用。
  4. 兼容 Nvidia 平台 支持通过 reComputer Mini J4012 Orin NX 16GB 平台进行部署。

特点内容​

  • 零组装: 即刻上手｜一开箱即踏入AI时代。
  • 6+1自由度结构设计，470mm臂展，赋予无限操作可能。
  • 配备2颗全金属无刷总线舵机，稳定驱动，轻松承重300g。
  • 智能平行夹爪，最大开合66mm，模块化指尖，精准抓取不设限。
  • 独家悬停控制系统，指尖一按，Leader Arm稳停于任意姿态。

规格参数​

项目（Item）跟随臂 | Viola领导臂 | Violin跟随臂 | Cello
自由度（Degrees of Freedom）6+16+16+1
最大工作半径（Reach）470毫米470毫米670毫米
最大臂展（Span）940毫米940毫米1340毫米
重复定位精度（Repeatability）2毫米-1毫米
工作负载（Working Payload）300克（在70%工作半径下）-750克（在70%工作半径下）
伺服电机（Servos）RX8-U50H-M × 2
RA8-U25H-M × 4
RA8-U26H-M × 1		RX8-U50H-M × 2
RA8-U25H-M × 4
RA8-U26H-M × 1		RX18-U100H-M × 3
RX8-U50H-M × 3
RX8-U51H-M × 1
平行夹爪套件（Parallel Gripper Kit）✅（支持）-✅（支持）
腕部旋转（Wrist Rotate）支持（Yes）支持（Yes）支持（Yes）
任意位置悬停（Hold at any Position）支持（Yes）支持（Yes，带手柄按键）支持（Yes）
腕部相机安装座（Wrist Camera Mount）提供参考3D打印文件-提供参考3D打印文件
兼容LeRobot（Works with LeRobot）✅（兼容）✅（兼容）✅（兼容）
兼容ROS 2（Works with ROS 2）✅（兼容）✅（兼容）✅（兼容）
兼容MoveIt2（Works with MoveIt2）✅（兼容）✅（兼容）✅（兼容）
兼容Gazebo（Works with Gazebo）✅（兼容）✅（兼容）✅（兼容）
通信集线器（Communication Hub）UC-01UC-01UC-01
电源适配器（Power Supply）12伏10安/120瓦，XT30接口12伏10安/120瓦，XT30接口12伏25安/300瓦，XT60接口

有关舵机更多资讯，请访问以下链接。

RA8-U25H-M

RX18-U100H-M

RX8-U50H-M

初始环境搭建​

对于 Ubuntu x86:

  • Ubuntu 22.04
  • CUDA 12+
  • Python 3.10
  • Torch 2.6

对于 Jetson Orin:

  • Jetson JetPack 6.0+
  • Python 3.10
  • Torch 2.6

安装与调试​

安装LeRobot​

需要根据你的 CUDA 版本安装 pytorch 和 torchvision 等环境。

  1. 安装 Miniconda： 对于 Jetson：
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh
chmod +x Miniconda3-latest-Linux-aarch64.sh
./Miniconda3-latest-Linux-aarch64.sh
source ~/.bashrc

或者，对于 X86 Ubuntu 22.04：

mkdir -p ~/miniconda3
cd miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh
source ~/miniconda3/bin/activate
conda init --all

2.创建并激活一个新的 conda 环境用于 LeRobot

conda create -y -n lerobot python=3.10 && conda activate lerobot

3.克隆 LeRobot 仓库：

git clone https://github.com/Seeed-Projects/lerobot-starai.git ~/lerobot

4.使用 miniconda 时，在环境中安装 ffmpeg：

conda install ffmpeg -c conda-forge
tip

这通常会为你的平台安装使用 libsvtav1 编码器编译的 ffmpeg 7.X。如果不支持 libsvtav1（可以通过 ffmpeg -encoders 查看支持的编码器），你可以：

  • 【适用于所有平台】显式安装 ffmpeg 7.X：
conda install ffmpeg=7.1.1 -c conda-forge
  • 【仅限 Linux】安装 ffmpeg 的构建依赖并从源码编译支持 libsvtav1 的 ffmpeg，并确保使用的 ffmpeg 可执行文件是正确的，可以通过 which ffmpeg 确认。

如果你遇到以下报错，也可以使用上述命令解决。

5.安装LeRobot：

cd ~/lerobot && pip install -e .

对于 Jetson Jetpack 设备（请确保在执行此步骤前按照此链接教程第 5 步安装了 Pytorch-gpu 和 Torchvision）：

conda install -y -c conda-forge "opencv>=4.10.0.84"  # 通过 conda 安装 OpenCV 和其他依赖，仅适用于 Jetson Jetpack 6.0+
conda remove opencv   # 卸载 OpenCV
pip3 install opencv-python==4.10.0.84  # 使用 pip3 安装指定版本 OpenCV
conda install -y -c conda-forge ffmpeg
conda uninstall numpy
pip3 install numpy==1.26.0  # 该版本需与 torchvision 兼容

6.安装 Fashionstar 电机依赖：

pip install lerobot_teleoperator_bimanual_leader
pip install lerobot_robot_bimanual_follower

7.检查 Pytorch 和 Torchvision

由于通过 pip 安装 LeRobot 环境时会卸载原有的 Pytorch 和 Torchvision 并安装 CPU 版本，因此需要在 Python 中进行检查。

import torch
print(torch.cuda.is_available())

如果输出结果为 False，需要根据官网教程重新安装 Pytorch 和 Torchvision。

如果你使用的是 Jetson 设备，请根据此教程安装 Pytorch 和 Torchvision。

机械臂开箱​

机械臂套装内包含

  • Leader arm 主体
  • Follower arm 主体
  • 手柄
  • 平行夹爪
  • 安装工具（螺丝、内六角扳手）
  • 电源 x2
  • C型夹具 x2
  • UC-01 转接板 x2

UC-01 转接板 开关：

手臂端口设置​

进入~/lerobot目录：

cd ~/lerobot

在终端输入以下指令来找到两个机械臂对应的端口号：

lerobot-find-port
tip

需要拔出USB，再按下回车，否则将无法检测到接口。

例如：

  1. 识别Leader时端口的示例输出（例如，在 Mac 上为 /dev/tty.usbmodem575E0031751，或在 Linux 上可能为 /dev/ttyUSB0）
  2. 识别Reader时端口的示例输出（例如，在 Mac 上为 /dev/tty.usbmodem575E0032081，或在 Linux 上可能为 /dev/ttyUSB1）
tip

如果识别不到ttyUSB0串口信息。尝试以下方法:

列出所有usb口。

lsusb

识别成功，查看ttyusb的信息。

sudo dmesg | grep ttyUSB

最后一行显示断连，因为brltty在占用该USB设备号，移除掉就可以了。

sudo apt remove brltty

最后，赋予权限。

sudo chmod 666 /dev/ttyUSB*

单臂校准设置​

如果是第一次校准，请对每个关节左右转动到对应位置。

如果是重新校准，按照命令提示输入字母c后按Enter键。

下面是参考值,通常情况下，真实的限位参考值的±10°范围内。

舵机ID角度下限参考值角度上限参考值备注
motor_0-180°180°转动到限位处
motor_1-90°90°转动到限位处
motor_2-90°90°转动到限位处
motor_3-180°180°没有限位，需转动到角度上下限参考值
motor_4-90°90°转动到限位处
motor_5-180°180°没有限位，需转动到角度上下限参考值
motor_60°100°转动到限位处
tip

以PC(linux)和jetson板卡为例，第一个插入usb接口会映射为ttyUSB0，第二个插入usb接口会映射为ttyUSB1。

在运行代码前请注意leader和follower的映射接口。

leader机械臂​

将leader连接到/dev/ttyUSB0，或者修改--teleop.port，然后执行：

lerobot-calibrate     --teleop.type=lerobot_teleoperator_violin --teleop.port=/dev/ttyUSB0 --teleop.id=my_awesome_staraiviolin_arm

follower机械臂​

将follower连接到/dev/ttyUSB1，或者修改--teleop.port，然后执行：

Viola:

lerobot-calibrate     --robot.type=lerobot_robot_viola --robot.port=/dev/ttyUSB1 --robot.id=my_awesome_staraiviola_arm

或者是Cello:

lerobot-calibrate     --robot.type=lerobot_robot_cello --robot.port=/dev/ttyUSB1 --robot.id=my_awesome_staraicello_arm

在运行命令后，需要手动掰机械臂，让每个关节达到极限值，终端会显示记录的范围数据，做完此操作后按下回车即可。

tip

校准的文件会保存到以下路径~/.cache/huggingface/lerobot/calibration/robots和~/.cache/huggingface/lerobot/calibration/teleoperators下。

双臂校准设置​

教程

leader机械臂​

将left_arm_port连接到/dev/ttyUSB0，right_arm_port连接到/dev/ttyUSB2，或者修改--teleop.left_arm_port --teleop.right_arm_port，然后执行：

lerobot-calibrate     --teleop.type=lerobot_teleoperator_bimanual_leader  --teleop.left_arm_port=/dev/ttyUSB0  --teleop.right_arm_port=/dev/ttyUSB2  --teleop.id=bi_starai_violin_leader

follower机械臂​

将left_arm_port连接到/dev/ttyUSB1，right_arm_port连接到/dev/ttyUSB3，或者修改--robot.left_arm_port --robot.right_arm_port，然后执行：

Viola:

lerobot-calibrate     --robot.type=lerobot_robot_bimanual_follower  --robot.arm_name=starai_viola  --robot.left_arm_port=/dev/ttyUSB1  --robot.right_arm_port=/dev/ttyUSB3 --robot.id=bi_starai_viola_follower

或者是Cello:

lerobot-calibrate     --robot.type=lerobot_robot_bimanual_follower  --robot.arm_name=starai_cello  --robot.left_arm_port=/dev/ttyUSB1  --robot.right_arm_port=/dev/ttyUSB3 --robot.id=bi_starai_cello_follower
tip

单臂和双臂的区别在于--teleop.type和--robot.type不一样，同时双臂需要给左右手各一个usb口，总共需要4个usb口--teleop.left_arm_port --teleop.right_arm_port --robot.left_arm_port --robot.right_arm_port。

若使用双臂，需要手动修改机械臂文件类型--teleop.type --robot.type和usb口--teleop.left_arm_port --teleop.right_arm_port --robot.left_arm_port --robot.right_arm_port，来适配遥操，收集数据，训练和评估命令。

遥控操作​

将手臂移动至图上位置待机。

您已准备好遥操作您的机器人（不包括摄像头）！运行以下简单脚本：

Violin&Viola:

lerobot-teleoperate \
    --robot.type=lerobot_robot_viola \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraiviola_arm \
    --teleop.type=lerobot_teleoperator_violin \
    --teleop.port=/dev/ttyUSB0 \
    --teleop.id=my_awesome_staraiviolin_arm

Violin&Cello:

lerobot-teleoperate \
    --robot.type=lerobot_robot_cello \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraicello_arm \
    --teleop.type=lerobot_teleoperator_violin \
    --teleop.port=/dev/ttyUSB0 \
    --teleop.id=my_awesome_staraiviolin_arm
双臂

Violin&Viola:

lerobot-teleoperate \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_viola \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.id=bi_starai_viola_follower \
    --teleop.type=lerobot_teleoperator_bimanual_leader \
    --teleop.left_arm_port=/dev/ttyUSB0 \
    --teleop.right_arm_port=/dev/ttyUSB2 \
    --teleop.id=bi_starai_violin_leader

Violin&Cello:

lerobot-teleoperate \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_cello \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.id=bi_starai_cello_follower \
    --teleop.type=lerobot_teleoperator_bimanual_leader \
    --teleop.left_arm_port=/dev/ttyUSB0 \
    --teleop.right_arm_port=/dev/ttyUSB2 \
    --teleop.id=bi_starai_violin_leader

远程操作命令将自动检测下列参数:

  1. 识别任何缺失的校准并启动校准程序。
  2. 连接机器人和远程操作设备并开始远程操作。

程序启动后，悬停按钮依旧生效。

添加摄像头​

如果是Orbbec Gemini2深度相机
淘宝来一单 🖱️
  • 🚀 步骤 1：安装 Orbbec SDK 依赖环境

  1. 拉取 pyorbbec 仓库

    cd ~/
    git clone https://github.com/orbbec/pyorbbecsdk.git

  2. 下载并安装 SDK 对应的 .whl 文件
    前往 pyorbbecsdk Releases，
    根据 Python 版本选择并安装，例如：

    pip install pyorbbecsdk-x.x.x-cp310-cp310-linux_x86_64.whl

  3. 在 pyorbbec 目录下安装依赖

    cd ~/pyorbbecsdk
    pip install -r requirements.txt

强制降低numpy版本到1.26.0

pip install numpy==1.26.0

可以忽略红色报错。

4.将orbbec sdk克隆到~/lerobot/src/cameras目录下

cd ~/lerobot/src/cameras
git clone https://github.com/ZhuYaoHui1998/orbbec.git

5.修改utils.py和__init__.py

  • 在~/lerobot/src/lerobot/cameras目录下找到utils.py，在40行处添加如下代码：
elif cfg.type == "orbbec":
            from .orbbec.camera_orbbec import OrbbecCamera

            cameras[key] = OrbbecCamera(cfg)
  • 在~/lerobot/src/lerobot/cameras目录下找到__init__.py，在18行处添加如下代码：
from .orbbec.configuration_orbbec import OrbbecCameraConfig
  • 🚀 步骤 2：函数调用与示例

以下示例均需将 starai_viola 替换为你所使用实际机械臂型号（如 so100 / so101）。

我们加入了focus_area超参数，因为过远的深度数据对于机械臂没有意义（抓取不到），因此小于或者大于focus_area的深度数据将会变为黑色,默认的focus_area是(20,600) 目前支持的分辨率只限于 width: 640, height: 880

Violin&Viola:

lerobot-teleoperate \
    --robot.type=lerobot_starai_viola \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraiviola_arm \
    --robot.cameras="{ up: {type: orbbec, width: 640, height: 880, fps: 30, focus_area:[60,300]}}" \
    --teleop.type=lerobot_starai_violin \
    --teleop.port=/dev/ttyUSB0 \
    --teleop.id=my_awesome_staraiviolin_arm \
    --display_data=true

Violin&Cello:

lerobot-teleoperate \
    --robot.type=lerobot_starai_cello \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraicello_arm \
    --robot.cameras="{ up: {type: orbbec, width: 640, height: 880, fps: 30, focus_area:[60,300]}}" \
    --teleop.type=lerobot_starai_violin \
    --teleop.port=/dev/ttyUSB0 \
    --teleop.id=my_awesome_staraiviolin_arm \
    --display_data=true

后续采集数据、训练及评估任务与常规RGB命令一样，只需要把:

  --robot.cameras="{ up: {type: orbbec, width: 640, height: 880, fps: 30, focus_area:[60,300]}}" \

替换到常规rgb命令中即可，你也可以再后面添加额外的单目RGB相机。

💡 作者与贡献

  • 作者: 张家铨，王文钊 - 华南师范大学

在插入您的两个 USB 摄像头后，运行以下脚本以检查摄像头的端口号，切记摄像头避免插在USB Hub上，USB Hub速率太慢会导致读不到图像数据。

lerobot-find-cameras opencv # or realsense for Intel Realsense cameras

终端将打印出以下信息。以我的笔记本为例，笔记本摄像头为Camera0和Camera1，index_or_path分别为2和4。

--- Detected Cameras ---
Camera #0:
  Name: OpenCV Camera @ /dev/video2
  Type: OpenCV
  Id: /dev/video2
  Backend api: V4L2
  Default stream profile:
    Format: 0.0
    Width: 640
    Height: 480
    Fps: 30.0
--------------------
Camera #1:
  Name: OpenCV Camera @ /dev/video4
  Type: OpenCV
  Id: /dev/video4
  Backend api: V4L2
  Default stream profile:
    Format: 0.0
    Width: 640
    Height: 360
    Fps: 30.0
--------------------

Finalizing image saving...
Image capture finished. Images saved to outputs/captured_images

您可以在 outputs/images_from_opencv_cameras 目录中找到每个摄像头拍摄的图片，并确认不同位置摄像头对应的端口索引信息。

确认外接摄像头后，将摄像头信息替换下方cameras信息您将能够在遥操作时在计算机上显示摄像头：

Violin&Viola:

lerobot-teleoperate \
    --robot.type=lerobot_robot_viola \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraiviola_arm \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --teleop.type=lerobot_teleoperator_violin \
    --teleop.port=/dev/ttyUSB0 \
    --teleop.id=my_awesome_staraiviolin_arm \
    --display_data=true

Violin&Cello:

lerobot-teleoperate \
    --robot.type=lerobot_robot_cello \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraicello_arm \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --teleop.type=lerobot_teleoperator_violin \
    --teleop.port=/dev/ttyUSB0 \
    --teleop.id=my_awesome_staraiviolin_arm \
    --display_data=true
双臂

Violin&Viola:

lerobot-teleoperate \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_viola \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.id=bi_starai_viola_follower \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --teleop.type=lerobot_teleoperator_bimanual_leader \
    --teleop.left_arm_port=/dev/ttyUSB0 \
    --teleop.right_arm_port=/dev/ttyUSB2 \
    --teleop.id=bi_starai_violin_leader \
    --display_data=true

Violin&Cello:

lerobot-teleoperate \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_cello \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.id=bi_starai_cello_follower \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --teleop.type=lerobot_teleoperator_bimanual_leader \
    --teleop.left_arm_port=/dev/ttyUSB0 \
    --teleop.right_arm_port=/dev/ttyUSB2 \
    --teleop.id=bi_starai_violin_leader \
    --display_data=true
tip

如果遇到此错误 AttributeError: module 'rerun' has no attribute 'scalar'. Did you mean: 'scalars'?。

你可以降低rerun版本来解决。

pip3 install rerun-sdk==0.23

数据集制作采集​

一旦您熟悉了遥操作，您就可以开始您的第一个数据集。

如果您想使用 Hugging Face Hub 的功能来上传您的数据集，并且您之前尚未这样做，请确保您已使用具有写入权限的令牌登录，该令牌可以从 Hugging Face 设置 中生成：

huggingface-cli login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential

将您的 Hugging Face 仓库名称存储在一个变量中，以运行以下命令：

HF_USER=$(huggingface-cli whoami | head -n 1)
echo $HF_USER

记录 10 个回合并上传数据集到 Hub：

Violin&Viola:

lerobot-record \
    --robot.type=lerobot_robot_viola \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraiviola_arm \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --teleop.type=lerobot_teleoperator_violin \
    --teleop.port=/dev/ttyUSB0 \
    --teleop.id=my_awesome_staraiviolin_arm \
    --display_data=true \
    --dataset.repo_id=starai/record-test \
    --dataset.episode_time_s=30 \
    --dataset.reset_time_s=30 \
    --dataset.num_episodes=10 \
    --dataset.push_to_hub=True \
    --dataset.single_task="Grab the black cube"

Violin&Cello:

lerobot-record \
    --robot.type=lerobot_robot_cello \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraicello_arm \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --teleop.type=lerobot_teleoperator_violin \
    --teleop.port=/dev/ttyUSB0 \
    --teleop.id=my_awesome_staraiviolin_arm \
    --display_data=true \
    --dataset.repo_id=starai/record-test \
    --dataset.episode_time_s=30 \
    --dataset.reset_time_s=30 \
    --dataset.num_episodes=10 \
    --dataset.push_to_hub=True \
    --dataset.single_task="Grab the black cube"
双臂

Violin&Viola:

lerobot-record \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_viola \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.id=bi_starai_viola_follower \
    --teleop.type=lerobot_teleoperator_bimanual_leader \
    --teleop.left_arm_port=/dev/ttyUSB0 \
    --teleop.right_arm_port=/dev/ttyUSB2 \
    --teleop.id=bi_starai_violin_leader \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --display_data=true \
    --dataset.repo_id=starai/record-test_bi_arm \
    --dataset.episode_time_s=30 \
    --dataset.reset_time_s=30 \
    --dataset.num_episodes=10 \
    --dataset.push_to_hub=True \
    --dataset.single_task="Grab the black cube"

Violin&Cello:

lerobot-record \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_cello \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.id=bi_starai_cello_follower \
    --teleop.type=lerobot_teleoperator_bimanual_leader \
    --teleop.left_arm_port=/dev/ttyUSB0 \
    --teleop.right_arm_port=/dev/ttyUSB2 \
    --teleop.id=bi_starai_violin_leader \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --display_data=true \
    --dataset.repo_id=starai/record-test_bi_arm \
    --dataset.episode_time_s=30 \
    --dataset.reset_time_s=30 \
    --dataset.num_episodes=10 \
    --dataset.push_to_hub=True \
    --dataset.single_task="Grab the black cube"
tip

如果你不想使用 Hugging Face Hub 的上传数据集功能，可以选择 --dataset.push_to_hub=false。同时将 --dataset.repo_id=${HF_USER}/starai 替换为一个自定义的本地文件夹名称，例如 --dataset.repo_id=starai/record-test。数据将存储在系统主目录下的 ~/.cache/huggingface/lerobot。

不上传到Hub:

Violin&Viola:

lerobot-record \
    --robot.type=lerobot_robot_viola \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraiviola_arm \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --teleop.type=lerobot_teleoperator_violin \
    --teleop.port=/dev/ttyUSB0 \
    --teleop.id=my_awesome_staraiviolin_arm \
    --display_data=true \
    --dataset.repo_id=starai/record-test \
    --dataset.episode_time_s=30 \
    --dataset.reset_time_s=30 \
    --dataset.num_episodes=10 \
    --dataset.push_to_hub=False \
    --dataset.single_task="Grab the black cube"

Violin&Cello:

lerobot-record \
    --robot.type=lerobot_robot_cello \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraicello_arm \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --teleop.type=lerobot_teleoperator_violin \
    --teleop.port=/dev/ttyUSB0 \
    --teleop.id=my_awesome_staraiviolin_arm \
    --display_data=true \
    --dataset.repo_id=starai/record-test \
    --dataset.episode_time_s=30 \
    --dataset.reset_time_s=30 \
    --dataset.num_episodes=10 \
    --dataset.push_to_hub=False \
    --dataset.single_task="Grab the black cube"
双臂

Violin&Viola:

lerobot-record \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_viola \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.id=bi_starai_viola_follower \
    --teleop.type=lerobot_teleoperator_bimanual_leader \
    --teleop.left_arm_port=/dev/ttyUSB0 \
    --teleop.right_arm_port=/dev/ttyUSB2 \
    --teleop.id=bi_starai_violin_leader \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --display_data=true \
    --dataset.repo_id=starai/record-test_bi_arm \
    --dataset.episode_time_s=30 \
    --dataset.reset_time_s=30 \
    --dataset.num_episodes=10 \
    --dataset.push_to_hub=False \
    --dataset.single_task="Grab the black cube"

Violin&Cello:

lerobot-record \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_cello \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.id=bi_starai_cello_follower \
    --teleop.type=lerobot_teleoperator_bimanual_leader \
    --teleop.left_arm_port=/dev/ttyUSB0 \
    --teleop.right_arm_port=/dev/ttyUSB2 \
    --teleop.id=bi_starai_violin_leader \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
    --display_data=true \
    --dataset.repo_id=starai/record-test_bi_arm \
    --dataset.episode_time_s=30 \
    --dataset.reset_time_s=30 \
    --dataset.num_episodes=10 \
    --dataset.push_to_hub=False \
    --dataset.single_task="Grab the black cube"
tip

为了区分单双臂，这里的--dataset.repo_id命名为starai/record-test_bi_arm。

  • record 提供了一套用于在机器人操作过程中捕获和管理数据的工具:

1.数据存储​

  • 数据使用 LeRobotDataset 格式存储，并在录制过程中存储在磁盘上。

2.检查点和恢复​

  • 记录期间会自动创建检查点。
  • 如果出现问题，可以通过使用--resume=true重新运行相同的命令来恢复。恢复录制时，必须设置为要录制的额外集数--dataset.num_episodes，而不是数据集中的目标总剧集数！
  • 要从头开始录制，请手动删除数据集目录。

3.记录参数​

使用命令行参数设置数据记录流：

参数说明
- warmup-time-s: 指初始化时间。
- episode-time-s: 表示每次收集数据的时间。
- reset-time-s: 是每次数据收集之间的准备时间。
- num-episodes: 表示预期收集多少组数据。
- push-to-hub: 决定是否将数据上传到 HuggingFace Hub。

4.录制期间的键盘控制​

使用键盘快捷键控制数据记录流：

  • 按右方向键(→) ： 提前停止当前情节或重置时间,然后移动到下一个。

  • 按左方向键(←) ：取消当前插曲并重新录制。

  • 按ESC：立即停止会话,编码视频并上传数据集。

tip

如果你的键盘按下后没有反应，可能你需要降低你pynput的版本，例如安装个1.6.8版本的。

pip install pynput==1.6.8
tip

在 Linux 上,如果左右箭头键和转义键在数据记录过程中没有任何效果,请确保已设置$DISPLAY环境变量。参见 pynput 限制。

一旦你熟悉了数据记录,你就可以创建一个更大的数据集进行训练。一个好的开始任务是抓住一个物体在不同的位置,并把它放在一个小盒子里。我们建议录制至少50集,每个地点10集。保持相机固定,并在整个录制中保持一致的抓握行为。还要确保你操纵的对象在相机上可见。一个好的经验法则是,你应该能够只看相机图像自己完成任务。

重播一个回合​

现在尝试在您的机器人上重播第一个回合:

Viola:

lerobot-replay \
    --robot.type=lerobot_robot_viola \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraiviola_arm \
    --dataset.repo_id=starai/record-test \
    --dataset.episode=1 # choose the episode you want to replay

Cello:

lerobot-replay \
    --robot.type=lerobot_robot_cello \
    --robot.port=/dev/ttyUSB1 \
    --robot.id=my_awesome_staraicello_arm \
    --dataset.repo_id=starai/record-test \
    --dataset.episode=1 # choose the episode you want to replay
双臂

Viola:

lerobot-replay \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_viola \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.id=bi_starai_viola_follower \
    --dataset.repo_id=starai/record-test_bi_arm \
    --dataset.episode=0 # choose the episode you want to replay

Cello:

lerobot-replay \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_cello \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.id=bi_starai_cello_follower \
    --dataset.repo_id=starai/record-test_bi_arm \
    --dataset.episode=0 # choose the episode you want to replay

训练​

要训练一个控制您机器人策略，以下是一个示例命令：

Viola:

lerobot-train \
  --dataset.repo_id=starai/record-test \
  --policy.type=act \
  --output_dir=outputs/train/act_viola_test \
  --job_name=act_viola_test \
  --policy.device=cuda \
  --wandb.enable=False \
  --policy.repo_id=starai/my_policy \
  --steps=200000

Cello:

lerobot-train \
  --dataset.repo_id=starai/record-test \
  --policy.type=act \
  --output_dir=outputs/train/act_cello_test \
  --job_name=act_cello_test \
  --policy.device=cuda \
  --wandb.enable=False \
  --policy.repo_id=starai/my_policy \
  --steps=200000
双臂

Viola:

lerobot-train \
  --dataset.repo_id=starai/record-test_bi_arm \
  --policy.type=act \
  --output_dir=outputs/train/act_bi_viola_test \
  --job_name=act_bi_viola_test \
  --policy.device=cuda \
  --wandb.enable=False \
  --policy.repo_id=starai/my_policy \
  --steps=200000

Cello:

lerobot-train \
  --dataset.repo_id=starai/record-test_bi_arm \
  --policy.type=act \
  --output_dir=outputs/train/act_bi_cello_test \
  --job_name=act_bi_cello_test \
  --policy.device=cuda \
  --wandb.enable=False \
  --policy.repo_id=starai/my_policy \
  --steps=200000
  1. --policy.type支持输入diffusion,pi0,pi0fast等策略
  2. 我们提供了数据集作为参数。dataset.repo_id=starai/record-test
  3. 我们将从 configuration_act.py 加载配置。重要的是，此策略将自动适应机器人的电机状态、电机动作和相机的数量，并保存在您的数据集中。
  4. 我们提供了 wandb.enable=true 来使用 Weights and Biases 可视化训练图表。这是可选的，但如果您使用它，请确保您已通过运行 wandb login 登录。

从某个检查点恢复训练。

Viola:

lerobot-train \
  --config_path=outputs/train/act_viola_test/checkpoints/last/pretrained_model/train_config.json \
  --resume=true \
  --steps=400000

Cello:

lerobot-train \
  --config_path=outputs/train/act_cello_test/checkpoints/last/pretrained_model/train_config.json \
  --resume=true \
  --steps=400000
如果训练SmolVLA 
pip install -e ".[smolvla]"

训练​

lerobot-train \
  --policy.path=lerobot/smolvla_base \ # <- Use pretrained fine-tuned model
  --dataset.repo_id=${HF_USER}/mydataset \
  --batch_size=64 \
  --steps=20000 \
  --output_dir=outputs/train/my_smolvla \
  --job_name=my_smolvla_training \
  --policy.device=cuda \
  --wandb.enable=true

验证​

lerobot-record \
  --robot.type=starai_viola \
  --robot.port=/dev/ttyUSB1 \
  --robot.id=my_awesome_staraiviola_arm \
  --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 1280, height: 720, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 1280, height: 720, fps: 30}}" \
  --dataset.single_task="Grasp a lego block and put it in the bin." \ # <- Use the same task description you used in your dataset recording
  --dataset.repo_id=${HF_USER}/eval_DATASET_NAME_test \ 
  --dataset.episode_time_s=50 \
  --dataset.num_episodes=10 \
  # <- Teleop optional if you want to teleoperate in between episodes \
  # --teleop.type=so100_leader \
  # --teleop.port=/dev/ttyACM0 \
  # --teleop.id=my_red_leader_arm \
  --policy.path=HF_USER/FINETUNE_MODEL_NAME # <- Use your fine-tuned model
如果训练 Libero

LIBERO 是一个旨在研究终身机器人学习的基准。这个想法是，机器人不仅会在工厂中进行一次预训练，而且随着时间的推移，它们需要不断学习和适应人类用户。这种持续的适应被称为决策终身学习 （LLDM）， 它是构建成为真正个性化帮手的机器人的关键一步。

LIBERO 包括五个任务 ：

  • LIBERO-Spatial （libero_spatial） – 需要推理空间关系的任务。

  • LIBERO-Object （libero_object） – 以作不同对象为中心的任务。

  • LIBERO-Goal （libero_goal） – 机器人必须适应不断变化的目标的目标条件任务。

  • LIBERO-90 （libero_90） – LIBERO-100 集合中的 90 个短期任务。

  • LIBERO-Long （libero_10） – LIBERO-100 系列中的 10 个长期任务。

这些套件总共涵盖 130 项任务 ，从简单的对象作到复杂的多步骤场景。LIBERO 旨在随着时间的推移而发展，并作为社区可以测试和改进终身学习算法的共享基准。

训练​

lerobot-train \
  --policy.type=smolvla \
  --policy.repo_id=${HF_USER}/libero-test \
  --dataset.repo_id=HuggingFaceVLA/libero \
  --env.type=libero \
  --env.task=libero_10 \
  --output_dir=./outputs/ \
  --steps=100000 \
  --batch_size=4 \
  --eval.batch_size=1 \
  --eval.n_episodes=1 \
  --eval_freq=1000 \

评估​

要安装 LIBERO，请按照 LeRobot 官方说明进行作，只需执行： pip install -e ".[libero]"

单任务评估:​

lerobot-eval \
  --policy.path="your-policy-id" \
  --env.type=libero \
  --env.task=libero_object \
  --eval.batch_size=2 \
  --eval.n_episodes=3

  • --env.task 选择任务 (libero_object, libero_spatial, etc.).

  • --eval.batch_size 控制并行运行的环境数量。

  • --eval.n_episodes 设置总共要运行的剧集数。

多任务评估​

lerobot-eval \
  --policy.path="your-policy-id" \
  --env.type=libero \
  --env.task=libero_object,libero_spatial \
  --eval.batch_size=1 \
  --eval.n_episodes=2
  • 将逗号分隔的列表传递给 --env.task 以进行多套件评估。

评估​

运行以下命令记录 10 个评估回合：

Viola:

lerobot-record  \
  --robot.type=lerobot_robot_viola \
  --robot.port=/dev/ttyUSB1 \
  --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
  --robot.id=my_awesome_staraiviola_arm \
  --display_data=false \
  --dataset.repo_id=starai/eval_record-test \
  --dataset.single_task="Put lego brick into the transparent box" \
  --policy.path=outputs/train/act_viola_test/checkpoints/last/pretrained_model
  # <- Teleop optional if you want to teleoperate in between episodes \
  # --teleop.type=lerobot_teleoperator_violin \
  # --teleop.port=/dev/ttyUSB0 \
  # --teleop.id=my_awesome_leader_arm \

Cello:

lerobot-record  \
  --robot.type=lerobot_robot_cello \
  --robot.port=/dev/ttyUSB1 \
  --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video4, width: 640, height: 480, fps: 30}}" \
  --robot.id=my_awesome_staraicello_arm \
  --display_data=false \
  --dataset.repo_id=starai/eval_record-test \
  --dataset.single_task="Put lego brick into the transparent box" \
  --policy.path=outputs/train/act_viola_test/checkpoints/last/pretrained_model
  # <- Teleop optional if you want to teleoperate in between episodes \
  # --teleop.type=lerobot_teleoperator_violin \
  # --teleop.port=/dev/ttyUSB0 \
  # --teleop.id=my_awesome_leader_arm \
双臂

Viola:

lerobot-record  \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_viola \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video0, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30}}" \
    --robot.id=bi_starai_viola_follower \
    --display_data=false \
    --dataset.repo_id=starai/eval_record-test_bi_arm \
    --dataset.single_task="test" \
    --policy.path=outputs/train/act_bi_viola_test/checkpoints/last/pretrained_model

Cello:

lerobot-record  \
    --robot.type=lerobot_robot_bimanual_follower \
    --robot.arm_name=starai_cello \
    --robot.left_arm_port=/dev/ttyUSB1 \
    --robot.right_arm_port=/dev/ttyUSB3 \
    --robot.cameras="{ up: {type: opencv, index_or_path: /dev/video0, width: 640, height: 480, fps: 30},front: {type: opencv, index_or_path: /dev/video2, width: 640, height: 480, fps: 30}}" \
    --robot.id=bi_starai_cello_follower \
    --display_data=false \
    --dataset.repo_id=starai/eval_record-test_bi_arm \
    --dataset.single_task="test" \
    --policy.path=outputs/train/act_bi_cello_test/checkpoints/last/pretrained_model

如您所见，这几乎与之前用于记录训练数据集的命令相同，注意几处变化：

  1. --policy.path 参数，指示您的策略训练结果权重文件的路径（例如 outputs/train/act_viola_test/checkpoints/last/pretrained_model）。如果您将模型训练结果权重文件上传到 Hub，也可以使用模型仓库（例如 ${HF_USER}/starai）。
  2. 评估数据集的名称dataset.repo_id以 eval_ 开头，这个操作会在你评估的时候为你单独录制评估时候的视频和数据，将保存在eval_开头的文件夹下，例如starai/eval_record-test。
  3. 如果评估阶段遇到File exists: 'home/xxxx/.cache/huggingface/lerobot/xxxxx/starai/eval_xxxx'请先删除eval_开头的这个文件夹再次运行程序。
  4. 当遇到mean is infinity. You should either initialize with stats as an argument or use a pretrained model请注意--robot.cameras这个参数中的up和front等关键词必须和采集数据集的时候保持严格一致。

FAQ​

  • 如果使用本文档教程，请git clone本文档推荐的github仓库https://github.com/servodevelop/lerobot.git。

  • 如果遥操作正常，而带Camera的遥操作无法显示图像界面，请参考这里

  • 如果在数据集遥操作过程中出现libtiff的问题，请更新libtiff版本。

    conda install libtiff==4.5.0  #for Ubuntu 22.04 is libtiff==4.5.1

  • 执行完安装LeRobot可能会自动卸载gpu版本的pytorch，所以需要在手动安装torch-gpu。

  • 对于Jetson，请先安装Pytorch和Torchvsion再执行conda install -y -c conda-forge ffmpeg,否则编译torchvision的时候会出现ffmpeg版本不匹配的问题。

  • 在3060的8G笔记本上训练ACT的50组数据的时间大概为6小时，在4090和A100的电脑上训练50组数据时间大概为2~3小时。

  • 数据采集过程中要确保摄像头位置和角度和环境光线的稳定，并且减少摄像头采集到过多的不稳定背景和行人，否则部署的环境变化过大会导致机械臂无法正常抓取。

  • 数据采集命令的num-episodes要确保采集数据足够，不可中途手动暂停，因为在数据采集结束后才会计算数据的均值和方差，这在训练中是必要的数据。

  • 如果程序提示无法读取USB摄像头图像数据，请确保USB摄像头不是接在Hub上的，USB摄像头必须直接接入设备，确保图像传输速率快。

参考文档​

lerobot starai github: lerobot starai

StarAI Robot Arm ROS2 Moveit2: star-arm-moveit2

StarAI机械臂相关性能介绍

StarAI机械臂开箱视频

STEP: STEP

URDF: URDF

Huggingface Project: Lerobot

ACT 或 ALOHA: 使用低成本硬件学习精细双手操作

VQ-BeT: VQ-BeT: 使用潜在动作生成行为

Diffusion Policy: Diffusion Policy

TD-MPC: TD-MPC

技术支持与产品讨论​

感谢您选择我们的产品！我们致力于为您提供多种支持，以确保您使用我们的产品时获得尽可能顺畅的体验。我们提供多种沟通渠道，以满足不同的偏好和需求。

Loading Comments...