ros2_medkit

Structured diagnostics for ROS 2 robots.
When your robot fails, find out why - in minutes, not hours.

Fault management · Live introspection · REST API · AI via MCP

The problem

When a robot breaks in the field, you SSH in, run ros2 node list, grep through logs, and try to reconstruct what happened. It works for one robot on your desk. It does not work for 20 robots at a customer site, at 2 AM, when you cannot reproduce the issue.

ros2_medkit gives your ROS 2 system a diagnostic REST API so you can inspect what is running, what failed, and why, without SSH and without custom tooling.

🚀 Quick Start

Try the full demo (requires Docker with Compose, no ROS 2 needed):

git clone https://github.com/selfpatch/selfpatch_demos.git
cd selfpatch_demos/demos/turtlebot3_integration
./run-demo.sh
# → API: http://localhost:8080/api/v1/  Web UI: http://localhost:3000

Open http://localhost:3000 in your browser. You will see a TurtleBot3 with Nav2, organized into a browsable entity tree with live faults, topic data, and parameter access.

Build from source (ROS 2 Jazzy, Humble, or Rolling):

source /opt/ros/jazzy/setup.bash   # or humble - adjust for your distro
git clone --recurse-submodules https://github.com/selfpatch/ros2_medkit.git
cd ros2_medkit
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install && source install/setup.bash
ros2 launch ros2_medkit_gateway gateway.launch.py
# → http://localhost:8080/api/v1/health

Verify it works: curl http://localhost:8080/api/v1/health should return {"status": "healthy", ...}.

For a guided walkthrough with demo nodes and the full API, see the Getting Started tutorial. For API examples, see our Postman collection.

Experimental: Pixi

Pixi provides a reproducible, lockfile-based environment without requiring a system-wide ROS 2 installation (Linux x86_64 only). This is experimental; the standard ROS 2 toolchain (rosdep + colcon) remains the primary method.

curl -fsSL https://pixi.sh/install.sh | bash
pixi install -e jazzy     # or: pixi install -e humble
pixi run -e jazzy build
pixi run -e jazzy test
pixi run -e jazzy smoke   # verify gateway starts

See installation docs for details. Feedback welcome on #265.

What you get

Start here: Faults. Your robot has 47 nodes. Something throws an error. Instead of grepping logs, you query GET /api/v1/faults and get a structured list with fault codes, timestamps, affected entities, environment snapshots, and history. Clear faults, subscribe to new ones via SSE, correlate them across components.

Beyond faults, medkit exposes the full ROS 2 graph through REST:

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