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.

What is ros2_medkit?

ros2_medkit is an experiment in 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:

• Area – physical or logical domain (e.g. base, arm, safety, navigation)
• Component – hardware or software component within an area
• Function – capability provided by one or more components
• 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.

Status

Early prototype / work in progress

This is an open source project exploring diagnostic patterns for ROS 2. APIs, architecture, and naming may change as the project evolves.

See the Roadmap for planned milestones, or check GitHub Milestones for current progress.

Target Use Cases

• Runtime discovery of what is actually running on the robot
• Health state modeled per Area / Component / Function / App
• Better remote troubleshooting and fleet-level observability for ROS 2 robots

Development

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 and early feedback are welcome! Please read CONTRIBUTING.md for guidelines.

By contributing, you agree to follow the CODE_OF_CONDUCT.md.

Security

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

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.