SO-101

软件设置

LeRobot 安装、SO-101 机器人配置、伺服校准、主从远程操作设置、Python API 和故障排除。 从全新的 Python 安装到运行的手臂，一切应有尽有。

跳转到一个部分：

› 乐机器人安装 › SO-101 机器人配置 › 伺服校准 › 领导者-追随者 Teleop › Python API › 故障排除
步骤一——乐机器人安装

乐机器人安装

LeRobot 是 SO-101 所需的唯一软件包。 它处理伺服通信、校准、遥控和数据记录。

创建虚拟环境

python -m venv ~/.venvs/so101
source ~/.venvs/so101/bin/activate   # Windows: .venvs\so101\Scripts\activate

安装乐机器人

pip install lerobot

验证安装

python -c "import lerobot; print(lerobot.__version__)"

从源安装（可选 - 最新功能）

git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -e ".[so101]"
第 2 步 — 机器人配置

SO-101机器人配置

LeRobot 包含一个内置的 SO-101 机器人配置。 您可以为从动臂（如果使用两臂遥控，则为引导臂）指定 USB 端口。

找到您的 USB 端口

# Linux / macOS
ls /dev/ttyUSB*    # typical: /dev/ttyUSB0, /dev/ttyUSB1
ls /dev/tty.usbserial*   # macOS alternative

# Windows — check Device Manager → Ports → COMx

SO-101 配置 YAML

LeRobot 在命令行或 YAML 文件上使用内联配置。 对于单臂设置：

# ~/.lerobot/robots/so101_follower.yaml
robot_type: so101
port: /dev/ttyUSB0   # update to your port
cameras:
  wrist_cam:
    type: opencv
    index_or_path: 0
    fps: 30
    width: 640
    height: 480

两臂（领导者-跟随者）配置

# ~/.lerobot/robots/so101_bimanual.yaml
robot_type: so101
port: /dev/ttyUSB1      # follower arm
leader_arms:
  main:
    type: so101
    port: /dev/ttyUSB0   # leader arm
cameras:
  top_cam:
    type: opencv
    index_or_path: 0
    fps: 30
    width: 640
    height: 480

测试连接

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=none   # just connects and reads state

您应该会看到打印的关节位置读数。 如果出现端口错误，请检查 故障排除.

步骤 3 — 伺服校准

伺服校准

与使用绝对编码器的 CAN 总线臂不同，Feetech STS3215 伺服系统需要校准来定义其零位置。 乐机器人会自动处理这个问题。

运行校准

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=calibrate

该脚本将提示您将手臂移动到特定位置（每个关节的起始位置、最小位置、最大位置），然后在每个位置按 Enter 键。 它将校准数据保存到 ~/.cache/huggingface/lerobot/calibration/so101/.

校准位置

乐机器人会要求您将每个关节定位在三个姿势：

  • 主场位置： 手臂完全伸展，末端执行器指向前方
  • 零扭矩位置： 手臂在重力作用下自然悬挂
  • 90度参考： 每个关节的中点

验证校准

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=teleoperate   # move arm by hand to verify joint readout

手动移动手臂（合规模式）。 在家中关节位置的读数应接近于零，并在移动每个关节时平滑地增加/减少。

重新校准提示： 每当拆卸关节、更换伺服器或发现关节位置漂移时，请再次运行校准。 校准文件存储每个臂的序列号并自动重新加载。

第 4 步 — 领导者-跟随者 Teleop

领导者-跟随者远程操作

SO-101 专为领导者-跟随者远程操作而设计：一只手臂（领导者）捕捉您的手部动作，第二只手臂（跟随者）实时镜像它们。 这将产生最高质量的培训演示。

启动领导者-跟随者远程操作

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB1 \
  --robot.leader_arms.main.type=so101 \
  --robot.leader_arms.main.port=/dev/ttyUSB0 \
  --control.type=teleoperate

单臂键盘遥控（无第二臂）

如果您只有一只手臂，请使用键盘控制模式：

python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=teleoperate \
  --control.teleop_keys=true

顺应/重力补偿模式

将引导臂置于低扭矩模式，以便您可以用手自由移动它：

python -c "
from lerobot.common.robot_devices.robots.so101 import SO101Robot
robot = SO101Robot(port='/dev/ttyUSB0')
robot.connect()
robot.set_compliance_mode(True)   # arm moves freely under hand guidance
"
第 5 步——Python API

Python API 快速入门

您可以通过LeRobot机器人API直接控制SO-101，无需CLI脚本。

基本联合控制

from lerobot.common.robot_devices.robots.so101 import SO101Robot
import torch

robot = SO101Robot(port="/dev/ttyUSB0")
robot.connect()

# Read current joint positions (6 DOF)
obs = robot.capture_observation()
print("Joint positions:", obs["observation.state"])

# Send joint position command (in degrees, normalized to [-1, 1] range)
action = torch.zeros(6)   # all joints to zero position
robot.send_action(action)

robot.disconnect()

重力补偿（可反向驱动模式）

from lerobot.common.robot_devices.robots.so101 import SO101Robot

robot = SO101Robot(port="/dev/ttyUSB0")
robot.connect()

# Enable backdrive — arm can be moved freely by hand
robot.set_compliance_mode(True)

import time
for _ in range(100):
    obs = robot.capture_observation()
    print(obs["observation.state"])   # prints live joint positions as you move arm
    time.sleep(0.02)

robot.disconnect()

读取伺服状态

from lerobot.common.robot_devices.motors.feetech import FeetechMotorsBus

bus = FeetechMotorsBus(port="/dev/ttyUSB0",
                       motors={"joint1": (1, "sts3215"),
                               "joint2": (2, "sts3215"),
                               "joint3": (3, "sts3215"),
                               "joint4": (4, "sts3215"),
                               "joint5": (5, "sts3215"),
                               "gripper": (6, "sts3215")})
bus.connect()
positions = bus.read("Present_Position", ["joint1", "joint2", "joint3"])
print("Positions:", positions)
bus.disconnect()
故障排除

最常见的 3 个问题

错误1 未找到串口： FileNotFoundError: /dev/ttyUSB0

未检测到 USB 伺服控制器。 通常是缺少驱动程序或电缆已拔出。

使固定：

# Check if the device is listed
ls /dev/ttyUSB*   # Linux
ls /dev/tty.usbserial*   # macOS

# Linux: add yourself to the dialout group (requires logout)
sudo usermod -aG dialout $USER

# Windows: install CP2102 or CH340 USB driver,
# then check Device Manager for COM port number
错误2 连接后舵机没有响应

舵机是物理连接的，但乐机器人无法读取它们的位置。 通常是电源问题或波特率错误。

使固定：

# 1. Verify 5V power supply is connected and LED on servo board is on
# 2. Check all servo daisy-chain cables are fully seated
# 3. Try scanning for servos directly:
python -c "
from lerobot.common.robot_devices.motors.feetech import FeetechMotorsBus
bus = FeetechMotorsBus('/dev/ttyUSB0', motors={})
bus.connect()
ids = bus.find_motor_ids()
print('Found motor IDs:', ids)
bus.disconnect()
"
错误3 下次运行时找不到校准数据

乐机器人保存每个手臂的校准序列号。 如果找不到校准文件，它将发出警告并使用原始编码器值。

使固定：

# Check calibration file location
ls ~/.cache/huggingface/lerobot/calibration/so101/

# Re-run calibration if the file is missing
python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --control.type=calibrate

# Pass explicit calibration path if needed
python -m lerobot.scripts.control_robot \
  --robot.type=so101 \
  --robot.port=/dev/ttyUSB0 \
  --robot.calibration_dir=/path/to/calibration \
  --control.type=teleoperate

还卡住了吗？ 询问 SO-101论坛 或检查 乐机器人GitHub问题.

以前的 ← 设置指南
下一个 规格 →

软件工作正常吗？ 开始收集数据。

一旦手臂开始移动，下一步就是记录您的第一个 LeRobot 数据集。

数据收集指南 → 完整 API 参考 在论坛上获取帮助