SO-ARM101 Braccio robotico 7 assi · Tutorial
SO-ARM101 7-DOF · Preparativi prima dell'esecuzione
Questa guida è rivolta a chi, dopo aver convertito il SO-ARM101 da 6 servomotori a 7 servomotori, vuole percorrere l'intero flusso con LeRobot (calibrazione → registrazione → addestramento → deployment). Codice di riferimento: questo repository (
lerobot-7dof), un fork del lerobot ufficiale in cui sono state modificate solo le configurazioni dei motori SO.
0. Prima di tutto, verifica il tuo braccio robotico
7 servomotori (tutti STS3215), corrispondenza tra ID servomotore e giunto:
| ID servomotore | Nome del giunto | Descrizione |
|---|---|---|
| 1 | shoulder_pan | Rotazione orizzontale della spalla |
| 2 | shoulder_lift | Sollevamento della spalla |
| 3 | elbow_flex | Flessione del gomito |
| 4 | wrist_flex | Flessione del polso (piegamento su/giù) |
| 5 | wrist_yaw | Imbardata del polso (rotazione destra/sinistra di circa 90°) · il servomotore aggiunto in questa modifica (inserito tra gli ex 4 e 5) |
| 6 | wrist_roll | Rollio del polso · era il motore di rollio n. 5, ID 5→6, pezzo stampato invariato, nome invariato |
| 7 | gripper | Pinza · ID originale = 6, dopo la modifica passa a 7 |
Ordine dei dati dei giunti (l'ordine delle dimensioni dei giunti di action / observation.state nei file Parquet dopo la registrazione): shoulder_pan → shoulder_lift → elbow_flex → wrist_flex → wrist_yaw → wrist_roll → gripper.
⚠️ Attenzione: i dati, i file di calibrazione e i modelli già addestrati della versione a 6 servomotori sono incompatibili con questo repository, occorre rifare tutto da capo seguendo la procedura riportata sotto.
1. Se hai clonato il repository ufficiale, quali file sostituire/modificare
Opzione A: usare direttamente il codice di questo repository (consigliato)
Opzione B: sostituzione manuale dopo il git clone del lerobot ufficiale
Da questo repository copiare 3 file nel clone ufficiale:
| File di questo repository (origine) | Sovrascrivere in (destinazione) |
|---|---|
src/lerobot/robots/so_follower/so_follower.py | file omonimo del clone ufficiale |
src/lerobot/teleoperators/so_leader/so_leader.py | file omonimo del clone ufficiale |
src/lerobot/robots/so_follower/robot_kinematic_processor.py | file omonimo del clone ufficiale (solo correzione di commenti, la funzionalità non è influenzata, si può non sostituire) |
cp src/lerobot/robots/so_follower/so_follower.py <clone ufficiale>/src/lerobot/robots/so_follower/so_follower.py
cp src/lerobot/teleoperators/so_leader/so_leader.py <clone ufficiale>/src/lerobot/teleoperators/so_leader/so_leader.pyPremessa: il tuo clone ufficiale deve avere la stessa struttura della baseline di questo repository (versione lerobot 2026-08). Se le versioni sono molto diverse, non sovrascrivere i file interi, applica invece le due "modifiche manuali" descritte sotto.
Modifiche manuali in caso di versioni non allineate (solo due punti)
① Dizionario dei motori (uno in so_follower.py e uno in so_leader.py, contenuto identico) —— sostituire
"wrist_flex": Motor(4, "sts3215", norm_mode_body),
"wrist_roll": Motor(5, "sts3215", norm_mode_body),
"gripper": Motor(6, "sts3215", MotorNormMode.RANGE_0_100),con
"wrist_flex": Motor(4, "sts3215", norm_mode_body),
"wrist_yaw": Motor(5, "sts3215", norm_mode_body), # Nuovo servomotore, rotazione sinistra/destra
"wrist_roll": Motor(6, "sts3215", norm_mode_body), # Ex motore di rollio n. 5, ID 5→6
"gripper": Motor(7, "sts3215", MotorNormMode.RANGE_0_100),② Logica di calibrazione (calibrate() in ciascuno dei due file) —— rimuovere il caso speciale del "giunto a giro completo": sostituire
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] = 4095con una sola riga, che registra l'escursione reale di tutti i giunti:
range_mins, range_maxes = self.bus.record_ranges_of_motion()Perché: la versione originale considerava
wrist_roll(rollio attorno all'asse dell'avambraccio) come un giunto in grado di compiere un giro completo (0~4095) e ne codificava l'intera escursione in modo fisso. Dopo la conversione a 7-DOF, i giunti del polso n. 5/6 (yaw / roll) hanno entrambi finecorsa meccanici e non possono compiere un giro completo; impostare forzatamente il giro completo farebbe inviare al codice comandi di giunto ad angoli fisicamente irraggiungibili, con rischio di danni. Ora in calibrazione si registrano manualmente i min/max reali di ogni motore.
Nota sul bi-braccio (doppio follower)
bi_so_follower / bi_so_leader (src/lerobot/robots/bi_so_follower/, src/lerobot/teleoperators/bi_so_leader/) si limitano a incapsulare il braccio singolo aggiungendo il prefisso left_/right_,senza definizioni di motori. Basta chei file del braccio singolo qui sopra siano stati modificati correttamente, e i comandi bi-braccio (--robot.type=bi_so_follower) sono automaticamente a 7-DOF.
1. Ambiente LeRobot
2. Sostituire i file (adattamento a 7DOF)
3. Porte seriali
4. Calibrazione
5. Teleoperazione
6. Con telecamera
7. Raccolta dataset
- Rivedere e riprodurre il dataset
- Note sulla raccolta del dataset
- Registrare un account Hugging Face (opzionale)
- Caricare il dataset su HuggingFace (opzionale)
- Raccolta del dataset tramite insegnamento-Stretta di mano 200
- Raccolta del dataset tramite insegnamento
8. Addestramento
- Configurazione dell'ambiente di addestramento su GPU cloud
- Comando di addestramento-ACT (consigliato per iniziare)
- Comando di addestramento-Diffusion
- Comando di addestramento-pi0.5
- Comando di addestramento-pi0 (risultati migliori)
- Comando di addestramento-pi0fast
- Comando di addestramento-smolvla (consigliato per progredire)
- Caricare il modello su HuggingFace (opzionale)
- Algoritmi di apprendimento per imitazione supportati da LeRobot
- Addestramento su Ubuntu locale
- Ottenere il file dei pesi del modello
- Suggerimenti sui parametri di addestramento
- Curve di addestramento in tempo reale con wandb