Microduck Robot●microduck-robot.com

Microduck Robot / LEROBOT

LeRobot SO-101 tutorial: build, calibrate, record, train and run

This guide follows the official Hugging Face LeRobot documentation for the SO-101 leader and follower arms, adds the checks builders most often miss, and ends with the LeKiwi mobile base and a troubleshooting checklist. The commands match LeRobot v0.7.0 (released 5 November 2026). LeRobot changes quickly, so compare the flags with the documentation for the version you install.

What you will build and what you need

LeRobot is Hugging Face's open-source robotics library. One set of commands moves a robot, records demonstrations, trains a policy and runs it. The SO-101 is its flagship arm: you move a leader arm by hand, a follower arm copies it, and the recorded motion and camera images teach a neural network to repeat the task by itself.

The work has seven stages: source the parts and install the software, give every motor an ID, assemble both arms, calibrate, teleoperate with cameras, record a dataset, then train and run a policy. The last build section adds the LeKiwi mobile base, followed by a troubleshooting checklist.

Swipe sideways to see the whole figure.

The seven stages of the build, with the command that does each oneA numbered list of seven stages from top to bottom. 1 Parts and software: pip install lerobot. 2 Ports and motor IDs: lerobot-find-port and lerobot-setup-motors. 3 Assemble both arms, by hand. 4 Calibrate: lerobot-calibrate. 5 Teleoperate with cameras: lerobot-find-cameras and lerobot-teleoperate. 6 Record a dataset: lerobot-record, and lerobot-replay to check it. 7 Train and run a policy: lerobot-train, then lerobot-rollout.1Parts and softwareGet the parts, install LeRobotpip install lerobot2Ports and motor IDsOne servo at a timelerobot-find-portlerobot-setup-motors3Assemble both armsJoint by joint, both armsNo command: build it by hand4CalibrateSame numbers on both armslerobot-calibrate5Teleoperate with camerasThe leader moves the followerlerobot-find-cameraslerobot-teleoperate6Record a datasetJoint positions and videolerobot-recordlerobot-replay7Train and run a policyACT policy on the follower armlerobot-trainlerobot-rollout
The seven stages of the build, with the command that does each one

You need two arms (parts in the next section), a USB bus-servo control board and a power supply for each arm, a computer with Python 3.12 or newer, two USB cameras (the commands in this guide use two), a free Hugging Face account for datasets and checkpoints, and a GPU for training. A laptop-class GPU is enough for the ACT policy used here, and a rented GPU works too.

We compiled this guide from the official documentation and community build reports, and we did not bench-test every step on every hardware revision. Older tutorials that call control_robot.py do not apply to 0.7.0, which uses the lerobot-* commands.

Parts, printing and power

The SO-101 project publishes the bill of materials and the print files, and the Hugging Face SO-101 page links to both. A complete leader and follower pair needs 12 Feetech STS3215 servos, two control boards, two power supplies, two USB-C cables, table clamps. The assembly uses M2×6 and M3×6 screws; the project's bill of materials does not list them, so check what ships with your servos or kit. Printed parts and complete kits are also sold.

The follower uses six servos with a 1/345 gear ratio. The leader uses three different ratios, so it can hold its own weight and still move with little force.

Match the power supply to the servos. The 7.4 V STS3215 has a stall torque of 16.5 kg·cm at 6 V (slightly less on a 5 V supply) and is normally run from a 5 V supply. The follower can use 12 V servos (30 kg·cm) for more power, but then it needs a 12 V supply rated 5 A or more; the leader always uses 7.4 V servos. Never connect the 12 V supply to a board that has 7.4 V servos on it; mark each supply with its voltage and the arm it belongs to.

Swipe sideways to see the whole figure.

Power and USB for the leader and the follower armA computer at the top is connected by a USB-C cable to the control board of the leader arm and to the control board of the follower arm. Each control board has its own power supply. Six servos are chained from each board, starting with servo 1, using 3-pin cables. The leader always uses 7.4 V servos on a 5 V supply. The follower uses 7.4 V servos on a 5 V supply, or 12 V servos on a 12 V supply rated 5 A or more. On a Waveshare board both jumpers are set to channel B, the USB channel.ComputerLeader arm5 V supplyControl boardWaveshare board:both jumpers onchannel B (USB).1234566 servos, 7.4 V, onthe 5 V supply.Follower armSupply: 5 V, or12 V 5 A+Control boardWaveshare board:both jumpers onchannel B (USB).1234567.4 V servos on 5V, or 12 V servoson 12 V.PowerUSB-C3-pin servo cableNever connect the 12 V supply to a board with 7.4 V servos.
Power and USB for the leader and the follower arm

Print in PLA+ with a 0.4 mm nozzle at 0.2 mm layers (or a 0.6 mm nozzle at 0.4 mm layers) and 15% infill. Each arm's parts come as a single file oriented to need few supports; keep supports out of horizontal screw holes. Print the Gauge Zero and Gauge Tight test pieces first and check them against a servo; if Gauge Zero does not fit as shown in the project's video, adjust your printer settings and print it again before printing the arms.

Have Phillips #0 and #1 screwdrivers ready, and clamp each base to the table before you test. The parts we supply for this build are linked below.

Scroll sideways to compare all columns.

JointMotor IDLeader gear ratioFollower gear ratio
Shoulder pan11/1911/345
Shoulder lift21/3451/345
Elbow flex31/1911/345
Wrist flex41/1471/345
Wrist roll51/1471/345
Gripper61/1471/345

Install LeRobot and motor support

LeRobot 0.7.0 needs Python 3.12 or newer. Create an isolated environment with conda (from miniforge) or uv, and activate it in every new terminal. ffmpeg is needed for video on most platforms (on macOS Intel and 32-bit ARM Linux LeRobot falls back to PyAV and you can skip it); the conda package works with every PyTorch version.

Create the environment
conda create -y -n lerobot python=3.12
conda activate lerobot
conda install ffmpeg -c conda-forge

Install LeRobot from PyPI with the extras you need. core_scripts adds what recording, replay and calibration use, feetech adds support for the STS3215 servos, and training adds the training tools.

Install LeRobot with extras
pip install 'lerobot[core_scripts,feetech]'
pip install 'lerobot[training]'

Platform notes: on Apple silicon PyTorch needs macOS 14 or newer, and macOS 15 or newer for GPU (MPS) acceleration. To use an NVIDIA GPU on Linux, the default PyTorch builds need a driver 580.65 or newer; with an older driver, install a matching CUDA build of PyTorch first and take torchcodec from the CPU index (see the Hugging Face installation page). Inside WSL also install evdev (conda install evdev -c conda-forge, or with uv sudo apt install libevdev-dev and then uv pip install evdev). With PyTorch 2.10 or newer you can use the system ffmpeg instead of the conda one.

Find the ports and set the motor IDs

New STS3215 servos usually ship with ID 1, and the controller and every servo must share one baud rate. LeRobot writes both into each servo's memory once, so do this before assembly and connect one servo at a time. Servos reused from another robot probably need it too.

Swipe sideways to see the whole figure.

The six joints of an SO-101 arm and the motor ID of eachSide view of a robot arm. Joint 1, shoulder pan, turns the whole arm about a vertical axis at the base. Joints 2, 3 and 4, shoulder lift, elbow flex and wrist flex, bend the arm in one plane. Joint 5, wrist roll, turns the gripper about the axis of the forearm. Joint 6 is the gripper. The motor ID of each joint is its number. Link lengths and axes follow the official SO-101 model.1234561Shoulder pan2Shoulder lift3Elbow flex4Wrist flex5Wrist roll6GripperMotor ID = joint number.Setup order: 6 down to 1.Follower arm, side view, proportions from the officialSO-101 model.On the leader, joint 6 is the trigger.
The six joints of an SO-101 arm and the motor ID of each

Connect a control board to the computer by USB, power it, and run the port finder. Unplug only that board's USB cable when asked and press Enter; the script prints the port, such as /dev/ttyACM0 on Linux, /dev/tty.usbmodem… on macOS or COM3 on Windows. Plug the cable back in, then repeat for the second board. On Linux you may have to allow access with sudo chmod 666 on each port (for example /dev/ttyACM0 and /dev/ttyACM1).

Find the port of a control board
lerobot-find-port

Run the setup script for the follower, then for the leader, each with its own port. The script names one motor at a time, so read the steps below before you run it.

Set the follower motor IDs
lerobot-setup-motors \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0

The leader uses the teleoperator options instead of the robot options. At each prompt take the motor with the gear ratio listed for that joint in the table in the parts section (on the leader 1/191 for shoulder pan and elbow flex, 1/345 for shoulder lift and 1/147 for wrist flex, wrist roll and gripper), and mark each motor with its ID as soon as the script reports it set.

Set the leader motor IDs
lerobot-setup-motors \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1
  1. The script names one motor at a time, starting with the gripper (ID 6) and ending with the shoulder pan (ID 1). Connect only that motor to the control board; it must not be chained to any other motor.
  2. Press Enter. When the script reports that the ID is set, unplug that motor's cable from the board, connect the next motor it names and press Enter again.
  3. Check the power, USB and 3-pin cables before each Enter. If the script reports an error, check these cables first, and on a Waveshare board both jumpers must sit on channel B (USB).
  4. When the script finishes, chain the motors together in order and connect the shoulder pan motor (ID 1) to the control board.

    Swipe sideways to see the whole figure.

    Setting motor IDs one servo at a time, then chaining the servos in orderTop panel: while setting IDs, only one servo is connected to the control board. The setup script names the servos in the order 6, 5, 4, 3, 2, 1. Bottom panel: after setup, the servos are chained in order. Servo 1 connects to the control board and each next servo connects to the previous one, up to servo 6.While setting IDsOnly the servo being set is connected. Unplug it, then connect the next one the scriptnames.Control board?Order the script asks for654321After setupChain the servos in order. Servo 1 connects to the control board.Control board123456
    Setting motor IDs one servo at a time, then chaining the servos in order

Assemble the leader and follower arms

Both arms share most printed parts and are built in the same order (the wrist roll part differs, and the leader has a handle and trigger where the follower has a moving jaw): base and shoulder, upper arm, forearm, wrist, then the gripper on the follower or the handle and trigger on the leader. Hugging Face publishes a short video for each joint on its SO-101 page; follow it next to these notes. Remove all support material from the printed parts first, and plug a 3-pin cable into every servo before you close it in.

  1. Joint 1, shoulder pan: fit both horns on the motor and secure the top one with an M3×6 screw (the bottom horn needs none). Set the motor into the base with four M2×6 screws, slide on the first motor holder with two M2×6, attach the shoulder with four M3×6 on top and four below, and add the shoulder motor holder.
  2. Joint 2, shoulder lift: fit both horns and secure the top one with an M3×6 screw (the bottom horn needs none), slide the motor in from the top, fasten it with four M2×6, then attach the upper arm with four M3×6 on each side.
  3. Joint 3, elbow: fit both horns and secure the top one with an M3×6 screw (the bottom horn needs none), insert motor 3 with four M2×6, and connect the forearm to it with four M3×6 on each side.
  4. Joint 4, wrist flex: fit both horns and secure the top one with an M3×6 screw (the bottom horn needs none), slide over motor holder 4, slide in motor 4 and fasten it with four M2×6.
  5. Joint 5, wrist roll: put motor 5 in the wrist holder with two M2×6 at the front, fit a single horn with an M3×6 screw, and secure the wrist to motor 4 with M3×6 screws as shown in the official Joint 5 video (the written guide says four on both sides).
  6. Follower gripper: attach the gripper to the wrist motor's horn with four M3×6, fit the gripper motor with two M2×6 on each side, fit both horns and secure the top one with an M3×6 screw (the bottom horn needs none), and secure the claw with M3×6 screws as shown in the official gripper video (the written guide says four on both sides).
  7. Leader handle: mount the leader holder on the wrist with four M3×6, fasten the handle to it with one M2×6, fit motor 6, the trigger motor (the official guide calls it the gripper motor), with two M2×6 on each side and a horn with an M3×6 screw, then attach the trigger with four M3×6.
  8. Before you power anything, turn each joint slowly by hand through its range and never force it past a stop; it should move without scraping. Mark each motor with its ID before you close it in, and clamp both bases to the table.

Calibrate both arms

Calibration records each joint's range so that the leader and the follower report the same numbers in the same physical pose. It also lets a policy trained on one robot run on another. Do it once for each arm, and again after a hardware change or when LeRobot reports a missing calibration. Recordings and policies made before a recalibration used the old calibration.

Calibrate the follower first. The script asks you to move every joint to the middle of its range and press Enter, then to move each joint through its full range of motion and press Enter again when every joint has been through it. Give each arm a unique id; that name labels its calibration file. The commands in this guide use /dev/ttyACM0 for the follower and /dev/ttyACM1 for the leader as examples: replace them with the ports you found, and do not swap the two arms.

Swipe sideways to see the whole figure.

Calibration: the middle of every range first, then each joint's full rangeTwo panels side by side. Step 1: each of the six joints is held at the middle of its range, shown as a dot at the centre of a bar, then you press Enter. Step 2: each of the six joints is moved through its whole range, shown as a double arrow from the minimum to the maximum end of the bar. Below: the same physical pose gives the same position values on the leader and the follower.Step 1: the middleMove every joint to the middle of itsrange, then press Enter.123456middleStep 2: the full rangeMove each joint through its whole range,then press Enter again.123456minmaxSame physical pose, same position values on the leader and the follower.
Calibration: the middle of every range first, then each joint's full range
Calibrate the follower
lerobot-calibrate \
    --robot.type=so101_follower \
    --robot.port=/dev/ttyACM0 \
    --robot.id=my_follower_arm

Then calibrate the leader with the same movements.

Calibrate the leader
lerobot-calibrate \
    --teleop.type=so101_leader \
    --teleop.port=/dev/ttyACM1 \
    --teleop.id=my_leader_arm

Use the same id in every later command; that is how LeRobot finds the calibration file, which is stored under ~/.cache/huggingface/lerobot/calibration by default. Back it up and keep it out of temporary folders: one community builder lost the calibration files in a power cycle and redid the calibration without putting every joint at the middle of its range, which gave some joints wrong homing offsets.

Teleoperate the follower with the leader

Teleoperation connects the two arms: the follower copies the leader. If a calibration is missing, the command starts the calibration procedure first. Start with small, slow movements, keep clear of the follower's joints, and keep the power supply within reach.

Teleoperate
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

Add cameras next. List them with the camera finder, which prints each camera's identifier and saves a test frame from each to outputs/captured_images; open the frames to see which index is which camera. The indices can change after a reboot or when you replug a camera.

List the cameras
lerobot-find-cameras opencv

Teleoperate again with the cameras attached and a live view in Rerun. The camera names you choose here, such as top and wrist, become the dataset keys later, so use the same names and settings from now on.

Teleoperate with cameras and a live view
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

Place the cameras so the policy can learn

A policy sees only the camera images and the joint positions, so a good camera setup matters more than high resolution. 640×480 at 30 fps is enough for most tasks and keeps recording and training fast.

Swipe sideways to see the whole figure.

Camera placement: fixed views of the task, even light, and the names that become dataset keysSide view of a workspace. The follower arm reaches for an object next to a target container. A top camera on a stand above the table looks down at the whole workspace, shown as a shaded field of view covering the arm, the object and the target. A wrist camera on the gripper looks along the jaws. A soft light panel at the upper left lights the scene evenly. The cameras stay fixed between recording and running. The camera names become dataset keys, observation.images.top and observation.images.wrist.Diffuse lightObjectTargettop camerawrist cameraFixed rigidly: do not move the cameras between recording and running.Camera names are dataset keys:observation.images.topobservation.images.wrist
Camera placement: fixed views of the task, even light, and the names that become dataset keys
  1. Light the scene evenly with diffuse light. Avoid direct sunlight, strong reflections and moving shadows: lighting that differs between recording and running can make a policy fail.
  2. Fix the cameras rigidly and never move them between recording and running. One community builder's first policy only pecked at the table, and one of several causes was that the cameras had moved slightly between recording and testing.
  3. Frame the task: the object, the gripper and the target should be visible in at least one camera. A good test is whether you could do the task yourself from the camera images alone. The same community builder demonstrated while watching only the camera feed; if you try that, keep the power supply within reach.
  4. The same builder replaced a side camera, whose view of the gripper tips was poor during grasps, with an overhead camera next to the front camera, which reduced occlusion; a wrist camera appears in that post only as a next step. If you record through the day, fix the exposure and white balance in your webcam's own settings; LeRobot's RealSense camera configuration also accepts exposure, gain and white_balance.
  5. With two identical webcams on Ubuntu, the USB addresses can swap and a recording may stop with a camera error. The same builder fixed this with udev rules that identify each camera by its physical USB port, so keep each camera in the same port; otherwise run the camera finder again after every reboot.

Record a dataset

Datasets use the LeRobotDataset format and are uploaded to the Hugging Face Hub. Create a free account, make a token with write access in your Hugging Face settings, then log in and keep your user name in a variable. Set HUGGINGFACE_TOKEN to your token first, or run hf auth login on its own and paste the token when asked.

Log in to 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

Record five episodes first to test the setup. Use the same robot id, ports and camera settings as in teleoperation, and describe the task in plain words.

Record a dataset
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 appends the date and time to the dataset name, so ${HF_USER}/record-test is saved as ${HF_USER}/record-test_YYYYMMDD_HHMMSS. Use that full name in later commands; find it with ls ~/.cache/huggingface/lerobot/${HF_USER}, or add --dataset.no_stamp=true to keep the name you passed. The dataset is stored in ~/.cache/huggingface/lerobot and pushed to the Hub when recording ends. A dataset pushed from a personal account can be public, so check its visibility on the Hub and add --dataset.private=true if it should be private; add --dataset.push_to_hub=False to keep it local. To continue a stopped session, rerun the command with --resume=true, the full timestamped --dataset.repo_id, --dataset.root set to the dataset's local folder, and --dataset.num_episodes set to the number of additional episodes, not the total.

Episode time and reset time default to 60 seconds (--dataset.episode_time_s and --dataset.reset_time_s), and the default number of episodes is 50. The keyboard controls the flow while you record, as the table below shows.

For a first useful dataset choose a simple task, such as picking an object from several positions and placing it in a bin. Record at least 50 episodes, about 10 per position, keep the cameras and your grasping style consistent, and add variety slowly. Re-record failed episodes. Fifty episodes at fixed positions are a starting point; expect a policy that works mainly near the positions you recorded. LeRobot prints a cadence line after each kept episode and a summary when recording ends. If the rate is well below the 30 Hz target, the dataset still claims 30 Hz, so the motion looks faster than it was. Find what slows the loop (in the documentation's example it was the camera reads) and re-record the affected episodes instead of training on them.

Check the data before training. Open the dataset in the LeRobot dataset visualizer on Hugging Face, and replay an episode on the robot to test that the motion repeats. Replay moves the arm without your input, so clear the workspace, start the arm near the episode's first pose and keep the power supply within reach.

Replay an episode
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

Scroll sideways to compare all columns.

KeyAction
Right arrow or nFinish the episode or the reset period early and move on
Left arrow or rDiscard the current episode and record it again
Esc or qStop the session: the episode in progress is saved, then the videos are encoded and the dataset is uploaded (press Left arrow or r first to discard that episode)

Train an ACT policy

ACT (Action Chunking Transformer) is the policy used in the LeRobot tutorial: it adapts to the motors and cameras stored in your dataset. The hardware guide puts the light policies (ACT, VQ-BeT, TD-MPC) at about 2 to 6 GB of GPU memory at batch size 8, as an indicative figure. Train on an NVIDIA GPU (cuda); on Apple silicon change the command to --policy.device=mps, which needs macOS 15 or newer (on macOS 14 LeRobot falls back to the CPU, which is not suitable for training).

Start training with the full dataset name.

Train an ACT policy
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

Without --steps training runs 100,000 steps, usually more than a small dataset needs: imitation learning typically converges within 5 to 10 passes over the data. A 50-episode dataset of 30-second episodes at 30 fps holds about 45,000 frames, which at batch size 8 is about 5,600 steps per pass, so 5 to 10 passes is roughly 28,000 to 56,000 steps. The command above uses --steps=20000, about three and a half passes, as a short first run; raise it if the policy is undertrained, and if you cut it much lower also set --policy.scheduler_decay_steps close to --steps. The hardware guide estimates roughly 30 to 60 minutes for five passes of ACT at batch size 8 on an RTX 3090 or 4090 and 1 to 2 hours on an L4 or A10G, and 6 to 14 hours at batch size 4 on an M1, M2 or M3 Max; it calls these figures indicative and says real runs can differ by about 50%.

Without a suitable GPU, train in Google Colab with the ACT notebook, or run hf auth login and add a Hugging Face Jobs flavor such as --job.target=a10g-small to the same command. Because that command enables Trackio, a job also needs --trackio.space_id=<user>/<space> (add --trackio.private=true to keep the Space private), or remove --trackio.enable=true. Jobs are billed per second and capped at 48 hours unless you set --job.timeout, upload a local-only dataset to a private repository for you, and push the trained model at the end; hf jobs hardware lists the flavors.

Checkpoints are written to outputs/train/act_so101_test/checkpoints. Resume an interrupted run from the last checkpoint. Because the training command sets --policy.repo_id=${HF_USER}/my_policy, the finished model is pushed to that repository at the end (--policy.push_to_hub=false turns this off, --policy.private=true makes it private); to upload a checkpoint yourself, use the same repository name so that --policy.path=${HF_USER}/my_policy finds it.

Resume training and upload the model
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

LeRobot's training script does not evaluate real-robot policies, so keep some episodes out of training, including start positions you did not record, and test the policy on them. A community builder trained on 50 episodes (10 in each of five start-position regions) and saw 60% success on new episodes from those regions but only 10% on episodes from a region left out of training. After raising the data to 25 episodes per region, the same builder reached 90% and 75%. These are small samples, scored with the builder's own scripts.

Run the policy on the follower

Deploy a trained policy with lerobot-rollout. Use the same robot id, camera names, camera settings and task text that you used when recording, and run the port finder again if you rebooted or replugged since. --duration is in seconds; without it the policy runs until you stop it.

Run the policy on the 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

The strategy sets what happens during the run, as the table below shows. A strategy that records a dataset needs a repository name that starts with rollout_ after your user name, for example --dataset.repo_id=${HF_USER}/rollout_so101_test; a timestamp is added to it. Recording strategies such as sentry take --dataset.single_task instead of --task; see the LeRobot documentation for each strategy's flags.

On LeRobot v0.5.x and earlier there is no lerobot-rollout; use lerobot-record as described in the v0.5.1 documentation. The training flags in this guide target the current release.

Run the first time with a short duration (for example 15 seconds), a clear workspace and a plan for how you will stop the arm; cutting the power releases the motors, so an arm that is not resting on something can drop. If the arm pecks at the table or overreaches, check the setup before blaming the model: the same calibration id, cameras in the same place with the same names and resolution, the same lighting, and objects in positions the dataset covers.

Scroll sideways to compare all columns.

StrategyWhat it does
baseRuns autonomously without recording, for quick tests
sentryRecords continuously and uploads automatically
highlightKeeps a ring buffer and saves it when you press a key
daggerHuman-in-the-loop data collection
episodicRecords episode by episode with reset phases in between

Extend the build with LeKiwi

LeKiwi is a three-wheeled mobile base that carries an SO-101 follower arm. A Raspberry Pi, or another 5 V computer with enough USB ports for the cameras and the motor control board (the LeKiwi page says two or more), runs the robot, and you drive it from a laptop with a leader arm and the keyboard. In the wired version everything runs on the laptop and the Pi steps can be skipped. The parts list, print files and base assembly instructions come from the LeKiwi project linked on the Hugging Face LeKiwi page.

Swipe sideways to see the whole figure.

LeKiwi: the laptop drives the robot over the network, the Raspberry Pi drives the motorsOn the left, a laptop with the leader arm, a keyboard and the script teleoperate.py. On the right, the LeKiwi robot: a Raspberry Pi running lekiwi_host, connected by USB to a motor control board and to the cameras. The control board drives the arm motors, IDs 6 to 1, and the wheel motors, IDs 9, 8 and 7. The laptop and the Pi talk over the same network using ZeroMQ, on ports 5555 for commands and 5556 for observations. In the wired version everything runs on the laptop.LaptopLeader arm (USB)Keyboardteleoperate.pyRun the example script withthe Pi's address as remote_ip.SamenetworkZeroMQ5555, 5556LeKiwi robotRaspberry Pi(host)lekiwi_hostControl boardCamerasArm motorsID 6 – 1Wheel motorsID 9, 8, 7Wired version: no Pi, everything runs on the laptop.
LeKiwi: the laptop drives the robot over the network, the Raspberry Pi drives the motors

Driving the base from the keyboard needs a global key backend, so it works on X11, on a Windows desktop, or on macOS with Input Monitoring granted to your terminal, but not on Wayland or headless machines.

  1. Build two SO-101 arms with the sections above: one to mount on the base and one as the leader. Then assemble the base.
  2. Install Raspberry Pi OS, enable SSH, and check that you can log in with ssh <user>@<pi-ip>. Install LeRobot on the Pi and on your laptop as in the install section, then add the LeKiwi extra, which brings the servo driver and ZeroMQ.
    Install the LeKiwi extra
    pip install 'lerobot[lekiwi]'
  3. Set up all motors with one command. It gives the arm motors IDs 6 to 1 and the wheels 9, 8 and 7; the wheel IDs must match the mounting positions shown in the LeKiwi documentation. LeKiwi uses a single control board.
    Set the LeKiwi motor IDs
    lerobot-setup-motors \
        --robot.type=lekiwi \
        --robot.port=/dev/ttyACM0
  4. Calibrate the follower arm on the Pi, and the leader arm on the laptop. The LeKiwi page shows --teleop.type=so100_leader for the leader; check which leader class examples/lekiwi/teleoperate.py creates, and calibrate with the same type and --teleop.id. The wheel motors need no calibration.
    Calibrate the LeKiwi arm
    lerobot-calibrate \
        --robot.type=lekiwi \
        --robot.id=my_awesome_kiwi
  5. On the Pi, activate the LeRobot environment and start the host. It stops after 30 seconds unless you raise --host.connection_time_s (for example to 600), which you need for longer sessions such as recording.
    Start the LeKiwi host on the Pi
    python -m lerobot.robots.lekiwi.lekiwi_host \
        --robot.id=my_awesome_kiwi \
        --host.connection_time_s=600
  6. On the laptop, edit examples/lekiwi/teleoperate.py in the LeRobot source repository: set remote_ip to the Pi's address and the leader arm's port and id to your own values, then run it. In record.py also set HF_REPO_ID and TASK_DESCRIPTION; in replay.py set remote_ip, port, the dataset id and the episode index. To run a trained policy the LeKiwi page uses examples/lekiwi/evaluate.py (set remote_ip, port and the model); the lerobot-rollout command in the previous section is written for a stand-alone SO-101. Speed has three modes, changed with R and F: fast 0.3 m/s and 90°/s, medium 0.2 m/s and 60°/s, slow 0.1 m/s and 30°/s.

Scroll sideways to compare all columns.

KeyAction
WMove forward
AMove left
SMove backward
DMove right
ZTurn left
XTurn right
RIncrease speed
FDecrease speed

Troubleshooting checklist

Many problems come from power, cables, ports, or a setup that changed between recording and running. Work through this table before you change any code.

For questions about LeRobot itself, the Hugging Face documentation links its Discord community. For parts from our shop, use the WhatsApp button or the support form.

Scroll sideways to compare all columns.

SymptomWhat to check
A serial port is not found or access is deniedRun the port finder again with the board powered and the USB cable in. On Linux allow access with sudo chmod 666 on the port. Ports can change after a reboot or replug, so run the port finder again.
The ID script cannot find the motorCheck the power supply, the USB cable and the 3-pin cable. Only the motor being set may be connected. On a Waveshare board both jumpers must be on channel B (USB).
Reused servos are not found or do not respondTheir IDs and baud rate likely do not match the new robot, as the SO-101 guide notes. Run the motor setup again, one servo at a time.
Calibration fails, or the arm moves wrongly after calibratingCalibrate again: first put every joint in the middle of its range and press Enter, then move each joint through its full range. A community builder who did not centre every joint ended up with wrong homing offsets. Use the same robot id afterwards.
A camera disconnects or its index changesRun the camera finder again after every reboot or replug. Two identical webcams can swap USB addresses on Linux; one community builder fixed this with udev rules keyed on the physical USB port.
The recording keys do nothingStart the command from an interactive terminal and keep it focused; the letter keys n, r and q work as well as the arrow and Esc keys. Only driving a robot with the keyboard, as on LeKiwi, needs X11, a Windows desktop or macOS permission.
Training cannot find the datasetUse the full dataset name, including its date and time suffix.
The recorded cadence is far below 30 HzRead the cadence lines that the recording prints. If reading the cameras dominates, lower the resolution or use fewer cameras, then record again: a policy expects the same camera setup at run time, and episodes recorded well below 30 Hz are stored as if they ran at 30 Hz.
The policy pecks at the table or overreachesCompare the calibration id, camera positions, names and lighting with the recording session, and check that objects start where the dataset has examples.
LeKiwi does not connect, or the host stops after 30 secondsFind the Pi's address with hostname -I, ping it from the laptop and test ssh <user>@<pi-ip>; enable SSH in sudo raspi-config if needed. The host stops after 30 seconds unless you set --host.connection_time_s.

Project sources

Contact us