Auto: twincat-2.1 — ADS Sum-read / Sum-write

Closes #310
This commit is contained in:
Joseph Doherty
2026-04-25 21:43:32 -04:00
parent fa2fbb404d
commit 931049b5a7
11 changed files with 875 additions and 26 deletions

View File

@@ -0,0 +1,93 @@
using System.Diagnostics;
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.IntegrationTests;
/// <summary>
/// PR 2.1 perf gate — verifies the bulk Sum-read path is materially faster than the
/// equivalent serial per-tag <see cref="TwinCAT.Ads.AdsClient.ReadValueAsync(string, Type, System.Threading.CancellationToken)"/>
/// loop on a real XAR runtime. The driver's <see cref="TwinCATDriver.ReadAsync"/>
/// already routes through the bulk path; the baseline calls through a hand-rolled
/// loop so we're comparing apples to apples on the same wire.
/// </summary>
/// <remarks>
/// Requires the perf fixture: <c>GVL_Perf.aTags : ARRAY[1..1000] OF DINT</c> per
/// <c>TwinCatProject/README.md §Performance scenarios</c>. Skipped unless
/// <c>TWINCAT_PERF=1</c> is set.
/// </remarks>
[Collection("TwinCATXar")]
[Trait("Category", "Performance")]
[Trait("Simulator", "TwinCAT-XAR")]
public sealed class TwinCATSumCommandPerfTests(TwinCATXarFixture sim)
{
private const int TagCount = 1000;
[TwinCATPerfFact]
public async Task Driver_sum_read_1000_tags_beats_loop_baseline_by_5x()
{
if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
var deviceAddress = $"ads://{sim.TargetNetId}:{sim.AmsPort}";
var tags = new TwinCATTagDefinition[TagCount];
var refs = new string[TagCount];
for (var i = 0; i < TagCount; i++)
{
// GVL_Perf.aTags is 1-based per IEC 61131-3 ARRAY declaration.
var name = $"Perf{i + 1}";
refs[i] = name;
tags[i] = new TwinCATTagDefinition(
Name: name,
DeviceHostAddress: deviceAddress,
SymbolPath: $"GVL_Perf.aTags[{i + 1}]",
DataType: TwinCATDataType.DInt);
}
var options = new TwinCATDriverOptions
{
Devices = [new TwinCATDeviceOptions(deviceAddress, "XAR-VM")],
Tags = tags,
UseNativeNotifications = false,
Timeout = TimeSpan.FromSeconds(15),
Probe = new TwinCATProbeOptions { Enabled = false },
};
// ---- Bulk (PR 2.1) measurement ----
await using var bulkDrv = new TwinCATDriver(options, "tc3-perf-bulk");
await bulkDrv.InitializeAsync("{}", TestContext.Current.CancellationToken);
// Warm-up: prime symbol-handle caches in the XAR runtime so the timed run
// measures sum-read steady state, not first-touch handle resolution.
await bulkDrv.ReadAsync(refs, TestContext.Current.CancellationToken);
var bulkSw = Stopwatch.StartNew();
var bulkResults = await bulkDrv.ReadAsync(refs, TestContext.Current.CancellationToken);
bulkSw.Stop();
// ---- Loop baseline measurement ----
// Use a fresh driver instance so the cache state matches the bulk run on first
// call. Single-tag-per-call across the full set is what PR 2.1 replaces.
await using var loopDrv = new TwinCATDriver(options, "tc3-perf-loop");
await loopDrv.InitializeAsync("{}", TestContext.Current.CancellationToken);
// Warm-up against the same refs.
for (var i = 0; i < TagCount; i++)
_ = await loopDrv.ReadAsync([refs[i]], TestContext.Current.CancellationToken);
var loopSw = Stopwatch.StartNew();
for (var i = 0; i < TagCount; i++)
_ = await loopDrv.ReadAsync([refs[i]], TestContext.Current.CancellationToken);
loopSw.Stop();
// Sanity: bulk path must produce TagCount snapshots all Good.
bulkResults.Count.ShouldBe(TagCount);
bulkResults.ShouldAllBe(s => s.StatusCode == TwinCATStatusMapper.Good);
// Conservative ratio — on the dev box bulk is ~10-20× the loop, target is 5×.
// Lower bound exists so the test is robust to noisy CI / VM scheduling.
var ratio = (double)loopSw.ElapsedMilliseconds / Math.Max(1, bulkSw.ElapsedMilliseconds);
ratio.ShouldBeGreaterThan(5.0,
$"Bulk Sum-read should be >5x faster than per-tag loop; got bulk={bulkSw.ElapsedMilliseconds}ms, loop={loopSw.ElapsedMilliseconds}ms (ratio={ratio:F2})");
}
}

View File

@@ -134,3 +134,24 @@ public sealed class TwinCATTheoryAttribute : TheoryAttribute
"for setup; typical cause is the trial license expired or TWINCAT_TARGET_NETID is unset.";
}
}
/// <summary>
/// Perf-tier <c>[Fact]</c> equivalent. Runs only when the XAR runtime is reachable
/// <em>and</em> <c>TWINCAT_PERF=1</c> is set. Perf tests are gated separately because
/// they exercise the wire heavily (1000+ tags) + can extend test runs by tens of
/// seconds — the operator opts in.
/// </summary>
public sealed class TwinCATPerfFactAttribute : FactAttribute
{
public TwinCATPerfFactAttribute()
{
if (!TwinCATXarFixture.IsRuntimeAvailable())
{
Skip = "TwinCAT XAR not reachable. See docs/drivers/TwinCAT-Test-Fixture.md " +
"for setup; typical cause is the trial license expired or TWINCAT_TARGET_NETID is unset.";
return;
}
if (Environment.GetEnvironmentVariable("TWINCAT_PERF") != "1")
Skip = "Perf tier disabled. Set TWINCAT_PERF=1 to run; see docs/drivers/TwinCAT-Test-Fixture.md §Performance.";
}
}

View File

@@ -0,0 +1,17 @@
<?xml version="1.0" encoding="utf-8"?>
<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.0">
<GVL Name="GVL_Perf" Id="{00000000-0000-0000-0000-000000000201}">
<Declaration><![CDATA[// PR 2.1 Sum-read perf fixture. 1000 DINTs read in one ADS sum-read by
// TwinCATSumCommandPerfTests; FB_PerfChurn rotates a few values each cycle so
// the wire isn't reading static data the runtime can short-circuit.
//
// Required by the perf-tier integration test
// Driver_sum_read_1000_tags_beats_loop_baseline_by_5x. See
// TwinCatProject/README.md §Performance scenarios.
VAR_GLOBAL
aTags : ARRAY[1..1000] OF DINT;
fbPerfChurn : FB_PerfChurn;
END_VAR
]]></Declaration>
</GVL>
</TcPlcObject>

View File

@@ -0,0 +1,22 @@
<?xml version="1.0" encoding="utf-8"?>
<TcPlcObject Version="1.1.0.1" ProductVersion="3.1.4024.0">
<POU Name="FB_PerfChurn" Id="{00000000-0000-0000-0000-000000000202}" SpecialFunc="None">
<Declaration><![CDATA[// Rotating writer for GVL_Perf.aTags so the perf integration test isn't
// reading completely static data — keeps the runtime's symbol caches honest.
// Increments each tag's value at MAIN-task cadence; touches all 1000 entries
// over the 1000 cycles spanning ~10s at the default 10ms PlcTask period.
FUNCTION_BLOCK FB_PerfChurn
VAR
nIndex : INT := 1;
END_VAR
]]></Declaration>
<Implementation>
<ST><![CDATA[GVL_Perf.aTags[nIndex] := GVL_Perf.aTags[nIndex] + 1;
nIndex := nIndex + 1;
IF nIndex > 1000 THEN
nIndex := 1;
END_IF
]]></ST>
</Implementation>
</POU>
</TcPlcObject>

View File

@@ -71,6 +71,70 @@ GVL_Fixture.nCounter := GVL_Fixture.nCounter + 1;
- `PlcTask` — cyclic, 10 ms interval, priority 20
- Assigned to `MAIN`
## Performance scenarios
PR 2.1 (ADS Sum-read / Sum-write) ships an opt-in perf-tier integration test
(`TwinCATSumCommandPerfTests.Driver_sum_read_1000_tags_beats_loop_baseline_by_5x`)
that reads 1000 DINTs in one shot and asserts the bulk path beats the per-tag
loop by ≥ 5×. The fixture state required by that test is:
### Global Variable List: `GVL_Perf`
```st
VAR_GLOBAL
// 1000-DINT array exercised by the bulk Sum-read benchmark.
aTags : ARRAY[1..1000] OF DINT;
fbPerfChurn : FB_PerfChurn;
END_VAR
```
The XAE-form GVL ships at `PLC/GVLs/GVL_Perf.TcGVL`; import it into the PLC
project alongside `GVL_Fixture`.
### POU: `FB_PerfChurn`
```st
FUNCTION_BLOCK FB_PerfChurn
VAR
nIndex : INT := 1;
END_VAR
GVL_Perf.aTags[nIndex] := GVL_Perf.aTags[nIndex] + 1;
nIndex := nIndex + 1;
IF nIndex > 1000 THEN
nIndex := 1;
END_IF
```
The XAE-form POU ships at `PLC/POUs/FB_PerfChurn.TcPOU`. Wire it into `MAIN`
so a value rotates each cycle:
```st
PROGRAM MAIN
VAR
END_VAR
// existing GVL_Fixture line:
GVL_Fixture.nCounter := GVL_Fixture.nCounter + 1;
// PR 2.1 keep aTags moving so caches don't short-circuit the read.
GVL_Perf.fbPerfChurn();
```
### Running the perf tier
```powershell
$env:TWINCAT_TARGET_HOST = '10.0.0.42'
$env:TWINCAT_TARGET_NETID = '5.23.91.23.1.1'
$env:TWINCAT_PERF = '1'
dotnet test tests\ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests `
--filter "Category=Performance"
```
Without `TWINCAT_PERF=1` the perf test skips via `[TwinCATPerfFact]` even when
the runtime is reachable — perf runs are opt-in to keep the default integration
pass fast.
### Runtime ID
- TC3 PLC runtime 1 (AMS port `851`) — the smoke-test fixture defaults

View File

@@ -72,6 +72,64 @@ internal class FakeTwinCATClient : ITwinCATClient
return Task.FromResult(ProbeResult);
}
// ---- Bulk surface (PR 2.1: SumSymbolRead / SumSymbolWrite) ----
public List<IReadOnlyList<TwinCATBulkReadItem>> BulkReadInvocations { get; } = new();
public List<IReadOnlyList<TwinCATBulkWriteItem>> BulkWriteInvocations { get; } = new();
public bool ThrowOnBulkRead { get; set; }
public bool ThrowOnBulkWrite { get; set; }
/// <summary>Per-symbol read failure injection — overlay onto <see cref="ReadStatuses"/>.</summary>
public Dictionary<string, uint> BulkReadStatuses { get; } = new(StringComparer.OrdinalIgnoreCase);
public virtual Task<IReadOnlyList<(object? value, uint status)>> ReadValuesAsync(
IReadOnlyList<TwinCATBulkReadItem> reads, CancellationToken ct)
{
// ThrowOnRead applies to both per-tag + bulk paths so legacy tests that toggled
// ThrowOnRead before bulk existed still surface BadCommunicationError correctly.
if (ThrowOnRead || ThrowOnBulkRead) throw Exception ?? new InvalidOperationException();
BulkReadInvocations.Add(reads);
// Preserve request order — the production sum-read returns one entry per request slot
// even on partial failure; so does this fake.
var output = new (object? value, uint status)[reads.Count];
for (var i = 0; i < reads.Count; i++)
{
var r = reads[i];
ReadLog.Add((r.SymbolPath, r.Type, null, null));
if (BulkReadStatuses.TryGetValue(r.SymbolPath, out var bulkStatus))
{
output[i] = (null, bulkStatus);
continue;
}
if (ReadStatuses.TryGetValue(r.SymbolPath, out var status) && status != TwinCATStatusMapper.Good)
{
output[i] = (null, status);
continue;
}
var value = Values.TryGetValue(r.SymbolPath, out var v) ? v : null;
output[i] = (value, TwinCATStatusMapper.Good);
}
return Task.FromResult<IReadOnlyList<(object? value, uint status)>>(output);
}
public virtual Task<IReadOnlyList<uint>> WriteValuesAsync(
IReadOnlyList<TwinCATBulkWriteItem> writes, CancellationToken ct)
{
if (ThrowOnWrite || ThrowOnBulkWrite) throw Exception ?? new InvalidOperationException();
BulkWriteInvocations.Add(writes);
var output = new uint[writes.Count];
for (var i = 0; i < writes.Count; i++)
{
var w = writes[i];
WriteLog.Add((w.SymbolPath, w.Type, null, w.Value));
Values[w.SymbolPath] = w.Value;
output[i] = WriteStatuses.TryGetValue(w.SymbolPath, out var s) ? s : TwinCATStatusMapper.Good;
}
return Task.FromResult<IReadOnlyList<uint>>(output);
}
public virtual void Dispose()
{
DisposeCount++;

View File

@@ -0,0 +1,238 @@
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>
/// PR 2.1 — bulk read / write contract via Sum-command surface. Verifies that
/// <see cref="TwinCATDriver.ReadAsync"/> + <see cref="TwinCATDriver.WriteAsync"/>
/// bucket scalar requests by device + dispatch each bucket as a single
/// <see cref="ITwinCATClient.ReadValuesAsync"/> / <see cref="ITwinCATClient.WriteValuesAsync"/>
/// call. Ordering preservation, partial failure mapping, empty input + cancellation
/// all live here. Per-tag fallback for bit-BOOL + whole-array tags is covered in
/// <see cref="TwinCATBitWriteTests"/> / <see cref="TwinCATArrayReadTests"/>.
/// </summary>
[Trait("Category", "Unit")]
public sealed class TwinCATSumCommandTests
{
private const string DevA = "ads://5.23.91.23.1.1:851";
private const string DevB = "ads://5.23.91.23.1.1:852";
private static (TwinCATDriver drv, FakeTwinCATClientFactory factory) NewDriver(params TwinCATTagDefinition[] tags)
{
var factory = new FakeTwinCATClientFactory();
var hosts = tags.Select(t => t.DeviceHostAddress).Distinct().ToArray();
if (hosts.Length == 0) hosts = [DevA];
var drv = new TwinCATDriver(new TwinCATDriverOptions
{
Devices = [.. hosts.Select(h => new TwinCATDeviceOptions(h))],
Tags = tags,
Probe = new TwinCATProbeOptions { Enabled = false },
}, "drv-bulk", factory);
return (drv, factory);
}
// ---- Bulk read ----
[Fact]
public async Task Bulk_read_dispatches_single_call_per_device_bucket()
{
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.Real),
new TwinCATTagDefinition("C", DevA, "GVL.C", TwinCATDataType.Bool));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
factory.Customise = () => new FakeTwinCATClient
{
Values = { ["GVL.A"] = 1, ["GVL.B"] = 2.5f, ["GVL.C"] = true },
};
var snapshots = await drv.ReadAsync(["A", "B", "C"], TestContext.Current.CancellationToken);
snapshots.Count.ShouldBe(3);
// One bulk-read call carrying all 3 tags — the throughput win this PR exists for.
factory.Clients[0].BulkReadInvocations.Count.ShouldBe(1);
factory.Clients[0].BulkReadInvocations[0].Count.ShouldBe(3);
}
[Fact]
public async Task Bulk_read_preserves_request_order_with_mixed_outcomes()
{
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
new TwinCATTagDefinition("B", DevA, "GVL.Missing", TwinCATDataType.DInt),
new TwinCATTagDefinition("C", DevA, "GVL.C", TwinCATDataType.String));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
factory.Customise = () =>
{
var c = new FakeTwinCATClient
{
Values = { ["GVL.A"] = 7, ["GVL.C"] = "ok" },
};
c.BulkReadStatuses["GVL.Missing"] = TwinCATStatusMapper.BadNodeIdUnknown;
return c;
};
var snapshots = await drv.ReadAsync(["A", "B", "C"], TestContext.Current.CancellationToken);
snapshots[0].StatusCode.ShouldBe(TwinCATStatusMapper.Good);
snapshots[0].Value.ShouldBe(7);
snapshots[1].StatusCode.ShouldBe(TwinCATStatusMapper.BadNodeIdUnknown);
snapshots[1].Value.ShouldBeNull();
snapshots[2].StatusCode.ShouldBe(TwinCATStatusMapper.Good);
snapshots[2].Value.ShouldBe("ok");
}
[Fact]
public async Task Bulk_read_buckets_per_device()
{
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
new TwinCATTagDefinition("X", DevB, "GVL.X", TwinCATDataType.DInt),
new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.DInt));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
factory.Customise = () => new FakeTwinCATClient
{
Values = { ["GVL.A"] = 1, ["GVL.B"] = 2, ["GVL.X"] = 99 },
};
var snapshots = await drv.ReadAsync(["A", "X", "B"], TestContext.Current.CancellationToken);
snapshots[0].Value.ShouldBe(1);
snapshots[1].Value.ShouldBe(99);
snapshots[2].Value.ShouldBe(2);
// Two clients (one per device); each bucket made a single bulk-read call.
factory.Clients.Count.ShouldBe(2);
factory.Clients[0].BulkReadInvocations.Count.ShouldBe(1);
factory.Clients[1].BulkReadInvocations.Count.ShouldBe(1);
factory.Clients.Sum(c => c.BulkReadInvocations.Sum(i => i.Count)).ShouldBe(3);
}
[Fact]
public async Task Empty_input_returns_empty_result_without_wire_call()
{
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
var snapshots = await drv.ReadAsync([], TestContext.Current.CancellationToken);
snapshots.Count.ShouldBe(0);
// No client created — driver short-circuits before EnsureConnectedAsync.
factory.Clients.Count.ShouldBe(0);
}
[Fact]
public async Task Bulk_read_whole_batch_failure_marks_every_slot_BadCommunicationError()
{
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.DInt));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
factory.Customise = () => new FakeTwinCATClient { ThrowOnBulkRead = true };
var snapshots = await drv.ReadAsync(["A", "B"], TestContext.Current.CancellationToken);
snapshots[0].StatusCode.ShouldBe(TwinCATStatusMapper.BadCommunicationError);
snapshots[1].StatusCode.ShouldBe(TwinCATStatusMapper.BadCommunicationError);
drv.GetHealth().State.ShouldBe(DriverState.Degraded);
}
[Fact]
public async Task Read_cancellation_propagates_through_bulk_path()
{
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
factory.Customise = () => new FakeTwinCATClient
{
ThrowOnBulkRead = true,
Exception = new OperationCanceledException(),
};
await Should.ThrowAsync<OperationCanceledException>(
() => drv.ReadAsync(["A"], TestContext.Current.CancellationToken));
}
// ---- Bulk write ----
[Fact]
public async Task Bulk_write_dispatches_single_call_per_device_bucket()
{
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.DInt),
new TwinCATTagDefinition("C", DevA, "GVL.C", TwinCATDataType.DInt));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
var results = await drv.WriteAsync(
[new WriteRequest("A", 1), new WriteRequest("B", 2), new WriteRequest("C", 3)],
TestContext.Current.CancellationToken);
results.Count.ShouldBe(3);
results.ShouldAllBe(r => r.StatusCode == TwinCATStatusMapper.Good);
factory.Clients[0].BulkWriteInvocations.Count.ShouldBe(1);
factory.Clients[0].BulkWriteInvocations[0].Count.ShouldBe(3);
}
[Fact]
public async Task Bulk_write_preserves_request_order_across_outcomes()
{
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.DInt, Writable: false),
new TwinCATTagDefinition("C", DevA, "GVL.C", TwinCATDataType.DInt));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
factory.Customise = () =>
{
var c = new FakeTwinCATClient();
c.WriteStatuses["GVL.C"] = TwinCATStatusMapper.BadOutOfRange;
return c;
};
var results = await drv.WriteAsync(
[
new WriteRequest("A", 1),
new WriteRequest("B", 2), // pre-bulk reject (read-only)
new WriteRequest("Unknown", 3),
new WriteRequest("C", 4), // mapped per-symbol error
], TestContext.Current.CancellationToken);
results[0].StatusCode.ShouldBe(TwinCATStatusMapper.Good);
results[1].StatusCode.ShouldBe(TwinCATStatusMapper.BadNotWritable);
results[2].StatusCode.ShouldBe(TwinCATStatusMapper.BadNodeIdUnknown);
results[3].StatusCode.ShouldBe(TwinCATStatusMapper.BadOutOfRange);
}
[Fact]
public async Task Bulk_write_whole_batch_failure_marks_every_slot_BadCommunicationError()
{
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt),
new TwinCATTagDefinition("B", DevA, "GVL.B", TwinCATDataType.DInt));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
factory.Customise = () => new FakeTwinCATClient { ThrowOnBulkWrite = true };
var results = await drv.WriteAsync(
[new WriteRequest("A", 1), new WriteRequest("B", 2)],
TestContext.Current.CancellationToken);
results[0].StatusCode.ShouldBe(TwinCATStatusMapper.BadCommunicationError);
results[1].StatusCode.ShouldBe(TwinCATStatusMapper.BadCommunicationError);
}
[Fact]
public async Task Empty_write_input_returns_empty_result_without_wire_call()
{
var (drv, factory) = NewDriver(
new TwinCATTagDefinition("A", DevA, "GVL.A", TwinCATDataType.DInt));
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
var results = await drv.WriteAsync([], TestContext.Current.CancellationToken);
results.Count.ShouldBe(0);
factory.Clients.Count.ShouldBe(0);
}
}