Microduck Robot●microduck-robot.com

Microduck Robot / LEROBOT

Tutorial LeRobot SO-101: montar, calibrar, grabar, entrenar y ejecutar

Esta guía sigue la documentación oficial de Hugging Face LeRobot para los brazos líder y seguidor SO-101, añade las comprobaciones que los constructores suelen pasar por alto y termina con la base móvil LeKiwi y una lista de comprobación de problemas. Los comandos corresponden a LeRobot v0.7.0 (publicada el 5 de noviembre de 2026). LeRobot cambia con rapidez, así que compara los parámetros con la documentación de la versión que instales.

Qué vas a construir y qué necesitas

LeRobot es la biblioteca de robótica de código abierto de Hugging Face. Con un mismo conjunto de comandos se mueve un robot, se graban demostraciones, se entrena una política y se ejecuta. El SO-101 es su brazo insignia: mueves a mano un brazo líder, un brazo seguidor lo copia, y el movimiento grabado junto con las imágenes de las cámaras enseña a una red neuronal a repetir la tarea por sí sola.

El trabajo consta de siete etapas: conseguir las piezas e instalar el software, asignar un ID a cada motor, montar los dos brazos, calibrar, teleoperar con cámaras, grabar un conjunto de datos y, por último, entrenar y ejecutar una política. La última sección de montaje añade la base móvil LeKiwi, seguida de una lista de comprobación de problemas.

Desliza hacia los lados para ver toda la figura.

Las siete etapas del montaje, con el comando que realiza cada unaUna lista numerada de siete etapas, de arriba abajo. 1 Piezas y software: pip install lerobot. 2 Puertos e ID de motores: lerobot-find-port y lerobot-setup-motors. 3 Montar los dos brazos, a mano. 4 Calibrar: lerobot-calibrate. 5 Teleoperar con cámaras: lerobot-find-cameras y lerobot-teleoperate. 6 Grabar un conjunto de datos: lerobot-record, y lerobot-replay para comprobarlo. 7 Entrenar y ejecutar una política: lerobot-train y después lerobot-rollout.1Piezas y softwareConsigue piezas e instala LeRobotpip install lerobot2Puertos e ID de motoresUn servo cada vezlerobot-find-portlerobot-setup-motors3Montar los dos brazosArticulación a articulaciónSin comando: se hace a mano4CalibrarMismos números en los dos brazoslerobot-calibrate5Teleoperar con cámarasEl líder mueve al seguidorlerobot-find-cameraslerobot-teleoperate6Grabar datosPosiciones articulares y vídeolerobot-recordlerobot-replay7Entrenar y ejecutarPolítica ACT en el brazo seguidorlerobot-trainlerobot-rollout
Las siete etapas del montaje, con el comando que realiza cada una

Necesitas dos brazos (las piezas, en la sección siguiente), una placa de control USB para servos de bus y una fuente de alimentación para cada brazo, un ordenador con Python 3.12 o superior, dos cámaras USB (los comandos de esta guía usan dos), una cuenta gratuita de Hugging Face para los conjuntos de datos y los puntos de control, y una GPU para entrenar. Una GPU de portátil basta para la política ACT que se usa aquí, y también sirve una GPU alquilada.

Hemos elaborado esta guía a partir de la documentación oficial y de informes de montaje de la comunidad, y no hemos probado cada paso en banco con cada revisión de hardware. Los tutoriales antiguos que usan control_robot.py no sirven para la versión 0.7.0, que usa los comandos lerobot-*.

Piezas, impresión y alimentación

El proyecto SO-101 publica la lista de materiales y los archivos de impresión, y la página de SO-101 de Hugging Face enlaza con ambos. Un par completo de brazo líder y brazo seguidor necesita 12 servos Feetech STS3215, dos placas de control, dos fuentes de alimentación, dos cables USB-C y abrazaderas de mesa. El montaje usa tornillos M2×6 y M3×6; la lista de materiales del proyecto no los recoge, así que comprueba qué viene con tus servos o tu kit. También se venden piezas impresas y kits completos.

El brazo seguidor usa seis servos con una relación de transmisión de 1/345. El brazo líder usa tres relaciones distintas, de modo que puede sostener su propio peso y aun así moverse con poca fuerza.

Adapta la fuente de alimentación a los servos. El STS3215 de 7,4 V tiene un par de bloqueo de 16,5 kg·cm a 6 V (algo menos con una fuente de 5 V) y normalmente se alimenta con una fuente de 5 V. El brazo seguidor puede usar servos de 12 V (30 kg·cm) para tener más potencia, pero entonces necesita una fuente de 12 V de 5 A o más; el brazo líder usa siempre servos de 7,4 V. No conectes nunca la fuente de 12 V a una placa que tenga servos de 7,4 V; marca cada fuente con su voltaje y el brazo al que pertenece.

Desliza hacia los lados para ver toda la figura.

Alimentación y USB del brazo líder y del brazo seguidorUn ordenador, arriba, está conectado mediante un cable USB-C a la placa de control del brazo líder y a la placa de control del brazo seguidor. Cada placa de control tiene su propia fuente de alimentación. De cada placa se encadenan seis servos, empezando por el servo 1, con cables de 3 pines. El brazo líder usa siempre servos de 7,4 V con una fuente de 5 V. El brazo seguidor usa servos de 7,4 V con una fuente de 5 V, o servos de 12 V con una fuente de 12 V de 5 A o más. En una placa Waveshare, los dos puentes están en el canal B, el canal USB.OrdenadorBrazo líderFuente de 5 VControladoraPlaca Waveshare:los dos puentes enel canal B (USB).1234566 servos de 7,4 Vcon fuente de 5 V.Brazo seguidorFuente:5 V, o 12 V 5 A+ControladoraPlaca Waveshare:los dos puentes enel canal B (USB).123456Servos de 7,4 Vcon 5 V, o servosde 12 V con 12 V.AlimentaciónUSB-CCable de servo de 3 pinesNunca conectes la fuente de 12 V a una placa con servos de 7,4 V.
Alimentación y USB del brazo líder y del brazo seguidor

Imprime en PLA+ con una boquilla de 0,4 mm y capas de 0,2 mm (o una boquilla de 0,6 mm y capas de 0,4 mm) y un 15 % de relleno. Las piezas de cada brazo vienen en un solo archivo, orientadas para necesitar pocos soportes; no pongas soportes en los agujeros horizontales de los tornillos. Imprime primero las piezas de prueba (calibres) Gauge Zero y Gauge Tight y compruébalas con un servo; si Gauge Zero no encaja como se muestra en el vídeo del proyecto, ajusta la configuración de tu impresora y vuelve a imprimirla antes de imprimir los brazos.

Ten a mano destornilladores Phillips #0 y #1, y sujeta cada base a la mesa con abrazaderas antes de hacer pruebas. Más abajo encontrarás enlaces a las piezas que suministramos para este montaje.

Desplázate horizontalmente para comparar todas las columnas.

ArticulaciónID del motorRelación de transmisión del brazo líderRelación de transmisión del brazo seguidor
Giro del hombro11/1911/345
Elevación del hombro21/3451/345
Flexión del codo31/1911/345
Flexión de la muñeca41/1471/345
Giro de la muñeca51/1471/345
Pinza61/1471/345

Instalar LeRobot y el soporte de motores

LeRobot 0.7.0 necesita Python 3.12 o superior. Crea un entorno aislado con conda (de miniforge) o uv y actívalo en cada terminal nueva. ffmpeg es necesario para el vídeo en la mayoría de las plataformas (en macOS Intel y en Linux ARM de 32 bits LeRobot recurre a PyAV y puedes omitirlo); el paquete de conda funciona con todas las versiones de PyTorch.

Crear el entorno
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forge

Instala LeRobot desde PyPI con los extras que necesites. core_scripts añade lo que usan la grabación, la reproducción y la calibración, feetech añade compatibilidad con los servos STS3215 y training añade las herramientas de entrenamiento.

Instalar LeRobot con extras
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'

Notas por plataforma: en Apple silicon, PyTorch necesita macOS 14 o superior, y macOS 15 o superior para la aceleración por GPU (MPS). Para usar una GPU NVIDIA en Linux, las compilaciones predeterminadas de PyTorch necesitan un controlador 580.65 o superior; con un controlador más antiguo, instala primero una compilación de PyTorch con CUDA que coincida y toma torchcodec del índice de CPU (consulta la página de instalación de Hugging Face). En WSL instala también evdev (conda install evdev -c conda-forge o, con uv, sudo apt install libevdev-dev y después uv pip install evdev). Con PyTorch 2.10 o superior puedes usar el ffmpeg del sistema en lugar del de conda.

Encontrar los puertos y asignar los ID de los motores

Los servos STS3215 nuevos suelen salir con el ID 1, y el controlador y todos los servos deben compartir una misma velocidad en baudios. LeRobot escribe ambos valores una sola vez en la memoria de cada servo, así que hazlo antes del montaje y conecta los servos de uno en uno. Los servos reutilizados de otro robot probablemente también lo necesitan.

Desliza hacia los lados para ver toda la figura.

Las seis articulaciones de un brazo SO-101 y el ID del motor de cada unaVista lateral de un brazo robótico. La articulación 1, el giro del hombro, hace girar todo el brazo alrededor de un eje vertical en la base. Las articulaciones 2, 3 y 4, la elevación del hombro, la flexión del codo y la flexión de la muñeca, doblan el brazo en un mismo plano. La articulación 5, el giro de la muñeca, hace girar la pinza alrededor del eje del antebrazo. La articulación 6 es la pinza. El ID del motor de cada articulación es su número. Las longitudes de los eslabones y los ejes siguen el modelo oficial del SO-101.1234561Giro del hombro2Elevación del hombro3Flexión del codo4Flexión de la muñeca5Giro de la muñeca6PinzaID motor = n.º articulación.Orden de asignación: de 6 a 1.Brazo seguidor, vista lateral, proporciones del modelo oficialSO-101.En el líder, la articulación 6 es el gatillo.
Las seis articulaciones de un brazo SO-101 y el ID del motor de cada una

Conecta una placa de control al ordenador por USB, aliméntala y ejecuta el buscador de puertos. Desconecta solo el cable USB de esa placa cuando se te pida y pulsa Enter; el script muestra el puerto, por ejemplo /dev/ttyACM0 en Linux, /dev/tty.usbmodem… en macOS o COM3 en Windows. Vuelve a conectar el cable y repite el proceso con la segunda placa. En Linux puede que tengas que permitir el acceso con sudo chmod 666 en cada puerto (por ejemplo, /dev/ttyACM0 y /dev/ttyACM1).

Encontrar el puerto de una placa de control
lerobot-find-port

Ejecuta el script de configuración primero para el brazo seguidor y luego para el brazo líder, cada uno con su propio puerto. El script nombra un motor cada vez, así que lee los pasos siguientes antes de ejecutarlo.

Asignar los ID de los motores del brazo seguidor
lerobot-setup-motors \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0

El brazo líder usa las opciones de teleoperador en lugar de las del robot. En cada indicación, toma el motor con la relación de transmisión que figura para esa articulación en la tabla de la sección de piezas (en el brazo líder, 1/191 para el giro del hombro y la flexión del codo, 1/345 para la elevación del hombro y 1/147 para la flexión de la muñeca, el giro de la muñeca y la pinza), y marca cada motor con su ID en cuanto el script indique que está asignado.

Asignar los ID de los motores del brazo líder
lerobot-setup-motors \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1
  1. El script nombra un motor cada vez, empezando por la pinza (ID 6) y terminando por el giro del hombro (ID 1). Conecta solo ese motor a la placa de control; no debe estar encadenado a ningún otro motor.
  2. Pulsa Enter. Cuando el script indique que el ID está asignado, desconecta el cable de ese motor de la placa, conecta el siguiente motor que nombre y pulsa Enter de nuevo.
  3. Comprueba los cables de alimentación, USB y de 3 pines antes de cada Enter. Si el script indica un error, revisa primero estos cables, y en una placa Waveshare los dos puentes deben estar en el canal B (USB).
  4. Cuando el script termine, encadena los motores en orden y conecta el motor del giro del hombro (ID 1) a la placa de control.

    Desliza hacia los lados para ver toda la figura.

    Asignar los ID de los motores servo a servo y encadenar después los servos en ordenPanel superior: mientras se asignan los ID, solo hay un servo conectado a la placa de control. El script nombra los servos en el orden 6, 5, 4, 3, 2, 1. Panel inferior: tras la configuración, los servos se encadenan en orden. El servo 1 se conecta a la placa de control y cada servo siguiente se conecta al anterior, hasta el servo 6.Al asignar los IDSolo está conectado el servo que se configura. Desconéctalo y conecta el siguiente quenombre el script.Controladora?Orden que pide el script654321Tras la configuraciónEncadena los servos en orden. El servo 1 se conecta a la placa de control.Controladora123456
    Asignar los ID de los motores servo a servo y encadenar después los servos en orden

Montar los brazos líder y seguidor

Ambos brazos comparten la mayoría de las piezas impresas y se montan en el mismo orden (la pieza del giro de la muñeca es distinta, y el brazo líder tiene un mango y un gatillo donde el brazo seguidor tiene una mandíbula móvil): base y hombro, brazo superior, antebrazo, muñeca y, por último, la pinza en el brazo seguidor o el mango y el gatillo en el brazo líder. Hugging Face publica un vídeo breve para cada articulación en su página de SO-101; síguelo junto con estas notas. Retira primero todo el material de soporte de las piezas impresas y conecta un cable de 3 pines a cada servo antes de cerrarlo dentro de la pieza.

  1. Articulación 1, giro del hombro: coloca ambos cuernos (horns) en el motor y fija el superior con un tornillo M3×6 (el cuerno inferior no necesita ninguno). Instala el motor en la base con cuatro tornillos M2×6, desliza el primer soporte de motor con dos M2×6, fija el hombro con cuatro M3×6 por arriba y cuatro por abajo, y añade el soporte del motor del hombro.
  2. Articulación 2, elevación del hombro: coloca ambos cuernos y fija el superior con un tornillo M3×6 (el cuerno inferior no necesita ninguno), desliza el motor desde arriba, fíjalo con cuatro M2×6 y une después el brazo superior con cuatro M3×6 a cada lado.
  3. Articulación 3, codo: coloca ambos cuernos y fija el superior con un tornillo M3×6 (el cuerno inferior no necesita ninguno), inserta el motor 3 con cuatro M2×6 y conecta el antebrazo a él con cuatro M3×6 a cada lado.
  4. Articulación 4, flexión de la muñeca: coloca ambos cuernos y fija el superior con un tornillo M3×6 (el cuerno inferior no necesita ninguno), encaja el soporte del motor 4, desliza dentro el motor 4 y fíjalo con cuatro M2×6.
  5. Articulación 5, giro de la muñeca: coloca el motor 5 en el soporte de la muñeca con dos M2×6 en la parte delantera, monta un solo cuerno con un tornillo M3×6 y fija la muñeca al motor 4 con tornillos M3×6 como se muestra en el vídeo oficial de la Articulación 5 (la guía escrita indica cuatro a cada lado).
  6. Pinza del brazo seguidor: fija la pinza al cuerno del motor de la muñeca con cuatro M3×6, coloca el motor de la pinza con dos M2×6 a cada lado, monta ambos cuernos y fija el superior con un tornillo M3×6 (el cuerno inferior no necesita ninguno), y fija la garra con tornillos M3×6 como se muestra en el vídeo oficial de la pinza (la guía escrita indica cuatro a cada lado).
  7. Mango del brazo líder: monta el soporte del brazo líder en la muñeca con cuatro M3×6, fija el mango a él con un M2×6, coloca el motor 6, el motor del gatillo (la guía oficial lo llama motor de la pinza), con dos M2×6 a cada lado y un cuerno con un tornillo M3×6, y fija después el gatillo con cuatro M3×6.
  8. Antes de dar corriente, gira lentamente a mano cada articulación a lo largo de todo su recorrido y no la fuerces nunca más allá de un tope; debe moverse sin rozar. Marca cada motor con su ID antes de cerrarlo dentro de la pieza y sujeta ambas bases a la mesa con abrazaderas.

Calibrar los dos brazos

La calibración registra el rango de cada articulación para que el brazo líder y el brazo seguidor indiquen los mismos números en la misma postura física. También permite que una política entrenada con un robot funcione en otro. Hazla una vez por brazo, y de nuevo tras un cambio de hardware o cuando LeRobot indique que falta una calibración. Las grabaciones y las políticas hechas antes de recalibrar usaron la calibración anterior.

Calibra primero el brazo seguidor. El script te pide que lleves cada articulación al centro de su rango y pulses Enter, y que después muevas cada articulación por todo su rango de movimiento y pulses Enter de nuevo cuando todas las articulaciones lo hayan recorrido. Dale a cada brazo un id único; ese nombre identifica su archivo de calibración. Los comandos de esta guía usan /dev/ttyACM0 para el brazo seguidor y /dev/ttyACM1 para el brazo líder como ejemplos: sustitúyelos por los puertos que hayas encontrado y no intercambies los dos brazos.

Desliza hacia los lados para ver toda la figura.

Calibración: primero el centro de cada rango y después el rango completo de cada articulaciónDos paneles lado a lado. Paso 1: cada una de las seis articulaciones se mantiene en el centro de su rango, representado por un punto en el centro de una barra, y después pulsas Enter. Paso 2: cada una de las seis articulaciones se mueve por todo su rango, representado por una flecha doble desde el extremo mínimo hasta el máximo de la barra. Abajo: la misma postura física da los mismos valores de posición en el brazo líder y en el seguidor.Paso 1: el centroLleva cada articulación al centro de surango y pulsa Enter.123456centroPaso 2: el rango completoMueve cada articulación por todo su rangoy pulsa Enter de nuevo.123456mín.máx.Misma postura física, mismos valores de posición en líder y seguidor.
Calibración: primero el centro de cada rango y después el rango completo de cada articulación
Calibrar el brazo seguidor
lerobot-calibrate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm

Calibra después el brazo líder con los mismos movimientos.

Calibrar el brazo líder
lerobot-calibrate \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm

Usa el mismo id en todos los comandos posteriores; así encuentra LeRobot el archivo de calibración, que se guarda por defecto en ~/.cache/huggingface/lerobot/calibration. Haz una copia de seguridad y no lo dejes en carpetas temporales: un constructor de la comunidad perdió los archivos de calibración en un ciclo de apagado y encendido y rehízo la calibración sin poner todas las articulaciones en el centro de su rango, lo que dio a algunas articulaciones desfases de origen (homing offsets) erróneos.

Teleoperar el brazo seguidor con el brazo líder

La teleoperación conecta los dos brazos: el brazo seguidor copia al brazo líder. Si falta una calibración, el comando inicia primero el procedimiento de calibración. Empieza con movimientos pequeños y lentos, mantente lejos de las articulaciones del brazo seguidor y ten la fuente de alimentación al alcance.

Teleoperar
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

Añade ahora las cámaras. Lístalas con el buscador de cámaras, que muestra el identificador de cada una y guarda un fotograma de prueba de cada una en outputs/captured_images; abre los fotogramas para ver qué índice corresponde a cada cámara. Los índices pueden cambiar tras un reinicio o al volver a conectar una cámara.

Listar las cámaras
lerobot-find-cameras opencv

Vuelve a teleoperar con las cámaras conectadas y una vista en directo en Rerun. Los nombres de cámara que elijas aquí, como top y wrist, se convertirán más adelante en las claves del conjunto de datos, así que usa a partir de ahora los mismos nombres y ajustes.

Teleoperar con cámaras y vista en directo
lerobot-teleoperate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {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

Colocar las cámaras para que la política pueda aprender

Una política solo ve las imágenes de las cámaras y las posiciones de las articulaciones, de modo que una buena disposición de las cámaras importa más que una resolución alta. 640×480 a 30 fps basta para la mayoría de las tareas y mantiene rápidos la grabación y el entrenamiento.

Desliza hacia los lados para ver toda la figura.

Colocación de las cámaras: vistas fijas de la tarea, luz uniforme y los nombres que se convierten en claves del conjunto de datosVista lateral de un espacio de trabajo. El brazo seguidor se acerca a un objeto situado junto a un recipiente de destino. Una cámara cenital sobre un soporte, encima de la mesa, mira hacia abajo todo el espacio de trabajo, representado como un campo de visión sombreado que cubre el brazo, el objeto y el destino. Una cámara de muñeca en la pinza mira a lo largo de las mandíbulas. Un panel de luz suave arriba a la izquierda ilumina la escena de manera uniforme. Las cámaras permanecen fijas entre la grabación y la ejecución. Los nombres de las cámaras se convierten en las claves del conjunto de datos, observation.images.top y observation.images.wrist.Luz difusaObjetoDestinocámara cenitalcámara de muñecaFija las cámaras con firmeza: no las muevas entre la grabación y la ejecución.Nombre de cámara = clave de datos:observation.images.topobservation.images.wrist
Colocación de las cámaras: vistas fijas de la tarea, luz uniforme y los nombres que se convierten en claves del conjunto de datos
  1. Ilumina la escena de forma uniforme con luz difusa. Evita la luz solar directa, los reflejos intensos y las sombras en movimiento: si la iluminación difiere entre la grabación y la ejecución, la política puede fallar.
  2. Fija las cámaras con firmeza y no las muevas nunca entre la grabación y la ejecución. La primera política de un constructor de la comunidad solo daba picotazos contra la mesa, y una de varias causas era que las cámaras se habían desplazado ligeramente entre la grabación y la prueba.
  3. Encuadra la tarea: el objeto, la pinza y el destino deben verse en al menos una cámara. Una buena prueba es preguntarte si serías capaz de hacer la tarea únicamente con las imágenes de las cámaras. El mismo constructor hizo las demostraciones mirando solo la imagen de las cámaras; si lo intentas, ten la fuente de alimentación al alcance.
  4. El mismo constructor sustituyó una cámara lateral, cuya vista de las puntas de la pinza era deficiente durante los agarres, por una cámara cenital junto a la cámara frontal, lo que redujo las oclusiones; una cámara de muñeca aparece en esa publicación solo como un paso siguiente. Si grabas a lo largo del día, fija la exposición y el balance de blancos en los ajustes propios de tu webcam; la configuración de cámara RealSense de LeRobot también acepta exposure, gain y white_balance.
  5. Con dos webcams idénticas en Ubuntu, las direcciones USB pueden intercambiarse y una grabación puede detenerse con un error de cámara. El mismo constructor lo resolvió con reglas udev que identifican cada cámara por su puerto USB físico, así que mantén cada cámara en el mismo puerto; si no, vuelve a ejecutar el buscador de cámaras tras cada reinicio.

Grabar un conjunto de datos

Los conjuntos de datos usan el formato LeRobotDataset y se suben al Hugging Face Hub. Crea una cuenta gratuita, genera un token con acceso de escritura en los ajustes de Hugging Face, inicia sesión y guarda tu nombre de usuario en una variable. Define antes HUGGINGFACE_TOKEN con tu token, o ejecuta hf auth login por separado y pega el token cuando se te pida.

Iniciar sesión en Hugging Face
hf auth login --token ${HUGGINGFACE_TOKEN} --add-to-git-credential
HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')
echo $HF_USER

Graba primero cinco episodios para probar la configuración. Usa el mismo id de robot, los mismos puertos y los mismos ajustes de cámara que en la teleoperación, y describe la tarea con palabras sencillas.

Grabar un conjunto de datos
lerobot-record \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {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=${HF_USER}/record-test \
    --dataset.num_episodes=5 \
    --dataset.single_task="Grab the black cube" \
    --dataset.streaming_encoding=true

LeRobot añade la fecha y la hora al nombre del conjunto de datos, así que ${HF_USER}/record-test se guarda como ${HF_USER}/record-test_YYYYMMDD_HHMMSS. Usa ese nombre completo en los comandos posteriores; búscalo con ls ~/.cache/huggingface/lerobot/${HF_USER}, o añade --dataset.no_stamp=true para conservar el nombre que indicaste. El conjunto de datos se guarda en ~/.cache/huggingface/lerobot y se sube al Hub cuando termina la grabación. Un conjunto de datos subido desde una cuenta personal puede ser público, así que comprueba su visibilidad en el Hub y añade --dataset.private=true si debe ser privado; añade --dataset.push_to_hub=False para conservarlo solo en local. Para continuar una sesión detenida, vuelve a ejecutar el comando con --resume=true, el --dataset.repo_id completo con la marca de tiempo, --dataset.root con la carpeta local del conjunto de datos y --dataset.num_episodes con el número de episodios adicionales, no el total.

El tiempo de episodio y el tiempo de reinicio son de 60 segundos por defecto (--dataset.episode_time_s y --dataset.reset_time_s), y el número de episodios por defecto es 50. El teclado controla el flujo mientras grabas, como muestra la tabla siguiente.

Para un primer conjunto de datos útil, elige una tarea sencilla, como recoger un objeto desde varias posiciones y colocarlo en un recipiente. Graba al menos 50 episodios, unos 10 por posición, mantén constantes las cámaras y tu forma de agarrar, y añade variedad poco a poco. Vuelve a grabar los episodios fallidos. Cincuenta episodios en posiciones fijas son un punto de partida; espera una política que funcione sobre todo cerca de las posiciones que grabaste. LeRobot muestra una línea de cadencia tras cada episodio conservado y un resumen cuando termina la grabación. Si la frecuencia está muy por debajo del objetivo de 30 Hz, el conjunto de datos sigue declarando 30 Hz, así que el movimiento parece más rápido de lo que fue. Averigua qué ralentiza el bucle (en el ejemplo de la documentación eran las lecturas de las cámaras) y vuelve a grabar los episodios afectados en lugar de entrenar con ellos.

Revisa los datos antes de entrenar. Abre el conjunto de datos en el visualizador de conjuntos de datos de LeRobot en Hugging Face y reproduce un episodio en el robot para comprobar que el movimiento se repite. La reproducción mueve el brazo sin tu intervención, así que despeja el espacio de trabajo, coloca el brazo cerca de la primera postura del episodio y ten la fuente de alimentación al alcance.

Reproducir un episodio
lerobot-replay \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
    --dataset.episode=0

Desplázate horizontalmente para comparar todas las columnas.

TeclaAcción
Flecha derecha o nTerminar antes el episodio o el periodo de reinicio y pasar al siguiente
Flecha izquierda o rDescartar el episodio actual y grabarlo de nuevo
Esc o qDetener la sesión: se guarda el episodio en curso y después se codifican los vídeos y se sube el conjunto de datos (pulsa antes Flecha izquierda o r para descartar ese episodio)

Entrenar una política ACT

ACT (Action Chunking Transformer) es la política que se usa en el tutorial de LeRobot: se adapta a los motores y las cámaras guardados en tu conjunto de datos. La guía de hardware sitúa las políticas ligeras (ACT, VQ-BeT, TD-MPC) en unos 2 a 6 GB de memoria de GPU con un tamaño de lote de 8, como cifra orientativa. Entrena en una GPU NVIDIA (cuda); en Apple silicon cambia el comando a --policy.device=mps, que necesita macOS 15 o superior (en macOS 14 LeRobot recurre a la CPU, que no es adecuada para entrenar).

Inicia el entrenamiento con el nombre completo del conjunto de datos.

Entrenar una política ACT
lerobot-train \
    --dataset.repo_id=${HF_USER}/record-test_YYYYMMDD_HHMMSS \
    --policy.type=act \
    --output_dir=outputs/train/act_so101_test \
    --job_name=act_so101_test \
    --policy.device=cuda \
    --trackio.enable=true \
    --policy.repo_id=${HF_USER}/my_policy \
    --steps=20000

Sin --steps, el entrenamiento ejecuta 100.000 pasos, normalmente más de los que necesita un conjunto de datos pequeño: el aprendizaje por imitación suele converger en 5 a 10 pasadas por los datos. Un conjunto de datos de 50 episodios de 30 segundos a 30 fps contiene unos 45.000 fotogramas, que con un tamaño de lote de 8 son unos 5.600 pasos por pasada, así que de 5 a 10 pasadas son aproximadamente de 28.000 a 56.000 pasos. El comando anterior usa --steps=20000, unas tres pasadas y media, como primera ejecución corta; auméntalo si la política está poco entrenada y, si lo reduces mucho, fija también --policy.scheduler_decay_steps cerca de --steps. La guía de hardware estima aproximadamente de 30 a 60 minutos para cinco pasadas de ACT con un tamaño de lote de 8 en una RTX 3090 o 4090 y de 1 a 2 horas en una L4 o A10G, y de 6 a 14 horas con un tamaño de lote de 4 en un M1, M2 o M3 Max; la propia guía llama orientativas a estas cifras y dice que las ejecuciones reales pueden diferir en torno a un 50 %.

Si no tienes una GPU adecuada, entrena en Google Colab con el cuaderno de ACT, o ejecuta hf auth login y añade al mismo comando un tipo de hardware («flavor») de Hugging Face Jobs, como --job.target=a10g-small. Como ese comando activa Trackio, un trabajo necesita además --trackio.space_id=<user>/<space> (añade --trackio.private=true para mantener el Space privado), o bien elimina --trackio.enable=true. Los trabajos se facturan por segundo y tienen un límite de 48 horas salvo que fijes --job.timeout, suben por ti a un repositorio privado un conjunto de datos que solo esté en local y publican el modelo entrenado al final; hf jobs hardware muestra los tipos disponibles.

Los puntos de control se escriben en outputs/train/act_so101_test/checkpoints. Reanuda una ejecución interrumpida desde el último punto de control. Como el comando de entrenamiento define --policy.repo_id=${HF_USER}/my_policy, el modelo terminado se publica en ese repositorio al final (--policy.push_to_hub=false lo desactiva y --policy.private=true lo hace privado); para subir un punto de control tú mismo, usa el mismo nombre de repositorio para que --policy.path=${HF_USER}/my_policy lo encuentre.

Reanudar el entrenamiento y subir el modelo
lerobot-train \
    --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
    --resume=true

hf upload ${HF_USER}/my_policy \
    outputs/train/act_so101_test/checkpoints/last/pretrained_model

El script de entrenamiento de LeRobot no evalúa políticas en robots reales, así que deja algunos episodios fuera del entrenamiento, incluidas posiciones de partida que no hayas grabado, y prueba la política con ellos. Un constructor de la comunidad entrenó con 50 episodios (10 en cada una de cinco regiones de posiciones de partida) y observó un 60 % de éxito en episodios nuevos de esas regiones, pero solo un 10 % en episodios de una región excluida del entrenamiento. Tras aumentar los datos a 25 episodios por región, el mismo constructor alcanzó un 90 % y un 75 %. Son muestras pequeñas, evaluadas con los propios scripts del constructor.

Ejecutar la política en el brazo seguidor

Despliega una política entrenada con lerobot-rollout. Usa el mismo id de robot, los mismos nombres y ajustes de cámara y el mismo texto de tarea que usaste al grabar, y vuelve a ejecutar el buscador de puertos si has reiniciado o reconectado algo desde entonces. --duration se expresa en segundos; sin él, la política se ejecuta hasta que la detengas.

Ejecutar la política en el robot
lerobot-rollout \
    --strategy.type=base \
    --policy.path=${HF_USER}/my_policy \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm \
    --robot.cameras="{ top: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30} }" \
    --task="Grab the black cube" \
    --duration=60

La estrategia determina lo que ocurre durante la ejecución, como muestra la tabla siguiente. Una estrategia que graba un conjunto de datos necesita un nombre de repositorio que empiece por rollout_ después de tu nombre de usuario, por ejemplo --dataset.repo_id=${HF_USER}/rollout_so101_test; se le añade una marca de tiempo. Las estrategias de grabación como sentry usan --dataset.single_task en lugar de --task; consulta la documentación de LeRobot para ver los parámetros de cada estrategia.

En LeRobot v0.5.x y anteriores no existe lerobot-rollout; usa lerobot-record como se describe en la documentación de la v0.5.1. Los parámetros de entrenamiento de esta guía corresponden a la versión actual.

La primera vez, ejecuta con una duración corta (por ejemplo, 15 segundos), un espacio de trabajo despejado y un plan para detener el brazo; cortar la alimentación libera los motores, así que un brazo que no esté apoyado en algo puede caerse. Si el brazo da picotazos contra la mesa o se pasa de largo, revisa la configuración antes de culpar al modelo: el mismo id de calibración, las cámaras en el mismo sitio con los mismos nombres y la misma resolución, la misma iluminación y objetos en posiciones que cubra el conjunto de datos.

Desplázate horizontalmente para comparar todas las columnas.

EstrategiaQué hace
baseSe ejecuta de forma autónoma sin grabar, para pruebas rápidas
sentryGraba de forma continua y sube los datos automáticamente
highlightMantiene un búfer circular y lo guarda cuando pulsas una tecla
daggerRecopilación de datos con una persona en el bucle (human-in-the-loop)
episodicGraba episodio a episodio, con fases de reinicio entre ellos

Ampliar el montaje con LeKiwi

LeKiwi es una base móvil de tres ruedas que lleva un brazo seguidor SO-101. Una Raspberry Pi, u otro ordenador de 5 V con suficientes puertos USB para las cámaras y la placa de control de los motores (la página de LeKiwi indica dos o más), ejecuta el robot, y lo manejas desde un portátil con un brazo líder y el teclado. En la versión con cable todo se ejecuta en el portátil y se pueden omitir los pasos de la Pi. La lista de piezas, los archivos de impresión y las instrucciones de montaje de la base proceden del proyecto LeKiwi enlazado desde la página de LeKiwi de Hugging Face.

Desliza hacia los lados para ver toda la figura.

LeKiwi: el portátil maneja el robot por la red y la Raspberry Pi maneja los motoresA la izquierda, un portátil con el brazo líder, un teclado y el script teleoperate.py. A la derecha, el robot LeKiwi: una Raspberry Pi que ejecuta lekiwi_host, conectada por USB a una placa de control de motores y a las cámaras. La placa de control maneja los motores del brazo, con los ID 6 a 1, y los motores de las ruedas, con los ID 9, 8 y 7. El portátil y la Pi se comunican por la misma red mediante ZeroMQ, por los puertos 5555 para los comandos y 5556 para las observaciones. En la versión con cable todo se ejecuta en el portátil.PortátilBrazo líder (USB)Tecladoteleoperate.pyScript de ejemplo:remote_ip = dirección de la Pi.Misma redZeroMQ5555, 5556Robot LeKiwiRaspberry Pi(el host)lekiwi_hostControladoraCámarasMotores brazoID 6 – 1Motores ruedasID 9, 8, 7Versión con cable: sin Pi, todo se ejecuta en el portátil.
LeKiwi: el portátil maneja el robot por la red y la Raspberry Pi maneja los motores

Manejar la base con el teclado requiere un backend de teclado global, así que funciona en X11, en un escritorio de Windows o en macOS con el permiso Input Monitoring concedido a tu terminal, pero no en Wayland ni en equipos sin pantalla (headless).

  1. Construye dos brazos SO-101 siguiendo las secciones anteriores: uno para montar en la base y otro como brazo líder. Después monta la base.
  2. Instala Raspberry Pi OS, activa SSH y comprueba que puedes iniciar sesión con ssh <user>@<pi-ip>. Instala LeRobot en la Pi y en tu portátil como en la sección de instalación y añade después el extra de LeKiwi, que incluye el controlador de servos y ZeroMQ.
    Instalar el extra de LeKiwi
    pip install 'lerobot[lekiwi]'
  3. Configura todos los motores con un solo comando. Asigna a los motores del brazo los ID 6 a 1 y a las ruedas 9, 8 y 7; los ID de las ruedas deben coincidir con las posiciones de montaje que muestra la documentación de LeKiwi. LeKiwi usa una única placa de control.
    Asignar los ID de los motores de LeKiwi
    lerobot-setup-motors \
        --robot.type=lekiwi \
        --robot.port=/dev/ttyACM0
  4. Calibra el brazo seguidor en la Pi y el brazo líder en el portátil. La página de LeKiwi muestra --teleop.type=so100_leader para el brazo líder; comprueba qué clase de brazo líder crea examples/lekiwi/teleoperate.py y calibra con el mismo tipo y el mismo --teleop.id. Los motores de las ruedas no necesitan calibración.
    Calibrar el brazo de LeKiwi
    lerobot-calibrate \
        --robot.type=lekiwi \
        --robot.id=my_awesome_kiwi
  5. En la Pi, activa el entorno de LeRobot e inicia el host. Se detiene a los 30 segundos salvo que aumentes --host.connection_time_s (por ejemplo, a 600), algo necesario en sesiones más largas, como la grabación.
    Iniciar el host de LeKiwi en la Pi
    python -m lerobot.robots.lekiwi.lekiwi_host \
        --robot.id=my_awesome_kiwi \
        --host.connection_time_s=600
  6. En el portátil, edita examples/lekiwi/teleoperate.py en el repositorio del código fuente de LeRobot: asigna a remote_ip la dirección de la Pi, indica tus propios valores para el port y el id del brazo líder, y ejecútalo. En record.py define también HF_REPO_ID y TASK_DESCRIPTION; en replay.py define remote_ip, port, el id del conjunto de datos y el índice del episodio. Para ejecutar una política entrenada, la página de LeKiwi usa examples/lekiwi/evaluate.py (define remote_ip, port y el modelo); el comando lerobot-rollout de la sección anterior está escrito para un SO-101 independiente. La velocidad tiene tres modos, que se cambian con R y F: rápido 0,3 m/s y 90°/s, medio 0,2 m/s y 60°/s, lento 0,1 m/s y 30°/s.

Desplázate horizontalmente para comparar todas las columnas.

TeclaAcción
WAvanzar
AMoverse a la izquierda
SRetroceder
DMoverse a la derecha
ZGirar a la izquierda
XGirar a la derecha
RAumentar la velocidad
FReducir la velocidad

Lista de comprobación de problemas

Muchos problemas vienen de la alimentación, los cables, los puertos o una configuración que cambió entre la grabación y la ejecución. Repasa esta tabla antes de cambiar nada del código.

Para dudas sobre el propio LeRobot, la documentación de Hugging Face enlaza con su comunidad de Discord. Para las piezas de nuestra tienda, usa el botón de WhatsApp o el formulario de soporte.

Desplázate horizontalmente para comparar todas las columnas.

SíntomaQué comprobar
No se encuentra un puerto serie o se deniega el accesoVuelve a ejecutar el buscador de puertos con la placa alimentada y el cable USB conectado. En Linux permite el acceso con sudo chmod 666 en el puerto. Los puertos pueden cambiar tras un reinicio o al volver a conectar un cable, así que vuelve a ejecutar el buscador de puertos.
El script de ID no encuentra el motorRevisa la fuente de alimentación, el cable USB y el cable de 3 pines. Solo puede estar conectado el motor que se está configurando. En una placa Waveshare los dos puentes deben estar en el canal B (USB).
Los servos reutilizados no se encuentran o no respondenEs probable que su ID y su velocidad en baudios no coincidan con los del nuevo robot, como señala la guía del SO-101. Vuelve a ejecutar la configuración de los motores, un servo cada vez.
La calibración falla o el brazo se mueve mal después de calibrarCalibra de nuevo: primero pon todas las articulaciones en el centro de su rango y pulsa Enter, y luego mueve cada articulación por todo su rango. Un constructor de la comunidad que no centró todas las articulaciones acabó con desfases de origen (homing offsets) erróneos. Usa después el mismo id de robot.
Una cámara se desconecta o cambia su índiceVuelve a ejecutar el buscador de cámaras tras cada reinicio o reconexión. Dos webcams idénticas pueden intercambiar sus direcciones USB en Linux; un constructor de la comunidad lo resolvió con reglas udev basadas en el puerto USB físico.
Las teclas de grabación no hacen nadaInicia el comando desde una terminal interactiva y mantén el foco en ella; las teclas de letra n, r y q funcionan igual que las flechas y Esc. Solo manejar un robot con el teclado, como en LeKiwi, necesita X11, un escritorio de Windows o el permiso de macOS.
El entrenamiento no encuentra el conjunto de datosUsa el nombre completo del conjunto de datos, incluido el sufijo de fecha y hora.
La cadencia grabada está muy por debajo de 30 HzLee las líneas de cadencia que imprime la grabación. Si la lectura de las cámaras es lo que más tiempo consume, reduce la resolución o usa menos cámaras y vuelve a grabar: una política espera la misma configuración de cámaras en el momento de la ejecución, y los episodios grabados muy por debajo de 30 Hz se almacenan como si se hubieran ejecutado a 30 Hz.
La política da picotazos contra la mesa o se pasa de largoCompara el id de calibración, las posiciones y los nombres de las cámaras y la iluminación con los de la sesión de grabación, y comprueba que los objetos empiezan donde el conjunto de datos tiene ejemplos.
LeKiwi no se conecta o el host se detiene a los 30 segundosAverigua la dirección de la Pi con hostname -I, haz ping a esa dirección desde el portátil y prueba ssh <user>@<pi-ip>; activa SSH en sudo raspi-config si hace falta. El host se detiene a los 30 segundos salvo que definas --host.connection_time_s.

Fuentes del proyecto

Contacto