Microduck Robot●microduck-robot.com

Microduck Robot / LEROBOT

Tutoriel LeRobot SO-101 : monter, étalonner, enregistrer, entraîner et exécuter

Ce guide suit la documentation officielle Hugging Face LeRobot pour les bras pilote et suiveur SO-101, ajoute les vérifications que l’on oublie le plus souvent et se termine par la base mobile LeKiwi et une liste de dépannage. Les commandes correspondent à LeRobot v0.7.0 (publiée le 5 novembre 2026). LeRobot évolue vite : comparez les options avec la documentation de la version que vous installez.

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.

Les sept étapes du montage, avec la commande qui réalise chacuneUne liste numérotée de sept étapes, de haut en bas. 1 Pièces et logiciel : pip install lerobot. 2 Ports et ID des moteurs : lerobot-find-port et lerobot-setup-motors. 3 Assembler les deux bras, à la main. 4 Étalonner : lerobot-calibrate. 5 Téléopérer avec des caméras : lerobot-find-cameras et lerobot-teleoperate. 6 Enregistrer un jeu de données : lerobot-record, et lerobot-replay pour le vérifier. 7 Entraîner et exécuter une politique : lerobot-train, puis lerobot-rollout.1Pièces et logicielPièces réunies, LeRobot installépip install lerobot2Ports et ID des moteursUn servomoteur à la foislerobot-find-portlerobot-setup-motors3Assembler les deux brasArticulation par articulationPas de commande : à monter à la main4ÉtalonnerMêmes valeurs sur les deux braslerobot-calibrate5Téléopérer avec camérasLe pilote déplace le suiveurlerobot-find-cameraslerobot-teleoperate6Enregistrer des donnéesPositions des articulations, vidéolerobot-recordlerobot-replay7Entraîner et exécuterPolitique ACT sur le bras suiveurlerobot-trainlerobot-rollout
Les sept étapes du montage, avec la commande qui réalise chacune

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.

Alimentation et USB du bras pilote et du bras suiveurUn ordinateur en haut est relié par un câble USB-C à la carte de commande du bras pilote et à la carte de commande du bras suiveur. Chaque carte de commande a sa propre alimentation. Six servomoteurs sont chaînés depuis chaque carte, en commençant par le servomoteur 1, avec des câbles à 3 broches. Le bras pilote utilise toujours des servomoteurs 7,4 V sur une alimentation de 5 V. Le bras suiveur utilise des servomoteurs 7,4 V sur une alimentation de 5 V, ou des servomoteurs 12 V sur une alimentation de 12 V d’au moins 5 A. Sur une carte Waveshare, les deux cavaliers sont placés sur le canal B, le canal USB.OrdinateurBras piloteAlimentation 5 VCarte moteursCarte Waveshare :les deux cavalierssur le canal B(USB).1234566 servomoteurs7,4 V, surl’alimentation 5 V.Bras suiveurAlimentation5 V, ou 12 V 5 A+Carte moteursCarte Waveshare :les deux cavalierssur le canal B(USB).123456Servomoteurs7,4 V sur 5 V,ou 12 V sur 12 V.AlimentationUSB-CCâble servo à 3 brochesJamais d’alimentation 12 V sur une carte avec des servomoteurs 7,4 V.
Alimentation et USB du bras pilote et du bras suiveur

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.

ArticulationID du moteurRapport de réduction du bras piloteRapport de réduction du bras suiveur
Rotation de l’épaule11/1911/345
Élévation de l’épaule21/3451/345
Flexion du coude31/1911/345
Flexion du poignet41/1471/345
Rotation du poignet51/1471/345
Pince61/1471/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.

Créer l’environnement
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forge

Installez 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.

Installer LeRobot avec ses extras
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.

Les six articulations d’un bras SO-101 et l’ID du moteur de chacuneVue de côté d’un bras robotisé. L’articulation 1, la rotation de l’épaule, fait tourner tout le bras autour d’un axe vertical à la base. Les articulations 2, 3 et 4, l’élévation de l’épaule, la flexion du coude et la flexion du poignet, plient le bras dans un même plan. L’articulation 5, la rotation du poignet, fait tourner la pince autour de l’axe de l’avant-bras. L’articulation 6 est la pince. L’ID du moteur de chaque articulation est son numéro. Les longueurs des segments et les axes suivent le modèle officiel du SO-101.1234561Rotation de l’épaule2Élévation de l’épaule3Flexion du coude4Flexion du poignet5Rotation du poignet6PinceID = n° de l’articulation.Ordre d’attribution : 6 à 1.Bras suiveur, vue de côté, proportions du SO-101 officiel.Sur le bras pilote, l’articulation 6 est la gâchette.
Les six articulations d’un bras SO-101 et l’ID du moteur de chacune

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).

Trouver le port d’une carte de commande
lerobot-find-port

Lancez 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.

Attribuer les ID des moteurs du bras suiveur
lerobot-setup-motors \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0

Le 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é.

Attribuer les ID des moteurs du bras pilote
lerobot-setup-motors \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1
  1. 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.
  2. 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.
  3. 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).
  4. 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’ordreVolet du haut : pendant l’attribution des ID, un seul servomoteur est relié à la carte de commande. Le script de configuration désigne les servomoteurs dans l’ordre 6, 5, 4, 3, 2, 1. Volet du bas : après la configuration, les servomoteurs sont chaînés dans l’ordre. Le servomoteur 1 est relié à la carte de commande et chaque servomoteur suivant est relié au précédent, jusqu’au servomoteur 6.Pendant l’attribution des IDSeul le servomoteur en cours est branché. Débranchez-le, puis branchez le suivant que lescript désigne.Carte moteurs?Ordre demandé par le script654321Après la configurationChaînez les servomoteurs dans l’ordre. Le servomoteur 1 est relié à la carte decommande.Carte moteurs123456
    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.

  1. 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.
  2. 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é.
  3. 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é.
  4. 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.
  5. 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é).
  6. 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é).
  7. 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.
  8. 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.

Étalonnage : d’abord le milieu de chaque plage, puis la course complète de chaque articulationDeux volets côte à côte. Étape 1 : chacune des six articulations est maintenue au milieu de sa plage, représenté par un point au centre d’une barre, puis vous appuyez sur Entrée. Étape 2 : chacune des six articulations est déplacée sur toute sa plage, représentée par une double flèche entre l’extrémité minimale et l’extrémité maximale de la barre. En dessous : la même pose physique donne les mêmes valeurs de position sur le bras pilote et sur le bras suiveur.Étape 1 : le milieuPlacez chaque articulation au milieu de saplage, puis appuyez sur Entrée.123456milieuÉtape 2 : la plage complèteDéplacez chaque articulation sur toute saplage, puis appuyez de nouveau sur Entrée.123456minmaxMême pose physique, mêmes valeurs de position sur les deux bras.
Étalonnage : d’abord le milieu de chaque plage, puis la course complète de chaque articulation
Étalonner le bras suiveur
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.

Étalonner le bras pilote
lerobot-calibrate \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm

Utilisez 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.

Téléopérer
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

Ajoutez 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.

Lister les caméras
lerobot-find-cameras opencv

Té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.

Téléopérer avec les caméras et un affichage en direct
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

Placer 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.

Placement des caméras : vues fixes de la tâche, lumière uniforme et noms qui deviennent des clés du jeu de donnéesVue de côté d’un espace de travail. Le bras suiveur atteint un objet situé à côté d’un récipient cible. Une caméra du haut, sur un support au-dessus de la table, regarde tout l’espace de travail vers le bas, ce que montre un champ de vision ombré qui couvre le bras, l’objet et la cible. Une caméra de poignet, sur la pince, regarde le long des mâchoires. Un panneau lumineux doux en haut à gauche éclaire la scène de façon uniforme. Les caméras restent fixes entre l’enregistrement et l’exécution. Les noms des caméras deviennent des clés du jeu de données, observation.images.top et observation.images.wrist.Lumière diffuseObjetCiblecaméra du hautcaméra de poignetFixation rigide : ne déplacez pas les caméras entre l’enregistrement et l’exécution.Noms de caméra = clés du jeu :observation.images.topobservation.images.wrist
Placement des caméras : vues fixes de la tâche, lumière uniforme et noms qui deviennent des clés du jeu de données
  1. É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.
  2. 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.
  3. 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.
  4. 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, gain et white_balance.
  5. 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é.

Se connecter à 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

Enregistrez 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.

Enregistrer un jeu de données
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 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.

Rejouer un épisode
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

Faites défiler horizontalement pour comparer toutes les colonnes.

ToucheAction
Flèche droite ou nTerminer l’épisode ou la période de réinitialisation en avance et passer à la suite
Flèche gauche ou rAbandonner l’épisode en cours et l’enregistrer de nouveau
Esc ou qArrê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.

Entraîner une politique 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

Sans --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.

Reprendre l’entraînement et téléverser le modèle
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

Le 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.

Exécuter la politique sur le 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 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égieCe qu’elle fait
baseS’exécute de façon autonome sans enregistrer, pour des tests rapides
sentryEnregistre en continu et téléverse automatiquement
highlightGarde un tampon circulaire et le sauvegarde quand vous appuyez sur une touche
daggerCollecte de données avec un humain dans la boucle
episodicEnregistre é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.

LeKiwi : l’ordinateur portable pilote le robot par le réseau, le Raspberry Pi pilote les moteursÀ gauche, un ordinateur portable avec le bras pilote, un clavier et le script teleoperate.py. À droite, le robot LeKiwi : un Raspberry Pi qui exécute lekiwi_host, relié en USB à une carte de commande des moteurs et aux caméras. La carte de commande pilote les moteurs du bras, ID 6 à 1, et les moteurs des roues, ID 9, 8 et 7. L’ordinateur portable et le Pi communiquent sur le même réseau avec ZeroMQ, sur les ports 5555 pour les commandes et 5556 pour les observations. Dans la version filaire, tout s’exécute sur l’ordinateur portable.Ordinateur portableBras pilote (USB)Clavierteleoperate.pyLancez l’exemple avecl’adresse du Pi en remote_ip.MêmeréseauZeroMQ5555, 5556Robot LeKiwiRaspberry Pi(hôte)lekiwi_hostCarte moteursCamérasMoteurs du brasID 6 – 1Moteurs de roueID 9, 8, 7Version filaire : pas de Pi, tout s’exécute sur l’ordinateur portable.
LeKiwi : l’ordinateur portable pilote le robot par le réseau, le Raspberry Pi pilote les moteurs

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.

  1. Construisez deux bras SO-101 avec les sections ci-dessus : un à monter sur la base et un comme bras pilote. Assemblez ensuite la base.
  2. 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]'
  3. 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
  4. Étalonnez le bras suiveur sur le Pi, et le bras pilote sur l’ordinateur portable. La page LeKiwi indique --teleop.type=so100_leader pour le bras pilote ; vérifiez quelle classe de bras pilote crée examples/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
  5. 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
  6. Sur l’ordinateur portable, modifiez examples/lekiwi/teleoperate.py dans le dépôt des sources de LeRobot : réglez remote_ip sur l’adresse du Pi, ainsi que le port et l’id du bras pilote sur vos propres valeurs, puis lancez-le. Dans record.py, réglez aussi HF_REPO_ID et TASK_DESCRIPTION ; dans replay.py, réglez remote_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 utilise examples/lekiwi/evaluate.py (réglez remote_ip, port et le modèle) ; la commande lerobot-rollout de 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.

ToucheAction
WAvancer
ASe déplacer vers la gauche
SReculer
DSe déplacer vers la droite
ZTourner à gauche
XTourner à droite
RAugmenter la vitesse
FDiminuer 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 moteurVé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 pasLeurs 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 changeRelancez 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 rienLancez 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éesUtilisez 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 HzLisez 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 loinComparez 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 secondesTrouvez 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.

Sources du projet

Contact