ros2_medkit_opcua: subscribe to native OPC-UA AlarmConditions and bridge to fault_manager

[mfaferek93]

Motivation

OPC-UA Part 9 defines AlarmConditionType events that vendor PLCs (Siemens S7-1500 FW V2.9+, Beckhoff TF6100, CodeSys 3.5+, Rockwell via FactoryTalk Linx) emit natively. The plugin currently reports faults only from threshold checks on scalar values - native alarms with their state machine, severity, and ack flow are ignored. Subscribe to AlarmConditionType events and bridge them to fault_manager as SOVD faults.

Scope

• Native event subscription via raw UA_Client_MonitoredItems_createEvents (open62541pp lacks subscribeEvent)
• EventFilter select clauses: EventType, EventId, SourceNode, Time, Severity, Message, ConditionId, BranchId, ConditionClassId, EnabledState, ActiveState, AckedState, ConfirmedState, ShelvingState, Retain
• ConditionRefresh on subscribe and on every reconnect, with RefreshStartEvent / RefreshEndEvent bracketing per spec
• Per-condition EventId tracking (required for spec-compliant Acknowledge calls)
• State machine on EnabledState x ShelvingState x ActiveState x AckedState x ConfirmedState x BranchId -> SOVD CONFIRMED / HEALED / CLEARED / suppressed (full table in design/index.rst)
• node_map.yaml extension: new alarm_source field, mutually exclusive with threshold
• acknowledge_fault and confirm_fault SOVD operations: POST -> OPC-UA Call (Object=ConditionId instance, Method=i=9111 Ack / i=9113 Confirm), comment as LocalizedText
• Existing threshold polling unchanged (OpenPLC fallback)
• Conformance Units claimed in design doc: A&C Base, A&C Refresh, A&C Acknowledge, A&C Confirm

Out of scope

• OPC-UA branch reasoning beyond suppression: BranchId != null events log to history only. Re-fires tracked via fault_manager occurrence_count + /faults/stream SSE.
• ShelvingState write operations (TimedShelve / OneShotShelve) - operator UI concern.
• Auto-discovery of alarm sources via browse - tracked in ros2_medkit_opcua: add browse-based auto node_map generation #368.
• Quality (StatusCode) propagation to SOVD - requires additive field on ReportFault.srv; tracked in follow-up.

Acceptance criteria

1. Synthetic AlarmConditionType event -> SOVD fault appears CONFIRMED within one publishing interval
2. ActiveState->Inactive transition -> CONFIRMED -> HEALED -> CLEARED depending on AckedState + ConfirmedState
3. acknowledge_fault operation triggers OPC-UA Acknowledge with tracked EventId; AckedState transitions on server
4. confirm_fault operation triggers OPC-UA Confirm; ConfirmedState transitions on server
5. EnabledState=false or ShelvingState=Shelved -> alarm not surfaced as CONFIRMED; transition back -> alarm reappears
6. BranchId != null events do not change SOVD live status; visible in fault_manager event log
7. Server restart -> ConditionRefresh fires; RefreshStartEvent / RefreshEndEvent bracketing handled; no missed alarms
8. Existing threshold-mode YAML continues to work unchanged
9. CI green on Humble + Jazzy + Rolling, ASAN + TSAN clean
10. Custom test server (open62541-based) included; verified spec-compliant via independent client smoke test

References

• OPC UA Part 9 (Alarms & Conditions) v1.05: https://reference.opcfoundation.org/Core/Part9/v105/docs/
• open62541 event subscription example: https://github.com/open62541/open62541/blob/master/examples/tutorial_client_events.c
• Subscription seam to extend: src/ros2_medkit_plugins/ros2_medkit_opcua/src/opcua_client.cpp:373
• Threshold-to-fault bridge to extend: src/ros2_medkit_plugins/ros2_medkit_opcua/src/opcua_plugin.cpp:468