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.
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.
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ón | ID del motor | Relación de transmisión del brazo líder | Relación de transmisión del brazo seguidor |
|---|---|---|---|
| Giro del hombro | 1 | 1/191 | 1/345 |
| Elevación del hombro | 2 | 1/345 | 1/345 |
| Flexión del codo | 3 | 1/191 | 1/345 |
| Flexión de la muñeca | 4 | 1/147 | 1/345 |
| Giro de la muñeca | 5 | 1/147 | 1/345 |
| Pinza | 6 | 1/147 | 1/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.
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forgeInstala 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.
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.
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).
lerobot-find-portEjecuta 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.
lerobot-setup-motors \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0El 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.
lerobot-setup-motors \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1- 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.
- 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.
- 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).
- 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 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.
- 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.
- 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.
- 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.
- 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.
- 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).
- 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).
- 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.
- 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.
lerobot-calibrate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_armCalibra después el brazo líder con los mismos movimientos.
lerobot-calibrate \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_armUsa 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.
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_armAñ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.
lerobot-find-cameras opencvVuelve 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.
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=trueColocar 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.
- 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.
- 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.
- 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.
- 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,gainywhite_balance. - 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.
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_USERGraba 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.
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=trueLeRobot 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.
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=0Desplázate horizontalmente para comparar todas las columnas.
| Tecla | Acción |
|---|---|
| Flecha derecha o n | Terminar antes el episodio o el periodo de reinicio y pasar al siguiente |
| Flecha izquierda o r | Descartar el episodio actual y grabarlo de nuevo |
| Esc o q | Detener 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.
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=20000Sin --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.
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_modelEl 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.
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=60La 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.
| Estrategia | Qué hace |
|---|---|
| base | Se ejecuta de forma autónoma sin grabar, para pruebas rápidas |
| sentry | Graba de forma continua y sube los datos automáticamente |
| highlight | Mantiene un búfer circular y lo guarda cuando pulsas una tecla |
| dagger | Recopilación de datos con una persona en el bucle (human-in-the-loop) |
| episodic | Graba 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.
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).
- 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.
- 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]' - 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 - 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_leaderpara el brazo líder; comprueba qué clase de brazo líder creaexamples/lekiwi/teleoperate.pyy 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 - 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 - En el portátil, edita
examples/lekiwi/teleoperate.pyen el repositorio del código fuente de LeRobot: asigna aremote_ipla dirección de la Pi, indica tus propios valores para elporty el id del brazo líder, y ejecútalo. Enrecord.pydefine tambiénHF_REPO_IDyTASK_DESCRIPTION; enreplay.pydefineremote_ip,port, el id del conjunto de datos y el índice del episodio. Para ejecutar una política entrenada, la página de LeKiwi usaexamples/lekiwi/evaluate.py(defineremote_ip,porty el modelo); el comandolerobot-rolloutde 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.
| Tecla | Acción |
|---|---|
| W | Avanzar |
| A | Moverse a la izquierda |
| S | Retroceder |
| D | Moverse a la derecha |
| Z | Girar a la izquierda |
| X | Girar a la derecha |
| R | Aumentar la velocidad |
| F | Reducir 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íntoma | Qué comprobar |
|---|---|
| No se encuentra un puerto serie o se deniega el acceso | Vuelve 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 motor | Revisa 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 responden | Es 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 calibrar | Calibra 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 índice | Vuelve 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 nada | Inicia 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 datos | Usa el nombre completo del conjunto de datos, incluido el sufijo de fecha y hora. |
| La cadencia grabada está muy por debajo de 30 Hz | Lee 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 largo | Compara 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 segundos | Averigua 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. |