Installation

The SDK ships two packages. Install both, just one, or neither — depending on your test stack.

Python: `pip install roboticks`

pip install roboticks

For MCAP recording (optional, pulls in mcap and mcap-ros2-support):

pip install 'roboticks[mcap]'

All extras:

Extra	What it adds	When
`mcap`	`mcap`, `mcap-ros2-support`	You use `mcap_capture`
`dev`	`pytest`, `pytest-cov`, `ruff`, `mypy`	Contributing to the SDK

The base install has no ROS2 dependency — see ROS-version-agnostic below.

In a colcon workspace

Add to your test package’s package.xml:

<test_depend>python3-roboticks-pip</test_depend>

…or, more pragmatically for a private workspace, install via pip into the colcon environment:

source /opt/ros/humble/setup.bash
python3 -m pip install --user 'roboticks[mcap]'

In a virtualenv

python3 -m venv .venv
source .venv/bin/activate
pip install 'roboticks[mcap]' pytest pytest-cov

The pytest plugin loads via the pytest11 entry point — no conftest.py changes required. Verify with:

pytest --trace-config 2>&1 | grep roboticks
# > active plugins: roboticks-0.1.0 at .../roboticks/pytest_plugin.py

C++: ament_cmake on `roboticks_cpp`

The C++ package is shipped via the ROS2 build farm (rosdep keys land on Humble, Iron, Rolling). For private workspaces, also vendor it as a submodule.

Via rosdep

Add to package.xml:

<test_depend>roboticks_cpp</test_depend>

Then:

rosdep install --from-paths src --ignore-src -r -y
colcon build

Vendored

cd src/
git submodule add https://github.com/roboticks-io/roboticks-sdk.git roboticks-sdk
# expose the cpp/ subtree to colcon
ln -s roboticks-sdk/cpp roboticks_cpp
colcon build

CMakeLists.txt

find_package(roboticks_cpp REQUIRED)

if(BUILD_TESTING)
  find_package(ament_cmake_gtest REQUIRED)
  ament_add_gtest(my_tests test/my_tests.cpp)
  target_link_libraries(my_tests roboticks_cpp::roboticks_cpp)
endif()

See C++ reference for the available targets (roboticks_cpp::roboticks_cpp, roboticks_cpp::gtest_main).

ROS2 distro matrix

ROS2 distro	Python	`roboticks`	`roboticks_cpp`
Humble (Ubuntu 22.04)	3.10	supported	supported
Iron (Ubuntu 22.04)	3.10	supported	supported
Jazzy (Ubuntu 24.04)	3.12	supported	supported
Rolling	3.10–3.12	supported	supported
(none, plain host)	3.10–3.13	supported (decorators only)	n/a

Foxy and earlier are end-of-life and not supported.

Python version matrix

The Python package supports CPython 3.10 through 3.13. PyPy is not supported (rclpy bindings are CPython-only).

Python	Supported	Notes
3.9	no	Below the ROS2 floor
3.10	yes	Humble / Iron default
3.11	yes
3.12	yes	Jazzy default
3.13	yes	Decorator-only path

ROS-version-agnostic

The Python package’s pyproject.toml does not declare rclpy as a dependency. Imports of rclpy live behind try-blocks; assertion helpers raise a clear RuntimeError at call time on hosts without rclpy:

# On macOS without rclpy:
from roboticks.assertions import assert_topic_published
assert_topic_published(...)
# RuntimeError: rclpy is not importable on this host.
#   Install ROS2 (Humble/Iron/Rolling) or run this test on a runner with ROS2.

This means:

Linters and type-checkers run anywhere.
Unit tests that don’t touch rclpy can run on a Mac, in CI without a ROS2 base image, etc.
The pytest plugin still emits properties; only the rclpy-touching code paths require ROS2.

Verify

python -c "import roboticks; print(roboticks.__version__)"
# > 0.1.0

For the C++ package:

. install/setup.bash
ros2 pkg list | grep roboticks_cpp
# > roboticks_cpp

Troubleshooting

The pytest plugin doesn't seem to be loaded

Run pytest --trace-config and look for roboticks in the active plugins list. If absent: pip install --force-reinstall roboticks then re-run.

`ImportError: rclpy` when importing roboticks.assertions

The assertions module imports rclpy lazily at the top level. If you’re on a non-ROS host and just want decorators, import from roboticks directly: from roboticks import confirms (no rclpy required).

colcon doesn't find roboticks_cpp

Source the right setup file: source install/setup.bash (not setup.sh). Confirm with ros2 pkg list | grep roboticks_cpp.

MCAP capture errors on import

The MCAP support is an extra. pip install 'roboticks[mcap]' adds mcap and mcap-ros2-support.

Decorators

First thing to import: @confirms.

Modules

The full module map.

Quickstart

From zero to first traced PR in ten minutes.

C++ reference

roboticks_cpp API in full.

Quick Start

GitHub App

Requirements

Traceability

Testing

SDK

Self-Hosted Runners

AI Features

CLI

Evidence Packs

Standards Coverage

Compliance Patterns

Integrations

Pricing

Resources

SDK Installation

Installation

Python: `pip install roboticks`

In a colcon workspace

In a virtualenv

C++: ament_cmake on `roboticks_cpp`

Via rosdep

Vendored

CMakeLists.txt

ROS2 distro matrix

Python version matrix

ROS-version-agnostic

Verify

Troubleshooting

Next

Decorators

Modules

Quickstart

C++ reference

​Installation

​Python: pip install roboticks

​In a colcon workspace

​In a virtualenv

​C++: ament_cmake on roboticks_cpp

​Via rosdep

​Vendored

​CMakeLists.txt

​ROS2 distro matrix

​Python version matrix

​ROS-version-agnostic

​Verify

​Troubleshooting

​Next

Decorators

Modules

Quickstart

C++ reference

Installation

Python: `pip install roboticks`

In a colcon workspace

In a virtualenv

C++: ament_cmake on `roboticks_cpp`

Via rosdep

Vendored

CMakeLists.txt

ROS2 distro matrix

Python version matrix

ROS-version-agnostic

Verify

Troubleshooting

Next