ros2_medkit gives your ROS 2 robot a diagnostics REST API. It finds every node, topic, service and action by itself, and turns failures - error logs, failed actions, /diagnostics - into clear faults: what broke, where, how bad, with a snapshot and a rosbag of the moment it happened. No changes to your code.

Quick start

1. Get Docker, if you don’t have it yet.

2. While your robot is running, start ros2_medkit on its computer:

   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
   

On Humble or Lyrical, change jazzy to humble or lyrical.

1. See what it found:

   curl localhost:8080/api/v1/apps     # every node on your robot
   curl localhost:8080/api/v1/faults   # everything that has failed
   

Or browse the whole API at localhost:8080/api/v1/docs.

[!TIP] That’s it. ros2_medkit is now watching your robot, and every new failure shows up as a fault.

No robot at hand? The sensor demo runs on any laptop and lets you break things on purpose (it needs curl and jq):

git clone https://github.com/selfpatch/selfpatch_demos.git
cd selfpatch_demos/demos/sensor_diagnostics
./run-demo.sh     # web UI on http://localhost:3000
./inject-nan.sh   # break a sensor, then watch the fault appear

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

Every run starts by dropping the result files of the previous one, so the summary it prints is the tally of the run you just started and not of everything tested since the last clean. colcon test-result counts any XML under build/ whose root element is <testsuite> or <testsuites>, whatever it is called, so the sweep asks colcon itself which files those are rather than matching a name. Run it on its own with ./scripts/drop_stale_results.sh if you invoke colcon test directly.

Every run also reclaims shared memory left behind by DDS participants that were killed rather than shut down. The aggregation suites kill peers on purpose, and nothing gives those segments back: about 0.65 MB each, and a container’s /dev/shm is 64 MB by default, so they accumulate across runs until something unrelated fails for lack of space. The reclaiming is fastdds shm clean, the vendor’s own tool, which removes a segment only when no process holds its lock. Run it on its own with ./scripts/sweep_shm.sh; it refuses while ROS processes are alive, and --force overrides that.

Pre-commit and Pre-push Hooks

File truncated at 100 lines see the full file