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