ros2_medkit_gateway

HTTP gateway node for the ros2_medkit diagnostics system.

Overview

The ROS 2 Medkit Gateway exposes ROS 2 system information and data through a RESTful HTTP API. It automatically discovers nodes in the ROS 2 system, organizes them into areas based on their namespaces, and provides endpoints to query and interact with them.

Key Features:

• Auto-discovery: Automatically detects ROS 2 nodes and topics
• Area-based organization: Groups nodes by namespace (e.g., /powertrain, /chassis, /body)
• REST API: Standard HTTP/JSON interface
• Real-time updates: Configurable cache refresh for up-to-date system state
• Bulk Data Management: Upload, download, list, and delete bulk data files (calibration, firmware, etc.)

Endpoints

All endpoints are prefixed with /api/v1 for API versioning.

Discovery Endpoints

• GET /api/v1/health - Health check endpoint (returns healthy status)
• GET /api/v1/ - Gateway status and version information
• GET /api/v1/version-info - SOVD version info (supported SOVD versions and base URIs)
• GET /api/v1/areas - List all discovered areas (powertrain, chassis, body, root)
• GET /api/v1/areas/{area_id} - Get area capabilities
• GET /api/v1/areas/{area_id}/subareas - List sub-areas within an area
• GET /api/v1/areas/{area_id}/contains - List components contained in an area
• GET /api/v1/components - List all discovered components across all areas
• GET /api/v1/components/{component_id} - Get component capabilities
• GET /api/v1/components/{component_id}/subcomponents - List sub-components
• GET /api/v1/components/{component_id}/hosts - List apps hosted on a component
• GET /api/v1/components/{component_id}/depends-on - List component dependencies
• GET /api/v1/areas/{area_id}/components - List components within a specific area

Component Data Endpoints

• GET /api/v1/components/{component_id}/data - Read all topic data from a component
• GET /api/v1/components/{component_id}/data/{topic_name} - Read specific topic data from a component
• PUT /api/v1/components/{component_id}/data/{topic_name} - Publish data to a topic

Operations Endpoints (Services & Actions)

• GET /api/v1/components/{component_id}/operations - List all services and actions for a component
• GET /api/v1/components/{component_id}/operations/{operation_id} - Get operation details
• POST /api/v1/components/{component_id}/operations/{operation_id}/executions - Execute operation (call service or send action goal)
• GET /api/v1/components/{component_id}/operations/{operation_id}/executions - List all executions for an operation
• GET /api/v1/components/{component_id}/operations/{operation_id}/executions/{execution_id} - Get execution status
• DELETE /api/v1/components/{component_id}/operations/{operation_id}/executions/{execution_id} - Cancel action execution

Configurations Endpoints (ROS 2 Parameters)

• GET /api/v1/components/{component_id}/configurations - List all parameters for a component
• GET /api/v1/components/{component_id}/configurations/{param} - Get parameter value
• PUT /api/v1/components/{component_id}/configurations/{param} - Set parameter value
• DELETE /api/v1/components/{component_id}/configurations/{param} - Reset parameter to default value
• DELETE /api/v1/components/{component_id}/configurations - Reset all parameters to default values

Bulk Data Endpoints

• GET /api/v1/{entity}/{id}/bulk-data - List bulk-data categories (rosbags + configured)
• GET /api/v1/{entity}/{id}/bulk-data/{category} - List bulk-data items in a category
• GET /api/v1/{entity}/{id}/bulk-data/{category}/{item_id} - Download a bulk-data file
• POST /api/v1/{entity}/{id}/bulk-data/{category} - Upload bulk data (components/apps only)
• DELETE /api/v1/{entity}/{id}/bulk-data/{category}/{item_id} - Delete bulk data (components/apps only)

Logging Endpoints

• GET /api/v1/components/{component_id}/logs - Query recent log entries for a component (all its nodes, prefix match)
• GET /api/v1/apps/{app_id}/logs - Query recent log entries for a specific app node (exact match)
• GET /api/v1/components/{component_id}/logs/configuration - Get log configuration for a component
• GET /api/v1/apps/{app_id}/logs/configuration - Get log configuration for an app
• PUT /api/v1/components/{component_id}/logs/configuration - Update log configuration for a component
• PUT /api/v1/apps/{app_id}/logs/configuration - Update log configuration for an app

API Reference

GET /api/v1/areas

Lists all discovered areas in the system.

Example:

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

Response:

```json [ { “id”: “powertrain”, “namespace”: “/powertrain”, “type”: “Area” }, { “id”: “chassis”, “namespace”: “/chassis”, “type”: “Area” } ]

File truncated at 100 lines see the full file

Changelog for package ros2_medkit_gateway

0.3.0 (2026-02-27)

• Gateway plugin framework with dynamic C++ plugin loading (#237)
• Software updates plugin with 8 SOVD-compliant endpoints (#237, #231)
• SSE-based periodic data subscriptions for real-time streaming without polling (#223)
• Global DELETE /api/v1/faults endpoint (#228)
• Return HEALED/PREPASSED faults via status filter (#218)
• Bulk data upload and delete endpoints (#216)
• Token-bucket rate limiting middleware, configurable per-endpoint (#220)
• Reduce lock contention in ConfigurationManager (#194)
• Cache component topic map to avoid per-request graph rebuild (#212)
• Require cpp-httplib >= 0.14 in pkg-config check (#230)
• Add missing ament_index_cpp dependency to package.xml (#191)
• Unit tests for HealthHandlers, DataHandlers, and AuthHandlers (#232, #234, #233)
• Standardize include guards to #pragma once (#192)
• Use foreach loop for CMake coverage flags (#193)
• Migrate ament_target_dependencies to compat shim for Rolling (#242)
• Multi-distro CI support for ROS 2 Humble, Jazzy, and Rolling (#219, #242)
• Contributors: \@bburda, \@eclipse0922, \@mfaferek93

0.2.0 (2026-02-07)

• Initial rosdistro release
• HTTP REST gateway for ros2_medkit diagnostics system
• SOVD-compatible entity discovery with four entity types:
  • Areas, Components, Apps, Functions
  • HATEOAS links and capabilities in all responses
  • Relationship endpoints (subareas, subcomponents, related-apps, hosts)
• Three discovery modes:
  • Runtime-only: automatic ROS 2 graph introspection
  • Manifest-only: YAML manifest with validation (11 rules)
  • Hybrid: manifest as source of truth + runtime linking
• REST API endpoints:
  • Fault management: GET/POST/DELETE /api/v1/faults
  • Data access: topic sampling via GenericSubscription
  • Operations: service calls and action goals via GenericClient
  • Configuration: parameter get/set via ROS 2 parameter API
  • Snapshots: GET /api/v1/faults/{code}/snapshots
  • Rosbag: GET /api/v1/faults/{code}/snapshots/bag
• Server-Sent Events (SSE) at /api/v1/faults/stream:
  • Multi-client support with thread-safe event queue
  • Keepalive, Last-Event-ID reconnection, configurable max_clients
• JWT-based authentication with configurable policies
• HTTPS/TLS support via OpenSSL and cpp-httplib
• Native C++ ROS 2 serialization via ros2_medkit_serialization (no CLI dependencies)
• Contributors: Bartosz Burda, Michal Faferek