Configuración del software

Instalación de LeRobot

LeRobot es el único paquete de software que necesitas para el SO-101. Maneja la comunicación de servos, calibración, teleoperación y grabación de datos.

Crear un entorno virtual

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

Instalar LeRobot

pip install lerobot

Verificar instalación

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

Instalar desde el código fuente (opcional — para las últimas características)

git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -e ".[so101]"

Configuración del Robot SO-101

LeRobot incluye una configuración de robot SO-101 incorporada. Especificas el puerto USB para el brazo seguidor (y el brazo líder si usas teleoperación de dos brazos).

Encuentra tu puerto USB

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

# Windows — check Device Manager → Ports → COMx

Configuración YAML de SO-101

LeRobot utiliza una configuración en línea en la línea de comandos o un archivo YAML. Para una configuración de un solo brazo:

# ~/.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

Configuración de dos brazos (líder-seguidor)

# ~/.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

Probar conexión

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

Deberías ver lecturas de posición de las juntas impresas. Si obtienes un error de puerto, verifica Solución de problemas.

Calibración del servo

A diferencia de los brazos con bus CAN que utilizan codificadores absolutos, los servos Feetech STS3215 necesitan calibración para definir sus posiciones cero. LeRobot maneja esto automáticamente.

Ejecutar calibración

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

El script te pedirá que muevas el brazo a posiciones específicas (inicio, mínimo, máximo para cada junta) y presiones Enter en cada posición. Guarda los datos de calibración en ~/.cache/huggingface/lerobot/calibration/so101/.

Posiciones de calibración

LeRobot te pedirá que posiciones cada junta en tres posturas:

• Posición de inicio: brazo completamente extendido, efector final apuntando hacia adelante
• Posición de torque cero: brazo colgando naturalmente bajo la gravedad
• Referencia de 90 grados: cada junta en su punto medio

Verificar calibración

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

Mueve el brazo manualmente (modo de cumplimiento). Las posiciones de las juntas deberían leer cerca de cero en la posición de inicio y aumentar/disminuir suavemente a medida que mueves cada junta.

Teleoperación Líder–Seguidor

El SO-101 está diseñado para teleoperación líder–seguidor: un brazo (líder) captura los movimientos de tu mano, y el segundo brazo (seguidor) los refleja en tiempo real. Esto produce las demostraciones de entrenamiento de la más alta calidad.

Iniciar teleoperación líder-seguidor

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

Teleoperación de un solo brazo con teclado (sin segundo brazo)

Si solo tienes un brazo, usa el modo de control por teclado:

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

Modo de cumplimiento / compensación de gravedad

Pon el brazo líder en modo de bajo par para que puedas moverlo libremente con tu mano:

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
"

Guía rápida de la API de Python

Puedes controlar el SO-101 directamente a través de la API del robot LeRobot sin los scripts de CLI.

Control básico de articulaciones

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()

Compensación de gravedad (modo retroalimentable)

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()

Leyendo el estado del servo

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 problemas comunes principales

# 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

# 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()
"

# 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

¿Aún atascado? Pregunta en el Foro SO-101 o comprobar el Problemas de LeRobot en GitHub.