Feetech STS3215 Calibration: What LeRobot Writes to the Servo

Calibration on an SO-100 is not a vague tuning step. On a Feetech STS3215 it is three integers per joint, written into the servo's non-volatile memory and mirrored into a JSON file on your laptop. Get them wrong and every joint angle you record is wrong the same systematic way, so a policy trained on it learns a mapping that only holds for the arm as it was miscalibrated that day.

This page covers what those three numbers are, which registers they land in, where they come from in the source, what breaks downstream, and the checks that catch a bad calibration in two minutes. Everything here is read out of LeRobot on the main branch (0.6.2 in development; last release v0.6.1, 2026-08-03) and the Feetech STS3215 product specification, edition A/0, 2020-04-10.

What an STS3215 actually reports

The STS3215 is a serial bus servo with an absolute 12-bit magnetic angle sensor. It does not report degrees. It reports a count, and the datasheet fixes the mapping: 360 degrees of output rotation over 0 to 4096, with 180 degrees at count 2048. Everything a LeRobot dataset contains about arm state starts as one of those integers, on every arm this platform supports except Koch v1.1, which uses Dynamixel servos.

The three numbers, and the registers they land in

LeRobot models a calibrated motor with a five-field dataclass called MotorCalibration: id, drive_mode, homing_offset, range_min, range_max. Only three of those reach the hardware. FeetechMotorsBus.write_calibration writes Homing_Offset (on protocol 0, which is what the SO arms use), then Min_Position_Limit, then Max_Position_Limit, and nothing else. drive_mode is always 0 on SO arms, and id is bookkeeping.

These registers live in EEPROM, so they survive a power cycle, which is why calibration happens once per physical arm. It is also why a used servo arrives carrying someone else's numbers, and why LeRobot compares file against motors on every connect instead of trusting either.

{
  "shoulder_pan":  { "id": 1, "drive_mode": 0, "homing_offset": 14,    "range_min": 1015, "range_max": 3128 },
  "shoulder_lift": { "id": 2, "drive_mode": 0, "homing_offset": -1732, "range_min": 812,  "range_max": 3260 },
  "elbow_flex":    { "id": 3, "drive_mode": 0, "homing_offset": 907,   "range_min": 985,  "range_max": 3061 },
  "wrist_flex":    { "id": 4, "drive_mode": 0, "homing_offset": -461,  "range_min": 900,  "range_max": 3190 },
  "wrist_roll":    { "id": 5, "drive_mode": 0, "homing_offset": 122,   "range_min": 0,    "range_max": 4095 },
  "gripper":       { "id": 6, "drive_mode": 0, "homing_offset": -1024, "range_min": 1975, "range_max": 3050 }
}

Where the numbers come from: the calibration run

The calibration routine for the SO follower and the SO leader is the same code, short enough to read in one sitting. It disables torque, forces every motor into position mode, asks for one pose, then asks for a sweep. Below is the whole sequence including the two prerequisites people skip, cross-checked against the upstream LeRobot SO-100 guide.

1. 1
   Install LeRobot with the Feetech extra

   The Feetech SDK is not in the base install. The extra pulls in feetech-servo-sdk, pyserial and deepdiff.

   bash

   git clone https://github.com/huggingface/lerobot.git
   cd lerobot
   pip install -e ".[feetech]"

2. 2
   Find the serial port

   Plug the arm in, unplug when prompted, and it names the device node. Do leader and follower separately.

   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/ttyACM0'

3. 3
   Set motor IDs and baud rate, once per arm

   New servos all ship with ID 1. This walks the chain from gripper down to shoulder_pan, writing IDs 6 to 1 and the default baud rate of 1000000 into EEPROM. Nothing works until it is done.

   bash

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

4. 4
   Run the calibration on the follower

   The script connects with calibrate=False, then calls calibrate(). If a file exists for that id it offers to write it back to the motors instead of sweeping again.

   bash

   lerobot-calibrate \
       --robot.type=so100_follower \
       --robot.port=/dev/ttyACM0 \
       --robot.id=my_follower

5. 5
   Pose the arm mid-range, then press Enter

   The homing step. LeRobot resets calibration (offset 0, limits 0 and 4095), reads every joint's raw position, and writes Homing_Offset = raw - 2047. The prompt interpolates the device, so it prints your id then the class name.

   text

   Move my_follower SOFollower to the middle of its range of motion and press ENTER....

6. 6
   Sweep every joint to both hard stops, then press Enter

   Torque is off, so you move the arm by hand. The script polls Present_Position and keeps a running min and max. Take each joint to both mechanical limits at least once, and do not forget the gripper.

   text

   Move all joints except 'wrist_roll' sequentially through their
   entire ranges of motion.
   Recording positions. Press ENTER to stop...

7. 7
   Repeat for the leader

   Same command, teleop side. Each arm gets its own file. The raw counts will not match and are not supposed to; the normalized value in the same pose has to.

   bash

   lerobot-calibrate \
       --teleop.type=so100_leader \
       --teleop.port=/dev/ttyACM1 \
       --teleop.id=my_leader

The result goes to disk and to the servos in the same breath. The path comes from the device class name and the id you passed, under the Hugging Face cache root.

# follower
~/.cache/huggingface/lerobot/calibration/robots/so_follower/my_follower.json

# leader
~/.cache/huggingface/lerobot/calibration/teleoperators/so_leader/my_leader.json

# override the root if you want it inside your project
export HF_LEROBOT_CALIBRATION=/path/to/my/calibrations

Why a bad calibration ruins episodes rather than just offsetting them

Here is the part most guides skip. A LeRobot episode does not store encoder counts. Every observation and action is a float per joint, named shoulder_pan.pos and so on, produced by the normalization step between the bus and the rest of the stack.

# lerobot/motors/motors_bus.py, MotorsBus._normalize (abridged)

bounded_val = min(max_, max(min_, val))          # clamp to [range_min, range_max]

if norm_mode is MotorNormMode.RANGE_M100_100:    # body joints, legacy mode
    norm = (((bounded_val - min_) / (max_ - min_)) * 200) - 100

elif norm_mode is MotorNormMode.RANGE_0_100:     # the gripper, always
    norm = ((bounded_val - min_) / (max_ - min_)) * 100

elif norm_mode is MotorNormMode.DEGREES:         # body joints, current default
    mid = (min_ + max_) / 2
    max_res = self.model_resolution_table[model] - 1   # 4095 for an sts3215
    norm = (val - mid) * 360 / max_res           # note: val, not bounded_val

Two failure modes fall out of that. In the RANGE modes the value is clamped to the recorded range first, so anything beyond range_max is recorded as exactly 100, indistinguishable from a joint parked at its limit. DEGREES does not clamp, but its zero is the midpoint of your recorded range, so losing 200 counts on one side shifts every angle in the dataset by 8.8 degrees.

The second consequence is about leader-follower teleoperation. The leader's position is normalized with the leader's calibration, sent as a float, and unnormalized with the follower's before it reaches Goal_Position. The two arms never exchange raw counts, so the normalized space is the shared language: if either dictionary is wrong, the follower goes somewhere the leader did not ask for.

Six checks that a calibration is sane

None of these needs a policy, a dataset or a GPU. Run them after every calibration and after any mechanical work on the arm.

1. range_min is strictly less than range_max on all six joints. record_ranges_of_motion refuses to finish when they are equal, but cannot catch a range that is merely too narrow.
2. The span in counts matches the joint's real travel. Multiply by 0.088 for degrees: a joint swinging about 180 degrees should show roughly 2048 counts.
3. wrist_roll is exactly 0 and 4095. Anything else was written by an older version or by hand.
4. Every homing_offset is inside -2047 to +2047. Outside that, encode_sign_magnitude raises and the write never lands.
5. The gripper reads near 0 fully closed and near 100 fully open, since it always uses RANGE_0_100.
6. The file and the servos agree. robot.is_calibrated reads all three registers off the bus and compares them against the cached file.

import json, pathlib

RESOLUTION = 4096
path = pathlib.Path.home() / ".cache/huggingface/lerobot/calibration/robots/so_follower/my_follower.json"
cal = json.loads(path.read_text())

for joint, c in cal.items():
    span = c["range_max"] - c["range_min"]
    degrees = span * 360 / (RESOLUTION - 1)
    print(f"{joint:<14} id={c['id']} offset={c['homing_offset']:>6} "
          f"span={span:>5} counts = {degrees:6.1f} deg")

    assert c["range_min"] < c["range_max"], f"{joint}: empty range"
    assert abs(c["homing_offset"]) <= 2047, f"{joint}: offset outside sign-magnitude range"
    if joint == "wrist_roll":
        assert (c["range_min"], c["range_max"]) == (0, 4095), "wrist_roll should be a full turn"
    elif span < 200:
        print(f"  WARNING {joint}: only {span} counts ({degrees:.1f} deg), sweep it again")

from lerobot.robots.so_follower import SO100Follower, SO100FollowerConfig

robot = SO100Follower(SO100FollowerConfig(port="/dev/ttyACM0", id="my_follower"))
robot.connect(calibrate=False)

print("file matches motors:", robot.is_calibrated)
for joint in robot.bus.motors:
    raw = robot.bus.read("Present_Position", joint, normalize=False)
    off = robot.bus.read("Homing_Offset", joint, normalize=False)
    lo = robot.bus.read("Min_Position_Limit", joint, normalize=False)
    hi = robot.bus.read("Max_Position_Limit", joint, normalize=False)
    print(f"{joint:<14} raw={raw:>5} offset={off:>6} limits=({lo}, {hi})")

robot.disconnect()

The seventh check is behavioural. Run teleoperation and hold leader and follower in the same physical pose: the normalized values should line up. If one joint is consistently off, that joint's homing offset is the suspect, not the mechanics.

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

Do it yourself, or let the platform handle what comes after

pip install -e ".[feetech]"

lerobot-find-port
lerobot-setup-motors --robot.type=so100_follower --robot.port=/dev/ttyACM0

lerobot-calibrate --robot.type=so100_follower --robot.port=/dev/ttyACM0 --robot.id=my_follower
lerobot-calibrate --teleop.type=so100_leader  --teleop.port=/dev/ttyACM1 --teleop.id=my_leader

lerobot-teleoperate \
    --robot.type=so100_follower --robot.port=/dev/ttyACM0 --robot.id=my_follower \
    --teleop.type=so100_leader  --teleop.port=/dev/ttyACM1 --teleop.id=my_leader

How precise can this get, realistically

One count is 0.088 degrees, which sounds precise until you look at the mechanics in front of the sensor. The datasheet allows up to 0.5 degrees of backlash, about 5.7 counts. An independent bench test by Robonine put a dial indicator on an 86 mm lever, measured 1.3 mm of play at the tip, and worked that back to 0.0151 radians, roughly 0.87 degrees or ten counts. The same test put repeatability at 0.3 mm on a 10 cm lever, about 0.17 degrees, and reports a built-in dead zone of ten counts.

That sets a floor. Chasing a homing offset to within a few counts is pointless when the joint has ten counts of slop, which is why the eyeballed mid-pose is fine. Being wrong by hundreds of counts is not, and that is what an under-swept range gives you.

Version notes, because upstream moved

Calibration has been rewritten more than once, and older posts describe an API that no longer exists. If a command or path below does not match what you read elsewhere, check the version it was written for.

The normalization default matters more than it looks. RANGE_M100_100 and DEGREES encode the same motion as different numbers, and a checkpoint trained on one does not transfer without a conversion. Check use_degrees before concatenating a recording made under v0.4.3 or earlier with a new one. Two things on main are newer than most tutorials: a pygame range-slider GUI in lerobot/motors/calibration_gui.py, one row per motor for dragging range_min and range_max, and lerobot-find-joint-limits, which drives the follower from the leader and reports the limits it saw, plus end-effector bounds if you give it a URDF.

Where to go next

With a calibration you trust, the next thing that decides whether training works is the data. The recording walkthrough covers the mechanics, and our notes on collecting high-quality VLA training data cover the judgement calls. If you are still assembling, the full SO-100 setup guide starts one step earlier, and SO-100 against SO-101 matters here because both use STS3215 servos and the same calibration procedure.