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 a SOVD-aligned entity hierarchy (Areas, Components, Apps, Functions), and provides endpoints to query and interact with them.

Key Features:

• Auto-discovery: Automatically detects ROS 2 nodes and topics
• SOVD entity model: Areas, Components (host-level), Apps (ROS 2 nodes), and Functions (namespace-based logical grouping)
• 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 - List all discovered apps
• GET /api/v1/apps/{app_id} - Get app capabilities
• GET /api/v1/apps/{app_id}/is-located-on - Get the component hosting this app
• GET /api/v1/functions - List all discovered functions
• GET /api/v1/functions/{function_id} - Get function capabilities
• GET /api/v1/functions/{function_id}/hosts - List apps grouped by this function

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

File truncated at 100 lines see the full file

Changelog for package ros2_medkit_gateway

Unreleased

Fixes:

• GET /api/v1/updates/{id}/status no longer returns 404 for a registered-but-idle package; POST /api/v1/updates now seeds a pending status, so the endpoint returns 200 {"status": "pending"} immediately after registration. 404 is reserved for packages that are not registered. Clients that used 404 as a signal for "registered but nothing started yet" must adapt (#378)

Features:

• Plugin API version bumped to v7. Adds PluginContext::notify_entities_changed(EntityChangeScope) lifecycle hook for plugins that mutate the entity surface at runtime; default no-op keeps v6 source code compiling unchanged against v7 headers. Binary compatibility is not provided: the plugin loader uses a strict equality check on plugin_api_version(), so out-of-tree plugins must be recompiled (#376)
• New discovery.manifest.fragments_dir parameter: gateway scans the directory for *.yaml / *.yml fragment files on every manifest load / reload and merges apps, components, and functions on top of the base manifest. Fragments are forbidden from declaring top-level areas, metadata, discovery, scripts, capabilities, or lock_overrides - those stay in the base manifest. Presence of any forbidden key (including empty-valued ones like areas: []) is reported as a FRAGMENT_FORBIDDEN_FIELD validation error that fails the load / reload. Unknown top-level keys (typos such as app: vs apps:) are ignored with a warning log. Files merged in alphabetical order for deterministic duplicate-id errors (#376)
• Fragment files are size-capped at 1 MiB (ManifestParser::kMaxFragmentBytes) before being read into memory, and any symlink resolving outside the canonical fragments_dir is skipped with a warning, so misconfigurations or symlink-based escapes cannot hand arbitrary bytes to the YAML parser (#376)
• All-or-nothing fragment semantics: a single malformed or forbidden fragment fails the entire load / reload and keeps the previously-loaded manifest active (#376)
• ManifestParser::parse_fragment_file convenience entrypoint that injects a synthetic manifest_version header when the fragment omits one
• See design/plugin_entity_notifications.rst for the lifecycle, merge-rule, and plugin-side write-contract walkthrough

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

File truncated at 100 lines see the full file