ros2_medkit

Modern, SOVD-compatible diagnostics for ROS 2 robots — built around an entity tree (Area / Component / Function / App) for runtime discovery, health modeling, and troubleshooting.

---

✨ 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 provides modern diagnostics for ROS 2–based systems.

Instead of hardcoding knowledge about every node, topic, or ECU, 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

The goal is to make this tree compatible with the SOVD (Service-Oriented Vehicle Diagnostics) model, so the same concepts can be used across robots, vehicles, and other embedded systems.

📋 Requirements

• OS: Ubuntu 24.04 LTS
• ROS 2: Jazzy Jalisco
• Compiler: GCC 13+ (C++17 support)
• Build System: colcon + ament_cmake

🚀 Quick Start

1. Clone and Install Dependencies

mkdir -p ~/ros2_medkit_ws/src
cd ~/ros2_medkit_ws/src
git clone --recurse-submodules https://github.com/selfpatch/ros2_medkit.git
cd ~/ros2_medkit_ws
rosdep install --from-paths src --ignore-src -r -y

Note: If you cloned without --recurse-submodules, run: git submodule update --init --recursive

2. Build

colcon build --symlink-install
source install/setup.bash

3. Launch the Gateway

ros2 launch ros2_medkit_gateway gateway.launch.py

4. Explore the API

Open your browser at http://localhost:8080/api/v1/areas or use curl:

curl http://localhost:8080/api/v1/areas

For more examples, see our Postman collection.

📚 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
• 🐛 Issues — Report bugs or request features
• 💡 Discussions — GitHub Discussions for Q&A and ideas

---

🛠️ Development

This section is for contributors and developers who want to build and test ros2_medkit locally.

Installing Dependencies

rosdep install --from-paths src --ignore-src -r -y

Building

colcon build --symlink-install

Testing

Run all tests:

source install/setup.bash
colcon test
colcon test-result --verbose

Run linters:

source install/setup.bash
colcon test --ctest-args -L linters
colcon test-result --verbose

Run only unit tests (everything except integration):

source install/setup.bash
colcon test --ctest-args -E test_integration
colcon test-result --verbose

Run only integration tests:

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:

colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON

2. Run tests:

source install/setup.bash
colcon test --ctest-args -LE linter

3. 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

4. (Optional) Generate HTML report:

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
2. Check out good first issues for beginners
3. Follow our Code of Conduct

🔒 Security

If you discover a security vulnerability, please follow the responsible disclosure process in SECURITY.md.

📄 License

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