Files
T
Joseph Doherty d50ee809e3 feat(heidenhain): native read-only LSV2 driver + in-process simulator (#803)
Native LSV2 TCP transport (default port 19000; no Java/Python/vendor SDK), ported from
the ignitionoee v0.20.3 reference driver:

- Lsv2ReadOnlyPolicy: payload-aware outbound allowlist (A_LG INSPECT/DNC/DATA, R_VR, R_PR,
  R_RI 22-28/30-34/51, bounded R_MB, R_DP), applied in Lsv2Codec.Frame before any byte is
  written; no public raw-command API.
- Lsv2Client: serialized transactions, one monotonic deadline per transaction, EOF/oversize/
  unexpected/trickle close the client; Close never waits on the gate.
- Lsv2Data / HeidenhainBindingCodec: reference decoders, R_PR byte-capacity + element-index
  rules, next-area cap, DATA Boolean 00/01/FF, strict non-truncating coercion.
- HeidenhainSession: per-batch wire cache, refusal suppression, provisional DNC denial retry,
  alarm cursor (57 = end, overflow = BadOutOfRange), capability strings.
- HeidenhainDeviceRuntime: one loop per control, generation-guarded publication, all-node
  BadNoCommunication on comms loss, bounded exponential reconnect.
- HeidenhainDriver: cached ReadAsync, push subscriptions deduped on (value,status), static
  catalog discovery (no connect), host status, diagnostics, skipped-tag report. No IWritable.
- Probe (INSPECT login + version) and factory registered in DriverFactoryBootstrap (probe on
  admin nodes too); DriverTypeNames.Heidenhain.

Tests: 159 unit tests against an in-process LSV2 simulator incl. the Java fixtures' captured
iTNC 530 replies as golden vectors; env-gated LiveIntegration category for real hardware.
2026-11-10 23:08:30 -05:00

409 lines
20 KiB
C#

using System.Buffers.Binary;
using System.Text;
using Shouldly;
using Xunit;
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>Session read-policy regression ported from the reference <c>HeidenhainSessionTest</c>.</summary>
[Trait("Category", "Unit")]
public sealed class HeidenhainSessionTests
{
private static CancellationToken Ct => TestContext.Current.CancellationToken;
private sealed class Harness : IAsyncDisposable
{
public required Lsv2Simulator Sim { get; init; }
public required SimulatedControl Control { get; init; }
public required HeidenhainSession Session { get; init; }
public required IReadOnlyList<HeidenhainTagDefinition> Tags { get; init; }
public async Task<Dictionary<string, HeidenhainSample>> ReadAsync(params string[] addresses)
{
var tags = addresses.Select(a => Tags.First(t => t.Address.Text == a || t.RawPath.EndsWith("/" + a, StringComparison.Ordinal))).ToList();
var samples = await Session.ReadBatchAsync(tags, Ct);
var map = new Dictionary<string, HeidenhainSample>();
for (var i = 0; i < tags.Count; i++) map[addresses[i]] = samples[i];
return map;
}
public int RuntimeRequests(int? selector = null) =>
Sim.Requests.Count(r => r.Command == "R_RI" && (selector is null || r.Selector == selector));
public async ValueTask DisposeAsync()
{
await Session.DisposeAsync();
Control.Violations.ShouldBeEmpty();
await Sim.DisposeAsync();
}
}
private static async Task<Harness> OpenAsync(
SimulatedControl control, IReadOnlyList<HeidenhainTagDefinition> tags,
bool telemetry = true, bool dnc = true, bool data = false, int maxAlarms = 64, bool timers = false,
HeidenhainSession.PasswordSource? passwords = null)
{
var sim = Lsv2Simulator.WithControl(control);
var client = new Lsv2Client("127.0.0.1", sim.Port, TimeSpan.FromSeconds(1));
var settings = new HeidenhainSessionSettings(telemetry, dnc, data, maxAlarms, timers,
tags.Any(t => t.Address.Kind == HeidenhainAddressKind.Plc), tags.Any(t => t.Address.Kind == HeidenhainAddressKind.DataPath));
var session = new HeidenhainSession(client, settings, passwords ?? ((_, _) => ValueTask.FromResult("")));
await client.OpenAsync(Ct);
await session.InitializeAsync(Ct);
return new Harness { Sim = sim, Control = control, Session = session, Tags = tags };
}
private static List<HeidenhainTagDefinition> Standard(params string[] addresses) => addresses.Select(a => TestTags.Def(a)).ToList();
private static SimReply DenyDnc(string role, string _) => role == "DNC" ? SimReply.Refuse(23) : SimReply.Ok("T_OK", []);
[Fact]
public async Task Batch_shares_reads_and_preserves_unknown_native_state()
{
var c = new SimulatedControl();
var program = new byte[8];
BinaryPrimitives.WriteInt32BigEndian(program, 5);
"A\0B\0"u8.ToArray().CopyTo(program, 4);
c.Runtime[24] = () => SimReply.Ok("S_RI", program);
c.Runtime[25] = () => SimReply.Ok("S_RI", new byte[12]);
c.Runtime[23] = () => SimReply.Ok("S_RI", [1, 44]);
await using var h = await OpenAsync(c, Standard("Program/Main", "Program/Current", "Program/Line", "Overrides/Feed", "Overrides/Spindle", "Status/ExecutionState"));
var v = await h.ReadAsync("Program/Main", "Program/Current", "Program/Line", "Overrides/Feed", "Overrides/Spindle", "Status/ExecutionState");
v.Values.ShouldAllBe(s => s.Status == HeidenhainStatus.Good);
h.RuntimeRequests(24).ShouldBe(1);
h.RuntimeRequests(25).ShouldBe(1);
v["Status/ExecutionState"].Value.ShouldBe(300); // raw enum preserved, not mapped
v["Program/Line"].Value.ShouldBe(5L);
v["Program/Current"].Value.ShouldBe("B");
}
[Theory]
[InlineData(57, true)]
[InlineData(23, false)]
[InlineData(24, false)]
[InlineData(25, false)]
public async Task Only_refusal_57_proves_an_empty_alarm_list(int code, bool empty)
{
var c = new SimulatedControl();
c.Runtime[27] = () => SimReply.Refuse(code);
await using var h = await OpenAsync(c, Standard("Alarms/Count", "Alarms/Messages"));
var v = await h.ReadAsync("Alarms/Count", "Alarms/Messages");
if (empty)
{
v["Alarms/Count"].Value.ShouldBe(0);
v["Alarms/Messages"].Value.ShouldBe(Array.Empty<string>());
v["Alarms/Count"].Status.ShouldBe(HeidenhainStatus.Good);
}
else
{
v.Values.ShouldAllBe(s => s.Status != HeidenhainStatus.Good && s.Value == null);
}
}
private static SimReply AlarmRecord()
{
var b = new byte[10];
BinaryPrimitives.WriteInt16BigEndian(b, 3);
BinaryPrimitives.WriteInt16BigEndian(b.AsSpan(2), 4);
BinaryPrimitives.WriteInt32BigEndian(b.AsSpan(4), -1);
b[8] = 65;
return SimReply.Ok("S_RI", b);
}
[Theory]
[InlineData(1)]
[InlineData(2)]
public async Task Alarm_cursor_end_at_the_limit_is_good(int limit)
{
var c = new SimulatedControl();
c.Runtime[27] = AlarmRecord;
c.Runtime[28] = () => SimReply.Refuse(57);
await using var h = await OpenAsync(c, Standard("Alarms/Count", "Alarms/Numbers", "Alarms/Classes"), maxAlarms: limit);
var v = await h.ReadAsync("Alarms/Count", "Alarms/Numbers", "Alarms/Classes");
v["Alarms/Count"].Status.ShouldBe(HeidenhainStatus.Good);
v["Alarms/Count"].Value.ShouldBe(1);
v["Alarms/Numbers"].Value.ShouldBe(new[] { -1 });
v["Alarms/Classes"].Value.ShouldBe(new[] { 3 });
}
[Fact]
public async Task Alarm_limit_exhaustion_is_out_of_range_never_truncated()
{
var c = new SimulatedControl();
c.Runtime[27] = AlarmRecord;
c.Runtime[28] = AlarmRecord;
await using var h = await OpenAsync(c, Standard("Alarms/Count", "Alarms/Messages"), maxAlarms: 1);
var v = await h.ReadAsync("Alarms/Count", "Alarms/Messages");
v.Values.ShouldAllBe(s => s.Status == HeidenhainStatus.BadOutOfRange && s.Value == null);
}
[Fact]
public async Task Malformed_alarm_record_is_a_decoding_error_not_an_empty_list()
{
var c = new SimulatedControl();
c.Runtime[27] = () => SimReply.Ok("S_RI", [0, 0, 0, 0, 0, 0, 0, 0, 65]); // unterminated text
await using var h = await OpenAsync(c, Standard("Alarms/Count", "Capabilities/Alarms"));
var v = await h.ReadAsync("Alarms/Count", "Capabilities/Alarms");
v["Alarms/Count"].Status.ShouldBe(HeidenhainStatus.BadDecodingError);
v["Capabilities/Alarms"].Value.ShouldBe("InvalidData");
}
[Fact]
public async Task Denied_dnc_leaves_inspect_telemetry_available_and_honours_each_read_refusal()
{
var c = new SimulatedControl { Login = DenyDnc };
c.Runtime[23] = () => SimReply.Ok("S_RI", [0, 4]);
c.Runtime[25] = () => SimReply.Refuse(23);
await using var h = await OpenAsync(c, Standard("Controller/Model", "Status/ExecutionState", "Overrides/Feed", "Capabilities/DncLogin", "Capabilities/Overrides"));
var v = await h.ReadAsync("Controller/Model", "Status/ExecutionState", "Overrides/Feed", "Capabilities/DncLogin", "Capabilities/Overrides");
v["Controller/Model"].Status.ShouldBe(HeidenhainStatus.Good);
v["Status/ExecutionState"].Value.ShouldBe(4);
v["Overrides/Feed"].Status.ShouldBe(HeidenhainStatus.BadUserAccessDenied);
v["Capabilities/DncLogin"].Value.ShouldBe("AccessDenied");
v["Capabilities/Overrides"].Value.ShouldBe("AccessDenied");
h.RuntimeRequests().ShouldBe(2);
// a stable denial is suppressed for the rest of the session
(await h.ReadAsync("Overrides/Feed"))["Overrides/Feed"].Status.ShouldBe(HeidenhainStatus.BadUserAccessDenied);
h.RuntimeRequests().ShouldBe(2);
}
[Fact]
public async Task Telemetry_opt_out_prevents_every_runtime_request()
{
var c = new SimulatedControl();
c.Runtime[23] = () => SimReply.Ok("S_RI", [0, 4]);
await using var h = await OpenAsync(c, Standard("Status/ExecutionState", "Capabilities/Execution", "Capabilities/DncLogin"), telemetry: false);
var v = await h.ReadAsync("Status/ExecutionState", "Capabilities/Execution", "Capabilities/DncLogin");
v["Status/ExecutionState"].Status.ShouldBe(HeidenhainStatus.BadNotSupported);
v["Capabilities/Execution"].Value.ShouldBe("Disabled");
v["Capabilities/DncLogin"].Value.ShouldBe("Disabled");
h.RuntimeRequests().ShouldBe(0);
h.Control.Logins.Select(l => l.Role).ShouldBe(new[] { "INSPECT" });
}
[Fact]
public async Task Experimental_timers_are_disabled_by_default_and_never_requested()
{
var c = new SimulatedControl();
c.Runtime[30] = () => SimReply.Ok("S_RI", [0, 0, 0, 9]);
await using var h = await OpenAsync(c, Standard("Timers/NcUptime", "Capabilities/Timer_NcUptime"));
var v = await h.ReadAsync("Timers/NcUptime", "Capabilities/Timer_NcUptime");
v["Timers/NcUptime"].Status.ShouldBe(HeidenhainStatus.BadNotSupported);
v["Capabilities/Timer_NcUptime"].Value.ShouldBe("Disabled");
h.RuntimeRequests(30).ShouldBe(0);
}
[Fact]
public async Task Enabled_timers_read_raw_uint32()
{
var c = new SimulatedControl();
c.Runtime[34] = () => SimReply.Ok("S_RI", [0xFF, 0xFF, 0xFF, 0xFF]);
await using var h = await OpenAsync(c, Standard("Timers/Spindle1Runtime"), timers: true);
(await h.ReadAsync("Timers/Spindle1Runtime"))["Timers/Spindle1Runtime"].Value.ShouldBe(4294967295L);
}
[Fact]
public async Task Tool_without_geometry_is_not_supported_not_zero()
{
var c = new SimulatedControl();
c.Runtime[51] = () => SimReply.Ok("S_RI", [0, 0, 0, 7, 0, 1, 0, 2]);
await using var h = await OpenAsync(c, Standard("Tool/Number", "Tool/Index", "Tool/AxisCode", "Tool/Length", "Tool/Radius"));
var v = await h.ReadAsync("Tool/Number", "Tool/Index", "Tool/AxisCode", "Tool/Length", "Tool/Radius");
v["Tool/Number"].Value.ShouldBe(7L);
v["Tool/Index"].Value.ShouldBe(1);
v["Tool/AxisCode"].Value.ShouldBe(2);
v["Tool/Length"].Status.ShouldBe(HeidenhainStatus.BadNotSupported);
v["Tool/Length"].Value.ShouldBeNull();
v["Tool/Radius"].Status.ShouldBe(HeidenhainStatus.BadNotSupported);
}
[Theory]
[InlineData("hermle49")]
[InlineData("hermle59")]
public async Task Captured_inspect_only_replies_publish_typed_telemetry_after_dnc_denial(string machine)
{
var f = Fixtures.Load("itnc530-inspect.properties");
var c = new SimulatedControl { Login = DenyDnc };
foreach (var s in new[] { 22, 23, 24, 25, 26, 27, 28, 51 })
{
var reply = SimReply.FromFixture(f[$"{machine}.{s}"]);
c.Runtime[s] = () => reply;
}
string[] addresses = ["Status/ExecutionState", "Status/ProgramState", "Program/Main", "Axes/Names", "Axes/Positions",
"Alarms/Count", "Alarms/Messages", "Alarms/Classes", "Overrides/Feed", "Tool/Number"];
await using var h = await OpenAsync(c, Standard(addresses));
var v = await h.ReadAsync(addresses);
v["Status/ExecutionState"].Value.ShouldBe(4);
v["Status/ProgramState"].Value.ShouldBe(7);
((string)v["Program/Main"].Value!).ShouldStartWith("TNC:");
v["Axes/Names"].Value.ShouldBe(new[] { "X", "Y", "Z", "C", "a", "A" });
((double[])v["Axes/Positions"].Value!).Length.ShouldBe(6);
v["Alarms/Count"].Value.ShouldBe(1);
v["Alarms/Messages"].Value.ShouldBe(new[] { "Run test of cutout channels" });
v["Alarms/Classes"].Value.ShouldBe(new[] { 7 });
v["Overrides/Feed"].Status.ShouldBe(HeidenhainStatus.BadUserAccessDenied);
v["Tool/Number"].Status.ShouldBe(machine == "hermle49" ? HeidenhainStatus.BadNotSupported : HeidenhainStatus.Good);
}
[Fact]
public async Task Data_path_type_mismatch_is_bad_and_aliases_share_one_read()
{
var c = new SimulatedControl();
c.DataPaths["/x"] = SimReply.Ok("S_DP", [0, 0, 0, 3, 0, 0, 0, 42]);
var tags = new List<HeidenhainTagDefinition>
{
TestTags.Def("DATA:/x", "Int64", "Plant/H/dev1/A"),
TestTags.Def("DATA:/x", "String", "Plant/H/dev1/B"),
};
await using var h = await OpenAsync(c, tags, telemetry: false, data: true);
var samples = await h.Session.ReadBatchAsync(tags, Ct);
samples[0].Value.ShouldBe(42L);
samples[1].Status.ShouldBe(HeidenhainStatus.BadTypeMismatch);
h.Sim.Requests.Count(r => r.Command == "R_DP").ShouldBe(1);
h.Control.Logins.Select(l => l.Role).ShouldBe(new[] { "INSPECT", "DATA" });
}
[Fact]
public async Task Data_bindings_stay_disabled_until_data_access_is_enabled()
{
var c = new SimulatedControl();
c.DataPaths["/x"] = SimReply.Ok("S_DP", [0, 0, 0, 3, 0, 0, 0, 42]);
var tags = new List<HeidenhainTagDefinition> { TestTags.Def("DATA:/x", "Int64"), TestTags.Def("Capabilities/DataLogin") };
await using var h = await OpenAsync(c, tags, data: false);
var s = await h.Session.ReadBatchAsync(tags, Ct);
s[0].Status.ShouldBe(HeidenhainStatus.BadNotSupported);
s[1].Value.ShouldBe("Disabled");
h.Sim.Requests.ShouldNotContain(r => r.Command == "R_DP");
h.Control.Logins.ShouldNotContain(l => l.Role == "DATA");
}
[Fact]
public async Task Transport_failure_invalidates_the_batch_and_close_prevents_good_reads()
{
var c = new SimulatedControl();
c.Runtime[23] = SimReply.Drop;
var tags = Standard("Controller/Model", "Status/ExecutionState", "Capabilities/Identity");
await using var h = await OpenAsync(c, tags);
var v = await h.ReadAsync("Controller/Model", "Status/ExecutionState", "Capabilities/Identity");
h.Session.CommunicationLost.ShouldBeTrue();
v["Controller/Model"].Status.ShouldBe(HeidenhainStatus.BadNoCommunication);
v["Status/ExecutionState"].Status.ShouldBe(HeidenhainStatus.BadNoCommunication);
v["Capabilities/Identity"].Value.ShouldBe("CommunicationLost");
await h.Session.DisposeAsync();
(await h.ReadAsync("Controller/Model"))["Controller/Model"].Status.ShouldBe(HeidenhainStatus.BadNoCommunication);
}
[Theory]
[InlineData("DNC")]
[InlineData("DATA")]
public async Task Temporary_optional_login_refusal_retries_with_a_fresh_credential(string role)
{
var attempts = 0;
var c = new SimulatedControl
{
Login = (r, pw) => r == role && Interlocked.Increment(ref attempts) == 1 ? SimReply.Refuse(25) : SimReply.Ok("T_OK", []),
};
c.Runtime[23] = () => SimReply.Ok("S_RI", [0, 3]);
c.DataPaths["/x"] = SimReply.Ok("S_DP", [0, 0, 0, 3, 0, 0, 0, 42]);
var resolved = 0;
var tags = role == "DATA" ? [TestTags.Def("DATA:/x", "Int64")] : Standard("Status/ExecutionState");
await using var h = await OpenAsync(c, tags, data: true,
passwords: (r, _) => { if (r == role) Interlocked.Increment(ref resolved); return ValueTask.FromResult("fresh"); });
var s = await h.Session.ReadBatchAsync(tags, Ct);
s[0].Status.ShouldBe(HeidenhainStatus.Good);
attempts.ShouldBe(2);
resolved.ShouldBe(2); // resolved on demand for each login — never cached
h.Control.Logins.Where(l => l.Role == role).ShouldAllBe(l => l.Password == "fresh");
}
[Theory]
[InlineData(false)]
[InlineData(true)]
public async Task Temporary_or_malformed_layout_recovers_and_aliases_read_once_per_batch(bool malformed)
{
var layouts = 0;
var c = new SimulatedControl
{
Intercept = r => r.Command == "R_PR" && Interlocked.Increment(ref layouts) == 1
? (malformed ? SimReply.Ok("S_PR", new byte[1]) : SimReply.Refuse(25))
: null,
Memory = (_, n) => SimReply.Ok("S_MB", [42, 0, 0, 0]),
};
var tags = new List<HeidenhainTagDefinition>
{
TestTags.Def("PLC:DWORD:0", "Int64", "Plant/H/dev1/A"),
TestTags.Def("PLC:DWORD:0", "Int32", "Plant/H/dev1/B"),
};
await using var h = await OpenAsync(c, tags, telemetry: false);
var s = await h.Session.ReadBatchAsync(tags, Ct);
s.ShouldAllBe(x => x.Status == HeidenhainStatus.Good);
s[0].Value.ShouldBe(42L);
s[1].Value.ShouldBe(42);
layouts.ShouldBe(2);
h.Sim.Requests.Count(r => r.Command == "R_MB").ShouldBe(1);
}
[Fact]
public async Task Plc_binding_outside_the_advertised_region_is_out_of_range_without_a_wire_read()
{
var c = new SimulatedControl { Memory = (_, _) => SimReply.Ok("S_MB", [0, 0]) };
var tags = new List<HeidenhainTagDefinition> { TestTags.Def("PLC:WORD:5", "Int32"), TestTags.Def("PLC:WORD:4", "Int32") };
await using var h = await OpenAsync(c, tags, telemetry: false);
var s = await h.Session.ReadBatchAsync(tags, Ct);
s[0].Status.ShouldBe(HeidenhainStatus.BadOutOfRange);
s[1].Status.ShouldBe(HeidenhainStatus.Good);
var mb = h.Sim.Requests.Single(r => r.Command == "R_MB");
BinaryPrimitives.ReadUInt32BigEndian(mb.Payload).ShouldBe(1008u);
mb.Payload[4].ShouldBe((byte)2);
}
[Fact]
public async Task Plc_memory_denial_is_access_denied_and_suppressed()
{
var c = new SimulatedControl(); // R_MB → T_ER 23, as on all four tested iTNC 530 controls
var tags = new List<HeidenhainTagDefinition> { TestTags.Def("PLC:WORD:1", "Int32") };
await using var h = await OpenAsync(c, tags, telemetry: false);
(await h.Session.ReadBatchAsync(tags, Ct))[0].Status.ShouldBe(HeidenhainStatus.BadUserAccessDenied);
(await h.Session.ReadBatchAsync(tags, Ct))[0].Status.ShouldBe(HeidenhainStatus.BadUserAccessDenied);
h.Sim.Requests.Count(r => r.Command == "R_MB").ShouldBe(1);
}
[Fact]
public async Task Repeated_transient_dnc_failures_cannot_permanently_suppress_telemetry()
{
var logins = 0;
var c = new SimulatedControl
{
Login = (r, _) => r == "DNC" && Interlocked.Increment(ref logins) <= 2 ? SimReply.Refuse(25) : SimReply.Ok("T_OK", []),
};
c.Runtime[23] = () => logins < 3 ? SimReply.Refuse(23) : SimReply.Ok("S_RI", [0, 4]);
c.Runtime[26] = () => logins < 3 ? SimReply.Refuse(23) : SimReply.Ok("S_RI", [0, 7]);
await using var h = await OpenAsync(c, Standard("Status/ExecutionState", "Status/ProgramState"));
(await h.ReadAsync("Status/ExecutionState", "Status/ProgramState")).Values
.ShouldAllBe(s => s.Status == HeidenhainStatus.BadUserAccessDenied);
var recovered = await h.ReadAsync("Status/ExecutionState", "Status/ProgramState");
recovered["Status/ExecutionState"].Value.ShouldBe(4);
recovered["Status/ProgramState"].Value.ShouldBe(7);
logins.ShouldBe(3);
}
[Fact]
public async Task Every_request_the_session_emits_is_allowlisted()
{
var c = new SimulatedControl();
foreach (var s in new[] { 22, 23, 24, 25, 26, 51 }) c.Runtime[s] = () => SimReply.Refuse(24);
c.Runtime[27] = () => SimReply.Refuse(57);
var tags = HeidenhainCatalog.Entries.Select(e => TestTags.Def(e.Address)).ToList();
tags.Add(TestTags.Def("PLC:WORD:1", "Int32"));
await using var h = await OpenAsync(c, tags, timers: true);
await h.Session.ReadBatchAsync(tags, Ct);
await h.Session.ReadBatchAsync(tags, Ct);
h.Sim.Requests.Select(r => r.Command).Distinct().ShouldBeSubsetOf(new[] { "A_LG", "R_VR", "R_PR", "R_RI", "R_MB" });
h.Sim.Requests.Where(r => r.Command == "A_LG").Select(r => Encoding.Latin1.GetString(r.Payload).Split('\0')[0])
.ShouldBeSubsetOf(new[] { "INSPECT", "DNC", "DATA" });
}
}