pysoarm
A lean, hardware-level Python API for the SO-100 / SO-101 robot arm: six Feetech STS3215 serial-bus servos on a single 1 Mbaud TTL bus.
pysoarm talks to the bus directly and deliberately stops there: no datasets, no policies,
no training stack. It targets the ergonomics of pylibfranka / pyAgxArm
(connect() → read_once() → write_goal() / control loop) within what position-servo
hardware can actually do.
Status: 0.1.2. Bus transport (SCS over
pyserialand the optionalrustypotbackend), calibration (including the motor-side flow andpysoarm calibrate), safety guards, trajectories, Cartesian kinematics, theSOArmdevice object with follower/leader roles, structured diagnostics, theArmBridge/ROS 2 adapter and the CLI are implemented and covered by tests, including opt-in hardware tests on a real SO-101. Teleoperation, dataset recording and policies are deliberate non-goals — see ADR 0001.
Why
- 1.4 ms per control step with the optional
rustypotbackend (0.98 ms to read six joints, 0.26 ms to write six goals) → a 200 Hz loop with zero overruns; 2.8 ms and ~2 % overruns with the pure-Python default. - Single small dependency (
pyserial) by default;pip install "pysoarm[rustypot]"adds the Rust backend (what LeRobot uses) behind the sameBusprotocol. - Explicit safety layer: per-step clipping, soft limits, temperature/voltage guards, communication watchdog — the parts that usually get skipped in quick scripts.
- Reuses your existing calibration (LeRobot-compatible JSON) instead of forcing
a re-calibration, and can run the Feetech calibration flow itself (
pysoarm calibrate). - Field diagnostics: structured status bits,
arm.health(),pysoarm doctor --stress(with--jsonand role-aware voltage thresholds), per-tick latency/p95 and an error policy that survives a lost frame, with failures attributed to the read, callback or write. - No software speed cap by default (LeRobot parity): goals are sent as requested, bounded
by the soft limits, thermal/voltage guards and the servo itself. Opt in to a rate-independent
ceiling with
SafetyLimits(max_speed_deg_s=720);gripper.close(wait=True)runs a timed trajectory, andconnect()retries transient serial failures with a backoff.
What it is not
The STS3215 is a position servo: there is no torque sensor, no force/torque feedback
and no hard real-time bus. Impedance/torque control à la Franka is not possible;
see docs/hardware.md for the honest capability matrix.
Non-goals (deliberate, see ADR 0001)
pysoarm is a device-layer SDK. A feature belongs here only if it is a physical fact of a single device (register, scale, calibration, limit, timing, status bit). Everything that needs a second device, an external data format or a learning stack stays outside:
| Not in pysoarm | Use instead |
|---|---|
| Teleoperation / leader-follower / input devices | ~10 lines of your own code (follower.write_goal(leader.read_once().q_deg)), or lerobot-teleoperate |
| Dataset recording (cameras, video encoding, parquet, Hub upload) | LeRobot (lerobot-record) |
| Dataset-format replay | ResampledTrajectory + your loader (any (t, q) table) |
| Policies, training, RL environments | LeRobot / your framework |
| ROS / ROS2 driver | a separate adapter package (not planned here) |
| Torque / impedance control | not available on position-servo hardware |
The reason is maintenance, not modesty: recording would pull in av, pyarrow, opencv
and huggingface_hub, and couple us to a dataset schema owned by upstream. The seam is
documented so the decision can be revisited without breaking the layer rule.
Install
pip install pysoarm # reference backend (pyserial)
pip install "pysoarm[rustypot]" # + fast Rust backend
pip install "pysoarm[dev]" # lint, types, tests, build
From source, for development (uv is the supported workflow):
git clone https://github.com/applebluecode/pysoarm && cd pysoarm
make install-dev # = uv sync --locked && uv run pre-commit install
Without uv (pip 25.1+, PEP 735 groups):
python -m venv .venv && . .venv/bin/activate
pip install --group dev -e .
pre-commit install
Quickstart
from pysoarm import SOArm
arm = SOArm(port="/dev/so101_follower", calibration="my_follower.json")
arm.connect()
try:
state = arm.read_once()
print(state.q_deg)
finally:
arm.stop()
A leader arm is the same object with role="leader" (read-only, torque stays off):
leader = SOArm("/dev/so101_leader", role="leader", calibration="my_leader.json")
Repository layout
src/pysoarm/ # the importable package (src layout)
arm.py # SOArm: high-level device object (pylibfranka-like surface)
loop.py # fixed-rate loop timing, latency stats and error policy
diagnostics.py # health cache, alarm latching and MotorHealth snapshots
tuning.py # motor-config register read/write helpers
state.py # immutable ArmState snapshots
calibration/ # LeRobot JSON + data model, and the motor-side calibration flow
gripper.py # thin percent-of-travel facade over the sixth joint
safety.py # limits, guards, watchdog
trajectory.py # interpolators / ramps for move_to()
bus/ # transport backends behind one Protocol (base, scs, rustypot, fake)
models/ # per-arm descriptions (joint names, motor ids, directions)
kinematics/ # optional FK/IK (placo) on top of a SO-101 URDF
cli/ # `pysoarm` entry point, parser and one module per command family
devices/udev/ # udev rule for stable /dev/so101_* names
tests/ # unit tests (hardware tests are opt-in)
examples/ # runnable examples
docs/ # mkdocs site + docs/adr/ (scope and other decisions)
ros2/ # separate ament_python package: pysoarm_ros2 node
.github/workflows/ # CI (lint + types + tests + build) and PyPI release
ROS 2
ros2/pysoarm_ros2 is a thin rclpy node over pysoarm.bridge.ArmBridge: it publishes
joint_states (radians), accepts joint_commands (radians) and exposes enable / disable
services. It stays a separate package so the device layer keeps zero ROS dependencies.
colcon build --packages-select pysoarm_ros2
ros2 run pysoarm_ros2 arm_node --ros-args -p port:=/dev/so101_follower -p backend:=rustypot
See docs/guides/ros2.md for parameters and safety behaviour.
Cartesian control
Kinematics is optional (pip install "pysoarm[kinematics]", needs your own URDF):
from pysoarm.kinematics import PlacoKinematics
arm = SOArm("/dev/so101_follower", kinematics=PlacoKinematics("so101.urdf"))
print(arm.forward()) # current end-effector pose
arm.move_to_pose(target_pose, duration=2.0) # IK, then a joint-space move
Unreachable targets raise NotReachableError before anything is written.
Development
make install-dev # uv sync --locked + pre-commit hooks
make check # lint + type + test (what CI runs)
make lint # ruff check + ruff format --check
make type # mypy --strict
make test # pytest
make cov # pytest + coverage
make build # sdist + wheel, then twine check --strict
make docs # serve the mkdocs site locally
Everything runs through uv run, so you never activate an environment manually.
Dependency management
-
pyproject.tomlis the only source of published metadata —pip install pysoarmnever looks at anything else. Dev-only tooling lives in PEP 735 dependency groups (dev,docs,hardware), which are not part of the distribution. -
uv.lockmakes the dev environment reproducible and is committed. CI runs withUV_FROZEN=1anduv sync --locked, so a stale lock fails the build instead of silently resolving different versions. -
The index is pinned in
pyproject.toml([[tool.uv.index]]→pypi.org) so the lock names the same artefacts for everyone. To resolve through a mirror locally:UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple uv lock
…but do not commit that lock: it would pin mirror URLs for downstream contributors.
-
make upgrade(uv lock --upgrade) is the way to bump dependencies; Dependabot also opensuv.lockPRs.
Hardware tests are marked hardware and skipped unless PYSOARM_HARDWARE_PORT is set:
PYSOARM_HARDWARE_PORT=/dev/ttyACM0 pytest -m hardware
Publishing
- bump
versioninpyproject.tomlandCHANGELOG.md; git tag v0.1.2 && git push --tags;- the
release.ymlworkflow builds, runstwine check, and publishes to PyPI via trusted publishing (OIDC, no API token stored).
License
Apache-2.0 — see LICENSE.
Metadata
Release files for pysoarm 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pysoarm-0.1.2.tar.gz | 141.5 kB | With provenance | Details for pysoarm-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pysoarm-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for pysoarm-0.1.2-py3-none-any.whl |
Total release size: 243.0 kB
Release files / pysoarm-0.1.2.tar.gz
| Download URL | pysoarm-0.1.2.tar.gz |
|---|---|
| Size | 141.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7da391c01cbc8676bf95d958052add375edce0c575553768c96e29d8ad7e290a
|
|
BLAKE2b-256 checksum How to use checksums |
cc224e143272acc01f51185b52aa4a81195f04b0535e8c781789c97d777d87f3
|
| 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 Nov 5, 2026.
Transparency logRelease files / pysoarm-0.1.2-py3-none-any.whl
| Download URL | pysoarm-0.1.2-py3-none-any.whl |
|---|---|
| Size | 101.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e8193f40e43c2111c3f7dd163a5ae41c1a3b80872563e211a9973763aa5f55e
|
|
BLAKE2b-256 checksum How to use checksums |
958aef9f49fada12271f2c57ec6536a36eaaf6155bd68dcda4f7e913fdc4e997
|
| 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 Nov 5, 2026.
Transparency logSecurity for pysoarm 0.1.2
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.
Attestation for pysoarm-0.1.2.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 Nov 5, 2026.
Transparency logA 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.