Enregistrer votre premier jeu de données LeRobot avec un SO-100

Un SO-100 suiveur, un bras leader de même conception et deux caméras USB peuvent affiner une politique en un après-midi. Le même banc peut tout aussi facilement produire soixante épisodes qui semblent sains dans un explorateur de fichiers et gaspiller une exécution GPU de six heures. La différence est rarement le modèle ; c'est ce qui s'est passé entre les servomoteurs et le fichier parquet.

Voici la voie manuelle, puis la plus courte. Chaque commande provient de lerobot 0.6.1, publié le 3 août 2026 et actuel sur PyPI. Il est passé aux points d'entrée de la console, donc les tutoriels qui exécutent python lerobot/scripts/control_robot.py décrivent un fichier qui n'existe plus.

Ce qu'une session d'enregistrement capture

Un jeu de données LeRobot n'est pas un dossier de vidéos mais une table indexée par le temps avec des vidéos jointes : chaque tic de boucle de contrôle écrit une ligne contenant l'action commandée, l'état atteint par le suiveur, une image par caméra, un horodatage et des indices. La politique ne voit que ces colonnes. Le schéma de lerobot/svla_so100_pickplace, lu depuis son meta/info.json.

Les articulations sont main_shoulder_pan, main_shoulder_lift, main_elbow_flex, main_wrist_flex, main_wrist_roll et main_gripper : les six degrés de liberté du SO-100. L'action et l'état partagent une forme car la téléopération leader-suiveur enregistre une cible et la position atteinte un pas plus tard. Cet écart est une information : là où le bras a lutté contre la gravité ou un objet coincé. Ces chaînes de caractères sont celles de ce jeu de données. Une session enregistrée avec la version 0.6.1 aujourd'hui écrit shoulder_pan.pos jusqu'à gripper.pos, IDs 1 à 6 sur le bus : les mêmes six articulations, des clés différentes, ce qui est important dès qu'une configuration adresse une caractéristique par son nom.

Ce dont vous avez besoin sur l'établi

Si le bras n'est pas encore construit, c'est une tâche pour une autre soirée : commencez par et le . Si vous n'avez encore rien acheté, lisez d'abord la : le SO-101 est la révision plus récente avec un câblage amélioré et sans étape de retrait d'engrenage, et le flux de travail d'enregistrement est identique.

Installer lerobot 0.6.1

conda create -y -n lerobot python=3.12
conda activate lerobot

# TorchCodec is the default video decoder and needs ffmpeg
conda install ffmpeg -c conda-forge

# core_scripts = dataset + hardware + viz extras (record, replay, calibrate)
# feetech     = SDK for the STS3215 bus servos in the SO-100
pip install 'lerobot[core_scripts,feetech]'

lerobot-info

Les extras sont ce qui pose le plus de problèmes. pip install lerobot installe uniquement les dépendances ML de base, rien qui ne communique avec un robot. Les bras Koch nécessitent dynamixel au lieu de feetech. Si votre shell n'a jamais entendu parler de lerobot-record, c'est la raison.

Ports, identifiants de moteur et calibration

Trois étapes uniques séparent les composants d'une boucle de téléopération fonctionnelle. permet à une politique entraînée sur votre bras de fonctionner sur celui de quelqu'un d'autre, en mappant les comptes bruts de l'encodeur sur une convention d'articulation partagée.

1. 1
   Trouver le port USB de chaque bras

   Exécutez-le avec les deux bras branchés, débranchez celui que vous identifiez lorsque vous y êtes invité, et notez quel port disparaît. Sous Linux, vous pourriez avoir besoin de sudo chmod 666 /dev/ttyACM0.

   bash

   lerobot-find-port
   # Finding all available ports for the MotorsBus.
   # Ports before disconnecting: ['/dev/ttyACM0', '/dev/ttyACM1']
   # Remove the USB cable from your MotorsBus and press Enter when done.
   # The port of this MotorsBus is '/dev/ttyACM1'
   # Reconnect the USB cable.

2. 2
   Écrire les identifiants de moteur et les débits en bauds

   Les identifiants sont écrits un moteur à la fois, et la documentation est stricte sur la manière de procéder : connectez exactement un moteur à la carte de contrôle, pas encore en série avec un autre. Le script parcourt la chaîne à l'envers, demandant d'abord la pince et lui attribuant l'ID 6, puis le poignet (wrist_roll) comme 5, jusqu'à l'épaule (shoulder_pan) comme 1. Faites-le avant l'assemblage.

   bash

   lerobot-setup-motors \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0
   
   lerobot-setup-motors \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1

3. 3
   Calibrer les deux bras

   Déplacez chaque articulation au milieu de sa plage, appuyez sur Entrée, puis balayez chacune sur toute sa plage. L'id devient le nom de fichier du profil.

   bash

   lerobot-calibrate \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0 \
       --robot.id=my_so100_follower
   
   lerobot-calibrate \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1 \
       --teleop.id=my_so100_leader

4. 4
   Téléopérer avant d'enregistrer quoi que ce soit

   Le test d'acceptation pour tout ce qui précède. Si la téléopération est saccadée, inversée, ou si une articulation ne suit pas, l'enregistrement le conserve en 50 épisodes.

   bash

   lerobot-teleoperate \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0 \
       --robot.id=my_so100_follower \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1 \
       --teleop.id=my_so100_leader \
       --display_data=true

Les caméras décident ce que la politique perçoit

lerobot-find-cameras opencv   # or: lerobot-find-cameras realsense

# --- Detected Cameras ---
# Camera #0:
#   Name: OpenCV Camera @ 0
#   Type: OpenCV
#   Id: 0
#   Backend api: AVFOUNDATION
#   Default stream profile:
#     Format: 16.0
#     Width: 1920
#     Height: 1080
#     Fps: 15.0

Deux vues, et leur positionnement est important : une caméra de scène fixe couvrant l'espace de travail, et une caméra de poignet près de l'effecteur terminal montrant ce que le préhenseur est sur le point de toucher. La liste de contrôle des jeux de données communautaires LeRobot demande de préférence deux vues à 480x640 / 720p ou mieux, un arrière-plan statique, un éclairage neutre et stable, et le bras du leader et les membres humains hors champ. Le guide d'enregistrement ajoute la règle empirique : vous devriez être capable d'effectuer la tâche vous-même en ne regardant que les images de la caméra.

La commande record et toutes les options

HF_USER=$(NO_COLOR=1 hf auth whoami | awk -F': *' 'NR==1 {print $2}')

lerobot-record \
    --robot.type=so100_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_so100_follower \
    --robot.cameras="{ top: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}, wrist: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30}}" \
    --teleop.type=so100_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_so100_leader \
    --display_data=true \
    --dataset.repo_id=${HF_USER}/so100_pick_cube \
    --dataset.single_task="Pick the red cube and drop it in the box" \
    --dataset.num_episodes=50 \
    --dataset.fps=30 \
    --dataset.episode_time_s=25 \
    --dataset.reset_time_s=10 \
    --dataset.streaming_encoding=true \
    --dataset.encoder_threads=2

Les valeurs par défaut ci-dessous proviennent de src/lerobot/configs/dataset.py sur la branche main, pas d'un tutoriel. Plusieurs ne sont pas ce que les gens supposent.

Contrôle clavier pendant une session

• Flèche droite ou n : terminer l'épisode ou la phase de réinitialisation plus tôt. C'est la touche que vous utilisez le plus, car une prise propre nécessite rarement 25 secondes.
• Flèche gauche ou r : annuler l'épisode et le refaire. Une mauvaise prise ne coûte rien maintenant et beaucoup plus tard.
• Échap ou q : arrêter la session, terminer l'encodage, télécharger.
• Ces commandes fonctionnent sur X11, Wayland et SSH sans interface graphique : sans backend de touches global, lerobot-record lit les mêmes touches depuis le terminal de contrôle. Les lettres survivent aux liaisons SSH lentes, où les séquences de flèches se divisent.
• La téléopération au clavier est différente et nécessite un backend global : X11, Windows ou macOS avec Accessibilité.

Combien d'épisodes, et à quoi ressemble un bon épisode

Le guide d'enregistrement suggère au moins 50 épisodes pour une première tâche, soit environ 10 par emplacement d'objet. Les pages de politiques listent un minimum par modèle, en dessous duquel une exécution ne vaut pas le temps GPU.

La meilleure question est de savoir combien de quoi. Data Scaling Laws in Imitation Learning for Robotic Manipulation (Lin et al., 2024) ont collecté plus de 40 000 démonstrations et effectué plus de 15 000 déploiements réels. La généralisation a suivi une relation approximativement en loi de puissance avec le nombre d' environnements et d'objets, et au-delà d'un seuil par environnement ou objet, les démonstrations supplémentaires ont eu un effet minimal. Sur un banc d'essai : déplacez l'objet, changez l'éclairage, échangez le cube, plutôt que de répéter une seule prise.

Un bon épisode est ennuyeux : pose initiale reproductible, une seule chose faite, terminée une fois l'objet dans la poubelle, chaîne de tâche de 25 à 50 caractères comme recommandé par la liste de contrôle. Prendre le cube rouge et le déposer dans la boîte est une chaîne de tâche ; task1 est l'anti-modèle que la liste de contrôle nomme explicitement. Les annotations vagues figurent en tête de sa liste de problèmes, et elles sont les plus importantes pour modèles vision-langage-action, où la chaîne est une entrée de modèle, pas un nom de fichier.

Défauts qui ruinent discrètement un jeu de données

Aucun ne lève d'exception. Tous survivent à l'entraînement, se manifestant par une courbe de perte qui semble correcte et un robot qui ne fait rien. Vérifiez pendant que la scène est configurée.

Une mise en garde : le tableau du guide de streaming-encoding liste la valeur par défaut comme True, tandis que la dataclass sur main indique streaming_encoding: bool = False. La documentation et le code ne concordent pas, il est donc préférable de le définir explicitement ; lerobot enregistre une suggestion le recommandant chaque fois qu'il démarre avec le flag désactivé.

Vérifier le jeu de données avant de louer un GPU

Le test d'acceptation de la documentation : comparer la durée de la vidéo à la durée de l'épisode rapportée par la CLI, et confirmer que le nombre de lignes est égal au nombre d'images par seconde (fps) multiplié par la durée. Par épisode, pas sur le total.

from lerobot.datasets import LeRobotDataset

ds = LeRobotDataset("your-user/so100_pick_cube_20260823_141530")
print("fps:", ds.fps, "frames:", ds.num_frames)

# In v3.0 the per-episode records live in meta/episodes/ as chunked parquet:
# lengths, tasks and offsets into the shared parquet and mp4 shards.
# They load through the datasets stack, so this is a datasets.Dataset --
# use .column_names and integer indexing, not pandas .columns / .head().
eps = ds.meta.episodes
print(eps.column_names)
print(eps[0])

# Global feature statistics, including per-joint min and max.
# A joint whose min equals its max never moved. A joint sitting at a
# hard limit for most of the run is the one that will stall the policy.
print(ds.meta.stats["observation.state"])

Ensuite, examinez-le. lerobot-dataset-viz rejoue un épisode image par image avec les tracés des articulations à côté des vues de la caméra, dans Rerun ou Foxglove. Les caméras inversées et les images figées apparaissent en dix secondes. Les gens sautent cette étape.

# Replay one episode with camera views and joint traces
lerobot-dataset-viz \
    --repo-id your-user/so100_pick_cube_20260823_141530 \
    --episode-index 0

# Foxglove instead, for a seekable, scrubbable timeline
lerobot-dataset-viz \
    --repo-id your-user/so100_pick_cube_20260823_141530 \
    --episode-index 0 \
    --display-mode foxglove

# Drop the episodes that did not survive review
lerobot-edit-dataset \
    --repo_id your-user/so100_pick_cube_20260823_141530 \
    --new_repo_id your-user/so100_pick_cube_clean \
    --operation.type delete_episodes \
    --operation.episode_indices "[3, 17, 41]"

v2.1 ou v3.0 : décidez avant d'enregistrer

La v2.1 écrivait un fichier parquet et un fichier MP4 par épisode. La v3.0 concatène de nombreux épisodes en des fragments partagés et reconstruit les limites à partir des métadonnées, de sorte que info.json contient des modèles de chemin comme data/chunk-{chunk_index:03d}/file-{file_index:03d}.parquet au lieu d'un numéro d'épisode. La justification en amont est un nombre réduit de fichiers plus volumineux : une initialisation plus rapide et moins de pression sur le système de fichiers à grande échelle.

# Upgrade an older v2.1 dataset to v3.0
python -m lerobot.scripts.convert_dataset_v21_to_v30 \
    --repo-id=your-user/so100_pick_cube

# By default it pushes the converted dataset back to the hub and tags it v3.0.
# To convert a local copy and keep it off the hub:
python -m lerobot.scripts.convert_dataset_v21_to_v30 \
    --repo-id=your-user/so100_pick_cube \
    --root=/path/to/dataset/directory \
    --push-to-hub=false

Deux chemins vers le même jeu de données

Du jeu de données à la politique

Cinquante épisodes propres alimentent chaque exécuté ici. s'entraîne à partir de zéro sur votre tâche seule, environ 80 millions de paramètres à environ 20 ms par étape d'action, le seul des cinq à l'aise avec les mouvements rapides. est d'environ 450 millions de paramètres sur une carte de 24 Go. est un modèle de fondation d'environ 3 milliards de paramètres où touche environ 40 millions de paramètres, nécessite un A100 ou un H100, et demande ce jeu de données v2.1.

Ensuite, le guide pour votre combinaison : , ou ; pour une première exécution, est plus court. Lorsque la politique fonctionne sur le banc mais s'effondre dès que vous déplacez la table, c'est un problème de données : et approfondissent la question de la diversité.