Skip to content

Commit 8014283

Browse files
bburdabburda
committed
feat(turtlebot3): Complete demo with manifest discovery, fault management and GUI as default
Major improvements to TurtleBot3 integration demo: Core Features: - Add manifest-based entity discovery (SOVD hierarchy: Areas→Components→Apps→Functions) - Implement fault management via diagnostic_bridge + fault_manager - Add SQLite storage for persistent fault tracking - Support conditional headless/GUI Gazebo modes Docker & Launch: - Fix Dockerfile: add ros2_medkit_fault_manager, fault_reporter, diagnostic_bridge packages - Add SQLite dependencies (sqlite3, libsqlite3-dev) - Update launch file: conditional Gazebo launch based on headless argument - Change default mode from headless to GUI for better UX - Add HEADLESS environment variable support in docker-compose.yml Manifest & Configuration: - Add turtlebot3_manifest.yaml defining complete entity hierarchy - Configure 4 areas: robot, navigation, diagnostics, bridge - Define 6 components: turtlebot3-base, lidar-sensor, nav2-stack, gateway, fault-manager, diagnostic-bridge-unit - Define 11 apps with ROS node bindings and dependencies - Define 3 functions: autonomous-navigation, robot-control, fault-management Shell Scripts: - Fix all app IDs: underscore format → hyphen format (bt_navigator → bt-navigator, etc.) - Add check-entities.sh: explore SOVD entity hierarchy - Add check-faults.sh: view active faults - Add inject-nav-failure.sh: trigger unreachable goal scenario - Add inject-localization-failure.sh: reset AMCL with high uncertainty - Add inject-controller-failure.sh: set restrictive velocity limits - Add inject-collision.sh: navigate toward obstacles - Add restore-normal.sh: restore defaults and clear faults - Update send-nav-goal.sh: use SOVD API instead of docker exec Documentation: - Completely rewrite TurtleBot3 demo README with: * Clear GUI vs headless mode instructions * SOVD entity hierarchy explanation * Fault management architecture diagram * Fault injection scenarios table * Complete REST API examples for all endpoints * Scripts reference table Testing: - All scripts verified working with GATEWAY_URL=http://172.19.0.2:8080 - Navigation goals successfully executed via SOVD API - Fault injection scenarios tested - 23 components discovered, 0 initial faults confirmed - GUI and headless modes both tested and working
1 parent c41c211 commit 8014283

16 files changed

Lines changed: 1091 additions & 120 deletions

‎README.md‎

Lines changed: 91 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -8,19 +8,41 @@ with real ROS 2 systems.
88
## Overview
99

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

13-
Each demo builds on real-world scenarios, starting from basic integration and
14-
progressing toward more advanced use cases.
13+
Each demo builds on real-world scenarios, progressing from simple sensor monitoring
14+
to complete mobile robot integration:
15+
16+
- **Sensor Diagnostics** — Lightweight demo focusing on data monitoring and fault injection
17+
- **TurtleBot3 Integration** — Full-featured demo with Nav2 navigation, showing entity hierarchy and real-time control
18+
19+
**Key Capabilities Demonstrated:**
20+
21+
- ✅ SOVD-compliant REST API (Areas → Components → Apps → Functions)
22+
- ✅ Real-time data access (topics via HTTP)
23+
- ✅ Configuration management (ROS 2 parameters via HTTP)
24+
- ✅ Operation execution (services and actions via HTTP)
25+
- ✅ Fault management and injection
26+
- ✅ Manifest-based entity discovery
27+
- ✅ Legacy diagnostics bridge support
28+
29+
Both demos support:
30+
31+
- REST API access via SOVD protocol
32+
- Web UI for visualization ([sovd_web_ui](https://github.com/selfpatch/sovd_web_ui))
33+
- Fault injection and monitoring
34+
- Docker deployment for easy setup
1535

1636
## Demos
1737

18-
| Demo | Description | Status |
19-
|------|-------------|--------|
20-
| [Sensor Diagnostics](demos/sensor_diagnostics/) | Lightweight sensor diagnostics demo (no Gazebo required) | ✅ Ready |
21-
| [TurtleBot3 Integration](demos/turtlebot3_integration/) | Full ros2_medkit integration with TurtleBot3 and Nav2 | 🚧 In Progress |
38+
| Demo | Description | Features | Status |
39+
|------|-------------|----------|--------|
40+
| [Sensor Diagnostics](demos/sensor_diagnostics/) | Lightweight sensor diagnostics demo (no Gazebo required) | Data monitoring, fault injection, dual fault reporting paths | ✅ Ready |
41+
| [TurtleBot3 Integration](demos/turtlebot3_integration/) | Full ros2_medkit integration with TurtleBot3 and Nav2 | SOVD-compliant API, manifest-based discovery, fault management | ✅ Ready |
42+
43+
### Quick Start
2244

23-
### Quick Start (Sensor Diagnostics)
45+
#### Sensor Diagnostics Demo (Fastest - No GPU Required)
2446

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

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

56+
**Features:**
57+
58+
- Simulated sensors (LiDAR, IMU, GPS, Camera)
59+
- Configurable fault injection via REST API
60+
- Dual fault reporting paths (legacy + modern)
61+
- Runs anywhere (CI, Codespaces, laptop)
62+
63+
#### TurtleBot3 + Nav2 Demo (Full Navigation Stack)
64+
65+
Full mobile robot demo with autonomous navigation:
66+
67+
```bash
68+
cd demos/turtlebot3_integration
69+
./run-demo.sh
70+
# Gazebo will open, Web UI at http://localhost:3000
71+
# Try: ./send-nav-goal.sh 2.0 0.5
72+
```
73+
74+
**Features:**
75+
76+
- Complete TurtleBot3 simulation in Gazebo
77+
- Nav2 navigation stack integration
78+
- SOVD-compliant REST API with entity hierarchy
79+
- Manifest-based discovery (Areas → Components → Apps → Functions)
80+
- Fault injection scenarios for Nav2 components
81+
- Real-time robot control via HTTP
82+
3483
## Getting Started
3584

3685
### Prerequisites
3786

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

4191
### Clone the Repository
4292

@@ -47,16 +97,44 @@ cd selfpatch_demos
4797

4898
### Run a Demo
4999

50-
Each demo has its own README with specific instructions. Start with:
100+
Each demo has its own README with specific instructions. See above Quick Start,
101+
or follow the detailed README in each demo directory:
51102

52103
```bash
53-
cd demos/turtlebot3_integration
104+
cd demos/sensor_diagnostics # or turtlebot3_integration
54105
# Follow the README.md in that directory
55106
```
56107

108+
## Example API Usage
109+
110+
All demos expose a SOVD-compliant REST API. Here are some common operations:
111+
112+
```bash
113+
# Check gateway health
114+
curl http://localhost:8080/api/v1/health
115+
116+
# List all apps (ROS 2 nodes)
117+
curl http://localhost:8080/api/v1/apps | jq '.items[] | {id, name}'
118+
119+
# Get sensor data
120+
curl http://localhost:8080/api/v1/apps/lidar_sim/data/scan | jq
121+
122+
# Update configuration
123+
curl -X PUT http://localhost:8080/api/v1/apps/lidar_sim/configurations/noise_stddev \
124+
-H "Content-Type: application/json" \
125+
-d '{"value": 0.5}'
126+
127+
# List active faults
128+
curl http://localhost:8080/api/v1/faults | jq
129+
```
130+
131+
See individual demo READMEs for more examples.
132+
57133
## Related Projects
58134

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

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

72150
## License
73151

74-
This project is licensed under the Apache License 2.0. See the [`LICENSE`](LICENSE) file for details.
152+
This project is licensed under the Apache License 2.0. See the [`LICENSE`](LICENSE) file for details.

‎demos/turtlebot3_integration/Dockerfile‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ RUN apt-get update && apt-get install -y \
3737
python3-requests \
3838
nlohmann-json3-dev \
3939
libcpp-httplib-dev \
40+
sqlite3 \
41+
libsqlite3-dev \
4042
git \
4143
curl \
4244
&& rm -rf /var/lib/apt/lists/*
@@ -47,6 +49,9 @@ RUN git clone --depth 1 --recurse-submodules https://github.com/selfpatch/ros2_m
4749
mv ros2_medkit/src/ros2_medkit_gateway \
4850
ros2_medkit/src/ros2_medkit_msgs \
4951
ros2_medkit/src/ros2_medkit_serialization \
52+
ros2_medkit/src/ros2_medkit_fault_manager \
53+
ros2_medkit/src/ros2_medkit_fault_reporter \
54+
ros2_medkit/src/ros2_medkit_diagnostic_bridge \
5055
ros2_medkit/src/dynamic_message_introspection . && \
5156
rm -rf ros2_medkit
5257

0 commit comments

Comments
 (0)