feat(modbus): wire Family / MelsecSubFamily / DisableFC23, and the form's timing keys

U1: a tag's addressString (Modicon / mnemonic / DL205 V-memory / MELSEC D-X-Y grammar) now resolves through ModbusAddressParser with the DRIVER's Family and MelsecSubFamily at every initialize and is authoritative; the family-unaware gates (deploy Inspect, AdminUI parse consult) accept what some family resolves. The tag editor gets an address-text field that resolves with the owning driver's family and persists both the string and the resolved region/offset/type fields; a hand edit drops the string. DisableFC23 now gates FC23: by default a 2..121-register holding write is one FC23 write + read-back (a unit answering exception 01, or failing FC23 at the transport, moves to FC16 for the rest of the generation); RTU framing deframes the FC23 reply. Live-checked: the pymodbus fixture implements FC23. Also: the AdminUI driver form serialises ModbusDriverOptions (TimeSpan strings), which the factory DTO never read - every timing field on the form was dead. The DTO now accepts both shapes (*Ms keys win). Refs #741 Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
2026-10-22 15:35:58 -04:00
parent 1adc9d65e1
commit 4a3d7a9361
13 changed files with 656 additions and 58 deletions
@@ -89,10 +89,13 @@ public sealed class ModbusDriverOptions
    public bool UseFC16ForSingleRegisterWrites { get; init; } = false;

    /// <summary>
-    ///     <b>Reserved / no-op</b> kill-switch for FC23 (Read/Write Multiple Registers). The
-    ///     driver does not currently emit FC23 — toggling this option has no observable effect
-    ///     today. The slot exists so a future block-read-coalescing enhancement that opts into
-    ///     FC23 can be disabled per-deployment without a code change. Default <c>false</c>.
+    ///     Kill-switch for FC23 (Read/Write Multiple Registers). By default a multi-register holding
+    ///     write (2–121 registers: 32/64-bit values, arrays, strings) is sent as ONE FC23 that writes
+    ///     the block and reads the same block back, so the device confirms what it now holds. A unit
+    ///     that answers FC23 with exception 01 (MELSEC QJ71MT91, S7 Modbus servers) is moved to FC16
+    ///     automatically, for that write and every later one; one that fails FC23 at the transport is
+    ///     moved too (that one write is reported as a comms failure). Set <c>true</c> to always use
+    ///     FC16. Default <c>false</c>.
    /// </summary>
    public bool DisableFC23 { get; init; } = false;

@@ -128,10 +131,11 @@ public sealed class ModbusDriverOptions
    public bool DisableReadCoalescing { get; init; } = false;

    /// <summary>
-    ///     PLC family hint that drives the parser's family-native branch. When set to a
-    ///     non-Generic value, address strings using that family's native syntax (DL205 V2000 /
-    ///     MELSEC D100) parse to the right region + offset directly. Defaults to
-    ///     <see cref="ModbusFamily.Generic"/> = Modicon-only behaviour preserved by default.
+    ///     PLC family hint that drives the parser's family-native branch. A tag authored with an
+    ///     <c>addressString</c> is resolved with this family at every initialize, so with a non-Generic
+    ///     value that family's native syntax (DL205 V2000 octal / MELSEC D100) parses to the right
+    ///     region + offset. Defaults to <see cref="ModbusFamily.Generic"/> (Modicon / mnemonic grammar).
+    ///     Tags authored by region + numeric address are unaffected.
    /// </summary>
    public ModbusFamily Family { get; init; } = ModbusFamily.Generic;

@@ -32,6 +32,24 @@ public static class ModbusTagDefinitionFactory
    /// <param name="def">The mapped definition when this returns <see langword="true"/>.</param>
    /// <returns><see langword="true"/> when <paramref name="tagConfig"/> is a valid Modbus address object.</returns>
    public static bool FromTagConfig(string tagConfig, string rawPath, out ModbusTagDefinition def)
+        => FromTagConfig(tagConfig, rawPath, ModbusFamily.Generic, MelsecFamily.Q_L_iQR, out def);
+
+    /// <summary>
+    ///     Family-aware overload: an <c>addressString</c> key (the Modicon / mnemonic / family-native grammar
+    ///     of <see cref="ModbusAddressParser"/> — <c>40001:F:CDAB</c>, DL205 <c>V2000</c>, MELSEC <c>D100</c>)
+    ///     is resolved with the DRIVER's <paramref name="family"/> / <paramref name="melsecSubFamily"/> and is
+    ///     authoritative for region, offset, type, bit, string length, byte order and array count; the
+    ///     editor also persists the resolved <c>region</c> / <c>address</c> keys beside it for display and for
+    ///     readers that predate it. Without an <c>addressString</c> this is exactly the 3-argument overload.
+    /// </summary>
+    /// <param name="tagConfig">The authored equipment-tag TagConfig JSON.</param>
+    /// <param name="rawPath">The tag's RawPath — becomes the definition's identity (<c>Name</c>).</param>
+    /// <param name="family">The driver's PLC family (from its <c>DriverConfig</c>).</param>
+    /// <param name="melsecSubFamily">The driver's MELSEC sub-family; consulted only for MELSEC.</param>
+    /// <param name="def">The mapped definition when this returns <see langword="true"/>.</param>
+    /// <returns><see langword="true"/> when <paramref name="tagConfig"/> is a valid Modbus address object.</returns>
+    public static bool FromTagConfig(string tagConfig, string rawPath, ModbusFamily family, MelsecFamily melsecSubFamily,
+        out ModbusTagDefinition def)
    {
        def = null!;
        if (string.IsNullOrWhiteSpace(tagConfig)) return false;
@@ -39,28 +57,60 @@ public static class ModbusTagDefinitionFactory
        {
            using var doc = JsonDocument.Parse(tagConfig);
            var root = doc.RootElement;
-            if (root.ValueKind != JsonValueKind.Object
-                || !root.TryGetProperty("region", out _)
-                || !root.TryGetProperty("address", out var addr))
-                return false;
-            if (addr.ValueKind != JsonValueKind.Number
-                || !addr.TryGetInt32(out var address)
-                || address < 0 || address > ushort.MaxValue)
-                return false;
-            // Strict enum reads: a present-but-invalid (typo'd) enum rejects the tag
-            // (→ BadNodeIdUnknown) instead of silently defaulting to a wrong-width Good.
-            if (!TagConfigJson.TryReadEnumStrict(root, "region", ModbusRegion.HoldingRegisters, out var region)) return false;
-            // An absent dataType defaults per region: a bit region (Coils / DiscreteInputs) only carries
-            // Bool, so defaulting it to Int16 would reject every bit tag authored without the key.
-            if (!TagConfigJson.TryReadEnumStrict(root, "dataType", DefaultDataType(region), out var dataType)) return false;
+            if (root.ValueKind != JsonValueKind.Object) return false;
+
+            ModbusRegion region;
+            int address;
+            ModbusDataType dataType;
+            ModbusByteOrder byteOrder;
+            byte bitIndex;
+            ushort stringLength;
+            int? arrayCount;
+            var addressText = ReadAddressString(root, out var addressStringInvalid);
+            if (addressStringInvalid) return false;
+            if (addressText is not null)
+            {
+                if (!ModbusAddressParser.TryParse(addressText, family, melsecSubFamily, out var parsed, out _) || parsed is null)
+                    return false;
+                region = parsed.Region;
+                address = parsed.Offset;
+                dataType = parsed.DataType;
+                byteOrder = parsed.ByteOrder;
+                bitIndex = parsed.Bit ?? 0;
+                stringLength = parsed.StringLength;
+                arrayCount = parsed.ArrayCount;
+            }
+            else
+            {
+                if (!root.TryGetProperty("region", out _) || !root.TryGetProperty("address", out var addr))
+                    return false;
+                if (addr.ValueKind != JsonValueKind.Number
+                    || !addr.TryGetInt32(out address)
+                    || address < 0 || address > ushort.MaxValue)
+                    return false;
+                // Strict enum reads: a present-but-invalid (typo'd) enum rejects the tag
+                // (→ BadNodeIdUnknown) instead of silently defaulting to a wrong-width Good.
+                if (!TagConfigJson.TryReadEnumStrict(root, "region", ModbusRegion.HoldingRegisters, out region)) return false;
+                // An absent dataType defaults per region: a bit region (Coils / DiscreteInputs) only carries
+                // Bool, so defaulting it to Int16 would reject every bit tag authored without the key.
+                if (!TagConfigJson.TryReadEnumStrict(root, "dataType", DefaultDataType(region), out dataType)) return false;
+                if (!TagConfigJson.TryReadEnumStrict(root, "byteOrder", ModbusByteOrder.BigEndian, out byteOrder)) return false;
+                bitIndex = (byte)ReadInt(root, "bitIndex");
+                stringLength = (ushort)ReadInt(root, "stringLength");
+                // isArray / arrayLength — optional keys authored by the typed Modbus tag editor.
+                // Canonical rule: a tag is an array iff isArray:true AND arrayLength >= 1.
+                // isArray:false (with any arrayLength) is scalar — the foundation materialises a
+                // scalar OPC UA node, so returning an array value would cause a shape mismatch.
+                // A 1-element array (isArray:true, arrayLength:1) IS valid and reads as short[1].
+                var isArray = ReadBool(root, "isArray");
+                var arrayLength = ReadInt(root, "arrayLength");
+                arrayCount = (isArray && arrayLength >= 1) ? arrayLength : null;
+            }
            // Region/type compatibility: a bit region carries only Bool, a register region never Bool.
            // A mismatch used to throw out of the coalescing planner (killing every tag's poll) or
            // silently return a bool into an Int32 node.
            if (!IsRegionTypeCompatible(region, dataType)) return false;
-            if (!TagConfigJson.TryReadEnumStrict(root, "byteOrder", ModbusByteOrder.BigEndian, out var byteOrder)) return false;
            if (!TagConfigJson.TryReadEnumStrict(root, "stringByteOrder", ModbusStringByteOrder.HighByteFirst, out var stringByteOrder)) return false;
-            var bitIndex = (byte)ReadInt(root, "bitIndex");
-            var stringLength = (ushort)ReadInt(root, "stringLength");
            // Guard: String tags require StringLength >= 1. RegisterCount = (StringLength+1)/2,
            // so StringLength=0 → 0 registers → spec-illegal FC03/FC04 with quantity=0 → PLC
            // returns exception 03. Reject here so the driver surfaces BadNodeIdUnknown rather
@@ -69,14 +119,6 @@ public static class ModbusTagDefinitionFactory
            // Guard: BitInRegister tags require BitIndex 0–15. Shift by ≥ 16 on an int overflows
            // a ushort mask silently — reads always return false, writes have no effect.
            if (dataType == ModbusDataType.BitInRegister && bitIndex > 15) return false;
-            // isArray / arrayLength — optional keys authored by the typed Modbus tag editor.
-            // Canonical rule: a tag is an array iff isArray:true AND arrayLength >= 1.
-            // isArray:false (with any arrayLength) is scalar — the foundation materialises a
-            // scalar OPC UA node, so returning an array value would cause a shape mismatch.
-            // A 1-element array (isArray:true, arrayLength:1) IS valid and reads as short[1].
-            var isArray = ReadBool(root, "isArray");
-            var arrayLength = ReadInt(root, "arrayLength");
-            int? arrayCount = (isArray && arrayLength >= 1) ? arrayLength : null;
            // "writable" defaults to true when absent (today's value) — makes read-only equipment tags
            // authorable. Node-level authz remains the effective write gate.
            var writable = TagConfigJson.ReadWritable(root);
@@ -100,6 +142,42 @@ public static class ModbusTagDefinitionFactory
        catch (InvalidOperationException) { return false; }
    }

+    /// <summary>
+    ///     Family-unaware acceptance, for the gates that do not know the owning driver's family (the deploy
+    ///     gate's <see cref="Inspect"/>, CSV import, the AdminUI parse consult): accepts a blob SOME family
+    ///     resolves, so the gate is never stricter than the driver it guards. Blobs without an
+    ///     <c>addressString</c> behave exactly like <see cref="FromTagConfig(string,string,out ModbusTagDefinition)"/>.
+    /// </summary>
+    /// <param name="tagConfig">The authored equipment-tag TagConfig JSON.</param>
+    /// <param name="rawPath">The tag's RawPath.</param>
+    /// <param name="def">The definition under the first family that resolves it.</param>
+    /// <returns><see langword="true"/> when any family's driver would serve the tag.</returns>
+    public static bool FromTagConfigAnyFamily(string tagConfig, string rawPath, out ModbusTagDefinition def)
+    {
+        foreach (var (family, sub) in AllFamilies)
+            if (FromTagConfig(tagConfig, rawPath, family, sub, out def)) return true;
+        def = null!;
+        return false;
+    }
+
+    private static readonly (ModbusFamily Family, MelsecFamily Sub)[] AllFamilies =
+    [
+        (ModbusFamily.Generic, MelsecFamily.Q_L_iQR),
+        (ModbusFamily.DL205, MelsecFamily.Q_L_iQR),
+        (ModbusFamily.MELSEC, MelsecFamily.Q_L_iQR),
+        (ModbusFamily.MELSEC, MelsecFamily.F_iQF),
+    ];
+
+    /// <summary>Reads the optional <c>addressString</c>: null when absent or blank; flags a non-string value.</summary>
+    private static string? ReadAddressString(JsonElement root, out bool invalid)
+    {
+        invalid = false;
+        if (!root.TryGetProperty("addressString", out var e) || e.ValueKind == JsonValueKind.Null) return null;
+        if (e.ValueKind != JsonValueKind.String) { invalid = true; return null; }
+        var text = e.GetString();
+        return string.IsNullOrWhiteSpace(text) ? null : text.Trim();
+    }
+
    /// <summary>The data type an authored tag gets when its <c>dataType</c> key is absent.</summary>
    /// <param name="region">The tag's region.</param>
    /// <returns><c>Bool</c> for Coils / DiscreteInputs, <c>Int16</c> for the register regions.</returns>
@@ -194,7 +272,7 @@ public static class ModbusTagDefinitionFactory

        // The accept gate: whatever the driver reads draws nothing. See the remarks. The RAW reference is
        // handed to the mapper — the driver reads the stored blob, not a trimmed copy of it.
-        if (FromTagConfig(reference, InspectionRawPath, out _)) return warnings;
+        if (FromTagConfigAnyFamily(reference, InspectionRawPath, out _)) return warnings;

        try
        {
@@ -235,6 +313,24 @@ public static class ModbusTagDefinitionFactory
    /// <param name="warnings">The list to append warnings to.</param>
    private static void DescribeRejection(JsonElement root, List<string> warnings)
    {
+        var addressText = ReadAddressString(root, out var addressStringInvalid);
+        if (addressStringInvalid)
+        {
+            warnings.Add("Modbus TagConfig 'addressString' is not a string — the tag will not resolve (BadNodeIdUnknown).");
+            return;
+        }
+        if (addressText is not null)
+        {
+            // The addressString is authoritative; the other address keys are not read at all.
+            if (!ModbusAddressParser.TryParse(addressText, out _, out var error))
+                warnings.Add($"Modbus 'addressString' '{addressText}' does not parse under any PLC family ({error}) — "
+                             + "the tag will not resolve (BadNodeIdUnknown).");
+            else
+                warnings.Add($"Modbus 'addressString' '{addressText}' resolves to an unusable tag (check its type against "
+                             + "the region) — the tag will not resolve (BadNodeIdUnknown).");
+            return;
+        }
+
        if (!root.TryGetProperty("region", out _))
        {
            warnings.Add(
@@ -533,7 +533,7 @@ public sealed class ModbusDriver
            _skippedTags.BeginRebuild(_options.RawTags.Count);
            foreach (var entry in _options.RawTags)
            {
-                if (ModbusTagDefinitionFactory.FromTagConfig(entry.TagConfig, entry.RawPath, out var def))
+                if (ModbusTagDefinitionFactory.FromTagConfig(entry.TagConfig, entry.RawPath, _options.Family, _options.MelsecSubFamily, out var def))
                    table[entry.RawPath] = def with { WriteIdempotent = entry.WriteIdempotent };
                else
                {
@@ -556,6 +556,7 @@ public sealed class ModbusDriver
                _transport = transport;
                Volatile.Write(ref _tagsByRawPath, table);
                Volatile.Write(ref _refusalWarned, new ConcurrentDictionary<string, byte>(StringComparer.Ordinal));
+                Volatile.Write(ref _fc23Unsupported, new ConcurrentDictionary<byte, byte>());
                WriteHealth(new DriverHealth(DriverState.Healthy, DateTime.UtcNow, null));

                // PR 23: kick off the probe loop once the transport is up. Initial state stays
@@ -1619,6 +1620,7 @@ public sealed class ModbusDriver
                        throw new ModbusWriteRefusedException(StatusBadOutOfRange,
                            $"Write of {qty} registers to {tag.Name} exceeds MaxRegistersPerWrite={writeCap}. " +
                            $"Split the tag (e.g. shorter StringLength or smaller ArrayCount) — partial FC16 chunks would lose atomicity.");
+                    if (await TryWriteViaFc23Async(transport, tag, bytes, qty, ct).ConfigureAwait(false)) return;
                    var pdu = new byte[6 + 1 + bytes.Length];
                    pdu[0] = 0x10;
                    pdu[1] = (byte)(tag.Address >> 8); pdu[2] = (byte)(tag.Address & 0xFF);
@@ -1634,6 +1636,79 @@ public sealed class ModbusDriver
        }
    }

+    /// <summary>FC23's spec ceiling on the write quantity (0x79); larger multi-register writes use FC16.</summary>
+    private const ushort Fc23MaxWriteRegisters = 121;
+
+    /// <summary>
+    ///     Units that refused FC23 (exception 01) or failed it at the transport; their multi-register writes
+    ///     use FC16 for the rest of this driver generation. Replaced (never cleared in place) on re-init.
+    /// </summary>
+    private ConcurrentDictionary<byte, byte> _fc23Unsupported = new();
+
+    /// <summary>
+    ///     Multi-register write via FC23 (Read/Write Multiple Registers): the device writes the block and
+    ///     returns the SAME block read back in one transaction, so the write is confirmed by the device's own
+    ///     post-write registers. Gated by <see cref="ModbusDriverOptions.DisableFC23"/>. A device that does
+    ///     not implement FC23 (MELSEC QJ71MT91, S7 Modbus servers — exception 01) falls back to FC16 for this
+    ///     write and every later one on that unit, which is safe because an Illegal Function wrote nothing.
+    ///     A transport failure on FC23 is reported (its outcome is unknown, so it is not retried as FC16) and
+    ///     also moves the unit to FC16, so a gateway that cannot frame FC23 costs one failed write, not all.
+    ///     A read-back that differs from what was written (PLC logic overwrote it in the same scan, or the
+    ///     device clamped it) is logged once per tag; the write itself was accepted.
+    /// </summary>
+    /// <returns><see langword="true"/> when FC23 performed the write; <see langword="false"/> to use FC16.</returns>
+    private async Task<bool> TryWriteViaFc23Async(
+        IModbusTransport transport, ModbusTagDefinition tag, byte[] bytes, ushort qty, CancellationToken ct)
+    {
+        var unit = ResolveUnitId(tag);
+        var unsupported = Volatile.Read(ref _fc23Unsupported);
+        // Only genuinely multi-register writes: a single register forced onto FC16 (UseFC16ForSingleRegisterWrites)
+        // stays on the function code the operator named.
+        if (_options.DisableFC23 || qty < 2 || qty > Fc23MaxWriteRegisters || unsupported.ContainsKey(unit)) return false;
+
+        var pdu = new byte[10 + 1 + bytes.Length];
+        pdu[0] = 0x17;
+        pdu[1] = (byte)(tag.Address >> 8); pdu[2] = (byte)(tag.Address & 0xFF); // read start
+        pdu[3] = (byte)(qty >> 8); pdu[4] = (byte)(qty & 0xFF);                 // read quantity
+        pdu[5] = (byte)(tag.Address >> 8); pdu[6] = (byte)(tag.Address & 0xFF); // write start
+        pdu[7] = (byte)(qty >> 8); pdu[8] = (byte)(qty & 0xFF);                 // write quantity
+        pdu[9] = (byte)bytes.Length;
+        Buffer.BlockCopy(bytes, 0, pdu, 10, bytes.Length);
+
+        byte[] resp;
+        try
+        {
+            resp = await transport.SendAsync(unit, pdu, ct).ConfigureAwait(false);
+        }
+        catch (ModbusException mex) when (mex.ExceptionCode == 0x01)
+        {
+            if (unsupported.TryAdd(unit, 0))
+                _logger.LogInformation(
+                    "Modbus unit {Unit} does not implement FC23 (Illegal Function); multi-register writes use FC16. Driver={DriverInstanceId}",
+                    unit, _driverInstanceId);
+            return false;
+        }
+        catch (Exception ex) when (ex is not ModbusException && !(ex is OperationCanceledException && ct.IsCancellationRequested))
+        {
+            if (unsupported.TryAdd(unit, 0))
+                _logger.LogWarning(ex,
+                    "Modbus FC23 write to unit {Unit} failed at the transport; later multi-register writes to it use FC16. Driver={DriverInstanceId}",
+                    unit, _driverInstanceId);
+            throw;
+        }
+
+        // resp = [0x17][byteCount][read-back registers…]
+        if (resp.Length < 2 || resp[1] != bytes.Length || resp.Length < 2 + resp[1])
+            throw new InvalidDataException(
+                $"Modbus FC23 response for {tag.Name} malformed: expected {bytes.Length} read-back bytes, got {(resp.Length < 2 ? -1 : resp[1])}");
+        if (!resp.AsSpan(2, bytes.Length).SequenceEqual(bytes)
+            && Volatile.Read(ref _refusalWarned).TryAdd("fc23:" + tag.Name, 0))
+            _logger.LogWarning(
+                "Modbus FC23 read-back of {RawPath} differs from the value written (device logic or clamping changed it); the write was accepted. Driver={DriverInstanceId}",
+                tag.Name, _driverInstanceId);
+        return true;
+    }
+
    /// <summary>
    ///     Encode an array-typed write value into a contiguous byte block by encoding each
    ///     element with the scalar codec. Caller submits IList / Array of the element CLR type.
@@ -78,7 +78,7 @@ public static class ModbusDriverFactoryExtensions
            Host = dto.Host!,
            Port = dto.Port ?? 502,
            UnitId = dto.UnitId ?? 1,
-            Timeout = TimeSpan.FromMilliseconds(dto.TimeoutMs ?? 2_000),
+            Timeout = Span(dto.TimeoutMs, dto.Timeout) ?? TimeSpan.FromSeconds(2),
            MaxRegistersPerRead = dto.MaxRegistersPerRead ?? 125,
            MaxRegistersPerWrite = dto.MaxRegistersPerWrite ?? 123,
            MaxCoilsPerRead = dto.MaxCoilsPerRead ?? 2000,
@@ -94,7 +94,7 @@ public static class ModbusDriverFactoryExtensions
                : ParseEnum<MelsecFamily>(dto.MelsecSubFamily, "<driver-level>", driverInstanceId, "MelsecSubFamily"),
            Transport = dto.Transport is null ? ModbusTransportMode.Tcp
                : ParseEnum<ModbusTransportMode>(dto.Transport, "<driver-level>", driverInstanceId, "Transport"),
-            AutoProhibitReprobeInterval = dto.AutoProhibitReprobeMs is { } reprobeMs ? TimeSpan.FromMilliseconds(reprobeMs) : null,
+            AutoProhibitReprobeInterval = Span(dto.AutoProhibitReprobeMs, dto.AutoProhibitReprobeInterval),
            AutoReconnect = dto.AutoReconnect ?? true,
            // v3: the deploy artifact (Wave C) populates rawTags with the cluster's authored raw Modbus
            // tags. The driver maps each RawTagEntry's TagConfig blob through ModbusTagDefinitionFactory
@@ -104,22 +104,22 @@ public static class ModbusDriverFactoryExtensions
            Probe = new ModbusProbeOptions
            {
                Enabled = dto.Probe?.Enabled ?? true,
-                Interval = TimeSpan.FromMilliseconds(dto.Probe?.IntervalMs ?? 5_000),
-                Timeout = TimeSpan.FromMilliseconds(dto.Probe?.TimeoutMs ?? 2_000),
+                Interval = Span(dto.Probe?.IntervalMs, dto.Probe?.Interval) ?? TimeSpan.FromSeconds(5),
+                Timeout = Span(dto.Probe?.TimeoutMs, dto.Probe?.Timeout) ?? TimeSpan.FromSeconds(2),
                ProbeAddress = dto.Probe?.ProbeAddress ?? 0,
            },
            KeepAlive = dto.KeepAlive is null ? new ModbusKeepAliveOptions() : new ModbusKeepAliveOptions
            {
                Enabled = dto.KeepAlive.Enabled ?? true,
-                Time = TimeSpan.FromMilliseconds(dto.KeepAlive.TimeMs ?? 30_000),
-                Interval = TimeSpan.FromMilliseconds(dto.KeepAlive.IntervalMs ?? 10_000),
+                Time = Span(dto.KeepAlive.TimeMs, dto.KeepAlive.Time) ?? TimeSpan.FromSeconds(30),
+                Interval = Span(dto.KeepAlive.IntervalMs, dto.KeepAlive.Interval) ?? TimeSpan.FromSeconds(10),
                RetryCount = dto.KeepAlive.RetryCount ?? 3,
            },
-            IdleDisconnectTimeout = dto.IdleDisconnectMs is { } ms ? TimeSpan.FromMilliseconds(ms) : null,
+            IdleDisconnectTimeout = Span(dto.IdleDisconnectMs, dto.IdleDisconnectTimeout),
            Reconnect = dto.Reconnect is null ? new ModbusReconnectOptions() : new ModbusReconnectOptions
            {
-                InitialDelay = TimeSpan.FromMilliseconds(dto.Reconnect.InitialDelayMs ?? 0),
-                MaxDelay = TimeSpan.FromMilliseconds(dto.Reconnect.MaxDelayMs ?? 30_000),
+                InitialDelay = Span(dto.Reconnect.InitialDelayMs, dto.Reconnect.InitialDelay) ?? TimeSpan.Zero,
+                MaxDelay = Span(dto.Reconnect.MaxDelayMs, dto.Reconnect.MaxDelay) ?? TimeSpan.FromSeconds(30),
                BackoffMultiplier = dto.Reconnect.BackoffMultiplier ?? 2.0,
            },
        };
@@ -127,6 +127,23 @@ public static class ModbusDriverFactoryExtensions
        return options;
    }

+    /// <summary>
+    ///     One timing knob, accepted in BOTH shapes the config can carry: the <c>*Ms</c> integer keys (CLI,
+    ///     seed data, hand-authored JSON) and the TimeSpan-string keys the AdminUI driver form emits — it
+    ///     serialises <see cref="ModbusDriverOptions"/> itself, so it writes <c>"timeout":"00:00:07"</c>, not
+    ///     <c>timeoutMs</c>. Before this every timing field on that form was silently ignored. The
+    ///     millisecond key wins when both are present; an unparseable TimeSpan string is ignored (the
+    ///     previous behaviour for these keys), never a reason to fail the driver.
+    /// </summary>
+    private static TimeSpan? Span(int? milliseconds, JsonElement? timeSpan)
+    {
+        if (milliseconds is { } ms) return TimeSpan.FromMilliseconds(ms);
+        if (timeSpan is { ValueKind: JsonValueKind.String } e
+            && TimeSpan.TryParse(e.GetString(), System.Globalization.CultureInfo.InvariantCulture, out var parsed))
+            return parsed;
+        return null;
+    }
+
    private static T ParseEnum<T>(string? raw, string? tagName, string driverInstanceId, string field) where T : struct, Enum
    {
        if (string.IsNullOrWhiteSpace(raw))
@@ -156,6 +173,8 @@ public static class ModbusDriverFactoryExtensions
        public byte? UnitId { get; init; }
        /// <summary>Gets or sets the timeout in milliseconds.</summary>
        public int? TimeoutMs { get; init; }
+        /// <summary>Gets or sets the timeout as a TimeSpan string (the AdminUI form's shape).</summary>
+        public JsonElement? Timeout { get; init; }
        /// <summary>Gets or sets the maximum number of registers per read operation.</summary>
        public ushort? MaxRegistersPerRead { get; init; }
        /// <summary>Gets or sets the maximum number of registers per write operation.</summary>
@@ -182,6 +201,8 @@ public static class ModbusDriverFactoryExtensions
        public string? Transport { get; init; }
        /// <summary>Gets or sets the automatic prohibition reprobei interval in milliseconds.</summary>
        public int? AutoProhibitReprobeMs { get; init; }
+        /// <summary>Gets or sets the re-probe interval as a TimeSpan string (the AdminUI form's shape).</summary>
+        public JsonElement? AutoProhibitReprobeInterval { get; init; }
        /// <summary>Gets or sets a value indicating whether automatic reconnection is enabled.</summary>
        public bool? AutoReconnect { get; init; }
        /// <summary>Gets or sets the authored raw tags (RawPath + TagConfig blob + WriteIdempotent) the
@@ -194,6 +215,8 @@ public static class ModbusDriverFactoryExtensions
        public ModbusKeepAliveDto? KeepAlive { get; init; }
        /// <summary>Gets or sets the idle disconnect timeout in milliseconds.</summary>
        public int? IdleDisconnectMs { get; init; }
+        /// <summary>Gets or sets the idle disconnect timeout as a TimeSpan string (the AdminUI form's shape).</summary>
+        public JsonElement? IdleDisconnectTimeout { get; init; }
        /// <summary>Gets or sets the reconnect configuration.</summary>
        public ModbusReconnectDto? Reconnect { get; init; }
    }
@@ -206,6 +229,10 @@ public static class ModbusDriverFactoryExtensions
        public int? TimeMs { get; init; }
        /// <summary>Gets or sets the keep-alive interval in milliseconds.</summary>
        public int? IntervalMs { get; init; }
+        /// <summary>Gets or sets the keep-alive time as a TimeSpan string (the AdminUI form's shape).</summary>
+        public JsonElement? Time { get; init; }
+        /// <summary>Gets or sets the keep-alive interval as a TimeSpan string (the AdminUI form's shape).</summary>
+        public JsonElement? Interval { get; init; }
        /// <summary>Gets or sets the retry count.</summary>
        public int? RetryCount { get; init; }
    }
@@ -216,6 +243,10 @@ public static class ModbusDriverFactoryExtensions
        public int? InitialDelayMs { get; init; }
        /// <summary>Gets or sets the maximum reconnect delay in milliseconds.</summary>
        public int? MaxDelayMs { get; init; }
+        /// <summary>Gets or sets the initial reconnect delay as a TimeSpan string (the AdminUI form's shape).</summary>
+        public JsonElement? InitialDelay { get; init; }
+        /// <summary>Gets or sets the maximum reconnect delay as a TimeSpan string (the AdminUI form's shape).</summary>
+        public JsonElement? MaxDelay { get; init; }
        /// <summary>Gets or sets the backoff multiplier for exponential reconnect delays.</summary>
        public double? BackoffMultiplier { get; init; }
    }
@@ -228,6 +259,10 @@ public static class ModbusDriverFactoryExtensions
        public int? IntervalMs { get; init; }
        /// <summary>Gets or sets the probe timeout in milliseconds.</summary>
        public int? TimeoutMs { get; init; }
+        /// <summary>Gets or sets the probe interval as a TimeSpan string (the AdminUI form's shape).</summary>
+        public JsonElement? Interval { get; init; }
+        /// <summary>Gets or sets the probe timeout as a TimeSpan string (the AdminUI form's shape).</summary>
+        public JsonElement? Timeout { get; init; }
        /// <summary>Gets or sets the probe register address.</summary>
        public ushort? ProbeAddress { get; init; }
    }
@@ -93,9 +93,10 @@ public static class ModbusRtuFraming
            // Exception frame: excCode(1) + CRC(2).
            trailing = 1 + 2;
        }
-        else if (fc is 0x01 or 0x02 or 0x03 or 0x04)
+        else if (fc is 0x01 or 0x02 or 0x03 or 0x04 or 0x17)
        {
-            // Read response: byteCount(1) then byteCount data bytes + CRC(2).
+            // Read response (and FC23 Read/Write Multiple, whose reply is a read): byteCount(1) then
+            // byteCount data bytes + CRC(2).
            var bc = new byte[1];
            await ReadExactlyAsync(stream, bc, ct).ConfigureAwait(false);
            var byteCount = bc[0];
@@ -105,9 +106,9 @@ public static class ModbusRtuFraming
        }
        else
        {
-            // Fixed 4-byte echo: correct for the write FCs this driver emits (05/06/0F/10). A future
-            // variable-length response FC outside 01-04 (e.g. FC23) would be mis-sized here and
-            // surface as a desync — revisit the FC-shape table if the driver starts emitting one.
+            // Fixed 4-byte echo: correct for the write FCs this driver emits (05/06/0F/10). FC23 is
+            // variable-length and handled above; any NEW variable-length response FC must be added there
+            // or it is mis-sized here and surfaces as a desync.
            trailing = 4 + 2;
        }