Skip to content

feat(turtlebot3): Complete demo with manifest discovery, fault management and GUI as default #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bburda wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(turtlebot3): Complete demo with manifest discovery, fault management and GUI as default #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 91 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,41 @@ with real ROS 2 systems.
## Overview

This repository contains example integrations and demos that show how ros2_medkit
can be used to add modern diagnostics to ROS 2-based robots and systems.
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, starting from basic integration and
progressing toward more advanced use cases.
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

**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](https://github.com/selfpatch/sovd_web_ui))
- Fault injection and monitoring
- Docker deployment for easy setup

## Demos

| Demo | Description | Status |
|------|-------------|--------|
| [Sensor Diagnostics](demos/sensor_diagnostics/) | Lightweight sensor diagnostics demo (no Gazebo required) | ✅ Ready |
| [TurtleBot3 Integration](demos/turtlebot3_integration/) | Full ros2_medkit integration with TurtleBot3 and Nav2 | 🚧 In Progress |
| Demo | Description | Features | Status |
|------|-------------|----------|--------|
| [Sensor Diagnostics](demos/sensor_diagnostics/) | Lightweight sensor diagnostics demo (no Gazebo required) | Data monitoring, fault injection, dual fault reporting paths | ✅ Ready |
| [TurtleBot3 Integration](demos/turtlebot3_integration/) | Full ros2_medkit integration with TurtleBot3 and Nav2 | SOVD-compliant API, manifest-based discovery, fault management | ✅ Ready |

### Quick Start

### Quick Start (Sensor Diagnostics)
#### Sensor Diagnostics Demo (Fastest - No GPU Required)

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

Expand All @@ -31,12 +53,40 @@ docker compose up
# Run ./run-demo.sh for an interactive walkthrough
```

**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:

```bash
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
```

**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

## Getting Started

### Prerequisites

- ROS 2 Jazzy (Ubuntu 24.04)
- [ros2_medkit](https://github.com/selfpatch/ros2_medkit) installed
- Docker and docker-compose (recommended)
- [ros2_medkit](https://github.com/selfpatch/ros2_medkit) >= 1.0.0

### Clone the Repository

Expand All @@ -47,16 +97,44 @@ cd selfpatch_demos

### Run a Demo

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

```bash
cd demos/turtlebot3_integration
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:

```bash
# 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.

## Related Projects

- [ros2_medkit](https://github.com/selfpatch/ros2_medkit) — The core diagnostics library
- [ros2_medkit](https://github.com/selfpatch/ros2_medkit) — Core diagnostics library with SOVD-compliant gateway
- [sovd_web_ui](https://github.com/selfpatch/sovd_web_ui) — Web-based visualization and control interface
- [ros2_medkit_mcp](https://github.com/selfpatch/ros2_medkit_mcp) — MCP server for LLM integration
- [ros2_medkit documentation](https://selfpatch.github.io/ros2_medkit/) — Full documentation and API reference

## Contributing
Expand All @@ -71,4 +149,4 @@ If you discover a security vulnerability, please follow the process in [`SECURIT

## License

This project is licensed under the Apache License 2.0. See the [`LICENSE`](LICENSE) file for details.
This project is licensed under the Apache License 2.0. See the [`LICENSE`](LICENSE) file for details.
5 changes: 5 additions & 0 deletions demos/turtlebot3_integration/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ RUN apt-get update && apt-get install -y \
python3-requests \
nlohmann-json3-dev \
libcpp-httplib-dev \
sqlite3 \
libsqlite3-dev \
git \
curl \
&& rm -rf /var/lib/apt/lists/*
Expand All @@ -47,6 +49,9 @@ RUN git clone --depth 1 --recurse-submodules https://github.com/selfpatch/ros2_m
mv ros2_medkit/src/ros2_medkit_gateway \
ros2_medkit/src/ros2_medkit_msgs \
ros2_medkit/src/ros2_medkit_serialization \
ros2_medkit/src/ros2_medkit_fault_manager \
Copy link

@mfaferek93 mfaferek93 Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since we're cloning from the main branch with --depth 1, builds might break if the upstream repo changes. Maybe worth pinning to a specific commit or tag for reproducibility?

Copy link
Contributor Author

@bburda bburda Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We’re cloning these packages only because they haven’t been deployed to the ROS Index yet.
For now, I suggest we leave this as-is and open a follow-up issue to replace all git clone/mv steps for ros2_medkit packages with a simple rosdep install driven by package.xml.

ros2_medkit/src/ros2_medkit_fault_reporter \
ros2_medkit/src/ros2_medkit_diagnostic_bridge \
ros2_medkit/src/dynamic_message_introspection . && \
rm -rf ros2_medkit

Expand Down
Loading
Loading