Skip to main content

​
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:
ExtraWhat it addsWhen
mcapmcap, mcap-ros2-supportYou use mcap_capture
devpytest, pytest-cov, ruff, mypyContributing 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 distroPythonroboticksroboticks_cpp
Humble (Ubuntu 22.04)3.10supportedsupported
Iron (Ubuntu 22.04)3.10supportedsupported
Jazzy (Ubuntu 24.04)3.12supportedsupported
Rolling3.10–3.12supportedsupported
(none, plain host)3.10–3.13supported (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).
PythonSupportedNotes
3.9noBelow the ROS2 floor
3.10yesHumble / Iron default
3.11yes
3.12yesJazzy default
3.13yesDecorator-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

Run pytest --trace-config and look for roboticks in the active plugins list. If absent: pip install --force-reinstall roboticks then re-run.
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).
Source the right setup file: source install/setup.bash (not setup.sh). Confirm with ros2 pkg list | grep roboticks_cpp.
The MCAP support is an extra. pip install 'roboticks[mcap]' adds mcap and mcap-ros2-support.

​
Next

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.