Skip to content

ServoPy 0.3.0

Pre-release
Pre-release

Choose a tag to compare

View all tags
@OpenGHz OpenGHz released this 18 Sep 09:48
· 4 commits to main since this release
v0.3.0
9d11807

ServoPy 0.3.0 is the first public package release of ServoPy, a ROS-independent library for online joint and Cartesian servoing.

ServoPy turns robot targets and measured feedback into bounded motion references. It combines a C++ numerical core with a Python API for building control loops, connecting existing IK solvers, and experimenting with robot motion in simulation.

This initial release includes:

  • Joint and Cartesian commands. Track joint positions, joint velocities, end-effector poses, and Cartesian twists through a common servo interface.

  • Motion limits and fault handling. Generate references with joint position, velocity, and acceleration limits, singularity handling, input freshness checks, timing checks, and explicit fault recovery.

  • Flexible kinematics and IK. Use built-in URDF kinematics or optional Pinocchio support. Connect an existing Python position IK solver through PositionIKAdapter, with checks for limits, joint continuity, and pose residuals.

  • Differential IK and redundancy control. Choose damped least squares or a box-constrained QP solver, add nullspace posture objectives and joint centering, or provide a custom differential IK implementation.

  • Optional jerk control. Use Ruckig smoothing with trajectory sampling and a retained feasible stopping trajectory.

  • Runtime and reproducibility tools. Connect device callbacks, run a periodic control loop, stream the latest target, cancel and recover execution, and record or replay sessions using JSONL.

Start in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --only-binary=:all: servo-py==0.3.0
python -m servo_py.examples.track_pose

The example runs without a robot or display. The package name is servo-py; the Python import is servo_py.

Prebuilt Linux wheels cover CPython 3.10–3.14, x86_64 and ARM64, with glibc 2.28 or newer. Matching wheels install without a C++ compiler, CMake, or a separate Eigen installation. NumPy is the only required third-party Python runtime dependency.

MuJoCo, Pinocchio, and Ruckig are optional integrations, available through the mujoco, pinocchio, and ruckig extras. The Ruckig extra uses version 0.19.4; its upstream Linux wheels cover x86_64, while ARM64 requires building that dependency from source. Building ServoPy itself from source requires a compiler supporting C++17 or newer.

Try the Panda simulation with MuJoCo:

python -m pip install --only-binary=:all: 'servo-py[mujoco]==0.3.0'
servo-py-panda --control-mode joint-position

The demo provides three control paths:

Mode | Control path -- | -- torque | Cartesian pose → differential IK → joint reference → torque control joint-position | Joint target → joint reference → position actuator ik-position | Cartesian pose → position IK → joint reference → position actuator

The viewer opens by default. Add --headless to run without a desktop. External targets, trajectory recording, and optional Ruckig smoothing are also supported.

ServoPy wheels are approximately 0.38–0.42 MB, excluding dependencies. Panda model assets are excluded from both wheels and source distributions. The demo downloads a pinned archive of approximately 5 MB on first use, verifies its SHA-256 checksum, and caches it for offline reuse. For an offline first run, provide the archive through SERVO_PY_PANDA_ARCHIVE.

Release validation covered the ten Linux wheels, Ubuntu 22.04 and 24.04 installations, and examples executed from installed packages outside the repository. The full optional-dependency suite passed 188 tests on x86_64; ARM64 passed 176 tests, with Ruckig-dependent checks skipped. A clean installation from TestPyPI also passed the basic example and Panda download, simulation, and offline cache checks. See the validation record for environments and results.

This is an alpha release. ServoPy generates motion references; applications remain responsible for feedback, actuator commands, and device stopping. Physical-robot validation, built-in geometric collision checking, and hard real-time execution are outside the current verified scope. The Panda position-control modes retain gravity-related tracking offsets. This release provides Linux wheels; Windows and macOS wheels are not included.

Explore the documentation, Python IK integration guide, and Panda tutorial. The README is available in English and Chinese; most tutorials and API documentation are currently in Chinese. Bug reports and reproducible examples are welcome through GitHub Issues.

ServoPy is MIT-licensed. The separately distributed Panda model assets are Apache-2.0 licensed; see NOTICE for attribution.

**ServoPy 0.3.0 is the first public package release of ServoPy**, a ROS-independent library for online joint and Cartesian servoing.

ServoPy turns robot targets and measured feedback into bounded motion references. It combines a C++ numerical core with a Python API for building control loops, connecting existing IK solvers, and experimenting with robot motion in simulation.

This initial release includes:

  • Joint and Cartesian commands. Track joint positions, joint velocities, end-effector poses, and Cartesian twists through a common servo interface.
  • Motion limits and fault handling. Generate references with joint position, velocity, and acceleration limits, singularity handling, input freshness checks, timing checks, and explicit fault recovery.
  • Flexible kinematics and IK. Use built-in URDF kinematics or optional Pinocchio support. Connect an existing Python position IK solver through PositionIKAdapter, with checks for limits, joint continuity, and pose residuals.
  • Differential IK and redundancy control. Choose damped least squares or a box-constrained QP solver, add nullspace posture objectives and joint centering, or provide a custom differential IK implementation.
  • Optional jerk control. Use Ruckig smoothing with trajectory sampling and a retained feasible stopping trajectory.
  • Runtime and reproducibility tools. Connect device callbacks, run a periodic control loop, stream the latest target, cancel and recover execution, and record or replay sessions using JSONL.

Start in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --only-binary=:all: servo-py==0.3.0
python -m servo_py.examples.track_pose

The example runs without a robot or display. The package name is servo-py; the Python import is servo_py.

Prebuilt Linux wheels cover CPython 3.10–3.14, x86_64 and ARM64, with glibc 2.28 or newer. Matching wheels install without a C++ compiler, CMake, or a separate Eigen installation. NumPy is the only required third-party Python runtime dependency.

MuJoCo, Pinocchio, and Ruckig are optional integrations, available through the mujoco, pinocchio, and ruckig extras. The Ruckig extra uses version 0.19.4; its upstream Linux wheels cover x86_64, while ARM64 requires building that dependency from source. Building ServoPy itself from source requires a compiler supporting C++17 or newer.

Try the Panda simulation with MuJoCo:

python -m pip install --only-binary=:all: 'servo-py[mujoco]==0.3.0'
servo-py-panda --control-mode joint-position

The demo provides three control paths:

Mode Control path
torque Cartesian pose → differential IK → joint reference → torque control
joint-position Joint target → joint reference → position actuator
ik-position Cartesian pose → position IK → joint reference → position actuator

The viewer opens by default. Add --headless to run without a desktop. External targets, trajectory recording, and optional Ruckig smoothing are also supported.

ServoPy wheels are approximately 0.38–0.42 MB, excluding dependencies. Panda model assets are excluded from both wheels and source distributions. The demo downloads a pinned archive of approximately 5 MB on first use, verifies its SHA-256 checksum, and caches it for offline reuse. For an offline first run, provide the archive through SERVO_PY_PANDA_ARCHIVE.

Release validation covered the ten Linux wheels, Ubuntu 22.04 and 24.04 installations, and examples executed from installed packages outside the repository. The full optional-dependency suite passed 188 tests on x86_64; ARM64 passed 176 tests, with Ruckig-dependent checks skipped. A clean installation from TestPyPI also passed the basic example and Panda download, simulation, and offline cache checks. See the [validation record](https://openghz.github.io/servopy/validation/) for environments and results.

This is an alpha release. ServoPy generates motion references; applications remain responsible for feedback, actuator commands, and device stopping. Physical-robot validation, built-in geometric collision checking, and hard real-time execution are outside the current verified scope. The Panda position-control modes retain gravity-related tracking offsets. This release provides Linux wheels; Windows and macOS wheels are not included.

Explore the [documentation](https://openghz.github.io/servopy/), [Python IK integration guide](https://openghz.github.io/servopy/python-ik/), and [Panda tutorial](https://openghz.github.io/servopy/mujoco-panda/). The README is available in English and Chinese; most tutorials and API documentation are currently in Chinese. Bug reports and reproducible examples are welcome through [GitHub Issues](https://github.com/OpenGHz/servopy/issues).

ServoPy is MIT-licensed. The separately distributed Panda model assets are Apache-2.0 licensed; see [NOTICE](https://github.com/OpenGHz/servopy/blob/main/NOTICE) for attribution.

Assets 2
Loading