https://github.com/selfpatch/ros2_medkit
ROS 2 Jazzy diagnostics and remote operations toolkit with SOVD style REST API. Runtime discovery, introspection, faults, secure access.
https://github.com/selfpatch/ros2_medkit
diagnostics edge fleet gateway introspection observability rbac remote-debugging rest-api robotics ros2 ros2-diagnostics ros2-medkit sovd
Last synced: about 1 month ago
JSON representation
ROS 2 Jazzy diagnostics and remote operations toolkit with SOVD style REST API. Runtime discovery, introspection, faults, secure access.
- Host: GitHub
- URL: https://github.com/selfpatch/ros2_medkit
- Owner: selfpatch
- License: apache-2.0
- Created: 2025-11-17T17:27:24.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-06T08:45:41.000Z (about 2 months ago)
- Last Synced: 2026-02-06T13:39:33.616Z (about 2 months ago)
- Topics: diagnostics, edge, fleet, gateway, introspection, observability, rbac, remote-debugging, rest-api, robotics, ros2, ros2-diagnostics, ros2-medkit, sovd
- Language: C++
- Homepage: https://selfpatch.github.io/ros2_medkit/
- Size: 5.73 MB
- Stars: 36
- Watchers: 3
- Forks: 2
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: docs/roadmap.rst
Awesome Lists containing this project
- Awesome-Embodied-Robotics-and-Agent - **ros2_medkit**
- awesome-weekly-robotics - ros2_medkit - Structured fault management for ROS 2 — persistent fault lifecycle, REST/SSE API, root cause correlation, and automatic rosbag capture on fault. Inspired by SOVD (Service-Oriented Vehicle Diagnostics), the ASAM standard that brings HTTP/REST diagnostics to automotive and robotics. Licence: Apache 2.0. (ROS / Libraries and Packages)
README
# ros2_medkit
[](https://github.com/selfpatch/ros2_medkit/actions/workflows/ci.yml)
[](https://codecov.io/gh/selfpatch/ros2_medkit)
[](https://selfpatch.github.io/ros2_medkit/)
[](LICENSE)
[](https://docs.ros.org/en/jazzy/)
[](https://discord.gg/6CXPMApAyq)
[](QUALITY_DECLARATION.md)
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):
```bash
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):
```bash
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](postman/).
## ✨ Features
- **🔍 Runtime Discovery** — Automatically discover what is actually running on your robot
- **🏗️ Entity Tree Model** — Organize diagnostics as Area → Component → Function → App
- **🔗 SOVD Compatible** — Align with Service-Oriented Vehicle Diagnostics standards
- **🌐 REST API Gateway** — HTTP interface for integration with external tools and UIs
- **📊 Health Modeling** — Track health state per entity for fleet-level observability
- **🔧 Easy Integration** — Works with existing ROS 2 Jazzy nodes out of the box
## 📖 Overview
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.
## 📋 Requirements
- **OS:** Ubuntu 24.04 LTS
- **ROS 2:** Jazzy Jalisco
- **Compiler:** GCC 13+ (C++17 support)
- **Build System:** colcon + ament_cmake
## 📚 Documentation
- 📖 [Full Documentation](https://selfpatch.github.io/ros2_medkit/)
- 🗺️ [Roadmap](https://selfpatch.github.io/ros2_medkit/roadmap.html)
- 📋 [GitHub Milestones](https://github.com/selfpatch/ros2_medkit/milestones)
## 💬 Community
We'd love to have you join our community!
- **💬 Discord** — [Join our server](https://discord.gg/6CXPMApAyq) for discussions, help, and announcements
- **🐛 Issues** — [Report bugs or request features](https://github.com/selfpatch/ros2_medkit/issues)
- **💡 Discussions** — [GitHub Discussions](https://github.com/selfpatch/ros2_medkit/discussions) for Q&A and ideas
---
## 🛠️ Development
This section is for contributors and developers who want to build and test ros2_medkit locally.
### Pre-commit Hooks
This project uses [pre-commit](https://pre-commit.com/) to automatically run
`clang-format`, `flake8`, and other checks on staged files before each commit.
```bash
pip install pre-commit
pre-commit install
```
To run all hooks against every file (useful after first setup):
```bash
pre-commit run --all-files
```
### Installing Dependencies
```bash
rosdep install --from-paths src --ignore-src -r -y
```
### Building
```bash
colcon build --symlink-install
```
### Testing
Run all tests:
```bash
source install/setup.bash
colcon test
colcon test-result --verbose
```
Run linters:
```bash
source install/setup.bash
colcon test --ctest-args -L linters
colcon test-result --verbose
```
Run only unit tests (everything except integration):
```bash
source install/setup.bash
colcon test --ctest-args -E test_integration
colcon test-result --verbose
```
Run only integration tests:
```bash
source install/setup.bash
colcon test --ctest-args -R test_integration
colcon test-result --verbose
```
### Code Coverage
To generate code coverage reports locally:
1. Build with coverage flags enabled:
```bash
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON
```
2. Run tests:
```bash
source install/setup.bash
colcon test --ctest-args -LE linter
```
3. Generate coverage report:
```bash
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
```
4. (Optional) Generate HTML report:
```bash
genhtml coverage.info --output-directory coverage_html
```
Then open `coverage_html/index.html` in your browser.
### CI/CD
All pull requests and pushes to main are automatically built and tested using GitHub Actions.
The CI workflow runs on Ubuntu 24.04 with ROS 2 Jazzy and consists of two parallel jobs:
**build-and-test:**
- Code linting and formatting checks (clang-format, clang-tidy)
- Unit tests and integration tests with demo automotive nodes
**coverage:**
- 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.
---
## 🤝 Contributing
Contributions are welcome! Whether it's bug reports, feature requests, documentation improvements, or code contributions — we appreciate your help.
1. Read our [Contributing Guidelines](CONTRIBUTING.md)
2. Check out [good first issues](https://github.com/selfpatch/ros2_medkit/labels/good%20first%20issue) for beginners
3. Follow our [Code of Conduct](CODE_OF_CONDUCT.md)
## 🔒 Security
If you discover a security vulnerability, please follow the responsible disclosure process in [SECURITY.md](SECURITY.md).
## 📄 License
This project is licensed under the **Apache License 2.0** — see the [LICENSE](LICENSE) file for details.
---
Made with ❤️ by the selfpatch community
💬 Join us on Discord