selfpatch_demos

Demonstration projects showcasing ros2_medkit integration with real ROS 2 systems.

Overview

This repository contains example integrations and demos that show how ros2_medkit can be used to add SOVD-compliant diagnostics and fault management to ROS 2-based robots and systems.

Each demo builds on real-world scenarios, progressing from simple sensor monitoring to complete mobile robot integration:

• Sensor Diagnostics — Lightweight demo focusing on data monitoring and fault injection
• TurtleBot3 Integration — Full-featured demo with Nav2 navigation, showing entity hierarchy and real-time control
• MoveIt Pick-and-Place — Panda 7-DOF arm manipulation with MoveIt 2, fault monitoring for planning, controllers, and joint limits

Key Capabilities Demonstrated:

• ✅ SOVD-compliant REST API (Areas → Components → Apps → Functions)
• ✅ Real-time data access (topics via HTTP)
• ✅ Configuration management (ROS 2 parameters via HTTP)
• ✅ Operation execution (services and actions via HTTP)
• ✅ Fault management and injection
• ✅ Manifest-based entity discovery
• ✅ Legacy diagnostics bridge support

Both demos support:

• REST API access via SOVD protocol
• Web UI for visualization (sovd_web_ui)
• Fault injection and monitoring
• Docker deployment for easy setup

Demos

Demo	Description	Features	Status
Sensor Diagnostics	Lightweight sensor diagnostics demo (no Gazebo required)	Data monitoring, fault injection, dual fault reporting paths	✅ Ready
TurtleBot3 Integration	Full ros2_medkit integration with TurtleBot3 and Nav2	SOVD-compliant API, manifest-based discovery, fault management	✅ Ready
MoveIt Pick-and-Place	Panda 7-DOF arm with MoveIt 2 manipulation and ros2_medkit	Planning fault detection, controller monitoring, joint limits	✅ Ready

Quick Start

Sensor Diagnostics Demo (Fastest - No GPU Required)

The sensor diagnostics demo is the fastest way to try ros2_medkit:

cd demos/sensor_diagnostics
./run-demo.sh
# Docker services start in daemon mode
# Web UI available at http://localhost:3000

# Explore the API
./check-demo.sh

Options:

./run-demo.sh --attached      # Run in foreground with logs
./check-demo.sh               # Interactive API demonstration
./stop-demo.sh                # Stop the demo

Features:

• Simulated sensors (LiDAR, IMU, GPS, Camera)
• Configurable fault injection via REST API
• Dual fault reporting paths (legacy + modern)
• Runs anywhere (CI, Codespaces, laptop)

TurtleBot3 + Nav2 Demo (Full Navigation Stack)

Full mobile robot demo with autonomous navigation:

cd demos/turtlebot3_integration
./run-demo.sh
# Gazebo will open, Web UI at http://localhost:3000
# Try: ./send-nav-goal.sh 2.0 0.5

# To stop
./stop-demo.sh

Features:

• Complete TurtleBot3 simulation in Gazebo
• Nav2 navigation stack integration
• SOVD-compliant REST API with entity hierarchy
• Manifest-based discovery (Areas → Components → Apps → Functions)
• Fault injection scenarios for Nav2 components
• Real-time robot control via HTTP

MoveIt 2 Pick-and-Place Demo (Manipulation Stack)

Panda robot arm demo with pick-and-place manipulation:

cd demos/moveit_pick_place
./run-demo.sh
# RViz will open with Panda arm (or use --headless), Web UI at http://localhost:3000
# Move the arm: ./move-arm.sh demo
# Inject faults: ./inject-planning-failure.sh
# Check faults: ./check-faults.sh

# To stop
./stop-demo.sh

Features:

• Panda 7-DOF arm with MoveIt 2 and mock hardware (no physics sim)
• Interactive arm control via move-arm.sh
• Continuous pick-and-place task loop
• Manipulation fault monitoring (planning, controller, joint limits)
• 5 fault injection scenarios with one-click scripts
• SOVD-compliant REST API with rich entity hierarchy (4 areas, 7 components)

Getting Started

Prerequisites

• ROS 2 Jazzy (Ubuntu 24.04)
• Docker and docker-compose (recommended)
• ros2_medkit >= 1.0.0

Clone the Repository

git clone https://github.com/selfpatch/selfpatch_demos.git
cd selfpatch_demos

Run a Demo

Each demo has its own README with specific instructions. See above Quick Start, or follow the detailed README in each demo directory:

cd demos/sensor_diagnostics  # or turtlebot3_integration
# Follow the README.md in that directory

Example API Usage

All demos expose a SOVD-compliant REST API. Here are some common operations:

# Check gateway health
curl http://localhost:8080/api/v1/health

# List all apps (ROS 2 nodes)
curl http://localhost:8080/api/v1/apps | jq '.items[] | {id, name}'

# Get sensor data
curl http://localhost:8080/api/v1/apps/lidar_sim/data/scan | jq

# Update configuration
curl -X PUT http://localhost:8080/api/v1/apps/lidar_sim/configurations/noise_stddev \
  -H "Content-Type: application/json" \
  -d '{"value": 0.5}'

# List active faults
curl http://localhost:8080/api/v1/faults | jq

See individual demo READMEs for more examples.

Testing

Each demo has automated smoke tests that verify the gateway starts and the REST API works correctly:

# Run smoke tests against a running demo (default: http://localhost:8080)
./tests/smoke_test.sh              # Sensor diagnostics (21 tests, incl. fault injection)
./tests/smoke_test_turtlebot3.sh   # TurtleBot3 (entity discovery)
./tests/smoke_test_moveit.sh       # MoveIt pick-and-place (entity discovery)

CI runs all 3 demos in parallel - each job builds the Docker image, starts the container, and runs the smoke tests against it. See CI workflow.

Related Projects

• ros2_medkit — Core diagnostics library with SOVD-compliant gateway
• sovd_web_ui — Web-based visualization and control interface
• ros2_medkit_mcp — MCP server for LLM integration
• ros2_medkit documentation — Full documentation and API reference

Contributing

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