Skip to main content

pysoarm

CI PyPI Python License Typed

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.1. Bus transport (SCS over pyserial and the optional rustypot backend), calibration (including the motor-side flow and pysoarm calibrate), safety guards, trajectories, Cartesian kinematics, the SOArm device object with follower/leader roles, structured diagnostics, the ArmBridge/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 rustypot backend (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 same Bus protocol.
  • 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, per-tick latency/p95 and an error policy that survives a lost frame.

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.toml is the only source of published metadata — pip install pysoarm never looks at anything else. Dev-only tooling lives in PEP 735 dependency groups (dev, docs, hardware), which are not part of the distribution.

  • uv.lock makes the dev environment reproducible and is committed. CI runs with UV_FROZEN=1 and uv 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 opens uv.lock PRs.

Hardware tests are marked hardware and skipped unless PYSOARM_HARDWARE_PORT is set:

PYSOARM_HARDWARE_PORT=/dev/ttyACM0 pytest -m hardware

Publishing

  1. bump version in pyproject.toml and CHANGELOG.md;
  2. git tag v0.1.0 && git push --tags;
  3. the release.yml workflow builds, runs twine 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.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 pysoarm 0.1.1
File Size Uploaded Provenance Actions
pysoarm-0.1.1.tar.gz 127.5 kB With provenance Details for pysoarm-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 222.7 kB

Release files / pysoarm-0.1.1.tar.gz

Download URL pysoarm-0.1.1.tar.gz
Size 127.5 kB
Tags Source
SHA-256 checksum
How to use checksums
626b6fb392c3aec9e5808019ef553e8433cceacb86aebf317d8e760f7da90d2b
BLAKE2b-256 checksum
How to use checksums
e0936f96b116d553e124658f99af01bdb004708d45a5cb9c833b4c9e8e08d44a
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 log

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

Download URL pysoarm-0.1.1-py3-none-any.whl
Size 95.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ac255755577f97ca8c3b9fdd4c018771cf271ea53942c6f69c5276eaac289e4c
BLAKE2b-256 checksum
How to use checksums
c997624d812b8696f3c7c02cd030ccb528795be8f1efa58469380feb7a034eaf
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 log

Security for pysoarm 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 pysoarm-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 Nov 5, 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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

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