Tutorial del brazo robótico SO-ARM101 de 7 ejes

SO-ARM101 7-DOF · Preparación previa

Esta guía está dirigida a quienes, tras convertir el SO-ARM101 de 6 servos a 7 servos, quieren ejecutar el flujo completo con LeRobot (calibración → grabación → entrenamiento → despliegue). Código correspondiente: este repositorio (lerobot-7dof), un fork del lerobot oficial en el que solo se han modificado las configuraciones de motores relacionadas con SO.

---

0. Confirma primero tu brazo robótico

7 servos (todos STS3215); correspondencia entre los ID de servo y las articulaciones:

ID de servo	Nombre de articulación	Descripción
1	shoulder_pan	Rotación horizontal del hombro
2	shoulder_lift	Elevación del hombro
3	elbow_flex	Flexión del codo
4	wrist_flex	Inclinación de la muñeca (flexión arriba/abajo)
5	wrist_yaw	Guiñada de la muñeca (rotación izquierda/derecha de unos 90°) · el servo nuevo de esta conversión (insertado entre los antiguos n.º 4 y n.º 5)
6	wrist_roll	Balanceo de la muñeca · el antiguo motor de balanceo n.º 5, ID 5→6, la pieza impresa no cambia ni tampoco el nombre
7	gripper	Pinza · antes ID=6, tras la conversión pasa a 7

Orden de los datos de las articulaciones (orden de las dimensiones de las articulaciones en action / observation.state dentro del Parquet tras la grabación): shoulder_pan → shoulder_lift → elbow_flex → wrist_flex → wrist_yaw → wrist_roll → gripper.

⚠️ Nota: los datos, los archivos de calibración y los modelos ya entrenados de la versión de 6 servos son incompatibles con este repositorio; hay que rehacer todo el proceso siguiendo lo indicado a continuación.

---

1. Si has clonado el repositorio oficial de código, qué archivos hay que sustituir o modificar

Opción A: usar directamente el código de este repositorio (recomendado)

lerobot-7dof.zip

Opción B: sustitución manual tras clonar el lerobot oficial

Copiar de este repositorio 3 archivos sobre el clon oficial:

Archivo de este repositorio (origen)	Se copia sobre (destino)
src/lerobot/robots/so_follower/so_follower.py	El archivo del mismo nombre del clon oficial
src/lerobot/teleoperators/so_leader/so_leader.py	El archivo del mismo nombre del clon oficial
src/lerobot/robots/so_follower/robot_kinematic_processor.py	El archivo del mismo nombre del clon oficial (solo corrección de comentarios; no afecta a la funcionalidad, se puede omitir)

cp src/lerobot/robots/so_follower/so_follower.py          <clon oficial>/src/lerobot/robots/so_follower/so_follower.py
cp src/lerobot/teleoperators/so_leader/so_leader.py       <clon oficial>/src/lerobot/teleoperators/so_leader/so_leader.py

Requisito: que tu clon oficial tenga la misma estructura que la base de este repositorio (versión de lerobot 2026-08). Si las versiones difieren mucho, no sobrescribas archivos enteros; aplica en su lugar los dos cambios de la sección "Modificación manual" que aparece a continuación.

Modificación manual si las versiones no coinciden (solo dos cambios)

① Diccionario de motores (una copia en so_follower.py y otra en so_leader.py, con el mismo contenido) —— el bloque original

"wrist_flex": Motor(4, "sts3215", norm_mode_body),
"wrist_roll": Motor(5, "sts3215", norm_mode_body),
"gripper": Motor(6, "sts3215", MotorNormMode.RANGE_0_100),

se cambia por

"wrist_flex": Motor(4, "sts3215", norm_mode_body),
"wrist_yaw": Motor(5, "sts3215", norm_mode_body),   # Servo nuevo, rotación izquierda/derecha
"wrist_roll": Motor(6, "sts3215", norm_mode_body),  # Antiguo motor de balanceo n.º 5, ID 5→6
"gripper": Motor(7, "sts3215", MotorNormMode.RANGE_0_100),

② Lógica de calibración (el calibrate() de cada uno de los dos archivos) —— elimina el caso especial de la "articulación de vuelta completa": el bloque

full_turn_motor = "wrist_roll"
unknown_range_motors = [motor for motor in self.bus.motors if motor != full_turn_motor]
range_mins, range_maxes = self.bus.record_ranges_of_motion(unknown_range_motors)
range_mins[full_turn_motor] = 0
range_maxes[full_turn_motor] = 4095

se sustituye por una sola línea que registra el rango real de todas las articulaciones:

range_mins, range_maxes = self.bus.record_ranges_of_motion()

Por qué: la versión original fijaba wrist_roll (balanceo alrededor del eje del antebrazo) como una articulación capaz de girar una vuelta completa (0~4095) y codificaba su rango completo de forma rígida. Tras la conversión a 7-DOF, las articulaciones de muñeca n.º 5 y n.º 6 (yaw / roll) tienen topes mecánicos y no pueden girar por completo; fijar una vuelta completa haría que el código enviara comandos de articulación a ángulos que el mecanismo no puede alcanzar, con riesgo de daños. Ahora, durante la calibración, se registra manualmente el mínimo/máximo real de cada motor.

Nota sobre el doble brazo seguidor

bi_so_follower / bi_so_leader（src/lerobot/robots/bi_so_follower/、src/lerobot/teleoperators/bi_so_leader/）solo envuelven el brazo individual añadiendo los prefijos left_/right_, no contienen definiciones de motores. Basta con modificarlos archivos del brazo individual anteriorespara que los comandos de doble brazo (--robot.type=bi_so_follower) sean automáticamente 7-DOF.

1. Instalar LeRobot

• Equipo Ubuntu
• Equipo Windows
• Equipo MAC

2. Sustituir los archivos (adaptación a 7DOF)

• Sustituir los archivos (adaptación a 7DOF)

3. Puerto serie

• Ubuntu
• Equipo Windows
• Equipo MAC

4. Calibración

• Equipo Ubuntu
• Equipo Windows
• Equipo Mac

5. Teleoperación

• Equipo Ubuntu
• Equipo Windows
• Equipo Mac

6. Cámara y teleop.

• Equipo Ubuntu
• Equipo Windows
• Equipo Mac

7. Conjunto de datos

• Revisar y reproducir el conjunto de datos
• Notas de la recopilación del conjunto de datos
• Cuenta de Hugging Face (opcional)
• Subir el conjunto de datos a HuggingFace (opcional)
• Recopilación del conjunto de datos por enseñanza-Apretón de manos 200
• Recopilación del conjunto de datos por enseñanza

8. Entrenamiento

• Configuración del entorno de entrenamiento con GPU en la nube
• Línea de comandos de entrenamiento-ACT (recomendado para empezar)
• Línea de comandos de entrenamiento-Diffusion
• Línea de comandos de entrenamiento-pi0.5
• Línea de comandos de entrenamiento-pi0 (el de mejores resultados)
• Línea de comandos de entrenamiento-pi0fast
• Línea de comandos de entrenamiento-smolvla (recomendado para nivel avanzado)
• Subir el modelo a HuggingFace (opcional)
• Algoritmos de aprendizaje por imitación compatibles con LeRobot
• Entrenamiento local en Ubuntu
• Obtener el archivo de pesos del modelo
• Recomendaciones de parámetros de entrenamiento
• Curvas de entrenamiento en tiempo real con wandb

9. Inferencia

• Descripción de la línea de comandos
• Línea de comandos de inferencia-ACT
• Línea de comandos de inferencia-Diffusion
• Línea de comandos de inferencia-pi0.5
• Línea de comandos de inferencia-pi0
• Línea de comandos de inferencia-smolvla
• Bugs comunes y soluciones
• Inferencia en NVIDIA DGX Spark
• Inferencia en D-Robotics RDK S100