dohertj2/lmxopcua
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(twincat): opt-in ADS sum-read and /hosts diagnostics bag; refresh TwinCAT backlog (#645, #612)

Browse Source 
Sum-read (#310): batches a poll's reads per device into sum commands capped at sumReadMaxItems,
per-item ADS errors mapped per tag, falls back to individual reads when the target refuses the
command. Diagnostics (#314): ADS state, app name, online-change count, task cycle/exec/jitter via
IDriverDiagnostics. Re-implemented against the current raw-byte read path (stranded auto/driver-gaps
commits predate it). Sum-write not ported. Unit tests only; live gate pending a route.

Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
This commit is contained in:
Joseph Doherty
2026-10-08 19:18:42 -04:00
parent 8801631739
commit af19db4ed1
15 changed files with 1055 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/FakeTwinCATClient.cs
+37
View File
@@ -71,12 +71,49 @@ internal class FakeTwinCATClient : ITwinCATClient
string symbolPath, TwinCATDataType type, int? bitIndex, int? arrayCount, CancellationToken ct)
{
if (ThrowOnRead) throw Exception ?? new InvalidOperationException();
SingleReadCount++;
LastReadArrayCount = arrayCount;
var status = ReadStatuses.TryGetValue(symbolPath, out var s) ? s : TwinCATStatusMapper.Good;
var value = Values.TryGetValue(symbolPath, out var v) ? v : null;
return Task.FromResult((value, status));
}
/// <summary>Gets the number of individual <see cref="ReadValueAsync"/> calls served.</summary>
public int SingleReadCount { get; private set; }
/// <summary>Gets the size of each <see cref="ReadValuesAsync"/> batch the driver issued, in order (#645).</summary>
public List<int> SumReadBatches { get; } = new();
/// <summary>Gets or sets an exception <see cref="ReadValuesAsync"/> throws instead of answering — a
/// <see cref="TwinCATSumReadRefusedException"/> models a target without sum commands.</summary>
public Exception? SumReadException { get; set; }
/// <summary>Gets or sets the ADS state text <see cref="ReadAdsStateAsync"/> returns.</summary>
public string? AdsStateText { get; set; }
/// <summary>Simulates an ADS sum-read: records the batch size, then answers each item from the same
/// tables the single read uses.</summary>
/// <param name="reads">The batch.</param>
/// <param name="ct">The cancellation token.</param>
/// <returns>One outcome per item.</returns>
public virtual Task<IReadOnlyList<(object? value, uint status)>> ReadValuesAsync(
IReadOnlyList<TwinCATBulkReadItem> reads, CancellationToken ct)
{
if (ThrowOnRead) throw Exception ?? new InvalidOperationException();
SumReadBatches.Add(reads.Count);
if (SumReadException is { } ex) throw ex;
var results = new (object? value, uint status)[reads.Count];
for (var i = 0; i < reads.Count; i++)
{
var path = reads[i].SymbolPath;
results[i] = (Values.TryGetValue(path, out var v) ? v : null,
ReadStatuses.TryGetValue(path, out var s) ? s : TwinCATStatusMapper.Good);
}
return Task.FromResult<IReadOnlyList<(object? value, uint status)>>(results);
}
/// <summary>Simulates reading the ADS device state.</summary>
/// <param name="ct">The cancellation token.</param>
/// <returns>The configured state text.</returns>
public virtual Task<string?> ReadAdsStateAsync(CancellationToken ct) => Task.FromResult(AdsStateText);
/// <summary>Simulates writing a value to a symbol.</summary>
/// <param name="symbolPath">The path to the symbol to write.</param>
/// <param name="type">The data type of the symbol.</param>
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/TwinCATDiagnosticsTests.cs
+148
View File
@@ -0,0 +1,148 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
/// <summary>Gitea #645 / #314 — PLC state / task-cycle facts on the optional IDriverDiagnostics bag.</summary>
[Trait("Category", "Unit")]
public sealed class TwinCATDiagnosticsTests
{
private const string Host1 = "ads://5.23.91.23.1.1:851";
private const string Host2 = "ads://5.23.91.24.1.1:851";
private static TwinCATDriver NewDriver(FakeTwinCATClientFactory factory, bool probe, params (string host, string? name)[] devices) =>
new(new TwinCATDriverOptions
{
Devices = [.. devices.Select(d => new TwinCATDeviceOptions(d.host, d.name))],
Probe = new TwinCATProbeOptions { Enabled = probe, Interval = TimeSpan.FromMilliseconds(20) },
}, "drv-diag", factory);
private static FakeTwinCATClient PlcClient() => new()
{
AdsStateText = "Run",
Values =
{
[TwinCATDriver.SymAppName] = "Plc30 App",
[TwinCATDriver.SymOnlineChangeCnt] = 7u,
[TwinCATDriver.SymCycleTime] = 100_000u, // 10.0 ms
[TwinCATDriver.SymLastExecTime] = 25_000u, // 2.5 ms
},
};
private static async Task Sample(TwinCATDriver drv, FakeTwinCATClient client, string host)
{
var state = drv.GetDeviceState(host)!;
await drv.SampleDeviceDiagnosticsAsync(state, client, CancellationToken.None);
}
/// <summary>Verifies the driver advertises the optional capability and is empty before any sample.</summary>
[Fact]
public async Task Bag_is_empty_before_the_first_sample()
{
var drv = NewDriver(new FakeTwinCATClientFactory(), false, (Host1, null));
await drv.InitializeAsync("{}", CancellationToken.None);
var diag = drv.ShouldBeAssignableTo<IDriverDiagnostics>()!;
diag.GetDiagnostics().ShouldBeEmpty();
}
/// <summary>Verifies a single-device driver publishes flat keys with state, app, cycle, exec and jitter.</summary>
[Fact]
public async Task Single_device_publishes_flat_keys()
{
var drv = NewDriver(new FakeTwinCATClientFactory(), false, (Host1, null));
await drv.InitializeAsync("{}", CancellationToken.None);
await Sample(drv, PlcClient(), Host1);
var bag = ((IDriverDiagnostics)drv).GetDiagnostics();
bag["TwinCAT.AdsState"].ShouldBe("Run");
bag["TwinCAT.AppName"].ShouldBe("Plc30 App");
bag["TwinCAT.OnlineChangeCnt"].ShouldBe("7");
bag["TwinCAT.CycleTimeMs"].ShouldBe("10.0");
bag["TwinCAT.LastExecTimeMs"].ShouldBe("2.5");
bag["TwinCAT.JitterMs"].ShouldBe("-7.5");
DriverDiagnostics.Bound(bag).Count.ShouldBe(bag.Count); // within the host's 16-entry cap
}
/// <summary>Verifies several devices are told apart by device name, falling back to host address.</summary>
[Fact]
public async Task Multiple_devices_are_prefixed()
{
var drv = NewDriver(new FakeTwinCATClientFactory(), false, (Host1, "Elma01"), (Host2, null));
await drv.InitializeAsync("{}", CancellationToken.None);
await Sample(drv, PlcClient(), Host1);
await Sample(drv, PlcClient(), Host2);
var bag = ((IDriverDiagnostics)drv).GetDiagnostics();
bag["TwinCAT.Elma01.AdsState"].ShouldBe("Run");
bag[$"TwinCAT.{Host2}.CycleTimeMs"].ShouldBe("10.0");
bag.ContainsKey("TwinCAT.AdsState").ShouldBeFalse();
}
/// <summary>Verifies a runtime without _TaskInfo (older TwinCAT 2) still yields the facts it has, and
/// the missing symbols are asked for once, not on every probe tick.</summary>
[Fact]
public async Task Missing_task_info_gives_a_partial_bag_and_is_not_re_asked()
{
var drv = NewDriver(new FakeTwinCATClientFactory(), false, (Host1, null));
await drv.InitializeAsync("{}", CancellationToken.None);
var client = new FakeTwinCATClient { AdsStateText = "Run" };
client.Values[TwinCATDriver.SymAppName] = "Plc1";
client.ReadStatuses[TwinCATDriver.SymCycleTime] = TwinCATStatusMapper.BadNodeIdUnknown;
client.ReadStatuses[TwinCATDriver.SymLastExecTime] = TwinCATStatusMapper.BadNodeIdUnknown;
client.ReadStatuses[TwinCATDriver.SymOnlineChangeCnt] = TwinCATStatusMapper.BadNodeIdUnknown;
await Sample(drv, client, Host1);
var readsAfterFirst = client.SingleReadCount;
await Sample(drv, client, Host1);
var bag = ((IDriverDiagnostics)drv).GetDiagnostics();
bag["TwinCAT.AdsState"].ShouldBe("Run");
bag["TwinCAT.AppName"].ShouldBe("Plc1");
bag.Keys.ShouldNotContain("TwinCAT.CycleTimeMs");
bag.Keys.ShouldNotContain("TwinCAT.JitterMs");
client.SingleReadCount.ShouldBe(readsAfterFirst + 1); // only AppName is read again
}
/// <summary>Verifies a failed sample keeps the previous snapshot rather than blanking the bag.</summary>
[Fact]
public async Task Failed_sample_keeps_the_last_values()
{
var drv = NewDriver(new FakeTwinCATClientFactory(), false, (Host1, null));
await drv.InitializeAsync("{}", CancellationToken.None);
var client = PlcClient();
await Sample(drv, client, Host1);
client.ThrowOnRead = true;
client.AdsStateText = null;
await Sample(drv, client, Host1);
var bag = ((IDriverDiagnostics)drv).GetDiagnostics();
bag["TwinCAT.CycleTimeMs"].ShouldBe("10.0");
bag["TwinCAT.AdsState"].ShouldBe("Run");
}
/// <summary>Verifies the probe loop itself fills the bag — no manual sampling.</summary>
[Fact]
public async Task Probe_loop_populates_the_bag()
{
var factory = new FakeTwinCATClientFactory { Customise = PlcClient };
var drv = NewDriver(factory, true, (Host1, null));
await drv.InitializeAsync("{}", CancellationToken.None);
try
{
IReadOnlyDictionary<string, string> bag = new Dictionary<string, string>();
for (var i = 0; i < 100 && bag.Count == 0; i++)
{
await Task.Delay(50);
bag = ((IDriverDiagnostics)drv).GetDiagnostics();
}
bag["TwinCAT.OnlineChangeCnt"].ShouldBe("7");
}
finally { await drv.ShutdownAsync(CancellationToken.None); }
}
}
tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/TwinCATSumReadTests.cs
+237
View File
@@ -0,0 +1,237 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
/// <summary>Gitea #645 / #310 — a poll's reads batched into ADS sum-read commands, with per-item status,
/// a chunk cap and a fallback to individual reads when the target refuses the command.</summary>
[Trait("Category", "Unit")]
public sealed class TwinCATSumReadTests
{
private const string Host = "ads://5.23.91.23.1.1:851";
private static TwinCATTagDefinition Tag(string name, TwinCATDataType type = TwinCATDataType.DInt) =>
new(name, Host, "MAIN." + name, type);
private static (TwinCATDriver drv, FakeTwinCATClientFactory factory) NewDriver(
bool useSumRead, int maxItems, params TwinCATTagDefinition[] tags)
{
var factory = new FakeTwinCATClientFactory();
var drv = new TwinCATDriver(new TwinCATDriverOptions
{
Devices = [new TwinCATDeviceOptions(Host)],
RawTags = TwinCATRawTags.Entries(tags),
Probe = new TwinCATProbeOptions { Enabled = false },
UseSumRead = useSumRead,
SumReadMaxItems = maxItems,
}, "drv-sum", factory);
return (drv, factory);
}
private static FakeTwinCATClient Seeded(params (string symbol, object value)[] values)
{
var c = new FakeTwinCATClient();
foreach (var (symbol, value) in values) c.Values[symbol] = value;
return c;
}
/// <summary>Verifies that sum-read is opt-in: off, every tag is read on its own.</summary>
[Fact]
public async Task Disabled_reads_each_tag_individually()
{
var (drv, factory) = NewDriver(false, 200, Tag("A"), Tag("B"), Tag("C"));
await drv.InitializeAsync("{}", CancellationToken.None);
factory.Customise = () => Seeded(("MAIN.A", 1), ("MAIN.B", 2), ("MAIN.C", 3));
var snaps = await drv.ReadAsync(["A", "B", "C"], CancellationToken.None);
snaps.Select(s => s.Value).ShouldBe([1, 2, 3]);
factory.Clients[0].SumReadBatches.ShouldBeEmpty();
factory.Clients[0].SingleReadCount.ShouldBe(3);
}
/// <summary>Verifies that one poll's tags go out as a single sum command, values in request order.</summary>
[Fact]
public async Task Enabled_batches_a_poll_into_one_sum_command()
{
var (drv, factory) = NewDriver(true, 200, Tag("A"), Tag("B"), Tag("C"));
await drv.InitializeAsync("{}", CancellationToken.None);
factory.Customise = () => Seeded(("MAIN.A", 1), ("MAIN.B", 2), ("MAIN.C", 3));
var snaps = await drv.ReadAsync(["C", "A", "B"], CancellationToken.None);
snaps.Select(s => s.Value).ShouldBe([3, 1, 2]);
snaps.ShouldAllBe(s => s.StatusCode == TwinCATStatusMapper.Good);
factory.Clients[0].SumReadBatches.ShouldBe([3]);
factory.Clients[0].SingleReadCount.ShouldBe(0);
}
/// <summary>Verifies that one item's error code lands on that tag only.</summary>
[Fact]
public async Task Per_item_error_code_is_mapped_to_that_tag_only()
{
var (drv, factory) = NewDriver(true, 200, Tag("A"), Tag("B"), Tag("C"));
await drv.InitializeAsync("{}", CancellationToken.None);
factory.Customise = () =>
{
var c = Seeded(("MAIN.A", 1), ("MAIN.C", 3));
c.ReadStatuses["MAIN.B"] = TwinCATStatusMapper.BadNodeIdUnknown; // ADS 1808 DeviceSymbolNotFound
return c;
};
var snaps = await drv.ReadAsync(["A", "B", "C"], CancellationToken.None);
snaps[0].StatusCode.ShouldBe(TwinCATStatusMapper.Good);
snaps[1].StatusCode.ShouldBe(TwinCATStatusMapper.BadNodeIdUnknown);
snaps[1].Value.ShouldBeNull();
snaps[2].StatusCode.ShouldBe(TwinCATStatusMapper.Good);
snaps[2].Value.ShouldBe(3);
}
/// <summary>Verifies the size cap: a bigger poll splits into chunks and a lone remainder reads singly.</summary>
[Fact]
public async Task Poll_larger_than_the_cap_is_split_into_chunks()
{
var tags = Enumerable.Range(0, 5).Select(i => Tag("T" + i)).ToArray();
var (drv, factory) = NewDriver(true, 2, tags);
await drv.InitializeAsync("{}", CancellationToken.None);
factory.Customise = () =>
{
var c = new FakeTwinCATClient();
for (var i = 0; i < 5; i++) c.Values["MAIN.T" + i] = i * 10;
return c;
};
var snaps = await drv.ReadAsync([.. tags.Select(t => t.Name)], CancellationToken.None);
snaps.Select(s => s.Value).ShouldBe([0, 10, 20, 30, 40]);
factory.Clients[0].SumReadBatches.ShouldBe([2, 2]);
factory.Clients[0].SingleReadCount.ShouldBe(1); // the 5th tag: a one-item "batch" is just a read
}
/// <summary>Verifies the refusal fallback: the poll still completes and the device stops asking.</summary>
[Fact]
public async Task Refused_sum_command_falls_back_to_individual_reads_and_sticks()
{
var (drv, factory) = NewDriver(true, 200, Tag("A"), Tag("B"), Tag("C"));
await drv.InitializeAsync("{}", CancellationToken.None);
factory.Customise = () =>
{
var c = Seeded(("MAIN.A", 1), ("MAIN.B", 2), ("MAIN.C", 3));
c.SumReadException = new TwinCATSumReadRefusedException(1793);
return c;
};
var first = await drv.ReadAsync(["A", "B", "C"], CancellationToken.None);
var second = await drv.ReadAsync(["A", "B", "C"], CancellationToken.None);
first.Select(s => s.Value).ShouldBe([1, 2, 3]);
first.ShouldAllBe(s => s.StatusCode == TwinCATStatusMapper.Good);
second.Select(s => s.Value).ShouldBe([1, 2, 3]);
factory.Clients[0].SumReadBatches.ShouldBe([3]); // tried once, never again
factory.Clients[0].SingleReadCount.ShouldBe(6);
drv.GetHealth().State.ShouldBe(Core.Abstractions.DriverState.Healthy);
}
/// <summary>Verifies a comms failure is not mistaken for a refusal: the chunk goes Bad, sum stays on.</summary>
[Fact]
public async Task Comms_failure_marks_the_chunk_bad_and_does_not_disable_sum_read()
{
var (drv, factory) = NewDriver(true, 200, Tag("A"), Tag("B"));
await drv.InitializeAsync("{}", CancellationToken.None);
factory.Customise = () =>
{
var c = Seeded(("MAIN.A", 1), ("MAIN.B", 2));
c.SumReadException = new InvalidOperationException("router gone");
return c;
};
var failed = await drv.ReadAsync(["A", "B"], CancellationToken.None);
factory.Clients[0].SumReadException = null;
var recovered = await drv.ReadAsync(["A", "B"], CancellationToken.None);
failed.ShouldAllBe(s => s.StatusCode == TwinCATStatusMapper.BadCommunicationError);
recovered.Select(s => s.Value).ShouldBe([1, 2]);
factory.Clients[0].SumReadBatches.ShouldBe([2, 2]);
}
/// <summary>Verifies unknown references do not disturb result order.</summary>
[Fact]
public async Task Unknown_reference_keeps_its_slot_in_a_batched_poll()
{
var (drv, factory) = NewDriver(true, 200, Tag("A"), Tag("B"));
await drv.InitializeAsync("{}", CancellationToken.None);
factory.Customise = () => Seeded(("MAIN.A", 1), ("MAIN.B", 2));
var snaps = await drv.ReadAsync(["A", "nope", "B"], CancellationToken.None);
snaps[0].Value.ShouldBe(1);
snaps[1].StatusCode.ShouldBe(TwinCATStatusMapper.BadNodeIdUnknown);
snaps[2].Value.ShouldBe(2);
factory.Clients[0].SumReadBatches.ShouldBe([2]);
}
/// <summary>Verifies the batch carries bit index and array length so the client decodes like a single read.</summary>
[Fact]
public async Task Bulk_items_carry_array_length_and_bit_index()
{
var captured = new List<TwinCATBulkReadItem>();
var factory = new FakeTwinCATClientFactory { Customise = () => new CapturingClient(captured) };
var drv = new TwinCATDriver(new TwinCATDriverOptions
{
Devices = [new TwinCATDeviceOptions(Host)],
RawTags = TwinCATRawTags.Entries([
new TwinCATTagDefinition("Arr", Host, "MAIN.Arr", TwinCATDataType.Int, ArrayLength: 4),
new TwinCATTagDefinition("Bit", Host, "MAIN.Word.3", TwinCATDataType.Bool),
]),
Probe = new TwinCATProbeOptions { Enabled = false },
UseSumRead = true,
}, "drv-sum", factory);
await drv.InitializeAsync("{}", CancellationToken.None);
await drv.ReadAsync(["Arr", "Bit"], CancellationToken.None);
captured.Count.ShouldBe(2);
captured[0].ArrayCount.ShouldBe(4);
captured[1].BitIndex.ShouldBe(3);
}
/// <summary>Verifies the JSON keys reach the options.</summary>
[Fact]
public void Options_parse_from_driver_config_json()
{
var on = TwinCATDriverFactoryExtensions.ParseOptionsForTests(
"""{"useSumRead": true, "sumReadMaxItems": 50}""", "d");
on.UseSumRead.ShouldBeTrue();
on.SumReadMaxItems.ShouldBe(50);
var off = TwinCATDriverFactoryExtensions.ParseOptionsForTests("{}", "d");
off.UseSumRead.ShouldBeFalse();
off.SumReadMaxItems.ShouldBe(200);
}
/// <summary>Verifies which overall ADS codes mean "no sum commands here" rather than a comms fault.</summary>
[Theory]
[InlineData(1792u, true)]
[InlineData(1793u, true)]
[InlineData(1794u, true)]
[InlineData(1795u, true)]
[InlineData(1797u, true)]
[InlineData(1798u, true)]
[InlineData(6u, false)] // TargetPortNotFound
[InlineData(1861u, false)] // ClientSyncTimeOut
[InlineData(1808u, false)] // symbol not found: a per-item matter
public void Overall_ads_codes_classify_as_refusal_only_for_service_errors(uint code, bool refusal) =>
AdsTwinCATClient.IsSumRefusal(code).ShouldBe(refusal);
private sealed class CapturingClient(List<TwinCATBulkReadItem> sink) : FakeTwinCATClient
{
public override Task<IReadOnlyList<(object? value, uint status)>> ReadValuesAsync(
IReadOnlyList<TwinCATBulkReadItem> reads, CancellationToken ct)
{
sink.AddRange(reads);
return base.ReadValuesAsync(reads, ct);
}
}
}