具身开发者社区

外观

教程huggingface.co6 天前

LeRobot + SO-101 装配、标定、遥操作与首个数据集录制教程 ​

本文按官方文档整理 SO-101 的实操流程：准备零件并安装 LeRobot，配置 follower 与 leader 电机端口、id 和 baudrate，完成基础装配提示，再通过遥操作自动触发标定，最后登录 Hugging Face Hub 并录制、上传第一条数据集。

AI 整理
  • 本体 SDK 与控制
  • 数据与采集

> 本文依据以下官方文档整理：huggingface.co/docs/lerobot/so101、huggingface.co/docs/lerobot/il_robots。命令与版本以文档当前版本为准。

前置条件 ​

  • SO-101 follower arm：6x STS3215 motors with 1/345 gearing
  • SO-101 leader arm：Base / Shoulder Pan、Shoulder Lift、Elbow Flex、Wrist Flex、Wrist Roll、Gripper 对应文档表格中的 motor 与 gear ratio
  • MotorBus、USB cable、power supply、controller board、3-pin cable
  • 3D-printed parts，并已移除 support material
  • 已按 Installation Guide 安装 LeRobot
  • Hugging Face write-access token，用于上传 dataset

1. 1. 准备 SO-101 零件并安装 LeRobot ​

先按文档中的 README 获取 bill of materials、采购链接和 3D 打印说明。随后按 Installation Guide 安装 LeRobot；此外，SO-101 还需要安装 Feetech SDK。命令如下：

bash
pip install -e ".[feetech]"

2. 2. 查找每个机械臂对应的 USB 端口 ​

将 MotorBus 通过 USB 和电源连接到电脑，运行查找端口脚本；脚本提示时断开对应 MotorBus，再按 Enter。记录输出中的端口，分别对应 leader 或 follower arm。

bash
lerobot-find-port

示例输出会显示 The port of this MotorsBus is /dev/tty.usbmodem575E0032081。

3. 3. 设置 follower 电机 id 与 baudrate ​

新电机通常默认 id 为 1，需要逐个单独连接到 controller board 写入唯一 id 与相同 baudrate。先连接 follower arm 的 USB 和电源，并使用上一步得到的端口运行：

bash
lerobot-setup-motors \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem585A0076841  # <- paste here the port found at previous step

按提示仅连接对应电机，例如 gripper，看到 'gripper' motor id set to 6 后继续下一颗。

4. 4. 设置 leader 电机 id 与 baudrate ​

leader arm 执行同样流程。文档说明 leader 使用不同 gear ratio，以兼顾自重支撑与较小移动阻力。连接 leader arm 的 controller board、USB 与电源后运行：

bash
lerobot-setup-motors \
    --teleop.type=so101_leader \
    --teleop.port=/dev/tty.usbmodem575E0031751  # <- paste here the port found at previous step

每一步按提示只连接一个电机，完成后再将各电机用 3-pin cable 串接。

5. 5. 清理 3D 打印件并开始基础装配 ​

移除 3D-printed parts 上的 support material，文档建议用 small screwdriver 从支撑材料下方撬起。继续装配前，建议在电机放入后安装一根 3-pin cable。Joint 1 需要安装 both motor horns，top horn 用 M3x6mm screw 固定，bottom horn 不需要螺丝；再将 first motor 放入 base，并用 M2x6mm screws 固定。

6. 6. 遥操作 SO-101，并自动触发缺失标定 ​

文档说明 teleoperate command 会自动识别缺失 calibration 并启动 calibration procedure，然后连接 robot 与 teleop device 开始遥操作。注意同一套设备在 teleoperating、recording、evaluating 时要使用相同 id。

bash
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

7. 7. 登录 Hugging Face Hub 并准备数据集命名 ​

录制数据集会使用 Hugging Face hub 上传功能。若此前未使用 Hub，需用 write-access token 通过 CLI 登录；随后把 Hugging Face repository name 存入变量并确认输出。

bash
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
bash
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER

8. 8. 录制并上传第一条 SO-101 数据集 ​

熟悉遥操作后即可录制。下面命令会录制 5 episodes，并上传到 Hub；本例还开启相机与 display_data。数据会本地存储，并默认在录制结束后推送到 Hugging Face 页面。

bash
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.streaming_encoding=true \
    # --dataset.rgb_encoder.vcodec=auto \
    --dataset.encoder_threads=2

验证是否跑通 ​

端口查找时应看到 The port of this MotorsBus is ...；设置电机时应看到类似 'gripper' motor id set to 6，并能继续下一电机提示。遥操作命令会连接 robot 与 teleop device 并开始 teleoperation。录制结束后，本地数据位于 ~/.cache/huggingface/lerobot/{repo-id}，并上传到 Hugging Face 页面；可运行：

bash
echo https://huggingface.co/datasets/${HF_USER}/so101_test

文档里点名的注意事项 ​

  • 如果在设置电机时报错，检查 power supply、USB cable between your computer and the controller board、3-pin cable from the controller board to the motor。
  • 如果使用 Waveshare controller board，确保 two jumpers are set on the B channel (USB)。
  • 设置电机 id 与 baudrate 时，每次只能让 controller board 连接当前提示的一个电机，且该电机不能 daisy-chained 到其他电机。
  • 如果 repurposing motors from another robot，通常也需要重新设置 ids and baudrate。
  • 同一套 setup 在 teleoperating、recording、evaluating 时，要使用相同 robot id，因为它用于存储 calibration file。
  • 恢复录制时使用 --resume=true，且 --dataset.num_episodes 必须设置为 additional episodes，而不是 dataset 的目标总 episode 数。

相关 SDK 条目 ​

来源

本页事实对应的公开页面，以原文为准。

  1. huggingface.co/docs/lerobot/so101访问 2026-10-22
  2. huggingface.co/docs/lerobot/il_robots访问 2026-10-22