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
• Incremental entity cache: Discovery refresh diffs add/remove/change and performs zero structural allocations in the cache layer at steady state (object-pool backed, fixed capacity reserved at init via entity_cache.capacity)
• 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

File truncated at 100 lines see the full file

Changelog for package ros2_medkit_gateway

Forthcoming

• Manual asset inventory: a manifest assets: list and a new discovery.inventory.csv_path parameter declare assets that no protocol layer can describe (or fully describe). Both paths recognize the canonical names id, manufacturer, model, serial, hardware_rev, firmware, endpoint, role, area plus the shared aliases (serial_number, hardware_revision / hw_rev, firmware_version / fw) and keep any other column / key as an extra; RFC-4180-style quoting is honored. Each asset becomes a Component with source = "inventory" and a structured asset identity carrying per-field provenance, appended to the base manifest on every load / reload and merged into the tree by id alongside protocol-discovered structure; area places the asset under an Area, without it the asset appears only in the flat component list. CSV rows never fail the load: rows without an id are skipped with a warning, for duplicate ids the first row wins, a row whose id is already a manifest component keeps the manifest definition (the row's identity is folded in as gap-fill), and an unknown area is dropped with a warning. The CSV is size-capped at 1 MiB before being read; a missing file is skipped with a warning (mirrors fragments_dir), while an unreadable or malformed one fails the load / reload. Requires a manifest-backed discovery mode (manifest_only / hybrid with discovery.manifest_path set); empty = disabled (default) (#490)

0.6.0 (2026-06-22)

• SOVD entity status and lifecycle control endpoints: GET /apps/{id}/status and GET /components/{id}/status, plus lifecycle control routes backed by a new LifecycleProvider plugin interface and plugin-manager routing. Control returns 501 Not Implemented until a provider is registered; the routes are RBAC-gated, advertised via a status link on app and component detail, and declared under the OpenAPI Lifecycle tag (#437)
• Accurate app and component status: app status is read from the managed-node lifecycle state through a GetState-backed reader, and a component reports notReady when all hosted apps are offline while staying ready as long as it is reachable (#455)
• Bounded the executor and HTTP server thread pools, sized to the cold-wait plus SSE budget, with misconfiguration guards and a bounded keep-alive timeout (#457)
• Startup discovery summary logged at boot, with an empty-graph warning when no entities are discovered (#438)
• Bounded the unsupported-message-type cache and exposed its size; unknown message types now warn once instead of on every sample (#450)
• OpenAPI query parameters are derived from a typed query contract, tightening the query-parameter schema and its regression gate (#417)
• PluginContext can aggregate peer faults across daisy-chained gateways through the SOVD service interface (#419)
• Single-command bringup of the local medkit stack via bringup.launch.py and bringup_params.yaml (#439)
• Docker image enables CORS for the documented web UI path and uses explicit web UI origins instead of wildcard CORS (#452)
• Docker image bundles the CycloneDDS RMW as an opt-in alternative implementation (#451)
• Native gateway launch enables web UI CORS by default and honors the CORS settings from a supplied config_file (#461)
• Incremental, embedded-hardened entity cache: ThreadSafeEntityCache stores entities in a fixed-capacity SlotStore object pool indexed by open-addressed flat hash maps, and update_all reconciles the discovery output by id (add / remove / change only) so steady-state refresh does zero structural allocations. Capacity is reserved via entity_cache.capacity (default 256) and cache stats are exposed on /health as x-medkit-entity-cache. Discovery refreshes are debounced via discovery.refresh_debounce_ms (default 1000) and operation type_info schemas resolve lazily, cutting gateway CPU under graph churn roughly 4x. Entity detail operations[] no longer embeds schemas eagerly; the schemas remain on the /operations resource (#462)
• Contributors: \@bburda, \@mfaferek93

0.5.0 (2026-06-08)

Breaking Changes:

• Typed router refactor. HandlerContext no longer carries send_json / send_error / send_plugin_error / send_dto / parse_body: handlers return http::Result<TResponse> and the framework owns response writing through RouteRegistry. The raw void(httplib::Request, httplib::Response) RouteRegistry lambda overloads are removed - call sites must use the typed reg.get<T> / reg.post<TBody, T> / reg.del<T> overloads, the multi-shape reg.post_alternates<TBody, TAlt...> / reg.del_alternates<TAlt...>, or one of the named escape hatches (reg.sse / reg.binary_download / reg.multipart_upload<T> /

File truncated at 100 lines see the full file