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
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:3000Build 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/areasFor more examples, see our Postman collection.
| Feature | Status | Description |
|---|---|---|
| 🔍 Discovery | Available | Automatically discover running nodes, topics, services, and actions |
| 📊 Data | Available | Read and write topic data via REST |
| ⚙️ Operations | Available | Call services and actions with execution tracking |
| 🔧 Configurations | Available | Read, write, and reset node parameters |
| 🚨 Faults | Available | Query, inspect, and clear faults with environment data and snapshots |
| 📦 Bulk Data | Available | Upload, download, and manage files (calibration, firmware, rosbags) |
| 📡 Subscriptions | Available | Stream live data and fault events via SSE |
| 🔄 Software Updates | Available | Async prepare/execute lifecycle with pluggable backends |
| 🔒 Authentication | Available | JWT-based RBAC (viewer, operator, configurator, admin) |
| 📋 Logs | Planned | Log sources, entries, and configuration |
| 🔁 Entity Lifecycle | Planned | Start, restart, shutdown control |
| 🔐 Modes & Locking | Planned | Target mode control and resource locking |
| 📝 Scripts | Planned | Diagnostic script upload and execution |
| 🧹 Clear Data | Planned | Clear cached and learned diagnostic data |
| 📞 Communication Logs | Planned | Protocol-level communication logging |
ros2_medkit models a robot as a diagnostic entity tree:
| Entity | Description | Example |
|---|---|---|
| Area | Physical or logical domain | base, arm, safety, navigation |
| Component | Hardware or software component within an area | motor_controller, lidar_driver |
| Function | Capability provided by one or more components | localization, obstacle_detection |
| App | Deployable software unit | node, container, process |
Compatible with the SOVD (Service-Oriented Vehicle Diagnostics) model — same concepts across robots, vehicles, and embedded systems.
- 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
We'd love to have you join our community!
- 💬 Discord — Join our server for discussions, help, and announcements
- 🐛 Issues — Report bugs or request features
- 💡 Discussions — GitHub Discussions for Q&A and ideas
This section is for contributors and developers who want to build and test ros2_medkit locally.
This project uses pre-commit to automatically run
clang-format, flake8, and other checks on staged files before each commit.
pip install pre-commit
pre-commit installTo run all hooks against every file (useful after first setup):
pre-commit run --all-filesrosdep install --from-paths src --ignore-src -r -ycolcon build --symlink-installRun all tests:
source install/setup.bash
colcon test
colcon test-result --verboseRun linters:
source install/setup.bash
colcon test --ctest-args -L linters
colcon test-result --verboseRun only unit tests (everything except integration):
source install/setup.bash
colcon test --ctest-args -E test_integration
colcon test-result --verboseRun only integration tests:
source install/setup.bash
colcon test --ctest-args -R test_integration
colcon test-result --verboseTo generate code coverage reports locally:
- Build with coverage flags enabled:
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON- Run tests:
source install/setup.bash
colcon test --ctest-args -LE linter- Generate coverage report:
lcov --capture --directory build --output-file coverage.raw.info --ignore-errors mismatch,negative
lcov --extract coverage.raw.info '*/ros2_medkit/src/*/src/*' '*/ros2_medkit/src/*/include/*' --output-file coverage.info --ignore-errors unused
lcov --list coverage.info- (Optional) Generate HTML report:
genhtml coverage.info --output-directory coverage_htmlThen open coverage_html/index.html in your browser.
All pull requests and pushes to main are automatically built and tested using GitHub Actions. The CI workflow runs a build matrix across ROS 2 Jazzy (Ubuntu 24.04), ROS 2 Humble (Ubuntu 22.04), and ROS 2 Rolling (Ubuntu 24.04, allow-failure) and consists of the following jobs:
build-and-test (matrix: Jazzy + Humble + Rolling):
- Full build and unit/integration tests on all distros
- Rolling jobs are allowed to fail (best-effort forward-compatibility)
- Code linting and formatting checks (clang-format, clang-tidy) — Jazzy only
coverage (Jazzy only):
- Builds with coverage instrumentation (Debug mode)
- Runs unit tests only (for stable coverage metrics)
- Generates lcov coverage report (available as artifact)
- Uploads coverage to Codecov (only on push to main)
After every run the workflow uploads test results and coverage reports as artifacts for debugging and review.
Contributions are welcome! Whether it's bug reports, feature requests, documentation improvements, or code contributions — we appreciate your help.
- Read our Contributing Guidelines
- Check out good first issues for beginners
- Follow our Code of Conduct
If you discover a security vulnerability, please follow the responsible disclosure process in SECURITY.md.
This project is licensed under the Apache License 2.0 — see the LICENSE file for details.
Made with ❤️ by the selfpatch community
💬 Join us on Discord