Skip to main content

Pixel-art SO-101 with the elbow highlighted

so101-calibrator

Calibrate your SO-101 arms step by step, with a check at every step.
For LeRobot. In the terminal. English and Turkish.

PyPI Python 3.10+ Tests LeRobot compatible MIT license

One step of the calibration: move the elbow

Start

uv tool install so101-calibrator     # or: pipx install so101-calibrator / pip install so101-calibrator
so101-cal --mock                     # try it on a simulated arm
so101-cal                            # then with your arms plugged in

Pick Follower, then Leader, then Test both arms. Every screen shows one thing to do; the joint to move is orange; Enter goes on. LeRobot then finds the calibration with no extra flags.

Why

lerobot-calibrate does the math right but leaves you blind: a motor on the wrong id, a follower on USB power, a joint swept halfway or a motor mounted backwards only shows up later as a jerky robot. Here every step is checked, every failure says what to fix, and every calibration is kept as a version.

✅ Checked steps USB port, motors 1–6, supply voltage, middle pose, ranges, joint directions, save
🕘 Versions history, diff, one-key rollback, export to LeRobot
🦾 Teleop test leader → follower, refuses to start if the poses differ
💬 Assistant optional, local (Strands + Ollama) or Claude
🧪 Mock arm try everything without hardware

Home screen   The assistant explaining a failed check

More

Keys
Key
⏎ start · done · continue · retry
r / f retry / accept a failed step anyway
j live joint bars
? the long explanation of a step
a ask the assistant
l English ↔ Türkçe
h history (⏎ make active, d compare, e export)
esc cancel (press twice)
Commands (scripts, other ids, rollback)
so101-cal calibrate follower --id follower --note "new elbow motor"
so101-cal calibrate leader --id leader
so101-cal teleop-test
so101-cal verify follower             # EEPROM still matches, middle pose reads ~2047

so101-cal history                     # all arms and versions
so101-cal diff follower 2 3           # what changed, in encoder ticks
so101-cal activate follower 2         # roll back and export
so101-cal write follower              # push the active version into the motors
so101-cal export follower --calibration-dir hardware/calibration
so101-cal import path/to/follower.json --role follower --id follower

Then, as usual:

lerobot-teleoperate --robot.type=so101_follower --robot.port=... --robot.id=follower \
  --teleop.type=so101_leader --teleop.port=... --teleop.id=leader
Assistant
uv tool install "so101-calibrator[ai]"
so101-cal ai use ollama               # local model (or ollama:qwen2.5, ...)
so101-cal ai use openai:my-model      # LM Studio / llama.cpp / vLLM: URL in $SO101CAL_AI_URL
so101-cal ai use claude               # ANTHROPIC_API_KEY

Press a in the app and ask, or press Enter on an empty line to have the current problem explained. Local models run as a Strands agent that can also read the calibration history and compare versions. It only explains: none of its tools can move the arm.

Try it without hardware
so101-cal --mock --mock-faults voltage:5         # see a failing check
so101-cal --mock dashboard                       # the web version, http://127.0.0.1:8101

Faults: missing:<id>, voltage:<V>, reversed:<joint>, stuck:<joint>, hot:<joint> (prefix leader. for the leader).

Where things are stored

History: ~/.so101-calibrator/<arm>/v0001.json … (plain JSON; --store or $SO101CAL_HOME to move it). Exports: the LeRobot cache, ~/.cache/huggingface/lerobot/calibration/robots/so_follower/<id>.json and teleoperators/so_leader/<id>.json (or $HF_LEROBOT_CALIBRATION). A different existing file is kept as a .bak.

Troubleshooting
Symptom Likely cause
No port disappears when unplugging Charge-only USB cable, or the CH343 driver is missing (Windows)
No motor answers Power adapter off, or the cable to the first motor
Motors answer at another baud rate Run lerobot-setup-motors once
Missing motor id 4 Loose cable going into motor 4
Direction mismatch on one joint A motor or horn is mounted the other way round
EEPROM differs Motor replaced or another tool wrote it: recalibrate or so101-cal write
How it relates to LeRobot

Same math and file format as lerobot-calibrate for the SO-101 (homing offset = position − 2047, recorded min/max, wrist_roll 0..4095), through Feetech's scservo_sdk, so neither LeRobot nor PyTorch is needed. Built against LeRobot 0.6.1. The command line is the stable interface; the Python API may change before 1.0.

Contributing

Reports from real arms are very welcome. See CONTRIBUTING.md.

MIT. The SO-101 pixel art is rendered from the SO-ARM100 model (Apache-2.0).

Metadata

Release files for so101-calibrator 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for so101-calibrator 0.1.1
File Size Uploaded Provenance Actions
so101_calibrator-0.1.1.tar.gz 292.1 kB With provenance Details for so101_calibrator-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for so101-calibrator 0.1.1
File Interpreter ABI Platform Actions
so101_calibrator-0.1.1-py3-none-any.whl Python 3 none any Details for so101_calibrator-0.1.1-py3-none-any.whl

Total release size: 585.5 kB

Release files / so101_calibrator-0.1.1.tar.gz

Download URL so101_calibrator-0.1.1.tar.gz
Size 292.1 kB
Tags Source
SHA-256 checksum
How to use checksums
2ac21c2fb75dbe6132edf862bd02a1b90c6df667a34faecdf791ea84b7a15a61
BLAKE2b-256 checksum
How to use checksums
ee0b1e01566844deaae56af2db08b5eee2b6bd8e271ae866ac0f619d9eabd3aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / so101_calibrator-0.1.1-py3-none-any.whl

Download URL so101_calibrator-0.1.1-py3-none-any.whl
Size 293.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bb68a6c17e25564419120802f656fa63e232c855e09eba2b9d6626da23d834c4
BLAKE2b-256 checksum
How to use checksums
77b97878e224df8a2a8c3551d8f79d4e324ae1edcda434218ab29f057673074a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for so101-calibrator 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for so101_calibrator-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page