Files
lmxopcua/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs
T
Joseph Doherty a8d313ed5a fix(twincat): review round 2 - teardown confined to its generation; write health; re-arm epoch
- I1: the poll engine belongs to a teardown generation. ShutdownAsync/Dispose
  retire the current engine and install a fresh one in the same swap as the
  device/tag tables, then dispose the retired one (possibly in the background
  after a cancelled or over-budget shutdown). A subscription made after the
  next InitializeAsync can no longer land in an engine whose late dispose tail
  would dispose its CTS without cancelling it (a loop no UnsubscribeAsync could
  find). Poll handles are generation-qualified (TwinCATPollHandle) because each
  engine numbers handles from 1; SubscribeAsync re-homes a subscription that
  raced a retirement.
- M1: a write's status feeds per-device health - Good clears that device's
  comms fault and advances LastSuccessfulRead, a comms status degrades, a
  refusal keeps the state.
- M2: a symbol-version re-arm bumps a per-registration epoch; an in-flight
  retry that fails afterwards no longer re-imposes the backoff.
- M3: a re-arm restarts the refusal backoff at 30 s.
- M4: documented that PLC-not-in-RUN detection needs the probe.
- M5: WSTRING and multi-dimensional array encode-plan tests; the cancelled-
  shutdown test asserts Unknown health and awaits its background teardown.
- M6: an infinity spelled as a string ('Infinity', '-inf') passes like a
  float/double infinity; a finite overflow stays BadOutOfRange.

Refs #739
Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
2026-10-22 15:00:23 -04:00

2115 lines
115 KiB
C#

using System.Collections.Concurrent;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.OtOpcUa.Commons.Observability;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
/// <summary>
/// TwinCAT ADS driver — talks to Beckhoff PLC runtimes (TC2 + TC3) via AMS / ADS. PR 1 ships
/// the <see cref="IDriver"/> skeleton; read / write / discover / subscribe / probe / host-
/// resolver land in PRs 2 and 3.
/// </summary>
public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery, IBatchSubscribable,
IHostConnectivityProbe, IPerCallHostResolver, IRediscoverable, ISkippedTagReporter, IDriverDiagnostics,
IDisposable, IAsyncDisposable
{
/// <summary>Authored tags this driver could not build into its poll table.</summary>
private readonly SkippedTagLedger _skippedTags = new();
/// <inheritdoc />
public SkippedTagReport? GetSkippedTags() => _skippedTags.Snapshot();
// Mutable so ReinitializeAsync can apply a new config generation. The constructor seeds
// it; InitializeAsync re-parses driverConfigJson over the top of it (committed under _lifecycleLock).
private volatile TwinCATDriverOptions _options;
private readonly string _driverInstanceId;
private readonly ITwinCATClientFactory _clientFactory;
private readonly ILogger<TwinCATDriver> _logger;
// The poll engine belongs to a teardown GENERATION (#739 fix round 2): ShutdownAsync / Dispose retire the
// current engine and install a fresh one in the same swap, then dispose the retired one — possibly in the
// background after a cancelled or over-budget shutdown. PollGroupEngine.DisposeAsync clears whatever its
// own table holds when it finishes, so a subscription made after a later InitializeAsync must never land
// in a retiring engine, or the old teardown would dispose its CTS without cancelling it (a poll loop no
// UnsubscribeAsync can find, running forever).
private volatile PollGeneration _poll;
private long _nextPollGeneration;
/// <summary>One generation's poll engine plus its serial (the serial is part of every handle it issues).</summary>
private sealed record PollGeneration(long Serial, PollGroupEngine Engine);
/// <summary>
/// A poll subscription handle, qualified by the engine generation that issued it. Each engine numbers its
/// handles from 1, so without the generation a retired engine's late callback would carry a handle EQUAL
/// to a new subscription's and be taken for it.
/// </summary>
private sealed record TwinCATPollHandle(long Generation, ISubscriptionHandle Inner) : ISubscriptionHandle
{
/// <inheritdoc />
public string DiagnosticId => $"twincat-poll-g{Generation}-{Inner.DiagnosticId}";
}
// Device + tag tables are BUILD-AND-SWAP (#739 L8): InitializeAsync builds fresh tables and publishes
// them by reference under _lifecycleLock; ShutdownAsync / Dispose swap in empty ones and release what
// they took. A retained poll loop, the probe tick or an in-flight write therefore always sees one whole
// generation — never a table mid-Clear — and two overlapping teardowns can never release the same
// device twice (each device set is taken by exactly one swap).
private volatile ConcurrentDictionary<string, DeviceState> _devices = NewDeviceTable();
// v3: the authored RawPath → definition table. Keyed case-sensitive ordinal (the RawPath is
// the exact wire reference). Built in InitializeAsync from _options.RawTags via the pure mapper.
private volatile IReadOnlyDictionary<string, TwinCATTagDefinition> _tagsByRawPath = EmptyTags;
private static readonly IReadOnlyDictionary<string, TwinCATTagDefinition> EmptyTags =
new Dictionary<string, TwinCATTagDefinition>(StringComparer.Ordinal);
private static ConcurrentDictionary<string, DeviceState> NewDeviceTable() => new(StringComparer.OrdinalIgnoreCase);
// Serialises the table swaps against each other. _lifecycleGeneration is bumped by every
// InitializeAsync and every teardown, so an InitializeAsync that was overtaken while it awaited
// (an abandoned init overlapping the runtime's next ShutdownAsync, or a newer init) sees a
// different generation at its commit and releases what it built instead of installing it.
private readonly object _lifecycleLock = new();
private long _lifecycleGeneration;
/// <summary>Test accessor: the RMW gate for a device + parent word, or null.</summary>
internal SemaphoreSlim? BitRmwGateForTest(string host, string parentPath) =>
_bitRmwLocks.TryGetValue($"{host}|{parentPath}", out var g) ? g : null;
/// <summary>Test seam: awaited after the new generation is built and before it is committed, so a test can
/// interleave a teardown deterministically. Never set in production.</summary>
internal Func<Task>? BeforeCommitForTest { get; set; }
/// <summary>Upper bound on joining released devices' probe loops (one wait for all of them).</summary>
internal static readonly TimeSpan ProbeJoinTimeout = TimeSpan.FromSeconds(2);
/// <summary>
/// Upper bound on the whole of <see cref="ShutdownAsync"/>. The runtime gives a final stop 5 s, so
/// the driver stops waiting a little earlier; anything still running past it (a poll loop wedged in
/// a read) is cancelled already and finishes in the background.
/// </summary>
internal static readonly TimeSpan ShutdownBudget = TimeSpan.FromSeconds(4.5);
// References that already logged their bad-read Warning in the current bad episode (#739 P10).
// Removed when the tag reads Good; cleared on (re-)initialise and shutdown.
private readonly ConcurrentDictionary<string, byte> _warnedRefs = new(StringComparer.Ordinal);
// Per-parent-word RMW gate for BOOL-within-word writes: a single-bit write is a
// read-modify-write of the parent word (TwinCAT's symbol table doesn't expose "Word.N"),
// so concurrent bit-writers to the same word must serialise or they lose each other's
// updates. Keyed by device + parent symbol. (Cannot guard against the PLC program writing
// the word between our read and write — inherent to RMW.) The gates are KEPT across generations
// and teardowns (never cleared or disposed): a write still in flight on the old generation and the
// first write of the next one must serialise on the SAME gate. A SemaphoreSlim owns no kernel handle
// unless AvailableWaitHandle is read, and the key set is bounded by the authored bit tags.
private readonly ConcurrentDictionary<string, SemaphoreSlim> _bitRmwLocks =
new(StringComparer.OrdinalIgnoreCase);
// v3: resolves a read/write/subscribe fullReference (always a RawPath) to a tag definition by a
// single hit on the authored _tagsByRawPath table. A miss is a miss — the driver surfaces
// BadNodeIdUnknown (no blob-parse fallback).
private readonly EquipmentTagRefResolver<TwinCATTagDefinition> _resolver;
private DriverHealth _health = new(DriverState.Unknown, null, null);
/// <summary>Occurs when a subscribed tag value changes.</summary>
public event EventHandler<DataChangeEventArgs>? OnDataChange;
/// <summary>
/// Batched data changes (R02:P1): one raise per poll cycle on the poll path, one per notification on
/// the native path (each ADS notification is its own burst). DriverInstanceActor subscribes only this
/// event of a batch-capable driver, so EVERY data change the driver publishes goes through both.
/// </summary>
public event EventHandler<DataChangeBatchEventArgs>? OnDataChangeBatch;
/// <summary>Occurs when a device host connectivity status changes.</summary>
public event EventHandler<HostStatusChangedEventArgs>? OnHostStatusChanged;
/// <summary>Occurs when the Galaxy object hierarchy or TwinCAT symbol table is rediscovered.</summary>
public event EventHandler<RediscoveryEventArgs>? OnRediscoveryNeeded;
/// <summary>Initializes a new instance of the <see cref="TwinCATDriver"/> class.</summary>
/// <param name="options">Driver configuration options.</param>
/// <param name="driverInstanceId">Unique driver instance identifier.</param>
/// <param name="clientFactory">Optional ADS client factory; defaults to <see cref="AdsTwinCATClientFactory"/>.</param>
/// <param name="logger">Optional logger; defaults to <see cref="NullLogger{TwinCATDriver}"/>.</param>
public TwinCATDriver(TwinCATDriverOptions options, string driverInstanceId,
ITwinCATClientFactory? clientFactory = null,
ILogger<TwinCATDriver>? logger = null)
{
ArgumentNullException.ThrowIfNull(options);
_options = options;
_driverInstanceId = driverInstanceId;
_clientFactory = clientFactory ?? new AdsTwinCATClientFactory();
_logger = logger ?? NullLogger<TwinCATDriver>.Instance;
_resolver = new EquipmentTagRefResolver<TwinCATTagDefinition>(
r => _tagsByRawPath.TryGetValue(r, out var t) ? t : null);
_poll = CreatePollEngine();
}
/// <summary>Builds one generation's poll engine; its callbacks publish generation-qualified handles.</summary>
private PollGeneration CreatePollEngine()
{
var driverInstanceId = _driverInstanceId;
var serial = Interlocked.Increment(ref _nextPollGeneration);
return new PollGeneration(serial, new PollGroupEngine(
reader: ReadAsync,
onChange: (handle, tagRef, snapshot) =>
OnDataChange?.Invoke(this, new DataChangeEventArgs(new TwinCATPollHandle(serial, handle), tagRef, snapshot)),
onError: HandlePollError,
backoffCap: PollBackoffCap,
onBatch: (handle, items) => OnDataChangeBatch?.Invoke(this,
new DataChangeBatchEventArgs(new TwinCATPollHandle(serial, handle), items)),
// The engine owns no Meter (Core.Abstractions takes no metrics dependency), so this
// closure IS the production consumer of its overrun signal.
onOverrun: _ => OtOpcUaTelemetry.PollOverruns.Add(1,
new KeyValuePair<string, object?>(OtOpcUaTelemetry.PollOverrunDriverTypeTag, DriverTypeNames.TwinCAT),
new KeyValuePair<string, object?>(OtOpcUaTelemetry.PollOverrunDriverInstanceTag, driverInstanceId))));
}
/// <summary>Upper bound on the poll-loop failure backoff — adopts the S7-proven 30 s cap fleet-wide.</summary>
private static readonly TimeSpan PollBackoffCap = TimeSpan.FromSeconds(30);
/// <summary>
/// Routes a poll-loop reader failure to the driver health surface: logs it and
/// degrades to <see cref="DriverState.Degraded"/> preserving <c>LastSuccessfulRead</c>.
/// Never downgrades a <see cref="DriverState.Faulted"/> state (a stronger, config-level signal).
/// </summary>
/// <param name="ex">The exception caught by the poll engine.</param>
internal void HandlePollError(Exception ex)
{
_logger.LogWarning(ex, "TwinCAT poll reader failed. Driver={DriverInstanceId}", _driverInstanceId);
var current = _health;
if (current.State != DriverState.Faulted)
_health = new DriverHealth(DriverState.Degraded, current.LastSuccessfulRead, ex.Message);
}
/// <inheritdoc />
public string DriverInstanceId => _driverInstanceId;
/// <inheritdoc />
public string DriverType => "TwinCAT";
/// <inheritdoc />
/// <remarks>
/// An initialise that is overtaken before it commits — a <see cref="ShutdownAsync"/> / <see cref="Dispose"/>
/// or a newer <see cref="InitializeAsync"/> bumped the lifecycle generation while it was building — releases
/// what it built and throws <see cref="OperationCanceledException"/>. Cancellation is the honest outcome:
/// the work was abandoned by a later lifecycle call, not failed, so it must not write <c>Faulted</c> over
/// the newer state or let a caller believe this generation is live; returning normally would claim a
/// driver that was never installed. The runtime has usually abandoned the task by then, and an
/// overlapping retry treats it like any other cancelled attempt.
/// </remarks>
public async Task InitializeAsync(string driverConfigJson, CancellationToken cancellationToken)
{
// InitializeAsync is reachable on a live driver with no teardown first (the IDriver contract
// allows it, and a reconnect retry can overlap a running attempt). The new generation is BUILT
// first and published by one swap; the previous device states (probe loops, clients, native
// registrations) are released right after the swap — never orphaned, and a retained poll loop
// never sees an empty table in between. Deliberately NOT ShutdownAsync: that also drops _poll and
// the subscriptions.
long generation;
lock (_lifecycleLock)
{
generation = ++_lifecycleGeneration;
_health = new DriverHealth(DriverState.Initializing, null, null);
}
_warnedRefs.Clear();
var devices = NewDeviceTable();
var committed = false;
try
{
// Apply the supplied config generation. A blank or content-free document keeps the
// constructor-seeded options — that path covers callers that have already
// materialised options up front (the factory passes both, in agreement).
var options = _options;
if (!string.IsNullOrWhiteSpace(driverConfigJson))
{
var parsed = TwinCATDriverFactoryExtensions.ParseOptions(driverConfigJson, _driverInstanceId);
if (parsed.Devices.Count > 0 || parsed.RawTags.Count > 0)
options = parsed;
}
foreach (var device in options.Devices)
{
var addr = TwinCATAmsAddress.TryParse(device.HostAddress)
?? throw new InvalidOperationException(
$"TwinCAT device has invalid HostAddress '{device.HostAddress}' — expected 'ads://{{netId}}:{{port}}'.");
devices[device.HostAddress] = new DeviceState(addr, device);
}
// Build the RawPath → definition table from the authored raw tags. Each entry's TagConfig
// blob is mapped by the pure factory; the entry's WriteIdempotent flag AND its owning
// DeviceName are threaded onto the def (both live on the RawTagEntry, not inside the blob).
// DeviceName is resolved to the target's live host (def.DeviceHostAddress) via ResolveDeviceHost
// so the existing device routing (_devices keyed by HostAddress) is unchanged. A mapper miss is
// skipped (logged), never thrown — a bad tag must not fail the whole driver init.
var tags = new Dictionary<string, TwinCATTagDefinition>(StringComparer.Ordinal);
_skippedTags.BeginRebuild(options.RawTags.Count);
foreach (var entry in options.RawTags)
{
if (TwinCATTagDefinitionFactory.FromTagConfig(entry.TagConfig, entry.RawPath, out var def))
tags[entry.RawPath] = def with
{
WriteIdempotent = entry.WriteIdempotent,
DeviceHostAddress = ResolveDeviceHost(options, entry.DeviceName),
};
else
{
_skippedTags.Skip(entry.RawPath, "TagConfig did not map to a definition");
_logger.LogWarning(
"TwinCAT tag config did not map to a definition; skipping. Driver={DriverInstanceId} RawPath={RawPath}",
_driverInstanceId, entry.RawPath);
}
}
_skippedTags.Commit();
if (BeforeCommitForTest is { } pause) await pause().ConfigureAwait(false);
ConcurrentDictionary<string, DeviceState> previous;
lock (_lifecycleLock)
{
if (generation != _lifecycleGeneration)
throw new OperationCanceledException(
"TwinCAT InitializeAsync was superseded by a shutdown or a newer initialise while it ran.");
_options = options;
_tagsByRawPath = tags;
previous = _devices;
_devices = devices;
committed = true;
// Probe loops start INSIDE the commit so a teardown that swaps this generation out right
// after always finds (and cancels) them.
if (options.Probe.Enabled)
{
foreach (var state in devices.Values)
{
state.ProbeCts = new CancellationTokenSource();
var ct = state.ProbeCts.Token;
// Store the task so the teardown can join it.
state.ProbeTask = Task.Run(() => ProbeLoopAsync(state, ct), ct);
}
}
_health = new DriverHealth(DriverState.Healthy, DateTime.UtcNow, null);
}
// The replaced generation is now unreachable from the tables: release it (bounded).
await ReleaseDevicesAsync(previous.Values).ConfigureAwait(false);
}
catch (Exception ex) when (!committed)
{
// Nothing of this generation was published: release what was built. A superseded init leaves
// health to whoever overtook it.
await ReleaseDevicesAsync(devices.Values).ConfigureAwait(false);
if (ex is not OperationCanceledException)
{
lock (_lifecycleLock)
{
if (generation == _lifecycleGeneration)
_health = new DriverHealth(DriverState.Faulted, null, ex.Message);
}
}
throw;
}
}
/// <summary>
/// Releases a set of device states that have already been swapped out of <see cref="_devices"/>:
/// marks them released (so a probe wedged in the blocking ADS connect disposes the client it
/// eventually gets), disposes their native registrations (a re-initialise must not leave live ADS
/// notifications bound to a dead generation), cancels every probe loop and joins them all together
/// within <see cref="ProbeJoinTimeout"/>, then disposes their clients. The connect gates are NOT
/// disposed — an in-flight read/write may still hold one.
/// </summary>
/// <param name="states">The released device states (each owned by exactly one caller).</param>
private async Task ReleaseDevicesAsync(ICollection<DeviceState> states)
{
if (states.Count == 0) return;
var probes = BeginRelease(states);
if (probes.Count > 0)
{
try { await Task.WhenAll(probes).WaitAsync(ProbeJoinTimeout).ConfigureAwait(false); }
catch { /* cancelled, faulted or wedged in the synchronous ADS connect — teardown continues */ }
}
EndRelease(states);
}
/// <summary>The non-blocking first half of a release: mark, retract registrations, cancel probes.</summary>
private static List<Task> BeginRelease(ICollection<DeviceState> states)
{
var probes = new List<Task>(states.Count);
foreach (var state in states)
{
state.Released = true;
foreach (var reg in state.NativeRegistrations.Values) { try { reg.Dispose(); } catch { } }
try { state.ProbeCts?.Cancel(); } catch { /* already disposed */ }
if (state.ProbeTask is Task pt) probes.Add(pt);
}
return probes;
}
/// <summary>The second half of a release, after the bounded probe join: dispose CTSs and clients.</summary>
private static void EndRelease(ICollection<DeviceState> states)
{
foreach (var state in states)
{
try { state.ProbeCts?.Dispose(); } catch { }
state.ProbeCts = null;
state.ProbeTask = null;
try { state.DisposeClient(); } catch { /* best-effort */ }
}
}
/// <summary>
/// Swaps out every table AND the poll engine under the lifecycle lock and returns what the caller now
/// owns. Everything returned belongs to the retired generation only; nothing a later
/// <see cref="InitializeAsync"/> / <see cref="SubscribeAsync"/> creates is reachable from it.
/// </summary>
private (ICollection<DeviceState> devices, PollGroupEngine poll) TakeAllForTeardown()
{
lock (_lifecycleLock)
{
_lifecycleGeneration++;
var taken = _devices;
_devices = NewDeviceTable();
_tagsByRawPath = EmptyTags;
var poll = _poll;
_poll = CreatePollEngine();
return (taken.Values, poll.Engine);
}
}
/// <summary>The most recent teardown's background work (poll-engine dispose + device release). Test
/// visibility only: a cancelled shutdown leaves it running.</summary>
internal Task? LastTeardownForTest { get; private set; }
/// <inheritdoc />
public async Task ReinitializeAsync(string driverConfigJson, CancellationToken cancellationToken)
{
await ShutdownAsync(cancellationToken).ConfigureAwait(false);
await InitializeAsync(driverConfigJson, cancellationToken).ConfigureAwait(false);
}
/// <inheritdoc />
/// <remarks>
/// Safe to run concurrently with itself, with <see cref="DisposeAsync"/>/<see cref="Dispose"/> and with
/// an abandoned <see cref="InitializeAsync"/>: the tables are taken by one atomic swap, so each device
/// is released exactly once and an overtaken init releases its own generation. Bounded by
/// <see cref="ShutdownBudget"/>.
/// </remarks>
public async Task ShutdownAsync(CancellationToken cancellationToken)
{
// Native subs first — disposing the handles is cheap + lets the client close its
// notifications before the AdsClient itself goes away.
foreach (var sub in _nativeSubs.Values)
foreach (var r in sub.Registrations) { try { r.Dispose(); } catch { } }
_nativeSubs.Clear();
var (taken, retiredPoll) = TakeAllForTeardown();
// The poll loops and the device release wind down in parallel (releasing a client can unblock a
// poll loop stuck in a read on it); the whole teardown is bounded. Both halves own ONLY the retired
// generation, so finishing in the background after a cancelled wait is safe.
var teardown = Task.WhenAll(retiredPoll.DisposeAsync().AsTask(), ReleaseDevicesAsync(taken));
LastTeardownForTest = teardown;
var cancelled = false;
try { await teardown.WaitAsync(ShutdownBudget, cancellationToken).ConfigureAwait(false); }
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
{
// The caller stopped waiting. The tables are already swapped out and every loop is cancelled, so
// the rest of the teardown finishes in the background; report the cancellation after the cheap
// bookkeeping below.
cancelled = true;
}
catch (TimeoutException)
{
_logger.LogWarning(
"TwinCAT driver '{DriverInstanceId}' shutdown exceeded {Budget}; the remaining teardown continues in the background",
_driverInstanceId, ShutdownBudget);
}
catch { /* best-effort teardown */ }
_warnedRefs.Clear();
_resolver.Clear(); // no-op in v3 (the resolver reads the live table by closure); kept for symmetry
_health = new DriverHealth(DriverState.Unknown, _health.LastSuccessfulRead, null);
if (cancelled) throw new OperationCanceledException(cancellationToken);
}
/// <inheritdoc />
public DriverHealth GetHealth() => _health;
/// <summary>Gets the count of configured devices.</summary>
internal int DeviceCount => _devices.Count;
/// <summary>Gets the device state for the specified host address.</summary>
/// <param name="hostAddress">The ADS host address.</param>
/// <returns>Device state or null if not found.</returns>
internal DeviceState? GetDeviceState(string hostAddress) =>
_devices.TryGetValue(hostAddress, out var s) ? s : null;
// ---- IReadable ----
/// <inheritdoc />
public async Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
IReadOnlyList<string> fullReferences, CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(fullReferences);
var now = DateTime.UtcNow;
var results = new DataValueSnapshot[fullReferences.Count];
// With UseSumRead the reads for one device are gathered and issued as ADS sum-reads
// after this pass; everything else (and a device that refused the sum command) reads one by one.
Dictionary<DeviceState, List<SumReadEntry>>? buckets = null;
for (var i = 0; i < fullReferences.Count; i++)
{
var reference = fullReferences[i];
if (!_resolver.TryResolve(reference, out var def))
{
results[i] = new DataValueSnapshot(null, TwinCATStatusMapper.BadNodeIdUnknown, null, now);
continue;
}
if (!_devices.TryGetValue(def.DeviceHostAddress, out var device))
{
results[i] = new DataValueSnapshot(null, TwinCATStatusMapper.BadNodeIdUnknown, null, now);
continue;
}
if (_options.UseSumRead && !device.SumReadUnsupported)
{
var parsed = TwinCATSymbolPath.TryParse(def.SymbolPath);
var symbolName = parsed?.ToAdsSymbolName() ?? def.SymbolPath;
buckets ??= [];
if (!buckets.TryGetValue(device, out var bucket))
buckets[device] = bucket = [];
bucket.Add(new SumReadEntry(i, reference, def, symbolName, parsed?.BitIndex));
continue;
}
results[i] = await ReadOneAsync(reference, def, device, now, cancellationToken).ConfigureAwait(false);
}
if (buckets is not null)
foreach (var (device, bucket) in buckets)
await ReadBucketAsync(device, bucket, results, now, cancellationToken).ConfigureAwait(false);
return results;
}
private readonly record struct SumReadEntry(
int Index, string Reference, TwinCATTagDefinition Def, string SymbolName, int? BitIndex);
/// <summary>One tag read on its own — the pre-sum-read path, also the fallback for a refused sum command.</summary>
private async Task<DataValueSnapshot> ReadOneAsync(
string reference, TwinCATTagDefinition def, DeviceState device, DateTime now, CancellationToken cancellationToken)
{
try
{
var client = await EnsureConnectedAsync(device, cancellationToken).ConfigureAwait(false);
var parsed = TwinCATSymbolPath.TryParse(def.SymbolPath);
var symbolName = parsed?.ToAdsSymbolName() ?? def.SymbolPath;
// An array-typed tag (def.ArrayLength != null) reads the array as raw bytes and decodes
// it with TwinCATArrayCodec — the same decode a native array notification runs — into an
// element-typed CLR array. Scalar tags pass null (scalar path) — bit-indexed BOOLs are
// inherently scalar so the client ignores arrayCount when a bitIndex is present.
var (value, status) = await client.ReadValueAsync(
symbolName, def.DataType, parsed?.BitIndex, def.ArrayLength, cancellationToken)
.ConfigureAwait(false);
return CompleteRead(device, reference, def, symbolName, value, status, now);
}
catch (OperationCanceledException) { throw; }
catch (Exception ex)
{
MarkCommsFault(ex.Message, device);
return new DataValueSnapshot(null, TwinCATStatusMapper.BadCommunicationError, null, now);
}
}
/// <summary>Maps one read outcome to a snapshot and applies the health / log side effects.</summary>
private DataValueSnapshot CompleteRead(DeviceState device,
string reference, TwinCATTagDefinition def, string symbolName, object? value, uint status, DateTime now)
{
if (status == TwinCATStatusMapper.Good)
{
_warnedRefs.TryRemove(reference, out _); // a later failure is a new episode and warns again
RecordDeviceAnswered(now, device, force: true);
return new DataValueSnapshot(value, status, now, now);
}
// Once per tag per bad episode: a Warning every poll for every bad tag (50 typo'd symbols on a
// 500 ms poll = 100 Warnings/s) buried everything else in the log.
if (_warnedRefs.TryAdd(reference, 0))
{
if (status == TwinCATStatusMapper.BadTypeMismatch)
_logger.LogWarning(
"TwinCAT driver '{DriverInstanceId}' refused '{Reference}': declared {DataType} " +
"cannot decode the PLC symbol '{Symbol}' (string/numeric kind mismatch, array element type " +
"or length mismatch, or a reference/container); logged once until the tag reads Good",
_driverInstanceId, reference, def.DataType, symbolName);
else
_logger.LogWarning(
"TwinCAT driver '{DriverInstanceId}' ADS read error 0x{Status:X8} for '{Reference}'; " +
"logged once until the tag reads Good",
_driverInstanceId, status, reference);
}
if (IsCommsStatus(status))
MarkCommsFault($"ADS status {status:X8} reading {reference}", device);
else
RecordDeviceAnsweredKeepState(now); // a refusal: the device answered — no state change
return new DataValueSnapshot(value, status, now, now);
}
/// <summary>
/// Applies the health contract to a write the client returned a status for: Good is the device
/// answering (clears that device's comms fault, advances <c>LastSuccessfulRead</c>); a comms-class
/// status is a comms fault; anything else is a refusal — the device answered, the state is unchanged.
/// </summary>
private void NoteWriteOutcome(DeviceState device, uint status, string reference)
{
var now = DateTime.UtcNow;
if (status == TwinCATStatusMapper.Good) RecordDeviceAnswered(now, device, force: true);
else if (IsCommsStatus(status)) MarkCommsFault($"ADS status {status:X8} writing {reference}", device);
else RecordDeviceAnsweredKeepState(now);
}
/// <summary>
/// True for a status that means the request did not get a device answer (router / transport /
/// timeout). Every other non-Good status is the device refusing this one tag (symbol not found, type
/// mismatch, PLC not running, access denied): per-tag Bad with no health write.
/// </summary>
/// <param name="status">The mapped OPC UA status.</param>
/// <returns>True for a comms-class status.</returns>
internal static bool IsCommsStatus(uint status) =>
status is TwinCATStatusMapper.BadCommunicationError or TwinCATStatusMapper.BadTimeout;
/// <summary>Advances <c>LastSuccessfulRead</c> without changing the state (the device answered with a refusal).</summary>
private void RecordDeviceAnsweredKeepState(DateTime now)
{
var current = _health;
if (current.State is DriverState.Faulted or DriverState.Unknown or DriverState.Initializing) return;
_health = current with { LastSuccessfulRead = now };
}
/// <summary>
/// Reads one device's gathered tags as ADS sum-reads of at most <c>SumReadMaxItems</c> symbols each.
/// A target that refuses the sum command flips <see cref="DeviceState.SumReadUnsupported"/> and the
/// rest of the bucket is read individually; any other failure marks only the affected chunk Bad.
/// </summary>
private async Task ReadBucketAsync(
DeviceState device, List<SumReadEntry> bucket, DataValueSnapshot[] results, DateTime now,
CancellationToken cancellationToken)
{
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));
if (device.SumReadUnsupported || chunk.Count == 1)
{
foreach (var e in chunk)
results[e.Index] = await ReadOneAsync(e.Reference, e.Def, device, now, cancellationToken).ConfigureAwait(false);
continue;
}
// Set once the connect succeeded: a connect / backoff failure is the connect path's to report (it
// logs its own Warning) and must not consume the once-per-device sum-chunk-failure Warning below.
var connected = false;
try
{
var client = await EnsureConnectedAsync(device, cancellationToken).ConfigureAwait(false);
connected = true;
var items = new TwinCATBulkReadItem[chunk.Count];
for (var k = 0; k < chunk.Count; k++)
items[k] = new TwinCATBulkReadItem(chunk[k].SymbolName, chunk[k].Def.DataType, chunk[k].BitIndex, chunk[k].Def.ArrayLength);
var fallbacksBefore = client.SumFallbackCount;
var bulk = await client.ReadValuesAsync(items, cancellationToken).ConfigureAwait(false);
if (client.SumFallbackCount > fallbacksBefore && !device.SumFallbackWarned)
{
device.SumFallbackWarned = true;
_logger.LogWarning(
"TwinCAT driver '{DriverInstanceId}' device '{Device}': the target rejected an ADS sum-read " +
"request (ADS error {AdsError}; 0 = malformed response) and the chunk was read singly. Sum-read " +
"is not working on this target; this warning is logged once per device",
_driverInstanceId, device.Options.HostAddress, client.LastSumFallbackCode);
}
for (var k = 0; k < chunk.Count; k++)
{
var e = chunk[k];
var (value, status) = k < bulk.Count ? bulk[k] : (null, TwinCATStatusMapper.BadCommunicationError);
results[e.Index] = CompleteRead(device, e.Reference, e.Def, e.SymbolName, value, status, now);
}
}
catch (OperationCanceledException) { throw; }
catch (TwinCATSumReadRefusedException refused)
{
device.SumReadUnsupported = true;
_logger.LogWarning(
"TwinCAT driver '{DriverInstanceId}' device '{Device}' refused the ADS sum-read command " +
"(ADS error {AdsError}); falling back to individual reads for this device",
_driverInstanceId, device.Options.HostAddress, refused.AdsErrorCode);
foreach (var e in chunk)
results[e.Index] = await ReadOneAsync(e.Reference, e.Def, device, now, cancellationToken).ConfigureAwait(false);
}
catch (Exception ex)
{
foreach (var e in chunk)
results[e.Index] = new DataValueSnapshot(null, TwinCATStatusMapper.BadCommunicationError, null, now);
MarkCommsFault(ex.Message, device);
// Once per device: the health message is overwritten by the next good read in the same poll, so
// without this a sum-read path failing on every poll left no trace (hw2 live gate, 2026-10-08).
if (connected && !device.SumChunkFailureWarned)
{
device.SumChunkFailureWarned = true;
_logger.LogWarning(ex,
"TwinCAT driver '{DriverInstanceId}' device '{Device}': an ADS sum-read chunk of {Count} tags " +
"failed and was reported BadCommunicationError; this warning is logged once per device",
_driverInstanceId, device.Options.HostAddress, chunk.Count);
}
}
}
}
// ---- IWritable ----
/// <inheritdoc />
public async Task<IReadOnlyList<WriteResult>> WriteAsync(
IReadOnlyList<WriteRequest> writes, CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(writes);
var results = new WriteResult[writes.Count];
for (var i = 0; i < writes.Count; i++)
{
var w = writes[i];
if (!_resolver.TryResolve(w.FullReference, out var def))
{
results[i] = new WriteResult(TwinCATStatusMapper.BadNodeIdUnknown);
continue;
}
if (!def.Writable)
{
results[i] = new WriteResult(TwinCATStatusMapper.BadNotWritable);
continue;
}
if (!_devices.TryGetValue(def.DeviceHostAddress, out var device))
{
results[i] = new WriteResult(TwinCATStatusMapper.BadNodeIdUnknown);
continue;
}
try
{
var parsed = TwinCATSymbolPath.TryParse(def.SymbolPath);
var bitIndex = def.DataType == TwinCATDataType.Bool ? parsed?.BitIndex : null;
// Shape checks run BEFORE any wire traffic (connect included): an array write needs exactly
// ArrayLength elements, each converted to the declared element type (a CLR int[] to an Int16
// array converts; it is not exact-matched) — a length mismatch / out-of-range element is
// OverflowException (BadOutOfRange), a scalar value InvalidCastException (BadTypeMismatch).
var bitValue = bitIndex is not null ? Convert.ToBoolean(w.Value) : false;
var elements = bitIndex is null && def.ArrayLength is int arrayLength
? TwinCATArrayCodec.ToWriteElements(def.DataType, w.Value, arrayLength)
: null;
var client = await EnsureConnectedAsync(device, cancellationToken).ConfigureAwait(false);
// BOOL-within-word write — a read-modify-write of the parent word at the parent's OWN
// width and on raw bytes (the client resolves the parent and checks the bit against it, the
// notification path's model), under a per-parent lock so concurrent bit writers to the same
// word don't lose each other's updates.
if (bitIndex is int bit)
{
var parentPath = (parsed! with { BitIndex = null }).ToAdsSymbolName();
var gate = _bitRmwLocks.GetOrAdd(
$"{def.DeviceHostAddress}|{parentPath}", static _ => new SemaphoreSlim(1, 1));
await gate.WaitAsync(cancellationToken).ConfigureAwait(false);
try
{
results[i] = new WriteResult(await client.WriteBitAsync(
parentPath, bit, bitValue, cancellationToken).ConfigureAwait(false));
}
finally
{
gate.Release();
}
NoteWriteOutcome(device, results[i].StatusCode, w.FullReference);
continue;
}
var symbolName = parsed?.ToAdsSymbolName() ?? def.SymbolPath;
if (elements is not null)
{
// Array tag: raw bytes encoded by TwinCATArrayCodec at the layout planned from the PLC
// array — the inverse of the array read.
results[i] = new WriteResult(await client.WriteArrayAsync(
symbolName, def.DataType, elements, cancellationToken).ConfigureAwait(false));
NoteWriteOutcome(device, results[i].StatusCode, w.FullReference);
continue;
}
var status = await client.WriteValueAsync(
symbolName, def.DataType, parsed?.BitIndex, w.Value, cancellationToken).ConfigureAwait(false);
results[i] = new WriteResult(status);
NoteWriteOutcome(device, status, w.FullReference);
}
catch (OperationCanceledException) { throw; }
catch (NotSupportedException)
{
// A write the client cannot express is a refusal, not a comms fault (#611): no health
// write, or the comms-loss watchdog would reconnect a healthy device over a config issue.
results[i] = new WriteResult(TwinCATStatusMapper.BadNotSupported);
}
catch (Exception ex) when (ex is FormatException or InvalidCastException)
{
results[i] = new WriteResult(TwinCATStatusMapper.BadTypeMismatch);
}
catch (OverflowException)
{
results[i] = new WriteResult(TwinCATStatusMapper.BadOutOfRange);
}
catch (Exception ex)
{
results[i] = new WriteResult(TwinCATStatusMapper.BadCommunicationError);
MarkCommsFault(ex.Message, device);
}
}
return results;
}
// ---- ITagDiscovery ----
/// <inheritdoc />
// Run-once: DiscoverAsync emits pre-declared tags and (when EnableControllerBrowse is set)
// fully awaits the controller symbol browse within the single call, streaming the complete
// node set in one pass — nothing fills in asynchronously after connect, so a single
// discovery pass is sufficient.
public DiscoveryRediscoverPolicy RediscoverPolicy => DiscoveryRediscoverPolicy.Once;
// ADS symbol upload is real device enumeration - config-gated on EnableControllerBrowse, which the
// universal browser's PatchForBrowse guarantees at open time.
/// <inheritdoc />
public bool SupportsOnlineDiscovery => true;
/// <inheritdoc />
public async Task DiscoverAsync(IAddressSpaceBuilder builder, CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(builder);
var root = builder.Folder("TwinCAT", "TwinCAT");
foreach (var device in _options.Devices)
{
var label = device.DeviceName ?? device.HostAddress;
var deviceFolder = root.Folder(device.HostAddress, label);
// Authored raw tags (mapped into the RawPath → def table at Initialize) — always emitted
// as the authoritative config path. The def's Name is the RawPath, used for both the browse
// name and the driver FullName; it is routed to this device by def.DeviceHostAddress.
var tagsForDevice = _tagsByRawPath.Values.Where(t =>
string.Equals(t.DeviceHostAddress, device.HostAddress, StringComparison.OrdinalIgnoreCase));
foreach (var tag in tagsForDevice)
{
deviceFolder.Variable(tag.Name, tag.Name, new DriverAttributeInfo(
FullName: tag.Name,
DriverDataType: tag.DataType.ToDriverDataType(),
// A pre-declared tag with a positive ArrayLength is a 1-D array node; null
// (or non-positive) stays scalar (Phase 4c).
IsArray: tag.ArrayLength is > 0,
ArrayDim: tag.ArrayLength is > 0 ? (uint)tag.ArrayLength.Value : null,
SecurityClass: tag.Writable
? SecurityClassification.Operate
: SecurityClassification.ViewOnly,
IsHistorized: false,
IsAlarm: false,
WriteIdempotent: tag.WriteIdempotent,
NativeDataType: tag.DataType.ToString()));
}
// Controller-side symbol browse — opt-in. Falls back to pre-declared-only on any
// client-side error so a flaky symbol-table download doesn't block discovery.
if (_options.EnableControllerBrowse && _devices.TryGetValue(device.HostAddress, out var state))
{
IAddressSpaceBuilder? discoveredFolder = null;
try
{
var client = await EnsureConnectedAsync(state, cancellationToken).ConfigureAwait(false);
await foreach (var sym in client.BrowseSymbolsAsync(cancellationToken).ConfigureAwait(false))
{
if (TwinCATSystemSymbolFilter.IsSystemSymbol(sym.InstancePath)) continue;
if (sym.DataType is not TwinCATDataType dt) continue; // unsupported type
discoveredFolder ??= deviceFolder.Folder("Discovered", "Discovered");
discoveredFolder.Variable(sym.InstancePath, sym.InstancePath, new DriverAttributeInfo(
FullName: sym.InstancePath,
DriverDataType: dt.ToDriverDataType(),
// A discovered 1-D array symbol carries its element count in
// sym.ArrayLength (the browser reports the ELEMENT type as dt);
// multi-dim/unsupported arrays arrive with null ArrayLength → scalar
// (Phase 4c).
IsArray: sym.ArrayLength is > 0,
ArrayDim: sym.ArrayLength is > 0 ? (uint)sym.ArrayLength.Value : null,
SecurityClass: sym.ReadOnly
? SecurityClassification.ViewOnly
: SecurityClassification.Operate,
IsHistorized: false,
IsAlarm: false,
WriteIdempotent: false,
NativeDataType: dt.ToString()));
}
}
catch (OperationCanceledException) { throw; }
catch (Exception ex)
{
// Symbol-loader failure is non-fatal to discovery — pre-declared tags already
// shipped. Log so operators can correlate the partial discovery.
_logger.LogWarning(ex,
"TwinCAT driver '{DriverInstanceId}' symbol browse failed for device " +
"'{HostAddress}'; falling back to pre-declared tags only",
_driverInstanceId, device.HostAddress);
}
}
}
}
// ---- ISubscribable (native ADS notifications with poll fallback) ----
private readonly ConcurrentDictionary<long, NativeSubscription> _nativeSubs = new();
private long _nextNativeSubId;
private long _nextRegId;
/// <inheritdoc />
// Subscribe via native ADS notifications when TwinCATDriverOptions.UseNativeNotifications is
// true, otherwise fall through to the shared PollGroupEngine. Native path registers one
// notification per tag against the target's PLC runtime — the PLC pushes changes on its own
// cycle so we skip the poll loop entirely. Each registration stores its REPLAYABLE INTENT on
// the owning device so EnsureConnectedAsync can re-register it after a reconnect.
public async Task<ISubscriptionHandle> SubscribeAsync(
IReadOnlyList<string> fullReferences, TimeSpan publishingInterval, CancellationToken cancellationToken)
{
if (!_options.UseNativeNotifications)
{
// A teardown racing this call may retire the engine we read: re-home the subscription on the
// current one so it never lives in an engine that is being disposed.
while (true)
{
var generation = _poll;
var inner = generation.Engine.Subscribe(fullReferences, publishingInterval);
if (ReferenceEquals(generation, _poll)) return new TwinCATPollHandle(generation.Serial, inner);
generation.Engine.Unsubscribe(inner);
}
}
var id = Interlocked.Increment(ref _nextNativeSubId);
var handle = new NativeSubscriptionHandle(id);
var registrations = new List<NativeRegistration>(fullReferences.Count);
// Devices whose connect failed during THIS call: the rest of their tags are stored as dead
// intents straight away rather than each paying (and logging) its own failed connect.
HashSet<DeviceState>? unreachable = null;
try
{
foreach (var reference in fullReferences)
{
// An unresolvable reference (unknown RawPath, or a tag routed to an unconfigured device)
// publishes BadNodeIdUnknown once — the poll path's status — instead of leaving the node on
// whatever status the server seeded it with.
if (!_resolver.TryResolve(reference, out var def)
|| !_devices.TryGetValue(def.DeviceHostAddress, out var device))
{
RaiseDataChange(handle, reference, new DataValueSnapshot(
null, TwinCATStatusMapper.BadNodeIdUnknown, null, DateTime.UtcNow));
continue;
}
var parsed = TwinCATSymbolPath.TryParse(def.SymbolPath);
var symbolName = parsed?.ToAdsSymbolName() ?? def.SymbolPath;
var bitIndex = parsed?.BitIndex;
// The callback closes over the stable (handle, reference) pair, so it survives a
// client swap unchanged — replay re-registers the SAME intent onto the new client.
var reg = new NativeRegistration(
Interlocked.Increment(ref _nextRegId), device, reference, symbolName,
def.DataType, bitIndex, def.ArrayLength, publishingInterval,
onChange: (_, value) =>
{
// A push is the device answering: stamp LastSuccessfulRead so a notification-only
// driver does not look silent to the comms-loss watchdog.
var now = DateTime.UtcNow;
RecordDeviceAnswered(now, device);
RaiseDataChange(handle, reference, new DataValueSnapshot(value, TwinCATStatusMapper.Good, now, now));
},
// When the handle goes dead (a failed replay) push a Bad snapshot so
// subscribers see the tag go Bad instead of a frozen-Good-stale value.
onUnavailable: status => RaiseDataChange(handle, reference, new DataValueSnapshot(
null, status, null, DateTime.UtcNow)));
registrations.Add(reg);
if (unreachable?.Contains(device) == true)
{
// Same device already failed to connect in this call: keep the intent dead for the
// probe-tick retry / reconnect replay and surface Bad now.
device.NativeRegistrations[reg.Id] = reg;
NoteDeadFailure(reg, TwinCATStatusMapper.BadCommunicationError, refused: false, DateTime.UtcNow);
RaiseDataChange(handle, reference, new DataValueSnapshot(
null, TwinCATStatusMapper.BadCommunicationError, null, DateTime.UtcNow));
continue;
}
try
{
await RegisterNotificationAsync(device, reg, cancellationToken).ConfigureAwait(false);
}
catch (OperationCanceledException) { throw; }
catch (TwinCATNotificationRefusedException refused)
{
// The device answered and refused THIS tag (declared type cannot decode the symbol,
// array over the notification cap, symbol not found): isolate it — one WARN, one
// snapshot carrying the refusal's status, no health write (a refusal is not a comms
// fault). Its intent stays on the device with no live handle, so the probe-tick retry
// re-checks it after a PLC program change.
_logger.LogWarning(
"TwinCAT driver '{DriverInstanceId}' refused native notification for '{Reference}': {Reason}",
_driverInstanceId, reference, refused.Message);
NoteDeadFailure(reg, refused.StatusCode, refused: true, DateTime.UtcNow);
RaiseDataChange(handle, reference, new DataValueSnapshot(
null, refused.StatusCode, null, DateTime.UtcNow));
}
catch (DeviceUnavailableException unavailable)
{
// The device could not be connected (offline, router down, backoff window open).
// Every tag of this device goes Bad + dead for the retry; other devices carry on.
(unreachable ??= []).Add(device);
MarkCommsFault(unavailable.InnerException?.Message ?? unavailable.Message, device);
NoteDeadFailure(reg, TwinCATStatusMapper.BadCommunicationError, refused: false, DateTime.UtcNow);
RaiseDataChange(handle, reference, new DataValueSnapshot(
null, TwinCATStatusMapper.BadCommunicationError, null, DateTime.UtcNow));
}
catch (Exception ex)
{
// A per-tag registration failure that is not a refusal (the AddDeviceNotification
// round-trip failed): this tag goes Bad + dead for the retry; the rest keep going.
_logger.LogWarning(ex,
"TwinCAT driver '{DriverInstanceId}' native-notification registration failed for " +
"'{Reference}'; it will be retried on the next healthy probe tick",
_driverInstanceId, reference);
MarkCommsFault(ex.Message, device);
NoteDeadFailure(reg, TwinCATStatusMapper.BadCommunicationError, refused: false, DateTime.UtcNow);
RaiseDataChange(handle, reference, new DataValueSnapshot(
null, TwinCATStatusMapper.BadCommunicationError, null, DateTime.UtcNow));
}
}
}
catch (OperationCanceledException)
{
// Cancelled mid-subscribe: leave the subscription in a clean "never existed" state rather
// than a half-registered one the caller has to clean up.
foreach (var r in registrations) { try { r.Dispose(); } catch { } }
throw;
}
_nativeSubs[id] = new NativeSubscription(handle, registrations);
return handle;
}
/// <summary>
/// The device state was released (re-initialise / teardown) while a connect on it ran. Not an
/// <see cref="OperationCanceledException"/>: the caller's token was not cancelled, so the data path maps
/// it like any failed request (Bad for this call) and <see cref="MarkCommsFault"/> ignores it.
/// </summary>
private sealed class DeviceReleasedException(string host)
: Exception($"TwinCAT device {host} was released during connect.");
/// <summary>The connect step of a native registration failed — the whole device is unreachable.</summary>
private sealed class DeviceUnavailableException(Exception inner)
: Exception("TwinCAT device unreachable: " + inner.Message, inner);
/// <summary>
/// Records a comms fault: <see cref="DriverState.Degraded"/> preserving <c>LastSuccessfulRead</c>.
/// Never downgrades <see cref="DriverState.Faulted"/>. A fault observed on a device is remembered ON
/// that device (<see cref="DeviceState.CommsFault"/>) and only that device answering clears it — the
/// driver state is the worst of every device (#739 fix round 1).
/// </summary>
/// <param name="message">The fault description.</param>
/// <param name="device">The device the fault was observed on; a fault on a device already swapped out of
/// the table (a read/write racing a re-initialise or teardown) belongs to a dead generation and is
/// not recorded.</param>
private void MarkCommsFault(string message, DeviceState? device = null)
{
if (device?.Released == true) return;
if (device is not null) device.CommsFault = message;
var current = _health;
if (current.State != DriverState.Faulted)
_health = new DriverHealth(DriverState.Degraded, current.LastSuccessfulRead, message);
}
/// <summary>
/// Consecutive failed probe ticks (connect failure, failed ReadState) after which a device counts as
/// unreachable and the driver goes <see cref="DriverState.Degraded"/> with <c>LastSuccessfulRead</c>
/// preserved — so an unreachable AMS router reaches the comms-loss watchdog instead of leaving the
/// driver Healthy with stale-Good values. Three ticks ride out a single dropped ReadState.
/// </summary>
internal const int ProbeFailuresBeforeDegraded = 3;
/// <summary>Minimum spacing between <c>LastSuccessfulRead</c> stamps from the notification path.</summary>
private static readonly TimeSpan AnsweredStampInterval = TimeSpan.FromMilliseconds(250);
/// <summary>
/// Why one device keeps the driver Degraded, or null when it does not: probe-unreachable, a PLC whose
/// ADS state is not <c>Run</c> (coordinator ruling: a stopped / config-mode PLC is Degraded with a
/// reason even though it answers), or an uncleared comms fault seen on it.
/// </summary>
/// <remarks>
/// The ADS state comes from the probe's ReadState, so PLC-not-in-RUN detection needs the probe
/// (<c>Probe.Enabled</c>, the default); with the probe off the state is unknown and never degrades.
/// </remarks>
private static string? DeviceDegradedReason(DeviceState d)
{
if (d.ConsecutiveProbeFailures >= ProbeFailuresBeforeDegraded)
return $"TwinCAT device {d.Options.HostAddress} unreachable ({d.ConsecutiveProbeFailures} consecutive failed probes)";
if (d.PlcState is { } st && !string.Equals(st, "Run", StringComparison.OrdinalIgnoreCase))
return $"TwinCAT device {d.Options.HostAddress}: PLC in {st}";
return d.CommsFault;
}
/// <summary>
/// Records that a device answered (a native push, a successful probe, a Good read): clears THAT
/// device's comms fault, advances <c>LastSuccessfulRead</c>, and sets the state to the worst of every
/// device — Healthy only when no device is unreachable, out of RUN or still faulted (then Degraded
/// with that device's reason; the stamp still advances, since a device did answer). Throttled so a
/// notification burst does not allocate a health record per value; never touches Faulted.
/// </summary>
/// <param name="now">The time the device answered.</param>
/// <param name="device">The device that answered; null when not attributable.</param>
/// <param name="force">Write even inside the throttle window (an explicit read / probe outcome).</param>
private void RecordDeviceAnswered(DateTime now, DeviceState? device = null, bool force = false)
{
if (device?.Released == true) return;
if (device?.CommsFault is not null)
{
device.CommsFault = null;
force = true;
}
var current = _health;
if (current.State == DriverState.Faulted) return;
// Hot path (a notification on a healthy driver inside the window): no device scan, no allocation.
if (!force && current.State == DriverState.Healthy && current.LastSuccessfulRead is { } recent
&& now - recent < AnsweredStampInterval)
return;
string? reason = null;
foreach (var d in _devices.Values)
if ((reason = DeviceDegradedReason(d)) is not null) break;
var state = reason is null ? DriverState.Healthy : DriverState.Degraded;
if (!force && current.State == state && current.LastSuccessfulRead is { } last
&& now - last < AnsweredStampInterval)
return;
_health = new DriverHealth(state, now, reason);
}
/// <summary>First probe-tick retry delay of a REFUSED dead registration (the PLC answered and refused it).</summary>
internal static readonly TimeSpan RefusedRetryInitial = TimeSpan.FromSeconds(30);
/// <summary>Cap of the refused-registration retry backoff.</summary>
internal static readonly TimeSpan RefusedRetryMax = TimeSpan.FromMinutes(10);
/// <summary>
/// Books a failed registration attempt. A REFUSAL is deterministic until the PLC program changes, so it
/// backs off exponentially (30 s doubling to 10 min) and is re-armed at once by a symbol-version change
/// or retried by the reconnect replay; a comms-class failure stays on the every-tick retry.
/// </summary>
/// <returns>True when the published status changes (the caller republishes the tag).</returns>
/// <param name="reg">The registration.</param>
/// <param name="status">The status the failure maps to.</param>
/// <param name="refused">True for a refusal (backs off), false for a comms-class failure.</param>
/// <param name="now">The failure time.</param>
/// <param name="epochAtAttempt">The registration's <see cref="NativeRegistration.RearmEpoch"/> when the attempt
/// started; when a re-arm happened while it was in flight the backoff is NOT re-imposed (the re-arm wins).</param>
private static bool NoteDeadFailure(NativeRegistration reg, uint status, bool refused, DateTime now,
int? epochAtAttempt = null)
{
if (epochAtAttempt is int epoch && epoch != reg.RearmEpoch)
{
// A symbol-version change re-armed this registration mid-attempt: keep it re-armed.
}
else if (refused)
{
reg.RefusalBackoff = reg.RefusalBackoff == TimeSpan.Zero
? RefusedRetryInitial
: TimeSpan.FromTicks(Math.Min(reg.RefusalBackoff.Ticks * 2, RefusedRetryMax.Ticks));
reg.NextRetryUtc = now + reg.RefusalBackoff;
}
else
{
reg.RefusalBackoff = TimeSpan.Zero;
reg.NextRetryUtc = DateTime.MinValue;
}
var changed = reg.DeadStatus != status;
reg.DeadStatus = status;
return changed;
}
/// <summary>Clears the dead-registration bookkeeping after a successful (re-)registration.</summary>
private static void NoteLive(NativeRegistration reg)
{
reg.DeadStatus = null;
reg.RefusalBackoff = TimeSpan.Zero;
reg.NextRetryUtc = DateTime.MinValue;
}
/// <summary>
/// Raises one data change for a native subscription on BOTH events: the per-tag one (legacy consumers)
/// and a one-item batch (a fresh list per raise — the consumer may retain it).
/// </summary>
private void RaiseDataChange(ISubscriptionHandle handle, string reference, DataValueSnapshot snapshot)
{
OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, reference, snapshot));
OnDataChangeBatch?.Invoke(this, new DataChangeBatchEventArgs(handle, [new DataChangeItem(reference, snapshot)]));
}
/// <summary>
/// Registers one native notification and records its replayable intent on the device — both
/// under the device <see cref="DeviceState.ConnectGate"/> so the register can't race a
/// concurrent reconnect-replay (which also runs under that gate). The intent is added to the
/// device registry only AFTER the handle is live, so a replay triggered by this same
/// <c>EnsureConnected</c> can't double-register the not-yet-stored tag.
/// </summary>
private async Task RegisterNotificationAsync(DeviceState device, NativeRegistration reg, CancellationToken ct)
{
await device.ConnectGate.WaitAsync(ct).ConfigureAwait(false);
try
{
ITwinCATClient client;
try
{
client = await EnsureConnectedUnderGateAsync(device, ct, timeoutOverride: null).ConfigureAwait(false);
}
catch (OperationCanceledException) { throw; }
catch (Exception ex)
{
// Keep the intent dead (no live handle): the replay after the next successful connect
// re-registers it. The caller short-circuits the rest of this device's tags.
device.NativeRegistrations[reg.Id] = reg;
throw new DeviceUnavailableException(ex);
}
ITwinCATNotificationHandle newHandle;
try
{
newHandle = await client.AddNotificationAsync(
reg.SymbolName, reg.DataType, reg.BitIndex, reg.ArrayLength, reg.Interval,
_options.NotificationMaxDelayMs, reg.OnChange, ct).ConfigureAwait(false);
}
catch (OperationCanceledException) { throw; }
catch
{
// Keep the intent with no live handle (a "dead" registration) so the probe-tick
// retry re-checks it and UnsubscribeAsync still removes it; the caller isolates it.
device.NativeRegistrations[reg.Id] = reg;
throw;
}
reg.SwapHandle(newHandle); // initial set — previous handle is null
device.NativeRegistrations[reg.Id] = reg;
}
finally
{
device.ConnectGate.Release();
}
}
/// <inheritdoc />
public async Task UnsubscribeAsync(ISubscriptionHandle handle, CancellationToken cancellationToken)
{
if (handle is NativeSubscriptionHandle native && _nativeSubs.TryRemove(native.Id, out var sub))
{
// NativeRegistration.Dispose removes itself from its device registry (so a later replay
// won't touch it) and disposes its live handle.
foreach (var r in sub.Registrations) { try { r.Dispose(); } catch { } }
return;
}
// Async teardown: the engine drains the in-flight poll without blocking the caller's
// thread — this runs inside a DriverInstanceActor mailbox turn.
// A handle of a retired generation has nothing left to stop: its engine was disposed with it.
var current = _poll;
if (handle is TwinCATPollHandle poll && poll.Generation == current.Serial)
await current.Engine.UnsubscribeAsync(poll.Inner).ConfigureAwait(false);
}
private sealed record NativeSubscriptionHandle(long Id) : ISubscriptionHandle
{
/// <inheritdoc />
public string DiagnosticId => $"twincat-native-sub-{Id}";
}
private sealed record NativeSubscription(
NativeSubscriptionHandle Handle,
IReadOnlyList<NativeRegistration> Registrations);
/// <summary>
/// One live native-notification registration: its replayable intent plus the current live
/// <see cref="ITwinCATNotificationHandle"/>. The handle is swapped (not re-created) when the
/// device reconnects, so unsubscribe / teardown always dispose the latest one. The handle
/// field is exchanged atomically so a reconnect-replay swap and an unsubscribe dispose can't
/// corrupt each other on the common path.
/// </summary>
internal sealed class NativeRegistration : IDisposable
{
/// <summary>Globally-unique registration id (registry key on the device).</summary>
public long Id { get; }
/// <summary>The device this notification is registered against.</summary>
public DeviceState Device { get; }
/// <summary>Driver-side full reference the pushed value is reported under.</summary>
public string Reference { get; }
/// <summary>ADS symbol name (resolved from the symbol path).</summary>
public string SymbolName { get; }
/// <summary>Declared data type.</summary>
public TwinCATDataType DataType { get; }
/// <summary>Bit index for a BOOL-within-word symbol; null otherwise.</summary>
public int? BitIndex { get; }
/// <summary>Authored array length — the whole array is registered and published; null for a scalar.</summary>
public int? ArrayLength { get; }
/// <summary>Requested notification interval.</summary>
public TimeSpan Interval { get; }
/// <summary>Value-change callback (closes over the owning subscription handle + reference).</summary>
public Action<string, object?> OnChange { get; }
/// <summary>
/// Bad-quality callback. Invoked when this registration's handle goes dead
/// (a failed replay) so subscribers observe the tag go Bad instead of frozen-Good-stale —
/// the <see cref="OnChange"/> shape has no quality channel. Closes over the same
/// (handle, reference) pair as <see cref="OnChange"/>.
/// </summary>
public Action<uint> OnUnavailableStatus { get; }
/// <summary>Publishes <c>BadCommunicationError</c> for a handle that went dead on a comms failure.</summary>
public void OnUnavailable() => OnUnavailableStatus(TwinCATStatusMapper.BadCommunicationError);
/// <summary>Publishes the status of a refusal (the PLC answered and refused this tag).</summary>
/// <param name="status">The refusal's OPC UA status.</param>
public void OnRefused(uint status) => OnUnavailableStatus(status);
private ITwinCATNotificationHandle? _handle;
/// <summary>
/// True while this registration holds a live notification handle. False after a failed
/// replay marks it dead — the probe-tick retry re-registers such handles.
/// </summary>
public bool HasLiveHandle => Volatile.Read(ref _handle) is not null;
/// <summary>Initializes a new instance of the <see cref="NativeRegistration"/> class.</summary>
/// <param name="id">Globally-unique registration id (registry key on the device).</param>
/// <param name="device">The device this notification is registered against.</param>
/// <param name="reference">Driver-side full reference the pushed value is reported under.</param>
/// <param name="symbolName">ADS symbol name (resolved from the symbol path).</param>
/// <param name="dataType">Declared data type.</param>
/// <param name="bitIndex">Bit index for a BOOL-within-word symbol; null otherwise.</param>
/// <param name="arrayLength">Authored array length for an array tag; null for a scalar.</param>
/// <param name="interval">Requested notification interval.</param>
/// <param name="onChange">Value-change callback (closes over the owning subscription handle + reference).</param>
/// <param name="onUnavailable">Bad-quality callback (given the status to publish) fired when the handle goes dead.</param>
public NativeRegistration(long id, DeviceState device, string reference, string symbolName,
TwinCATDataType dataType, int? bitIndex, int? arrayLength, TimeSpan interval, Action<string, object?> onChange,
Action<uint> onUnavailable)
{
Id = id;
Device = device;
Reference = reference;
SymbolName = symbolName;
DataType = dataType;
BitIndex = bitIndex;
ArrayLength = arrayLength;
Interval = interval;
// A notification already queued in the client's dispatch channel can be delivered after this
// registration is disposed (unsubscribe / teardown): drop it here, for every client.
OnChange = (symbol, value) => { if (!IsDisposed) onChange(symbol, value); };
OnUnavailableStatus = status => { if (!IsDisposed) onUnavailable(status); };
}
/// <summary>Installs a freshly-registered handle and returns the previous one (null on first set).</summary>
/// <param name="newHandle">The newly-registered notification handle.</param>
/// <returns>The previous handle, or null.</returns>
public ITwinCATNotificationHandle? SwapHandle(ITwinCATNotificationHandle newHandle) =>
Interlocked.Exchange(ref _handle, newHandle);
/// <summary>
/// Atomically clears the live handle and returns the previous one. The caller
/// disposes the returned (already-dead) handle best-effort. After this
/// <see cref="HasLiveHandle"/> is false until a retry re-registers.
/// </summary>
/// <returns>The previous handle, or null.</returns>
public ITwinCATNotificationHandle? MarkHandleDead() =>
Interlocked.Exchange(ref _handle, null);
/// <summary>The Bad status last published for this registration while dead; null while live.</summary>
public uint? DeadStatus { get; set; }
/// <summary>Earliest time the probe-tick retry may re-attempt this dead registration.</summary>
public DateTime NextRetryUtc { get; set; }
/// <summary>Current refusal backoff (zero after a comms-class failure, a success or a re-arm).</summary>
public TimeSpan RefusalBackoff { get; set; }
private int _rearmEpoch;
/// <summary>Bumped by every symbol-version re-arm; a retry that started before it must not re-impose a backoff.</summary>
public int RearmEpoch => Volatile.Read(ref _rearmEpoch);
/// <summary>
/// Re-arms the retry after a PLC program change: retry on the next tick and restart the backoff
/// from <see cref="RefusedRetryInitial"/> (the refusal it backed off from may no longer apply).
/// </summary>
public void Rearm()
{
Interlocked.Increment(ref _rearmEpoch);
RefusalBackoff = TimeSpan.Zero;
NextRetryUtc = DateTime.MinValue;
}
private volatile bool _disposed;
/// <summary>Gets a value indicating whether this registration has been disposed (its callbacks are dropped).</summary>
public bool IsDisposed => _disposed;
/// <summary>Removes this registration from its device and disposes its live handle.</summary>
public void Dispose()
{
_disposed = true;
Device.NativeRegistrations.TryRemove(Id, out _);
var h = Interlocked.Exchange(ref _handle, null);
try { h?.Dispose(); } catch { /* best-effort */ }
}
}
// ---- IHostConnectivityProbe ----
/// <inheritdoc />
public IReadOnlyList<HostConnectivityStatus> GetHostStatuses() =>
[.. _devices.Values.Select(s => new HostConnectivityStatus(s.Options.HostAddress, s.HostState, s.HostStateChangedUtc))];
private async Task ProbeLoopAsync(DeviceState state, CancellationToken ct)
{
while (!ct.IsCancellationRequested)
{
var success = false;
ITwinCATClient? probed = null;
try
{
// Probe-initiated connects honor TwinCATProbeOptions.Timeout — distinct from
// the driver-wide _options.Timeout used by reads/writes.
// The probe bypasses the connect backoff — its own interval is the bounded recovery
// cadence, and a successful probe connect resets the window for the data path.
var client = await EnsureConnectedAsync(state, ct, _options.Probe.Timeout, bypassBackoff: true)
.ConfigureAwait(false);
success = await client.ProbeAsync(ct).ConfigureAwait(false);
// The probe's ReadState also says whether the PLC is in RUN; a stopped PLC answers but
// serves no live data, so it keeps the driver Degraded (RecordDeviceAnswered below).
if (success) state.PlcState = client.LastAdsState;
// A locally-connected client whose wire probe FAILS is wire-dead but port-open:
// force a recycle so the next tick rebuilds + replays native notifications. Without
// this the IsConnected fast-path would keep handing back the dead client forever
// (the compounding bug — native pushes would never recover).
if (!success)
await RecycleClientAsync(state, ct).ConfigureAwait(false);
else
{
// 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);
probed = client;
}
}
catch (OperationCanceledException) when (ct.IsCancellationRequested) { break; }
catch
{
// Probe threw — the connect-failure path clears the client only when the CONNECT
// failed; a throw from ProbeAsync on an already-connected client would leave it in
// place, so force a recycle to guarantee the next tick rebuilds + replays. A shutdown
// racing this recycle cancels the gate wait — exit the loop cleanly.
try { await RecycleClientAsync(state, ct).ConfigureAwait(false); }
catch (OperationCanceledException) when (ct.IsCancellationRequested) { break; }
}
if (success)
{
state.ConsecutiveProbeFailures = 0;
RecordDeviceAnswered(DateTime.UtcNow, state, force: true);
if (probed is not null) ReportNotificationDrops(state, probed);
}
else if (++state.ConsecutiveProbeFailures >= ProbeFailuresBeforeDegraded)
{
MarkCommsFault($"TwinCAT device {state.Options.HostAddress} unreachable " +
$"({state.ConsecutiveProbeFailures} consecutive failed probes)", state);
}
TransitionDeviceState(state, success ? HostState.Running : HostState.Stopped);
// 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; }
}
}
/// <summary>
/// Logs a Warning when the client's native-notification queue dropped values since the last probe
/// tick (the queue is bounded and drops on overflow — silently, before #739 L8). At most one
/// Warning per probe interval, carrying the delta and the total.
/// </summary>
private void ReportNotificationDrops(DeviceState state, ITwinCATClient client)
{
var total = client.DroppedNotificationCount;
var delta = total - state.ReportedNotificationDrops;
if (delta <= 0) return;
state.ReportedNotificationDrops = total;
_logger.LogWarning(
"TwinCAT driver '{DriverInstanceId}' device '{HostAddress}' dropped {Dropped} native notification(s) " +
"since the last probe ({Total} on this connection): the notification queue was full — the consumer " +
"is not keeping up with the PLC's change rate",
_driverInstanceId, state.Options.HostAddress, delta, total);
}
// ---- IDriverDiagnostics ----
// Well-known system symbols, exported by TC3 (and most TC2) PLC runtimes under TwinCAT_SystemInfoVarList.
// _TaskInfo[1] is the first PLC task; CycleTime / LastExecTime are UDINT counts of 100 ns.
internal const string SymOnlineChangeCnt = "TwinCAT_SystemInfoVarList._AppInfo.OnlineChangeCnt";
internal const string SymAppName = "TwinCAT_SystemInfoVarList._AppInfo.AppName";
internal const string SymCycleTime = "TwinCAT_SystemInfoVarList._TaskInfo[1].CycleTime";
internal const string SymLastExecTime = "TwinCAT_SystemInfoVarList._TaskInfo[1].LastExecTime";
// TwinCAT 2 exports the same facts under different globals (leading dot required): FW_SYSTEMINFOTYPE
// `.SYSTEMINFO` and the `.SYSTEMTASKINFOARR` array (same 100 ns units). Live gate hw2 2026-10-08: a TC2 2.11
// Elma (Z34834) answers DeviceSymbolNotFound for every TwinCAT_SystemInfoVarList symbol and serves these.
// Asked only after the TC3 name answered "not found", so a TC3 target never pays for them.
internal const string SymTc2ProjectName = ".SYSTEMINFO.PROJECTNAME";
internal const string SymTc2OnlineChangeCount = ".SYSTEMINFO.ONLINECHANGECOUNT"; // UINT on TC2
internal const string SymTc2CycleTime = ".SYSTEMTASKINFOARR[1].CYCLETIME";
internal const string SymTc2LastExecTime = ".SYSTEMTASKINFOARR[1].LASTEXECTIME";
/// <summary>Converts a TwinCAT 100 ns tick count to milliseconds.</summary>
/// <param name="ticks100ns">The tick count in 100 ns units.</param>
/// <returns>The equivalent duration in milliseconds.</returns>
internal static double TicksToMilliseconds(uint ticks100ns) => ticks100ns / 10_000.0;
/// <summary>
/// Most recent <see cref="TwinCATDeviceDiagnostics"/> for a device, or null before its first
/// successful probe sample (or for an unknown host address).
/// </summary>
/// <param name="hostAddress">The device's ADS host address.</param>
/// <returns>The snapshot, or null.</returns>
internal TwinCATDeviceDiagnostics? GetDeviceDiagnostics(string hostAddress) =>
_devices.TryGetValue(hostAddress, out var s) ? s.LastDiagnostics : null;
/// <summary>
/// Samples the ADS device state and the four system symbols once per healthy probe tick and stores the
/// result on <see cref="DeviceState.LastDiagnostics"/>. Every read is individually best-effort: a
/// runtime that does not export a symbol (older TwinCAT 2 builds) keeps the previous value, and a
/// symbol that answers "not found" is not asked again until the client is rebuilt. Never throws
/// (except cancellation) — diagnostics must not disturb the probe.
/// </summary>
/// <param name="state">The device whose diagnostics are sampled.</param>
/// <param name="client">The connected ADS client to read through.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
internal async Task SampleDeviceDiagnosticsAsync(DeviceState state, ITwinCATClient client, CancellationToken ct)
{
try
{
var prev = state.LastDiagnostics;
// 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,
SymTc2ProjectName, TwinCATDataType.String, ct).ConfigureAwait(false) as string
?? prev?.AppName;
var onlineChange = ToUInt(await ReadDiagSymbolAsync(state, client, SymOnlineChangeCnt, TwinCATDataType.UDInt,
SymTc2OnlineChangeCount, TwinCATDataType.UInt, ct).ConfigureAwait(false))
?? prev?.OnlineChangeCnt;
var cycleTicks = ToUInt(await ReadDiagSymbolAsync(state, client, SymCycleTime, TwinCATDataType.UDInt,
SymTc2CycleTime, TwinCATDataType.UDInt, ct).ConfigureAwait(false));
var execTicks = ToUInt(await ReadDiagSymbolAsync(state, client, SymLastExecTime, TwinCATDataType.UDInt,
SymTc2LastExecTime, TwinCATDataType.UDInt, ct).ConfigureAwait(false));
var cycleMs = cycleTicks is { } c ? TicksToMilliseconds(c) : prev?.CycleTimeMs;
var execMs = execTicks is { } x ? TicksToMilliseconds(x) : prev?.LastExecTimeMs;
state.LastDiagnostics = new TwinCATDeviceDiagnostics(adsState, appName, onlineChange, cycleMs, execMs, DateTime.UtcNow);
}
catch (OperationCanceledException) when (ct.IsCancellationRequested) { throw; }
catch { /* best-effort */ }
}
private static uint? ToUInt(object? v) => v switch
{
uint u => u,
null => null,
_ => Convert.ToUInt32(v, System.Globalization.CultureInfo.InvariantCulture),
};
/// <summary>Reads the TC3 system symbol, falling back to its TwinCAT 2 equivalent once the TC3 name is
/// known to be absent on this target.</summary>
private async Task<object?> ReadDiagSymbolAsync(
DeviceState state, ITwinCATClient client, string symbol, TwinCATDataType type,
string tc2Symbol, TwinCATDataType tc2Type, CancellationToken ct)
{
var value = await ReadDiagSymbolAsync(state, client, symbol, type, ct).ConfigureAwait(false);
if (value is null && state.UnavailableDiagSymbols.ContainsKey(symbol))
value = await ReadDiagSymbolAsync(state, client, tc2Symbol, tc2Type, ct).ConfigureAwait(false);
return value;
}
private async Task<object?> ReadDiagSymbolAsync(
DeviceState state, ITwinCATClient client, string symbol, TwinCATDataType type, CancellationToken ct)
{
if (state.UnavailableDiagSymbols.ContainsKey(symbol)) return null;
try
{
var (value, status) = await client.ReadValueAsync(symbol, type, null, null, ct).ConfigureAwait(false);
if (status == TwinCATStatusMapper.Good) return value;
if (status == TwinCATStatusMapper.BadNodeIdUnknown)
state.UnavailableDiagSymbols[symbol] = 0;
return null;
}
catch (OperationCanceledException) when (ct.IsCancellationRequested) { throw; }
catch { return null; }
}
// The /hosts diagnostics bag: per device, ADS state, PLC app name, online change count, task cycle
// time, last execution time and headroom (cycle - last exec). A single-device driver uses flat
// TwinCAT.* keys; several devices prefix the device name (or host address). A pure in-memory read -
// the probe loop does the sampling. The host bounds the bag (DriverDiagnostics.MaxEntries), so a
// many-device driver keeps the first keys in ordinal order. Empty before the first sample.
/// <inheritdoc />
IReadOnlyDictionary<string, string> IDriverDiagnostics.GetDiagnostics()
{
var bag = new Dictionary<string, string>(StringComparer.Ordinal);
var multi = _devices.Count > 1;
foreach (var state in _devices.Values)
{
if (state.LastDiagnostics is not { } d) continue;
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 { } 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;
}
// 0.1 ms resolution: the bag is published on a heartbeat and its digest is in the publish fingerprint,
// so sub-0.1 ms wobble should not read as a change.
private static string FormatMs(double ms) =>
Math.Round(ms, 1, MidpointRounding.AwayFromZero).ToString("0.0", System.Globalization.CultureInfo.InvariantCulture);
private void TransitionDeviceState(DeviceState state, HostState newState)
{
HostState old;
lock (state.ProbeLock)
{
old = state.HostState;
if (old == newState) return;
state.HostState = newState;
state.HostStateChangedUtc = DateTime.UtcNow;
}
_logger.LogInformation(
"TwinCAT driver '{DriverInstanceId}' device '{HostAddress}' state: {OldState} → {NewState}",
_driverInstanceId, state.Options.HostAddress, old, newState);
OnHostStatusChanged?.Invoke(this,
new HostStatusChangedEventArgs(state.Options.HostAddress, old, newState));
}
// ---- IPerCallHostResolver ----
/// <summary>
/// Documented sentinel returned by <see cref="ResolveHost"/> when neither the tag nor a
/// fallback device is configured. Empty-string never matches an
/// <see cref="HostConnectivityStatus.HostName"/> emitted by this driver (every real
/// host is an <c>ads://…</c> URI), so it cleanly signals "unresolved" without colliding
/// with a real host key. Used to be <see cref="DriverInstanceId"/>, which is a logical
/// config-DB identifier — that collided with consumers who expected the resolver and the
/// connectivity-status table to share keys.
/// </summary>
public const string UnresolvedHostSentinel = "";
/// <summary>
/// Resolve a <see cref="RawTagEntry.DeviceName"/> to the device's live host address
/// (<see cref="TwinCATTagDefinition.DeviceHostAddress"/>) used to route reads/writes/subscriptions
/// to the right connection. The deploy-time
/// <c>DriverDeviceConfigMerger</c> already fills <see cref="TwinCATDriverOptions.Devices"/> from each
/// <c>Device</c> row's <c>DeviceConfig</c>, so we resolve the DeviceName against that list —
/// first by <see cref="TwinCATDeviceOptions.DeviceName"/>, then by
/// <see cref="TwinCATDeviceOptions.HostAddress"/> (callers that route by host, e.g. the Client
/// CLI, pass the host string as the DeviceName). An empty DeviceName routes to the sole device
/// on a single-device instance; an unmatched name leaves the def unrouted (→ BadNodeIdUnknown).
/// </summary>
/// <param name="options">The options generation being initialised.</param>
/// <param name="deviceName">The owning device's name (or host) from the raw-tag entry.</param>
/// <returns>The resolved device host address, or empty when unresolved.</returns>
private static string ResolveDeviceHost(TwinCATDriverOptions options, string deviceName)
{
var devices = options.Devices;
if (string.IsNullOrEmpty(deviceName))
return devices.Count == 1 ? devices[0].HostAddress : "";
foreach (var d in devices)
if (string.Equals(d.DeviceName, deviceName, StringComparison.OrdinalIgnoreCase))
return d.HostAddress;
foreach (var d in devices)
if (string.Equals(d.HostAddress, deviceName, StringComparison.OrdinalIgnoreCase))
return d.HostAddress;
return "";
}
// Resolves a reference to the device host that keys its per-host resilience (bulkhead / circuit
// breaker). Routes through EquipmentTagRefResolver so an equipment-tag reference (raw TagConfig
// JSON) resolves to its OWN authored device rather than the first-device fallback. The empty-host
// guard keeps an address-less equipment tag on the fallback rather than keying the
// UnresolvedHostSentinel. The resolver caches parses, so this adds no per-call cost after first use.
/// <inheritdoc />
public string ResolveHost(string fullReference)
{
if (_resolver.TryResolve(fullReference, out var def) && !string.IsNullOrEmpty(def.DeviceHostAddress))
return def.DeviceHostAddress;
// First device's HostAddress when one exists; otherwise the unresolved sentinel —
// intentionally NOT DriverInstanceId, which is a config-DB key, not a host address.
return _options.Devices.FirstOrDefault()?.HostAddress ?? UnresolvedHostSentinel;
}
/// <summary>
/// Lazily connect a device's client, serialized per device by
/// <see cref="DeviceState.ConnectGate"/>. Without the gate, a
/// concurrent read / write / probe could each create + connect a separate client and
/// leak all-but-one, or dispose a client another thread is mid-connect on. The S7 and
/// AB-CIP drivers serialize device access the same way; single-connection-per-PLC is
/// also what docs/v2/driver-specs.md recommends.
/// </summary>
private async Task<ITwinCATClient> EnsureConnectedAsync(
DeviceState device, CancellationToken ct, TimeSpan? timeoutOverride = null, bool bypassBackoff = false)
{
// Fast path — already connected, no gate needed.
if (device.Client is { IsConnected: true } fast) return fast;
await device.ConnectGate.WaitAsync(ct).ConfigureAwait(false);
try
{
return await EnsureConnectedUnderGateAsync(device, ct, timeoutOverride, bypassBackoff).ConfigureAwait(false);
}
finally
{
device.ConnectGate.Release();
}
}
/// <summary>
/// Thrown by the connect path when a per-device <see cref="ConnectionBackoff"/> window is
/// still open — a fail-fast that costs no wire traffic. Read/write map it to
/// <c>BadCommunicationError</c> via their generic catch, exactly as a real connect failure.
/// </summary>
private sealed class ConnectionThrottledException(string message) : Exception(message);
/// <summary>
/// The connect-or-reconnect core, assuming the caller already holds
/// <see cref="DeviceState.ConnectGate"/>. When it installs a NEW client (a genuine
/// reconnect, not a fast-path reuse) it replays every stored native-notification intent
/// onto it — otherwise native ADS pushes would silently stop after a drop. Both
/// the initial subscribe (<see cref="RegisterNotificationAsync"/>) and the probe loop call
/// through here under the same gate, so a replay can never race a register.
/// </summary>
private async Task<ITwinCATClient> EnsureConnectedUnderGateAsync(
DeviceState device, CancellationToken ct, TimeSpan? timeoutOverride, bool bypassBackoff = false)
{
// Re-check under the gate: another caller may have connected while we waited.
if (device.Client is { IsConnected: true } c) return c;
// A released device (swapped out by a re-initialise / teardown) never connects again.
if (device.Released) throw new DeviceReleasedException(device.Options.HostAddress);
// Inside an open backoff window a data-path caller fails fast — no client
// create, no wire connect. The probe loop bypasses this (its interval is the recovery
// cadence) and drives the failure/success recording.
if (!bypassBackoff && !device.Backoff.ShouldAttempt(DateTime.UtcNow))
throw new ConnectionThrottledException(
$"TwinCAT connect to {device.Options.HostAddress} throttled — backoff window open after a recent connect failure.");
// Discard a stale (created-but-disconnected) client before making a fresh one.
if (device.Client is { IsConnected: false } stale)
{
stale.OnSymbolVersionChanged -= HandleSymbolVersionChanged;
try { stale.Dispose(); } catch { /* best-effort */ }
device.Client = null;
}
var client = _clientFactory.Create();
client.OnSymbolVersionChanged += HandleSymbolVersionChanged;
// timeoutOverride lets the probe loop use TwinCATProbeOptions.Timeout for probe-
// initiated connects rather than the driver-level _options.Timeout. Reads / writes
// pass null and get the driver default.
var effectiveTimeout = timeoutOverride ?? _options.Timeout;
try
{
await client.ConnectAsync(device.ParsedAddress, effectiveTimeout, ct)
.ConfigureAwait(false);
_logger.LogInformation(
"TwinCAT driver '{DriverInstanceId}' connected to {HostAddress}",
_driverInstanceId, device.Options.HostAddress);
}
catch (Exception ex)
{
_logger.LogWarning(ex,
"TwinCAT driver '{DriverInstanceId}' failed to connect to {HostAddress}",
_driverInstanceId, device.Options.HostAddress);
client.OnSymbolVersionChanged -= HandleSymbolVersionChanged;
client.Dispose();
device.Backoff.RecordFailure(DateTime.UtcNow); // open the backoff window
throw;
}
if (device.Released)
{
// This device was torn down while the (blocking) connect ran: never install a client on a
// released generation, where nothing would ever dispose it.
client.OnSymbolVersionChanged -= HandleSymbolVersionChanged;
try { client.Dispose(); } catch { /* best-effort */ }
throw new DeviceReleasedException(device.Options.HostAddress);
}
device.Client = client;
device.ReportedNotificationDrops = 0;
device.UnavailableDiagSymbols.Clear(); // a rebuilt client may face a PLC that now exports them
device.Backoff.RecordSuccess(); // recovery resets the window immediately
// Re-register every native notification onto the fresh client. Native ADS is push, so
// (unlike the poll fallback) it cannot self-heal by re-reading — without this the
// subscription is silently dead after a reconnect.
await ReplayNativeRegistrationsAsync(device, client, ct).ConfigureAwait(false);
return client;
}
/// <summary>
/// Re-registers every stored <see cref="NativeRegistration"/> for a device onto the given
/// freshly-connected client and swaps in the new live handle (disposing the dead one from
/// the previous client). Runs under <see cref="DeviceState.ConnectGate"/>. A single
/// registration that fails to replay is logged and skipped — one bad symbol must not abort
/// recovery of the rest.
/// </summary>
private async Task ReplayNativeRegistrationsAsync(DeviceState device, ITwinCATClient client, CancellationToken ct)
{
var intents = device.NativeRegistrations.Values.ToArray();
if (intents.Length == 0) return;
var replayed = 0;
foreach (var reg in intents)
{
try
{
var newHandle = await client.AddNotificationAsync(
reg.SymbolName, reg.DataType, reg.BitIndex, reg.ArrayLength, reg.Interval,
_options.NotificationMaxDelayMs, reg.OnChange, ct).ConfigureAwait(false);
var old = reg.SwapHandle(newHandle);
try { old?.Dispose(); } catch { /* dead handle from the disposed client */ }
// An UnsubscribeAsync (gate-free) can race this replay — if it removed the
// registration between the intents snapshot and this swap, the fresh handle is
// ownerless. Retract it immediately so the ADS notification isn't leaked live.
if (!device.NativeRegistrations.ContainsKey(reg.Id))
{
var orphan = reg.MarkHandleDead();
try { orphan?.Dispose(); } catch { /* best-effort */ }
continue;
}
NoteLive(reg);
replayed++;
}
catch (TwinCATNotificationRefusedException refused)
{
// The PLC answered and refused this tag again (it was already isolated at subscribe, or a
// program change made it undecodable): republish the refusal's status, keep it dead for the
// probe-tick retry, and leave health alone — a refusal is not a comms fault.
_logger.LogDebug(
"TwinCAT driver '{DriverInstanceId}' native notification '{Symbol}' on device '{HostAddress}' " +
"still refused after reconnect: {Reason}",
_driverInstanceId, reg.SymbolName, device.Options.HostAddress, refused.Message);
var dead = reg.MarkHandleDead();
try { dead?.Dispose(); } catch { /* already-dead handle from the disposed client */ }
if (NoteDeadFailure(reg, refused.StatusCode, refused: true, DateTime.UtcNow))
try { reg.OnRefused(refused.StatusCode); } catch { /* never abort recovery of the rest */ }
}
catch (Exception ex)
{
_logger.LogWarning(ex,
"TwinCAT driver '{DriverInstanceId}' failed to replay native notification " +
"'{Symbol}' on device '{HostAddress}' after reconnect",
_driverInstanceId, reg.SymbolName, device.Options.HostAddress);
// The intent has no live handle now — mark it dead so the probe-tick
// retry re-registers it, surface Bad quality to subscribers (the OnChange shape has
// no quality channel), and degrade health preserving the last successful read.
var dead = reg.MarkHandleDead();
try { dead?.Dispose(); } catch { /* already-dead handle from the disposed client */ }
if (NoteDeadFailure(reg, TwinCATStatusMapper.BadCommunicationError, refused: false, DateTime.UtcNow))
try { reg.OnUnavailable(); } catch { /* never let a subscriber callback abort recovery of the rest */ }
MarkCommsFault($"native-notification replay failed for '{reg.SymbolName}' on {device.Options.HostAddress}", device);
}
}
_logger.LogInformation(
"TwinCAT driver '{DriverInstanceId}' re-registered {Replayed}/{Total} native notifications " +
"on device '{HostAddress}' after reconnect",
_driverInstanceId, replayed, intents.Length, device.Options.HostAddress);
}
/// <summary>
/// Re-registers every dead (failed-replay) <see cref="NativeRegistration"/> onto
/// the device's currently-connected client. Runs under <see cref="DeviceState.ConnectGate"/>
/// (shared with the replay so it can't race a register/unsubscribe). Called from the probe
/// loop after a successful probe — a bounded retry cadence (the probe interval) with no extra
/// timers. A registration that fails again just stays dead for the next tick. Recovery of the
/// value itself arrives via ADS's initial-notification push on register, exactly as the
/// initial subscribe relies on.
/// </summary>
private async Task RetryDeadRegistrationsAsync(DeviceState device, CancellationToken ct)
{
if (device.NativeRegistrations.IsEmpty) return;
await device.ConnectGate.WaitAsync(ct).ConfigureAwait(false);
try
{
if (device.Client is not { IsConnected: true } client) return;
var recovered = 0;
var now = DateTime.UtcNow;
foreach (var reg in device.NativeRegistrations.Values)
{
if (reg.HasLiveHandle) continue;
// A refused registration waits out its backoff (a symbol-version change re-arms it).
if (now < reg.NextRetryUtc) continue;
var epoch = reg.RearmEpoch;
try
{
var newHandle = await client.AddNotificationAsync(
reg.SymbolName, reg.DataType, reg.BitIndex, reg.ArrayLength, reg.Interval,
_options.NotificationMaxDelayMs, reg.OnChange, ct).ConfigureAwait(false);
reg.SwapHandle(newHandle);
// Ownership re-check — see ReplayNativeRegistrationsAsync.
if (!device.NativeRegistrations.ContainsKey(reg.Id))
{
var orphan = reg.MarkHandleDead();
try { orphan?.Dispose(); } catch { /* best-effort */ }
continue;
}
NoteLive(reg);
recovered++;
}
catch (OperationCanceledException) when (ct.IsCancellationRequested) { throw; }
catch (Exception ex)
{
// Republish only when the failure CLASS changes (a comms blip that turned into a refusal,
// or the reverse); the same failure again publishes nothing.
var refusal = ex as TwinCATNotificationRefusedException;
var status = refusal?.StatusCode ?? TwinCATStatusMapper.BadCommunicationError;
if (NoteDeadFailure(reg, status, refusal is not null, now, epoch))
try { reg.OnRefused(status); } catch { /* never abort the rest */ }
_logger.LogDebug(ex,
"TwinCAT driver '{DriverInstanceId}' probe-tick retry of dead notification " +
"'{Symbol}' on device '{HostAddress}' failed; will retry next tick",
_driverInstanceId, reg.SymbolName, device.Options.HostAddress);
}
}
if (recovered > 0)
_logger.LogInformation(
"TwinCAT driver '{DriverInstanceId}' recovered {Recovered} dead native notification(s) " +
"on device '{HostAddress}' via probe-tick retry",
_driverInstanceId, recovered, device.Options.HostAddress);
}
finally
{
device.ConnectGate.Release();
}
}
/// <summary>
/// Disposes + nulls a device's client under <see cref="DeviceState.ConnectGate"/> so the
/// next <see cref="EnsureConnectedAsync"/> rebuilds it (and replays notifications). Called
/// by the probe loop when a wire-level probe fails on a locally-"connected" client — the
/// <see cref="ITwinCATClient.IsConnected"/> fast-path keys on the AMS-port state, not wire
/// liveness, so without this forced recycle a wire-dead-but-port-open client would keep
/// being reused and native pushes would never recover.
/// </summary>
private async Task RecycleClientAsync(DeviceState device, CancellationToken ct)
{
// Honor the probe token so a connect wedged under the gate
// (TwinCAT's blocking SDK Connect — the un-fixed root, carried) can't hang the probe loop
// beyond cancellation. Was CancellationToken.None.
await device.ConnectGate.WaitAsync(ct).ConfigureAwait(false);
try
{
if (device.Client is { } c)
{
c.OnSymbolVersionChanged -= HandleSymbolVersionChanged;
try { c.Dispose(); } catch { /* best-effort */ }
device.Client = null;
}
}
finally
{
device.ConnectGate.Release();
}
}
/// <summary>
/// Routes a wire-detected ADS symbol-version-changed (DeviceSymbolVersionInvalid 1809 /
/// 0x0711) to Core as an <see cref="IRediscoverable"/> invocation.
/// A PLC re-download invalidates every symbol + notification handle, so the address
/// space must be rebuilt — this is the documented TwinCAT failure mode, not a transient
/// connection error.
/// </summary>
private void HandleSymbolVersionChanged(object? sender, EventArgs e)
{
// A program change can make a refused registration valid: re-arm every backed-off dead intent of the
// device whose client saw it, so the next probe tick re-checks them at once.
foreach (var d in _devices.Values)
if (ReferenceEquals(d.Client, sender))
foreach (var reg in d.NativeRegistrations.Values)
reg.Rearm();
OnRediscoveryNeeded?.Invoke(this, new RediscoveryEventArgs(
"TwinCAT symbol-version-changed (DeviceSymbolVersionInvalid 0x0711) — PLC program re-downloaded",
ScopeHint: "TwinCAT"));
}
/// <summary>
/// Synchronous teardown — no <c>await</c>, no captured sync context. The OPC UA stack
/// thread can call <see cref="Dispose"/>; routing through <c>DisposeAsync().GetResult()</c>
/// can deadlock on a single-threaded sync context (see docs/v2/driver-stability.md).
/// The operations here are all genuinely synchronous —
/// cancel tokens, wait on task handles with a hard timeout, dispose clients — so a
/// synchronous path does the right thing without re-entering the scheduler.
/// </summary>
/// <summary>Synchronously disposes driver resources without awaiting async operations.</summary>
public void Dispose()
{
// Dispose native subscriptions first — handle disposal is sync.
foreach (var sub in _nativeSubs.Values)
foreach (var r in sub.Registrations) { try { r.Dispose(); } catch { } }
_nativeSubs.Clear();
var (taken, retiredPoll) = TakeAllForTeardown();
var probes = BeginRelease(taken);
// PollGroupEngine.DisposeAsync awaits loop tasks; drive it synchronously with a bounded Wait() on
// the returned task (no sync-context capture), in parallel with the probe join.
var poll = retiredPoll.DisposeAsync().AsTask();
try { Task.WhenAll([poll, .. probes]).Wait(ProbeJoinTimeout); } catch { /* cancel races are expected */ }
EndRelease(taken);
_warnedRefs.Clear();
_resolver.Clear(); // no-op in v3 (the resolver reads the live table by closure); kept for symmetry
_health = new DriverHealth(DriverState.Unknown, _health.LastSuccessfulRead, null);
}
/// <summary>Asynchronously disposes driver resources.</summary>
/// <returns>Completion task.</returns>
public async ValueTask DisposeAsync() => await ShutdownAsync(CancellationToken.None).ConfigureAwait(false);
internal sealed class DeviceState(TwinCATAmsAddress parsedAddress, TwinCATDeviceOptions options)
{
/// <summary>Gets the parsed AMS address for the device.</summary>
public TwinCATAmsAddress ParsedAddress { get; } = parsedAddress;
/// <summary>Gets the device configuration options.</summary>
public TwinCATDeviceOptions Options { get; } = options;
/// <summary>Gets or sets the active ADS client for this device.</summary>
public ITwinCATClient? Client { get; set; }
/// <summary>Serializes connect / reconnect so concurrent callers never race a client
/// create-or-dispose for this device.</summary>
public SemaphoreSlim ConnectGate { get; } = new(1, 1);
/// <summary>
/// Per-device connect-attempt throttle. A dead device fails fast inside the
/// backoff window instead of paying a full connect on every data call; the probe loop
/// bypasses it and a successful connect resets it. Consulted + mutated only under
/// <see cref="ConnectGate"/>, satisfying <see cref="ConnectionBackoff"/>'s
/// caller-synchronized contract.
/// </summary>
public ConnectionBackoff Backoff { get; } = new(TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(30));
/// <summary>
/// Live native-notification registrations against this device, keyed by registration id.
/// Holds the <b>replayable intent</b> (symbol / type / bit / interval / callback), not just
/// an opaque handle, so that when <see cref="TwinCATDriver.EnsureConnectedAsync"/> swaps in
/// a fresh client after a drop it can re-register every notification onto it.
/// Populated by <c>SubscribeAsync</c>, drained by <c>UnsubscribeAsync</c> / teardown.
/// </summary>
public ConcurrentDictionary<long, NativeRegistration> NativeRegistrations { get; } = new();
/// <summary>Gets the lock object for synchronizing host state transitions.</summary>
public object ProbeLock { get; } = new();
/// <summary>Gets or sets the current host connectivity state.</summary>
public HostState HostState { get; set; } = HostState.Unknown;
/// <summary>Gets or sets the UTC timestamp of the last host state change.</summary>
public DateTime HostStateChangedUtc { get; set; } = DateTime.UtcNow;
/// <summary>Gets or sets the cancellation token source for the probe loop.</summary>
public CancellationTokenSource? ProbeCts { get; set; }
/// <summary>The running probe-loop task — awaited by <see cref="TwinCATDriver.ShutdownAsync"/>
/// so the loop cannot touch a disposed client.</summary>
public Task? ProbeTask { get; set; }
/// <summary>Set when the target answered the ADS sum-read command with "service / index group not
/// supported"; 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>True once the "sum request rejected, chunk read singly" warning was logged for this device.</summary>
public volatile bool SumFallbackWarned;
/// <summary>True once an unexpected sum-read chunk failure was logged for this device.</summary>
public volatile bool SumChunkFailureWarned;
/// <summary>The last comms fault seen on this device; cleared when this device answers. Null = none.</summary>
public volatile string? CommsFault;
/// <summary>The ADS state (<c>Run</c>, <c>Stop</c>, <c>Config</c>, …) the last successful probe read; null = unknown.</summary>
public volatile string? PlcState;
/// <summary>Consecutive failed probe ticks; reset by a successful probe. Written only by this device's probe loop.</summary>
public volatile int ConsecutiveProbeFailures;
/// <summary>Latest probe-sampled PLC diagnostics; null before the first sample.</summary>
public TwinCATDeviceDiagnostics? LastDiagnostics { get; set; }
/// <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();
Client = null;
// A rebuilt client may face a PLC that now exports the symbols (e.g. after a program download).
UnavailableDiagSymbols.Clear();
}
/// <summary>
/// Set once this device state has been swapped out of the driver's table. A connect that
/// completes afterwards (a probe wedged in the blocking ADS <c>Connect</c> past the bounded join)
/// disposes its client instead of installing it on a dead generation.
/// </summary>
public volatile bool Released;
/// <summary>Total notification drops last reported for this device's current client.</summary>
public long ReportedNotificationDrops;
}
}