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

fix(twincat): review fixes for sum-read and diagnostics (#645)

Browse Source 
Strict width+kind eligibility for sum-batched scalars (others read singly); latch only on ADS
1793/1794, split 1792/1797/1798 without latching; 32 KiB per-command budget and 500-item ceiling;
short sum response handled per item. Diagnostics: opt-in diagnosticsEnabled (default off), reuse the
probe's ReadState, sample after the host-state transition, JitterMs renamed HeadroomMs, compact
per-device line so many devices fit the 16-entry cap, unavailable-symbol latch cleared on reconnect.
AdminUI: min/max on sum-read max, diagnostics checkbox. Pure planner extracted and unit-tested.

Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
This commit is contained in:
Joseph Doherty
2026-10-08 19:29:35 -04:00
parent af19db4ed1
commit fbcb521d1b
16 changed files with 470 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Contracts/TwinCATDriverOptions.cs
+11 -1
View File
@@ -73,10 +73,20 @@ public sealed class TwinCATDriverOptions
/// <summary>
/// Maximum symbols per ADS sum-read command; larger polls are split into chunks of this size.
/// Bounds the request/response size against the target's ADS buffer. Values below 1 are treated as 1.
/// Only consulted when <see cref="UseSumRead"/> is <c>true</c>.
/// Values above 500 (the ADS sub-command ceiling) are treated as 500. Only consulted when
/// <see cref="UseSumRead"/> is <c>true</c>.
/// </summary>
public int SumReadMaxItems { get; init; } = 200;
/// <summary>
/// When <c>true</c>, each healthy probe tick also reads up to four <c>TwinCAT_SystemInfoVarList</c>
/// symbols (app name, online-change count, task cycle and last-exec time) and the ADS state the probe
/// already fetched, and publishes them on the <c>/hosts</c> diagnostics bag (Gitea #645 / #314).
/// Default <c>false</c>: that is up to four extra read requests per device per probe interval against
/// the PLC, not yet live-gated. Pending the read-only live gate on a TC2 and a TC3 target.
/// </summary>
public bool DiagnosticsEnabled { get; init; }
/// <summary>
/// Timeout for the AdminUI Test Connect probe, in seconds. The AdminUI clamps to a
/// 60s server-side maximum; this default is what the form pre-fills for new instances.
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs
+71 -52
View File
@@ -174,9 +174,13 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
var results = new (object? value, uint status)[reads.Count];
var planned = new List<PlannedSumRead>(reads.Count);
Task<(object? value, uint status)> ReadSingly(int index) =>
ReadValueAsync(reads[index].SymbolPath, reads[index].Type, reads[index].BitIndex,
reads[index].ArrayCount, cancellationToken);
// Plan every item exactly as the single read would (symbol resolved from the Beckhoff symbol cache,
// declared type checked against it), but stop short of the wire read: those become ONE sum command.
// Anything the sum command cannot carry is read on its own right here.
// declared type checked against it), but stop short of the wire read: eligible items become sum
// commands. Anything the sum command cannot carry exactly is read on its own right here.
for (var i = 0; i < reads.Count; i++)
{
var r = reads[i];
@@ -184,8 +188,7 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
{
if (r.BitIndex is not null && r.Type == TwinCATDataType.Bool)
{
results[i] = await ReadValueAsync(r.SymbolPath, r.Type, r.BitIndex, r.ArrayCount, cancellationToken)
.ConfigureAwait(false);
results[i] = await ReadSingly(i).ConfigureAwait(false);
continue;
}
@@ -196,6 +199,7 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
TwinCATArrayLayout layout;
if (r.ArrayCount is int count)
{
// Arrays are raw bytes on the single path too, with the same strict element rule.
if (TwinCATTypeGuard.CheckArray(r.Type, count, shape, array, out layout) is not null)
{
results[i] = (null, TwinCATStatusMapper.BadTypeMismatch);
@@ -209,6 +213,14 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
results[i] = (null, TwinCATStatusMapper.BadTypeMismatch);
continue;
}
// The single read value-converts a numeric pair (DInt over a PLC INT is fine there); raw
// bytes decoded as the declared type would not. Only an exact width + kind match rides the
// sum command — the rest keeps the Beckhoff conversion by reading singly.
if (!TwinCATSumReadPlanner.ScalarEligible(r.Type, shape))
{
results[i] = await ReadSingly(i).ConfigureAwait(false);
continue;
}
// A scalar is a one-element "array" at the type's own width (a STRING at the PLC's declared
// width), so scalar and array share one raw decode.
layout = new TwinCATArrayLayout(1, r.Type is TwinCATDataType.String or TwinCATDataType.WString
@@ -220,8 +232,7 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
// as an index-group/offset sum entry. Read it individually.
if (symbol!.IndexGroup == SymbolValueByHandle)
{
results[i] = await ReadValueAsync(r.SymbolPath, r.Type, r.BitIndex, r.ArrayCount, cancellationToken)
.ConfigureAwait(false);
results[i] = await ReadSingly(i).ConfigureAwait(false);
continue;
}
@@ -235,82 +246,88 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
if (planned.Count == 0) return results;
// Split to the byte budget; a lone item (or an oversized one) is just a read.
var groups = TwinCATSumReadPlanner.Partition(
[.. planned.Select(p => p.Layout.ByteLength)], TwinCATSumReadPlanner.MaxBatchBytes);
foreach (var group in groups)
{
var items = group.Select(g => planned[g]).ToList();
if (items.Count == 1)
{
results[items[0].Index] = await ReadSingly(items[0].Index).ConfigureAwait(false);
continue;
}
await ReadGroupAsync(items, reads, results, ReadSingly, cancellationToken).ConfigureAwait(false);
}
return results;
}
private async Task ReadGroupAsync(
List<PlannedSumRead> items, IReadOnlyList<TwinCATBulkReadItem> reads,
(object? value, uint status)[] results,
Func<int, Task<(object? value, uint status)>> readSingly, CancellationToken cancellationToken)
{
async Task FallBackAsync()
{
foreach (var p in items) results[p.Index] = await readSingly(p.Index).ConfigureAwait(false);
}
ResultSumReadRaw sum;
try
{
var entities = new List<IgIoSumReadEntity>(planned.Count);
foreach (var p in planned)
var entities = new List<IgIoSumReadEntity>(items.Count);
foreach (var p in items)
entities.Add(new IgIoSumReadEntity(p.IndexGroup, p.IndexOffset, p.Layout.ByteLength));
sum = await new SumRead(_client, entities, SumCommandErrorStrategy.Relaxed)
.ReadRawAsync(cancellationToken).ConfigureAwait(false);
}
catch (AdsErrorException ex) when (IsSumRefusal((uint)ex.ErrorCode))
catch (AdsErrorException ex) when (TwinCATSumReadPlanner.IsRefusal((uint)ex.ErrorCode))
{
throw new TwinCATSumReadRefusedException((uint)ex.ErrorCode, ex);
}
catch (AdsSumCommandException)
catch (ArgumentException)
{
// The library gave up on the batch without an overall ADS code (a sub-item failure under its
// strict handling). Not a refusal of the service: read these items one by one this time.
foreach (var p in planned)
results[p.Index] = await ReadValueAsync(reads[p.Index].SymbolPath, reads[p.Index].Type,
reads[p.Index].BitIndex, reads[p.Index].ArrayCount, cancellationToken).ConfigureAwait(false);
return results;
// The library slices the response by the REQUESTED lengths and throws when a target answers with
// less. That is this target mangling this response, not a comms fault: read the group singly.
await FallBackAsync().ConfigureAwait(false);
return;
}
// The overall code is the sum command itself; per-item codes are in SubErrors.
// On an overall failure the library RETURNS the code (SubErrors all set, ReadBlocks null).
if (sum.ErrorCode != AdsErrorCode.NoError)
{
var overall = (uint)sum.ErrorCode;
if (IsSumRefusal(overall))
if (TwinCATSumReadPlanner.IsRefusal(overall))
throw new TwinCATSumReadRefusedException(overall);
if (TwinCATSumReadPlanner.IsRequestRejected(overall))
{
await FallBackAsync().ConfigureAwait(false); // too big / bad size for THIS request: no latch
return;
}
var mapped = MapAndSignal(overall);
foreach (var p in planned) results[p.Index] = (null, mapped);
return results;
foreach (var p in items) results[p.Index] = (null, mapped);
return;
}
for (var k = 0; k < planned.Count; k++)
var utf8 = StringsAreUtf8();
for (var k = 0; k < items.Count; k++)
{
var p = planned[k];
var p = items[k];
var subError = sum.SubErrors is { } errs && k < errs.Length ? errs[k] : AdsErrorCode.NoError;
if (subError != AdsErrorCode.NoError)
{
results[p.Index] = (null, MapAndSignal((uint)subError));
continue;
}
if (sum.ReadBlocks is not { } blocks || k >= blocks.Count || blocks[k].Length < p.Layout.ByteLength)
{
// A short block would decode garbage; treat it as a size mismatch, not a value.
results[p.Index] = (null, TwinCATStatusMapper.MapAdsError(1797));
continue;
}
var decoded = TwinCATArrayCodec.Decode(reads[p.Index].Type, sum.ReadBlocks![k].Span, p.Layout, StringsAreUtf8());
results[p.Index] = (p.IsArray ? decoded : decoded.GetValue(0), TwinCATStatusMapper.Good);
ReadOnlyMemory<byte>? block = sum.ReadBlocks is { } blocks && k < blocks.Count ? blocks[k] : null;
results[p.Index] = TwinCATSumReadPlanner.DecodeItem(
reads[p.Index].Type, subError, block, p.Layout, p.IsArray, utf8, MapAndSignal);
}
return results;
}
private const uint SymbolValueByHandle = 0xF005;
private readonly record struct PlannedSumRead(int Index, uint IndexGroup, uint IndexOffset, TwinCATArrayLayout Layout, bool IsArray);
/// <summary>
/// True for an overall ADS code that means "this target does not do sum commands" (service / index
/// group / offset / size not supported) rather than a comms fault.
/// </summary>
internal static bool IsSumRefusal(uint adsError) => adsError is 1792 or 1793 or 1794 or 1795 or 1797 or 1798;
private string? _lastAdsState;
/// <inheritdoc />
public async Task<string?> ReadAdsStateAsync(CancellationToken cancellationToken)
{
try
{
var state = await _client.ReadStateAsync(cancellationToken).ConfigureAwait(false);
return state.ErrorCode == AdsErrorCode.NoError ? state.State.AdsState.ToString() : null;
}
catch (OperationCanceledException) { throw; }
catch { return null; }
}
public string? LastAdsState => Volatile.Read(ref _lastAdsState);
/// <summary>
/// Resolves the PLC symbol behind <paramref name="symbolPath"/> into the facts
@@ -435,7 +452,9 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
try
{
var state = await _client.ReadStateAsync(cancellationToken).ConfigureAwait(false);
return state.ErrorCode == AdsErrorCode.NoError;
var ok = state.ErrorCode == AdsErrorCode.NoError;
Volatile.Write(ref _lastAdsState, ok ? state.State.AdsState.ToString() : null);
return ok;
}
catch
{
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/ITwinCATClient.cs
+4 -6
View File
@@ -86,13 +86,11 @@ public interface ITwinCATClient : IDisposable
}
/// <summary>
/// The target's ADS device state (<c>Run</c>, <c>Stop</c>, <c>Config</c>, …) as text, or <c>null</c>
/// when it cannot be read. Feeds the driver's <c>/hosts</c> diagnostics (Gitea #645 / #314).
/// Default <c>null</c> — a client without a state read simply reports none.
/// The ADS device state name (<c>Run</c>, <c>Stop</c>, <c>Config</c>, …) the most recent
/// <see cref="ProbeAsync"/> read, or <c>null</c> when unknown. Reuses the probe's own ReadState so
/// diagnostics add no request (Gitea #645 / #314). Default <c>null</c>.
/// </summary>
/// <param name="cancellationToken">Cancellation token for the read.</param>
/// <returns>The state name, or <c>null</c>.</returns>
Task<string?> ReadAdsStateAsync(CancellationToken cancellationToken) => Task.FromResult<string?>(null);
string? LastAdsState => null;
/// <summary>
/// Write a symbolic value. Returns the mapped OPC UA status for the operation
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDeviceDiagnostics.cs
+3 -2
View File
@@ -20,6 +20,7 @@ internal sealed record TwinCATDeviceDiagnostics(
double? LastExecTimeMs,
DateTime UpdatedUtc)
{
/// <summary>Gets last execution time minus cycle time: positive means the task overran its cycle.</summary>
public double? JitterMs => CycleTimeMs is { } c && LastExecTimeMs is { } x ? x - c : null;
/// <summary>Gets cycle time minus last execution time: how much of the cycle was spare. Negative means the
/// task overran its cycle. (Not jitter — that needs the variation across cycles.)</summary>
public double? HeadroomMs => CycleTimeMs is { } c && LastExecTimeMs is { } x ? c - x : null;
}
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs
+37 -15
View File
@@ -374,7 +374,7 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
DeviceState device, List<SumReadEntry> bucket, DataValueSnapshot[] results, DateTime now,
CancellationToken cancellationToken)
{
var chunkSize = Math.Max(1, _options.SumReadMaxItems);
var chunkSize = Math.Clamp(_options.SumReadMaxItems, 1, TwinCATSumReadPlanner.MaxItemsCeiling);
for (var start = 0; start < bucket.Count; start += chunkSize)
{
var chunk = bucket.GetRange(start, Math.Min(chunkSize, bucket.Count - start));
@@ -867,6 +867,7 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
while (!ct.IsCancellationRequested)
{
var success = false;
ITwinCATClient? probed = null;
try
{
// Probe-initiated connects honor TwinCATProbeOptions.Timeout — distinct from
@@ -884,12 +885,11 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
if (!success)
await RecycleClientAsync(state, ct).ConfigureAwait(false);
else
{
// 05/STAB-16: on a healthy tick, re-register any notifications whose replay
// failed (a transient AddNotification blip) so they recover without a client swap.
{
await RetryDeadRegistrationsAsync(state, ct).ConfigureAwait(false);
// #645/#314: sample the PLC state / task-cycle facts for /hosts. Best-effort.
await SampleDeviceDiagnosticsAsync(state, client, ct).ConfigureAwait(false);
probed = client;
}
}
catch (OperationCanceledException) when (ct.IsCancellationRequested) { break; }
@@ -905,6 +905,14 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
TransitionDeviceState(state, success ? HostState.Running : HostState.Stopped);
// #645/#314: opt-in PLC state / task-cycle sampling for /hosts. After the host-state transition so a
// slow target cannot delay it; never throws (except cancellation).
if (_options.DiagnosticsEnabled && probed is not null)
{
try { await SampleDeviceDiagnosticsAsync(state, probed, ct).ConfigureAwait(false); }
catch (OperationCanceledException) when (ct.IsCancellationRequested) { break; }
}
try { await Task.Delay(_options.Probe.Interval, ct).ConfigureAwait(false); }
catch (OperationCanceledException) { break; }
}
@@ -943,10 +951,8 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
try
{
var prev = state.LastDiagnostics;
var adsState = prev?.AdsState;
try { adsState = await client.ReadAdsStateAsync(ct).ConfigureAwait(false) ?? adsState; }
catch (OperationCanceledException) when (ct.IsCancellationRequested) { throw; }
catch { /* keep previous */ }
// The probe's own ReadState (ProbeAsync) already fetched this; no second request.
var adsState = client.LastAdsState ?? prev?.AdsState;
var appName = await ReadDiagSymbolAsync(state, client, SymAppName, TwinCATDataType.String, ct).ConfigureAwait(false) as string
?? prev?.AppName;
@@ -1002,13 +1008,27 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
foreach (var state in _devices.Values)
{
if (state.LastDiagnostics is not { } d) continue;
var prefix = multi ? $"TwinCAT.{state.Options.DeviceName ?? state.Options.HostAddress}." : "TwinCAT.";
var name = state.Options.DeviceName ?? state.Options.HostAddress;
if (multi)
{
// One compact line per device so the host's 16-entry cap shows up to 16 devices, not 2.
var parts = new List<string>(6);
if (d.AdsState is not null) parts.Add(d.AdsState);
if (!string.IsNullOrEmpty(d.AppName)) parts.Add(d.AppName);
if (d.OnlineChangeCnt is { } n) parts.Add("online-changes " + n.ToString(System.Globalization.CultureInfo.InvariantCulture));
if (d.CycleTimeMs is { } cy) parts.Add("cycle " + FormatMs(cy) + " ms");
if (d.LastExecTimeMs is { } ex) parts.Add("exec " + FormatMs(ex) + " ms");
if (d.HeadroomMs is { } h) parts.Add("headroom " + FormatMs(h) + " ms");
bag[$"TwinCAT.{name}"] = string.Join("; ", parts);
continue;
}
const string prefix = "TwinCAT.";
if (d.AdsState is not null) bag[prefix + "AdsState"] = d.AdsState;
if (!string.IsNullOrEmpty(d.AppName)) bag[prefix + "AppName"] = d.AppName;
if (d.OnlineChangeCnt is { } oc) bag[prefix + "OnlineChangeCnt"] = oc.ToString(System.Globalization.CultureInfo.InvariantCulture);
if (d.CycleTimeMs is { } cy) bag[prefix + "CycleTimeMs"] = FormatMs(cy);
if (d.LastExecTimeMs is { } ex) bag[prefix + "LastExecTimeMs"] = FormatMs(ex);
if (d.JitterMs is { } j) bag[prefix + "JitterMs"] = FormatMs(j);
if (d.CycleTimeMs is { } cy2) bag[prefix + "CycleTimeMs"] = FormatMs(cy2);
if (d.LastExecTimeMs is { } ex2) bag[prefix + "LastExecTimeMs"] = FormatMs(ex2);
if (d.HeadroomMs is { } h2) bag[prefix + "HeadroomMs"] = FormatMs(h2);
}
return bag;
}
@@ -1181,6 +1201,7 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
throw;
}
device.Client = client;
device.UnavailableDiagSymbols.Clear(); // a rebuilt client may face a PLC that now exports them
device.Backoff.RecordSuccess(); // 05/STAB-8: recovery resets the window immediately
// Re-register every native notification onto the fresh client. Native ADS is push, so
@@ -1438,9 +1459,9 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
/// so the loop cannot touch a disposed client.</summary>
public Task? ProbeTask { get; set; }
/// <summary>Disposes the active ADS client if any.</summary>
/// <summary>Set when the target refused the ADS sum-read command (#645); the device reads one tag at a
/// time from then on. Cleared only by a fresh <see cref="DeviceState"/> (driver re-initialise).</summary>
/// <summary>Set when the target answered the ADS sum-read command with "service / index group not
/// supported" (#645); the device reads one tag at a time from then on. Cleared only by a fresh
/// <see cref="DeviceState"/> (driver re-initialise).</summary>
public volatile bool SumReadUnsupported;
/// <summary>Latest probe-sampled PLC diagnostics (#645 / #314); null before the first sample.</summary>
@@ -1449,6 +1470,7 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
/// <summary>Diagnostic system symbols the target answered "not found" for — not re-asked until the client is rebuilt.</summary>
public ConcurrentDictionary<string, byte> UnavailableDiagSymbols { get; } = new(StringComparer.Ordinal);
/// <summary>Disposes the active ADS client if any.</summary>
public void DisposeClient()
{
Client?.Dispose();
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriverFactoryExtensions.cs
+4
View File
@@ -80,6 +80,7 @@ public static class TwinCATDriverFactoryExtensions
NotificationMaxDelayMs = dto.NotificationMaxDelayMs ?? 0,
UseSumRead = dto.UseSumRead ?? false,
SumReadMaxItems = dto.SumReadMaxItems ?? 200,
DiagnosticsEnabled = dto.DiagnosticsEnabled ?? false,
};
}
@@ -119,6 +120,9 @@ public static class TwinCATDriverFactoryExtensions
/// <summary>Gets or sets a value indicating whether a poll's reads are batched into ADS sum-reads.</summary>
public bool? UseSumRead { get; init; }
/// <summary>Gets or sets a value indicating whether probe-tick PLC diagnostics are sampled.</summary>
public bool? DiagnosticsEnabled { get; init; }
/// <summary>Gets or sets the maximum symbols per sum-read command.</summary>
public int? SumReadMaxItems { get; init; }
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATSumReadPlanner.cs
+103
View File
@@ -0,0 +1,103 @@
using Beckhoff = TwinCAT.Ads;
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
/// <summary>
/// The pure decisions behind an ADS sum-read (Gitea #645 / #310), split out of
/// <see cref="AdsTwinCATClient"/> so they are unit-testable without an ADS connection: which items may
/// ride a sum command, how a poll is split to fit a request budget, which overall ADS codes mean what,
/// and how one item's raw block becomes a value.
/// </summary>
internal static class TwinCATSumReadPlanner
{
/// <summary>Hard ceiling on items per sum command (ADS documents roughly 500 sub-commands).</summary>
public const int MaxItemsCeiling = 500;
/// <summary>Per-command byte budget: the sum of the items' read lengths plus <see cref="PerItemOverhead"/> each.
/// Keeps a poll that includes large arrays inside a modest router / CE buffer.</summary>
public const int MaxBatchBytes = 32 * 1024;
/// <summary>Bytes of per-item ADS error code carried in a sum response.</summary>
public const int PerItemOverhead = 4;
/// <summary>
/// True when a SCALAR may be read as raw bytes in a sum command. The sum path decodes the bytes as the
/// DECLARED type, so it needs the strict width + float/integer-kind rule (the notification rule); the
/// lenient <see cref="TwinCATTypeGuard.CheckRead"/> relies on the Beckhoff value conversion a raw read
/// does not do. An item failing this but passing CheckRead must be read individually.
/// </summary>
/// <param name="declared">The tag's declared type.</param>
/// <param name="plc">The PLC symbol's shape.</param>
/// <returns>True when the raw-bytes decode is exact.</returns>
public static bool ScalarEligible(TwinCATDataType declared, TwinCATPlcSymbolShape plc) =>
TwinCATTypeGuard.CheckNotification(declared, plc) is null;
/// <summary>The service or index group itself is unsupported: the device never does sum commands. Latches.</summary>
/// <param name="adsError">The overall ADS code.</param>
/// <returns>True for 1793 (service not supported) and 1794 (invalid index group).</returns>
public static bool IsRefusal(uint adsError) => adsError is 1793 or 1794;
/// <summary>The target rejected THIS request (general error / bad size / bad data), typically because it was
/// too big. Not a device property: read the chunk singly for this poll, do not latch.</summary>
/// <param name="adsError">The overall ADS code.</param>
/// <returns>True for 1792, 1797 and 1798.</returns>
public static bool IsRequestRejected(uint adsError) => adsError is 1792 or 1797 or 1798;
/// <summary>
/// Splits items (in order) into groups whose summed <c>length + PerItemOverhead</c> stays within
/// <paramref name="budget"/>. An item that alone exceeds the budget gets its own group (the caller reads a
/// one-item group individually).
/// </summary>
/// <param name="byteLengths">Each item's read length.</param>
/// <param name="budget">The byte budget per command.</param>
/// <returns>Groups of positions into <paramref name="byteLengths"/>.</returns>
public static List<List<int>> Partition(IReadOnlyList<int> byteLengths, int budget)
{
var groups = new List<List<int>>();
List<int>? current = null;
var used = 0;
for (var i = 0; i < byteLengths.Count; i++)
{
var cost = byteLengths[i] + PerItemOverhead;
if (current is null || used + cost > budget)
{
current = [];
groups.Add(current);
used = 0;
}
current.Add(i);
used += cost;
}
return groups;
}
/// <summary>
/// Turns one item's sum-response slice into a value. A per-item ADS error maps to its status; a missing or
/// short block (a target answering with less than was asked for) is a size error for that item only.
/// </summary>
/// <param name="type">The declared type.</param>
/// <param name="subError">The item's ADS error code (0 = none).</param>
/// <param name="block">The item's bytes, or null when the response had none.</param>
/// <param name="layout">The planned layout (a scalar is one element).</param>
/// <param name="isArray">True to return the whole array, false for element 0.</param>
/// <param name="utf8">True when the target's STRINGs are UTF-8.</param>
/// <param name="mapError">Maps an ADS code to an OPC UA status (also raises symbol-version signals).</param>
/// <returns>The value and status.</returns>
public static (object? value, uint status) DecodeItem(
TwinCATDataType type, Beckhoff.AdsErrorCode subError, ReadOnlyMemory<byte>? block,
TwinCATArrayLayout layout, bool isArray, bool utf8, Func<uint, uint> mapError)
{
if (subError != Beckhoff.AdsErrorCode.NoError) return (null, mapError((uint)subError));
if (block is not { } b || b.Length < layout.ByteLength)
return (null, TwinCATStatusMapper.MapAdsError(1797));
try
{
var decoded = TwinCATArrayCodec.Decode(type, b.Span, layout, utf8);
return (isArray ? decoded : decoded.GetValue(0), TwinCATStatusMapper.Good);
}
catch (ArgumentException)
{
return (null, TwinCATStatusMapper.MapAdsError(1797));
}
}
}