ros2_medkit

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

Fault correlation · Black-box recording · REST API · AI via MCP

🚀 Quick Start

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

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

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

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/areas

For more examples, see our Postman collection.

✨ Features

📖 Overview

ros2_medkit models a robot as a diagnostic entity tree:

Compatible with the SOVD (Service-Oriented Vehicle Diagnostics) model — same concepts across robots, vehicles, and embedded systems.

📋 Requirements

• OS: Ubuntu 24.04 LTS (Jazzy / Rolling) or Ubuntu 22.04 LTS (Humble)
• ROS 2: Jazzy Jalisco, Humble Hawksbill, or Rolling (experimental)
• Compiler: GCC 11+ (C++17 support)
• Build System: colcon + ament_cmake

📚 Documentation

• 📖 Full Documentation
• 🗺️ Roadmap
• 📋 GitHub Milestones

💬 Community

We’d love to have you join our community!

• 💬 Discord — Join our server for discussions, help, and announcements

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 Requirements

Before opening or updating a Pull Request, you must:

1. Build the project successfully:

   colcon build
   

1. Run all tests:

   colcon test
   colcon test-result --verbose
   

1. Ensure all tests pass locally
2. Fix any build warnings or test failures

Pull Request Checklist

Before submitting your PR, ensure:

• Code follows the repository’s style and conventions
• Build succeeds without warnings
• All tests pass locally
• New tests are added for new functionality
• Existing tests are updated if behavior changes
• Documentation is updated where applicable
• PR description clearly explains what changed and why
• Related issue is referenced (e.g., “Fixes #123”)

Code Review Process

• The project maintainers will review pull requests as time permits
• Address review feedback promptly
• Keep discussions professional and constructive

File truncated at 100 lines see the full file