ros2_medkit_opcua

Gateway plugin that bridges OPC-UA capable PLCs (OpenPLC, Siemens S7, Beckhoff, Allen-Bradley, etc.) into the SOVD entity tree. Enables unified diagnostics for mixed ROS 2 + industrial PLC deployments through a single REST API, with PLC alarms routed to ros2_medkit_fault_manager and numeric PLC values optionally bridged to ROS 2 std_msgs/Float32 topics.

Follows the same plugin pattern as ros2_medkit_graph_provider: implements GatewayPlugin + IntrospectionProvider against the get_routes() plugin API, loaded at runtime by ros2_medkit_gateway via dlopen.

What it does

• Connects to any OPC-UA capable PLC server over opc.tcp
• Emits SOVD entities (area, component, apps) from a YAML-driven node map
• Exposes PLC values as the x-plc-data vendor collection
• Allows writing setpoints via x-plc-operations with type-aware coercion and range validation
• Reports the connection state and poll metrics via x-plc-status
• Maps threshold-based PLC alarms to SOVD faults on the owning entity
• Optionally publishes numeric PLC values to ROS 2 std_msgs/Float32 topics

Architecture

                    OPC-UA (TCP :4840)
PLC Runtime  <─────────────────────────>  OPC-UA Plugin (.so)
  IEC 61131-3 program                      │
  Cyclic execution (100ms)                 │  Polls all configured nodes
  Variables exposed as OPC-UA nodes        │  Maps to SOVD entity tree
                                           │  Alarm thresholds -> fault reporting
                                           │
                                           ▼
                                    ros2_medkit Gateway
                                      REST API :8080
                                           │
                                    ┌──────┴──────┐
                                    │             │
                              SOVD REST      Fleet Gateway
                              (direct)       (aggregation)
                                    │             │
                                Dashboard    Multi-device view

The plugin connects to any PLC with an OPC-UA server over TCP. No ROS 2 dependency between the plugin and the PLC - communication is pure OPC-UA. The plugin is loaded by the gateway at runtime via dlopen() and registers vendor REST endpoints for PLC data access and control.

SOVD Entity Model

The plugin creates a hierarchical entity tree from a YAML node map configuration:

Area: plc_systems
  └── Component: openplc_runtime
        ├── App: tank_process
        │     Data: tank_level (mm), tank_temperature (C), tank_pressure (bar)
        │     Faults: PLC_HIGH_TEMP, PLC_LOW_LEVEL, PLC_OVERPRESSURE
        ├── App: fill_pump
        │     Data: pump_speed (%)
        │     Operations: set_pump_speed
        └── App: drain_valve
              Data: valve_position (%)
              Operations: set_valve_position

REST API

Vendor Endpoints

Standard SOVD (provided by gateway)

Example Responses

Live PLC data:

GET /api/v1/apps/tank_process/x-plc-data

{
  "entity_id": "tank_process",
  "connected": true,
  "timestamp": 1774185903,
  "items": [
    {"name": "tank_level", "value": 742.5, "unit": "mm", "data_type": "float", "writable": true},
    {"name": "tank_temperature", "value": 31.8, "unit": "C", "data_type": "float", "writable": true},
    {"name": "tank_pressure", "value": 2.95, "unit": "bar", "data_type": "float", "writable": false}
  ]
}

Write to PLC:

```json POST /api/v1/apps/fill_pump/x-plc-operations/set_pump_speed {“value”: 80.0}

File truncated at 100 lines see the full file

Changelog for package ros2_medkit_opcua

0.4.0 (2026-04-11)

• Initial release
• OpcuaPlugin implementation of GatewayPlugin and IntrospectionProvider that bridges OPC-UA capable PLCs into the SOVD entity tree
• REST endpoints via the new get_routes() plugin API: x-plc-data, x-plc-operations, x-plc-status
• Vendor capabilities registered per entity - only PLC-backed apps and the PLC runtime component advertise the x-plc-* endpoints
• Full OPC 10000-6 section 5.3.1.10 node identifier support (i= numeric, s= string, g= GUID, b= opaque ByteString); example node maps for OpenPLC, Siemens S7-1500 TIA Portal, Beckhoff TwinCAT 3, Allen-Bradley via Kepware and KUKA KR C5
• NodeMap driven by YAML configuration - same binary serves any OPC-UA compliant server by changing the node map file
• Deterministic entity ordering in IntrospectionResult output (entries sorted by id)
• Threshold-based PLC alarm detection routed to SOVD faults via ros2_medkit_msgs services ReportFault / ClearFault
• Optional bridging of numeric PLC values to ROS 2 std_msgs/Float32 topics from set_context()
• Type-aware writes with per-node range validation
• Robust connection-loss detection: all three OPC-UA client paths (read_value, read_values, write_value) mark the connection as dropped on terminal status codes so OpcuaPoller reconnect kicks in without stalling
• Polling mode (default) and OPC-UA subscription mode, backed by open62541pp v0.16.0
• Integration test suite against an OpenPLC IEC 61131-3 tank demo container
• Contributors: \@mfaferek93