Merge feat/830-heidenhain-followups

This commit is contained in:
Joseph Doherty
2026-11-11 01:55:10 -05:00
33 changed files with 1802 additions and 82 deletions
@@ -0,0 +1,384 @@
using System.Buffers.Binary;
using System.Collections.Concurrent;
using System.Text;
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Driver.Heidenhain.Lsv2;
using ZB.MOM.WW.OtOpcUa.Driver.Heidenhain.Tests.Simulator;
namespace ZB.MOM.WW.OtOpcUa.Driver.Heidenhain.Tests;
/// <summary>
/// lmxopcua#831: controller alarms as native Part 9 conditions (<c>ALARM:</c> selectors + the <c>alarm</c> object),
/// local-only acknowledgement (nothing sent to the control), quality-only annotation of a failed walk, and the
/// identity-change rediscovery signal — against the in-process LSV2 simulator and the captured iTNC 530 alarm reply.
/// </summary>
[Trait("Category", "Unit")]
public sealed class HeidenhainAlarmTests
{
private static CancellationToken Ct => TestContext.Current.CancellationToken;
private const string Alarm = """, "alarm": {"alarmType": "AlarmCondition", "severity": 800}""";
private static RawTagEntry AlarmTag(string selector, string name, bool withAlarm = true) =>
new($"Plant/H/dev1/{name}",
$$"""{"address": "ALARM:{{selector}}", "dataType": "Boolean"{{(withAlarm ? Alarm : "")}}}""", false, "dev1");
// ---- selector grammar ----
[Theory]
[InlineData("*", "*")]
[InlineData("other", "OTHER")]
[InlineData("class=7", "CLASS=7")]
[InlineData("NUMBER=-5..-1/class=7", "CLASS=7/NUMBER=-5..-1")]
[InlineData("GROUP=4/NUMBER=100..199", "GROUP=4/NUMBER=100..199")]
public void Selector_grammar_accepts_and_canonicalises(string body, string canonical)
{
HeidenhainAlarmSelector.TryParse(body, out var s, out var error).ShouldBeTrue(error);
s!.Canonical.ShouldBe(canonical);
HeidenhainAddress.TryParse("ALARM:" + body, out var a, out _).ShouldBeTrue();
a!.Kind.ShouldBe(HeidenhainAddressKind.Alarm);
a.Text.ShouldBe("ALARM:" + canonical);
}
[Theory]
[InlineData("")]
[InlineData("CLASS")]
[InlineData("CLASS=x")]
[InlineData("CLASS=70000")]
[InlineData("CLASS=-1")]
[InlineData("NUMBER=5..1")]
[InlineData("CLASS=1/CLASS=2")]
[InlineData("TYPE=1")]
[InlineData("NUMBER=3000000000")]
public void Selector_grammar_refuses(string body)
{
HeidenhainAlarmSelector.TryParse(body, out _, out var error).ShouldBeFalse();
error.ShouldNotBeNullOrEmpty();
}
[Fact]
public void Selector_matching_and_negative_numbers()
{
HeidenhainAlarmSelector.TryParse("CLASS=7/NUMBER=-1", out var s, out _).ShouldBeTrue();
s!.Matches(7, 4, -1).ShouldBeTrue();
s.Matches(7, 4, 1).ShouldBeFalse();
s.Matches(6, 4, -1).ShouldBeFalse();
}
// ---- TagConfig pairing ----
[Fact]
public void An_alarm_selector_and_the_alarm_object_only_work_together()
{
HeidenhainTagDefinitionFactory.TryFromTagConfig("p", "d", AlarmTag("*", "a").TagConfig, out var def, out var error).ShouldBeTrue(error);
def!.IsAlarmCondition.ShouldBeTrue();
def.DataType.ShouldBe(DriverDataType.Boolean);
def.Alarm!.Severity.ShouldBe(800);
def.Group.ShouldBe(HeidenhainPollGroup.Alarm);
HeidenhainTagRules.ExpectedTagDataType(AlarmTag("*", "a").TagConfig).ShouldBe("Boolean");
HeidenhainTagDefinitionFactory.TryFromTagConfig("p", "d", AlarmTag("*", "a", withAlarm: false).TagConfig, out _, out error).ShouldBeFalse();
error!.ShouldContain("alarm");
HeidenhainTagDefinitionFactory.TryFromTagConfig("p", "d", """{"address":"Status/ExecutionState","alarm":{}}""", out _, out error).ShouldBeFalse();
error!.ShouldContain("not an ALARM: selector");
HeidenhainTagDefinitionFactory.TryFromTagConfig("p", "d", """{"address":"ALARM:*","dataType":"Int32","alarm":{}}""", out _, out _).ShouldBeFalse();
HeidenhainTagDefinitionFactory.TryFromTagConfig("p", "d", """{"address":"ALARM:*","isArray":true,"alarm":{}}""", out _, out _).ShouldBeFalse();
HeidenhainTagDefinitionFactory.Inspect(AlarmTag("*", "a").TagConfig).ShouldBeEmpty();
}
// ---- pure transition rules ----
private static HeidenhainAlarmTag Tag(string selector, int? severity = null) =>
new("Plant/H/dev1/a", "h:1", Parse(selector), severity);
private static HeidenhainAlarmSelector Parse(string body)
{
HeidenhainAlarmSelector.TryParse(body, out var s, out _).ShouldBeTrue();
return s!;
}
private static readonly IAlarmSubscriptionHandle H = new HeidenhainAlarmSubscriptionHandle(1);
[Fact]
public void Transitions_raise_retrigger_clear_and_ignore_reordering()
{
var tag = Tag("*", 900);
var a = new Lsv2Alarm(7, 4, -1, "Run test of cutout channels");
var b = new Lsv2Alarm(3, 1, 100, "Coolant low");
var all = new[] { tag.Selector };
var now = DateTime.UtcNow;
var (e1, t1) = HeidenhainAlarmRules.Transition(null, HeidenhainAlarmRules.Evaluate(tag.Selector, [a], all), tag, H, now);
e1!.Kind.ShouldBe(AlarmTransitionKind.Raise);
e1.ConditionId.ShouldBe(tag.RawPath);
e1.OpcUaSeverity.ShouldBe(900);
e1.Severity.ShouldBe(AlarmSeverity.Critical);
e1.Message.ShouldBe("-1 Run test of cutout channels (class 7, group 4)");
// unchanged → nothing
HeidenhainAlarmRules.Transition(t1, HeidenhainAlarmRules.Evaluate(tag.Selector, [a], all), tag, H, now).Event.ShouldBeNull();
// a new alarm (it also becomes the displayed one) → Retrigger
var (e2, t2) = HeidenhainAlarmRules.Transition(t1, HeidenhainAlarmRules.Evaluate(tag.Selector, [a, b], all), tag, H, now);
e2!.Kind.ShouldBe(AlarmTransitionKind.Retrigger);
e2.Message.ShouldBe("100 Coolant low (class 3, group 1) [+1 more]");
// the same set in another wire order → nothing (deterministic display order)
HeidenhainAlarmRules.Transition(t2, HeidenhainAlarmRules.Evaluate(tag.Selector, [b, a], all), tag, H, now).Event.ShouldBeNull();
// the displayed alarm leaves while another remains → Retrigger with the next one down
var (e3, t3) = HeidenhainAlarmRules.Transition(t2, HeidenhainAlarmRules.Evaluate(tag.Selector, [a], all), tag, H, now);
e3!.Kind.ShouldBe(AlarmTransitionKind.Retrigger);
var (e4, _) = HeidenhainAlarmRules.Transition(t3, [], tag, H, now);
e4!.Kind.ShouldBe(AlarmTransitionKind.Clear);
}
[Fact]
public void Other_is_what_no_filter_on_the_control_claims_and_severity_defaults_to_high()
{
var a = new Lsv2Alarm(7, 4, -1, "x");
var b = new Lsv2Alarm(3, 1, 100, "y");
var selectors = new[] { Parse("CLASS=7"), Parse("*"), Parse("OTHER") };
HeidenhainAlarmRules.Evaluate(Parse("OTHER"), [a, b], selectors).Select(k => k.Number).ShouldBe(new[] { 100 });
HeidenhainAlarmRules.Evaluate(Parse("*"), [a, b], selectors).Count.ShouldBe(2);
var (e, _) = HeidenhainAlarmRules.Transition(null, HeidenhainAlarmRules.Evaluate(Parse("OTHER"), [a, b], selectors),
Tag("OTHER"), H, DateTime.UtcNow);
e!.Severity.ShouldBe(AlarmSeverity.High);
e.OpcUaSeverity.ShouldBeNull();
}
// ---- end to end against the simulator ----
/// <summary>A control whose active-alarm list can be changed between walks (27 = first, 28 = next, 57 = end).</summary>
private sealed class AlarmList
{
private volatile byte[][] _records = [];
private int _cursor;
public void Set(params byte[][] records) => _records = records;
public void Install(SimulatedControl c)
{
c.Runtime[27] = () => { _cursor = 0; return Next(); };
c.Runtime[28] = Next;
}
private SimReply Next()
{
var r = _records;
return _cursor < r.Length ? SimReply.Ok("S_RI", r[_cursor++]) : SimReply.Refuse(57);
}
}
/// <summary>The captured iTNC 530 reply (Java fixture <c>hermle49.27</c>): class 7, group 4, number -1.</summary>
private static byte[] Golden() => SimReply.FromFixture(Fixtures.Load("itnc530-inspect.properties")["hermle49.27"]).Payload!;
private static byte[] Record(int cls, int group, int number, string text)
{
var t = Encoding.Latin1.GetBytes(text + "\0");
var b = new byte[8 + t.Length];
BinaryPrimitives.WriteUInt16BigEndian(b, (ushort)cls);
BinaryPrimitives.WriteUInt16BigEndian(b.AsSpan(2), (ushort)group);
BinaryPrimitives.WriteInt32BigEndian(b.AsSpan(4), number);
t.CopyTo(b, 8);
return b;
}
private static HeidenhainDriverOptions Options(int port, params RawTagEntry[] tags) => new()
{
Devices = [new HeidenhainDeviceOptions { Host = "127.0.0.1", Port = port, DeviceName = "dev1" }],
RawTags = tags,
TimeoutMs = 500,
Polling = new HeidenhainPollingOptions { StatusMs = 100, CustomMs = 100, SlowMs = 300, AlarmMs = 100 },
Reconnect = new HeidenhainReconnectOptions { InitialDelayMs = 100, MaxDelayMs = 200 },
};
private static HeidenhainDriver Create(HeidenhainDriverOptions o) =>
new(o, "hh-1", null, new HeidenhainCredentials(null), null, null);
private static async Task WaitUntil(Func<bool> condition, int timeoutMs = 5000)
{
var deadline = DateTime.UtcNow.AddMilliseconds(timeoutMs);
while (!condition())
{
if (DateTime.UtcNow > deadline) throw new TimeoutException("condition not reached");
await Task.Delay(20, Ct);
}
}
private static readonly string[] ReadOnlyCommands = ["A_LG", "R_VR", "R_PR", "R_RI", "R_MB", "R_DP"];
[Fact]
public async Task Golden_controller_alarm_raises_and_clears_conditions_with_only_allowlisted_reads()
{
var control = new SimulatedControl();
var list = new AlarmList();
list.Install(control);
list.Set(Golden());
await using var sim = Lsv2Simulator.WithControl(control);
var any = AlarmTag("*", "Any");
var cls7 = AlarmTag("CLASS=7", "Class7");
var cls1 = AlarmTag("CLASS=1", "Class1");
var other = AlarmTag("OTHER", "Other");
await using var d = Create(Options(sim.Port, any, cls7, cls1, other));
var events = new ConcurrentQueue<AlarmEventArgs>();
d.OnAlarmEvent += (_, e) => events.Enqueue(e);
await d.InitializeAsync("{}", Ct);
(await d.ReadAsync([any.RawPath], Ct))[0].StatusCode.ShouldBe(HeidenhainStatus.BadNotSupported); // a condition, not a value
await d.SubscribeAlarmsAsync([any.RawPath, cls7.RawPath, cls1.RawPath, other.RawPath], Ct);
await WaitUntil(() => events.Count(e => e.Kind == AlarmTransitionKind.Raise) >= 2);
await Task.Delay(400, Ct); // several more walks: an unchanged list re-raises nothing
var raises = events.Where(e => e.Kind == AlarmTransitionKind.Raise).ToList();
raises.Select(e => e.ConditionId).Order().ShouldBe(new[] { any.RawPath, cls7.RawPath }.Order());
raises.ShouldAllBe(e => e.Message == "-1 Run test of cutout channels (class 7, group 4)" && e.OpcUaSeverity == 800
&& e.SourceNodeId == $"127.0.0.1:{sim.Port}");
events.Count.ShouldBe(2);
list.Set();
await WaitUntil(() => events.Count(e => e.Kind == AlarmTransitionKind.Clear) == 2);
list.Set(Record(1, 2, 3, "Other alarm"), Golden());
await WaitUntil(() => events.Any(e => e.ConditionId == cls1.RawPath && e.Kind == AlarmTransitionKind.Raise));
await WaitUntil(() => events.Count(e => e.Kind == AlarmTransitionKind.Raise) == 5); // Any, Class7, Class1 again/new
events.ShouldNotContain(e => e.ConditionId == other.RawPath); // every alarm is claimed by a CLASS filter
// Read-only: only the allowlisted read set ever reached the wire, and every alarm walk is R_RI 27/28.
control.Violations.ShouldBeEmpty();
sim.Requests.Select(r => r.Command).Distinct().ShouldBeSubsetOf(ReadOnlyCommands);
sim.Requests.Where(r => r.Command == "R_RI").Select(r => r.Selector).Distinct().Order().ShouldBe(new[] { 27, 28 });
d.GetHealth().State.ShouldBe(DriverState.Healthy);
}
[Fact]
public async Task Acknowledge_is_local_only_and_never_touches_the_control()
{
var control = new SimulatedControl();
await using var sim = Lsv2Simulator.WithControl(control);
var any = AlarmTag("*", "Any");
await using var d = Create(Options(sim.Port, any));
await d.InitializeAsync("{}", Ct);
await d.AcknowledgeAsync([new AlarmAcknowledgeRequest($"127.0.0.1:{sim.Port}", any.RawPath, "seen", "op")], Ct);
await Task.Delay(200, Ct);
sim.Connections.ShouldBe(0); // no session was opened, so nothing at all was sent
sim.Requests.ShouldBeEmpty();
// And with a live session: the request log grows only by the poll's own allowlisted reads.
var list = new AlarmList();
list.Install(control);
list.Set(Golden());
await d.SubscribeAlarmsAsync([any.RawPath], Ct);
await WaitUntil(() => sim.Requests.Count(r => r.Command == "R_RI") >= 4);
await d.AcknowledgeAsync([new AlarmAcknowledgeRequest($"127.0.0.1:{sim.Port}", any.RawPath, "seen", "op")], Ct);
await Task.Delay(200, Ct);
sim.Requests.Select(r => r.Command).Distinct().ShouldBeSubsetOf(ReadOnlyCommands);
control.Violations.ShouldBeEmpty();
}
[Fact]
public async Task Comms_loss_annotates_quality_once_and_recovery_never_re_raises_an_active_condition()
{
var control = new SimulatedControl();
var list = new AlarmList();
list.Install(control);
list.Set(Golden());
await using var sim = Lsv2Simulator.WithControl(control);
var any = AlarmTag("*", "Any");
await using var d = Create(Options(sim.Port, any));
var events = new ConcurrentQueue<AlarmEventArgs>();
d.OnAlarmEvent += (_, e) => events.Enqueue(e);
await d.InitializeAsync("{}", Ct);
await d.SubscribeAlarmsAsync([any.RawPath], Ct);
await WaitUntil(() => events.Any(e => e.Kind == AlarmTransitionKind.Raise));
sim.GoOffline();
await WaitUntil(() => events.Any(e => e.QualityStatusCode == HeidenhainStatus.BadNoCommunication));
await WaitUntil(() => d.GetHealth().State == DriverState.Degraded);
await Task.Delay(500, Ct); // several failed reconnects: still ONE annotation
events.Count(e => e.IsQualityOnly && e.QualityStatusCode == HeidenhainStatus.BadNoCommunication).ShouldBe(1);
sim.GoOnline();
await WaitUntil(() => events.Any(e => e.IsQualityOnly && e.QualityStatusCode == HeidenhainStatus.Good), 8000);
await Task.Delay(400, Ct);
events.Count(e => e.Kind == AlarmTransitionKind.Raise).ShouldBe(1); // the same alarm is still active: no re-raise (no un-ack)
events.ShouldNotContain(e => e.Kind == AlarmTransitionKind.Retrigger || e.Kind == AlarmTransitionKind.Clear);
d.GetHealth().State.ShouldBe(DriverState.Healthy);
}
[Fact]
public async Task A_refused_alarm_walk_is_quality_only_and_does_not_degrade_health()
{
var control = new SimulatedControl();
control.Runtime[27] = () => SimReply.Refuse(49); // access denied
await using var sim = Lsv2Simulator.WithControl(control);
var any = AlarmTag("*", "Any");
await using var d = Create(Options(sim.Port, any));
var events = new ConcurrentQueue<AlarmEventArgs>();
d.OnAlarmEvent += (_, e) => events.Enqueue(e);
await d.InitializeAsync("{}", Ct);
await d.SubscribeAlarmsAsync([any.RawPath], Ct);
await WaitUntil(() => events.Any(e => e.QualityStatusCode == HeidenhainStatus.BadUserAccessDenied));
await Task.Delay(400, Ct);
events.ShouldAllBe(e => e.IsQualityOnly);
events.Count.ShouldBe(1);
d.GetHealth().State.ShouldBe(DriverState.Healthy);
}
[Fact]
public async Task Alarm_events_are_recorded_only_while_a_handler_listens()
{
var control = new SimulatedControl();
var list = new AlarmList();
list.Install(control);
list.Set(Golden());
await using var sim = Lsv2Simulator.WithControl(control);
var any = AlarmTag("*", "Any");
await using var d = Create(Options(sim.Port, any));
await d.InitializeAsync("{}", Ct);
await d.SubscribeAlarmsAsync([any.RawPath], Ct);
await WaitUntil(() => sim.Requests.Count(r => r.Command == "R_RI" && r.Selector == 27) >= 3);
var events = new ConcurrentQueue<AlarmEventArgs>();
d.OnAlarmEvent += (_, e) => events.Enqueue(e);
await WaitUntil(() => events.Any(e => e.Kind == AlarmTransitionKind.Raise)); // nothing was "told" while detached
}
// ---- rediscovery ----
[Fact]
public async Task A_reconnect_with_a_different_identity_raises_rediscovery_once()
{
var control = new SimulatedControl();
control.Runtime[23] = () => SimulatedControl.U16(4);
await using var sim = Lsv2Simulator.WithControl(control);
var tag = TestTags.Raw("Status/ExecutionState");
await using var d = Create(Options(sim.Port, tag));
var raised = new ConcurrentQueue<RediscoveryEventArgs>();
d.OnRediscoveryNeeded += (_, e) => raised.Enqueue(e);
await d.InitializeAsync("{}", Ct);
await d.SubscribeAsync([tag.RawPath], TimeSpan.FromMilliseconds(100), Ct);
await WaitUntil(() => d.GetHostStatuses().Single().State == HostState.Running);
var connections = sim.Connections;
// Same identity across a reconnect: baseline only, nothing raised.
sim.GoOffline();
await WaitUntil(() => d.GetHealth().State == DriverState.Degraded);
sim.GoOnline();
await WaitUntil(() => sim.Connections > connections && d.GetHealth().State == DriverState.Healthy, 8000);
raised.ShouldBeEmpty();
// NC software update while it was away.
control.Version = Encoding.Latin1.GetBytes("iTNC 530\0NC 340490 08\0PLC\0OPT\0");
connections = sim.Connections;
sim.GoOffline();
await WaitUntil(() => d.GetHealth().State == DriverState.Degraded);
sim.GoOnline();
await WaitUntil(() => !raised.IsEmpty, 8000);
await Task.Delay(300, Ct);
raised.Count.ShouldBe(1);
raised.Single().Reason.ShouldContain("340490 04");
raised.Single().Reason.ShouldContain("340490 08");
control.Violations.ShouldBeEmpty();
}
}
@@ -151,13 +151,26 @@ public sealed class HeidenhainDriverTests
sim.GoOffline();
// EVERY remote leaf — fast status, slow identity/alarms and custom PLC — goes Bad at once.
await WaitUntil(() => tags.Take(5).All(t => rec.Last(t.RawPath)?.StatusCode == HeidenhainStatus.BadNoCommunication));
rec.Last(tags[5].RawPath)!.Value.ShouldBe("CommunicationLost");
// The invalidation is ONE pass over the device's tags (in authored order, capability last), delivered to this
// thread's recorder as it runs — so wait for the WHOLE pass to land (the capability's CommunicationLost is
// its last publication) before asserting on any of it. Asserting the capability the instant the five value
// tags read Bad raced the pass's final publish (1/40 on 5bbe1e3c: "Supported").
await WaitUntil(() => tags.Take(5).All(t => rec.Last(t.RawPath)?.StatusCode == HeidenhainStatus.BadNoCommunication)
&& rec.Last(tags[5].RawPath)?.Value is "CommunicationLost");
rec.Last(tags[5].RawPath)!.StatusCode.ShouldBe(HeidenhainStatus.Good);
// ...and it is one pass: no remote value published Good again after its outage invalidation.
foreach (var t in tags.Take(5))
{
var seq = rec.For(t.RawPath).Select(s => s.StatusCode).ToList();
seq.Skip(seq.LastIndexOf(HeidenhainStatus.BadNoCommunication)).ShouldAllBe(s => s == HeidenhainStatus.BadNoCommunication);
}
(await d.ReadAsync([tags[2].RawPath], Ct))[0].StatusCode.ShouldBe(HeidenhainStatus.BadNoCommunication);
await WaitUntil(() => d.GetHealth().State == DriverState.Degraded);
// Degraded holds through every reconnect attempt (Backoff AND Connecting carry the last error), but the host
// status reads Stopped only in Backoff and Unknown while a reconnect attempt is in flight — so wait for the
// Backoff phase rather than sample whichever phase the loop happens to be in.
await WaitUntil(() => d.GetHealth().State == DriverState.Degraded && d.GetHostStatuses().Single().State == HostState.Stopped);
d.GetHealth().LastError.ShouldNotBeNullOrEmpty();
d.GetHostStatuses().Single().State.ShouldBe(HostState.Stopped);
hostEvents.ShouldContain(e => e.NewState == HostState.Stopped);
var frozen = d.GetHealth().LastSuccessfulRead;
await Task.Delay(500, Ct);