feat(arrays): Modbus String[]/BitInRegister[] array writes reachable; table follows the resolver

The Modbus lane (#741 U3) gave the driver String[] and BitInRegister[] holding-register array encoders, and
moved address resolution to ModbusTagAddressResolution (keys first, a bit region coerced to Bool, strict key
reads), but DriverArrayWriteSupport still listed both array shapes read-only (follow-up F1), so a client
write was BadNotWritable before it reached the driver.

Modbus row now mirrors the driver end to end:
- Keys shape only (region + address both present). A string-only addressString tag is resolved by the
  driver with its own family through a parser Core.Abstractions cannot reference, so it stays read-only
  (pinned: the conservative direction).
- Strict reads as the resolver: address an integer 0-65535; a present region / dataType / byteOrder /
  stringByteOrder string must name a member.
- Coils: any dataType (coerced to Bool), <= 1968 coils (FC15).
- HoldingRegisters (FC16, never Bool): numeric, String ((stringLength+1)/2 registers, stringLength >= 1),
  BitInRegister (1 register, bitIndex 0-15, span ending <= 65535), all within maxRegistersPerWrite.
  FC23 is opt-in and never changes the answer.
- Elements convert (ScadaBridge int[] -> Int16 stays writable); only a String / DateTime node over a
  numeric or bit element is left out, since such an element never converts.

Tests: the parity test's PendingF1 exemption and its guard are gone; the parity matrix is now region x
element type x node type against the real WriteAsync with a spec-conformant device (FC15 > 1968 refused),
plus shape edges at every cap boundary (numeric, String, BitInRegister, coil), strict key reads, FC23
on/off, string-only, the ScadaBridge int[] shape and U3 wire bytes. Core.Abstractions row tests and a
composer test (String[] and BitInRegister[] writable; over-cap, no-stringLength and string-only read-only).
Docs: table XML doc, Uns.md, modbus-addressing.md, drivers/Modbus.md, data-plane rules.

Refs #741

Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
This commit is contained in:
Joseph Doherty
2026-10-22 17:10:00 -04:00
parent 92dea29547
commit 5533de6281
8 changed files with 597 additions and 130 deletions
+5 -4
View File
@@ -323,7 +323,7 @@ carried on the plan records (`RawTagPlan.ArrayWritable`, mirrored onto every UNS
| Driver | Array writes | Element types |
|---|---|---|
| **Modbus** | Yes | `region: Coils` (FC15, any element, ≤ 1968 coils); `region: HoldingRegisters` with `Int16`/`UInt16`/`Bcd16`/`Int32`/`UInt32`/`Bcd32`/`Float32`/`Int64`/`UInt64`/`Float64` (FC16) whose `arrayLength × registers-per-element` fits `maxRegistersPerWrite` (default 123; the smallest value set on the driver or the tag's device wins) — the driver refuses rather than splits an over-cap FC16, so e.g. a 62-element `Int32` array (124 registers) stays read-only. Not BitInRegister / String / Bool-in-register; input regions are read-only |
| **Modbus** | Yes (String / BitInRegister arrays since #741) | Tags addressed by `region` + `address` keys (strict reads: an integer address 0–65535, enum strings that name a member). `region: Coils` (FC15, ≤ 1968 coils) with **any** `dataType` — a bit region is coerced to Bool, never refused. `region: HoldingRegisters` (FC16) with a fixed-width numeric type (`Int16`/`UInt16`/`Bcd16`/`Int32`/`UInt32`/`Bcd32`/`Float32`/`Int64`/`UInt64`/`Float64`), `String` (`(stringLength+1)/2` registers per element, `stringLength >= 1`) or `BitInRegister` (one register per element, read-modify-written in one FC03 + one FC16, `bitIndex` 0–15, span ending at or before register 65535), whose `arrayLength × registers-per-element` fits `maxRegistersPerWrite` (default 123; the smallest value set on the driver or the tag's device wins) — the driver refuses rather than splits an over-cap FC16, so e.g. a 62-element `Int32` array (124 registers) stays read-only. FC23 (opt-in) never changes the answer. Not Bool-in-register; input regions are read-only. A **string-only** tag (`addressString`, no keys) stays read-only: the driver resolves it with its own family, which the composer cannot know — use the editor's Resolve to pin the keys |
| **S7** | Yes | `Byte`/`Int16`/`UInt16`/`Int32`/`UInt32`/`Float32` (one contiguous block). Not `Bool` (would clobber neighbouring bits) nor the wide / String / DateTime types |
| **OpcUaClient** | Yes | All — forwarded upstream unchanged; the upstream server decides (shape included) |
| **Galaxy** | Yes | OPC UA `Boolean`/`Int32`/`Int64`/`Float`/`Double`/`String`/`DateTime` (the `MxValueEncoder` array variants) — **only with a declared `arrayLength`**: an undeclared length materialises an unbounded node, and a short whole-array write would *resize* the Galaxy attribute (mxaccessgw contract), so such a node stays read-only |
@@ -340,9 +340,10 @@ stays read-only.
**Elements convert; they are not exact-matched.** ScadaBridge writes CLR `int[]` / `List<int>` to Int16
nodes: the node manager converts a numeric array to the node's element type, and the AB CIP, AB Legacy
and TwinCAT encoders convert each element again to the controller's type (an element that does not fit
is `BadOutOfRange`). Those rows therefore do not key on an exact node `DataType`; they leave out only
node types whose elements never convert — a `DateTime` or `String` node over a numeric element, and a
`Boolean` node on AB Legacy. An array tag deployed read-only before its driver gained an encoder turns
is `BadOutOfRange`), as does Modbus to the register / coil type. Those rows therefore do not key on an
exact node `DataType`; they leave out only node types whose elements never convert — a `DateTime` or
`String` node over a numeric element (on Modbus, over a numeric or bit element; a Modbus `String`
element takes any node type), and a `Boolean` node on AB Legacy. An array tag deployed read-only before its driver gained an encoder turns
writable on the next deploy (a surgical `ArrayWritable` update, no rebuild).
Each "Yes" row is pinned against the driver's real encoder by a parity test in that driver's
+8 -4
View File
@@ -138,11 +138,15 @@ numeric, String, and BitInRegister array reads.
**Live-verify** — Mac-verifiable against the simulator at `10.100.0.35:5020` (no fixture
bring-up required; the sim is always-on on the shared Docker host).
**Array writes** (#610) — a whole-array write goes out as one FC15 (coils) or one FC16 (numeric
holding registers); the driver refuses rather than splits an FC16 longer than `maxRegistersPerWrite`
(default 123). The server mirrors that: an array tag is client-writable only when
**Array writes** (#610, #741) — a whole-array write goes out as one FC15 (coils) or one FC16
(holding registers: numeric, `String` at `(stringLength+1)/2` registers per element, and
`BitInRegister` as one FC03 + one FC16 read-modify-write of the span); the driver refuses rather than
splits an FC16 longer than `maxRegistersPerWrite` (default 123). The server mirrors that: an array tag
is client-writable only when it is addressed by `region` + `address` keys and
`arrayLength × registers-per-element` fits the cap (and a coil array ≤ 1968), else its node stays
read-only — see [Uns.md §Array writes](../Uns.md#array-writes-610), including the upgrade note.
read-only. A string-only (`addressString`) array stays read-only, because the composer cannot resolve
it under the driver's family — see [Uns.md §Array writes](../Uns.md#array-writes-610) and
[modbus-addressing.md §Array writes](../v2/modbus-addressing.md#array-writes-610-741).
**Deferrals** — multi-dimensional arrays (`arrayLength` is always 1-D); per-element historization.
+35
View File
@@ -89,6 +89,13 @@ For 8-byte values (Int64 / Float64) the same labels apply pairwise.
`40001:F:5` = `Float32[5]` (consumes HR[0..9]). Array + bit suffix is
rejected. Strings are not arrays.
An array written through the grammar string alone (a **string-only** tag —
`addressString` with no `region`/`address` keys) is served and written by the
driver, but its OPC UA node stays **read-only**: whether a write fits is
decided at compose time, where the driver's family is not known. Pin the keys
(the editor's "Resolve with driver family") to make the array writable — see
"Array writes" below.
### Composition
The 3-field shorthand `40001:F:5` is parsed as `(type=F, count=5)` because
@@ -279,3 +286,31 @@ than asking users to rewrite spreadsheets.
`BitInRegister`).
- Exception 01/02/03 are device refusals: per-tag Bad, one Warning per tag,
no driver Degraded; reads and writes share one comms-fault health slot.
## Array writes (#610, #741)
Whether an array node is client-writable is decided by
`DriverArrayWriteSupport` (Core.Abstractions) at compose time, and it says yes
only for what `ModbusDriver.WriteAsync` encodes end to end
(`ModbusArrayWriteSupportParityTests` pins the two against each other):
- **Keys only.** The tag must carry `region` + `address` (read as strictly as
the driver reads them). A string-only tag stays read-only — the composer
cannot resolve the grammar under the driver's family.
- **Coils:** one FC15 of at most 1968 coils (the spec ceiling; the driver does
not chunk). Any `dataType` — a bit region is coerced to Bool.
- **HoldingRegisters:** one FC16 whose register count fits
`maxRegistersPerWrite` (default 123; the smallest value on the driver or the
tag's device wins). Registers per element: 1 / 2 / 4 for the numeric types,
`(stringLength+1)/2` for `String` (each element nul-padded to that width), 1
for `BitInRegister` (the span is read with one FC03, the addressed bit of each
register is set or cleared, and the span is written back with one FC16 —
the other 15 bits are preserved; `bitIndex` 0–15, the span must end at or
before register 65535). FC23 (`useFC23ForMultiRegisterWrites`) is opt-in,
capped at 121 registers and falls back to FC16 above that, so it never
changes which arrays are writable.
- **Never writable:** DiscreteInputs / InputRegisters, Bool in a register
region, a `String` with no `stringLength`, a `bitIndex` above 15, a missing
or zero `arrayLength`, and a `String` / `DateTime` node over a numeric or bit
element (such an element never converts). Elements otherwise convert, so a
ScadaBridge `int[]` to an `Int16` node is writable.