Ce que vous allez construire et ce qu’il vous faut
LeRobot est la bibliothèque de robotique open source de Hugging Face. Un seul jeu de commandes permet de déplacer un robot, d’enregistrer des démonstrations, d’entraîner une politique et de l’exécuter. Le SO-101 est son bras phare : vous déplacez à la main un bras pilote (leader), un bras suiveur (follower) le copie, et les mouvements enregistrés avec les images des caméras apprennent à un réseau de neurones à répéter la tâche tout seul.
Le travail comporte sept étapes : réunir les pièces et installer le logiciel, donner un ID à chaque moteur, assembler les deux bras, étalonner, téléopérer avec des caméras, enregistrer un jeu de données, puis entraîner et exécuter une politique. La dernière section de montage ajoute la base mobile LeKiwi, suivie d’une liste de dépannage.
Faites défiler horizontalement pour voir toute la figure.
Il vous faut deux bras (pièces dans la section suivante), pour chaque bras une carte de commande USB pour servomoteurs à bus série et une alimentation, un ordinateur avec Python 3.12 ou plus récent, deux caméras USB (les commandes de ce guide en utilisent deux), un compte Hugging Face gratuit pour les jeux de données et les points de contrôle, et un GPU pour l’entraînement. Un GPU d’ordinateur portable suffit pour la politique ACT utilisée ici, et un GPU loué convient aussi.
Nous avons compilé ce guide à partir de la documentation officielle et de retours de la communauté, sans tester chaque étape sur chaque révision du matériel. Les anciens tutoriels qui appellent control_robot.py ne s’appliquent pas à la version 0.7.0, qui utilise les commandes lerobot-*.
Pièces, impression et alimentation
Le projet SO-101 publie la nomenclature et les fichiers d’impression, et la page SO-101 de Hugging Face renvoie vers les deux. Une paire complète bras pilote et bras suiveur demande 12 servomoteurs Feetech STS3215, deux cartes de commande, deux alimentations, deux câbles USB-C et des serre-joints de table. Le montage utilise des vis M2×6 et M3×6 ; la nomenclature du projet ne les liste pas : vérifiez donc ce qui est fourni avec vos servomoteurs ou votre kit. Des pièces imprimées et des kits complets sont aussi vendus.
Le bras suiveur utilise six servomoteurs avec un rapport de réduction de 1/345. Le bras pilote utilise trois rapports différents, afin de pouvoir soutenir son propre poids tout en bougeant avec peu d’effort.
Adaptez l’alimentation aux servomoteurs. Le STS3215 7,4 V a un couple de blocage de 16,5 kg·cm à 6 V (un peu moins avec une alimentation de 5 V) et est normalement alimenté en 5 V. Le bras suiveur peut utiliser des servomoteurs 12 V (30 kg·cm) pour plus de puissance, mais il lui faut alors une alimentation de 12 V d’au moins 5 A ; le bras pilote utilise toujours des servomoteurs 7,4 V. Ne branchez jamais l’alimentation 12 V sur une carte qui porte des servomoteurs 7,4 V ; indiquez sur chaque alimentation sa tension et le bras auquel elle est destinée.
Faites défiler horizontalement pour voir toute la figure.
Imprimez en PLA+ avec une buse de 0,4 mm et des couches de 0,2 mm (ou une buse de 0,6 mm et des couches de 0,4 mm), avec un remplissage de 15 %. Les pièces de chaque bras sont fournies dans un seul fichier, orienté pour demander peu de supports ; gardez les supports hors des trous de vis horizontaux. Imprimez d’abord les pièces d’essai Gauge Zero et Gauge Tight et vérifiez-les avec un servomoteur ; si Gauge Zero ne s’ajuste pas comme dans la vidéo du projet, modifiez les réglages de votre imprimante et réimprimez cette pièce avant d’imprimer les bras.
Prévoyez des tournevis cruciformes Phillips n° 0 et n° 1 et fixez chaque base à la table avant de tester. Vous trouverez ci-dessous les liens vers les pièces que nous proposons pour ce montage.
Faites défiler horizontalement pour comparer toutes les colonnes.
| Articulation | ID du moteur | Rapport de réduction du bras pilote | Rapport de réduction du bras suiveur |
|---|---|---|---|
| Rotation de l’épaule | 1 | 1/191 | 1/345 |
| Élévation de l’épaule | 2 | 1/345 | 1/345 |
| Flexion du coude | 3 | 1/191 | 1/345 |
| Flexion du poignet | 4 | 1/147 | 1/345 |
| Rotation du poignet | 5 | 1/147 | 1/345 |
| Pince | 6 | 1/147 | 1/345 |
Installer LeRobot et la prise en charge des moteurs
LeRobot 0.7.0 nécessite Python 3.12 ou plus récent. Créez un environnement isolé avec conda (de miniforge) ou uv, et activez-le dans chaque nouveau terminal. ffmpeg est nécessaire pour la vidéo sur la plupart des plateformes (sur macOS Intel et sur Linux ARM 32 bits, LeRobot se rabat sur PyAV et vous pouvez vous en passer) ; le paquet conda fonctionne avec toutes les versions de PyTorch.
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forgeInstallez LeRobot depuis PyPI avec les extras dont vous avez besoin. core_scripts ajoute ce qu’utilisent l’enregistrement, le rejeu et l’étalonnage, feetech ajoute la prise en charge des servomoteurs STS3215, et training ajoute les outils d’entraînement.
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'Remarques selon la plateforme : sur Apple silicon, PyTorch demande macOS 14 ou plus récent, et macOS 15 ou plus récent pour l’accélération GPU (MPS). Pour utiliser un GPU NVIDIA sous Linux, les versions de PyTorch par défaut demandent un pilote 580.65 ou plus récent ; avec un pilote plus ancien, installez d’abord une version CUDA de PyTorch correspondante et prenez torchcodec sur l’index CPU (voir la page d’installation de Hugging Face). Dans WSL, installez aussi evdev (conda install evdev -c conda-forge, ou avec uv sudo apt install libevdev-dev puis uv pip install evdev). Avec PyTorch 2.10 ou plus récent, vous pouvez utiliser le ffmpeg du système à la place de celui de conda.
Trouver les ports et attribuer les ID des moteurs
Les servomoteurs STS3215 neufs sont généralement livrés avec l’ID 1, et le contrôleur et chaque servomoteur doivent partager le même débit en bauds. LeRobot écrit les deux une seule fois dans la mémoire de chaque servomoteur : faites-le donc avant le montage, en connectant un servomoteur à la fois. Les servomoteurs réutilisés d’un autre robot en ont probablement aussi besoin.
Faites défiler horizontalement pour voir toute la figure.
Reliez une carte de commande à l’ordinateur par USB, alimentez-la, puis lancez le détecteur de ports. Quand le script le demande, débranchez uniquement le câble USB de cette carte et appuyez sur Entrée ; il affiche alors le port, par exemple /dev/ttyACM0 sous Linux, /dev/tty.usbmodem… sous macOS ou COM3 sous Windows. Rebranchez le câble, puis répétez l’opération pour la seconde carte. Sous Linux, il peut être nécessaire d’autoriser l’accès avec sudo chmod 666 sur chaque port (par exemple /dev/ttyACM0 et /dev/ttyACM1).
lerobot-find-portLancez le script de configuration pour le bras suiveur, puis pour le bras pilote, chacun avec son propre port. Le script désigne un moteur à la fois : lisez donc les étapes ci-dessous avant de le lancer.
lerobot-setup-motors \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0Le bras pilote utilise les options du téléopérateur à la place de celles du robot. À chaque invite, prenez le moteur dont le rapport de réduction est celui indiqué pour cette articulation dans le tableau de la section sur les pièces (sur le bras pilote : 1/191 pour la rotation de l’épaule et la flexion du coude, 1/345 pour l’élévation de l’épaule et 1/147 pour la flexion du poignet, la rotation du poignet et la pince), et marquez chaque moteur avec son ID dès que le script indique qu’il est attribué.
lerobot-setup-motors \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1- Le script désigne un moteur à la fois, en commençant par la pince (ID 6) et en terminant par la rotation de l’épaule (ID 1). Connectez uniquement ce moteur à la carte de commande ; il ne doit être chaîné à aucun autre moteur.
- Appuyez sur Entrée. Quand le script indique que l’ID est attribué, débranchez le câble de ce moteur de la carte, connectez le moteur suivant qu’il désigne et appuyez de nouveau sur Entrée.
- Vérifiez l’alimentation, l’USB et les câbles à 3 broches avant chaque Entrée. Si le script signale une erreur, vérifiez d’abord ces câbles ; sur une carte Waveshare, les deux cavaliers doivent être sur le canal B (USB).
- Quand le script a terminé, chaînez les moteurs dans l’ordre et connectez le moteur de rotation de l’épaule (ID 1) à la carte de commande.
Faites défiler horizontalement pour voir toute la figure.
Attribution des ID un servomoteur à la fois, puis chaînage des servomoteurs dans l’ordre
Assembler les bras pilote et suiveur
Les deux bras partagent la plupart des pièces imprimées et se montent dans le même ordre (la pièce de rotation du poignet diffère, et le bras pilote a une poignée et une gâchette là où le bras suiveur a une mâchoire mobile) : base et épaule, haut du bras, avant-bras, poignet, puis la pince sur le bras suiveur ou la poignée et la gâchette sur le bras pilote. Hugging Face publie une courte vidéo pour chaque articulation sur sa page SO-101 ; suivez-la en vous aidant de ces notes. Retirez d’abord tous les supports d’impression des pièces, et branchez un câble à 3 broches sur chaque servomoteur avant de le refermer dans la structure.
- Articulation 1, rotation de l’épaule : montez les deux palonniers sur le moteur et fixez celui du haut avec une vis M3×6 (celui du bas n’en demande pas). Placez le moteur dans la base avec quatre vis M2×6, glissez le premier support de moteur et fixez-le avec deux M2×6, fixez l’épaule avec quatre M3×6 dessus et quatre dessous, puis ajoutez le support de moteur de l’épaule.
- Articulation 2, élévation de l’épaule : montez les deux palonniers et fixez celui du haut avec une vis M3×6 (celui du bas n’en demande pas), glissez le moteur par le haut, fixez-le avec quatre M2×6, puis fixez le haut du bras avec quatre M3×6 de chaque côté.
- Articulation 3, coude : montez les deux palonniers et fixez celui du haut avec une vis M3×6 (celui du bas n’en demande pas), insérez le moteur 3 avec quatre M2×6, puis reliez-y l’avant-bras avec quatre M3×6 de chaque côté.
- Articulation 4, flexion du poignet : montez les deux palonniers et fixez celui du haut avec une vis M3×6 (celui du bas n’en demande pas), enfilez le support de moteur 4, glissez le moteur 4 et fixez-le avec quatre M2×6.
- Articulation 5, rotation du poignet : placez le moteur 5 dans le support du poignet avec deux M2×6 à l’avant, montez un seul palonnier avec une vis M3×6, puis fixez le poignet au moteur 4 avec des vis M3×6 comme dans la vidéo officielle de l’articulation 5 (le guide écrit en indique quatre de chaque côté).
- Pince du bras suiveur : fixez la pince au palonnier du moteur du poignet avec quatre M3×6, montez le moteur de la pince avec deux M2×6 de chaque côté, montez les deux palonniers et fixez celui du haut avec une vis M3×6 (celui du bas n’en demande pas), puis fixez la mâchoire avec des vis M3×6 comme dans la vidéo officielle de la pince (le guide écrit en indique quatre de chaque côté).
- Poignée du bras pilote : montez le support du bras pilote sur le poignet avec quatre M3×6, fixez-y la poignée avec une vis M2×6, montez le moteur 6, le moteur de la gâchette (le guide officiel l’appelle moteur de la pince), avec deux M2×6 de chaque côté et un palonnier avec une vis M3×6, puis fixez la gâchette avec quatre M3×6.
- Avant de mettre quoi que ce soit sous tension, tournez lentement chaque articulation à la main sur toute sa course, sans jamais la forcer au-delà d’une butée ; elle doit bouger sans frotter. Marquez chaque moteur avec son ID avant de le refermer dans la structure, et fixez les deux bases à la table.
Étalonner les deux bras
L’étalonnage enregistre la plage de chaque articulation afin que le bras pilote et le bras suiveur indiquent les mêmes valeurs dans la même pose physique. Il permet aussi à une politique entraînée sur un robot de fonctionner sur un autre. Faites-le une fois pour chaque bras, puis de nouveau après une modification matérielle ou lorsque LeRobot signale un étalonnage manquant. Les enregistrements et les politiques réalisés avant un nouvel étalonnage ont utilisé l’ancien étalonnage.
Étalonnez d’abord le bras suiveur. Le script vous demande de placer chaque articulation au milieu de sa plage et d’appuyer sur Entrée, puis de déplacer chaque articulation sur toute son amplitude et d’appuyer de nouveau sur Entrée quand toutes les articulations ont parcouru leur plage. Donnez à chaque bras un id unique ; ce nom identifie son fichier d’étalonnage. Les commandes de ce guide utilisent /dev/ttyACM0 pour le bras suiveur et /dev/ttyACM1 pour le bras pilote, à titre d’exemple : remplacez-les par les ports que vous avez trouvés et n’intervertissez pas les deux bras.
Faites défiler horizontalement pour voir toute la figure.
lerobot-calibrate \
--robot.type=so101_follower \
--robot.port=/dev/ttyACM0 \
--robot.id=my_follower_armÉtalonnez ensuite le bras pilote avec les mêmes mouvements.
lerobot-calibrate \
--teleop.type=so101_leader \
--teleop.port=/dev/ttyACM1 \
--teleop.id=my_leader_armUtilisez le même id dans toutes les commandes suivantes : c’est ainsi que LeRobot retrouve le fichier d’étalonnage, stocké par défaut dans ~/.cache/huggingface/lerobot/calibration. Sauvegardez-le et gardez-le hors des dossiers temporaires : un utilisateur de la communauté a perdu ses fichiers d’étalonnage lors d’une mise hors puis sous tension, puis a refait l’étalonnage sans placer chaque articulation au milieu de sa plage, ce qui a donné de mauvais décalages de référence (homing offsets) à certaines articulations.
Téléopérer le bras suiveur avec le bras pilote
La téléopération relie les deux bras : le bras suiveur copie le bras pilote. Si un étalonnage manque, la commande lance d’abord la procédure d’étalonnage. Commencez par des mouvements petits et lents, restez à l’écart des articulations du bras suiveur et gardez l’alimentation à portée de main.
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_armAjoutez ensuite les caméras. Listez-les avec le détecteur de caméras, qui affiche l’identifiant de chaque caméra et enregistre une image de test de chacune dans outputs/captured_images ; ouvrez ces images pour savoir quel index correspond à quelle caméra. Les index peuvent changer après un redémarrage ou lorsque vous rebranchez une caméra.
lerobot-find-cameras opencvTéléopérez de nouveau avec les caméras connectées et un affichage en direct dans Rerun. Les noms de caméra que vous choisissez ici, comme top et wrist, deviennent plus tard les clés du jeu de données : utilisez donc les mêmes noms et les mêmes réglages à partir de maintenant.
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=truePlacer les caméras pour que la politique puisse apprendre
Une politique ne voit que les images des caméras et les positions des articulations : une bonne installation des caméras compte donc plus qu’une haute résolution. 640×480 à 30 fps suffit pour la plupart des tâches et garde l’enregistrement et l’entraînement rapides.
Faites défiler horizontalement pour voir toute la figure.
- Éclairez la scène de façon uniforme avec une lumière diffuse. Évitez la lumière directe du soleil, les reflets forts et les ombres mouvantes : un éclairage qui diffère entre l’enregistrement et l’exécution peut faire échouer une politique.
- Fixez les caméras rigidement et ne les déplacez jamais entre l’enregistrement et l’exécution. La première politique d’un utilisateur de la communauté ne faisait que picorer la table ; parmi plusieurs causes, l’une était que les caméras avaient légèrement bougé entre l’enregistrement et le test.
- Cadrez la tâche : l’objet, la pince et la cible doivent être visibles dans au moins une caméra. Un bon test consiste à vous demander si vous pourriez réaliser la tâche vous-même à partir des seules images des caméras. Le même utilisateur de la communauté faisait ses démonstrations en regardant uniquement le flux des caméras ; si vous essayez ainsi, gardez l’alimentation à portée de main.
- Le même utilisateur a remplacé une caméra latérale, dont la vue sur le bout de la pince était mauvaise pendant les saisies, par une caméra placée au-dessus de la scène à côté de la caméra frontale, ce qui a réduit les occlusions ; une caméra de poignet n’apparaît dans ce message que comme étape suivante. Si vous enregistrez pendant la journée, fixez l’exposition et la balance des blancs dans les réglages propres à votre webcam ; la configuration de caméra RealSense de LeRobot accepte aussi
exposure,gainetwhite_balance. - Avec deux webcams identiques sous Ubuntu, les adresses USB peuvent s’échanger et un enregistrement peut s’arrêter sur une erreur de caméra. Le même utilisateur a résolu cela avec des règles udev qui identifient chaque caméra par son port USB physique : gardez donc chaque caméra sur le même port ; sinon, relancez le détecteur de caméras après chaque redémarrage.
Enregistrer un jeu de données
Les jeux de données utilisent le format LeRobotDataset et sont téléversés sur le Hugging Face Hub. Créez un compte gratuit, générez un jeton avec accès en écriture dans vos paramètres Hugging Face, puis connectez-vous et gardez votre nom d’utilisateur dans une variable. Définissez d’abord HUGGINGFACE_TOKEN avec votre jeton, ou exécutez hf auth login séparément et collez le jeton lorsqu’il vous est demandé.
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_USEREnregistrez d’abord cinq épisodes pour tester l’installation. Utilisez les mêmes ID de robot, ports et réglages de caméra qu’en téléopération, et décrivez la tâche avec des mots simples.
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 ajoute la date et l’heure au nom du jeu de données : ${HF_USER}/record-test est donc enregistré sous ${HF_USER}/record-test_YYYYMMDD_HHMMSS. Utilisez ce nom complet dans les commandes suivantes ; retrouvez-le avec ls ~/.cache/huggingface/lerobot/${HF_USER}, ou ajoutez --dataset.no_stamp=true pour garder le nom que vous avez indiqué. Le jeu de données est stocké dans ~/.cache/huggingface/lerobot et envoyé sur le Hub à la fin de l’enregistrement. Un jeu de données envoyé depuis un compte personnel peut être public : vérifiez sa visibilité sur le Hub et ajoutez --dataset.private=true s’il doit être privé ; ajoutez --dataset.push_to_hub=False pour le garder en local. Pour poursuivre une session interrompue, relancez la commande avec --resume=true, le --dataset.repo_id complet avec son horodatage, --dataset.root réglé sur le dossier local du jeu de données et --dataset.num_episodes réglé sur le nombre d’épisodes supplémentaires, et non sur le total.
La durée d’un épisode et la durée de réinitialisation valent 60 secondes par défaut (--dataset.episode_time_s et --dataset.reset_time_s), et le nombre d’épisodes par défaut est de 50. Le clavier pilote le déroulement pendant l’enregistrement, comme le montre le tableau ci-dessous.
Pour un premier jeu de données utile, choisissez une tâche simple, par exemple prendre un objet à plusieurs positions et le déposer dans un bac. Enregistrez au moins 50 épisodes, soit environ 10 par position, gardez des caméras et une façon de saisir cohérentes, et ajoutez de la variété progressivement. Réenregistrez les épisodes ratés. Cinquante épisodes à des positions fixes sont un point de départ : attendez-vous à une politique qui fonctionne surtout près des positions enregistrées. LeRobot affiche une ligne de cadence après chaque épisode conservé et un récapitulatif à la fin de l’enregistrement. Si la fréquence est bien inférieure à la cible de 30 Hz, le jeu de données déclare quand même 30 Hz : le mouvement paraît donc plus rapide qu’il ne l’était. Cherchez ce qui ralentit la boucle (dans l’exemple de la documentation, c’était la lecture des caméras) et réenregistrez les épisodes concernés au lieu de vous entraîner dessus.
Vérifiez les données avant l’entraînement. Ouvrez le jeu de données dans le visualiseur de jeux de données LeRobot sur Hugging Face, et rejouez un épisode sur le robot pour vérifier que le mouvement se répète. Le rejeu déplace le bras sans votre intervention : dégagez l’espace de travail, placez le bras près de la première pose de l’épisode avant de commencer et gardez l’alimentation à portée de main.
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=0Faites défiler horizontalement pour comparer toutes les colonnes.
| Touche | Action |
|---|---|
| Flèche droite ou n | Terminer l’épisode ou la période de réinitialisation en avance et passer à la suite |
| Flèche gauche ou r | Abandonner l’épisode en cours et l’enregistrer de nouveau |
| Esc ou q | Arrêter la session : l’épisode en cours est sauvegardé, puis les vidéos sont encodées et le jeu de données est téléversé (appuyez d’abord sur Flèche gauche ou r pour abandonner cet épisode) |
Entraîner une politique ACT
ACT (Action Chunking Transformer) est la politique utilisée dans le tutoriel LeRobot : elle s’adapte aux moteurs et aux caméras enregistrés dans votre jeu de données. Le guide matériel situe les politiques légères (ACT, VQ-BeT, TD-MPC) à environ 2 à 6 Go de mémoire GPU avec une taille de lot de 8, à titre indicatif. Entraînez sur un GPU NVIDIA (cuda) ; sur Apple silicon, modifiez la commande en --policy.device=mps, ce qui demande macOS 15 ou plus récent (sous macOS 14, LeRobot se rabat sur le CPU, qui ne convient pas à l’entraînement).
Lancez l’entraînement avec le nom complet du jeu de données.
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=20000Sans --steps, l’entraînement dure 100 000 pas, souvent plus qu’un petit jeu de données n’en demande : l’apprentissage par imitation converge généralement en 5 à 10 passes sur les données. Un jeu de données de 50 épisodes de 30 secondes à 30 fps contient environ 45 000 images, soit, avec une taille de lot de 8, environ 5 600 pas par passe ; 5 à 10 passes représentent donc environ 28 000 à 56 000 pas. La commande ci-dessus utilise --steps=20000, soit environ trois passes et demie, comme court premier essai ; augmentez cette valeur si la politique est sous-entraînée, et si vous la réduisez beaucoup, réglez aussi --policy.scheduler_decay_steps à une valeur proche de --steps. Le guide matériel estime à peu près 30 à 60 minutes pour cinq passes d’ACT avec une taille de lot de 8 sur une RTX 3090 ou 4090, et 1 à 2 heures sur un L4 ou un A10G, puis 6 à 14 heures avec une taille de lot de 4 sur un M1, M2 ou M3 Max ; il indique que ces chiffres sont approximatifs et que les exécutions réelles peuvent différer d’environ 50 %.
Sans GPU adapté, entraînez dans Google Colab avec le notebook ACT, ou exécutez hf auth login et ajoutez à la même commande un type de machine Hugging Face Jobs, comme --job.target=a10g-small. Comme cette commande active Trackio, un job demande aussi --trackio.space_id=<user>/<space> (ajoutez --trackio.private=true pour garder le Space privé), ou bien retirez --trackio.enable=true. Les jobs sont facturés à la seconde et limités à 48 heures sauf si vous réglez --job.timeout ; ils téléversent à votre place un jeu de données uniquement local dans un dépôt privé et envoient le modèle entraîné à la fin ; hf jobs hardware liste les types de machine.
Les points de contrôle sont écrits dans outputs/train/act_so101_test/checkpoints. Reprenez une exécution interrompue à partir du dernier point de contrôle. Comme la commande d’entraînement définit --policy.repo_id=${HF_USER}/my_policy, le modèle terminé est envoyé à la fin vers ce dépôt (--policy.push_to_hub=false le désactive, --policy.private=true le rend privé) ; pour téléverser vous-même un point de contrôle, utilisez le même nom de dépôt afin que --policy.path=${HF_USER}/my_policy le trouve.
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_modelLe script d’entraînement de LeRobot n’évalue pas les politiques sur un vrai robot : gardez donc de côté des épisodes hors de l’entraînement, y compris des positions de départ que vous n’avez pas enregistrées, et testez la politique dessus. Un utilisateur de la communauté a entraîné sur 50 épisodes (10 dans chacune de cinq régions de positions de départ) et a observé 60 % de réussite sur de nouveaux épisodes issus de ces régions, mais seulement 10 % sur des épisodes d’une région exclue de l’entraînement. Après être passé à 25 épisodes par région, le même utilisateur a atteint 90 % et 75 %. Ce sont de petits échantillons, évalués avec les propres scripts de l’utilisateur.
Exécuter la politique sur le bras suiveur
Déployez une politique entraînée avec lerobot-rollout. Utilisez le même ID de robot, les mêmes noms et réglages de caméra et le même texte de tâche que lors de l’enregistrement, et relancez le détecteur de ports si vous avez redémarré ou rebranché depuis. --duration est en secondes ; sans cette option, la politique tourne jusqu’à ce que vous l’arrêtiez.
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 stratégie définit ce qui se passe pendant l’exécution, comme le montre le tableau ci-dessous. Une stratégie qui enregistre un jeu de données demande un nom de dépôt qui commence par rollout_ après votre nom d’utilisateur, par exemple --dataset.repo_id=${HF_USER}/rollout_so101_test ; un horodatage y est ajouté. Les stratégies d’enregistrement comme sentry prennent --dataset.single_task à la place de --task ; consultez la documentation de LeRobot pour les options de chaque stratégie.
Sur LeRobot v0.5.x et antérieur, lerobot-rollout n’existe pas ; utilisez lerobot-record comme décrit dans la documentation de la version v0.5.1. Les options d’entraînement de ce guide visent la version actuelle.
Lors du premier essai, utilisez une durée courte (par exemple 15 secondes), un espace de travail dégagé et un plan pour arrêter le bras ; couper l’alimentation relâche les moteurs : un bras qui ne repose pas sur quelque chose peut donc tomber. Si le bras picore la table ou va trop loin, vérifiez d’abord l’installation avant d’accuser le modèle : même ID d’étalonnage, caméras au même endroit avec les mêmes noms et la même résolution, même éclairage, et objets dans des positions couvertes par le jeu de données.
Faites défiler horizontalement pour comparer toutes les colonnes.
| Stratégie | Ce qu’elle fait |
|---|---|
| base | S’exécute de façon autonome sans enregistrer, pour des tests rapides |
| sentry | Enregistre en continu et téléverse automatiquement |
| highlight | Garde un tampon circulaire et le sauvegarde quand vous appuyez sur une touche |
| dagger | Collecte de données avec un humain dans la boucle |
| episodic | Enregistre épisode par épisode avec des phases de réinitialisation entre les deux |
Prolonger le montage avec LeKiwi
LeKiwi est une base mobile à trois roues qui porte un bras suiveur SO-101. Un Raspberry Pi, ou un autre ordinateur alimenté en 5 V avec assez de ports USB pour les caméras et la carte de commande des moteurs (la page LeKiwi indique deux ou plus), fait fonctionner le robot, et vous le pilotez depuis un ordinateur portable avec un bras pilote et le clavier. Dans la version filaire, tout s’exécute sur l’ordinateur portable et les étapes du Pi peuvent être ignorées. La liste des pièces, les fichiers d’impression et les instructions de montage de la base proviennent du projet LeKiwi, lié depuis la page LeKiwi de Hugging Face.
Faites défiler horizontalement pour voir toute la figure.
Piloter la base au clavier demande un backend de touches global : cela fonctionne donc sous X11, sur un bureau Windows ou sous macOS avec l’accès à la surveillance de l’entrée (Input Monitoring) accordé à votre terminal, mais pas sous Wayland ni sur des machines sans écran.
- Construisez deux bras SO-101 avec les sections ci-dessus : un à monter sur la base et un comme bras pilote. Assemblez ensuite la base.
- Installez Raspberry Pi OS, activez SSH et vérifiez que vous pouvez vous connecter avec
ssh <user>@<pi-ip>. Installez LeRobot sur le Pi et sur votre ordinateur portable comme dans la section d’installation, puis ajoutez l’extra LeKiwi, qui apporte le pilote des servomoteurs et ZeroMQ.Installer l’extra LeKiwi pip install 'lerobot[lekiwi]' - Configurez tous les moteurs avec une seule commande. Elle attribue aux moteurs du bras les ID 6 à 1 et aux roues les ID 9, 8 et 7 ; les ID des roues doivent correspondre aux positions de montage indiquées dans la documentation de LeKiwi. LeKiwi utilise une seule carte de commande.
Attribuer les ID des moteurs de LeKiwi lerobot-setup-motors \ --robot.type=lekiwi \ --robot.port=/dev/ttyACM0 - Étalonnez le bras suiveur sur le Pi, et le bras pilote sur l’ordinateur portable. La page LeKiwi indique
--teleop.type=so100_leaderpour le bras pilote ; vérifiez quelle classe de bras pilote créeexamples/lekiwi/teleoperate.py, et étalonnez avec le même type et le même--teleop.id. Les moteurs des roues n’ont pas besoin d’étalonnage.Étalonner le bras de LeKiwi lerobot-calibrate \ --robot.type=lekiwi \ --robot.id=my_awesome_kiwi - Sur le Pi, activez l’environnement LeRobot et démarrez l’hôte. Il s’arrête au bout de 30 secondes, sauf si vous augmentez
--host.connection_time_s(par exemple à 600), ce qui est nécessaire pour les sessions plus longues, comme l’enregistrement.Démarrer l’hôte LeKiwi sur le Pi python -m lerobot.robots.lekiwi.lekiwi_host \ --robot.id=my_awesome_kiwi \ --host.connection_time_s=600 - Sur l’ordinateur portable, modifiez
examples/lekiwi/teleoperate.pydans le dépôt des sources de LeRobot : réglezremote_ipsur l’adresse du Pi, ainsi que leportet l’id du bras pilote sur vos propres valeurs, puis lancez-le. Dansrecord.py, réglez aussiHF_REPO_IDetTASK_DESCRIPTION; dansreplay.py, réglezremote_ip,port, l’id du jeu de données et l’index de l’épisode. Pour exécuter une politique entraînée, la page LeKiwi utiliseexamples/lekiwi/evaluate.py(réglezremote_ip,portet le modèle) ; la commandelerobot-rolloutde la section précédente est écrite pour un SO-101 autonome. La vitesse a trois modes, changés avec R et F : rapide 0,3 m/s et 90°/s, moyen 0,2 m/s et 60°/s, lent 0,1 m/s et 30°/s.
Faites défiler horizontalement pour comparer toutes les colonnes.
| Touche | Action |
|---|---|
| W | Avancer |
| A | Se déplacer vers la gauche |
| S | Reculer |
| D | Se déplacer vers la droite |
| Z | Tourner à gauche |
| X | Tourner à droite |
| R | Augmenter la vitesse |
| F | Diminuer la vitesse |
Liste de dépannage
De nombreux problèmes viennent de l’alimentation, des câbles, des ports ou d’une installation qui a changé entre l’enregistrement et l’exécution. Parcourez ce tableau avant de modifier le moindre code.
Pour les questions sur LeRobot lui-même, la documentation de Hugging Face renvoie vers sa communauté Discord. Pour les pièces de notre boutique, utilisez le bouton WhatsApp ou le formulaire d’assistance.
Faites défiler horizontalement pour comparer toutes les colonnes.
| Symptôme | À vérifier |
|---|---|
| Un port série est introuvable ou l’accès est refusé | Relancez le détecteur de ports avec la carte alimentée et le câble USB branché. Sous Linux, autorisez l’accès avec sudo chmod 666 sur le port. Les ports peuvent changer après un redémarrage ou un rebranchement : relancez donc le détecteur de ports. |
| Le script d’ID ne trouve pas le moteur | Vérifiez l’alimentation, le câble USB et le câble à 3 broches. Seul le moteur en cours de configuration doit être connecté. Sur une carte Waveshare, les deux cavaliers doivent être sur le canal B (USB). |
| Des servomoteurs réutilisés sont introuvables ou ne répondent pas | Leurs ID et leur débit en bauds ne correspondent vraisemblablement pas au nouveau robot, comme le note le guide du SO-101. Relancez la configuration des moteurs, un servomoteur à la fois. |
| L’étalonnage échoue, ou le bras bouge mal après l’étalonnage | Étalonnez de nouveau : placez d’abord chaque articulation au milieu de sa plage et appuyez sur Entrée, puis déplacez chaque articulation sur toute son amplitude. Un utilisateur de la communauté qui n’avait pas centré chaque articulation s’est retrouvé avec de mauvais décalages de référence (homing offsets). Utilisez ensuite le même ID de robot. |
| Une caméra se déconnecte ou son index change | Relancez le détecteur de caméras après chaque redémarrage ou rebranchement. Deux webcams identiques peuvent échanger leurs adresses USB sous Linux ; un utilisateur de la communauté a résolu cela avec des règles udev basées sur le port USB physique. |
| Les touches d’enregistrement ne font rien | Lancez la commande depuis un terminal interactif et gardez-le au premier plan ; les touches n, r et q fonctionnent aussi bien que les touches fléchées et Esc. Seul le pilotage d’un robot au clavier, comme sur LeKiwi, demande X11, un bureau Windows ou une autorisation macOS. |
| L’entraînement ne trouve pas le jeu de données | Utilisez le nom complet du jeu de données, avec son suffixe de date et d’heure. |
| La cadence enregistrée est très inférieure à 30 Hz | Lisez les lignes de cadence qu’affiche l’enregistrement. Si la lecture des caméras domine, baissez la résolution ou utilisez moins de caméras, puis réenregistrez : une politique attend la même configuration de caméras à l’exécution, et les épisodes enregistrés bien en dessous de 30 Hz sont stockés comme s’ils tournaient à 30 Hz. |
| La politique picore la table ou va trop loin | Comparez l’ID d’étalonnage, la position et le nom des caméras et l’éclairage avec la session d’enregistrement, et vérifiez que les objets démarrent là où le jeu de données contient des exemples. |
| LeKiwi ne se connecte pas, ou l’hôte s’arrête au bout de 30 secondes | Trouvez l’adresse du Pi avec hostname -I, faites un ping depuis l’ordinateur portable et testez ssh <user>@<pi-ip> ; activez SSH dans sudo raspi-config si nécessaire. L’hôte s’arrête au bout de 30 secondes, sauf si vous réglez --host.connection_time_s. |