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.)
• Resource Locking: SOVD-compliant entity locking with scoped access control, lock breaking, and automatic expiry

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
• GET /api/v1/apps/{app_id}/is-located-on - Get the component hosting this app

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

Locking Endpoints

• POST /api/v1/{components|apps}/{id}/locks - Acquire a lock on an entity
• GET /api/v1/{components|apps}/{id}/locks - List active locks on an entity
• GET /api/v1/{components|apps}/{id}/locks/{lock_id} - Get lock details
• PUT /api/v1/{components|apps}/{id}/locks/{lock_id} - Extend lock expiration
• DELETE /api/v1/{components|apps}/{id}/locks/{lock_id} - Release a lock

Trigger Endpoints

• POST /api/v1/{entity}/{id}/triggers - Create a trigger with conditions
• GET /api/v1/{entity}/{id}/triggers - List active triggers
• GET /api/v1/{entity}/{id}/triggers/{trigger_id} - Get trigger details
• PUT /api/v1/{entity}/{id}/triggers/{trigger_id} - Update trigger conditions
• DELETE /api/v1/{entity}/{id}/triggers/{trigger_id} - Delete a trigger
• GET /api/v1/{entity}/{id}/triggers/{trigger_id}/events - SSE stream of trigger events

Scripts Endpoints

• GET /api/v1/{entity}/{id}/scripts - List available diagnostic scripts
• POST /api/v1/{entity}/{id}/scripts - Upload a new script
• GET /api/v1/{entity}/{id}/scripts/{script_id} - Get script details
• DELETE /api/v1/{entity}/{id}/scripts/{script_id} - Delete a script

File truncated at 100 lines see the full file

Changelog for package ros2_medkit_gateway

0.4.0 (2026-03-20)

Breaking Changes:

• GET /version-info response key renamed from sovd_info to items for SOVD alignment (#258)
• GET / root endpoint restructured: endpoints is now a flat string array, added capabilities object, api_base field, and name/version top-level fields (#258)
• Default rosbag storage format changed from sqlite3 to mcap (#258)
• Plugin API version bumped to v4 - added ScriptProvider, locking API, and extended PluginContext with entity snapshot, fault listing, and sampler registration
• GraphProviderPlugin extracted to separate ros2_medkit_graph_provider package

Features:

Discovery & Merge Pipeline:

• Layered merge pipeline for hybrid discovery with per-layer, per-field-group merge policies (#258)
• Gap-fill configuration: control heuristic entity creation with allow_heuristic_* options and namespace filtering (#258)
• Plugin layer: IntrospectionProvider now wired into discovery pipeline via PluginLayer (#258)
• /health endpoint includes merge pipeline diagnostics (layers, conflicts, gap-fill stats) (#258)
• Entity detail responses now include logs, bulk-data, cyclic-subscriptions URIs (#258)
• Entity capabilities fix: areas and functions now report correct resource collections (#258)
• discovery.manifest.enabled / discovery.runtime.enabled parameters for hybrid mode
• NewEntities.functions - plugins can now produce Function entities
• GET /apps/{id}/is-located-on endpoint for reverse host lookup (app to component)
• Beacon discovery plugin system - push-based entity enrichment via ROS 2 topic
• x-medkit-topic-beacon and x-medkit-param-beacon vendor extension REST endpoints
• Linux introspection plugins: procfs, systemd, and container plugins via x-medkit-* vendor endpoints (#263)

Locking:

• SOVD-compliant resource locking: acquire, release, extend with session tracking and expiration
• Lock enforcement on all mutating handlers (PUT, POST, DELETE)
• Per-entity lock configuration via manifest YAML with required_scopes
• Lock API exposed to plugins via PluginContext
• Automatic cyclic subscription cleanup on lock expiry
• LOCKS capability in entity descriptions

Scripts:

• SOVD script execution endpoints: CRUD for scripts and executions with subprocess execution
• ScriptProvider plugin interface for custom script backends
• DefaultScriptProvider with manifest + filesystem CRUD, argument passing, and timeout
• Manifest-defined scripts: ManifestParser populates ScriptsConfig.entries from manifest YAML
• allow_uploads config toggle for hardened deployments
• RBAC integration for script operations

Logging:

• LogProvider plugin interface for custom log backends (#258)
• LogManager with /rosout ring buffer and plugin delegation
• /logs and /logs/configuration endpoints
• LOGS capability in discovery responses
• Configurable log buffer size via parameters
• Area and function log endpoints with namespace aggregation (#258)

Triggers:

• Condition-based triggers with CRUD endpoints, SSE event streaming, and hierarchy matching
• TriggerManager with ConditionEvaluator interface and 4 built-in evaluators (OnChange, OnChangeTo, EnterRange, LeaveRange)
• ResourceChangeNotifier for async dispatch from FaultManager, UpdateManager, and OperationManager
• TriggerTopicSubscriber for data trigger ROS 2 topic subscriptions
• Persistent trigger storage via SQLite with restore-on-restart

File truncated at 100 lines see the full file