using System.Collections.Concurrent; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Logging.Abstractions; using S7.Net; using S7NetDataType = global::S7.Net.DataType; using S7DataItem = global::S7.Net.Types.DataItem; using ZB.MOM.WW.OtOpcUa.Commons.Observability; using ZB.MOM.WW.OtOpcUa.Core.Abstractions; namespace ZB.MOM.WW.OtOpcUa.Driver.S7; /// /// Siemens S7 native driver — speaks S7comm over ISO-on-TCP (port 102) via the S7netplus /// library. First implementation of for an in-process .NET Standard /// PLC protocol that is NOT Modbus, validating that the v2 driver-capability interfaces /// generalize beyond Modbus + Galaxy. /// /// /// /// PR 62 ships the scaffold: only (Initialize / Reinitialize / /// Shutdown / GetHealth). , , /// , , /// land in PRs 63-65 once the address parser (PR 63) is in place. /// /// /// Single-connection policy: S7netplus documented pattern is one /// Plc instance per PLC, serialized with a . /// Parallelising reads against a single S7 CPU doesn't help — the CPU scans the /// communication mailbox at most once per cycle (2-10 ms) and queues concurrent /// requests wire-side anyway. Multiple client-side connections just waste the CPU's /// 8-64 connection-resource budget. /// /// public sealed class S7Driver : IDriver, ITagDiscovery, IReadable, IWritable, IBatchSubscribable, IHostConnectivityProbe, ISkippedTagReporter, IDriverDiagnostics, IDisposable, IAsyncDisposable { /// Authored tags this driver could not build into its poll table. private readonly SkippedTagLedger _skippedTags = new(); /// public SkippedTagReport? GetSkippedTags() => _skippedTags.Snapshot(); private readonly string _driverInstanceId; private readonly ILogger _logger; private readonly IS7PlcFactory _plcFactory; /// Initializes a new instance of the class. /// Driver configuration (the constructor-supplied fallback used when /// Initialize/Reinitialize receive an empty config body). /// Unique driver instance identifier. /// Optional S7 connection factory; defaults to /// (real S7.Net). Tests inject a fake to exercise the reconnect path without a live PLC. /// Optional logger; a null logger is used when not supplied. public S7Driver(S7DriverOptions options, string driverInstanceId, IS7PlcFactory? plcFactory = null, ILogger? logger = null) { _options = options; _driverInstanceId = driverInstanceId; _plcFactory = plcFactory ?? new S7PlcFactory(); _logger = logger ?? NullLogger.Instance; _resolver = new EquipmentTagRefResolver( r => TagsByRawPath.TryGetValue(r, out var t) ? t : null); // The polling overlay runs on the shared PollGroupEngine (structural array diff + // drain-before-dispose + capped-exponential failure backoff + caller-token-filtered OCE), // retiring the bespoke S7 poll fork. minInterval 100 ms matches the S7 scan-mailbox floor; // backoffCap 30 s matches the retired fork's PollBackoffCap. _poll = new PollGroupEngine( reader: ReadAsync, onChange: (handle, tagRef, snapshot) => OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, tagRef, snapshot)), minInterval: TimeSpan.FromMilliseconds(100), onError: HandlePollError, backoffCap: TimeSpan.FromSeconds(30), onBatch: (handle, items) => OnDataChangeBatch?.Invoke(this, new DataChangeBatchEventArgs(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(OtOpcUaTelemetry.PollOverrunDriverTypeTag, DriverTypeNames.S7), new KeyValuePair(OtOpcUaTelemetry.PollOverrunDriverInstanceTag, driverInstanceId))); } // ---- ISubscribable + IHostConnectivityProbe state ---- private readonly PollGroupEngine _poll; private readonly object _probeLock = new(); private HostState _hostState = HostState.Unknown; private DateTime _hostStateChangedUtc = DateTime.UtcNow; private CancellationTokenSource? _probeCts; /// /// Handle to the in-flight probe loop. Tracked (rather than fire-and-forget) so /// can await it after cancelling — otherwise a probe /// iteration still inside the would race a disposed semaphore. /// private Task? _probeTask; /// /// Bounded grace window waits for the probe + poll loops to /// observe cancellation and exit before it disposes the shared semaphore / CTS objects. /// private static readonly TimeSpan DrainTimeout = TimeSpan.FromSeconds(5); /// Occurs when a subscribed tag value or status code changes. public event EventHandler? OnDataChange; /// /// Occurs once per poll cycle that produced at least one change, carrying that cycle's /// changed tags. Both data-change events fire by design — this one once per cycle, /// once per changed tag — so a consumer subscribes to EXACTLY /// ONE of the two; subscribing both double-delivers. /// public event EventHandler? OnDataChangeBatch; /// Occurs when host connectivity status changes. public event EventHandler? OnHostStatusChanged; /// OPC UA StatusCode used when the tag name isn't in the driver's tag map. private const uint StatusBadNodeIdUnknown = 0x80340000u; /// OPC UA StatusCode used when the tag's data type isn't implemented yet. private const uint StatusBadNotSupported = 0x803D0000u; /// OPC UA StatusCode used when a written value has the wrong shape / length / element type. private const uint StatusBadTypeMismatch = 0x80740000u; /// OPC UA StatusCode used when a value is unrepresentable in the S7 type (write) or a PLC buffer does not decode (read). private const uint StatusBadOutOfRange = 0x803C0000u; /// OPC UA StatusCode used when the tag is declared read-only. private const uint StatusBadNotWritable = 0x803B0000u; /// OPC UA StatusCode used when write fails validation (e.g. out-of-range value). private const uint StatusBadInternalError = 0x80020000u; /// OPC UA StatusCode used for socket / timeout / protocol-layer faults. private const uint StatusBadCommunicationError = 0x80050000u; /// OPC UA StatusCode used for a genuine device fault (CPU error, hardware fault). private const uint StatusBadDeviceFailure = 0x808B0000u; // Resolves a read/write/subscribe fullReference (a RawPath in v3) to a tag definition by a single // authored-table hit; a miss is a miss (the driver surfaces BadNodeIdUnknown, never a parse attempt). private readonly EquipmentTagRefResolver _resolver; /// /// Active driver configuration. Seeded from the constructor argument, then replaced by /// whatever / parse out of /// the supplied driverConfigJson. The /// constructor value is the fallback used when the caller passes an empty / placeholder /// JSON document (e.g. the "{}" some unit tests pass). /// private S7DriverOptions _options; private readonly SemaphoreSlim _gate = new(1, 1); /// /// Per-connection gate. Internal so PRs 63-65 (read/write/subscribe) can serialize on /// the same semaphore without exposing it publicly. Single-connection-per-PLC is a /// hard requirement of S7netplus — see class remarks. /// internal SemaphoreSlim Gate => _gate; /// /// Active S7 PLC connection. Null until returns; null /// after . Also (re)opened lazily by /// after a transient drop. Read-only outside this class; /// Read/Write/probe take the before touching it. /// internal IS7Plc? Plc { get; private set; } /// /// True once has parsed the tag table + opened the first /// connection, false after . Distinct from Plc != null /// because the reconnect path can leave transiently null / dead while the /// driver is still initialized — a data call then repairs the connection rather than /// throwing "not initialized". Guarded by . /// private bool _initialized; /// /// Set when a connection-fatal fault (socket drop / ) /// is observed on a read/write, so the next disposes the /// dead handle and re-opens. Kept as a flag (rather than nulling inline) so /// the dead handle is disposed exactly once, in . Guarded /// by . /// private bool _plcDead; private DriverHealth _health = new(DriverState.Unknown, null, null); /// /// The health snapshot, accessed with volatile semantics: it is written from the gate-holding /// read/write passes, the poll engine's error sink and the lifecycle methods, and read lock-free /// by (the health tick) — the same Volatile idiom ModbusDriver uses. /// is an immutable record, so a reference swap is a complete update. /// private DriverHealth Health { get => Volatile.Read(ref _health); set => Volatile.Write(ref _health, value); } /// /// Per-device connect-attempt throttle: a dead PLC costs one connect attempt per /// backoff window (1 s doubling to 30 s) instead of one per data call / poll tick / probe tick. /// Not internally synchronized — only touched from (under /// ) and from init/shutdown, which run with every loop drained. /// private readonly ConnectionBackoff _connectBackoff = new(TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(30)); /// Clock the connect backoff is measured on. Internal so tests step it deterministically. internal Func BackoffClock { get; set; } = static () => DateTime.UtcNow; /// /// Clock the read/write passes and the init publish stamp timestamps and /// LastSuccessfulRead with. Internal so a test can step it and assert a STRICT advance. /// internal Func UtcNow { get; set; } = static () => DateTime.UtcNow; /// /// The sticky write-side config fault (access denied / PUT-GET disabled), or null. A read /// pass that finds everything readable must NOT erase it (reads can succeed while writes are /// protected); it is cleared by the next write pass that writes something successfully. /// Guarded by . /// private (DriverState State, string Message)? _writeFault; /// /// The message of the last Degraded the WRITE side published, or null. A clean write batch /// retires a Degraded carrying exactly this message (a good write proves the comms fault it /// reported is gone) and leaves any other Degraded to the read pass. Guarded by . /// private string? _writeOwnedError; /// /// Tags whose refusal has already been logged this generation — the once-per-tag Warning. Cleared /// by every initialize publish. /// private readonly ConcurrentDictionary _refusalWarned = new(StringComparer.Ordinal); /// /// Tags the span planner must not group (R07:P2): members of a span the CPU refused as a block — /// the ones that were refused on their own, or every member when none was. They are read /// individually for the rest of the generation; a re-initialize (a corrected DB, a fixed tag) /// groups everything again. Guarded by . /// private readonly HashSet _noGroup = new(StringComparer.Ordinal); private bool _disposed; /// public string DriverInstanceId => _driverInstanceId; /// public string DriverType => "S7"; /// public async Task InitializeAsync(string driverConfigJson, CancellationToken cancellationToken) { // Serialised against every other lifecycle operation: DriverInstanceActor dispatches initialize // on a fire-and-forget Task.Run and a reconnect retry can start a second attempt while the // first is still inside OpenAsync. Without the gate attempt A's freshly opened Plc and probe // loop were overwritten by attempt B and never released (R07:H5) — the Modbus pattern. await _lifecycleGate.WaitAsync(cancellationToken).ConfigureAwait(false); try { await InitializeCoreAsync(driverConfigJson, cancellationToken).ConfigureAwait(false); } finally { _lifecycleGate.Release(); } } /// The lifecycle-gated body of . /// The driver config. /// Caller cancellation. /// A task that completes when the attempt has published, been superseded, or failed. private async Task InitializeCoreAsync(string driverConfigJson, CancellationToken cancellationToken) { // This attempt's generation. Every health write and table/connection publish below is stamped // with it and dropped once the generation has moved on: an attempt abandoned by its caller can // still be running when a ShutdownAsync (which only waits a bounded time for the lifecycle // gate) starts, and it must never publish over it. var gen = BeginGeneration(); // InitializeAsync is reachable on a live driver with no teardown first (the IDriver contract // allows it). Stop the previous probe loop and drop the previous connection before they are // replaced below. Deliberately NOT a full teardown: that also drops _poll and the subscriptions, // which are owned by the shutdown path (the actor re-subscribes after every successful init). await ReleaseConnectionAsync(gen).ConfigureAwait(false); TryWriteHealth(gen, new DriverHealth(DriverState.Initializing, null, null)); // Re-parse the supplied DriverConfig JSON so a config change delivered through the IDriver // contract is honoured. An empty / placeholder document (e.g. the "{}" some unit tests pass) // keeps the constructor-supplied options. Local until published: a superseded attempt must // not leave its options behind for the live connection to reopen against. var options = _options; IS7Plc? plc = null; try { if (HasConfigBody(driverConfigJson)) options = S7DriverFactoryExtensions.ParseOptions(_driverInstanceId, driverConfigJson); // v3: build the RawPath → definition table from the authored raw tags. Each entry's TagConfig // blob is mapped by the pure factory, which also applies S7TagShapeRules (the address must // parse; wide arrays, mis-typed Timer/Counter, wrong access widths, writable Timer/Counter or // Bool arrays and offset Bool arrays are refused). A refused tag is SKIPPED (logged, reported // through ISkippedTagReporter, reads BadNodeIdUnknown), never thrown: these used to be init // guards that faulted every tag on the PLC and made the actor retry the same init forever. // The entry's WriteIdempotent flag is threaded onto the def (it lives on the RawTagEntry). // Built into fresh dictionaries and published by ONE reference swap — a retained poll pass // reading the old table never sees it half-cleared. var tags = new Dictionary(StringComparer.Ordinal); var parsed = new Dictionary(StringComparer.Ordinal); var skipped = new List<(string RawPath, string Reason)>(); foreach (var entry in options.RawTags) { if (S7TagDefinitionFactory.FromTagConfig(entry.TagConfig, entry.RawPath, out var def, out var shapeRejection) && S7AddressParser.TryParse(def.Address, out var parsedAddress)) { tags[entry.RawPath] = def with { WriteIdempotent = entry.WriteIdempotent }; parsed[entry.RawPath] = parsedAddress; } else { skipped.Add((entry.RawPath, shapeRejection ?? "TagConfig did not map to a definition")); } } // Build the connection through the factory (the same seam EnsureConnectedAsync's reopen // uses) so the read/write timeouts are baked in identically on connect and reconnect. plc = _plcFactory.Create(options); try { using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); cts.CancelAfter(options.Timeout); await plc.OpenAsync(cts.Token).ConfigureAwait(false); } catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) { // The linked CancelAfter fired — a connect TIMEOUT, not a caller cancellation. // Surface it as a TimeoutException so init-time and reconnect-time timeouts report // the same exception type (for consistency); the outer catch still faults health. throw new TimeoutException( $"S7 connect to {options.Host}:{options.Port} timed out after " + $"{(int)options.Timeout.TotalMilliseconds} ms."); } // Publish everything this attempt built under _gate (no pass can be mid-flight against a // half-published state) and only while this attempt is still the current generation. await _gate.WaitAsync(cancellationToken).ConfigureAwait(false); try { if (!IsCurrentGeneration(gen)) { // The outer finally disposes the unpublished plc; the catch writes no health (the // generation moved on). Thrown, not returned: a caller must never read "initialized" // into an attempt that published nothing. throw new InvalidOperationException( "S7 initialize was superseded by a newer lifecycle operation before it published; " + "its connection was discarded."); } _options = options; Volatile.Write(ref _tables, new TagTables(tags, parsed)); _refusalWarned.Clear(); _noGroup.Clear(); _skippedTags.BeginRebuild(options.RawTags.Count); foreach (var (rawPath, reason) in skipped) { _skippedTags.Skip(rawPath, reason); _logger.LogWarning( "S7 tag skipped: {Reason} Driver={DriverInstanceId} RawPath={RawPath}", reason, _driverInstanceId, rawPath); } _skippedTags.Commit(); Plc = plc; plc = null; // published — no longer this method's to dispose _plcDead = false; _connectBackoff.RecordSuccess(); Volatile.Write(ref _negotiatedPduSize, Plc.MaxPduSize); _initialized = true; TryWriteHealth(gen, new DriverHealth(DriverState.Healthy, UtcNow(), null)); // Kick off the probe loop once the connection is up. Initial HostState stays Unknown // until the first probe tick succeeds — avoids broadcasting a premature Running // transition before any PDU round-trip has happened. Tracked (not fire-and-forget) so // a teardown can await it before disposing its CTS; Task.Run gets None so the handle // is always awaitable — the loop's own token check handles cancellation. if (options.Probe.Enabled) { var probeCts = new CancellationTokenSource(); _probeCts = probeCts; _probeTask = Task.Run(() => ProbeLoopAsync(probeCts.Token), CancellationToken.None); } } finally { _gate.Release(); } _logger.LogInformation("S7Driver connected. Driver={DriverInstanceId} Host={Host} CPU={CpuType} PduSize={PduSize} Tags={TagCount}", _driverInstanceId, options.Host, options.CpuType, _negotiatedPduSize, tags.Count); } catch (Exception ex) { // A superseded attempt reports nothing: the generation that replaced it owns health. if (TryWriteHealth(gen, new DriverHealth(DriverState.Faulted, null, ex.Message))) { _options = options; _logger.LogError(ex, "S7Driver connect failed. Driver={DriverInstanceId} Host={Host}", _driverInstanceId, options.Host); } throw; } finally { // A connection this attempt opened but did not publish (failed or superseded) is released // here, so a retry from the caller never leaks the TcpClient. if (plc is not null) { try { plc.Dispose(); } catch { /* best-effort */ } } } } /// public async Task ReinitializeAsync(string driverConfigJson, CancellationToken cancellationToken) { // Holds the lifecycle gate across BOTH halves so no other lifecycle operation slips between // them. InitializeCoreAsync re-parses driverConfigJson, so a config change delivered here is // applied in place rather than silently discarded. await _lifecycleGate.WaitAsync(cancellationToken).ConfigureAwait(false); try { await ShutdownCoreAsync().ConfigureAwait(false); await InitializeCoreAsync(driverConfigJson, cancellationToken).ConfigureAwait(false); } finally { _lifecycleGate.Release(); } } /// public async Task ShutdownAsync(CancellationToken cancellationToken) { // Bounded wait for the lifecycle gate: a wedged initialize (a connect that never returns, or an // attempt its caller abandoned) must not turn shutdown into a hang. Past the bound we tear down // anyway — the generation bump makes the still-running attempt discard instead of publish. var gated = false; try { gated = await _lifecycleGate.WaitAsync(LifecycleGateTimeout, cancellationToken).ConfigureAwait(false); } catch (OperationCanceledException) { /* the caller stopped waiting for the gate — still tear down */ } if (!gated) _logger.LogWarning( "S7 lifecycle gate still held at shutdown; tearing down anyway. Driver={DriverInstanceId}", _driverInstanceId); try { await ShutdownCoreAsync().ConfigureAwait(false); } finally { if (gated) _lifecycleGate.Release(); } } /// /// The complete teardown: the poll engine (every subscription), the probe loop, the connection, /// the sticky write fault and the per-generation memos. It is its own generation, so its final /// health write can never clobber an initialize that started after it. /// /// A task that completes once everything is released. private async Task ShutdownCoreAsync() { var gen = BeginGeneration(); // Drain the polling overlay first — the engine cancels each loop and awaits it before // disposing its CTS (drain-before-dispose), so no poll iteration touches _gate after this. try { await _poll.DisposeAsync().ConfigureAwait(false); } catch (Exception ex) { _logger.LogWarning(ex, "S7 poll engine drain failed. Driver={DriverInstanceId}", _driverInstanceId); } await ReleaseConnectionAsync(gen).ConfigureAwait(false); lock (_healthLock) { if (_generation != gen) return; // a newer initialize owns the state now _writeFault = null; _writeOwnedError = null; _connectBackoff.RecordSuccess(); Health = new DriverHealth(DriverState.Unknown, Health.LastSuccessfulRead, null); } } /// /// Cancels + bounded-joins the probe loop, then disposes its CTS and the PLC connection. The /// connection part of a teardown (everything but the poll engine and health). Releases only /// while is still current — a teardown that ran past the lifecycle gate /// must not dispose a connection a NEWER initialize already published. /// /// The generation of the lifecycle operation doing the release. /// A task that completes once the prior state is released. private async Task ReleaseConnectionAsync(long gen) { var probeCts = _probeCts; var probeTask = _probeTask; try { probeCts?.Cancel(); } catch { } if (probeTask is not null) { try { await probeTask.WaitAsync(DrainTimeout, CancellationToken.None).ConfigureAwait(false); } catch (TimeoutException) { /* a wedged probe loop — proceed; better than leaking the teardown */ } catch { /* loop faults are already surfaced via health; teardown continues */ } } // Swap the connection out under _gate so a Read/Write/poll pass that already holds the gate (they // re-read Plc inside it) can never see a disposed Plc mid-swap. Bounded: a wedged holder must not hang // teardown, in which case we proceed exactly as the un-gated path always did. var gated = false; try { gated = await _gate.WaitAsync(DrainTimeout).ConfigureAwait(false); } catch { } if (!gated) _logger.LogWarning( "S7 driver {DriverInstanceId}: disposing the S7 connection while an operation still holds the gate (waited {Timeout})", _driverInstanceId, DrainTimeout); try { if (!IsCurrentGeneration(gen)) return; // superseded: the newer generation released (or owns) this state // The probe loop has now observed cancellation and released _gate — safe to dispose the CTS. if (ReferenceEquals(_probeCts, probeCts)) { probeCts?.Dispose(); } else { // An initialize published (and started a probe loop) after this release took its // snapshot — a teardown whose generation bump raced the publish block. Cancel that // loop too; it exits on its next gate wait / delay. Not joined: it needs _gate, which // we hold. Its CTS is left to the GC rather than disposed under a running loop. try { _probeCts?.Cancel(); } catch { /* best-effort */ } probeCts?.Dispose(); } _probeCts = null; _probeTask = null; _initialized = false; _plcDead = false; try { Plc?.Dispose(); } catch { /* best-effort — tearing down anyway */ } Plc = null; Volatile.Write(ref _negotiatedPduSize, 0); // a stale post-teardown reading would read as "online" } finally { if (gated) { try { _gate.Release(); } catch (ObjectDisposedException) { } } } } // ---- lifecycle generation ---- /// /// Guards / / /// / against each other (R07:H5, the /// Modbus _lifecycleGate pattern). Distinct from , which serialises I/O. /// Never disposed: a Dispose racing a still-running ShutdownAsync must not make it throw. /// private readonly SemaphoreSlim _lifecycleGate = new(1, 1); /// /// Bounded wait the teardown paths take on before tearing down anyway. /// Internal so a test can shorten it instead of waiting the production 10 s. /// internal TimeSpan LifecycleGateTimeout { get; set; } = TimeSpan.FromSeconds(10); /// Serialises generation bumps against generation-stamped health writes. private readonly object _healthLock = new(); /// /// Lifecycle generation: bumped by every initialize and teardown. Health writes and /// table/connection publishes carry the generation they were computed under and are dropped /// once it has moved on. Written under . /// private long _generation; /// Starts a new lifecycle generation. /// The new generation. private long BeginGeneration() { lock (_healthLock) return ++_generation; } /// The current lifecycle generation. private long CurrentGeneration => Interlocked.Read(ref _generation); /// True while is still the current lifecycle generation. /// The generation to test. /// when nothing has superseded it. private bool IsCurrentGeneration(long gen) => CurrentGeneration == gen; /// Writes only while is current. /// The generation the health was computed under. /// The health to publish. /// when written. private bool TryWriteHealth(long gen, DriverHealth health) { lock (_healthLock) { if (_generation != gen) return false; Health = health; return true; } } /// /// Derives and writes a new health from the current one, atomically, only while /// is current — for the passes that preserve LastSuccessfulRead. /// /// The generation the update was computed under. /// Maps the current health to the new one; returning null writes nothing. /// when written. private bool TryUpdateHealth(long gen, Func update) { lock (_healthLock) { if (_generation != gen) return false; if (update(Health) is not { } next) return false; Health = next; return true; } } /// The published RawPath → definition and RawPath → parsed-address tables, swapped as one. /// RawPath → definition. /// RawPath → pre-parsed address. private sealed record TagTables( IReadOnlyDictionary Tags, IReadOnlyDictionary Parsed) { /// The empty tables a driver starts with. public static readonly TagTables Empty = new( new Dictionary(StringComparer.Ordinal), new Dictionary(StringComparer.Ordinal)); } /// The live tag tables; replaced by reference at init, never mutated in place. private TagTables _tables = TagTables.Empty; /// The live RawPath → definition table. private IReadOnlyDictionary TagsByRawPath => Volatile.Read(ref _tables).Tags; /// The live RawPath → pre-parsed address table. private IReadOnlyDictionary ParsedByRawPath => Volatile.Read(ref _tables).Parsed; /// public DriverHealth GetHealth() => Health; /// /// True when carries a real config body. The /// bootstrapper always passes a populated document; some unit tests pass "{}" or /// an empty string to exercise lifecycle shape without a config — those keep the /// constructor-supplied . /// private static bool HasConfigBody(string? driverConfigJson) { if (string.IsNullOrWhiteSpace(driverConfigJson)) return false; var trimmed = driverConfigJson.Trim(); return trimmed is not "{}" and not "[]"; } /// /// PDU size the CPU negotiated on the most recent successful connect, in bytes; 0 before the first /// connect and after shutdown. Snapshotted at connect so it stays readable while the handle is /// being replaced. Surfaced through and the connect log line. /// public int NegotiatedPduSize => Volatile.Read(ref _negotiatedPduSize); private int _negotiatedPduSize; /// /// Driver-specific diagnostics key/value pairs (currently S7.NegotiatedPduSize). The core /// record carries no diagnostics bag, so this is the surface until one exists. /// /// A snapshot of the diagnostics. public IReadOnlyDictionary GetDiagnostics() => new Dictionary { ["S7.NegotiatedPduSize"] = NegotiatedPduSize, }; // IDriverDiagnostics view of the same facts, as strings, for the /hosts page. Empty before the // first connect (PDU size 0 is "not negotiated yet", not a size). /// IReadOnlyDictionary IDriverDiagnostics.GetDiagnostics() { var pdu = NegotiatedPduSize; return pdu > 0 ? new Dictionary { ["S7.NegotiatedPduSize"] = pdu.ToString(System.Globalization.CultureInfo.InvariantCulture) } : new Dictionary(); } // ---- IReadable ---- // The batch is served in two passes under ONE gate acquisition. First S7ReadSpanPlanner groups // the resolved tags into contiguous (area, DB) byte spans and each span is read with a single // ReadBytesAsync, its members decoded by slicing the returned block - this is what turns one wire // request per tag into one per contiguous block. Whatever the planner declines (Timer/Counter, // whose offsets are device numbers) plus any span not worth issuing (see PrefersPerTagRead) falls // to the leftover list. // // Those leftovers get a SECOND grouping pass: the ones a S7DataItem expresses cleanly - the narrow // scalars, which is what a demoted single-member span is - are batched into multi-var requests by // ReadLeftoversByMultiVarAsync, which crosses (area, DB) boundaries a block read cannot. Whatever // remains (Timer/Counter, unparseable addresses, and any chunk whose multi-var request faulted) // goes through the unchanged per-tag ReadOneAsync path. // // Setting SpanReadMaxGapBytes below zero skips BOTH passes, which restores the pre-grouping // behaviour exactly. Either way the result array is written by original index, so the caller sees // its own ordering regardless of how the batch was partitioned, and both passes share // RecordReadFailure so a fault stamps the same status whichever path observed it. /// public async Task> ReadAsync( IReadOnlyList fullReferences, CancellationToken cancellationToken) { // Validate the list before the init check so a null argument produces an // ArgumentNullException (consistent with DiscoverAsync) rather than an // InvalidOperationException from the not-initialized check. ArgumentNullException.ThrowIfNull(fullReferences); RequireInitialized(); var now = UtcNow(); var results = new DataValueSnapshot[fullReferences.Count]; // Health is decided ONCE, at the end of the pass, from every outcome the pass observed — // never per item. See ReadPassOutcome. var outcome = new ReadPassOutcome(); await _gate.WaitAsync(cancellationToken).ConfigureAwait(false); // The lifecycle generation this pass runs in — its health write is dropped if a teardown or // re-initialize has moved on by the time it lands. Captured under _gate, where the init // publish happens, and re-checked against _initialized: a pass that passed RequireInitialized // and then waited out a teardown must not reopen a connection on a shut-down driver. var gen = CurrentGeneration; try { RequireInitialized(); // (Re)open the connection under the gate. A failed (re)connect degrades the whole // batch to BadCommunicationError rather than throwing — the poll loop / next read // retries, and EnsureConnectedAsync repairs on the following call. IS7Plc plc; try { plc = await EnsureConnectedAsync(cancellationToken).ConfigureAwait(false); } // Rethrow ONLY caller cancellation. A timeout-born OCE (none expected after the // EnsureConnectedAsync conversion, but e.g. an S7.Net-internal CTS) must degrade the // batch below, not escape as teardown. catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; } catch (Exception ex) { for (var i = 0; i < fullReferences.Count; i++) results[i] = new DataValueSnapshot(null, StatusBadCommunicationError, null, now); TryUpdateHealth(gen, h => new DriverHealth(DriverState.Degraded, h.LastSuccessfulRead, ex.Message)); return results; } // Resolve every reference first. An unresolvable one is a miss, stamped here and never // offered to the planner — grouping must not be able to change what "unknown tag" means. var resolved = new S7TagDefinition?[fullReferences.Count]; for (var i = 0; i < fullReferences.Count; i++) { if (_resolver.TryResolve(fullReferences[i], out var tag)) resolved[i] = tag; else results[i] = new DataValueSnapshot(null, StatusBadNodeIdUnknown, null, now); } // Indexes the per-tag path must serve: everything, when grouping is off; otherwise the // planner's leftovers (Timer/Counter) plus any tag whose address won't parse. var perTag = new List(); // Indexes that must take the per-tag path WITHOUT the multi-var pass: tags the planner may // not group (R07:P2) and the members of a span refused this pass. Batching them into a // multi-var request would just refuse the whole chunk again. List? forcedPerTag = null; // Members of each span refused this pass, and which of them were then refused on their own. List>? refusedSpans = null; // Members of each multi-var chunk that fell back per tag this pass (R07:P2's multi-var sibling). List>? multiVarFallbacks = null; HashSet? refusedAlone = null; if (_options.SpanReadMaxGapBytes >= 0) { List<(int OriginalIndex, S7TagDefinition Tag, S7ParsedAddress Addr)>? plannable = null; for (var i = 0; i < fullReferences.Count; i++) { if (resolved[i] is not { } tag) continue; if (_noGroup.Contains(tag.Name)) { (forcedPerTag ??= []).Add(i); continue; } if (!TryGetParsedAddress(tag, out var addr)) { // Defensive: every tag pre-parses at init. A tag that somehow didn't goes // to the per-tag path, where ReadOneAsync's Parse throws the FormatException // the catch ladder has always mapped to BadCommunicationError. perTag.Add(i); continue; } (plannable ??= []).Add((i, tag, addr)); } if (plannable is not null) { var plan = S7ReadSpanPlanner.Build( plannable, _options.SpanReadMaxGapBytes, _options.SpanReadMaxSpanBytes); foreach (var span in plan.Spans) { // A span that saves no round-trip is not worth changing the wire shape for. if (PrefersPerTagRead(span)) { perTag.Add(span.Members[0].OriginalIndex); continue; } // Fail fast once an earlier span marked the handle dead (R07:P1): every // further wire op on it would pay the full deadline under the gate. if (_plcDead) { foreach (var member in span.Members) results[member.OriginalIndex] = DeadHandleSnapshot(now); continue; } if (await ReadSpanAsync(plc, span, results, now, outcome, cancellationToken).ConfigureAwait(false) is { } refusedMembers) { (refusedSpans ??= []).Add(refusedMembers); (forcedPerTag ??= []).AddRange(refusedMembers); } } perTag.AddRange(plan.LeftoverIndexes); } } else { for (var i = 0; i < fullReferences.Count; i++) if (resolved[i] is not null) perTag.Add(i); } // Sorted so a batch is served in reference order regardless of how it was partitioned — // the per-tag tail is otherwise ordered by the planner's grouping, not by the caller's. perTag.Sort(); // Second grouping pass: the leftovers a DataItem can express ride ONE multi-var request // per chunk instead of a wire request each. Deliberately gated on the SAME switch as the // span pass — SpanReadMaxGapBytes < 0 is documented to restore the pre-grouping wire // shape exactly, and batching the (then complete) per-tag list would break that. What // comes back is the tags still owed an individual read, still in reference order. if (_options.SpanReadMaxGapBytes >= 0) { perTag = await ReadLeftoversByMultiVarAsync( plc, resolved, perTag, results, now, outcome, cancellationToken, fallback => (multiVarFallbacks ??= []).Add(fallback)).ConfigureAwait(false); } if (forcedPerTag is not null) { perTag.AddRange(forcedPerTag); perTag.Sort(); } foreach (var i in perTag) { // Fail fast once the handle is dead (R07:P1) — see the span loop. if (_plcDead) { results[i] = DeadHandleSnapshot(now); continue; } try { var value = await ReadOneAsync(plc, resolved[i]!, cancellationToken).ConfigureAwait(false); results[i] = new DataValueSnapshot(value, 0u, now, now); outcome.RecordSuccess(); } catch (OperationCanceledException) { // Cancellation observed mid-PDU abandons a half-read ISO-on-TCP response on the // single gated stream — the handle must be reopened, not reused. Mark // dead (we hold _gate) and propagate: the caller cancelled, nobody consumes the // batch. Marking is unconditional on OCE (not routed through the type classifier): // whether bytes moved is unknowable, and a false positive costs one cheap reopen // versus permanent desync for a false negative. Kept AT the call site rather // than inside RecordReadFailure so the rethrow preserves the original stack. _plcDead = true; throw; } catch (Exception ex) { if ((refusedSpans is not null || multiVarFallbacks is not null) && IsRefusal(ex)) (refusedAlone ??= []).Add(i); results[i] = new DataValueSnapshot(null, RecordReadFailure(ex, outcome, [resolved[i]!.Name]), null, now); } } // Remember what must not be grouped again (R07:P2). Skipped when the handle died mid-pass: // the per-member reads then proved nothing about which member the CPU refuses. // A multi-var chunk that fell back: memo only the members refused ON THEIR OWN — without one, // the chunk's failure explains nothing about its members, and they keep batching. if (multiVarFallbacks is not null && refusedAlone is not null && !_plcDead) { foreach (var members in multiVarFallbacks) { var bad = members.Where(refusedAlone.Contains).ToList(); if (bad.Count == 0) continue; foreach (var m in bad) _noGroup.Add(resolved[m]!.Name); _logger.LogInformation( "S7 CPU refused a multi-var read of {MemberCount} tag(s); reading {Tags} individually from now on. Driver={DriverInstanceId}", members.Count, string.Join(", ", bad.Select(m => resolved[m]!.Name)), _driverInstanceId); } } if (refusedSpans is not null && !_plcDead) { foreach (var members in refusedSpans) { var bad = members.Where(m => refusedAlone?.Contains(m) == true).ToList(); var memo = bad.Count > 0 ? bad : [.. members]; foreach (var m in memo) _noGroup.Add(resolved[m]!.Name); _logger.LogInformation( "S7 CPU refused a grouped read of {MemberCount} tag(s); reading {Tags} individually from now on. Driver={DriverInstanceId}", members.Count, string.Join(", ", memo.Select(m => resolved[m]!.Name)), _driverInstanceId); } } } finally { // THE single health write of the pass — worst-state-wins over every outcome recorded // above. In a FINALLY, so evidence the pass already gathered survives an abandoned // batch: the three OCE arms rethrow mid-pass, and on a partially-working device a // repeatedly-cancelled poll would otherwise freeze LastSuccessfulRead while tags were // demonstrably still being read — tripping the comms-loss watchdog into a reconnect // loop, the exact false positive the AnySuccess design exists to prevent. // // A pass that observed NOTHING reports nothing (HasObservations), which is also what // makes flushing here safe on the two paths that reach the finally with no outcomes: // the connect-failure early return, whose own Degraded write must NOT be overwritten, // and an OCE that fired before any tag was stamped. Both no-op. // // LastSuccessfulRead advances whenever ANYTHING read, even into a Degraded/Faulted // state — see ReadPassOutcome for why that is load-bearing. // // A sticky write-side Faulted (PUT/GET denied) outranks a read pass that found less // wrong: reads can succeed against a CPU whose writes are protected, and a clean read // must not erase the config alert. The write pass clears it on its next success. if (outcome.HasObservations) { var state = outcome.WorstFailure; var error = state == DriverState.Healthy ? null : outcome.WorstError; if (_writeFault is { } wf && ReadPassOutcome.Rank(wf.State) > ReadPassOutcome.Rank(state)) { state = wf.State; error = wf.Message; } TryUpdateHealth(gen, h => new DriverHealth( state, outcome.AnySuccess ? now : h.LastSuccessfulRead, error)); } _gate.Release(); } return results; } /// /// The outcomes ONE pass observed, accumulated so the pass writes /// exactly once — worst state wins. /// /// /// /// Health used to be stamped per item, in three separate read loops, so the pass /// reported whatever its LAST item happened to be: a mixed pass read Healthy, and /// the access-denied Faulted config alert — usually a minority of the batch — was /// erased by any later good tag. Ranking (Healthy < Degraded < Faulted) and /// deciding once at the end makes the verdict a function of the whole pass rather than /// of its item ordering. /// /// /// is tracked separately from the state on purpose. The /// comms-loss watchdog trips only on a non-Healthy state AND a frozen /// LastSuccessfulRead; several drivers latch Degraded off a single unreadable /// address, so a pass that lands Degraded must still advance the timestamp when /// anything at all was read, or an entirely reachable CPU would be reconnected every /// 90 s forever. /// /// /// Not thread-safe, and does not need to be: a pass runs wholly under /// and every read loop inside it is sequential. /// /// private sealed class ReadPassOutcome { /// True once any tag in the pass read successfully. public bool AnySuccess { get; private set; } /// /// The worst failure state recorded so far; means no /// failure has been recorded at all. /// public DriverState WorstFailure { get; private set; } = DriverState.Healthy; /// /// The first message recorded at the worst severity — the one that explains /// . /// /// /// It must move WITH the state, not independently of it. Keeping the pass's /// chronologically-first message instead desynced the pair whenever a Degraded fault /// preceded a Faulted one: the driver reported the access-denied config alert while its /// message talked about some unrelated device fault and never mentioned PUT/GET, which /// is the one thing the operator has to act on. Within a severity the FIRST message /// still wins — a later peer failure is as likely to be a consequence of it as an /// independent fault. /// public string? WorstError { get; private set; } /// /// True once the pass observed anything at all — a success or a failure. False for a /// degenerate pass (empty batch, or every reference unresolvable), which must report /// nothing rather than invent a verdict. /// public bool HasObservations => AnySuccess || WorstFailure != DriverState.Healthy; /// Records that one tag read successfully. public void RecordSuccess() => AnySuccess = true; /// /// Records that the CPU answered for one tag without serving it (a refusal, an undecodable /// buffer). Not a failure — it ranks nothing — but it IS proof of a live device, so it /// advances LastSuccessfulRead exactly like a success. /// public void RecordAnswered() => AnySuccess = true; /// /// Records one failed tag, keeping the worst state and the message that explains it. /// /// The state this failure would have stamped on its own. /// The failure's operator-facing message. public void RecordFailure(DriverState state, string message) { if (Rank(state) > Rank(WorstFailure)) { // Escalating the severity MUST re-point the message at the new cause. WorstFailure = state; WorstError = message; } else { WorstError ??= message; } } /// Severity order the pass ranks by: Healthy (none) < Degraded < Faulted. /// The state to rank. /// Its severity, higher being worse. internal static int Rank(DriverState state) => state switch { DriverState.Faulted => 2, DriverState.Degraded => 1, _ => 0, }; } /// /// Items one multi-var request may carry. The caller owns chunking — S7.Net does NOT /// split a multi-var read, it throws when the request or the projected response exceeds /// the negotiated PDU (AssertPduSizeForRead). /// /// /// The request costs a 19-byte header plus 12 bytes per item; the response costs a /// 14-byte header plus 4 bytes of item header plus the item's own data. Against the common /// 240-byte PDU that permits 18 items request-side and — for the 4-byte-or-narrower scalars /// this pass batches — 28 response-side. 12 sits well inside both, leaving headroom for a /// CPU that negotiates a smaller PDU than 240, which is the failure this constant exists to /// avoid: an oversized request is a hard throw, not a paged read. It is deliberately NOT a /// config key — the safe value is a property of the protocol, not of a deployment. /// private const int MultiVarReadMaxItems = 12; /// /// Fewest batchable leftovers worth issuing a multi-var request for. ONE leftover is one /// wire request either way, so batching it would change the observable wire shape of every /// single-tag read for zero benefit — the same reasoning /// applies to a lone narrow span. /// /// /// The gate is on the PASS, not on each chunk: a batch of 13 still splits into 12 + 1, and /// that trailing single is left in the multi-var path. It costs one wire request either way, /// so re-routing it would buy nothing and would make the chunk loop's index bookkeeping /// answer a second question. /// private const int MultiVarReadMinItems = 2; /// /// Serves the span planner's leftovers that a can express by /// batching them into multi-var requests, and returns the indexes still owed an individual /// — in ascending reference order. /// /// /// /// Only a narrow scalar is batched. A carrying the same /// area / DB / offset / bit / VarType that S7.Net's own address parser derives /// from the tag's address string, with Count == 1, is decoded by the SAME /// ParseBytes call the per-address read path uses — so its boxed value is /// byte-for-byte and type-for-type what would have produced, /// and applies to it unchanged. /// /// /// Timer and Counter deliberately stay on the per-tag path even though S7.Net's /// VarType names them. Their per-tag path does not go through ParseBytes /// at all — it block-reads the 2-byte word and decodes it in /// , which surfaces a Counter as int where /// S7.Net's own Counter.FromByteArray returns ushort, and which carries a /// documented BCD follow-up for legacy C-area counters. Batching them would fork that /// decode into a second site that must be kept in step by hand. Correctness beats the /// round-trip. Arrays, wide/buffer scalars and unparseable addresses are likewise left /// alone — the first two already read a block apiece, and the last has no address to /// build an item from. /// /// /// A multi-var fault is never a tag's fault. The whole chunk falls back to the /// per-tag path, which is what decides the tag's status — batching must not be able to /// stamp a tag Bad that reading it one at a time would have served, so /// is deliberately NOT called for the request itself. /// S7.Net offers no per-item error surface to be finer-grained with: a /// carries only its Value, and the response parser /// throws on the FIRST item the CPU refused (before populating any later item), so /// per-chunk fallback is the finest granularity the library actually admits. Per-ITEM /// decoding, by contrast, is guarded individually — exactly as the span path guards its /// members — because a mis-authored tag must not spoil the neighbours it shared a /// request with, and it fails identically on the per-tag path anyway. /// /// /// The live connection (caller holds ). /// The batch's resolved tags, indexed by reference position. /// Indexes the span pass left for the per-tag path, ascending. /// The batch's result array, written in place at each tag's original index. /// The batch timestamp, shared by every tag in the batch. /// The pass's outcome accumulator; every decoded item records into it. /// Cancellation token for the reads. /// Receives the member indexes of each chunk that fell back per tag, so /// the caller can memo the members then refused on their own (the multi-var sibling of R07:P2). /// The indexes still owed an individual read, ascending. private async Task> ReadLeftoversByMultiVarAsync( IS7Plc plc, S7TagDefinition?[] resolved, List leftovers, DataValueSnapshot[] results, DateTime now, ReadPassOutcome outcome, CancellationToken ct, Action> onChunkFallback) { var stillPerTag = new List(); List<(int Index, S7TagDefinition Tag, S7ParsedAddress Addr)>? batchable = null; foreach (var i in leftovers) { var tag = resolved[i]!; if (tag.ArrayCount is >= 1 || !TryGetParsedAddress(tag, out var addr) || IsBufferType(tag, addr)) { stillPerTag.Add(i); continue; } (batchable ??= []).Add((i, tag, addr)); } // Nothing to gain: leave the (at most one) batchable tag exactly where it was. if (batchable is null || batchable.Count < MultiVarReadMinItems) { if (batchable is not null) foreach (var (index, _, _) in batchable) stillPerTag.Add(index); stillPerTag.Sort(); return stillPerTag; } for (var start = 0; start < batchable.Count; start += MultiVarReadMaxItems) { var chunk = batchable.GetRange(start, Math.Min(MultiVarReadMaxItems, batchable.Count - start)); // Fail fast once the handle is dead (R07:P1) — see ReadAsync's span loop. if (_plcDead) { foreach (var (index, _, _) in chunk) results[index] = DeadHandleSnapshot(now); continue; } IReadOnlyList answered; try { var items = new List(chunk.Count); foreach (var (_, _, addr) in chunk) items.Add(ToDataItem(addr)); answered = await plc.ReadMultipleVarsAsync(items, ct).ConfigureAwait(false); // The contract is "the same items back, in the supplied order". Anything else is // unmappable to the batch's indexes, so treat it as a failed chunk rather than // guessing which tag got which value. if (answered is null || answered.Count != chunk.Count) { throw new System.IO.InvalidDataException( $"S7.Net returned {answered?.Count.ToString() ?? "no"} multi-var item(s) " + $"for a {chunk.Count}-item request"); } } catch (OperationCanceledException) { // Same reasoning as the per-tag and span paths: a cancelled read abandons a half-read // response on the single gated stream, so the handle must be reopened. _plcDead = true; throw; } catch (Exception ex) when (IsS7TransportLoss(ex)) { // A transport loss is the connection's fault, not the batch's: falling back would // send one more doomed per-tag read per member, each paying the full deadline // (R07:P1). Mark the handle dead and fail the chunk (and, via the guards, the rest // of the pass) without I/O. _plcDead = true; outcome.RecordFailure(DriverState.Degraded, ex.Message); foreach (var (index, _, _) in chunk) results[index] = DeadHandleSnapshot(now); continue; } catch (Exception ex) { _logger.LogDebug(ex, "S7 driver {DriverInstanceId}: multi-var read of {ItemCount} leftover tag(s) failed; " + "falling back to per-tag reads for that chunk", _driverInstanceId, chunk.Count); foreach (var (index, _, _) in chunk) stillPerTag.Add(index); onChunkFallback([.. chunk.Select(c => c.Index)]); continue; } for (var k = 0; k < chunk.Count; k++) { var (index, tag, addr) = chunk[k]; try { var raw = answered[k].Value ?? throw new System.IO.InvalidDataException( $"S7.Net returned null multi-var value for '{tag.Address}'"); results[index] = new DataValueSnapshot(ReinterpretRawValue(tag, addr, raw), 0u, now, now); outcome.RecordSuccess(); } catch (Exception ex) { // Decoding is pure and synchronous — no cancellation can surface here, so there // is deliberately no OperationCanceledException arm to shadow the request one. results[index] = new DataValueSnapshot(null, RecordReadFailure(ex, outcome, [tag.Name]), null, now); } } } // The fallback chunks were appended out of order behind the non-batchable tags. stillPerTag.Sort(); return stillPerTag; } /// /// Builds the multi-var request item for one narrow scalar — the exact /// (DataType, DB, StartByteAdr, BitAdr, VarType, Count) tuple S7.Net's own address /// parser derives from the equivalent address string, so the item reads and decodes /// identically to 's per-address read. /// /// The tag's parsed address; its picks the var type. /// The request item, with no value yet. private static S7DataItem ToDataItem(S7ParsedAddress addr) => new() { DataType = ToS7NetArea(addr.Area), DB = addr.DbNumber, StartByteAdr = addr.ByteOffset, // Non-Bit sizes parse to a bit offset of 0, which S7.Net ignores for those var types. BitAdr = (byte)addr.BitOffset, VarType = addr.Size switch { S7Size.Bit => VarType.Bit, S7Size.Byte => VarType.Byte, S7Size.Word => VarType.Word, S7Size.DWord => VarType.DWord, _ => throw new NotSupportedException($"S7 size {addr.Size} has no multi-var VarType mapping"), }, Count = 1, }; /// /// True when a planned span is better served by the per-tag path: it holds exactly ONE /// narrow scalar, so issuing it as a block read saves no round-trip and buys nothing. /// /// /// The point of grouping is to replace N wire requests with one. A lone narrow tag is one /// wire request either way — but a block read reaches the CPU differently from S7.Net's /// per-address string read, so converting it would change the observable wire shape of every /// single-tag read on the server for zero benefit. A lone ARRAY or wide/buffer scalar is NOT /// demoted: those already read a block on the per-tag path, so serving them as a /// single-member span is byte-for-byte the request they always issued. /// /// The planned span to judge. /// true when the span's single member should go through . private static bool PrefersPerTagRead(S7ReadSpanPlanner.Span span) => span.Members.Count == 1 && span.Members[0].Tag.ArrayCount is not >= 1 && !IsBufferType(span.Members[0].Tag, span.Members[0].Addr); /// /// Reads one planned span — a SINGLE ReadBytesAsync serving every member — and /// decodes each member from its slice of the returned block. /// /// /// A span read is one wire request standing in for many per-tag requests, so a transport /// fault that used to spoil one tag now spoils all of them: every member is stamped with /// the SAME status would have produced for that exception on /// the per-tag path, and health degrades identically. Decoding, by contrast, is per member /// inside its own guard — a single mis-authored tag (declared type vs. address size) must /// not spoil the neighbours that shared its block. /// /// The live connection (caller holds ). /// The planned block read. /// The batch's result array, written in place at each member's original index. /// The batch timestamp, shared by every tag in the batch. /// The pass's outcome accumulator; every member records into it. /// Cancellation token for the read. /// /// once every member has been stamped; or, when the CPU REFUSED the block /// of a multi-member span (R07:P2 — one member past the DB's end refuses them all), the members' /// original indexes, unstamped, for the caller to read one at a time. /// private async Task?> ReadSpanAsync( IS7Plc plc, S7ReadSpanPlanner.Span span, DataValueSnapshot[] results, DateTime now, ReadPassOutcome outcome, CancellationToken ct) { byte[] block; try { block = await plc.ReadBytesAsync( ToS7NetArea(span.Area), span.DbNumber, span.StartByte, span.LengthBytes, ct) .ConfigureAwait(false) ?? throw new System.IO.InvalidDataException( $"S7.Net returned null block for {span.Area} db{span.DbNumber} " + $"@{span.StartByte}+{span.LengthBytes}"); } catch (OperationCanceledException) { // Same reasoning as the per-tag path: a cancelled block read leaves the single gated // stream at an untrustworthy position, so the handle must be reopened. _plcDead = true; throw; } catch (Exception ex) when (span.Members.Count > 1 && IsRefusal(ex)) { // The planner's old invariant ("a grouped read cannot fault where the per-tag reads would // have succeeded") is false: the block is the UNION of the members' ranges, so one member // running past the DB's real end, or over-declaring a STRING, makes the CPU refuse every // neighbour with it. Hand the members back for individual reads. _logger.LogDebug(ex, "S7 driver {DriverInstanceId}: CPU refused the block read of {Area} db{Db} @{Start}+{Length}; " + "re-reading its {Count} member(s) individually", _driverInstanceId, span.Area, span.DbNumber, span.StartByte, span.LengthBytes, span.Members.Count); return [.. span.Members.Select(m => m.OriginalIndex)]; } catch (Exception ex) { var status = RecordReadFailure(ex, outcome, span.Members.Select(m => m.Tag.Name)); foreach (var member in span.Members) results[member.OriginalIndex] = new DataValueSnapshot(null, status, null, now); return null; } foreach (var member in span.Members) { try { var value = DecodeMember(member, block); results[member.OriginalIndex] = new DataValueSnapshot(value, 0u, now, now); outcome.RecordSuccess(); } catch (Exception ex) { // Decoding is pure and synchronous — no cancellation can surface here, so there is // deliberately no OperationCanceledException arm to shadow the block-read one above. results[member.OriginalIndex] = new DataValueSnapshot(null, RecordReadFailure(ex, outcome, [member.Tag.Name]), null, now); } } return null; } /// /// Decodes one span member from its slice of the block, routing to exactly the decoder /// would have chosen for that tag, in the same order. /// /// The member to decode, carrying its slice position and width. /// The block the span read. /// The decoded value, boxed identically to the per-tag path's. private static object DecodeMember(S7ReadSpanPlanner.Member member, byte[] block) { // The two block decoders take byte[] (they hand the buffer to S7.Net's own // S7String/DateTime/Timer/Counter FromByteArray helpers, which are byte[]-only), so a // member that is not the whole block is copied out. Narrow scalars need no copy at all — // DecodeNarrowScalar reads straight from a ReadOnlySpan positioned at the tag's own byte. if (member.Tag.ArrayCount is >= 1) return DecodeArrayBlock(member.Tag, member.Addr, SliceForMember(member, block)); if (IsBufferType(member.Tag, member.Addr)) return DecodeScalarBlock(member.Tag, member.Addr, SliceForMember(member, block)); return DecodeNarrowScalar(member.Tag, member.Addr, block.AsSpan(member.RelativeOffset, member.WidthBytes)); } /// /// The member's own bytes as a byte[] for the block decoders. Returns the block /// itself — no copy — when the member IS the whole block, which is the single-member span /// every array / wide scalar produces today. /// /// The member whose bytes are wanted. /// The block the span read. /// The member's bytes, starting at its own first byte. private static byte[] SliceForMember(S7ReadSpanPlanner.Member member, byte[] block) => member.RelativeOffset == 0 && member.WidthBytes == block.Length ? block : block[member.RelativeOffset..(member.RelativeOffset + member.WidthBytes)]; /// /// The tag's parsed address: the table built at init, with an on-demand parse as the /// defensive fallback for a tag that isn't in it. Mirrors 's /// lookup, but never throws — an unparseable address returns false so the caller can /// route the tag to the per-tag path, where the surfaces /// through the ladder exactly as it always has. /// /// The tag whose address is wanted. /// The parsed address, valid only when this returns true. /// true when the address is known or parses. private bool TryGetParsedAddress(S7TagDefinition tag, out S7ParsedAddress addr) => ParsedByRawPath.TryGetValue(tag.Name, out addr) || S7AddressParser.TryParse(tag.Address, out addr); /// /// The read-failure classification ladder, shared by the per-tag path and the span path so /// a failed span stamps every member with exactly the status the same exception would have /// produced on a single tag. Records the failure into the pass's outcome, applies the /// dead-handle side effect, and returns the status code the caller must stamp. /// /// /// /// The health state is recorded, not applied. It goes into /// so the pass can write once at the /// end, worst-state-wins — writing it here is what let a later good tag erase this /// failure. The _plcDead / side effects /// stay IMMEDIATE: they govern whether the very next read reopens the handle, which /// cannot wait for the pass to finish. /// /// /// is deliberately NOT handled here: it is /// control flow rather than a per-tag status (it marks the handle dead and propagates), /// and rethrowing it from a helper would rewrite the stack. Both call sites catch it /// first. /// /// /// The exception observed on a read. /// The pass's outcome accumulator this failure is recorded into. /// The tags the failure belongs to (every member of a failed span), for the /// once-per-tag refusal Warning. /// The OPC UA status code every affected tag must be stamped with. private uint RecordReadFailure(Exception ex, ReadPassOutcome outcome, IEnumerable tagNames) { switch (ex) { case NotSupportedException: return StatusBadNotSupported; case S7ValueRangeException: // A PLC buffer the type codec refuses (uninitialised DTL, non-BCD S5TIME…) is a data // problem, not a transport fault — no health change, no connection teardown. The // bytes came off the wire, so the CPU answered. outcome.RecordAnswered(); return StatusBadOutOfRange; case var _ when IsAccessDenied(ex): // PUT/GET-disabled (S7-1200/1500) / access-protection — a permanent configuration // fault, NOT a transient one. Blind retry is wasted effort, so map it to // BadNotSupported and flag the driver as a config alert (Faulted) rather than // Degraded — per driver-specs.md §5. Matched over the whole chain: S7.Net's READ // paths raise the CPU's item error as a bare Exception, not a PlcException. // It is ALSO an answer from a reachable CPU: LastSuccessfulRead must advance, or a // factory-default CPU (every read denied) trips the comms-loss watchdog into a // reconnect + re-subscribe every 90 s that can never fix a PUT/GET setting. // Faulted still wins the pass (worst state), so the config alert is kept. outcome.RecordAnswered(); outcome.RecordFailure(DriverState.Faulted, "S7 access denied — enable PUT/GET communication in TIA Portal " + $"(Protection & Security) for this CPU. PLC reported: {ex.Message}"); return StatusBadNotSupported; case var _ when IsRefusal(ex): // The CPU answered and refused the item (object does not exist, address out of // range, type inconsistent...) — deterministic, so a retry, a reopen or a Degraded // would all be wrong: per-tag Bad, a once-per-tag Warning, no health write, and it // counts as answered so LastSuccessfulRead advances (R07:H4). An all-refused driver // (wrong DB number) used to sit Degraded with a frozen timestamp and trip the // comms-loss watchdog every 90 s against a reachable PLC. outcome.RecordAnswered(); foreach (var name in tagNames) WarnRefusalOnce(name, "read", ex); return StatusBadDeviceFailure; case PlcException pex: // A genuine device-layer fault (CPU error, hardware fault) — transient enough to // keep retrying; report BadDeviceFailure and degrade health. A connection-fatal // PlcException (socket drop / ConnectionError) additionally marks the handle dead // so the next read reopens it. MarkConnectionDeadIfFatal(pex); outcome.RecordFailure(DriverState.Degraded, pex.Message); return StatusBadDeviceFailure; default: // Socket / timeout / transport fault — mark the handle dead when it's a connection // loss so EnsureConnectedAsync reopens on the next call. MarkConnectionDeadIfFatal(ex); outcome.RecordFailure(DriverState.Degraded, ex.Message); return StatusBadCommunicationError; } } private async Task ReadOneAsync(IS7Plc plc, S7TagDefinition tag, CancellationToken ct) { // Every tag pre-parses its address at init (ParsedByRawPath); the on-demand // S7AddressParser.Parse is a defensive fallback for a tag not in that table. Parse throws // FormatException on a bad address, which the caller's catch maps to BadCommunicationError. var addr = ParsedByRawPath.TryGetValue(tag.Name, out var parsed) ? parsed : S7AddressParser.Parse(tag.Address); // Array path: a tag with a declared count >= 1 reads a CONTIGUOUS block of // count × element-bytes in a SINGLE round-trip (Plc.ReadBytesAsync), then decodes each // element from its big-endian slice into an element-typed CLR array. The scalar path // (count null) is left byte-for-byte unchanged below. A count of 1 IS a valid 1-element // array (the foundation materialises a [1] OPC UA array node when isArray:true). if (tag.ArrayCount is >= 1) return await ReadArrayAsync(plc, tag, addr, ct).ConfigureAwait(false); // Wide/structured scalar path (Int64/UInt64/Float64/String/DateTime) AND the Timer/Counter // areas: S7.Net's string ReadAsync only decodes 1/2/4-byte size suffixes, so neither family // can go through the narrow path below. Read a contiguous byte block and decode it — // mirrors the array path's buffer read. Timer/Counter route here on AREA (IsBufferType), // so a Timer/Float64 tag reads its 2-byte S5TIME word here rather than falling through to // the dead Float64 stub (which would surface BadNotSupported on every read). if (IsBufferType(tag, addr)) return await ReadScalarBlockAsync(plc, tag, addr, ct).ConfigureAwait(false); // S7.Net's string-based ReadAsync returns object where the boxed .NET type depends on // the size suffix: DBX=bool, DBB=byte, DBW=ushort, DBD=uint. Our S7DataType enum // specifies the SEMANTIC type (Int16 vs UInt16 vs Float32 etc.); the reinterpret below // converts the raw unsigned boxed value into the requested type without issuing an // extra PLC round-trip. var raw = await plc.ReadAsync(tag.Address, ct).ConfigureAwait(false) ?? throw new System.IO.InvalidDataException($"S7.Net returned null for '{tag.Address}'"); return ReinterpretRawValue(tag, addr, raw); } /// /// Reads a 1-D array tag as ONE contiguous block (count × element-bytes) via /// S7.Net's buffer-based Plc.ReadBytesAsync(DataType, db, startByteAdr, count, ct) /// — a single PLC round-trip, NOT N string reads — then hands the raw byte block /// to the pure decode loop. Timer/Counter areas are /// already rejected at init, so only DB/M/I/Q reach here. /// private async Task ReadArrayAsync(IS7Plc plc, S7TagDefinition tag, S7ParsedAddress addr, CancellationToken ct) { var count = tag.ArrayCount!.Value; var elementBytes = ElementByteSize(addr.Size); var totalBytes = count * elementBytes; // ReadBytesAsync addresses by (area, db, startByteOffset, byteCount). The parser already // normalised the start to a BYTE offset (ByteOffset) for DB/M/I/Q; a Bit array starts at // its byte and consumes one byte per element (byte-granular contiguous bit access). S7.Net // transparently splits a > PDU-sized block into multiple wire requests, so the driver // doesn't have to chunk. var area = ToS7NetArea(addr.Area); var block = await plc.ReadBytesAsync(area, addr.DbNumber, addr.ByteOffset, totalBytes, ct) .ConfigureAwait(false) ?? throw new System.IO.InvalidDataException($"S7.Net returned null block for '{tag.Address}'"); return DecodeArrayBlock(tag, addr, block); } /// /// True when this tag must be read/written through the byte-buffer codec rather than /// S7.Net's string path. Two families route here: /// /// the wide/structured types (Int64/UInt64/Float64/String/DateTime), which are /// byte-anchored (DBB/MB/IB/QB) and decoded from a /// contiguous block — S7.Net's string ReadAsync only understands 1/2/4-byte size /// suffixes, so they can't use the narrow path; /// the Timer/Counter AREAS — a Timer (T{n}) decodes a 2-byte S5TIME word /// to a duration in seconds (double) and a Counter (C{n}) decodes a /// 2-byte word to a count (int); both are read-only this phase. Routing them /// here (rather than through the narrow path, which would hit the dead Float64 stub and /// throw BadNotSupported on every read) closes the interim correctness hole. /// /// The init guard already enforces byte-addressing + the Timer→Float64 / Counter→Int32 /// type constraints, so by the time a tag reaches here it is well-formed. /// /// Tag definition carrying the . /// Parsed address — its routes Timer/Counter into the seam regardless of . /// true if the tag routes through the byte-buffer codec. internal static bool IsBufferType(S7TagDefinition tag, S7ParsedAddress addr) => addr.Area is S7Area.Timer or S7Area.Counter || S7TagShapeRules.IsByteAnchored(tag.DataType); /// /// Reads a wide/structured scalar as ONE contiguous byte block via S7.Net's /// buffer-based Plc.ReadBytesAsync(DataType, db, startByteAdr, count, ct) (a single /// PLC round-trip), then hands the raw block to the pure /// decode. Mirrors 's shape. /// private async Task ReadScalarBlockAsync(IS7Plc plc, S7TagDefinition tag, S7ParsedAddress addr, CancellationToken ct) { var width = ScalarByteWidth(tag, addr); // For DB/M/I/Q, addr.ByteOffset is the start BYTE and `width` the byte count. For // Timer/Counter, addr.ByteOffset is the timer/counter NUMBER (db stays 0) and width is 2: // S7.Net's Timer/Counter transport size makes the request "count" word a per-2-byte unit, // so passing 2 reads exactly one timer/counter's 2-byte block (matching S7.Net's own // VarType.Timer/Counter path, which sets byteLength = varCount × 2). See ScalarByteWidth. var block = await plc.ReadBytesAsync(ToS7NetArea(addr.Area), addr.DbNumber, addr.ByteOffset, width, ct) .ConfigureAwait(false) ?? throw new System.IO.InvalidDataException($"S7.Net returned null block for '{tag.Address}'"); return DecodeScalarBlock(tag, addr, block); } /// /// Byte width of one wide/structured scalar (or one Timer/Counter word). /// The parsed AREA takes precedence over the tag's : a /// Timer/Counter address is always 2 bytes (one S5TIME / counter word), even though a /// Timer tag is typed (which would otherwise yield 8) and /// a Counter tag . For DB/M/I/Q areas the width follows the /// DataType: Int64/UInt64/Float64/DateTime are 8 bytes; an S7 STRING occupies /// StringLength + 2 bytes (the two-byte header carries the declared max length and /// the current actual length). Throws for any non-buffer type — defensive; /// gates this so a non-buffer type never reaches here. /// /// Tag definition carrying the and (for strings) StringLength. /// Parsed address — Timer/Counter areas force a 2-byte width regardless of . /// The byte width to read for this scalar. internal static int ScalarByteWidth(S7TagDefinition tag, S7ParsedAddress addr) { // Area precedence: Timer (S5TIME) and Counter are a single 16-bit word on the wire. The // Timer tag's Float64 DataType describes the DECODED value (seconds), not the read width, // so it must NOT drive an 8-byte read — that would mis-frame the timer word. if (addr.Area is S7Area.Timer or S7Area.Counter) return 2; return tag.DataType switch { S7DataType.Int64 or S7DataType.UInt64 or S7DataType.Float64 => 8, S7DataType.DateTime => 8, // 8 = S7 DATE_AND_TIME/DT BCD (S7.Net.Types.DateTime; the 8-byte DT, not 12-byte DTL). S7DataType.String => tag.StringLength + 2, S7DataType.WString => S7ValueCodecs.WStringWidth(tag.StringLength), S7DataType.Char => 1, S7DataType.WChar or S7DataType.Date or S7DataType.S5Time => 2, S7DataType.Tod or S7DataType.Time => 4, S7DataType.Dtl => 12, _ => throw new InvalidOperationException( $"S7 ScalarByteWidth called for non-buffer type {tag.DataType} (tag '{tag.Name}')"), }; } /// /// Pure decode step — turns a raw S7 (big-endian) byte block into the wide scalar's CLR /// value (long / ulong / double), boxed as . No /// network I/O — factored out of so the codec is /// unit-testable against a known block without a live PLC (S7.Net ships no in-process /// fake). Mirrors . /// /// Tag definition carrying the wide . /// Parsed address (carried for the error surface + the Timer/Counter seam). /// Raw contiguous byte block read from the PLC (length == ). /// The decoded scalar value boxed as . internal static object DecodeScalarBlock(S7TagDefinition tag, S7ParsedAddress addr, byte[] block) { // AREA precedence first (before the DataType switch): a Timer (T{n}) decodes its 2-byte // S5TIME word to a duration in SECONDS via S7.Net's Timer.FromByteArray (returns double); // a Counter (C{n}) exposes its 2-byte RAW WORD via Counter.FromByteArray (returns // ushort, surfaced as a non-negative int to match the tag's Int32 type). Routing on Area // here is essential: a Timer tag is typed Float64, so letting it fall to the Float64 arm // below would ReadDoubleBigEndian over a 2-byte block = garbage/throw. Boxed explicitly so // the box type is exactly double / int (not the switch-unified common type). if (addr.Area is S7Area.Timer) return (object)global::S7.Net.Types.Timer.FromByteArray(block); if (addr.Area is S7Area.Counter) { // S7.Net Counter.FromByteArray returns the raw big-endian word ((bytes[0]<<8)|bytes[1]), // without BCD reinterpretation. This preserves the raw value, not a verified PLC count: // S7comm C-area response encoding still needs independent raw bytes and PLC-side // count/binary/BCD references. CPU family alone does not prove that encoding. // IEC counter integers in DB memory take the DB type codec, not this C-area path; // S7-1500 also has legacy SIMATIC counters. See docs/drivers/S7.md for the evidence gate. return (object)(int)global::S7.Net.Types.Counter.FromByteArray(block); } // Each numeric arm is boxed to object explicitly: a bare switch expression would unify // long/ulong/double to their common type (double) and box THAT, mis-typing Int64/UInt64. return tag.DataType switch { S7DataType.Int64 => (object)System.Buffers.Binary.BinaryPrimitives.ReadInt64BigEndian(block), S7DataType.UInt64 => (object)System.Buffers.Binary.BinaryPrimitives.ReadUInt64BigEndian(block), S7DataType.Float64 => System.Buffers.Binary.BinaryPrimitives.ReadDoubleBigEndian(block), // S7 classic STRING: [maxLen byte][curLen byte][chars…]. S7.Net's S7String.FromByteArray // reads the two-byte header and returns exactly curLen ASCII chars, ignoring the reserved // padding past curLen — it validates curLen against the block, so no extra guard is needed. S7DataType.String => global::S7.Net.Types.S7String.FromByteArray(block), // S7 classic DATE_AND_TIME (DT): 8-byte BCD value (year/month/day/hour/min/sec + ms + // day-of-week nibble). S7.Net's DateTime.FromByteArray reads the BCD fields and returns a // System.DateTime; the DT range is 1990–2089 and round-trips to the millisecond. Boxed as // System.DateTime explicitly (the cast pins the box type, consistent with the numeric arms). S7DataType.DateTime => (object)global::S7.Net.Types.DateTime.FromByteArray(block), // The codecs below live in S7ValueCodecs (pure, big-endian); a malformed PLC buffer throws // S7ValueRangeException → BadOutOfRange on the read. TOD/TIME/S5TIME surface as Int32 ms. S7DataType.WString => S7ValueCodecs.DecodeWString(block), S7DataType.Char => S7ValueCodecs.DecodeChar(block), S7DataType.WChar => S7ValueCodecs.DecodeWChar(block), S7DataType.Dtl => (object)S7ValueCodecs.DecodeDtl(block), S7DataType.Date => (object)S7ValueCodecs.DecodeDate(block), S7DataType.Tod => (object)S7ValueCodecs.DecodeTod(block), S7DataType.Time => (object)S7ValueCodecs.DecodeTime(block), S7DataType.S5Time => (object)S7ValueCodecs.DecodeS5Time(block), _ => throw new System.IO.InvalidDataException( $"S7 scalar Read type-mismatch: tag '{tag.Name}' declared {tag.DataType} but address " + $"'{tag.Address}' parsed as Size={addr.Size}"), }; } /// /// Pure encode step — turns the caller's value into the raw S7 (big-endian) byte block /// for a wide scalar write. No network I/O — factored out of /// so the codec is unit-testable (mirrors /// ). /// /// Tag definition carrying the wide . /// Value to encode (coerced via Convert.To*). /// The big-endian byte block to write. internal static byte[] EncodeScalarBlock(S7TagDefinition tag, object? value) { // Timer/Counter are READ-ONLY this phase. A Timer tag is typed Float64 and a Counter tag // Int32, so the DataType switch below would otherwise hand them a (wrong, 8/wide-byte) // encode arm — guard on the parsed AREA first and refuse the write. The address parses to // an S7Area without I/O; TryParse keeps a malformed address from masking the read-only // contract (a bad address falls through to the DataType arms and is caught upstream). if (S7AddressParser.TryParse(tag.Address, out var addr) && addr.Area is S7Area.Timer or S7Area.Counter) { throw new NotSupportedException( $"S7 Timer/Counter writes are read-only this phase (tag '{tag.Name}' at '{tag.Address}')."); } switch (tag.DataType) { case S7DataType.Int64: { var b = new byte[8]; System.Buffers.Binary.BinaryPrimitives.WriteInt64BigEndian(b, Convert.ToInt64(value)); return b; } case S7DataType.UInt64: { var b = new byte[8]; System.Buffers.Binary.BinaryPrimitives.WriteUInt64BigEndian(b, Convert.ToUInt64(value)); return b; } case S7DataType.Float64: { var b = new byte[8]; System.Buffers.Binary.BinaryPrimitives.WriteDoubleBigEndian(b, Convert.ToDouble(value)); return b; } case S7DataType.String: // S7.Net's S7String.ToByteArray builds [maxLen=StringLength][curLen][chars…] and pads // the result to the full reserved field (StringLength + 2 bytes) — exactly the width // ReadScalarBlockAsync read, so WriteBytesAsync writes the whole reserved STRING. A value // longer than StringLength throws ArgumentException (S7.Net rejects overflow; we do NOT // silently truncate). A null value encodes as the empty string. // Surfaced as S7ValueRangeException (→ BadOutOfRange) like the WSTRING codec — a // client value error, not a comms fault (the raw ArgumentException used to land in the // generic catch as BadCommunicationError + Degraded). try { return global::S7.Net.Types.S7String.ToByteArray(Convert.ToString(value) ?? "", tag.StringLength); } catch (ArgumentException ex) { throw new S7ValueRangeException($"S7 STRING value does not fit the declared {tag.StringLength}-character field: {ex.Message}"); } case S7DataType.DateTime: // S7.Net's DateTime.ToByteArray builds the 8-byte DT BCD block. It validates the // 1990–2089 DT range and throws ArgumentOutOfRangeException for an out-of-range year — // we surface that (no silent clamp). Value coerced via Convert.ToDateTime (accepts a // System.DateTime or a parseable timestamp string). // The range refusal maps to BadOutOfRange (see STRING above). var dt = Convert.ToDateTime(value); try { return global::S7.Net.Types.DateTime.ToByteArray(dt); } catch (ArgumentOutOfRangeException ex) { throw new S7ValueRangeException($"S7 DATE_AND_TIME value {dt:O} is outside the DT range (1990–2089): {ex.Message}"); } // Writes refuse (S7ValueRangeException → BadOutOfRange) rather than truncate or clamp. case S7DataType.WString: return S7ValueCodecs.EncodeWString(value, tag.StringLength); case S7DataType.Char: return S7ValueCodecs.EncodeChar(value); case S7DataType.WChar: return S7ValueCodecs.EncodeWChar(value); case S7DataType.Dtl: return S7ValueCodecs.EncodeDtl(value); case S7DataType.Date: return S7ValueCodecs.EncodeDate(value); case S7DataType.Tod: return S7ValueCodecs.EncodeTod(value); case S7DataType.Time: return S7ValueCodecs.EncodeTime(value); case S7DataType.S5Time: return S7ValueCodecs.EncodeS5Time(value); default: throw new InvalidOperationException( $"S7 EncodeScalarBlock called for non-buffer type {tag.DataType} (tag '{tag.Name}')"); } } /// Width in bytes of one array element for the given access size. Bit elements are /// byte-granular over the wire (one byte per bool), so they cost 1 byte each. /// The parsed access width. /// Element byte size: Bit/Byte = 1, Word = 2, DWord = 4. internal static int ElementByteSize(S7Size size) => size switch { S7Size.Bit => 1, S7Size.Byte => 1, S7Size.Word => 2, S7Size.DWord => 4, _ => throw new InvalidOperationException($"Unknown S7Size {size}"), }; /// /// Maps the driver's to S7.Net's DataType for the /// buffer-based block read. Timer/Counter map to S7.Net's Timer/Counter /// transport types — the ScalarByteWidth 2-byte read uses these to read one /// timer/counter word (the array path never reaches Timer/Counter: wide-type arrays are /// rejected at init and Timer/Counter are always scalar). /// private static S7NetDataType ToS7NetArea(S7Area area) => area switch { S7Area.DataBlock => S7NetDataType.DataBlock, S7Area.Memory => S7NetDataType.Memory, S7Area.Input => S7NetDataType.Input, S7Area.Output => S7NetDataType.Output, S7Area.Timer => S7NetDataType.Timer, S7Area.Counter => S7NetDataType.Counter, _ => throw new NotSupportedException($"S7 area {area} has no S7.Net DataType mapping"), }; /// /// Pure decode loop — turns a raw S7 (big-endian) byte block into an element-typed CLR /// array (short[] / ushort[] / int[] / uint[] / float[] /// / byte[] / bool[]), boxed as . No network I/O — /// factored out of so the block-decode is unit-testable /// against a known byte block without a live PLC (S7.Net ships no in-process fake). /// Each element is read from its i × element-bytes slice using S7 big-endian byte /// order, identical to the per-element semantics of . /// /// Tag definition carrying the element and array count. /// Parsed address carrying the access . /// Raw contiguous byte block read from the PLC (length == count × element-bytes). /// An element-typed CLR array boxed as . internal static object DecodeArrayBlock(S7TagDefinition tag, S7ParsedAddress addr, byte[] block) { var count = tag.ArrayCount!.Value; var elementBytes = ElementByteSize(addr.Size); switch (tag.DataType, addr.Size) { case (S7DataType.Bool, S7Size.Bit): { var a = new bool[count]; for (var i = 0; i < count; i++) a[i] = (block[i] & 0x01) != 0; return a; } case (S7DataType.Byte, S7Size.Byte): { var a = new byte[count]; for (var i = 0; i < count; i++) a[i] = block[i]; return a; } case (S7DataType.UInt16, S7Size.Word): { var a = new ushort[count]; for (var i = 0; i < count; i++) a[i] = ReadBeUInt16(block, i * elementBytes); return a; } case (S7DataType.Int16, S7Size.Word): { var a = new short[count]; for (var i = 0; i < count; i++) a[i] = unchecked((short)ReadBeUInt16(block, i * elementBytes)); return a; } case (S7DataType.UInt32, S7Size.DWord): { var a = new uint[count]; for (var i = 0; i < count; i++) a[i] = ReadBeUInt32(block, i * elementBytes); return a; } case (S7DataType.Int32, S7Size.DWord): { var a = new int[count]; for (var i = 0; i < count; i++) a[i] = unchecked((int)ReadBeUInt32(block, i * elementBytes)); return a; } case (S7DataType.Float32, S7Size.DWord): { var a = new float[count]; for (var i = 0; i < count; i++) a[i] = BitConverter.UInt32BitsToSingle(ReadBeUInt32(block, i * elementBytes)); return a; } case (S7DataType.Int64, _): case (S7DataType.UInt64, _): case (S7DataType.Float64, _): case (S7DataType.String, _): case (S7DataType.DateTime, _): case (S7DataType.WString, _): case (S7DataType.Char, _): case (S7DataType.WChar, _): case (S7DataType.Dtl, _): case (S7DataType.Date, _): case (S7DataType.Tod, _): case (S7DataType.Time, _): case (S7DataType.S5Time, _): throw new NotSupportedException( $"S7 array reads of {tag.DataType} land in a follow-up PR"); default: throw new System.IO.InvalidDataException( $"S7 array Read type-mismatch: tag '{tag.Name}' declared {tag.DataType} but address " + $"'{tag.Address}' parsed as Size={addr.Size}"); } } /// Reads a big-endian 16-bit word from at . private static ushort ReadBeUInt16(byte[] block, int offset) => (ushort)((block[offset] << 8) | block[offset + 1]); /// Reads a big-endian 32-bit dword from at . private static uint ReadBeUInt32(byte[] block, int offset) => ((uint)block[offset] << 24) | ((uint)block[offset + 1] << 16) | ((uint)block[offset + 2] << 8) | block[offset + 3]; /// /// Byte width one narrow scalar (Bit/Byte/Word/DWord) occupies inside a contiguous block — /// the stride a span planner uses to size and slice a group read. Delegates to /// so the scalar and array paths can never disagree about a /// size's width (a Bit costs a whole byte: S7 block reads are byte-granular). /// /// Parsed address carrying the access . /// Byte width: Bit/Byte = 1, Word = 2, DWord = 4. internal static int NarrowScalarWidth(S7ParsedAddress addr) => ElementByteSize(addr.Size); /// /// Pure decode step — turns the tag's own slice of a contiguous big-endian block into the /// SEMANTIC CLR value declared by its , boxed as /// . No network I/O and no driver state: this is the span-read twin of /// (which reinterprets the boxed value S7.Net's /// per-tag string ReadAsync returns), and it deliberately mirrors that method's /// sign/width/conversion semantics arm for arm so a tag reads identically whether it was /// served by one wire request of its own or by one block read shared with its neighbours. /// /// /// is positioned at the tag's OWN first byte — /// slice[0] is the tag's first byte, so is /// the caller's business and is never re-applied here. Only the leading /// bytes are consumed; a longer slice (the rest of the /// block) is fine. Wide/structured types (Int64/UInt64/Float64/String/DateTime) and the /// Timer/Counter areas are NOT narrow — they route through /// — and fall into the mismatch arm here so a mis-routed /// tag fails loudly instead of decoding garbage from a truncated slice. /// /// Tag definition carrying the narrow . /// Parsed address carrying the access and (for Bool) the bit position. /// The tag's slice of the block, big-endian, at least bytes long. /// The decoded value boxed as , with the same box type produces. internal static object DecodeNarrowScalar(S7TagDefinition tag, S7ParsedAddress addr, ReadOnlySpan slice) { // Each arm boxes explicitly: a bare switch expression would unify bool/byte/ushort/short/ // uint/int/float to a common type and box THAT, mis-typing every narrow tag (the same trap // DecodeScalarBlock documents). The box type is part of the contract — the publish pipeline // and the OPC UA variable's DataType both key off it. switch (tag.DataType, addr.Size) { // DBX / M{n}.{b}: S7.Net's string read returns the already-extracted bool. From a block // we extract it ourselves at the parsed bit position (0-7, guaranteed by the parser). case (S7DataType.Bool, S7Size.Bit): return (object)((slice[0] & (1 << addr.BitOffset)) != 0); // DBB: the whole byte, unsigned (S7.Net boxes a byte). case (S7DataType.Byte, S7Size.Byte): return (object)slice[0]; // DBW: one big-endian word. UInt16 is the raw word; Int16 is the SAME bits reinterpreted // unchecked (0x8000 => -32768), exactly as ReinterpretRawValue casts S7.Net's ushort. case (S7DataType.UInt16, S7Size.Word): return (object)System.Buffers.Binary.BinaryPrimitives.ReadUInt16BigEndian(slice); case (S7DataType.Int16, S7Size.Word): return (object)unchecked((short)System.Buffers.Binary.BinaryPrimitives.ReadUInt16BigEndian(slice)); // DBD: one big-endian dword. UInt32 raw; Int32 the same bits unchecked; Float32 the same // bits reinterpreted as IEEE-754 single (never a numeric conversion). case (S7DataType.UInt32, S7Size.DWord): return (object)System.Buffers.Binary.BinaryPrimitives.ReadUInt32BigEndian(slice); case (S7DataType.Int32, S7Size.DWord): return (object)unchecked((int)System.Buffers.Binary.BinaryPrimitives.ReadUInt32BigEndian(slice)); case (S7DataType.Float32, S7Size.DWord): return (object)BitConverter.UInt32BitsToSingle( System.Buffers.Binary.BinaryPrimitives.ReadUInt32BigEndian(slice)); default: throw new System.IO.InvalidDataException( $"S7 narrow-span Read type-mismatch: tag '{tag.Name}' declared {tag.DataType} but address " + $"'{tag.Address}' parsed as Size={addr.Size}"); } } /// /// Pure reinterpret step — converts the boxed value that S7.Net returns (always an /// unsigned type: bool, byte, ushort, uint) into the /// SEMANTIC type declared by the tag's . No network I/O. /// Factored out of so it can be exercised in unit tests /// without a live PLC. /// /// Tag definition containing type information. /// Parsed tag address. /// Raw value from S7.Net. /// The reinterpreted value in the target semantic type. internal static object ReinterpretRawValue(S7TagDefinition tag, S7ParsedAddress addr, object raw) => (tag.DataType, addr.Size, raw) switch { (S7DataType.Bool, S7Size.Bit, bool b) => b, (S7DataType.Byte, S7Size.Byte, byte by) => by, (S7DataType.UInt16, S7Size.Word, ushort u16) => u16, (S7DataType.Int16, S7Size.Word, ushort u16) => unchecked((short)u16), (S7DataType.UInt32, S7Size.DWord, uint u32) => u32, (S7DataType.Int32, S7Size.DWord, uint u32) => unchecked((int)u32), (S7DataType.Float32, S7Size.DWord, uint u32) => BitConverter.UInt32BitsToSingle(u32), // Unreachable defensive backstop — every wide type (Int64/UInt64/Float64/String/ // DateTime) AND every Timer/Counter tag routes through the byte-buffer path // (IsBufferType → ReadScalarBlockAsync → DecodeScalarBlock) before ReinterpretRawValue // is ever consulted. Kept (not deleted) so a future regression that mis-routes a wide // type to the narrow path fails loudly here instead of silently mis-decoding. (S7DataType.Int64, _, _) => throw new NotSupportedException("S7 Int64 is unreachable here — wide types route through the byte-buffer path (DecodeScalarBlock)"), (S7DataType.UInt64, _, _) => throw new NotSupportedException("S7 UInt64 is unreachable here — wide types route through the byte-buffer path (DecodeScalarBlock)"), (S7DataType.Float64, _, _) => throw new NotSupportedException("S7 Float64 (LReal) is unreachable here — wide types route through the byte-buffer path (DecodeScalarBlock)"), (S7DataType.String, _, _) => throw new NotSupportedException("S7 STRING is unreachable here — wide types route through the byte-buffer path (DecodeScalarBlock)"), (S7DataType.DateTime, _, _) => throw new NotSupportedException("S7 DateTime is unreachable here — wide types route through the byte-buffer path (DecodeScalarBlock)"), _ => throw new System.IO.InvalidDataException( $"S7 Read type-mismatch: tag '{tag.Name}' declared {tag.DataType} but address '{tag.Address}' " + $"parsed as Size={addr.Size}; S7.Net returned {raw.GetType().Name}"), }; // ---- IWritable ---- /// public async Task> WriteAsync( IReadOnlyList writes, CancellationToken cancellationToken) { // Same as ReadAsync — validate before the init check so a null argument is a // typed argument error, not the "not initialized" surface. ArgumentNullException.ThrowIfNull(writes); RequireInitialized(); var results = new WriteResult[writes.Count]; // Health is decided ONCE, at the end of the batch, worst-state-wins — see WritePassOutcome. var outcome = new WritePassOutcome(); await _gate.WaitAsync(cancellationToken).ConfigureAwait(false); var gen = CurrentGeneration; // see ReadAsync try { RequireInitialized(); // (Re)open under the gate; a failed (re)connect degrades every write to // BadCommunicationError rather than throwing. IS7Plc plc; try { plc = await EnsureConnectedAsync(cancellationToken).ConfigureAwait(false); } // Rethrow ONLY caller cancellation — a timeout-born OCE degrades the batch below rather // than escaping as teardown (defense-in-depth, mirrors ReadAsync). catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; } catch (Exception ex) { for (var i = 0; i < writes.Count; i++) results[i] = new WriteResult(StatusBadCommunicationError); outcome.RecordFailure(DriverState.Degraded, ex.Message); return results; } for (var i = 0; i < writes.Count; i++) { var w = writes[i]; if (!_resolver.TryResolve(w.FullReference, out var tag)) { results[i] = new WriteResult(StatusBadNodeIdUnknown); continue; } if (!tag.Writable) { results[i] = new WriteResult(StatusBadNotWritable); continue; } // Timer/Counter write guard: an equipment tag authored writable=true (S7 mapper // honours the "writable" key, and node-level auth governs writes) whose address is a // Timer/Counter would bypass the !Writable gate above and reach EncodeScalarBlock, // which throws NotSupportedException → BadNotSupported. The docs say Timer/Counter // writes return BadNotWritable. Detect the area here before the call so it // consistently returns BadNotWritable (init guard-d also rejects a writable // Timer/Counter, but the mapper doesn't run that guard). // TryParse (not Parse) so a malformed address falls through to the existing // error path rather than throwing here. if (ParsedByRawPath.TryGetValue(tag.Name, out var tcParsed) ? tcParsed.Area is S7Area.Timer or S7Area.Counter : (S7AddressParser.TryParse(tag.Address, out tcParsed) && tcParsed.Area is S7Area.Timer or S7Area.Counter)) { results[i] = new WriteResult(StatusBadNotWritable); continue; } // Fail the rest of the batch fast once a write marked the handle dead (R07:P1): the // next call reopens; this batch must not serialise one deadline per remaining write. if (_plcDead) { results[i] = new WriteResult(StatusBadCommunicationError); continue; } try { await WriteOneAsync(plc, tag, w.Value, cancellationToken).ConfigureAwait(false); results[i] = new WriteResult(0u); outcome.RecordSuccess(); } catch (OperationCanceledException) { // Cancellation observed mid-PDU abandons a half-written ISO-on-TCP request on // the single gated stream — the handle must be reopened, not reused. // Mark dead (we hold _gate) and propagate: the caller cancelled, nobody consumes // the batch, and Release() still runs in finally. Marking is unconditional on // OCE — a false positive costs one cheap reopen versus permanent desync. _plcDead = true; throw; } catch (NotSupportedException) { results[i] = new WriteResult(StatusBadNotSupported); } catch (S7ValueRangeException) { // Value unrepresentable in the S7 type (string over its declared max, DATE < 1990…): // refused with nothing sent — a client error, no health impact. results[i] = new WriteResult(StatusBadOutOfRange); } catch (S7WriteValueException) { // Client-supplied value of the wrong shape — not a device or comms fault. results[i] = new WriteResult(StatusBadTypeMismatch); } catch (Exception ex) when (IsAccessDenied(ex)) { // PUT/GET-disabled / access-protection on write — same permanent // configuration fault as on read. BadNotSupported + // a config-alert health state, not a transient device failure. results[i] = new WriteResult(StatusBadNotSupported); // An answer (see the read ladder): advances LastSuccessfulRead. RecordAnswered sets // AnyAnswered only, so the sticky _writeFault still clears only on a real success. outcome.RecordAnswered(); outcome.RecordFailure(DriverState.Faulted, "S7 access denied — enable PUT/GET communication in TIA Portal " + $"(Protection & Security) for this CPU. PLC reported: {ex.Message}"); } catch (Exception ex) when (IsRefusal(ex)) { // The CPU answered and refused the item — per-tag Bad, once-per-tag Warning, no // Degraded, and it counts as answered (R07:H4). results[i] = new WriteResult(StatusBadDeviceFailure); outcome.RecordAnswered(); WarnRefusalOnce(tag.Name, "write", ex); } catch (PlcException pex) { // Genuine device-layer fault — degrade health so a PLC-down-during-writes // scenario is visible to the operator (previously health was never updated // on write failure). A connection-fatal PlcException also marks the handle // dead so the next call reopens. MarkConnectionDeadIfFatal(pex); results[i] = new WriteResult(StatusBadDeviceFailure); outcome.RecordFailure(DriverState.Degraded, pex.Message); } catch (Exception ex) { // Socket/timeout/conversion failure. Map to BadCommunicationError (not // BadInternalError) for transport faults; degrade health, and mark the handle // dead when it's a connection loss. MarkConnectionDeadIfFatal(ex); results[i] = new WriteResult(StatusBadCommunicationError); outcome.RecordFailure(DriverState.Degraded, ex.Message); } } } finally { // THE single health write of the batch (a finally, so an OCE mid-batch still flushes the // evidence gathered so far — a pass that observed nothing writes nothing). ApplyWritePassHealth(gen, outcome); _gate.Release(); } return results; } /// /// Publishes one write batch's verdict: worst state wins over every outcome the /// batch recorded, so a Faulted access-denied item is not erased by a later Degraded or /// successful sibling. Maintains , the sticky Faulted a read pass /// must not erase. Caller holds . /// /// The lifecycle generation the batch ran in; a superseded batch writes nothing. /// The batch's accumulated outcomes. private void ApplyWritePassHealth(long gen, WritePassOutcome outcome) { if (!outcome.HasObservations || !IsCurrentGeneration(gen)) return; var worst = outcome.WorstFailure; var priorWriteFault = _writeFault; if (worst == DriverState.Faulted) _writeFault = (DriverState.Faulted, outcome.WorstError!); else if (outcome.AnySuccess) _writeFault = null; // a write got through — the protection fault is gone var answeredAt = outcome.AnyAnswered ? UtcNow() : (DateTime?)null; if (worst == DriverState.Healthy) { // Clean batch (successes and/or refusals): the CPU answered, so LastSuccessfulRead // advances, and a non-Healthy state the WRITE side owns is retired — a Faulted only by a // real success (a refusal does not prove PUT/GET is enabled), a write-side comms Degraded // by any answer. A state the read side owns (its own message) is the read pass's to clear. var ownedFault = outcome.AnySuccess && _writeFault is null ? priorWriteFault?.Message : null; var ownedDegraded = _writeOwnedError; _writeOwnedError = null; TryUpdateHealth(gen, h => { var lsr = answeredAt ?? h.LastSuccessfulRead; if ((h.State == DriverState.Faulted && ownedFault is not null && h.LastError == ownedFault) || (h.State == DriverState.Degraded && ownedDegraded is not null && h.LastError == ownedDegraded)) return new DriverHealth(DriverState.Healthy, lsr, null); return lsr == h.LastSuccessfulRead ? null : h with { LastSuccessfulRead = lsr }; }); return; } var state = worst; var error = outcome.WorstError; // A Degraded-only batch must not downgrade a still-sticky Faulted. if (_writeFault is { } wf && ReadPassOutcome.Rank(wf.State) > ReadPassOutcome.Rank(state)) { state = wf.State; error = wf.Message; } if (state == DriverState.Degraded) _writeOwnedError = error; TryUpdateHealth(gen, h => new DriverHealth(state, answeredAt ?? h.LastSuccessfulRead, error)); } /// /// The outcomes ONE batch observed — the write-side sibling of /// (same worst-state-wins ranking and severity-pinned message), /// accumulated so the batch writes once instead of per item. /// private sealed class WritePassOutcome { private readonly ReadPassOutcome _inner = new(); /// True once any item in the batch wrote successfully. public bool AnySuccess => _inner.AnySuccess; /// The worst failure recorded; Healthy means none. public DriverState WorstFailure => _inner.WorstFailure; /// The message explaining . public string? WorstError => _inner.WorstError; /// True once the batch observed a success, a refusal or a failure. public bool HasObservations => _inner.HasObservations || AnyAnswered; /// True once the CPU answered any item (a success or a refusal) — proof of a live device. public bool AnyAnswered { get; private set; } /// Records one successful write. public void RecordSuccess() { _inner.RecordSuccess(); AnyAnswered = true; } /// Records a write the CPU answered by refusing it: not a success, not a failure. public void RecordAnswered() => AnyAnswered = true; /// Records one failed write. /// The state the failure would have stamped alone. /// The operator-facing message. public void RecordFailure(DriverState state, string message) => _inner.RecordFailure(state, message); } private async Task WriteOneAsync(IS7Plc plc, S7TagDefinition tag, object? value, CancellationToken ct) { // Parse the address the same way ReadOneAsync does: every tag pre-parses at init // (ParsedByRawPath), with an on-demand parse as a defensive fallback. Needed here so the // wide-type write can byte-address the block (the narrow path below addresses by the raw // address string instead). var addr = ParsedByRawPath.TryGetValue(tag.Name, out var parsed) ? parsed : S7AddressParser.Parse(tag.Address); // Array path: ONE contiguous WriteBytesAsync of count × element-bytes — the inverse // of ReadArrayAsync. Bool / wide-type arrays throw NotSupportedException (→ BadNotSupported); // a wrong-shaped value throws S7WriteValueException (→ BadTypeMismatch, no health impact). if (tag.ArrayCount is >= 1) { var arrayBytes = EncodeArrayBlock(tag, addr, value); await plc.WriteBytesAsync(ToS7NetArea(addr.Area), addr.DbNumber, addr.ByteOffset, arrayBytes, ct) .ConfigureAwait(false); return; } // Wide/structured scalar path: encode the value to a big-endian byte block and write it // at the start byte via S7.Net's buffer-based WriteBytesAsync. Mirrors the read seam; // the narrow string-based write below stays unchanged for 1/2/4-byte types. if (IsBufferType(tag, addr)) { await WriteScalarBlockAsync(plc, tag, addr, value, ct).ConfigureAwait(false); return; } // S7.Net's Plc.WriteAsync(string address, object value) expects the boxed value to // match the address's size-suffix type: DBX=bool, DBB=byte, DBW=ushort, DBD=uint. // Our S7DataType lets the caller pass short/int/float; convert to the unsigned // wire representation before handing off. var boxed = BoxValueForWrite(tag.DataType, value); await plc.WriteAsync(tag.Address, boxed, ct).ConfigureAwait(false); } /// /// Pure encode loop — the inverse of : turns the caller's array /// into the contiguous big-endian block for a single WriteBytesAsync. No network I/O. /// Accepts any non-string (OPC UA hands the server /// a typed array, but a boxed object[] is equally fine); each element is coerced with /// Convert.To* like the scalar path. /// /// Tag definition carrying the element type and declared array length. /// Parsed address carrying the access . /// The array to encode; must hold exactly ArrayCount elements. /// The big-endian block, count × element-bytes long. /// Bool or wide-type element arrays. /// The value is not an array, has the wrong length, or an /// element does not convert to the element type. internal static byte[] EncodeArrayBlock(S7TagDefinition tag, S7ParsedAddress addr, object? value) { var count = tag.ArrayCount!.Value; switch (tag.DataType, addr.Size) { case (S7DataType.Bool, _): throw new NotSupportedException( $"S7 Bool array writes are not supported (tag '{tag.Name}'): a byte-granular write would clobber neighbouring bits."); case (S7DataType.Int64, _): case (S7DataType.UInt64, _): case (S7DataType.Float64, _): case (S7DataType.String, _): case (S7DataType.DateTime, _): case (S7DataType.WString, _): case (S7DataType.Char, _): case (S7DataType.WChar, _): case (S7DataType.Dtl, _): case (S7DataType.Date, _): case (S7DataType.Tod, _): case (S7DataType.Time, _): case (S7DataType.S5Time, _): throw new NotSupportedException($"S7 array writes of {tag.DataType} are not supported (tag '{tag.Name}')."); case (S7DataType.Byte, S7Size.Byte): case (S7DataType.UInt16, S7Size.Word): case (S7DataType.Int16, S7Size.Word): case (S7DataType.UInt32, S7Size.DWord): case (S7DataType.Int32, S7Size.DWord): case (S7DataType.Float32, S7Size.DWord): break; default: throw new System.IO.InvalidDataException( $"S7 array Write type-mismatch: tag '{tag.Name}' declared {tag.DataType} but address " + $"'{tag.Address}' parsed as Size={addr.Size}"); } if (value is string || value is not System.Collections.IEnumerable items) throw new S7WriteValueException($"S7 array tag '{tag.Name}' requires an array value."); var elements = new List(count); foreach (var e in items) elements.Add(e); // Convert.ToXxx(null) is 0 — a null element must not silently write zero to the PLC. if (elements.Contains(null)) throw new S7WriteValueException($"S7 array tag '{tag.Name}': an element is null."); if (elements.Count != count) throw new S7WriteValueException( $"S7 array tag '{tag.Name}' has {count} elements but the write supplied {elements.Count}."); var elementBytes = ElementByteSize(addr.Size); var block = new byte[count * elementBytes]; try { for (var i = 0; i < count; i++) { var span = block.AsSpan(i * elementBytes, elementBytes); var element = elements[i]; switch (tag.DataType) { case S7DataType.Byte: span[0] = Convert.ToByte(element); break; case S7DataType.UInt16: System.Buffers.Binary.BinaryPrimitives.WriteUInt16BigEndian(span, Convert.ToUInt16(element)); break; case S7DataType.Int16: System.Buffers.Binary.BinaryPrimitives.WriteInt16BigEndian(span, Convert.ToInt16(element)); break; case S7DataType.UInt32: System.Buffers.Binary.BinaryPrimitives.WriteUInt32BigEndian(span, Convert.ToUInt32(element)); break; case S7DataType.Int32: System.Buffers.Binary.BinaryPrimitives.WriteInt32BigEndian(span, Convert.ToInt32(element)); break; case S7DataType.Float32: System.Buffers.Binary.BinaryPrimitives.WriteSingleBigEndian(span, Convert.ToSingle(element)); break; } } } catch (Exception ex) when (ex is FormatException or InvalidCastException or OverflowException) { throw new S7WriteValueException( $"S7 array tag '{tag.Name}': an element does not convert to {tag.DataType} ({ex.Message})."); } return block; } /// /// A caller-supplied write value the driver cannot encode (wrong shape / length / element /// type). A client error — maps to BadTypeMismatch and does not touch driver health. /// internal sealed class S7WriteValueException(string message) : Exception(message); /// /// Writes a wide/structured scalar as ONE contiguous byte block via S7.Net's /// buffer-based Plc.WriteBytesAsync(DataType, db, startByteAdr, byte[] value, ct). /// The pure produces the big-endian bytes; this method /// owns only the network I/O (mirrors ). /// private async Task WriteScalarBlockAsync(IS7Plc plc, S7TagDefinition tag, S7ParsedAddress addr, object? value, CancellationToken ct) { var bytes = EncodeScalarBlock(tag, value); await plc.WriteBytesAsync(ToS7NetArea(addr.Area), addr.DbNumber, addr.ByteOffset, bytes, ct) .ConfigureAwait(false); } /// /// Pure boxing step — converts the caller's value into the unsigned wire type that /// S7.Net's Plc.WriteAsync expects for each address size (bool → bool, byte /// → byte, short → ushort, int → uint, float → uint-bits). No network I/O. /// Factored out of so it can be exercised in unit tests /// without a live PLC. /// /// Target S7 data type. /// Value to box. /// The boxed value in the wire type expected by S7.Net. internal static object BoxValueForWrite(S7DataType dataType, object? value) => dataType switch { S7DataType.Bool => (object)Convert.ToBoolean(value), S7DataType.Byte => (object)Convert.ToByte(value), S7DataType.UInt16 => (object)Convert.ToUInt16(value), S7DataType.Int16 => (object)unchecked((ushort)Convert.ToInt16(value)), S7DataType.UInt32 => (object)Convert.ToUInt32(value), S7DataType.Int32 => (object)unchecked((uint)Convert.ToInt32(value)), S7DataType.Float32 => (object)BitConverter.SingleToUInt32Bits(Convert.ToSingle(value)), // Unreachable defensive backstop — every wide type routes through the byte-buffer write // path (IsBufferType → WriteScalarBlockAsync → EncodeScalarBlock) before BoxValueForWrite // is consulted. Kept (not deleted) so a mis-route fails loudly rather than mis-encoding. S7DataType.Int64 => throw new NotSupportedException("S7 Int64 is unreachable here — wide types route through the byte-buffer path (EncodeScalarBlock)"), S7DataType.UInt64 => throw new NotSupportedException("S7 UInt64 is unreachable here — wide types route through the byte-buffer path (EncodeScalarBlock)"), S7DataType.Float64 => throw new NotSupportedException("S7 Float64 (LReal) is unreachable here — wide types route through the byte-buffer path (EncodeScalarBlock)"), S7DataType.String => throw new NotSupportedException("S7 STRING is unreachable here — wide types route through the byte-buffer path (EncodeScalarBlock)"), S7DataType.DateTime => throw new NotSupportedException("S7 DateTime is unreachable here — wide types route through the byte-buffer path (EncodeScalarBlock)"), S7DataType.WString or S7DataType.Char or S7DataType.WChar or S7DataType.Dtl or S7DataType.Date or S7DataType.Tod or S7DataType.Time or S7DataType.S5Time => throw new NotSupportedException($"S7 {dataType} is unreachable here — wide types route through the byte-buffer path (EncodeScalarBlock)"), _ => throw new InvalidOperationException($"Unknown S7DataType {dataType}"), }; private void RequireInitialized() { if (!_initialized) throw new InvalidOperationException("S7Driver not initialized"); } /// /// Returns a live S7 connection, lazily disposing a dead handle and re-opening a fresh one /// when the previous connection dropped (the reconnect path). The fast path returns the /// current when it is still connected and not marked dead; otherwise it /// builds + opens a new connection via with the same /// timeout-linked CTS the initial connect uses. /// /// /// MUST be called while holding — it mutates / /// and reuses the single-connection-per-PLC invariant the gate /// enforces. The read / write / probe paths all take the gate before calling it. /// /// While the PLC is down every data call and probe tick would pay a full connect attempt /// bounded only by _options.Timeout. This method is the single /// choke-point all S7 reconnects flow through (already gate-serialized), so the /// connect-attempt throttle lives here: the shared /// primitive is consulted with ShouldAttempt(now) at the top of the slow path — /// inside the window the call fails fast with no connect attempt, which every caller /// already degrades on — with RecordFailure/RecordSuccess around the connect. /// A successful connect clears the window, so recovery is never delayed past the first /// attempt that finds the PLC back; the 30 s cap bounds the worst case. /// /// /// Cancellation token for the (re)connect attempt. /// A live . private async Task EnsureConnectedAsync(CancellationToken ct) { // Fast path — the current connection is live and not flagged dead. if (!_plcDead && Plc is { IsConnected: true } live) return live; // Dispose the stale / dead handle before making a fresh one (exactly once, here). if (Plc is not null) { try { Plc.Dispose(); } catch { /* best-effort */ } Plc = null; } _plcDead = false; // Inside the backoff window fail fast WITHOUT a connect attempt. A plain // InvalidOperationException (not an OCE) so the read/write/probe catch ladders degrade on it. if (!_connectBackoff.ShouldAttempt(BackoffClock())) throw new InvalidOperationException( $"S7 reconnect to {_options.Host}:{_options.Port} suppressed — backing off after a failed connect attempt."); var plc = _plcFactory.Create(_options); try { using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct); cts.CancelAfter(_options.Timeout); await plc.OpenAsync(cts.Token).ConfigureAwait(false); } catch (OperationCanceledException) when (!ct.IsCancellationRequested) { _connectBackoff.RecordFailure(BackoffClock()); // The linked CancelAfter fired — a connect TIMEOUT, not a caller cancellation. // Surface it as a connection FAILURE (TimeoutException) so callers route it through // their degrade paths: an escaping OCE reads as teardown and permanently killed the // subscription poll loops (the unreachable-host regression). try { plc.Dispose(); } catch { /* best-effort */ } throw new TimeoutException( $"S7 connect to {_options.Host}:{_options.Port} timed out after " + $"{(int)_options.Timeout.TotalMilliseconds} ms."); } catch (Exception ex) { // Caller cancellation is teardown, not a dead PLC — it must not open a window. if (!(ex is OperationCanceledException && ct.IsCancellationRequested)) _connectBackoff.RecordFailure(BackoffClock()); try { plc.Dispose(); } catch { /* best-effort */ } throw; } _connectBackoff.RecordSuccess(); Plc = plc; Volatile.Write(ref _negotiatedPduSize, plc.MaxPduSize); _logger.LogInformation("S7Driver reconnected. Driver={DriverInstanceId} Host={Host} CPU={CpuType} PduSize={PduSize}", _driverInstanceId, _options.Host, _options.CpuType, _negotiatedPduSize); return plc; } /// /// Flags the current connection dead when is a connection-level loss, /// so the next reopens. A no-op for data-address / type /// faults — those don't warrant tearing down a healthy socket. /// /// The exception observed on a read / write. private void MarkConnectionDeadIfFatal(Exception ex) { if (IsS7ConnectionFatal(ex)) _plcDead = true; } /// /// The result stamped, without any I/O, on an item a pass skipped because an earlier item had /// already marked the connection dead (R07:P1). The pass's health already carries the failure /// that marked it. /// /// The pass timestamp. /// A BadCommunicationError snapshot. private static DataValueSnapshot DeadHandleSnapshot(DateTime now) => new(null, StatusBadCommunicationError, null, now); /// /// The TRANSPORT subset of : a socket / IO / disposed handle / /// blown deadline / anywhere in the chain. Excludes the /// framing class, because S7.Net reports a multi-var request with one refused item as /// PlcException(ReadData, PlcException(WrongNumberReceivedBytes)) (live-probed on the snap7 /// fixture) over a perfectly healthy stream — the multi-var path falls back per tag for that /// shape, and a genuine desync still surfaces on the per-tag reads. /// /// The exception to classify. /// for a transport loss. private static bool IsS7TransportLoss(Exception ex) { for (Exception? e = ex; e is not null; e = e.InnerException) { if (e is System.Net.Sockets.SocketException or System.IO.IOException or ObjectDisposedException or TimeoutException) return true; if (e is PlcException { ErrorCode: ErrorCode.ConnectionError }) return true; } return false; } /// /// True when (or any inner exception) is a socket-level / connection /// loss OR an ISO-on-TCP framing/desync fault that a reopen can repair — a /// / / /// ; a from a wire op that /// blew its wall-clock ceiling (an unresponsive but still /// TCP-established peer — the READ-leg sibling of the connect-timeout fix); an S7.Net framing violation /// ( / / /// ); or a carrying /// or . /// A framing violation means the single serialized stream's position is untrustworthy — a /// half-read PDU left by a timeout/cancellation makes every later response mis-frame, so only /// a reopen recovers (the Modbus desync mode, rebuilt in S7). /// /// Deliberately NOT : the driver's own decode /// backstop ( / ) throws /// it for a declared-type/address-size CONFIG mismatch on a HEALTHY socket — classifying /// it would churn a full reopen on every read of a mis-authored tag. A genuinely desynced /// stream's very next PDU still lands in TPKT/TPDU/WrongNumber territory, which now tears /// down, so a real desync self-heals within one extra failed call. /// /// A data-address / type error (S7.Net's / /// for a bad address, PUT/GET-denied, etc.) is deliberately /// NOT treated as fatal — reopening wouldn't help and would churn a healthy connection. /// /// The exception to classify. /// true when a reconnect is warranted. private static bool IsS7ConnectionFatal(Exception ex) { for (Exception? e = ex; e is not null; e = e.InnerException) { if (e is System.Net.Sockets.SocketException or System.IO.IOException or ObjectDisposedException) return true; // A wire op that blew its wall-clock deadline (S7OperationDeadline — the async read/write // ceiling S7.Net's ignored socket ReadTimeout/WriteTimeout can't provide) means the // connection is unresponsive: discard + reopen. This is the READ-leg sibling of the // connect-timeout fix — without it a frozen-but-established peer wedges the // poll loop forever instead of surfacing Bad + reconnecting. if (e is TimeoutException) return true; // ISO-on-TCP framing/desync surface: the stream position is untrustworthy — // a half-read PDU left by a timeout/cancellation makes every later response mis-frame. // NOTE: deliberately NOT System.IO.InvalidDataException — ReinterpretRawValue throws it // for a declared-type/address-size CONFIG mismatch on a healthy socket. if (e is TPKTInvalidException or TPDUInvalidException or WrongNumberOfBytesException) return true; if (e is PlcException { ErrorCode: ErrorCode.ConnectionError or ErrorCode.WrongNumberReceivedBytes }) return true; } return false; } /// /// True when is a deterministic PLC REFUSAL of the item: the CPU answered /// with an S7 item error (object does not exist, address out of range, data type inconsistent / /// not supported, hardware fault, or an unknown status), or S7.Net raised a /// / over a response it could /// not use. Excludes the access-denied refusal (its own sticky Faulted config alert) and /// anything carrying a socket / timeout / framing / cancellation fault in its chain — those /// wrap a transport failure, not an answer. /// /// /// Live-probed against the snap7 fixture (2026-10-22): S7.Net's READ paths /// (ReadAsync(string), ReadBytesAsync) raise the item error as a BARE /// — "Received error from PLC: Object does not exist." — not wrapped in /// a ; its write paths wrap whatever they hit in a /// PlcException(WriteData). Both shapes are matched. /// /// The exception raised by S7.Net. /// when the CPU answered and refused. internal static bool IsRefusal(Exception ex) { if (IsAccessDenied(ex) || IsS7ConnectionFatal(ex) || HasCancellationInChain(ex)) return false; if (ex is PlcException { ErrorCode: ErrorCode.ReadData or ErrorCode.WriteData }) return true; for (Exception? e = ex; e is not null; e = e.InnerException) if (IsS7ItemError(e)) return true; return false; } /// /// True for the bare S7.Net's response-code validator raises for an S7 /// item error ("Received error from PLC: …" / "Invalid response from PLC: statusCode=…"). /// Exact type only: a derived exception carrying similar words is not S7.Net's validator. /// /// One exception of a chain. /// for the validator's item-error shape. private static bool IsS7ItemError(Exception e) => e.GetType() == typeof(Exception) && (e.Message.StartsWith("Received error from PLC", StringComparison.Ordinal) || e.Message.StartsWith("Invalid response from PLC", StringComparison.Ordinal)); /// True when a cancellation is buried in the exception chain (a half-read PDU, not a refusal). /// The exception to inspect. /// when any inner exception is an . private static bool HasCancellationInChain(Exception ex) { for (var e = ex.InnerException; e is not null; e = e.InnerException) if (e is OperationCanceledException) return true; return false; } /// Logs a refusal once per tag per generation. /// The refused tag. /// "read" or "write". /// The refusal. private void WarnRefusalOnce(string tagName, string operation, Exception ex) { if (!_refusalWarned.TryAdd(tagName, 0)) return; _logger.LogWarning( "S7 CPU refused the {Operation} of tag {Tag} ({Reason}); it reads Bad until the tag or the PLC program is fixed. " + "Driver health is unaffected. Further refusals of this tag are not logged. Driver={DriverInstanceId}", operation, tagName, ex.InnerException?.Message ?? ex.Message, _driverInstanceId); } /// /// Detects an S7 PUT/GET-disabled / access-protection fault. S7.Net's response-code validator /// throws a plain for the S7 AccessingObjectNotAllowed status — /// bare on the read paths, wrapped in a () /// on the write paths. There is no typed error code for it, so the message is the only /// discriminator S7.Net exposes. The top-level exception must be S7.Net-shaped (a /// or the validator's bare item error), so an unrelated exception that /// happens to say "not allowed" is not mistaken for it. /// /// The exception raised by S7.Net. /// when the PLC refused access to the object. internal static bool IsAccessDenied(Exception ex) { if (ex is not PlcException && !IsS7ItemError(ex)) return false; // A transport fault wins over any wording in the chain: a socket error whose text happens to // contain the phrase must reopen (Degraded), not latch a sticky config alert. if (IsS7ConnectionFatal(ex) || HasCancellationInChain(ex)) return false; for (Exception? e = ex; e is not null; e = e.InnerException) { // S7.Net's exact wording for the S7 AccessingObjectNotAllowed status — not the loose "not // allowed", which any unrelated exception text can contain. if (e.Message.Contains("Accessing object not allowed", StringComparison.OrdinalIgnoreCase)) { return true; } } return false; } // ---- ITagDiscovery ---- /// // Run-once: DiscoverAsync emits the complete node set synchronously from the configured tag // table in a single pass — nothing fills in asynchronously after connect, so a single // discovery pass is sufficient. public DiscoveryRediscoverPolicy RediscoverPolicy => DiscoveryRediscoverPolicy.Once; /// public Task DiscoverAsync(IAddressSpaceBuilder builder, CancellationToken cancellationToken) { ArgumentNullException.ThrowIfNull(builder); var folder = builder.Folder("S7", "S7"); foreach (var t in TagsByRawPath.Values) { // A tag carrying a non-null array count (>= 1) surfaces as a 1-D OPC UA array node. // A null count stays scalar. A count of 1 IS a valid 1-element array: the foundation // materialises a [1] OPC UA array node when isArray:true, so the driver must agree. var isArray = t.ArrayCount is >= 1; folder.Variable(t.Name, t.Name, new DriverAttributeInfo( FullName: t.Name, DriverDataType: MapDataType(t.DataType), IsArray: isArray, ArrayDim: isArray ? (uint)t.ArrayCount!.Value : null, SecurityClass: t.Writable ? SecurityClassification.Operate : SecurityClassification.ViewOnly, IsHistorized: false, IsAlarm: false, WriteIdempotent: t.WriteIdempotent)); } return Task.CompletedTask; } private static DriverDataType MapDataType(S7DataType t) => t switch { S7DataType.Bool => DriverDataType.Boolean, S7DataType.Byte => DriverDataType.Int32, // no 8-bit in DriverDataType yet // UInt32 values > int.MaxValue (2^31-1) wrap negative when surfaced as // Int32. That residual lossy note now applies ONLY to UInt32 — Int64/UInt64 map to // their own DriverDataType members below (Phase 4d), so they are no longer lossy. S7DataType.Int16 or S7DataType.UInt16 or S7DataType.Int32 or S7DataType.UInt32 => DriverDataType.Int32, S7DataType.Int64 => DriverDataType.Int64, S7DataType.UInt64 => DriverDataType.UInt64, S7DataType.Float32 => DriverDataType.Float32, S7DataType.Float64 => DriverDataType.Float64, S7DataType.String or S7DataType.WString or S7DataType.Char or S7DataType.WChar => DriverDataType.String, S7DataType.DateTime or S7DataType.Dtl or S7DataType.Date => DriverDataType.DateTime, // TOD / TIME / S5TIME surface as Int32 milliseconds (the default arm; named for the reader). S7DataType.Tod or S7DataType.Time or S7DataType.S5Time => DriverDataType.Int32, _ => DriverDataType.Int32, }; // ---- ISubscribable (polling overlay) ---- /// public Task SubscribeAsync( IReadOnlyList fullReferences, TimeSpan publishingInterval, CancellationToken cancellationToken) => Task.FromResult(_poll.Subscribe(fullReferences, publishingInterval)); /// public async Task UnsubscribeAsync(ISubscriptionHandle handle, CancellationToken cancellationToken) { // Async teardown: the engine drains the in-flight poll without blocking the caller's // thread — this runs inside a DriverInstanceActor mailbox turn. await _poll.UnsubscribeAsync(handle).ConfigureAwait(false); } /// /// Routes a poll-loop reader failure (surfaced by the shared /// 's onError sink) to the driver health surface: logs it and /// degrades to preserving LastSuccessfulRead. Never /// downgrades a state (e.g. PUT/GET-denied set by ReadAsync) /// — Faulted is the stronger, permanent-config signal. Replaces the retired fork's /// HandlePollFailure; the engine now owns the consecutive-failure count + backoff. /// /// The exception caught by the poll engine. private void HandlePollError(Exception ex) { // A retained poll that ran into a teardown / re-initialize IN PROGRESS ("not initialized" while a // lifecycle operation holds _lifecycleGate) belongs to no live generation: that operation owns // health, and writing Degraded over its Initializing (or its final Unknown) would break the "old // work never overwrites newer health" rule. A poll against a driver nobody is initializing (a // subscribe before init, a failed init) still surfaces Degraded (Driver.S7-009). if (!_initialized && _lifecycleGate.CurrentCount == 0) { _logger.LogDebug(ex, "S7 poll reader failed during a lifecycle operation; no health write. Driver={DriverInstanceId}", _driverInstanceId); return; } _logger.LogWarning(ex, "S7 poll reader failed. Driver={DriverInstanceId}", _driverInstanceId); TryUpdateHealth(CurrentGeneration, h => h.State == DriverState.Faulted ? null : new DriverHealth(DriverState.Degraded, h.LastSuccessfulRead, ex.Message)); } // ---- IHostConnectivityProbe ---- /// /// Host identifier surfaced in . host:port format /// matches the Modbus driver's convention so the Admin UI dashboard renders both /// family's rows uniformly. /// public string HostName => $"{_options.Host}:{_options.Port}"; /// public IReadOnlyList GetHostStatuses() { lock (_probeLock) return [new HostConnectivityStatus(HostName, _hostState, _hostStateChangedUtc)]; } private async Task ProbeLoopAsync(CancellationToken ct) { while (!ct.IsCancellationRequested) { // Running / Stopped, or null for "no verdict this tick" — which leaves the host state alone. HostState? verdict = null; try { // Probe via S7.Net's low-cost GetCpuStatus — returns the CPU state (Run/Stop) // and is intentionally light on the comms mailbox. Single-word Plc.ReadAsync // would also work but GetCpuStatus doubles as a "PLC actually up" check. // // Gate CONTENTION is not a verdict (R07:H7): a read pass or write batch holding the // gate past the probe deadline is the connection being USED, and that pass reports // its own outcome through health. Reporting the host Stopped for it flapped /hosts on // every long pass against a perfectly healthy PLC. if (!await _gate.WaitAsync(_options.Probe.Timeout, ct).ConfigureAwait(false)) { Interlocked.Increment(ref _probeGateContentions); } else { try { // A tick that raced a teardown / re-initialize has nothing to probe and must // not reopen a connection on a driver that is not initialized. if (_initialized) verdict = await ProbeOnceAsync(ct).ConfigureAwait(false); } finally { _gate.Release(); } } } catch (OperationCanceledException) when (ct.IsCancellationRequested) { return; } catch { verdict = HostState.Stopped; /* any other probe fault */ } if (verdict is { } state) TransitionTo(state); try { await Task.Delay(_options.Probe.Interval, ct).ConfigureAwait(false); } catch (OperationCanceledException) { return; } } } /// /// One probe round trip. Caller holds . Returns the verdict; rethrows only /// loop teardown. /// /// The probe loop's token. /// or . private async Task ProbeOnceAsync(CancellationToken ct) { try { // EnsureConnectedAsync doubles as the reconnect backstop: if a read/write marked the handle // dead (or the socket dropped between ticks), the probe reopens it here so recovery doesn't // wait for the next data call. It runs on the LOOP token, not the (shorter) probe deadline: // the connect is bounded by _options.Timeout inside, and a timeout there must count as a // failure so the backoff window opens — cutting it with the probe deadline looked like a // caller cancel, recorded nothing, and let a black-holed host cost a connect attempt every // probe tick. var plc = await EnsureConnectedAsync(ct).ConfigureAwait(false); // The probe deadline bounds only the CPU-status round trip. using var probeCts = CancellationTokenSource.CreateLinkedTokenSource(ct); probeCts.CancelAfter(_options.Probe.Timeout); await plc.ReadStatusAsync(probeCts.Token).ConfigureAwait(false); return HostState.Running; } catch (OperationCanceledException) when (ct.IsCancellationRequested) { throw; // loop teardown — the caller's finally releases the gate } catch (OperationCanceledException) { // Probe deadline fired mid-PDU: the CPU-status response may still be in flight, so the // handle can't be reused (half-read ⇒ desync). The caller holds _gate, keeping _plcDead // gate-guarded. _plcDead = true; return HostState.Stopped; } catch (Exception ex) { // Classify + mark while holding _gate so a wire-dead/desynced handle whose TcpClient still // claims Connected is reopened by the NEXT tick's EnsureConnectedAsync instead of being // re-probed forever. MarkConnectionDeadIfFatal(ex); return HostState.Stopped; } } /// Probe ticks that found the gate held past the probe deadline and gave no verdict. private int _probeGateContentions; /// Count of probe ticks skipped for gate contention. Internal so a test can wait on it. internal int ProbeGateContentions => Volatile.Read(ref _probeGateContentions); private void TransitionTo(HostState newState) { HostState old; lock (_probeLock) { old = _hostState; if (old == newState) return; _hostState = newState; _hostStateChangedUtc = DateTime.UtcNow; } _logger.LogInformation("S7 probe transition. Driver={DriverInstanceId} Host={Host} {OldState} → {NewState}", _driverInstanceId, HostName, old, newState); OnHostStatusChanged?.Invoke(this, new HostStatusChangedEventArgs(HostName, old, newState)); } /// Disposes the driver and releases resources. public void Dispose() { // Avoid the sync-over-async DisposeAsync().AsTask().GetAwaiter().GetResult() // pattern (a known deadlock surface even when currently safe here). ShutdownAsync's // body is effectively synchronous apart from waiting on probe/poll Tasks; do the same // teardown directly, blocking only on the drain — and only with a bounded timeout so // a wedged loop can't hang Dispose() indefinitely. if (_disposed) return; _disposed = true; SynchronousTeardown(); // _gate / _lifecycleGate are deliberately NOT disposed: a Dispose can race a still-running // ShutdownAsync (the runtime disposes right after a bounded shutdown), which would then throw // ObjectDisposedException mid-teardown. A SemaphoreSlim whose wait handle was never requested // holds no unmanaged resource. } /// Asynchronously disposes the driver and releases resources. /// A task representing the asynchronous operation. public async ValueTask DisposeAsync() { if (_disposed) return; _disposed = true; // Safe while a ShutdownAsync is still running: it waits (bounded) for the lifecycle gate, and // the teardown is idempotent. The semaphores are not disposed (see Dispose). try { await ShutdownAsync(CancellationToken.None).ConfigureAwait(false); } catch { /* disposal is best-effort */ } } /// /// Synchronous teardown — mirrors but blocks (with a bounded /// timeout) on the probe + poll Tasks instead of awaiting them. Used by the sync /// path so we don't sync-over-async . /// private void SynchronousTeardown() { // Its own lifecycle generation, like ShutdownCoreAsync: an initialize still running past this // point discards what it built instead of publishing it over the torn-down driver. var gen = BeginGeneration(); // Drain the polling overlay (drain-before-dispose). try { _poll.DisposeAsync().AsTask().Wait(DrainTimeout); } catch { /* timeouts/loop faults are tolerated — teardown continues */ } var probeCts = _probeCts; var probeTask = _probeTask; try { probeCts?.Cancel(); } catch { } if (probeTask is not null) { try { probeTask.Wait(DrainTimeout); } catch { /* timeouts/loop faults are tolerated — teardown continues */ } } probeCts?.Dispose(); _probeCts = null; _probeTask = null; _initialized = false; _plcDead = false; _writeFault = null; _writeOwnedError = null; _connectBackoff.RecordSuccess(); try { Plc?.Dispose(); } catch { /* best-effort — tearing down anyway */ } Plc = null; Volatile.Write(ref _negotiatedPduSize, 0); // a stale post-teardown reading would read as "online" TryUpdateHealth(gen, h => new DriverHealth(DriverState.Unknown, h.LastSuccessfulRead, null)); } }