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

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> / reg.static_asset / reg.docs_endpoint / reg.docs_subtree). static_assert(dto::has_dto_shape_v<T>) gates every typed overload, so non-DTO return types fail at compile time. The plugin ABI is unaffected: PluginResponse keeps its send_json / send_error surface and now routes through the same internal http::detail::write_json_body primitive as the framework, so plugin wire format is unchanged (#403)
• Provider ABI typed. FaultProvider, DataProvider, OperationProvider, and UpdateProvider::get_update return typed DTO envelopes (FaultListResult / FaultDetailResult / FaultClearResult / the matching Data*Result and Operation*Result shapes / UpdateStatusResult) instead of raw tl::expected<nlohmann::json, ErrorInfo>. The wire bytes are byte-identical because each envelope wraps an opaque content object emitted verbatim by JsonWriter; commercial and out-of-tree plugins must wrap their existing JSON in the matching envelope type (mechanical: Result.content = std::move(json_payload)). The plugin ABI itself (PluginRoute shape, PluginResponse ctor, plugin api version) is locked by test_plugin_abi_conformance and is unchanged (#403)
• SchemaWriter emits optional DTO fields as anyOf: [<inner>, {type: "null"}] (the OpenAPI 3.1 idiom) instead of nullable: true. Generated clients see T | null for every optional field rather than T | undefined. Wire format is unchanged - the gateway still omits absent optional fields, and JsonReader continues to accept absent fields; the schema change only opts the published spec into round-tripping a literal null value cleanly for clients that prefer to send one. As part of this, a handful of fields that were previously emitted as an explicit JSON null when absent are now omitted entirely (consistent with the optional-omission policy): the script execution fields progress / started_at / completed_at / parameters / error (GET .../scripts/{id}/executions/{eid}) and the script parameters_schema field (GET .../scripts/{id}). Clients that tested field === null or relied on the key always being present must treat an absent key the same as null (#403)
• Synchronous operation-execution service-call failures (POST /api/v1/{entity-path}/operations/{id}/executions when the underlying ROS 2 service call fails) now return the standard SOVD GenericError envelope ({"error_code": "vendor-error", "vendor_code": "x-medkit-ros2-service-unavailable", "message": "Service call failed", ...}, HTTP status 500 unchanged) instead of the previous bespoke nested {"error": {"code", "message", "details"}} object. This aligns the one remaining non-standard error path with every other gateway error; clients that parsed error.code / error.details for this specific failure must read vendor_code / parameters instead (#403)
• GET /api/v1/{entity-path}/data now publishes the opaque DataListResult schema ({type: object, additionalProperties: true, x-medkit-opaque: true}), matching how GET .../faults already publishes FaultListResult. The wire payload is unchanged for runtime (ROS 2) entities - it is still {"items": [...], "x-medkit": {...}} built from the typed Collection<DataItem, DataListXMedkit> - but for plugin-owned entities the provider's free-form per-item shape now passes through verbatim instead of being re-parsed into Collection<DataItem>. This fixes a regression in which plugin per-item fields (the OPC-UA plugin's value / unit / data_type / writable) were silently dropped by the typed re-parse. Clients that generated a typed DataItem model from the previous spec for this route now see an opaque object instead (#403)
• Entity responses (areas, components, apps, functions - list items and detail) now always carry a top-level type discriminator (an enum of area / component / app / function). Previously list items had no type and detail responses exposed it only inside x-medkit.entityType. Additive and tolerant-client-safe; consumers keying on the entity kind can now read the top-level type (#403)
• ros2_medkit_msgs/srv/ClearFault request gains a bool skip_correlation_auto_clear field (see the per-entity fault scope entry below for the in-tree motivation). Adding a request field changes the service type hash, so out-of-tree callers that invoke the service directly (for example ros2 service call /fault_manager/clear_fault ros2_medkit_msgs/srv/ClearFault ... as documented in the ros2_medkit_fault_manager README) must rebuild against the new ros2_medkit_msgs to keep talking to fault_manager. The in-tree gateway client and server are updated together (#395)
• Per-entity fault routes are now correctly scoped to the entity's hosted apps. GET /api/v1/{entity-path}/faults/{fault_code},

File truncated at 100 lines see the full file