Skip to main content

如何从0搭建具身智能最新版Lerobot SO-ARM100和SO-ARM101机械臂并完成自定义抓取任务

tip

本教程已更新至最新版 lerobot,如需查阅旧版教程,请点击此处

SO-10xARM 是由 TheRobotStudio 发起的一个完全开源的机器人手臂项目。它包括从动臂和领导臂手臂,并提供详细的3D打印文件和操作指南。LeRobot 致力于为真实世界的机器人提供 PyTorch 中的模型、数据集和工具。其目标是降低机器人学的入门门槛,使每个人都能通过共享数据集和预训练模型进行贡献和受益。LeRobot 集成了经过验证的前沿方法,专注于模仿学习和强化学习。它提供了一套预训练模型、包含人类收集的示范数据集和仿真环境,使用户无需进行机器人组装即可开始使用。未来几周,计划在当前最具成本效益和性能的机器人上增强对真实世界机器人的支持。

项目介绍

SO-ARM10x 和 reComputer Jetson AI 智能机器人套件无缝结合了高精度的机器人手臂控制与强大的 AI 计算平台,提供了全面的机器人开发解决方案。该套件基于 Jetson Orin 或 AGX Orin 平台,结合 SO-ARM10x 机器人手臂和 LeRobot AI 框架,为用户提供适用于教育、科研和工业自动化等多种场景的智能机器人系统。

本维基提供了 SO ARM10x 的组装和调试教程,并在 Lerobot 框架内实现数据收集和训练。

caution

Seeed Studio 仅对硬件质量负责。教程严格按官方文档更新,如遇无法解决的软件或环境问题,请先查阅文末FAQ,或者联系客服加入SeeedStudio Lerobot交流群询问,也可以在这里询问:LeRobot GitHubDiscord频道

🔧 SO-ARM10x 系列特点:

  1. 开源 & 低成本
    本系列由 TheRobotStudio 提供,是一套开源、低成本的机器人臂解决方案。

  2. 支持 LeRobot 平台集成
    专为与 LeRobot 平台 集成而设计。该平台提供 PyTorch 模型、数据集与工具,面向现实机器人任务的模仿学习(包括数据采集、仿真、训练与部署)。

  3. 丰富的学习资源
    提供全面的开源学习资源,包括组装与校准指南、测试与数据采集教程、训练与部署文档,帮助用户快速上手并开发机器人应用。

  4. 兼容 Nvidia 平台
    支持通过 reComputer Mini J4012 Orin NX 16GB 平台进行部署。

🆕 更新内容:

  • 布线优化:与 SO-ARM100 相比,SO-ARM101 在布线方面进行了改进,解决了先前第3关节处可能出现断线的问题。新的布线设计也不再限制关节的活动范围。
  • 主臂齿轮比优化:主臂现在采用了经过优化的齿轮比电机,无需外部减速机构,同时提升了性能。
  • 新增功能支持:主臂现在可以实时跟随从臂动作,这对即将引入的策略尤为关键,可实现人类实时干预并修正机器动作。

规格参数

本教程硬件由矽递科技Seeed Studio提供

类型SO-ARM100SO-ARM101
标准版专业版标准版专业版
Leader Arm12个 ST-3215- C001 (7.4V) 1:345 齿轮比电机,适用于所有关节12个 ST-3215-C018/ST-3215-C047 (12V) 1:345 齿轮比电机,适用于所有关节

1个 ST-3215- C001 (7.4V) 1:345 齿轮比电机,仅用于第2号关节
2个 ST-3215-C044 (7.4V) 1:191 齿轮比电机,用于第1号和第3号关节
3个 ST-3215-C046 (7.4V) 1:147 齿轮比电机,用于第4号、第5号关节及第6号夹爪

Follower Arm与SO-ARM100相同
电源5.5 mm×2.1 mm DC 5 V 4 A5.5 mm×2.1 mm DC 12 V 2 A5.5 mm×2.1 mm DC 5 V 4 A

5.5 mm×2.1 mm DC 12 V 2 A(从臂Follower)
5.5 mm×2.1 mm DC 5 V 4 A(主臂Leader)

角度传感器12位磁编码器
推荐工作温度范围0 °C ~ 40 °C
通信方式UART
控制方式PC
danger

若购买 SO101 Arm Kit 标准版,所有电源均为5V。若购买 SO101 Arm Kit Pro 版,Leader机械臂的校准及每一步骤均使用5V电源,Follower机械臂的校准及每一步骤均使用12V电源。

材料清单(BOM)

部件数量是否包含
舵机12
舵机驱动板2
USB-C线缆(2条)1
电源适配器2
3D打印桌面夹具4
手臂的3D打印部件1Option

初始系统环境

For Ubuntu X86:

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

For Jetson Orin:

  • Jetson Jetpack 6.0+
  • Python 3.10
  • Torch 2.6

步骤目录

3D打印参考参数

caution

随着2025年4月28日官方发布 SO101,SO100 将不再支持打印指导,但源文件仍可在我们的 Makerworld 找到。不过,对于之前购买了SO100 的用户,教程和安装方法以及代码依然兼容。SO101 的打印件也完全兼容 SO100 的电机套件安装。

第一步:选择打印机

提供的 STL 文件可以直接在许多 FDM 打印机上打印。以下是经过测试并推荐的设置,但其他设置也可能适用。

  • 材料:PLA+
  • 喷嘴直径与精度:0.4mm 喷嘴直径,层高 0.2mm,或 0.6mm 喷嘴直径,层高 0.4mm。
  • 填充密度:15%

第二步:设置打印机

  • 确保打印机已校准且打印床水平调整正确,具体操作请参考打印机说明书。
  • 清洁打印床,确保无灰尘或油污。如果使用水或其他液体清洁打印床,请确保彻底干燥。
  • 如果打印机建议,使用标准胶棒在打印区域涂抹一层薄薄的均匀胶水,避免结块或涂抹不均。
  • 按照打印机说明书装载打印机耗材(线材)。
  • 确保打印机设置与上述推荐参数匹配(大多数打印机有多种设置选项,请选择最接近的)。
  • 设置支撑:支撑应设置为“处处需要”,但忽略与水平面小于 45 度的倾斜面。
  • 水平轴方向的螺丝孔内不应有支撑结构。

第三步:打印零件

所有关于 Leader 或 Follower 的零件都已经排版好,方便 3D 打印,且朝 Z 轴正方向摆放,以最小化支撑需求。

  • 对于打印床尺寸为 220mm x 220mm(如 Ender)的打印机,请打印以下文件:

  • 对于打印床尺寸为 205mm x 250mm(如 Prusa/Up)的打印机,请打印以下文件:

安装 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
  1. 创建并激活一个新的 conda 环境用于 lerobot
conda create -y -n lerobot python=3.10 && conda activate lerobot
  1. 克隆 Lerobot 仓库:
git clone https://github.com/Seeed-Projects/lerobot.git ~/lerobot
  1. 使用 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 确认。
  1. 安装带有 feetech 电机依赖的 LeRobot:
cd ~/lerobot && pip install -e ".[feetech]"

对于 Jetson Jetpack 6.2 设备(请确保在执行此步骤前按照此链接教程第 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 兼容
  1. 检查 Pytorch 和 Torchvision

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

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

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

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

校准舵机并组装机械臂

danger

由于官方代码和舵机厂家固件升级,2025年6月30日之前的用户请先下载飞特官方上位机(Windows系统下),上电连接所有舵机,选择对应的端口号->波特率1000000->打开->搜索,搜索到所有的舵机后点击升级->在线检测->升级固件,确保固件版本从3.9升级到3.10版本,避免出现后续问题。

note

如果更新固件失败后无法再次识别到改舵机,可以拿另一个可以识别的舵机单独链接到上位机,然后电机扫描和固件在线检测,这时保持当前窗口,立刻断开当前舵机,连上无法识别的舵机,并且在1秒内点击在线升级即可,若失败可以多次尝试。

SO101的舵机校准初始化与SO100方法和代码一致的,这里只是需要注意SO101的Leader机械臂的前三个关节减速比与SO100不同,所以需要仔细区分并校准。建议方便起见,在每个电机上做好标记,注明是 Follower(用 F 表示)还是 Leader(用 L 表示),以及对应的编号从 1 到 6(例如 F1...F6 和 L1...L6)。后续我们用F1-F6来代表Follower机械臂的1到6的关节舵机,L1-L6来代表Leader机械臂从1到6的关节舵机,对应的舵机型号关节及减速比信息如下。

舵机型号减速比对应机械臂关节
ST-3215-C044(7.4V)1:191L1
ST-3215-C001(7.4V)1:345L2
ST-3215-C044(7.4V)1:191L3
ST-3215-C046(7.4V)1:147L4–L6
ST-3215-C001(7.4V) / C018(12V) / C047(12V)1:345F1–F6
danger

现在你需要将 5V 或 12V 电源连接到电机总线上。对于 STS3215 7.4V 电机使用 5V 电源,对于 STS3215 12V 电机使用 12V 电源。请注意,Leader 机械臂始终使用 7.4V 电机,因此如果你同时有 12V 和 7.4V 电机,一定要使用正确的电源,否则可能会烧坏电机!然后,通过 USB 将电机总线连接到你的电脑。请注意,USB 不会为电机供电,因此电源和 USB 都必须连接。

danger

如果你买的是SO101的标准版,则使用5V电源进行Leader舵机校准(ST-3215-C046, C044, C001).

Leader机械臂1号舵机校准Leader机械臂2号舵机校准Leader机械臂3号舵机校准Leader机械臂4号舵机校准Leader机械臂5号舵机校准Leader机械臂6号舵机校准
fig1fig2fig3fig4fig5fig6
danger

如果你买的是SO101的Pro版,则使用12V电源进行Follower舵机校准(ST-3215-C047/ST-3215-C018),如果是SO101标准版则使用5V进行舵机校准(ST-3215-C001).

Follower机械臂1号舵机校准Follower机械臂2号舵机校准Follower机械臂3号舵机校准Follower机械臂4号舵机校准Follower机械臂5号舵机校准Follower机械臂6号舵机校准
fig1fig2fig3fig4fig5fig6
tip

再次提醒,请确保舵机关节 ID 和齿轮比与 SO-ARM101 的严格对应。

以下是代码校准步骤,请参照上图中接线舵机进行校准

查找机械臂对应的 USB 端口 为了找到每个机械臂正确的端口,请运行实用脚本两次:

python -m lerobot.find_port

示例输出:

Finding all available ports for the MotorBus.
['/dev/ttyACM0', '/dev/ttyACM1']
Remove the usb cable from your MotorsBus and press Enter when done.

[...Disconnect corresponding leader or follower arm and press Enter...]

The port of this MotorsBus is /dev/ttyACM1
Reconnect the USB cable.
tip

请记住要拔出 USB 接头,否则将无法检测到接口。

识别领导臂端口时的示例输出(例如,在 Mac 上为 /dev/tty.usbmodem575E0031751,或在 Linux 上可能为 /dev/ttyACM0): 识别跟从懂端口时的示例输出(例如,在 Mac 上为 /dev/tty.usbmodem575E0032081,或在 Linux 上可能为 /dev/ttyACM1):

故障排除:在 Linux 上,你可能需要通过运行以下命令来赋予 USB 端口访问权限:

sudo chmod 666 /dev/ttyACM0
sudo chmod 666 /dev/ttyACM1

配置舵机

将 USB 线从电脑连接到从动臂的舵机驱动板,并接通电源。然后,运行以下命令。

python -m lerobot.setup_motors \
--robot.type=so101_follower \
--robot.port=/dev/tty.usbmodem585A0076841 # <- paste here the port found at previous step

您会看到以下输出。

Connect the controller board to the 'gripper' motor only and press enter.

依照指示,连接夹爪的舵机。请确保它是唯一连接到舵机驱动板的舵机,并且该舵机尚未与其他任何舵机进行连接。当您按下 [Enter] 键后,脚本将自动设置该舵机的 ID 和波特率。

之后,您应该会看到以下信息:

'gripper' motor id set to 6

接着是下一条输出是:

Connect the controller board to the 'wrist_roll' motor only and press enter.

您可以从驱动板上断开 3 针接口,但可以将其留在夹爪舵机另一端,因为它已经在正确的位置了。现在,将另一根 3 针接口插入腕部旋转舵机,并将其连接到驱动板。与之前的舵机一样,请确保它是唯一连接到驱动板的舵机,并且舵机本身没有连接到任何其他舵机。

caution

根据指示,对每个舵机重复上述操作。

在每次按 Enter 键之前,请务必检查您的线缆连接。例如,在操作电路板时,电源线可能会断开。

当您完成所有步骤后,脚本将自动结束,此时舵机即可投入使用。现在,您可以将每根舵机的 3 针接口依次连接,并将第一个舵机(ID 为 1 的“shoulder pan”舵机)的线缆连接到驱动板。现在可以将驱动板安装到机械臂的底座上。

对领导臂重复相同的步骤。

python -m lerobot.setup_motors \
--teleop.type=so101_leader \
--teleop.port=/dev/tty.usbmodem575E0031751 # <- paste here the port found at previous step

组装教程

tip
  • SO-ARM101 双臂的组装过程与 SO-ARM100 相同。唯一的区别在于 SO-ARM101 增加了线缆夹,且主机械臂(Leader Arm)关节舵机的齿轮比不同。因此,SO100 和 SO101 都可以参考以下内容进行安装。
  • 组装前,请再次检查您的电机型号和减速比。如果您购买的是 SO100,可以忽略此步骤。如果您购买的是 SO101,请参考下表区分 F1 至 F6 和 L1 至 L6。
Servo ModelGear RatioCorresponding Joints
ST-3215-C044(7.4V)1:191L1
ST-3215-C001(7.4V)1:345L2
ST-3215-C044(7.4V)1:191L3
ST-3215-C046(7.4V)1:147L4–L6
ST-3215-C001(7.4V) / C018(12V) / C047(12V)1:345F1–F6
danger

如果您购买的是 SO101 机械臂套件标准版,所有电源均为 5V。如果您购买的是 SO101 机械臂套件专业版,则主机械臂(Leader Arm)在每个校准和操作步骤中应使用 5V 电源,而随动臂(Follower Arm)在每个校准和操作步骤中应使用 12V 电源。

组装领导臂

Step 1Step 2Step 3Step 4Step 5Step 6
fig1fig2fig3fig4fig5fig6
Step 7Step 8Step 9Step 10Step 11Step 12
fig1fig2fig3fig4fig5fig6
Step 13Step 14Step 15Step 16Step 17Step 18
fig1fig2fig3fig4fig5fig6
Step 19Step 20
fig1fig2

组装从动臂

tip
  • 从动臂的组装步骤与领导臂基本相同。唯一的区别在于第12步之后,末端执行器(夹爪和手柄)的安装方式有所不同。
Step 1Step 2Step 3Step 4Step 5Step 6
fig1fig2fig3fig4fig5fig6
Step 7Step 8Step 9Step 10Step 11Step 12
fig1fig2fig3fig4fig5fig6
Step 13Step 14Step 15Step 16Step 17
fig1fig2fig3fig4fig5

校准机械臂

tip

SO100 和 SO101 的代码是兼容的。SO100 用户可以直接使用 SO101 的参数和代码进行操作。

danger

若购买 SO101 Arm Kit 标准版,所有电源均为5V。若购买 SO101 Arm Kit Pro 版,Leader机械臂的校准及每一步骤均使用5V电源,Follower机械臂的校准及每一步骤均使用12V电源。

接下来,你需要对你的 SO-10x 机器人接上电源和数据线进行校准,以确保在相同的物理位置时,Leader 臂和 Follower 臂的位置信息一致。这个校准过程至关重要,因为它可以让在一个 SO-10x 机器人上训练的神经网络在另一个机器人上也能正常工作。如果需要重新校准机械臂,请删除 ~/lerobot/.cache/huggingface/calibration/so101 文件夹。

从动臂手动校准

请通过 3 针接口连接 6 个机器人舵机的接口,并将底盘舵机连接到舵机驱动板,然后运行以下命令或 API 示例来校准机械臂:

接口授权

首先,您需要授予接口权限,运行以下命令:

sudo chmod 666 /dev/ttyACM*

然后校准从动臂

接下来,通过运行以下 Python 命令来校准从动臂:

python -m lerobot.calibrate \
--robot.type=so101_follower \
--robot.port=/dev/tty.usbmodem58760431551 \ # <- 您的机器人接口
--robot.id=my_awesome_follower_arm # <- 给机器人一个独一无二的名称

下面的视频演示了如何执行校准。首先,您需要将机器人移动到所有关节都位于其活动范围中间的位置。然后,按下回车键后,您必须将每个关节在其完整的运动范围内移动。

领导臂手动校准

对主机械臂进行校准的步骤与上述相同,请运行以下命令或 API 示例:

python -m lerobot.calibrate \
--teleop.type=so101_leader \
--teleop.port=/dev/tty.usbmodem58760431551 \ # <- 您的机器人接口
--teleop.id=my_awesome_leader_arm # <- 给机器人一个独一无二的名称

遥控操作

现在,您就可以遥控操作您的机器人了!运行这个简单的脚本(它不会连接和显示摄像头):

请注意,与机器人关联的 ID 用于存储校准文件。在使用相同设置进行遥控操作、录制和评估时,使用相同的 ID 至关重要。

python -m lerobot.teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/tty.usbmodem58760431541 \
--robot.id=my_awesome_follower_arm \
--teleop.type=so101_leader \
--teleop.port=/dev/tty.usbmodem58760431551 \
--teleop.id=my_awesome_leader_arm

遥控操作命令将自动执行以下步骤:

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

添加摄像头

tip

SO100 和 SO101 的代码是兼容的。SO100 用户可以直接使用 SO101 的参数和代码进行操作。

为了实例化摄像头,您需要一个摄像头标识符。这个标识符可能会在您重启电脑或重新插拔摄像头时发生变化,这主要取决于您的操作系统。

要查找连接到您系统的摄像头的摄像头索引,请运行以下脚本:

python -m lerobot.find_cameras opencv # or realsense for Intel Realsense cameras

终端会打印相关摄像头信息。

--- Detected Cameras ---
Camera #0:
Name: OpenCV Camera @ 0
Type: OpenCV
Id: 0
Backend api: AVFOUNDATION
Default stream profile:
Format: 16.0
Width: 1920
Height: 1080
Fps: 15.0
--------------------
(more cameras ...)

您可以在 outputs/captured_images 目录中找到每台摄像头拍摄的图片。

warning

macOS 中使用 Intel RealSense 摄像头时,您可能会遇到 “Error finding RealSense cameras: failed to set power state” 的错误。这可以通过使用 sudo 权限运行相同的命令来解决。请注意,在 macOS 中使用 RealSense 摄像头是不稳定的。

之后,您就可以在遥控操作时在电脑上显示摄像头画面了,只需运行以下代码即可。这对于在录制第一个数据集之前准备您的设置非常有用。

python -m lerobot.teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/tty.usbmodem58760431541 \
--robot.id=my_awesome_follower_arm \
--robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
--teleop.type=so101_leader \
--teleop.port=/dev/tty.usbmodem58760431551 \
--teleop.id=my_awesome_leader_arm \
--display_data=true

如果您有更多摄像头,可以通过更改 --robot.cameras 参数来添加。您应该注意index_or_path 的格式,它由 python -m lerobot.find_cameras opencv 命令输出的摄像头 ID 的最后一位数字决定。

例如,如果你想添加摄像头:

python -m lerobot.teleoperate \
--robot.type=so101_follower \
--robot.port=/dev/tty.usbmodem58760431541 \
--robot.id=my_awesome_follower_arm \
--robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}, side: {type: opencv, index_or_path: 1, width: 1920, height: 1080, fps: 30}}" \
--teleop.type=so101_leader \
--teleop.port=/dev/tty.usbmodem58760431551 \
--teleop.id=my_awesome_leader_arm \
--display_data=true

数据集制作采集

tip

SO100 和 SO101 的代码是兼容的。SO100 用户可以直接使用 SO101 的参数和代码进行操作。

一旦您熟悉了遥操作,您就可以使用 SO-10x 记录您的第一个数据集。

如果您想使用 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

记录 5 个回合并将您的数据集上传到 Hub:

python -m lerobot.record \
--robot.type=so101_follower \
--robot.port=/dev/tty.usbmodem585A0076841 \
--robot.id=my_awesome_follower_arm \
--robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \
--teleop.type=so101_leader \
--teleop.port=/dev/tty.usbmodem58760431551 \
--teleop.id=my_awesome_leader_arm \
--display_data=true \
--dataset.repo_id=${HF_USER}/record-test \
--dataset.num_episodes=5 \
--dataset.single_task="Grab the black cube" \
--dataset.push_to_hub=true \ # You can choose false if you want to save the data locally
--dataset.episode_time_s=30 \
--dataset.reset_time_s=30

你会看到类似如下数据:

INFO 2024-08-10 15:02:58 ol_robot.py:219 dt:33.34 (30.0hz) dtRlead: 5.06 (197.5hz) dtWfoll: 0.25 (3963.7hz) dtRfoll: 6.22 (160.7hz) dtRlaptop: 32.57 (30.7hz) dtRphone: 33.84 (29.5hz)

参数说明

  • episode-time-s: 表示每次收集数据的时间。
  • reset-time-s: 是每次数据收集之间的准备时间。
  • num-episodes: 表示预期收集多少组数据。
  • push-to-hub: 决定是否将数据上传到 HuggingFace Hub。
tip
  • "如果你希望将数据保存在本地 (--dataset.push_to_hub=false),请将 --dataset.repo_id=${HF_USER}/so101_test 替换为一个自定义的本地文件夹名称,例如 --dataset.repo_id=seeed_123/so101_test。数据将存储在系统主目录下的 ~/.cache/huggingface/lerobot."

  • 如果你通过 --dataset.push_to_hub=true 将数据集上传到了 Hugging Face Hub,可以通过 在线可视化你的数据集,只需复制粘贴你的 repo id。

  • 在回合记录过程中任何时候按下右箭头 → 可提前停止并进入重置状态。重置过程中同样,可提前停止并进入下一个回合记录。

  • 在录制或重置到早期阶段时,随时按左箭头 ← 可提前停止当前剧集,并重新录制。

  • 在录制过程中随时按 ESCAPE ESC 可提前结束会话,直接进入视频编码和数据集上传。

  • 注意:你可以通过添加 --control.resume=true 来继续录制。如果你还没有上传数据集,还需要添加 --control.local_files_only=true

  • 一旦你熟悉了数据记录,你就可以创建一个更大的数据集进行训练。一个不错的起始任务是在不同的位置抓取物体并将其放入箱子中。我们建议至少记录 50 个场景,每个位置 10 个场景。保持相机固定,并在整个录制过程中保持一致的抓取行为。同时确保你正在操作的物体在相机视野中可见。一个很好的经验法则是,你应该仅通过查看相机图像就能完成这项任务。

  • 在接下来的章节中,你将训练你的神经网络。在实现可靠的抓取性能后,你可以在数据收集过程中引入更多变化,例如增加抓取位置、不同的抓取技巧以及改变相机位置。

  • 避免快速添加过多变化,因为这可能会阻碍您的结果。

  • 在 Linux 上,如果在数据记录期间左右箭头键和 Esc 键没有效果,请确保您已设置 $DISPLAY 环境变量。参见 pynput 限制

可视化数据集

tip

SO100 和 SO101 的代码是兼容的。SO100 用户可以直接使用 SO101 的参数和代码进行操作。

echo ${HF_USER}/so101_test  

如果您没有使用 --dataset.push_to_hub=false ,并上传了数据,您也可以在本地通过以下命令进行可视化:

python -m lerobot.scripts.visualize_dataset_html \
--repo-id ${HF_USER}/so101_test \

如果您使用了 --dataset.push_to_hub=false ,没有上传数据,您也可以通过以下命令在本地进行可视化:

python -m lerobot.scripts.visualize_dataset_html \
--repo-id seeed_123/so101_test \

这里,seeed_123 是数据收集时自定义的 repo_id 名称。

回放一个数据集

tip

SO100 和 SO101 的代码是兼容的。SO100 的用户可以直接使用 SO101 的参数和代码进行操作。

现在,尝试在您的机器人上重播第一个数据集:

python -m lerobot.replay \
--robot.type=so101_follower \
--robot.port=/dev/tty.usbmodem58760431541 \
--robot.id=my_awesome_follower_arm \
--dataset.repo_id=${HF_USER}/record-test \
--dataset.episode=0 # 选择你要回放的数据集

训练

tip

SO100 和 SO101 的代码是兼容的。SO100 的用户可以直接利用 SO101 的参数和代码进行操作。

要训练一个控制您机器人策略,使用 python -m lerobot.scripts.train 脚本。需要一些参数。以下是一个示例命令:

python -m lerobot.scripts.train \
--dataset.repo_id=${HF_USER}/so101_test \
--policy.type=act \
--output_dir=outputs/train/act_so101_test \
--job_name=act_so101_test \
--policy.device=cuda \
--wandb.enable=true \

如果您想在本地数据集上进行训练,请确保 repo_id 与数据收集时使用的名称匹配,并添加 --policy.push_to_hub=False

命令解释

  • 数据集指定:我们通过 --dataset.repo_id=${HF_USER}/so101_test 参数提供了数据集。
  • 策略类型:我们使用 policy.type=act 提供了策略,这将从 configuration_act.py 加载配置。重要的是,这个策略会自动适应您机器人(例如 laptopphone)的电机状态、电机动作和摄像头数量,这些信息已保存在您的数据集中。
  • 设备选择:我们提供了 policy.device=cuda,因为我们正在 Nvidia GPU 上进行训练,但您可以使用 policy.device=mps 在 Apple Silicon 上进行训练。
  • 可视化工具:我们提供了 wandb.enable=true 来使用 Weights and Biases 可视化训练图表。这是可选的,但如果您使用它,请确保您已通过运行 wandb login 登录。

训练可能需要几个小时。您将在 outputs/train/act_so100_test/checkpoints 目录中找到检查点文件。

要从某个检查点恢复训练,下面是一个从 act_so101_test 策略的最后一个检查点恢复训练的示例命令:

python -m lerobot.scripts.train \
--config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
--resume=true

Upload policy checkpoints

训练完成后,可以使用以下命令上传最新的检查点:

huggingface-cli upload ${HF_USER}/act_so101_test \
outputs/train/act_so101_test/checkpoints/last/pretrained_model

你还可以通过以下方式上传中间检查点:

CKPT=010000
huggingface-cli upload ${HF_USER}/act_so101_test${CKPT} \
outputs/train/act_so101_test/checkpoints/${CKPT}/pretrained_model

评估

tip

SO100 和 SO101 的代码是兼容的。SO100 用户可以直接使用 SO101 的参数和代码进行操作。

您可以使用 lerobot/record.py 中的 record 功能,但需要将策略训练结果权重作为输入。例如,运行以下命令记录 10 个评估回合:

python -m lerobot.record  \
--robot.type=so100_follower \
--robot.port=/dev/ttyACM1 \
--robot.cameras="{ up: {type: opencv, index_or_path: /dev/video10, width: 640, height: 480, fps: 30}, side: {type: intelrealsense, serial_number_or_name: 233522074606, width: 640, height: 480, fps: 30}}" \
--robot.id=my_awesome_follower_arm \
--display_data=false \
--dataset.repo_id=${HF_USER}/eval_so100 \
--dataset.single_task="Put lego brick into the transparent box" \
--policy.path=${HF_USER}/my_policy

如您所见,这几乎与之前用于记录训练数据集的命令相同。只有两处变化:

  1. 增加了 --policy.path 参数,指示您的策略检查点的路径(例如 outputs/train/eval_act_so100_test/checkpoints/last/pretrained_model)。如果您将模型检查点上传到 Hub,也可以使用模型仓库(例如 ${HF_USER}/act_so100_test)。
  2. 数据集的名称以 eval 开头,以反映您正在运行推理(例如 ${HF_USER}/eval_act_so100_test)。

FAQ

  • 如果实用本文档教程,请git clone本文档推荐的github仓库https://github.com/Seeed-Projects/lerobot.git,本文档推荐的仓库是验证过后的稳定版本,Lerobot官方仓库是实时更新的最新版本,会出现一些无法预知的问题,例如数据集版本不同,指令不同等。

  • 如果遇到以下报错,需要检查对应端口号的机械臂是否接通电源,总线舵机是否出现数据线松动或者脱落。

    ConnectionError: Read failed due to comunication eror on port /dev/ttyACM0 for group key Present_Position_Shoulder_pan_Shoulder_lift_elbow_flex_wrist_flex_wrist_roll_griper: [TxRxResult] There is no status packet!
  • 如果你维修或者更换过机械臂零件,请完全删除~/lerobot/.cache/huggingface/calibration/so100文件夹并重新校准机械臂

  • 如果遥操作正常,而带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版本不匹配的问题。

  • 如果出现如下问题,是电脑的不支持此格式的视频编码,需要修改lerobot/lerobot/common/datasets /video_utils.py文件134行vcodec: str = "libsvtav1"的值修改为libx264或者libopenh264,不同电脑参数不同,可以进行尝试。 Issues 705

    [vost#0:0 @ 0x13207240] Unknown encoder 'libsvtav1' [vost#0:0 @ 0x13207240] Error selecting an encoder Error opening output file /home/han/.cache/huggingface/lerobot/lyhhan/so100_test/videos/chunk-000/observation.images.laptop/episode_000000.mp4. Error opening output files: Encoder not found
  • 重要的事!!!如果再执行过程中舵机的数据线松动,请恢复这个舵机到初始位置再重新链接舵机数据线,也可以通过初始化舵机命令单独校准某个舵机,校准单独的舵机的时候确保舵机上只有一个数据线与驱动板相连。如果出现

    Auto-correct calibration of motor 'wrist roll' by shifting value by 1 full turns, from '-270 < -312.451171875 < 270degrees' to'-270<-312.451171875 < 270 degrees'.

    或者校准机械臂过程中的其他关于角度和超出限位值的报错,这个方法依然适用。

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

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

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

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

tip

如果你遇到无法解决的软件问题或环境依赖问题,除了查看本教程末尾的常见问题(FAQ)部分外,请及时在 LeRobot 平台LeRobot Discord 频道 反馈问题。

参考文档

英文文档

TheRobotStudio Project: SO-ARM10x

Huggingface Project: Lerobot

Dnsty: Jetson Containers

Jetson AI Lab

Diffusion Policy

ACT or ALOHA

TDMPC

VQ-BeT

技术支持与产品讨论

感谢您选择我们的产品!我们在此为您提供多种支持,以确保您的产品体验尽可能顺畅。我们提供多种沟通渠道,以满足不同的偏好和需求。

Loading Comments...