使用 SO-100 运行 LeRobot框架

目录

• A. 获取零件
• B. 安装 LeRobot
• C. 配置电机
• D. 逐步装配说明
• E. 校准
• F. 远程操作
• G. 记录数据集
• H. 可视化数据集
• I. 回放一个片段
• J. 训练策略
• K. 评估你的策略
• L. 更多信息

A. 获取零件

遵循此 README，其中包含物料清单、零件获取链接、3D 打印零件的说明，以及如果你是第一次打印或不拥有 3D 打印机的建议。

在装配之前，你首先需要配置电机。为此，我们提供了一个便捷的脚本，所以让我们先安装 LeRobot。配置完成后，我们还将指导你完成装配。

B. 安装 LeRobot

[!TIP]
我们经常使用命令提示符（cmd）。如果你对使用命令提示符不熟悉或想复习命令行使用，你可以参考这里：命令行速成课程

在你的电脑上：

1. 安装 Miniconda

2. 重启 shell

在 shell 中粘贴：source ~/.bashrc 或在 Mac 上：source ~/.bash_profile 或 source ~/.zshrc（如果你使用 zshell）

3. 为 LeRobot 创建并激活一个全新的 conda 环境

视频安装说明

conda create -y -n lerobot python=3.10

然后激活你的 conda 环境（每次打开 shell 使用 LeRobot 时都要这样做！）：

conda activate lerobot

4. 克隆 LeRobot:

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

5. 安装 LeRobot 及其 feetech 电机依赖：

cd ~/lerobot && pip install -e ".[feetech]"

额外：仅适用于 Linux（非 Mac）：安装录制数据集的额外依赖：

conda install -y -c conda-forge ffmpeg
pip uninstall -y opencv-python
conda install -y -c conda-forge "opencv>=4.10.0"

太棒了 :hugs:！你已完成 LeRobot 的安装，现在可以开始组装 SO100 机械臂了 :robot:。每次使用 LeRobot 时，你都可以进入我们安装 LeRobot 的文件夹 ~/lerobot 并运行其中一个命令。

C. 配置电机

在本教程中，你将找到执行步骤的视频，完整的视频教程可以在这里找到：装配视频。

1. 找到每条机械臂对应的 USB 端口

为你的领导者机械臂指定一个总线伺服适配器和 6 个电机，同样为跟随者机械臂指定另一个总线伺服适配器和 6 个电机。便于标记并在每个电机上写下它是跟随者 F 还是领导者 L 及其 ID 从 1 到 6（F1...F6 和 L1...L6）。

a. 运行脚本查找端口

视频查找端口

为了找到每个总线伺服适配器的端口，运行实用脚本：

python lerobot/scripts/find_motors_bus_port.py

b. 示例输出

示例输出，当识别领导者机械臂的端口时（例如，Mac 上的 /dev/tty.usbmodem575E0031751，或 Linux 上的 /dev/ttyACM0）：

查找 MotorBus 的所有可用端口。
['/dev/tty.usbmodem575E0032081', '/dev/tty.usbmodem575E0031751']
移除 MotorBus 的 usb 线并按 Enter。

[...断开领导者的机械臂线缆并按 Enter...]

此 MotorBus 的端口是 /dev/tty.usbmodem575E0031751
重新连接 usb 线缆。

示例输出，当识别跟随者机械臂的端口时（例如，/dev/tty.usbmodem575E0032081，或 Linux 上的 /dev/ttyACM1）：

查找 MotorBus 的所有可用端口。
['/dev/tty.usbmodem575E0032081', '/dev/tty.usbmodem575E0031751']
移除 MotorBus 的 usb 线并按 Enter。

[...断开跟随者的机械臂线缆并按 Enter...]

此 MotorBus 的端口是 /dev/tty.usbmodem575E0032081
重新连接 usb 线缆。

c. 故障排除

在 Linux 上，你可能需要通过运行以下命令授予 USB 端口访问权限：

sudo chmod 666 /dev/ttyACM0
sudo chmod 666 /dev/tty ACM1

d. 更新配置文件

重要：现在你有了端口，更新 port 的默认值在 SO100RobotConfig 中。你将找到类似的内容：

@RobotConfig.register_subclass("so100")
@dataclass
class So100RobotConfig(ManipulatorRobotConfig):
    calibration_dir: str = ".cache/calibration/so100"
    # `max_relative_target` 限制了相对位置目标向量的大小，出于安全考虑。
    # 将其设置为所有电机的正标量值，或与你的跟随者机械臂中电机数量相同的列表。
    max_relative_target: int | None = None

    leader_arms: dict[str, MotorsBusConfig] = field(
        default_factory=lambda: {
            "main": FeetechMotorsBusConfig(
                port="/dev/tty.usbmodem58760431091",  <-- 在此处更新
                motors={
                    # 名称: (索引, 型号)
                    "shoulder_pan": [1, "sts3215"],
                    "shoulder_lift": [2, "sts3215"],
                    "elbow_flex": [3, "sts3215"],
                    "wrist_flex": [4, "sts3215"],
                    "wrist_roll": [5, "sts3215"],
                    "gripper": [6, "sts3215"],
                },
            ),
        }
    )

    follower_arms: dict[str, MotorsBusConfig] = field(
        default_factory=lambda: {
            "main": FeetechMotorsBusConfig(
                port="/dev/tty.usbmodem585A0076891",  <-- 在此处更新
                motors={
                    # 名称: (索引, 型号)
                    "shoulder_pan": [1, "sts3215"],
                    "shoulder_lift": [2, "sts3215"],
                    "elbow_flex": [3, "sts3215"],
                    "wrist_flex": [4, "sts3215"],
                    "wrist_roll": [5, "sts3215"],
                    "gripper": [6, "sts3215"],
                },
            ),
        }
    )

2. 装配底座

让我们从装配跟随者机械臂的底座开始

a. 设置所有 12 个电机的 ID

视频配置电机

插入你的第一个电机 F1 并运行此脚本将其 ID 设置为 1。它还会将其当前位置设置为 2048，所以预期你的电机会旋转。将 --port 后的文本替换为相应的跟随者控制板端口，并在 cmd 中运行此命令：

python lerobot/scripts/configure_motor.py \
  --port /dev/tty.usbmodem58760432961 \
  --brand feetech \
  --model sts3215 \
  --baudrate 1000000 \
  --ID 1

这些电机目前是有限制的。它们只能接收 0 到 4096 之间的值，这对应于一整圈。它们不能转超过这个范围。2048 是这个范围的中间值，所以我们可以采取 -2048 步（逆时针 180 度）达到最大范围，或采取 +2048 步（顺时针 180 度）达到最大范围。配置步骤还将归零偏移设置为 0，所以如果你装配错误，你可以随时更新归零偏移以补偿 ± 2048 步（± 180 度）的偏移。

然后拔出你的电机并插入第二个电机，将其 ID 设置为 2。

python lerobot/scripts/configure_motor.py \
  --port /dev/tty.usbmodem58760432961 \
  --brand feetech \
  --model sts3215 \
  --baudrate 1000000 \
  --ID 2

重复此过程，直到所有电机的 ID 为 6。对领导者机械臂的 6 个电机也做同样的事情。

b. 移除 6 个领导者电机的齿轮

视频移除齿轮

按照视频移除齿轮。你需要移除领导机械臂电机的齿轮。因此，你将只使用电机的位置编码，并减少摩擦，更容易操作领导机械臂。

D. 逐步装配说明

步骤 1：清洁零件

• 去除 3D 打印零件上的所有支撑材料。

---

附加指南

视频装配机械臂

注意：
此视频为装配机械臂提供了视觉指南，但没有指明何时或如何进行布线。事先插入线缆比事后插入要容易得多。第一条机械臂的装配可能超过 1 小时，但一旦你习惯了，你可以在 1 小时内装配第二条机械臂。

---

第一个电机

步骤 2：插入线缆

• 向第一个电机插入两根线缆。

步骤 3：安装在底座中

• 将第一个电机放入底座。

步骤 4：固定电机

• 用 4 颗螺丝固定电机。从底部两颗，从顶部两颗。

步骤 5：安装电机支架

• 滑上第一个电机支架，并用两颗螺丝固定（两侧各一颗）。

步骤 6：安装电机轮毂

• 安装两个电机轮毂，用螺丝固定顶部轮毂。在安装电机轮毂时，尽量不要移动电机位置，特别是对于领导机械臂，我们移除了齿轮。

视频添加电机轮毂

步骤 7：安装肩部零件

• 将一根线缆路由到机器人后方，另一根路由到左侧或向你方向（见照片）。
• 安装肩部零件。

步骤 8：固定肩部

• 用 4 颗螺丝固定肩部零件，顶部和底部各四颗。
  (通过转动肩部访问底部的孔)。

---

第二个电机装配

步骤 9：安装电机 2

• 从顶部滑入第二个电机，并将电机 1 的线缆连接到电机 2。

步骤 10：安装肩部支架

• 添加肩部电机支架。
• 确保从电机 1 到电机 2 的线缆位于支架后方，而另一根线缆则通向顶部（见照片）。这部分装配可能很紧，你可以使用类似图中的工作台或类似设置来推动零件围绕电机。

步骤 11：固定电机 2

• 用 4 颗螺丝固定第二个电机。

步骤 12：安装电机轮毂

• 向电机 2 安装两个电机轮毂，再次使用轮毂螺丝。

步骤 13：安装底座附件

• 用 2 颗螺丝安装底座附件。

步骤 14：安装上臂

• 用两侧各 4 颗螺丝安装上臂。

---

第三个电机装配

步骤 15：安装电机 3

• 将电机 2 的电机线缆穿过线缆支架到电机 3，然后用 4 颗螺丝固定电机 3。

步骤 16：安装电机轮毂

• 向电机 3 安装两个电机轮毂，用轮毂螺丝固定一个。

步骤 17：安装前臂

• 用两侧各 4 颗螺丝将前臂连接到电机 3。

---

第四个电机装配

步骤 18：安装电机 4

• 滑入电机 4，连接电机 3 的线缆，并用螺丝将其线缆固定在其支架中。

步骤 19：安装电机 4 的支架

• 安装第四个电机支架（装配较紧）。确保一根线缆通向顶部，电机 3 的线缆通向底部（见照片）。

步骤 20：固定电机 4 和安装轮毂

• 用 4 颗螺丝固定电机 4 并安装其电机轮毂，使用一颗轮毂螺丝。

---

手腕装配

步骤 21：安装电机 5

• 将电机 5 插入手腕支架，并用两颗前螺丝固定。

步骤 22：安装手腕

• 连接电机 4 到电机 5 的线缆。并预先插入另一根线缆用于手爪。
• 用两侧各 4 颗螺丝将手腕固定到电机 4 上。

步骤 23：安装手腕轮毂

• 在手腕电机上只安装一个电机轮毂，用轮毂螺丝固定。

---

跟随者配置

步骤 24：安装手爪

• 将手爪连接到电机 5。

步骤 25：安装手爪电机

• 插入手爪电机，连接电机 5 到电机 6 的电机线缆，并用两侧各 3 颗螺丝固定。

步骤 26：安装手爪轮毂和爪子

• 安装电机轮毂，再次使用轮毂螺丝。
• 安装手爪，并用两侧各 4 颗螺丝固定。

步骤 27：安装控制器

• 在背面安装电机控制器。

领导者配置

对于领导者配置，执行步骤 1–23。确保你已经移除电机齿轮。

步骤 24：安装领导者支架

• 将领导者支架安装到手腕上，并用一颗螺丝固定。

步骤 25：安装手柄

• 用手柄连接到电机 5 上，用 4 颗螺丝固定。

步骤 26：安装手爪电机

• 插入手爪电机，用两侧各 3 颗螺丝固定，用轮毂螺丝安装电机轮毂，并连接电机线缆。

步骤 27：安装触发器

• 用 4 颗螺丝安装跟随者触发器。

步骤 28：安装控制器

• 在背面安装电机控制器。

装配完成 – 继续进行校准。

E. 校准

接下来，你需要校准你的 SO-100 机器人，以确保领导者机械臂和跟随者机械臂在相同物理位置时具有相同的位置值。此校准非常重要，因为它允许在一个 SO-100 机器人上训练的神经网络在另一个机器人上也能够工作。

a. 手动校准跟随者机械臂

与装配视频中步骤 6 说明的自动校准相反，我们实际上将手动校准跟随者机械臂。

你需要将跟随者机械臂依次移动到以下位置：

1. 零位	2. 旋转位	3. 休息位

确保两者机械臂都已连接，并运行以下脚本以启动手动校准：

python lerobot/scripts/control_robot.py \
  --robot.type=so100 \
  --robot.cameras='{}' \
  --control.type=calibrate \
  --control.arms='["main_follower"]'

b. 手动校准领导者机械臂

按照装配视频中步骤 6 说明的手动校准。你需要将领导机械臂依次移动到以下位置：

1. 零位	2. 旋转位	3. 休息位

运行此脚本以启动手动校准：

python lerobot/scripts/control_robot.py \
  --robot.type=so100 \
  --robot.cameras='{}' \
  --control.type=calibrate \
  --control.arms='["main_leader"]'

F. 远程操作

简单远程操作
然后你就可以开始远程操作你的机器人了！运行这个简单的脚本（它不会连接并显示摄像头）：

python lerobot/scripts/control_robot.py \
  --robot.type=so100 \
  --robot.cameras='{}' \
  --control.type=teleoperate

a. 带摄像头显示的远程操作

按照此指南设置你的摄像头。然后你将能够在远程操作时在电脑上显示摄像头。这对于在录制第一个数据集之前准备你的设置非常有用。

python lerobot/scripts/control_robot.py \
  --robot.type=so100 \
  --control.type=teleoperate

G. 记录数据集

一旦你熟悉了远程操作，你就可以开始用 SO-100 记录你的第一个数据集了。

如果你想使用 Hugging Face 集成的功能上传你的数据集并且你之前没有这样做过，请确保你已使用写权限的令牌登录，可以在 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

记录 2 个片段并将你的数据集上传到集线器：

python lerobot/scripts/control_robot.py \
  --robot.type=so100 \
  --control.type=record \
  --control.fps=30 \
  --control.single_task="Grasp a lego block and put it in the bin." \
  --control.repo_id=${HF_USER}/so100_test \
  --control.tags='["so100","tutorial"]' \
  --control.warmup_time_s=5 \
  --control.episode_time_s=30 \
  --control.reset_time_s=30 \
  --control.num_episodes=2 \
  --control.push_to_hub=true

注意：你可以通过添加 --control.resume=true 来继续记录。

H. 可视化数据集

如果你使用 --control.push_to_hub=true 上传了你的数据集，你可以在线可视化你的数据集，通过复制粘贴你的仓库 ID：

echo ${HF_USER}/so100_test

如果你没有使用 --control.push_to_hub=false 上传，你也可以本地可视化它（可以在浏览器中打开窗口 http://127.0.0.1:9090 使用可视化工具）：

python lerobot/scripts/visualize_dataset_html.py \
  --repo-id ${HF_USER}/so100_test \
  --local-files-only 1

I. 回放一个片段

现在尝试在你的机器人上回放第一个片段：

python lerobot/scripts/control_robot.py \
  --robot.type=so100 \
  --control.type=replay \
  --control.fps=30 \
  --control.repo_id=${HF_USER}/so100_test \
  --control.episode=0

J. 训练策略

要训练一个策略来控制你的机器人，使用 python lerobot/scripts/train.py 脚本。需要一些参数。以下是一个示例命令：

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

让我们来解释一下：

1. 我们提供了数据集作为参数：--dataset.repo_id=${HF_USER}/so100_test。
2. 我们提供了策略：policy.type=act。这会从 configuration_act.py 加载配置。重要的是，此策略会自动适应你的机器人的电机状态数量、电机动作和摄像头（例如 laptop 和 phone），这些已经保存在你的数据集中。
3. 我们提供了 policy.device=cuda，因为我们正在使用 Nvidia GPU 进行训练，但你可以使用 policy.device=mps 在 Apple 芯片上进行训练。
4. 我们提供了 wandb.enable=true 以使用 Weights and Biases 来可视化训练图。这是可选的，但如果你使用它，请确保你已经通过运行 wandb login 登录。

训练可能需要几个小时。你可以在 outputs/train/act_so100_test/checkpoints 中找到检查点。

要从检查点恢复训练，以下是从 act_so100_test 策略的 last 检查点恢复训练的示例命令：

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

K. 评估你的策略

你可以使用 record 函数从 lerobot/scripts/control_robot.py 中运行，但使用策略检查点作为输入。例如，运行此命令以记录 10 个评估片段：

python lerobot/scripts/control_robot.py \
  --robot.type=so100 \
  --control.type=record \
  --control.fps=30 \
  --control.single_task="Grasp a lego block and put it in the bin." \
  --control.repo_id=${HF_USER}/eval_act_so100_test \
  --control.tags='["tutorial"]' \
  --control.warmup_time_s=5 \
  --control.episode_time_s=30 \
  --control.reset_time_s=30 \
  --control.num_episodes=10 \
  --control.push_to_hub=true \
  --control.policy.path=outputs/train/act_so100_test/checkpoints/last/pretrained_model

如你所见，这与之前用于记录训练数据集的命令几乎相同。有两个变化：

1. 有一个额外的 --control.policy.path 参数，它指示你的策略检查点的路径（例如 outputs/train/eval_act_so100_test/checkpoints/last/pretrained_model）。你也可以使用模型仓库，如果你上传了一个模型检查点到集线器（例如 ${HF_USER}/act_so100_test）。
2. 数据集名称以 eval 开头，以表示你正在运行推理（例如 ${HF_USER}/eval_act_so100_test）。

L. 更多信息

遵循此之前的教程以获取更深入的教程，了解如何用 LeRobot 控制真实机器人。

[!TIP]
如果你有任何问题或需要帮助，请在 Discord 的 #so100-arm 频道中联系我们。
```