ros2_medkit

A structured diagnostic model for ROS 2 robots, over REST.
Drop it next to the stack you already run - no code changes - and a failure that ROS 2 diagnostics leaves as a log line becomes one structured fault: a fault code on a SOVD entity tree, with lifecycle, history, and the state captured at the moment it happened.

Drop it into the stack you already run

Nav2: a navigation goal that quietly aborts

You run Nav2. A NavigateToPose goal aborts - the planner gives up, the robot is wedged in a corner - and the only trace is a line buried in a log you would have to SSH in to read.

Start ros2_medkit next to it (no changes to Nav2). The aborted goal becomes a fault:

curl http://localhost:8080/api/v1/apps/bt_navigator/faults
# → ACTION_NAVIGATE_TO_POSE_ABORTED  severity=ERROR  source=/bt_navigator  status=CONFIRMED
#   + a black-box rosbag of the seconds around the failure

It works because an aborted action goal is often the only failure signal Nav2 emits, and ros2_medkit’s action bridge turns that into a structured fault on the bt_navigator entity - no instrumentation, no callbacks added to Nav2.

[!TIP] Nothing was added to Nav2. The bridge reads the action status your stack already publishes, so the same trick works for any action server - MoveIt, Nav2, or your own nodes.

Two ways to feed it:

• Native, for code you own - report faults directly with the FaultReporter client. This is the richest path (your own codes, severities and context) and the canonical way for new code; see the integration tutorial.
• Drop-in bridges, for the stack you will not rewrite - most real robots run huge existing projects nobody is going to retrofit with diagnostics. Point the bridges at what they already emit and you get structured faults (and states) in minutes, zero code changes: /diagnostics, /rosout logs, aborted actions.

So you get a remote, queryable, time-traveled fault instead of a log line - whether or not you touch the node’s code.

Run it in 5 minutes

One command. No code changes, no config. Point a container at your already-running robot - it ships the gateway, the fault manager and the drop-in bridges, and speaks whatever DDS your stack speaks (Fast DDS and CycloneDDS are both baked in):

docker run --rm --network host --ipc host \
  -e ROS_DOMAIN_ID="${ROS_DOMAIN_ID:-0}" \
  -e RMW_IMPLEMENTATION="${RMW_IMPLEMENTATION:-rmw_fastrtps_cpp}" \
  ghcr.io/selfpatch/ros2_medkit-jazzy:latest \
  ros2 launch ros2_medkit_gateway bringup.launch.py
# → REST API live at http://localhost:8080/api/v1/

Swap jazzy for humble/lyrical; the two -e flags forward your shell’s ROS_DOMAIN_ID and RMW_IMPLEMENTATION (falling back to domain 0 / Fast DDS if unset) so the container joins the same DDS graph as your robot. The packages are heading into the ROS index, so once your distro picks them up it is a plain apt install too:

sudo apt install ros-jazzy-ros2-medkit-gateway   # or ros-humble- / ros-lyrical-
ros2 launch ros2_medkit_gateway bringup.launch.py

File truncated at 100 lines see the full file

Contributing to ros2_medkit

Thanks for your interest in contributing to ros2_medkit! This guide explains how to report issues, suggest features, and contribute code.

How to Report Issues

Did you find a bug?

• Ensure the bug was not already reported by searching Issues
• If you can’t find an existing issue, open a new one and select the Bug report template
• Fill in all sections of the template:
  • Steps to reproduce - numbered steps to recreate the issue
  • Expected behavior - what you expected to happen
  • Actual behavior - what actually happened, including error messages or stack traces
  • Environment - ros2_medkit version, ROS 2 distro, OS
  • Additional information - logs, snippets, or screenshots if helpful

Do you want to suggest a feature or improvement?

• Check if the feature has already been suggested in Issues
• If not, open a new issue and select the Feature request / General issue template
• Fill in all sections:
  • Proposal - describe the change or feature you’d like to see
  • Motivation - why is this important? Who does it benefit?
  • Alternatives considered - other options or implementations you considered
  • Additional context - any other context or screenshots

How to Contribute Code

Development Workflow

1. Fork the repository and clone your fork locally
2. Install pre-commit hooks (one-time setup):

   pip install pre-commit
   pre-commit install
   

1. Create a branch from main with a descriptive name:
   • feature/short-description for new features
   • fix/short-description for bug fixes
   • docs/short-description for documentation changes
2. Make your changes following the project’s coding standards
3. Test your changes locally (see Build and Test section below)
4. Commit your changes with clear, descriptive commit messages
   • Pre-commit hooks will automatically check formatting
5. Push your branch to your fork
6. Open a Pull Request against the main branch of this repository

Commit Messages

• Use clear and descriptive commit messages
• Start with a verb in imperative mood (e.g., “Add”, “Fix”, “Update”, “Remove”)
• Keep the first line under 72 characters
• Add a blank line followed by a more detailed explanation if needed

Examples:

Add support for SOVD entity mapping

Fix memory leak in diagnostic tree traversal

Update documentation for colcon build process

Build and Test

Before opening or updating a Pull Request, you must build and test locally:

source /opt/ros/jazzy/setup.bash   # or humble - adjust for your distro
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install && source install/setup.bash

Use scripts/test.sh for testing (preferred over raw colcon commands):

./scripts/test.sh              # Unit tests only (default)
./scripts/test.sh integ        # Integration tests only
./scripts/test.sh lint         # Fast linters (no clang-tidy)
./scripts/test.sh all          # Everything
./scripts/test.sh <test_name>  # Single test by CTest name regex

Pre-commit and Pre-push Hooks

pipx install pre-commit
pre-commit install
pre-commit install --hook-type pre-push

On commit: clang-format, cmake-lint, shellcheck, flake8, ament-copyright, trailing whitespace. On push: incremental clang-tidy on changed .cpp files.

Code Coverage

```bash colcon build –cmake-args -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON ./scripts/test.sh # run tests

File truncated at 100 lines see the full file