Ruckig: Real-Time, Jerk-Constrained Motion Generation

Where Ruckig Fits in Robot and Machine Control

Ruckig addresses online trajectory generation for robots and machines whose commands cannot change instantaneously without violating motion limits. A control application supplies an initial position, velocity, and acceleration, then specifies a target state and per-axis limits for maximum velocity, acceleration, and jerk. Ruckig calculates how to move between those states. This is useful for robot arms, joints, actuators, and other machines whose controller needs a new trajectory as sensor input changes.

The important boundary is between a target state and a geometric path. For a state-to-state motion, the target includes position, velocity, and acceleration. Ruckig states that it guarantees a time-optimal solution under the supplied constraints. It can also accept intermediate positions for waypoint following, although that mode changes both the planning problem and the product behavior described in the README.

Ruckig itself is unitless. The README recommends using a consistent unit system, such as meters or radians for positions and seconds for time. That means the library does not enforce whether a position represents a joint angle, linear displacement, or another coordinate. The integrating application owns unit selection, conversion, and hardware-specific behavior.

Ruckig's Online State and Control-Cycle Model

The C++ interface is organized around `Ruckig`, `InputParameter`, and `OutputParameter`. The `Ruckig` constructor receives the number of degrees of freedom and the control cycle. Input data is divided into the current state, target state, and kinematic limits. Output data holds the newly calculated state for each cycle.

The central mechanism is repeated evaluation. Application code calls `ruckig.update(input, output)`. While the return value is `Result::Working`, the new output state can be sent to the target device. Calling `output.pass_to_input(input)` then copies that calculated kinematic state into the input's current state. If the actual current state differs from the precalculated trajectory at the next update, Ruckig calculates again from the novel input. This is the feature that allows trajectories to be generated on the fly.

Acceleration-constrained operation is available by omitting `max_jerk` and the current and target acceleration values. Omitting a constraint does not turn Ruckig into a general path planner. It changes which kinematic state and limits participate in the trajectory calculation.

Building Ruckig and Running a First C++ Trajectory

The README says Ruckig has no dependencies except for testing. Build it in Release mode from a new build directory with the documented CMake sequence. The commands create `build`, configure the parent project, and invoke `make`.

mkdir -p build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make

After compilation, link your application against the built library. For system-wide installation, the README lists `make install`; it also documents Debian packaging through `cpack` and `dpkg`. An embedding project can instead include the repository as a subdirectory. The README points to `examples/CMakeLists.txt` for the concrete CMake pattern and names `add_subdirectory(ruckig)` as the integration call.

A minimal first control object uses six degrees of freedom and a `0.001` second control cycle, exactly as shown below:

Ruckig ruckig {6, 0.001};

The example then creates six-axis input and output parameters. The ellipses in this README excerpt indicate omitted repeated values, so the snippet is an interface outline rather than a complete executable program. The repository's `examples/01_position.cpp` is the concrete file to consult for the full first-use implementation.

Populating Start, Target, and Motion Limits

Each input parameter has parallel vectors for the current position, velocity, and acceleration, followed by target values and maximum limits. Keeping these vectors aligned is an application responsibility because the constructor identifies degrees of freedom, not semantic axis names.

The following block follows the values in the README. Each vector has six entries before the displayed ellipsis, so the ellipses stand for values that a complete example must fill in.

InputParameter input {6};
input.current_position = {0.2, ...};
input.current_velocity = {0.1, ...};
input.current_acceleration = {0.1, ...};
input.target_position = {0.5, ...};
input.target_velocity = {-0.1, ...};
input.target_acceleration = {0.2, ...};
input.max_velocity = {0.4, ...};
input.max_acceleration = {1.0, ...};
input.max_jerk = {4.0, ...};

OutputParameter output {6};

The control loop asks Ruckig to update, consumes `output.new_position`, and advances the input state. The state handoff is not optional because the next calculation depends on the current state.

while (ruckig.update(input, output) == Result::Working) {
  // e.g. robot->setJointPositions(output.new_position)
  output.pass_to_input(input);
}

For most applications, the README says this loop runs in a real-time thread and controls actual hardware. Completion is reported through `Result::Finished`.

Intermediate Waypoints and the Cloud API Boundary

Intermediate waypoints change the licensing boundary in the Ruckig Community Version. The README states that this edition uses a cloud API for remote calculation and is therefore not real-time capable. Ruckig Pro is documented as calculating the same general waypoint capability locally. This distinction matters more than the extra constructor argument.

The constructor and both parameter objects reserve room for a maximum number of waypoints:

Ruckig ruckig {6, 0.001, 8};
InputParameter input {6, 8};
OutputParameter output {6, 8};

Intermediate positions can then be assigned before calculation:

input.intermediate_positions = {
  {0.2, ...},
  {0.8, ...},
};

Once intermediate positions are present, the documented Community Version switches to the cloud API. Teams with hard real-time deadlines should not treat this path as equivalent to the locally calculated state-to-state loop. The README also warns that jerk-limited online trajectory generation with waypoints has fundamental limitations and links to a dedicated documentation page. That limitation makes Ruckig Pro, with local calculation, the relevant alternative for applications that reject a remote dependency or need local waypoint timing.

Python and Rust Availability Compared

Ruckig is primarily presented as a C++ library, but the repository contains packaging and examples for other languages. A Python module is available from PyPI and is described as useful for development or debugging. The Python package metadata requires Python `>=3.9` and uses `scikit-build-core` with `nanobind` to build `python_ruckig` and `python_ruckig_stub`.

The documented installation command is short:

pip install ruckig

When building through CMake, `BUILD_PYTHON_MODULE` enables the module. A repository-local Python installation is also supported with:

pip install .

Rust support is visible in `Cargo.toml` and matching example files. The crate uses edition `2021`, depends on `cxx` and `cxx-build`, and points its library at `src/wrapper/rust.rs`. That wrapper approach differs from treating Ruckig as a native Rust optimizer: the Cargo metadata binds a C++ implementation through the listed bridge dependencies. The repository includes Rust position, offline position, and velocity examples.

These language choices do not change the core adoption question. Control-loop timing, waypoint locality, and the mapping from output states to real hardware remain application-level checks.

Release Cadence, Versioning, and MIT Implications

The repository is not archived, and the last push was on 2026-09-29. Recent releases listed with the project include `v0.19.4` on 2026-07-15, `v0.17.3` on 2026-03-24, and `v0.15.3` on 2025-05-16. These dates indicate recent repository activity, but they do not by themselves describe compatibility between releases or the policy for upgrading a deployed control system.

There is a concrete versioning detail to check. The listed latest release is `v0.19.4`, while both `pyproject.toml` and `Cargo.toml` declare version `0.19.6`. A source build or wrapper installation should therefore be tied to a deliberate repository or package revision rather than assuming that release tags and package metadata always match.

The C++ README states that Ruckig has no dependencies apart from testing, which reduces the number of runtime components for a basic build. Python and Rust builds still use their documented build tooling and wrapper dependencies. The project is licensed under MIT. Integrating its source into a distributed product therefore requires attention to the actual `LICENSE` file and preservation of its license notice. This is a source-level compliance check, not advice on a particular distribution model.

Editorial conclusion

Engineers building real-time C++ control loops should consider Ruckig when jerk limits and arbitrary initial or target states matter. Projects that need locally calculated intermediate waypoints should verify the Community Version's cloud API boundary first, while teams needing local waypoint calculation must examine Ruckig Pro. Before adoption, confirm that the planned control cycle, motion limits, and hardware integration fit the documented interface.

Frequently asked questions

Official sources

1. License: MIT
2. pantor/ruckig on GitHub
3. Project website
4. README
5. Releases