diff --git a/src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IAddressSpaceBuilder.cs b/src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IAddressSpaceBuilder.cs index 21bb44c..96075c8 100644 --- a/src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IAddressSpaceBuilder.cs +++ b/src/ZB.MOM.WW.OtOpcUa.Core.Abstractions/IAddressSpaceBuilder.cs @@ -42,4 +42,39 @@ public interface IVariableHandle { /// Driver-side full reference for read/write addressing. string FullReference { get; } + + /// + /// Annotate this variable with an OPC UA AlarmConditionState. Drivers with + /// = true call this during discovery so the + /// concrete address-space builder can materialize a sibling condition node. The returned + /// sink receives lifecycle transitions raised through + /// — the generic node manager wires the subscription; the concrete builder decides how + /// to surface the state (e.g. OPC UA AlarmConditionState.Activate, + /// Acknowledge, Deactivate). + /// + IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info); +} + +/// +/// Metadata used to materialize an OPC UA AlarmConditionState sibling for a variable. +/// Populated by the driver's discovery step; concrete builders decide how to surface it. +/// +/// Human-readable alarm name used for the SourceName event field. +/// Severity at address-space build time; updates arrive via . +/// Initial description; updates arrive via . +public sealed record AlarmConditionInfo( + string SourceName, + AlarmSeverity InitialSeverity, + string? InitialDescription); + +/// +/// Sink a concrete address-space builder returns from . +/// The generic node manager routes per-alarm payloads here — +/// the sink translates the transition into an OPC UA condition state change or whatever the +/// concrete builder's backing address space supports. +/// +public interface IAlarmConditionSink +{ + /// Push an alarm transition (Active / Acknowledged / Inactive) for this condition. + void OnTransition(AlarmEventArgs args); } diff --git a/src/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs b/src/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs index 1672ee1..8712107 100644 --- a/src/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs +++ b/src/ZB.MOM.WW.OtOpcUa.Core/OpcUa/GenericDriverNodeManager.cs @@ -1,27 +1,41 @@ +using System.Collections.Concurrent; using ZB.MOM.WW.OtOpcUa.Core.Abstractions; namespace ZB.MOM.WW.OtOpcUa.Core.OpcUa; /// /// Generic, driver-agnostic backbone for populating the OPC UA address space from an -/// . The Galaxy-specific subclass (GalaxyNodeManager) is deferred -/// to Phase 2 per decision #62 — this class is the foundation that Phase 2 ports the v1 -/// LmxNodeManager logic into. +/// . Walks the driver's discovery, wires the alarm + data-change + +/// rediscovery subscription events, and hands each variable to the supplied +/// . Concrete OPC UA server implementations provide the +/// builder — see the Server project's OpcUaAddressSpaceBuilder for the materialization +/// against CustomNodeManager2. /// /// -/// Phase 1 status: scaffold only. The v1 LmxNodeManager in the legacy Host is unchanged -/// so IntegrationTests continue to pass. Phase 2 will lift-and-shift its logic here, swapping -/// IMxAccessClient for and GalaxyAttributeInfo for -/// . +/// Per docs/v2/plan.md decision #52 + #62 — Core owns the node tree, drivers stream +/// Folder/Variable calls, alarm-bearing variables are annotated via +/// and subsequent +/// payloads route to the sink the builder returned. /// -public abstract class GenericDriverNodeManager(IDriver driver) +public class GenericDriverNodeManager(IDriver driver) : IDisposable { protected IDriver Driver { get; } = driver ?? throw new ArgumentNullException(nameof(driver)); public string DriverInstanceId => Driver.DriverInstanceId; + // Source tag (DriverAttributeInfo.FullName) → alarm-condition sink. Populated during + // BuildAddressSpaceAsync by a recording IAddressSpaceBuilder implementation that captures the + // IVariableHandle per attr.IsAlarm=true variable and calls MarkAsAlarmCondition. + private readonly ConcurrentDictionary _alarmSinks = + new(StringComparer.OrdinalIgnoreCase); + + private EventHandler? _alarmForwarder; + private bool _disposed; + /// - /// Populates the address space by streaming nodes from the driver into the supplied builder. + /// Populates the address space by streaming nodes from the driver into the supplied builder, + /// wraps the builder so alarm-condition sinks are captured, subscribes to the driver's + /// alarm event stream, and routes each transition to the matching sink by SourceNodeId. /// Driver exceptions are isolated per decision #12 — the driver's subtree is marked Faulted, /// but other drivers remain available. /// @@ -32,6 +46,73 @@ public abstract class GenericDriverNodeManager(IDriver driver) if (Driver is not ITagDiscovery discovery) throw new NotSupportedException($"Driver '{Driver.DriverInstanceId}' does not implement ITagDiscovery."); - await discovery.DiscoverAsync(builder, ct); + var capturing = new CapturingBuilder(builder, _alarmSinks); + await discovery.DiscoverAsync(capturing, ct); + + if (Driver is IAlarmSource alarmSource) + { + _alarmForwarder = (_, e) => + { + // Route the alarm to the sink registered for the originating variable, if any. + // Unknown source ids are dropped silently — they may belong to another driver or + // to a variable the builder chose not to flag as an alarm condition. + if (_alarmSinks.TryGetValue(e.SourceNodeId, out var sink)) + sink.OnTransition(e); + }; + alarmSource.OnAlarmEvent += _alarmForwarder; + } + } + + public void Dispose() + { + if (_disposed) return; + _disposed = true; + if (_alarmForwarder is not null && Driver is IAlarmSource alarmSource) + { + alarmSource.OnAlarmEvent -= _alarmForwarder; + } + _alarmSinks.Clear(); + } + + /// + /// Snapshot the current alarm-sink registry by source node id. Diagnostic + test hook; + /// not part of the hot path. + /// + internal IReadOnlyCollection TrackedAlarmSources => _alarmSinks.Keys.ToList(); + + /// + /// Wraps the caller-supplied so every + /// call registers the returned sink in + /// the node manager's source-node-id map. The builder itself drives materialization; + /// this wrapper only observes. + /// + private sealed class CapturingBuilder( + IAddressSpaceBuilder inner, + ConcurrentDictionary sinks) : IAddressSpaceBuilder + { + public IAddressSpaceBuilder Folder(string browseName, string displayName) + => new CapturingBuilder(inner.Folder(browseName, displayName), sinks); + + public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo attributeInfo) + => new CapturingHandle(inner.Variable(browseName, displayName, attributeInfo), sinks); + + public void AddProperty(string browseName, DriverDataType dataType, object? value) + => inner.AddProperty(browseName, dataType, value); + } + + private sealed class CapturingHandle( + IVariableHandle inner, + ConcurrentDictionary sinks) : IVariableHandle + { + public string FullReference => inner.FullReference; + + public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info) + { + var sink = inner.MarkAsAlarmCondition(info); + // Register by the driver-side full reference so the alarm forwarder can look it up + // using AlarmEventArgs.SourceNodeId (which the driver populates with the same tag). + sinks[inner.FullReference] = sink; + return sink; + } } } diff --git a/src/ZB.MOM.WW.OtOpcUa.Core/ZB.MOM.WW.OtOpcUa.Core.csproj b/src/ZB.MOM.WW.OtOpcUa.Core/ZB.MOM.WW.OtOpcUa.Core.csproj index b31947c..8e48171 100644 --- a/src/ZB.MOM.WW.OtOpcUa.Core/ZB.MOM.WW.OtOpcUa.Core.csproj +++ b/src/ZB.MOM.WW.OtOpcUa.Core/ZB.MOM.WW.OtOpcUa.Core.csproj @@ -16,6 +16,10 @@ + + + + diff --git a/src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Proxy/GalaxyProxyDriver.cs b/src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Proxy/GalaxyProxyDriver.cs index c8749ca..8762cd4 100644 --- a/src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Proxy/GalaxyProxyDriver.cs +++ b/src/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Proxy/GalaxyProxyDriver.cs @@ -114,17 +114,31 @@ public sealed class GalaxyProxyDriver(GalaxyProxyOptions options) var folder = builder.Folder(obj.ContainedName, obj.ContainedName); foreach (var attr in obj.Attributes) { - folder.Variable( + var fullName = $"{obj.TagName}.{attr.AttributeName}"; + var handle = folder.Variable( attr.AttributeName, attr.AttributeName, new DriverAttributeInfo( - FullName: $"{obj.TagName}.{attr.AttributeName}", + FullName: fullName, DriverDataType: MapDataType(attr.MxDataType), IsArray: attr.IsArray, ArrayDim: attr.ArrayDim, SecurityClass: MapSecurity(attr.SecurityClassification), IsHistorized: attr.IsHistorized, IsAlarm: attr.IsAlarm)); + + // PR 15: when Galaxy flags the attribute as alarm-bearing (AlarmExtension + // primitive), register an alarm-condition sink so the generic node manager + // can route OnAlarmEvent payloads for this tag to the concrete address-space + // builder. Severity default Medium — the live severity arrives through + // AlarmEventArgs once MxAccessGalaxyBackend's tracker starts firing. + if (attr.IsAlarm) + { + handle.MarkAsAlarmCondition(new AlarmConditionInfo( + SourceName: fullName, + InitialSeverity: AlarmSeverity.Medium, + InitialDescription: null)); + } } } } diff --git a/tests/ZB.MOM.WW.OtOpcUa.Core.Tests/GenericDriverNodeManagerTests.cs b/tests/ZB.MOM.WW.OtOpcUa.Core.Tests/GenericDriverNodeManagerTests.cs new file mode 100644 index 0000000..6d47a4f --- /dev/null +++ b/tests/ZB.MOM.WW.OtOpcUa.Core.Tests/GenericDriverNodeManagerTests.cs @@ -0,0 +1,163 @@ +using Shouldly; +using Xunit; +using ZB.MOM.WW.OtOpcUa.Core.Abstractions; +using ZB.MOM.WW.OtOpcUa.Core.OpcUa; + +namespace ZB.MOM.WW.OtOpcUa.Core.Tests; + +[Trait("Category", "Unit")] +public sealed class GenericDriverNodeManagerTests +{ + /// + /// BuildAddressSpaceAsync walks the driver's discovery through the caller's builder. Every + /// variable marked with MarkAsAlarmCondition captures its sink in the node manager; later, + /// IAlarmSource.OnAlarmEvent payloads are routed by SourceNodeId to the matching sink. + /// This is the plumbing that PR 16's concrete OPC UA builder will use to update the actual + /// AlarmConditionState nodes. + /// + [Fact] + public async Task Alarm_events_are_routed_to_the_sink_registered_for_the_matching_source_node_id() + { + var driver = new FakeDriver(); + var builder = new RecordingBuilder(); + using var nm = new GenericDriverNodeManager(driver); + + await nm.BuildAddressSpaceAsync(builder, CancellationToken.None); + + builder.Alarms.Count.ShouldBe(2); + nm.TrackedAlarmSources.Count.ShouldBe(2); + + // Simulate the driver raising a transition for one of the alarms. + var args = new AlarmEventArgs( + SubscriptionHandle: new FakeHandle("s1"), + SourceNodeId: "Tank.HiHi", + ConditionId: "cond-1", + AlarmType: "Tank.HiHi", + Message: "Level exceeded", + Severity: AlarmSeverity.High, + SourceTimestampUtc: DateTime.UtcNow); + driver.RaiseAlarm(args); + + builder.Alarms["Tank.HiHi"].Received.Count.ShouldBe(1); + builder.Alarms["Tank.HiHi"].Received[0].Message.ShouldBe("Level exceeded"); + // The other alarm sink never received a payload — fan-out is tag-scoped. + builder.Alarms["Heater.OverTemp"].Received.Count.ShouldBe(0); + } + + [Fact] + public async Task Non_alarm_variables_do_not_register_sinks() + { + var driver = new FakeDriver(); + var builder = new RecordingBuilder(); + using var nm = new GenericDriverNodeManager(driver); + + await nm.BuildAddressSpaceAsync(builder, CancellationToken.None); + + // FakeDriver registers 2 alarm-bearing variables + 1 plain variable. + nm.TrackedAlarmSources.ShouldNotContain("Tank.Level"); // the plain one + } + + [Fact] + public async Task Unknown_source_node_id_is_dropped_silently() + { + var driver = new FakeDriver(); + var builder = new RecordingBuilder(); + using var nm = new GenericDriverNodeManager(driver); + await nm.BuildAddressSpaceAsync(builder, CancellationToken.None); + + driver.RaiseAlarm(new AlarmEventArgs( + new FakeHandle("s1"), "Unknown.Source", "c", "t", "m", AlarmSeverity.Low, DateTime.UtcNow)); + + builder.Alarms.Values.All(s => s.Received.Count == 0).ShouldBeTrue(); + } + + [Fact] + public async Task Dispose_unsubscribes_from_OnAlarmEvent() + { + var driver = new FakeDriver(); + var builder = new RecordingBuilder(); + var nm = new GenericDriverNodeManager(driver); + await nm.BuildAddressSpaceAsync(builder, CancellationToken.None); + + nm.Dispose(); + + driver.RaiseAlarm(new AlarmEventArgs( + new FakeHandle("s1"), "Tank.HiHi", "c", "t", "m", AlarmSeverity.Low, DateTime.UtcNow)); + + // No sink should have received it — the forwarder was detached. + builder.Alarms["Tank.HiHi"].Received.Count.ShouldBe(0); + } + + // --- test doubles --- + + private sealed class FakeDriver : IDriver, ITagDiscovery, IAlarmSource + { + public string DriverInstanceId => "fake"; + public string DriverType => "Fake"; + public event EventHandler? OnAlarmEvent; + + public Task InitializeAsync(string driverConfigJson, CancellationToken ct) => Task.CompletedTask; + public Task ReinitializeAsync(string driverConfigJson, CancellationToken ct) => Task.CompletedTask; + public Task ShutdownAsync(CancellationToken ct) => Task.CompletedTask; + public DriverHealth GetHealth() => new(DriverState.Healthy, DateTime.UtcNow, null); + public long GetMemoryFootprint() => 0; + public Task FlushOptionalCachesAsync(CancellationToken ct) => Task.CompletedTask; + + public Task DiscoverAsync(IAddressSpaceBuilder builder, CancellationToken ct) + { + var folder = builder.Folder("Tank", "Tank"); + var lvl = folder.Variable("Level", "Level", new DriverAttributeInfo( + "Tank.Level", DriverDataType.Float64, false, null, SecurityClassification.FreeAccess, false, IsAlarm: false)); + var hiHi = folder.Variable("HiHi", "HiHi", new DriverAttributeInfo( + "Tank.HiHi", DriverDataType.Boolean, false, null, SecurityClassification.FreeAccess, false, IsAlarm: true)); + hiHi.MarkAsAlarmCondition(new AlarmConditionInfo("Tank.HiHi", AlarmSeverity.High, "High-high alarm")); + + var heater = builder.Folder("Heater", "Heater"); + var ot = heater.Variable("OverTemp", "OverTemp", new DriverAttributeInfo( + "Heater.OverTemp", DriverDataType.Boolean, false, null, SecurityClassification.FreeAccess, false, IsAlarm: true)); + ot.MarkAsAlarmCondition(new AlarmConditionInfo("Heater.OverTemp", AlarmSeverity.Critical, "Over-temperature")); + return Task.CompletedTask; + } + + public void RaiseAlarm(AlarmEventArgs args) => OnAlarmEvent?.Invoke(this, args); + + public Task SubscribeAlarmsAsync(IReadOnlyList _, CancellationToken __) + => Task.FromResult(new FakeHandle("sub")); + public Task UnsubscribeAlarmsAsync(IAlarmSubscriptionHandle _, CancellationToken __) => Task.CompletedTask; + public Task AcknowledgeAsync(IReadOnlyList _, CancellationToken __) => Task.CompletedTask; + } + + private sealed class FakeHandle(string diagnosticId) : IAlarmSubscriptionHandle + { + public string DiagnosticId { get; } = diagnosticId; + } + + private sealed class RecordingBuilder : IAddressSpaceBuilder + { + public Dictionary Alarms { get; } = new(StringComparer.OrdinalIgnoreCase); + + public IAddressSpaceBuilder Folder(string _, string __) => this; + + public IVariableHandle Variable(string _, string __, DriverAttributeInfo info) + => new Handle(info.FullName, Alarms); + + public void AddProperty(string _, DriverDataType __, object? ___) { } + + public sealed class Handle(string fullRef, Dictionary alarms) : IVariableHandle + { + public string FullReference { get; } = fullRef; + public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo _) + { + var sink = new RecordingSink(); + alarms[FullReference] = sink; + return sink; + } + } + + public sealed class RecordingSink : IAlarmConditionSink + { + public List Received { get; } = new(); + public void OnTransition(AlarmEventArgs args) => Received.Add(args); + } + } +} diff --git a/tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.E2E/RecordingAddressSpaceBuilder.cs b/tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.E2E/RecordingAddressSpaceBuilder.cs index b6a1d08..461e421 100644 --- a/tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.E2E/RecordingAddressSpaceBuilder.cs +++ b/tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.E2E/RecordingAddressSpaceBuilder.cs @@ -12,6 +12,7 @@ public sealed class RecordingAddressSpaceBuilder : IAddressSpaceBuilder public List Folders { get; } = new(); public List Variables { get; } = new(); public List Properties { get; } = new(); + public List AlarmConditions { get; } = new(); public IAddressSpaceBuilder Folder(string browseName, string displayName) { @@ -22,7 +23,7 @@ public sealed class RecordingAddressSpaceBuilder : IAddressSpaceBuilder public IVariableHandle Variable(string browseName, string displayName, DriverAttributeInfo attributeInfo) { Variables.Add(new RecordedVariable(browseName, displayName, attributeInfo)); - return new RecordedVariableHandle(attributeInfo.FullName); + return new RecordedVariableHandle(attributeInfo.FullName, AlarmConditions); } public void AddProperty(string browseName, DriverDataType dataType, object? value) @@ -33,6 +34,37 @@ public sealed class RecordingAddressSpaceBuilder : IAddressSpaceBuilder public sealed record RecordedFolder(string BrowseName, string DisplayName); public sealed record RecordedVariable(string BrowseName, string DisplayName, DriverAttributeInfo AttributeInfo); public sealed record RecordedProperty(string BrowseName, DriverDataType DataType, object? Value); + public sealed record RecordedAlarmCondition(string SourceNodeId, AlarmConditionInfo Info); + public sealed record RecordedAlarmTransition(string SourceNodeId, AlarmEventArgs Args); - private sealed record RecordedVariableHandle(string FullReference) : IVariableHandle; + /// + /// Sink the tests assert on to verify the alarm event forwarder routed a transition + /// to the correct source-node-id. One entry per . + /// + public List AlarmTransitions { get; } = new(); + + private sealed class RecordedVariableHandle : IVariableHandle + { + private readonly List _conditions; + public string FullReference { get; } + public RecordedVariableHandle(string fullReference, List conditions) + { + FullReference = fullReference; + _conditions = conditions; + } + + public IAlarmConditionSink MarkAsAlarmCondition(AlarmConditionInfo info) + { + _conditions.Add(new RecordedAlarmCondition(FullReference, info)); + return new RecordingSink(FullReference); + } + + private sealed class RecordingSink : IAlarmConditionSink + { + public string SourceNodeId { get; } + public List Received { get; } = new(); + public RecordingSink(string sourceNodeId) => SourceNodeId = sourceNodeId; + public void OnTransition(AlarmEventArgs args) => Received.Add(args); + } + } }