LeRobot SO-101 机械臂使用文档

适用对象：SO-101 Follower/Leader 双臂用户，或仅 Follower 单臂用户。

适用环境：Ubuntu（推荐 22.04/24.04）或 Windows；本文命令以 Bash 为主，Windows 另给说明。

版本提示：本文以 LeRobot 官方教程与命令行为准，并兼容你原文档中常见的 python 方式（如 python -m lerobot.*）。

 

1. 快速跑通（最小闭环：能动起来 + 能录一段 + 能回放）

  1. 连接电源与 USB：Follower/Leader 各自控制板通过 USB 连接到电脑；确认电源电压符合套件要求，先不上力（不要夹手）。
  2. 准备 Python 环境：创建独立 conda 环境（避免与 ROS2/系统 Python 混用）。
  3. 安装 LeRobot：从 PyPI 安装，或从 GitHub 克隆后 editable 安装（推荐用于开发/跟随最新文档）。
  4. 找到串口端口：用 lerobot-find-port（Linux/macOS）或系统设备管理器（Windows）确认 follower/leader 各自对应的端口。
  5. （仅 DIY）设置舵机 ID：用 lerobot-setup-motors 依次配置每个舵机的 ID（一次只连接一个舵机更安全）。
  6. 校准：用 lerobot-calibrate 完成 follower/leader 的零位与方向校准。
  7. 遥操作：用 lerobot-teleoperate 让 leader 控 follower，验证动作一致。
  8. 录制：用 lerobot-record 录 1–2 个 episode（本地保存即可，先不上传）。
  9. 回放：用 lerobot-replay 回放刚刚录制的某个 episode，验证可重复性。

提示：如果你只想验证硬件能跑：先跳到第 4、6、7 节（端口→校准→遥操作）。

2. 软件环境准备

2.1 建议的目录结构

  • 建议把 LeRobot 工程放在独立目录，例如：~/workspace/lerobot/（Linux）或 D:\workspace\lerobot\（Windows）。
  • 数据集默认会存到用户目录缓存路径：~/.cache/huggingface/lerobot/{repo-id}（Linux/macOS）。

2.2 安装 Miniconda（如已安装可跳过）

  • 目的：用 conda 隔离 Python 依赖，避免系统包冲突。
  • Windows：安装后建议勾选“Add to PATH”或使用 Anaconda Prompt。

2.3 创建 conda 环境（推荐）

  • 作用：创建独立 Python 3.10 环境，并安装 ffmpeg（用于视频编码）。
  • 为什么是 3.10：LeRobot 教程通常以 3.10 为基线，兼容性更稳。

命令：创建并进入 LeRobot 环境（带注释）

# 创建环境（Linux/macOS/WSL）

conda create -n lerobot python=3.10 ffmpeg -c conda-forge -y

# 激活环境

conda activate lerobot

# 可选：避免每次打开终端自动进入 base

conda config --set auto_activate_base false

3. 安装 LeRobot（两种方式）

3.1 方式 A：从 PyPI 安装（更简单）

  • 适合：只想使用 LeRobot，不需要修改源码。
  • 关键点：如果使用 Feetech/SO-101 这类串口舵机，通常需要带上相应 extra（例如 feetech）。

命令：PyPI 安装（根据你的版本选择其一）

# 升级 pip（避免老版本解析依赖出错）

python -m pip install -U pip

# 安装 LeRobot（如官方提供 feetech extra，则使用下面写法）

python -m pip install "lerobot[feetech]"

# 若你的版本不提供 extra，也可以先装 lerobot 再按提示补装依赖

python -m pip install lerobot

提示：安装完成后可先运行 lerobot-info（第 3.3 节）确认 CLI 是否可用。

3.2 方式 B：从 GitHub 安装（推荐用于跟随最新教程）

  • 适合：需要对源码二次开发/希望与官方教程保持一致。
  • editable 安装（-e）的含义：源码改动即时生效，不用反复重装。

命令：从 GitHub 安装（带注释）

# 进入工作目录

cd ~/workspace

# 克隆仓库（网络较慢时可用代理/镜像，但不要改动命令标点）

git clone https://github.com/huggingface/lerobot.git

cd lerobot

# 安装（带 feetech 相关依赖）

python -m pip install -e ".[feetech]"

3.3 验证安装（检查 CLI）

  • 目的：确认 lerobot-* 命令已进入 PATH，并可正常运行。

命令：验证 LeRobot 安装

lerobot-info

# 预期：打印版本、可用脚本、支持的机器人/设备等信息（不同版本输出略有差异）

4. 连接机械臂与查找端口（最常见卡点）

4.1 Ubuntu / Linux：查找 follower 与 leader 的端口

  • 推荐方法：优先使用 /dev/serial/by-id/，因为它比 /dev/ttyACM0 更稳定（重插不易变化）。
  • 也可用 lerobot-find-port 自动扫描并提示可用端口。

命令：Linux 查找串口端口（带注释）

# 方法 1：查看稳定别名（推荐）

ls -l /dev/serial/by-id/


# 方法 2：只看 ACM/USB 设备（快速）

ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null


# 方法 3：使用 LeRobot 工具自动查找（如果已安装）

lerobot-find-port

4.2 Windows：查找 COM 端口并固定编号

  • 打开【设备管理器】→【端口（COM 和 LPT）】查看 SO-101 对应的 COM 号。
  • 建议在端口属性里固定 COM 编号（避免重插后变化）。
  • 后续命令中的 --robot.port / --teleop.port 直接填写 COMx（如 COM7）。

4.3 串口权限（Linux）

  • 现象：报错 Permission denied / 无法打开串口。
  • 根因：当前用户没有访问 /dev/ttyACM* 或 /dev/ttyUSB* 的权限。
  • 推荐做法：把用户加入 dialout 组，然后重新登录。
  • 临时做法：chmod 仅用于快速验证，不建议长期使用。

命令：Linux 串口权限处理（带注释）

# 推荐：加入 dialout 组（需要重新登录或重启后生效）

sudo usermod -a -G dialout $USER


# 重新登录后验证：

groups | grep dialout


# 临时（不推荐长期）：只为快速验证硬件

sudo chmod 666 /dev/ttyACM0

注意：长期使用建议用 dialout/udev 方式；chmod 666 会让所有用户可读写该设备，存在安全风险。

5.（仅 DIY）舵机 ID 配置：lerobot-setup-motors

  • 什么时候需要：你自行组装/更换过舵机，或舵机 ID 混乱导致关节错位/不动。
  • 原则：一次只连接一个舵机进行设置更稳妥；设置完成再连下一个。
  • 作用：把每个物理舵机写入唯一 ID，使软件能按关节顺序控制。

命令：设置舵机 ID（示例）

# 示例：设置 follower 机械臂舵机（按官方工具提示交互执行）

lerobot-setup-motors \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0


# 常见做法：按提示依次选择 joint1 ~ joint6（或 joint7/gripper），每次确认成功后再进行下一个。

注意：如果你不确定自己的关节数量/是否有夹爪，请以实际硬件为准；不要强行写入不匹配的关节映射。

6. 校准：lerobot-calibrate（必须做）

  • 作用：建立“电机角度—软件关节”的对应关系，写入校准文件；否则遥操作/回放会偏差很大。
  • 重要：follower 与 leader 需要分别校准；并且后续 teleoperate/record/replay 要保持同一个 --robot.id 与 --teleop.id（用于关联校准文件）。

命令：分别校准 follower 与 leader（示例）

# 校准 follower（示例，端口按你的实际替换）

lerobot-calibrate \
  --robot.type=so101_follower \
  --robot.port=/dev/ttyACM0 \
  --robot.id=my_follower_arm


# 校准 leader（示例）

lerobot-calibrate \
  --robot.type=so101_leader \
  --robot.port=/dev/ttyACM1 \
  --robot.id=my_leader_arm

提示：如果你的版本没有 lerobot-calibrate，可使用原文档中的 python -m lerobot.calibrate 形式；参数名保持一致即可。

7. 遥操作：lerobot-teleoperate（Leader 控 Follower）

  • 目标：验证 leader 的关节动作能正确映射到 follower（方向/零位都正确）。
  • teleoperate 会自动检查校准文件：缺失时会提示并进入校准流程。

命令：最小遥操作（无视觉）

lerobot-teleoperate \

  --robot.type=so101_follower \

  --robot.port=/dev/ttyACM0 \

  --robot.id=my_follower_arm \

  --teleop.type=so101_leader \

  --teleop.port=/dev/ttyACM1 \

  --teleop.id=my_leader_arm

7.1 加入摄像头并可视化（可选）

  • 用途：边遥操作边查看摄像头画面与关节状态，便于采集高质量数据。
  • 先找摄像头 index：使用 lerobot-find-cameras。

命令：查找摄像头（带注释）

# 查找摄像头（opencv index）

lerobot-find-cameras

命令：遥操作 + 摄像头 + 可视化（示例）

# 遥操作 + 摄像头（示例：单前置摄像头）

lerobot-teleoperate \

  --robot.type=so101_follower \

  --robot.port=/dev/ttyACM0 \

  --robot.id=my_follower_arm \

  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \

  --teleop.type=so101_leader \

  --teleop.port=/dev/ttyACM1 \

  --teleop.id=my_leader_arm \

  --display_data=true

注意：如果 OpenCV 摄像头出现异步/编码报错，可尝试降低分辨率/帧率，或给 OpenCV 相机配置加 fourcc（如 MJPG）。

8. 数据采集：lerobot-record（录制数据集）

  • 作用：在遥操作过程中记录“观测（相机/关节）—动作（关节指令）”，保存为 LeRobotDataset 格式，可直接用于训练。
  • 建议：先录 5–10 个 episode 验证流程，再扩展到 50+。
  • 本地保存路径（默认）：~/.cache/huggingface/lerobot/{repo-id}

8.1（推荐）先不上传：仅本地录制

  • 目的：避免一开始就被 Hugging Face Token/网络等问题阻塞。
  • 做法：设置 --dataset.push_to_hub=false。

命令：本地录制 5 个 episode（示例）

HF_USER=$(hf auth whoami | head -n 1)  # 可选：如果你已登录 HF


lerobot-record \

  --robot.type=so101_follower \

  --robot.port=/dev/ttyACM0 \

  --robot.id=my_follower_arm \

  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \

  --teleop.type=so101_leader \

  --teleop.port=/dev/ttyACM1 \

  --teleop.id=my_leader_arm \

  --display_data=true \

  --dataset.repo_id=my_local/so101_pickplace \

  --dataset.num_episodes=5 \

  --dataset.single_task="Pick and place" \

  --dataset.push_to_hub=false

8.2 键盘控制（录制时非常重要）

  • →（右方向键）：提前结束当前 episode（或 reset 阶段）并进入下一段。
  • ←（左方向键）：取消当前 episode 并重新录制。
  • ESC：立即停止，开始编码视频并写盘（如果启用上传则会随后上传）。

注意：Linux 下如果方向键/ESC 不生效，通常是 $DISPLAY 未设置或 pynput 限制导致；可在桌面环境运行，或设置 DISPLAY。

9. 回放：lerobot-replay（验证可重复性）

  • 作用：把数据集中某个 episode 的动作序列重新发送给 robot，用于检查重复性、关节映射、控制稳定性。
  • 建议：在开始训练前，至少回放 1–2 次确认硬件一致性。

命令：回放数据集的第 0 个 episode（示例）

lerobot-replay \

  --robot.type=so101_follower \

  --robot.port=/dev/ttyACM0 \

  --robot.id=my_follower_arm \

  --dataset.repo_id=my_local/so101_pickplace \

  --dataset.episode=0

10. 训练：lerobot-train（以 ACT 为例）

  • 目的：用你录制的数据训练策略网络（policy），让 follower 自主完成任务。
  • 最少条件：有数据集（dataset.repo_id），有 GPU（推荐），并选择 policy.type（如 act）。

命令：训练 ACT（示例，先不上传/不使用 W&B）

# 如果你有 NVIDIA GPU：

lerobot-train \

  --dataset.repo_id=my_local/so101_pickplace \

  --policy.type=act \

  --output_dir=outputs/train/act_so101_pickplace \

  --job_name=act_so101_pickplace \

  --policy.device=cuda \

  --wandb.enable=false \

  --policy.push_to_hub=false

提示：如果你想用原文档的训练方式，也可使用：python lerobot/scripts/train.py ...；两者本质一致，优先推荐 lerobot-train。

10.1 断点续训（resume）

  • 作用：训练中断后从 checkpoints/last 继续。
  • 做法：指定 config_path 为上一次训练保存的 train_config.json，并设置 --resume=true。

命令：从 last checkpoint 继续训练（示例）

lerobot-train \

  --config_path=outputs/train/act_so101_pickplace/checkpoints/last/pretrained_model/train_config.json \

  --resume=true

10.2 远程服务器训练（通用做法，去商业化）

  • 适用：本地没有 GPU 或训练速度太慢。
  • 你只需要一台：Ubuntu + NVIDIA GPU + CUDA 驱动（或用云/机房/实验室任意 GPU 机）。
  • 关键：用 rsync/scp 把 ~/.cache/huggingface/lerobot/{repo-id} 数据集同步到服务器；训练完成后把 outputs/train/ 同步回本地。

命令：远程训练（示例）

# 本地 -> 服务器：同步数据集（示例，替换 user@host 和路径）

rsync -avP ~/.cache/huggingface/lerobot/my_local/so101_pickplace/ user@host:~/lerobot_data/so101_pickplace/


# 服务器上训练（进入你的 conda env 后执行）

lerobot-train \

  --dataset.root=~/lerobot_data \

  --dataset.repo_id=my_local/so101_pickplace \

  --policy.type=act \

  --output_dir=outputs/train/act_so101_pickplace \

  --job_name=act_so101_pickplace \

  --policy.device=cuda \

  --wandb.enable=false \

  --policy.push_to_hub=false

注意：不同版本的 LeRobot 对 dataset.root 参数支持可能略有差异；若不支持，可直接把数据集放到默认缓存路径或按官方提示调整。

11. 推理与评估（用录制脚本加载 policy）

  • 官方推荐：复用 lerobot-record，在命令中增加 --policy.path 来进行推理并录制评估 episode。
  • policy.path 可以是：本地 outputs/train/.../checkpoints/last/pretrained_model，或 HF Hub 上的模型仓库名。

命令：加载训练好的 policy 进行推理并录制评估数据（示例）

lerobot-record \

  --robot.type=so101_follower \

  --robot.port=/dev/ttyACM0 \

  --robot.id=my_follower_arm \

  --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \

  --display_data=false \

  --dataset.repo_id=my_local/eval_act_so101_pickplace \

  --dataset.num_episodes=10 \

  --dataset.single_task="Pick and place" \

  --dataset.push_to_hub=false \

  --policy.path=outputs/train/act_so101_pickplace/checkpoints/last/pretrained_model

注意：推理阶段务必确保安全：先把速度调低，工作空间清空，避免撞击。必要时先断电测试流程再上电执行。

12. 常见问题排查（按现象定位）

12.1 现象：找不到端口 / 端口号变了

  • Linux：优先使用 /dev/serial/by-id/ 的稳定路径；或重新运行 lerobot-find-port。
  • Windows：在设备管理器确认 COM 号，并固定端口号；避免 USB 口更换。

12.2 现象：Permission denied / 无法打开串口（Linux）

  • 加入 dialout 组并重新登录（推荐）。
  • 临时 chmod 仅用于验证，不建议长期使用。

12.3 现象：遥操作方向反了 / 关节错位

  • 优先检查是否完成校准（第 6 节）。
  • DIY 用户检查舵机 ID 是否按关节顺序写入（第 5 节）。
  • 确认使用一致的 --robot.id/--teleop.id，避免读取到错误的校准文件。

12.4 现象：录制时方向键/ESC 无效（Linux）

  • 检查是否在图形桌面环境运行；确认 $DISPLAY 已设置。
  • 某些远程终端/无头环境下 pynput 受限，需要改用本地桌面或按官方限制处理。

12.5 现象：推理时报 CUDA/CPU 不匹配

  • 如果模型在 CUDA 机器上保存，但在无 CUDA 的机器加载，可能需要指定 map_location 或重新导出/使用 CPU 版本。
  • 最简单做法：在同一类设备（GPU/CPU）上训练与推理；或确保安装的 torch 与设备匹配。

13. 参考（官方优先）

  • LeRobot 官方仓库：https://github.com/huggingface/lerobot
  • Imitation Learning on Real-World Robots（含 SO-101 teleoperate/record/replay/train/inference 示例）：https://raw.githubusercontent.com/huggingface/lerobot/main/docs/source/il_robots.mdx
  • SO-101 机器人教程（包含 lerobot-find-port / lerobot-setup-motors / lerobot-calibrate 等）：https://huggingface.co/docs/lerobot/en/so101
  • Hugging Face CLI 登录（huggingface-cli login）：https://huggingface.co/docs/huggingface_hub/guides/cli

# linux # ubuntu
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

cover

高效开发新范式：Qwen Code 与可组合 Agent Skills 的协同之道

avatar 2048 AI社区
cover

11个AI论文助手，满足不同专业需求

avatar 2048 AI社区
cover

学术写作利器：11款AI网站覆盖各学科

avatar 2048 AI社区