Phase 3 PR 57 -- S7 byte-order + fingerprint integration tests against s7_1500 pymodbus profile. Three facts in new S7_ByteOrderTests class: (1) S7_Float32_ABCD_decodes_1_5f_from_HR100 reads HR[100..101] with ModbusByteOrder.BigEndian AND with WordSwap on the same wire bytes; asserts BigEndian==1.5f AND WordSwap!=1.5f -- proving both that Siemens S7 stores Float32 in ABCD word order (opposite of DL260 CDAB) and that the ByteOrder flag is not a no-op on the same wire buffer. (2) S7_Int32_ABCD_decodes_0x12345678_from_HR300 reads HR[300]=0x1234 + HR[301]=0x5678 with BigEndian and asserts the reassembled Int32 = 0x12345678; documents the contrast with DL260 CDAB Int32 encoding. (3) S7_DB1_fingerprint_marker_at_HR0_reads_0xABCD reads HR[0]=0xABCD -- real MB_SERVER deployments reserve DB1.DBW0 as a fingerprint so clients can verify they're pointing at the right DB, protecting against typos in the MB_SERVER.MB_HOLD_REG.DB_number parameter. No driver code changes -- the ByteOrder.BigEndian path has existed since PR 24; this PR exists to lock in the S7-specific semantics at the integration level so future refactors of NormalizeWordOrder can't silently break S7. All 3 tests gate on MODBUS_SIM_PROFILE=s7_1500 so they skip cleanly against dl205 or standard profiles. Verified end-to-end: 4/4 S7 integration tests pass (1 smoke from PR 56 + 3 new). No regression in driver unit tests. Per the per-quirk-PR plan: the S7 quirks NOT testable via pymodbus sim (MB_SERVER STATUS 0x8383 optimized-DB behavior, port-per-connection semantics, CP 343-1 Lean license rejection, STOP-mode non-determinism) remain in docs/v2/s7.md as design guidance for driver users rather than automated tests -- they're TIA-Portal-side or CP-hardware-side behaviors that pymodbus cannot reproduce without custom Python actions.

_p54.json

@@ -0,0 +1 @@
+{"title":"Phase 3 PR 54 -- Siemens S7 Modbus TCP quirks research doc","body":"## Summary\n\nAdds `docs/v2/s7.md` (485 lines) covering Siemens SIMATIC S7 family Modbus TCP behavior. Mirrors the `docs/v2/dl205.md` template for future per-quirk implementation PRs.\n\n## Key findings for the implementation track\n\n- **No fixed memory map** — every S7 Modbus server is user-wired via `MB_SERVER`/`MODBUSCP`/`MODBUSPN` library blocks. Driver must accept per-site config, not assume a vendor layout.\n- **MB_SERVER requires non-optimized DBs** (STATUS `0x8383` if optimized). Most common field bug.\n- **Word order default = ABCD** (opposite of DL260). Driver's S7 profile default must be `ByteOrder.BigEndian`, not `WordSwap`.\n- **One port per MB_SERVER instance** — multi-client requires parallel FBs on 503/504/… Most clients assume port 502 multiplexes (wrong on S7).\n- **CP 343-1 Lean is server-only**, requires the `2XV9450-1MB00` license.\n- **FC20/21/22/23/43 all return Illegal Function** on every S7 variant — driver must not attempt FC23 bulk-read optimization for S7.\n- **STOP-mode behavior non-deterministic** across firmware bands — treat both read/write STOP-mode responses as unavailable.\n\nTwo items flagged as unconfirmed rumour (V2.0+ float byte-order claim, STOP-mode caching location).\n\nNo code, no tests — implementation lands in PRs 56+.\n\n## Test plan\n- [x] Doc renders as markdown\n- [x] 31 citations present\n- [x] Section structure matches dl205.md template","head":"phase-3-pr54-s7-research-doc","base":"v2"}

_p55.json

@@ -0,0 +1 @@
+{"title":"Phase 3 PR 55 -- Mitsubishi MELSEC Modbus TCP quirks research doc","body":"## Summary\n\nAdds `docs/v2/mitsubishi.md` (451 lines) covering MELSEC Q/L/iQ-R/iQ-F/FX3U Modbus TCP behavior. Mirrors `docs/v2/dl205.md` template for per-quirk implementation PRs.\n\n## Key findings for the implementation track\n\n- **Module naming trap** — `QJ71MB91` is SERIAL RTU, not TCP. TCP module is `QJ71MT91`. Surface clearly in driver docs.\n- **No canonical mapping** — per-site 'Modbus Device Assignment Parameter' block (up to 16 entries). Treat mapping as runtime config.\n- **X/Y hex vs octal depends on family** — Q/L/iQ-R use HEX (X20 = decimal 32); FX/iQ-F use OCTAL (X20 = decimal 16). Helper must take a family selector.\n- **Word order CDAB default** across all MELSEC families (opposite of Siemens S7). Driver Mitsubishi profile default: `ByteOrder.WordSwap`.\n- **D-registers binary by default** (opposite of DL205's BCD default). Caller opts in to `Bcd16`/`Bcd32` when ladder uses BCD.\n- **FX5U needs firmware ≥ 1.060** for Modbus TCP server — older is client-only.\n- **FX3U-ENET vs FX3U-ENET-P502 vs FX3U-ENET-ADP** — only the middle one binds port 502; the last has no Modbus at all. Common operator mis-purchase.\n- **QJ71MT91 does NOT support FC22 / FC23** — iQ-R / iQ-F do. Bulk-read optimization must gate on capability.\n- **STOP-mode writes configurable** on Q/L/iQ-R/iQ-F (default accept), always rejected on FX3U-ENET.\n\nThree unconfirmed rumours flagged separately.\n\nNo code, no tests — implementation lands in PRs 58+.\n\n## Test plan\n- [x] Doc renders as markdown\n- [x] 17 citations present\n- [x] Per-model test naming matrix included (`Mitsubishi_QJ71MT91_*`, `Mitsubishi_FX5U_*`, `Mitsubishi_FX3U_ENET_*`, shared `Mitsubishi_Common_*`)","head":"phase-3-pr55-mitsubishi-research-doc","base":"v2"}

docs/v2/mitsubishi.md

@@ -0,0 +1,451 @@
+# Mitsubishi Electric MELSEC — Modbus TCP quirks
+
+Mitsubishi's MELSEC family speaks Modbus TCP through a patchwork of add-on modules
+and built-in Ethernet ports, not a single unified stack. The module names are
+confusingly similar (`QJ71MB91` is *serial* RTU, `QJ71MT91` is the TCP/IP module
+[9]; `LJ71MT91` is the L-series equivalent; `RJ71EN71` is the iQ-R Ethernet module
+with a MODBUS/TCP *slave* mode bolted on [8]; `FX3U-ENET`, `FX3U-ENET-P502`,
+`FX3U-ENET-ADP`, `FX3GE` built-in, and `FX5U` built-in are all different code
+paths) — and every one of the categories below has at least one trap a textbook
+Modbus client gets wrong: hex-numbered X/Y devices colliding with decimal Modbus
+addresses, a user-defined "device assignment" parameter block that means *no two
+sites are identical*, CDAB-vs-ABCD word order driven by how the ladder built the
+32-bit value, sub-spec FC16 caps on the older QJ71MT91, and an FX3U port-502
+licensing split that makes `FX3U-ENET` and `FX3U-ENET-P502` different SKUs.
+This document catalogues each quirk, cites primary sources, and names the
+ModbusPal integration test we'd write for it (convention from
+`docs/v2/modbus-test-plan.md`: `Mitsubishi_<model>_<behavior>`).
+
+## Models and server/client capability
+
+| Model                  | Family   | Modbus TCP server | Modbus TCP client | Source |
+|------------------------|----------|-------------------|-------------------|--------|
+| `QJ71MT91`             | MELSEC-Q | Yes (slave)       | Yes (master)      | [9]    |
+| `QJ71MB91`             | MELSEC-Q | **Serial only** — RS-232/422/485 RTU, *not TCP* | — | [1][3] |
+| `LJ71MT91`             | MELSEC-L | Yes (slave)       | Yes (master)      | [10]   |
+| `RJ71EN71` / `RnENCPU` | MELSEC iQ-R | Yes (slave)    | Yes (master)      | [8]    |
+| `RJ71C24` / `RJ71C24-R2` | MELSEC iQ-R | RTU (serial)  | RTU (serial)      | [13]   |
+| iQ-R built-in Ethernet | CPU      | Yes (slave)       | Yes (master)      | [7]    |
+| iQ-F `FX5U` built-in Ethernet | CPU | Yes, firmware ≥ 1.060 [11] | Yes | [7][11][12] |
+| `FX3U-ENET`            | FX3U bolt-on | Yes (slave), but **not on port 502** [5] | Yes | [4][5] |
+| `FX3U-ENET-P502`       | FX3U bolt-on | Yes (slave), port 502 enabled | Yes | [5] |
+| `FX3U-ENET-ADP`        | FX3U adapter | **No MODBUS** [5] | No MODBUS     | [5]    |
+| `FX3GE` built-in       | FX3GE CPU | No MODBUS (needs ENET module) [6] | No | [6] |
+| `FX3G` + `FX3U-ENET`   | FX3G | Yes via ENET module | Yes | [6] |
+
+- A common integration mistake is to buy `FX3U-ENET-ADP` expecting MODBUS —
+  that adapter speaks only MC protocol / SLMP. Our driver should surface a clear
+  capability error, not "connection refused", when the operator's device tag
+  says `FX3U-ENET-ADP` [5].
+- Older forum threads assert the FX5U is "client only" [12] — that was true on
+  firmware ≤ 1.040. Firmware 1.060 and later ship the parameter-driven MODBUS
+  TCP server built-in and need no function blocks [11].
+
+## Modbus device assignment (the parameter block)
+
+Unlike a DL260 where the CPU exposes a *fixed* V-memory-to-Modbus mapping, every
+MELSEC MODBUS-TCP module exposes a **Modbus Device Assignment Parameter** block
+that the engineer configures in GX Works2 / GX Configurator-MB / GX Works3.
+Each of the four Modbus tables (Coil, Input, Input Register, Holding Register)
+can be split into up to 16 independent "assignment" entries, each binding a
+contiguous Modbus address range to a MELSEC device head (`M0`, `D0`, `X0`,
+`Y0`, `B0`, `W0`, `SM0`, `SD0`, `R0`, etc.) and a point count [3][7][8][9].
+
+- **There is no canonical "MELSEC Modbus mapping"**. Two sites running the same
+  QJ71MT91 module can expose completely different Modbus layouts. Our driver
+  must treat the mapping as site-data (config-file-driven), not as a device
+  profile constant.
+- **Default values do exist** — both GX Configurator-MB (for Q/L series) and
+  GX Works3 (for iQ-R / iQ-F / FX5) ship a "dedicated pattern" default that is
+  applied when the engineer does not override the assignment. Per the FX5
+  MODBUS Communication manual (JY997D56101) and the QJ71MT91 manual, the FX5
+  dedicated default is [3][7][11]:
+
+  | Modbus table       | Modbus range (0-based) | MELSEC device | Head |
+  |--------------------|------------------------|---------------|------|
+  | Coil (FC01/05/15)  | 0 – 7679               | M             | M0   |
+  | Coil               | 8192 – 8959            | Y             | Y0   |
+  | Input (FC02)       | 0 – 7679               | M             | M0   |
+  | Input              | 8192 – 8959            | X             | X0   |
+  | Input Register (FC04) | 0 – 6143            | D             | D0   |
+  | Holding Register (FC03/06/16) | 0 – 6143    | D             | D0   |
+
+  This matches the widely circulated "FC03 @ 0 = D0" convention that shows up
+  in Ubidots / Ignition / AdvancedHMI integration guides [6][12].
+
+- **X/Y in the default mapping occupy a second, non-zero Modbus range** (8192+
+  on FX5; similar on Q/L/iQ-R). Driver users who expect "X0 = coil 0" will be
+  reading M0 instead. Document this clearly.
+- **Assignment-range collisions silently disable the slave.** The QJ71MT91
+  manual states explicitly that if any two of assignments 1-16 duplicate the
+  head Modbus device number, the slave function is inactive with no clear
+  error — the module just won't respond [9]. The driver probe will look like a
+  simple timeout; the site engineer has to open GX Configurator-MB to diagnose.
+
+Test names:
+`Mitsubishi_FX5U_default_mapping_coil_0_is_M0`,
+`Mitsubishi_FX5U_default_mapping_holding_0_is_D0`,
+`Mitsubishi_QJ71MT91_duplicate_assignment_head_disables_slave`.
+
+## X/Y addressing — hex on MELSEC, decimal on Modbus
+
+**MELSEC X (input) and Y (output) device numbers are hexadecimal on Q / L /
+iQ-R** and **octal** on FX / iQ-F (with a GX Works3 toggle) [14][15].
+
+- On a Q CPU, `X20` means decimal **32**, not 20. On an FX5U in default (octal)
+  mode, `X20` means decimal **16**. GX Works3 exposes a project-level option to
+  display FX5U X/Y in hex to match Q/L/iQ-R convention — the same physical
+  input is then called `X10` [14].
+- The Modbus Device Assignment Parameter block takes the *head device* as a
+  MELSEC-native number, which is interpreted in the CPU's native base
+  (hex for Q/L/iQ-R, octal for FX/iQ-F). After that, **Modbus offsets from
+  the head are plain decimal** — the module does not apply a second hex
+  conversion [3][9].
+- Example (QJ71MT91 on a Q CPU): assignment "Coil 0 = X0, 512 points" exposes
+  physical `X0` through `X1FF` (hex) as coils 0-511. A client reading coil 32
+  gets the bit `X20` (hex) — i.e. the 33rd input, not the value at "input 20"
+  that the operator wrote on the wiring diagram in decimal.
+- **Driver bug source**: if the operator's tag configuration says "read X20" and
+  the driver helpfully converts "20" to decimal 20 → coil offset 20, the
+  returned bit is actually `X14` (hex) — off by twelve. Our config layer must
+  preserve the MELSEC-native base that the site engineer sees in GX Works.
+- Timers/counters (`T`, `C`, `ST`) are always decimal in MELSEC notation.
+  Internal relays (`M`, `B`, `L`), data registers (`D`, `W`, `R`, `ZR`),
+  and special relays/registers (`SM`, `SD`) also decimal. **Only `X` and `Y`
+  (and on Q/L/iQ-R, `B` link relays and `W` link registers) use hex**, and
+  the X/Y decision is itself family-dependent [14][15].
+
+Test names:
+`Mitsubishi_Q_X_address_is_hex_X20_equals_coil_offset_32`,
+`Mitsubishi_FX5U_X_address_is_octal_X20_equals_coil_offset_16`,
+`Mitsubishi_W_link_register_is_hex_W10_equals_holding_offset_16`.
+
+## Word order for 32-bit values
+
+MELSEC stores 32-bit ladder values (`DINT`, `DWORD`, `REAL` / single-precision
+float) across **two consecutive D-registers, low word first** — i.e., `CDAB`
+when viewed as a Modbus register pair [2][6].
+
+```
+D100 (low word)  : 0xCC 0xDD   (big-endian bytes within the word)
+D101 (high word) : 0xAA 0xBB
+```
+
+A Modbus master reading D100/D101 as a `float` with default (ABCD) word order
+gets garbage. Ignition's built-in Modbus driver notes Mitsubishi as a "CDAB
+device" specifically for this reason [2].
+
+- **Q / L / iQ-R / iQ-F all agree** — this is a CPU-level convention, not a
+  module choice. Both the QJ71MT91 manual and the FX5 MODBUS Communication
+  manual describe 32-bit access by "reading the lower 16 bits from the start
+  address and the upper 16 bits from start+1" [6][11].
+- **Byte order within each register is big-endian** (Modbus standard). The
+  module does not byte-swap.
+- **Configurable?** The MODBUS modules themselves do **not** expose a word-
+  order toggle; the behavior is fixed to how the CPU laid out the value in the
+  two D-registers. If the ladder programmer used an `SWAP` instruction or a
+  union-style assignment, the word order can be whatever they made it — but
+  for values produced by the standard `D→DBL` and `FLT`/`FLT2` instructions
+  it is always CDAB [2].
+- **FX5U quirk**: the FX5 MODBUS Communication manual tells the programmer to
+  use the `SWAP` instruction *if* the remote Modbus peer requires
+  little-endian *byte* ordering (BADC) [11]. This is only relevant when the
+  FX5U is the Modbus *client*, but it confirms the FX5U's native wire layout
+  is big-endian-byte / little-endian-word (CDAB) on the server side too.
+- **Rumoured exception**: a handful of MrPLC forum threads report iQ-R
+  RJ71EN71 firmware < 1.05 returning DWORDs in `ABCD` order when accessed via
+  the built-in Ethernet port's MODBUS slave [8]. _Unconfirmed_; treat as a
+  per-site test.
+
+Test names:
+`Mitsubishi_Float32_word_order_is_CDAB`,
+`Mitsubishi_Int32_word_order_is_CDAB`,
+`Mitsubishi_FX5U_SWAP_instruction_changes_byte_order_not_word_order`.
+
+## BCD vs binary encoding
+
+**MELSEC stores integer values in D-registers as plain binary two's-complement**,
+not BCD [16]. This is the opposite of AutomationDirect DirectLOGIC, where
+V-memory defaults to BCD and the ladder must explicitly request binary.
+
+- A ladder `MOV K1234 D100` stores `0x04D2` (1234 decimal) in D100, not
+  `0x1234`. The Modbus master reads `0x04D2` and decodes it as an integer
+  directly — no BCD conversion needed [16].
+- **Timer / counter current values** (`T0` current value, `C0` count) are
+  stored in binary as word devices on Q/L/iQ-R/iQ-F. The ladder preset
+  (`K...`) is also binary [16][17].
+- **Timer / counter preset `K` operand in FX3U / earlier FX**: also binary when
+  loaded from a D-register or a `K` constant. The older A-series CPUs had BCD
+  presets on some timer types, but MELSEC-Q, L, iQ-R, iQ-F, and FX3U all use
+  binary presets by default [17].
+- The FX3U programming manual dedicates `FNC 18 BCD` and `FNC 19 BIN` to
+  explicit conversion — their existence confirms that anything in D-registers
+  that came from a `BCD` instruction output is BCD, but nothing is BCD by
+  default [17].
+- **7-segment display registers** are a common site-specific exception — many
+  ladders pack `BCD D100` into a D-register so the operator panel can drive
+  a display directly. Our driver should not assume; expose a per-tag
+  "encoding = binary | BCD" knob.
+
+Test names:
+`Mitsubishi_D_register_stores_binary_not_BCD`,
+`Mitsubishi_FX3U_timer_current_value_is_binary`.
+
+## Max registers per request
+
+From the FX5 MODBUS Communication manual Chapter 11 [11]:
+
+| FC | Name                       | FX5U (built-in) | QJ71MT91     | iQ-R (RJ71EN71 / built-in) | FX3U-ENET |
+|----|----------------------------|-----------------|--------------|-----------------------------|-----------|
+| 01 | Read Coils                 | 1-2000          | 1-2000 [9]   | 1-2000 [8]                  | 1-2000    |
+| 02 | Read Discrete Inputs       | 1-2000          | 1-2000       | 1-2000                      | 1-2000    |
+| 03 | Read Holding Registers     | **1-125**       | 1-125 [9]    | 1-125 [8]                   | 1-125     |
+| 04 | Read Input Registers       | 1-125           | 1-125        | 1-125                       | 1-125     |
+| 05 | Write Single Coil          | 1               | 1            | 1                           | 1         |
+| 06 | Write Single Register      | 1               | 1            | 1                           | 1         |
+| 0F | Write Multiple Coils       | 1-1968          | 1-1968       | 1-1968                      | 1-1968    |
+| 10 | Write Multiple Registers   | **1-123**       | 1-123        | 1-123                       | 1-123     |
+| 16 | Mask Write Register        | 1               | not supported | 1                          | not supported |
+| 17 | Read/Write Multiple Regs   | R:1-125, W:1-121 | not supported | R:1-125, W:1-121          | not supported |
+
+- **The FX5U / iQ-R native-port limits match the Modbus spec**: 125 for FC03/04,
+  123 for FC16 [11]. No sub-spec caps like DL260's 100-register ceiling.
+- **QJ71MT91 does not support FC16 (0x16, Mask Write Register) or FC17
+  (0x17, Read/Write Multiple)** — requesting them returns exception `01`
+  Illegal Function [9]. FX5U and iQ-R *do* support both.
+- **QJ71MT91 device size**: 64k points (65,536) for each of Coil / Input /
+  Input Register / Holding Register, plus up to 4086k points for Extended
+  File Register via a secondary assignment range [9].
+- **FX3U-ENET / -P502 function code list is a strict subset** of the common
+  eight (FC01/02/03/04/05/06/0F/10). FC16 and FC17 not supported [4].
+
+Test names:
+`Mitsubishi_FX5U_FC03_126_registers_returns_IllegalDataValue`,
+`Mitsubishi_FX5U_FC16_124_registers_returns_IllegalDataValue`,
+`Mitsubishi_QJ71MT91_FC16_MaskWrite_returns_IllegalFunction`,
+`Mitsubishi_QJ71MT91_FC23_ReadWrite_returns_IllegalFunction`.
+
+## Exception codes
+
+MELSEC MODBUS modules return **only the standard Modbus exception codes 01-04**;
+no proprietary exception codes are exposed on the wire [8][9][11]. Module-
+internal diagnostics (buffer-memory error codes like `7380H`) are logged but
+not returned as Modbus exceptions.
+
+| Code | Name                 | MELSEC trigger                                          |
+|------|----------------------|---------------------------------------------------------|
+| 01   | Illegal Function     | FC17 or FC16 on QJ71MT91/FX3U; FC08 (Diagnostics); FC43 |
+| 02   | Illegal Data Address | Modbus address outside any assignment range             |
+| 03   | Illegal Data Value   | Quantity out of per-FC range (see table above); odd coil-byte count |
+| 04   | Server Device Failure | See below                                              |
+
+- **04 (Server Failure) triggers on MELSEC**:
+    - CPU in STOP or PAUSE during a write to an assignment whose "Access from
+      External Device" permission is set to "Disabled in STOP" [9][11].
+      *With the default "always enabled" setting the write succeeds in STOP
+      mode* — another common trap.
+    - CPU errors (parameter error, watchdog) during any access.
+    - Assignment points to a device range that is not configured (e.g. write
+      to `D16384` when CPU D-device size is 12288).
+- **Write to a "System Area" device** (e.g., `SD` special registers that are
+  CPU-reserved read-only) returns `04`, not `02`, on QJ71MT91 and iQ-R — the
+  assignment is valid, the device exists, but the CPU rejects the write [8][9].
+- **FX3U-ENET / -P502** returns `04` on any write attempt while the CPU is in
+  STOP, regardless of permission settings — the older firmware does not
+  implement the "Access from External Device" granularity that Q/L/iQ-R/iQ-F
+  expose [4].
+- **No rumour of proprietary codes 05-0B** from MELSEC; operators sometimes
+  report "exception 0A" but those traces all came from a third-party gateway
+  sitting between the master and the MELSEC module.
+
+Test names:
+`Mitsubishi_QJ71MT91_STOP_mode_write_with_Disabled_permission_returns_ServerFailure`,
+`Mitsubishi_QJ71MT91_STOP_mode_write_with_default_permission_succeeds`,
+`Mitsubishi_SD_system_register_write_returns_ServerFailure`,
+`Mitsubishi_FX3U_STOP_mode_write_always_returns_ServerFailure`.
+
+## Connection behavior
+
+Max simultaneous Modbus TCP clients, per module [7][8][9][11]:
+
+| Model                | Max TCP connections | Port 502 | Keepalive | Source |
+|----------------------|---------------------|----------|-----------|--------|
+| `QJ71MT91`           | 16 (shared with master role) | Yes | No | [9]    |
+| `LJ71MT91`           | 16                  | Yes      | No        | [10]   |
+| iQ-R built-in / `RJ71EN71` | 16            | Yes      | Configurable (KeepAlive = ON in parameter) | [8] |
+| iQ-F `FX5U` built-in | 8                   | Yes      | Configurable | [7][11] |
+| `FX3U-ENET`          | 8 TCP, but **not port 502** | No (port < 1024 blocked) | No | [4][5] |
+| `FX3U-ENET-P502`     | 8, port 502 enabled | Yes      | No        | [5]    |
+
+- **QJ71MT91's 16 is total connections shared between slave-listen and
+  master-initiated sockets** [9]. A site that uses the same module as both
+  master to downstream VFDs and slave to upstream SCADA splits the 16 pool.
+- **FX3U-ENET port-502 gotcha**: if the engineer loads a configuration with
+  port 502 into a non-P502 ENET module, GX Works shows the download as
+  successful; on next power cycle the module enters error state and the
+  MODBUS listener never starts. This is documented on third-party FX3G
+  integration guides [6].
+- **CPU STOP → RUN transition**: does **not** drop Modbus connections on any
+  MELSEC family. Existing sockets stay open; outstanding requests during the
+  transition may see exception 04 for a few scans but then resume [8][9].
+- **CPU reset (power cycle or `SM1255` forced reset)** drops all Modbus
+  connections and the module re-listens after typically 5-10 seconds.
+- **Idle timeout**: QJ71MT91 and iQ-R have a per-connection "Alive-Check"
+  (idle timer) parameter, default 0 (disabled). If enabled, default 10 s
+  probe interval, 3 retries before close [8][9]. FX5U similar defaults.
+- **Keep-alive (TCP-level)**: only iQ-R / iQ-F expose a TCP keep-alive option
+  (parameter "KeepAlive" in the Ethernet settings); QJ71MT91 and FX3U-ENET
+  do not — so NAT/firewall idle drops require driver-side pinging.
+
+Test names:
+`Mitsubishi_QJ71MT91_17th_connection_refused`,
+`Mitsubishi_FX5U_9th_connection_refused`,
+`Mitsubishi_STOP_to_RUN_transition_preserves_socket`,
+`Mitsubishi_CPU_reset_closes_all_sockets`.
+
+## Behavioral oddities
+
+- **Transaction ID echo**: QJ71MT91 and iQ-R reliably echo the MBAP TxId on
+  every response across firmware revisions; no reports of TxId drops under
+  load [8][9]. FX3U-ENET has an older, less-tested TCP stack; at least one
+  MrPLC thread reports out-of-order TxId echoes under heavy polling on
+  firmware < 1.14 [4]. _Unconfirmed_ on current firmware.
+- **Per-connection request serialization**: all MELSEC slaves serialize
+  requests within a single TCP connection — a new request is not processed
+  until the prior response has been sent. Pipelining multiple requests on one
+  socket causes the module to queue them in buffer memory and respond in
+  order, but **the queue depth is 1** on QJ71MT91 (a second in-flight request
+  is held on the TCP receive buffer, not queued) [9]. Driver should treat
+  Mitsubishi slaves as strictly single-flight per socket.
+- **Partial-frame handling**: QJ71MT91 and iQ-R close the socket on malformed
+  MBAP length fields. FX5U resynchronises at the next valid MBAP header
+  within 100 ms but will emit an error to `SD` diagnostics [11]. Driver must
+  reconnect on half-close and replay.
+- **FX3U UDP vs TCP**: `FX3U-ENET` supports both UDP and TCP MODBUS transports;
+  UDP is lossy and reorders under load. Default is TCP. Some legacy SCADA
+  configurations pinned the module to UDP for multicast discovery — do not
+  select UDP unless the site requires it [4].
+- **Known firmware-revision variants**:
+    - QJ71MT91 ≤ firmware 10052000000 (year-month format): FC15 with coil
+      count that forces byte-count to an odd value silently truncates the
+      last coil. Fixed in later revisions [9]. _Operator-reported_.
+    - FX5U firmware < 1.060: no native MODBUS TCP server — only accessible via
+      a predefined-protocol function block hack. Firmware ≥ 1.060 ships
+      parameter-based server. Our capability probe should read `SD203`
+      (firmware version) and flag < 1.060 as unsupported for server mode [11][12].
+    - iQ-R RJ71EN71 early firmware: possible ABCD word order (rumoured,
+      unconfirmed) [8].
+- **SD (special-register) reads during assignment-parameter load**: while
+  the CPU is loading a new MODBUS device assignment parameter (~1-2 s), the
+  slave returns exception 04 Server Failure on every request. Happens after
+  a parameter write from GX Configurator-MB [9].
+- **iQ-R "Station-based block transfer" collision**: if the RJ71EN71 is also
+  running CC-Link IE Control on the same module, a MODBUS/TCP request that
+  arrives during a CCIE cyclic period is delayed to the next scan — visible
+  as jittery response time, not a failure [8].
+
+Test names:
+`Mitsubishi_QJ71MT91_single_flight_per_socket`,
+`Mitsubishi_FX5U_malformed_MBAP_resync_within_100ms`,
+`Mitsubishi_FX3U_TxId_preserved_across_burst`,
+`Mitsubishi_FX5U_firmware_below_1_060_reports_no_server_mode`.
+
+## Model-specific differences for test coverage
+
+Summary of which quirks differ per model, so test-class naming can reflect them:
+
+| Quirk                                    | QJ71MT91 | LJ71MT91 | iQ-R (RJ71EN71 / built-in) | iQ-F (FX5U) | FX3U-ENET(-P502) |
+|------------------------------------------|----------|----------|----------------------------|-------------|------------------|
+| FC16 Mask-Write supported                | No       | No       | Yes                        | Yes         | No               |
+| FC17 Read/Write Multiple supported       | No       | No       | Yes                        | Yes         | No               |
+| Max connections                          | 16       | 16       | 16                         | 8           | 8                |
+| X/Y numbering base                       | hex      | hex      | hex                        | octal (default) | octal        |
+| 32-bit word order                        | CDAB     | CDAB     | CDAB (firmware-dependent rumour of ABCD) | CDAB | CDAB    |
+| Port 502 supported                       | Yes      | Yes      | Yes                        | Yes         | P502 only        |
+| STOP-mode write permission configurable  | Yes      | Yes      | Yes                        | Yes         | No (always blocks) |
+| TCP keep-alive parameter                 | No       | No       | Yes                        | Yes         | No               |
+| Modbus device assignment — max entries   | 16       | 16       | 16                         | 16          | 8                |
+| Server via parameter (no FB)             | Yes      | Yes      | Yes                        | Yes (fw ≥ 1.060) | Yes         |
+
+- **Test file layout**: `Mitsubishi_QJ71MT91_*`, `Mitsubishi_LJ71MT91_*`,
+  `Mitsubishi_iQR_*`, `Mitsubishi_FX5U_*`, `Mitsubishi_FX3U_ENET_*`,
+  `Mitsubishi_FX3U_ENET_P502_*`. iQ-R built-in Ethernet and the RJ71EN71
+  behave identically for MODBUS/TCP slave purposes and can share a file
+  `Mitsubishi_iQR_*`.
+- **Cross-model shared tests** (word order CDAB, binary not BCD, standard
+  exception codes, 125-register FC03 cap) can live in a single
+  `Mitsubishi_Common_*` fixture.
+
+## References
+
+1. Mitsubishi Electric, *MODBUS Interface Module User's Manual — QJ71MB91*
+   (SH-080578ENG), RS-232/422/485 MODBUS RTU serial module for MELSEC-Q —
+   https://dl.mitsubishielectric.com/dl/fa/document/manual/plc/sh080578eng/sh080578engk.pdf
+2. Inductive Automation, *Ignition Modbus Driver — Mitsubishi Q / iQ-R word
+   order*, documents CDAB convention —
+   https://docs.inductiveautomation.com/docs/8.1/ignition-modules/opc-ua/drivers/modbus-v2
+   and forum discussion https://forum.inductiveautomation.com/t/modbus-tcp-device-word-byte-order/65984
+3. Mitsubishi Electric, *Programmable Controller User's Manual QJ71MB91 MODBUS
+   Interface Module*, Chapter 7 "Parameter Setting" describing the Modbus
+   Device Assignment Parameter block (assignments 1-16, head-device
+   configuration) —
+   https://www.lcautomation.com/dbdocument/29156/QJ71MB91%20Users%20manual.pdf
+4. Mitsubishi Electric, *FX3U-ENET User's Manual* (JY997D18101), Chapter on
+   MODBUS/TCP communication; function code support and connection limits —
+   https://dl.mitsubishielectric.com/dl/fa/document/manual/plc_fx/jy997d18101/jy997d18101h.pdf
+5. Venus Automation, *Mitsubishi FX3U-ENET-P502 Module — Open Port 502 for
+   Modbus TCP/IP* —
+   https://venusautomation.com.au/mitsubishi-fx3u-enet-p502-module-open-port-502-for-modbus-tcp-ip/
+   and FX3U-ENET-ADP user manual (JY997D45801), which confirms the -ADP
+   variant does not support MODBUS —
+   https://dl.mitsubishielectric.com/dl/fa/document/manual/plc_fx/jy997d45801/jy997d45801h.pdf
+6. XML Control / Ubidots integration notes, *FX3G Modbus* — port-502 trap,
+   D-register mapping default, word order reference —
+   https://sites.google.com/site/xmlcontrol/archive/fx3g-modbus
+   and https://ubidots.com/blog/mitsubishi-plc-as-modbus-tcp-server/
+7. FA Support Me, *Modbus TCP on Built-in Ethernet port in iQ-F and iQ-R* —
+   confirms 16-connection limit on iQ-R, 8 on iQ-F, parameter-driven
+   configuration via GX Works3 —
+   https://www.fasupportme.com/portal/en/kb/articles/modbus-tcp-on-build-in-ethernet-port-in-iq-f-and-iq-r-en
+8. Mitsubishi Electric, *MELSEC iQ-R Ethernet User's Manual (Application)*
+   (SH-081259ENG) and *MELSEC iQ-RJ71EN71 User's Manual* Chapter on
+   "Communications Using Modbus/TCP" —
+   https://www.allied-automation.com/wp-content/uploads/2015/02/MITSUBISHI_manual_plc_iq-r_ethernet_users.pdf
+   and https://www.manualslib.com/manual/1533351/Mitsubishi-Electric-Melsec-Iq-Rj71en71.html?page=109
+9. Mitsubishi Electric, *MODBUS/TCP Interface Module User's Manual — QJ71MT91*
+   (SH-080446ENG), exception codes page 248, device assignment parameter
+   pages 116-124, duplicate-assignment-disables-slave note —
+   https://dl.mitsubishielectric.com/dl/fa/document/manual/plc/sh080446eng/sh080446engj.pdf
+10. Mitsubishi Electric, *MELSEC-L Network Features* — LJ71MT91 documented as
+    L-series equivalent of QJ71MT91 with identical MODBUS/TCP behavior —
+    https://us.mitsubishielectric.com/fa/en/products/cnt/programmable-controllers/melsec-l-series/network/features/
+11. Mitsubishi Electric, *MELSEC iQ-F FX5 User's Manual (MODBUS Communication)*
+    (JY997D56101), Chapter 11 "Modbus/TCP Communication Specifications" —
+    function code max-quantity table, frame specification, device assignment
+    defaults —
+    https://dl.mitsubishielectric.com/dl/fa/document/manual/plcf/jy997d56101/jy997d56101h.pdf
+12. MrPLC forum, *FX5U Modbus-TCP Server (Slave)*, firmware ≥ 1.60 enables
+    native server via parameter; earlier firmware required function block —
+    https://mrplc.com/forums/topic/31883-fx5u-modbus-tcp-server-slave/
+    and Industrial Monitor Direct's "FX5U MODBUS TCP Server Workaround"
+    article (reflects older firmware behavior) —
+    https://industrialmonitordirect.com/blogs/knowledgebase/mitsubishi-fx5u-modbus-tcp-server-configuration-workaround
+13. Mitsubishi Electric, *MELSEC iQ-R MODBUS and MODBUS/TCP Reference Manual —
+    RJ71C24 / RJ71C24-R2* (BCN-P5999-1060) — RJ71C24 is serial RTU only,
+    not TCP —
+    https://dl.mitsubishielectric.com/dl/fa/document/manual/plc/bcn-p5999-1060/bcnp59991060b.pdf
+14. HMS Industrial Networks, *eWON and Mitsubishi FX5U PLC* (KB-0264-00) —
+    documents that FX5U X/Y are octal in GX Works3 but hex when viewed as a
+    Q-series PLC through eWON; the project-level hex/octal toggle —
+    https://hmsnetworks.blob.core.windows.net/www/docs/librariesprovider10/downloads-monitored/manuals/knowledge-base/kb-0264-00-en-ewon-and-mitsubishi-fx5u-plc.pdf
+15. Fernhill Software, *Mitsubishi Melsec PLC Data Address* — documents
+    hex-vs-octal device numbering split across MELSEC families —
+    https://www.fernhillsoftware.com/help/drivers/mitsubishi-melsec/data-address-format.html
+16. Inductive Automation support, *Understanding Mitsubishi PLCs* — D registers
+    store signed 16-bit binary, not BCD; DINT combines two consecutive D
+    registers —
+    https://support.inductiveautomation.com/hc/en-us/articles/16517576753165-Understanding-Mitsubishi-PLCs
+17. Mitsubishi Electric, *FXCPU Structured Programming Manual [Device &
+    Common]* (JY997D26001) — FNC 18 BCD and FNC 19 BIN explicit-conversion
+    instructions confirm binary-by-default storage —
+    https://dl.mitsubishielectric.com/dl/fa/document/manual/plc_fx/jy997d26001/jy997d26001l.pdf

docs/v2/s7.md

@@ -0,0 +1,485 @@
+# Siemens SIMATIC S7 (S7-1200 / S7-1500 / S7-300 / S7-400 / ET 200SP) — Modbus TCP quirks
+
+Siemens S7 PLCs do *not* speak Modbus TCP natively at the OS/firmware level. Every
+S7 Modbus-TCP-server deployment is either (a) the **`MB_SERVER`** library block
+running on the CPU's PROFINET port (S7-1200 / S7-1500 / CPU 1510SP-series
+ET 200SP), or (b) the **`MODBUSCP`** function block running on a separate
+communication processor (**CP 343-1 / CP 343-1 Lean** on S7-300, **CP 443-1** on
+S7-400), or (c) the **`MODBUSPN`** block on an S7-1500 PN port via a licensed
+library. That means the quirks a Modbus client has to cope with are as much
+"this is how the user's PLC programmer wired the library block up" as "this is
+how the firmware behaves" — the byte-order and coil-mapping rules aren't
+hard-wired into silicon like they are on a DL260. This document catalogues the
+behaviours a driver has to handle across the supported model/CP variants, cites
+primary sources, and names the ModbusPal integration test we'd write for each
+(convention from `docs/v2/modbus-test-plan.md`: `S7_<model>_<behavior>`).
+
+## Model / CP Capability Matrix
+
+| PLC family          | Modbus TCP server mechanism        | Modbus TCP client mechanism       | License required?     | Typical port 502 source                                   |
+|---------------------|------------------------------------|------------------------------------|-----------------------|-----------------------------------------------------------|
+| S7-1200 (V4.0+)     | `MB_SERVER` on integrated PN port  | `MB_CLIENT`                       | No (in TIA Portal)    | CPU's onboard Ethernet [1][2]                              |
+| S7-1500 (all)       | `MB_SERVER` on integrated PN port  | `MB_CLIENT`                       | No (in TIA Portal)    | CPU's onboard Ethernet [1][3]                              |
+| S7-1500 + CP 1543-1 | `MB_SERVER` on CP's IP             | `MB_CLIENT`                       | No                    | Separate CP IP address [1]                                 |
+| ET 200SP CPU (1510SP, 1512SP) | `MB_SERVER` on PN port   | `MB_CLIENT`                       | No                    | CPU's onboard Ethernet [3]                                 |
+| S7-300 + CP 343-1 / CP 343-1 Lean | `MODBUSCP` (FB `MODBUSCP`, instance DB per connection) | Same FB, client mode | **Yes — 2XV9450-1MB00** per CP | CP's Ethernet port [4][5] |
+| S7-400 + CP 443-1   | `MODBUSCP`                         | `MODBUSCP` client mode            | **Yes — 2XV9450-1MB00** per CP | CP's Ethernet port [4] |
+| S7-400H + CP 443-1 (redundant H) | `MODBUSCP_REDUNDANT` / paired FBs | Not typical | Yes | Paired CPs in H-system [6] |
+| S7-300 / S7-400 CPU PN (e.g. CPU 315-2 PN/DP) | `MODBUSPN` library | `MODBUSPN` client mode | **Yes** — Modbus-TCP PN CPU lib | CPU's PN port [7] |
+| "CP 343-1 Lean"     | **Server only** (no client mode supported by Lean) | — | Yes, but with restrictions | CP's Ethernet port [4][5] |
+
+- **CP 343-1 Lean is server-only.** It can host `MODBUSCP` in server mode only;
+  client calls return an immediate error. A surprising number of "Lean + client
+  doesn't work" forum posts trace back to this [5].
+- **Pure OPC UA / PROFINET CPs (CP 1542SP-1, CP 1543-1)** support Modbus TCP on
+  S7-1500 via the same `MB_SERVER`/`MB_CLIENT` instructions by passing the
+  CP's `hw_identifier`. There is no separate "Modbus CP" license needed on
+  S7-1500, unlike S7-300/400 [1].
+- **No S7 Modbus server supports function codes 20/21 (file records),
+  22 (mask write), 23 (read-write multiple), or 43 (device identification).**
+  Sending any of these returns exception `01` (Illegal Function) on every S7
+  variant [1][4]. Our driver must not negotiate FC23 as a "bulk-read optimization"
+  when the profile is S7.
+
+Test names:
+`S7_1200_MBSERVER_Loads_OB1_Cyclic`,
+`S7_CP343_Lean_Client_Mode_Rejected`,
+`S7_All_FC23_Returns_IllegalFunction`.
+
+## Address / DB Mapping
+
+S7 Modbus servers **do not auto-expose PLC memory** — the PLC programmer has to
+wire one area per Modbus table to a DB or process-image region. This is the
+single biggest difference vs. DL205/Modicon/etc., where the memory map is
+fixed at the factory. Our driver must therefore be tolerant of "the same
+`40001` means completely different things on two S7-1200s on the same site."
+
+### S7-1200 / S7-1500 `MB_SERVER`
+
+The `MB_SERVER` instance exposes four Modbus tables to each connected client;
+each table's backing storage is a per-block parameter [1][8]:
+
+| Modbus table        | FCs         | Backing parameter           | Default / typical backing   |
+|---------------------|-------------|-----------------------------|-----------------------------|
+| Coils (0x)          | FC01, FC05, FC15 | *implicit* — Q process image | `%Q0.0`–`%Q1023.7` (→ coil addresses 0–8191) [1][9] |
+| Discrete Inputs (1x)| FC02        | *implicit* — I process image | `%I0.0`–`%I1023.7` (→ discrete addresses 0–8191) [1][9] |
+| Input Registers (3x)| FC04        | *implicit* — M memory or DB (version-dependent) | Some firmware routes FC04 through the same MB_HOLD_REG buffer [1][8] |
+| Holding Registers (4x)| FC03, FC06, FC16 | `MB_HOLD_REG` pointer  | User DB (e.g. `DB10.DBW0`) or `%MW` area [1][2][8] |
+
+- **`MB_HOLD_REG` is a pointer (VARIANT / ANY) into a user-defined DB** whose
+  first byte is holding-register 0 (`40001` in 1-based Modicon form). Byte
+  offset 2 is register 1, byte offset 4 is register 2, etc. [1][2].
+- **The DB *must* have "Optimized block access" UNCHECKED.** Optimized DBs let
+  the compiler reorder fields for alignment; Modbus requires fixed byte
+  offsets. With optimized access on, the compiler accepts the project but
+  `MB_SERVER` returns STATUS `0x8383` (misaligned access) or silently reads
+  zeros [8][10][11]. This is the #1 support-forum complaint.
+- **FC01/FC02/FC05/FC15 hit the Q and I process images directly — not the
+  `MB_HOLD_REG` DB.** Coil address 0 = `%Q0.0`, coil 1 = `%Q0.1`, coil 8 =
+  `%Q1.0`. The S7-1200 system manual publishes this mapping as `00001 → Q0.0`
+  through `09999 → Q1023.7` and `10001 → I0.0` through `19999 → I1023.7` in
+  1-based form; on the wire (0-based) that's coils 0-8191 and discrete inputs
+  0-8191 [9].
+- **`%M` markers are NOT automatically exposed.** To expose `%M` over Modbus
+  the programmer must either (a) copy `%M` to the `MB_HOLD_REG` DB each scan,
+  or (b) define an Array\[0..n\] of Bool inside that DB and copy bits in/out
+  of `%M`. Siemens has no "MB_COIL_REG" parameter analogous to
+  `MB_HOLD_REG` — this confuses users migrating from Schneider [9][12].
+- **Bit ordering within a Modbus holding register sourced from an `Array of
+  Bool`**: S7 stores bool\[0\] at `DBX0.0` which is bit 0 of byte 0 which is
+  the **low byte, low bit** of Modbus register `40001`. A naive client that
+  reads register `40001` and masks `0x0001` gets bool\[0\]. A client that
+  masks `0x8000` gets bool\[15\] because the high byte of the Modbus register
+  is the *second* byte of the DB. Siemens programmers routinely get this
+  wrong in the DB-via-DBX form; `Array[0..n] of Bool` is the recommended
+  layout because it aligns naturally [12][13].
+
+### S7-300/400 + CP 343-1 / CP 443-1 `MODBUSCP`
+
+Different paradigm: per-connection **parameter DB** (template
+`MODBUS_PARAM_CP`) declares a table of up to 8 register-area mappings. Each
+mapping is a tuple `(data_type, DB#, start_offset, length)` where `data_type`
+picks the Modbus table [4]:
+
+- `B#16#1` = Coils
+- `B#16#2` = Discrete Inputs
+- `B#16#3` = Holding Registers
+- `B#16#4` = Input Registers
+
+The `holding_register_start` and analogous `coils_start` parameters declare
+**which Modbus address range** the CP will serve, and the DB pointers say
+where in S7 memory that range lives [4][14]. Unlike `MB_SERVER`, the CP does
+not reach into `%Q`/`%I` directly — *everything* goes through a DB. If an
+address outside the declared ranges is requested, the CP returns exception
+`02` (Illegal Data Address) [4].
+
+Test names:
+`S7_1200_FC03_Reg0_Reads_DB10_DBW0`,
+`S7_1200_Optimized_DB_Returns_0x8383_MisalignedAccess`,
+`S7_1200_FC01_Coil0_Reads_Q0_0`,
+`S7_CP343_FC03_Outside_ParamBlock_Range_Returns_IllegalDataAddress`.
+
+## Data Types and Byte Order
+
+Siemens CPUs store scalars **big-endian** internally ("Motorola format"), which
+is the same byte order Modbus specifies inside each register. So for 16-bit
+values (`Int`, `Word`, `UInt`) the on-the-wire layout is straightforward
+`AB` — high byte of the PLC value in the high byte of the Modbus register
+[15][16]. No byte-swap trap for 16-bit types.
+
+The trap is 32-bit types (`DInt`, `DWord`, `Real`). Here's what actually
+happens across the S7 family:
+
+### S7-1200 / S7-1500 `MB_SERVER`
+
+- **The backing DB stores 32-bit values in big-endian byte order, high word
+  first** — i.e. `ABCD` when viewed as two consecutive Modbus registers. A
+  `Real` at `DB10.DBD0` with value `0x12345678` reads over Modbus as
+  register 0 = `0x1234`, register 1 = `0x5678` [15][16][17].
+- **This is `ABCD`, *not* `CDAB`.** Clients that hard-code CDAB (common default
+  for meters and VFDs) will get wildly wrong floats. Configure the S7 profile
+  with `WordOrder = ABCD` (aka "big-endian word + big-endian byte" aka
+  "high-word first") [15][17].
+- **`MB_SERVER` does not swap.** It's a direct memcpy from the DB bytes to
+  the Modbus payload. Whatever byte order the ladder programmer stored into
+  the DB is what the client receives [17]. This means a programmer who used
+  `MOVE_BLK` from two separate `Word`s into `DBD` with the "wrong" order can
+  produce `CDAB` without realising.
+- **`Real` is IEEE 754 single-precision** — unambiguous, no BCD trap like on
+  DL series [15].
+- **Strings**: S7 `String[n]` has a 2-byte header (max length, current length)
+  *before* the character bytes. A client reading a string over Modbus gets
+  the header in the first register and then the characters two-per-register
+  in high-byte-first order. `WString` is UTF-16 and the header is 4 bytes
+  [18]. Our driver's string decoder must expose the "skip header" option for
+  S7 profile.
+
+### S7-300/400 `MODBUSCP` (CP 343-1 / CP 443-1)
+
+- The CP writes the exact DB bytes onto the wire — again `ABCD` if the DB
+  stores `DInt`/`Real` in native Siemens order [4].
+- **`MODBUSCP` has no `data_type` byte-swap knob.** (The `data_type` parameter
+  names the Modbus table, not the byte order — see the Address Mapping
+  section.) If the other end of the link expects `CDAB`, the programmer has
+  to swap words in ladder before writing the DB [4][14].
+
+### Operator-reported oddity
+
+- Some S7 drivers (Kepware's "Siemens TCP/IP Ethernet" driver, Ignition's
+  "Siemens S7" driver) expose a per-tag `Float Byte Order` with options
+  `ABCD`/`CDAB`/`BADC`/`DCBA` because end-users have encountered every
+  permutation in the field — not because the PLC natively swaps, but because
+  ladder programmers have historically stored floats every which way [19].
+  Our S7 Modbus profile should default to `ABCD` but expose a per-tag
+  override.
+- **Unconfirmed rumour**: that S7-1500 firmware V2.0+ reverses float byte
+  order for `MB_CLIENT` only. Not reproduced; the Siemens forum thread that
+  launched it was a user error (the remote server was the swapper, not the
+  S7) [20]. Treat as false until proven.
+
+Test names:
+`S7_1200_Real_WordOrder_ABCD_Default`,
+`S7_1200_DInt_HighWord_First_At_DBD0`,
+`S7_1200_String_Header_First_Two_Bytes`,
+`S7_CP343_No_Internal_ByteSwap`.
+
+## Coil / Discrete Input Mapping
+
+On `MB_SERVER` the mapping from coil address → S7 bit is fixed at the
+process-image level [1][9][12]:
+
+| Modbus coil / discrete input addr | S7 address    | Notes                               |
+|-----------------------------------|---------------|-------------------------------------|
+| Coil 0 (FC01/05/15)               | `%Q0.0`       | bit 0 of output byte 0              |
+| Coil 7                            | `%Q0.7`       | bit 7 of output byte 0              |
+| Coil 8                            | `%Q1.0`       | bit 0 of output byte 1              |
+| Coil 8191 (max)                   | `%Q1023.7`    | highest exposed output bit          |
+| Discrete input 0 (FC02)           | `%I0.0`       | bit 0 of input byte 0               |
+| Discrete input 8191               | `%I1023.7`    | highest exposed input bit           |
+
+Formulas:
+
+```
+coil_addr   = byte_index * 8 + bit_index    (e.g. %Q5.3 → coil 43)
+discr_addr  = byte_index * 8 + bit_index    (e.g. %I10.2 → disc 82)
+```
+
+- **1-based Modicon form adds 1:** coil 0 (wire) = `00001` (Modicon), etc.
+  Our driver sends the 0-based PDU form, so `%Q0.0` writes to wire address 0.
+- **Writing FC05/FC15 to `%Q` is accepted even while the CPU is in STOP** —
+  the PLC's process image doesn't care about the user program state. But the
+  output won't propagate to the physical module until RUN (see STOP section
+  below) [1][21].
+- **`%M` markers require a DB-backed `Array of Bool`** as described in the
+  Address Mapping section. Our driver can't assume "coil N = MN.0" like it
+  can on Modicon — on S7 it's always Q/I unless the programmer built a
+  mapping DB [12].
+- **Bit-inside-holding-register**: for `Array of Bool` inside the
+  `MB_HOLD_REG` DB, bool[0] is bit 0 of byte 0 → **low byte, low bit** of
+  Modbus register 40001. Most third-party clients probe this in the low
+  byte, so the common case works; the less-common case (bool[8]) is bit 0 of
+  byte 1 → **high byte, low bit** of Modbus register 40001. Clients that
+  test only bool[0] will pass and miss the mis-alignment on bool[8] [12][13].
+
+Test names:
+`S7_1200_Coil_0_Is_Q0_0`,
+`S7_1200_Coil_8_Is_Q1_0`,
+`S7_1200_Discrete_Input_7_Is_I0_7`,
+`S7_1200_Coil_Write_In_STOP_Accepted_But_Output_Frozen`.
+
+## Function Code Support & Max Registers Per Request
+
+| FC | Name                       | S7-1200 / S7-1500 MB_SERVER | CP 343-1 / CP 443-1 MODBUSCP | Max qty per request            |
+|----|----------------------------|-----------------------------|------------------------------|--------------------------------|
+| 01 | Read Coils                 | Yes                         | Yes                          | 2000 bits (spec)               |
+| 02 | Read Discrete Inputs       | Yes                         | Yes                          | 2000 bits (spec)               |
+| 03 | Read Holding Registers     | Yes                         | Yes                          | **125** (spec max)             |
+| 04 | Read Input Registers       | Yes                         | Yes                          | **125**                        |
+| 05 | Write Single Coil          | Yes                         | Yes                          | 1                              |
+| 06 | Write Single Register      | Yes                         | Yes                          | 1                              |
+| 15 | Write Multiple Coils       | Yes                         | Yes                          | 1968 bits (spec) — *see note*  |
+| 16 | Write Multiple Registers   | Yes                         | Yes                          | **123** (spec max for TCP)     |
+| 07 | Read Exception Status      | No (RTU only)               | No                           | —                              |
+| 17 | Report Server ID           | No                          | No                           | —                              |
+| 20/21 | Read/Write File Record  | No                          | No                           | —                              |
+| 22 | Mask Write Register        | No                          | No                           | —                              |
+| 23 | Read/Write Multiple        | No                          | No                           | —                              |
+| 43 | Read Device Identification | No                          | No                           | —                              |
+
+- **S7-1200/1500 honour the full spec maxima** for FC03/04 (125) and FC16
+  (123) [1][22]. No sub-spec cap like DL260's 100-register FC16 limit.
+- **FC15 (Write Multiple Coils) on `MB_SERVER`** writes into `%Q`, which maxes
+  out at 1024 bytes = 8192 bits, but the spec's 1968-bit per-request limit
+  caps any single call first [1][9].
+- **`MB_HOLD_REG` buffer size is bounded by DB size** — max DB size on
+  S7-1200 is 64 KB, on S7-1500 is much larger (several MB depending on CPU),
+  so the practical `MB_HOLD_REG` limit is 32767 16-bit registers on S7-1200
+  and effectively unbounded on S7-1500 [22][23]. The *per-request* limit is
+  still 125.
+- **Read past the end of `MB_HOLD_REG`** returns exception `02` (Illegal
+  Data Address) at the start of the overflow register, not a partial read
+  [1][8].
+- **Request larger than spec max** (e.g. FC03 quantity 126) returns exception
+  `03` (Illegal Data Value). Verified on S7-1200 V4.2 [1][24].
+- **CP 343-1 `MODBUSCP` per-request maxima are spec** (125/125/123/1968/2000),
+  matching the standard [4]. The CP's `MODBUS_PARAM_CP` caps the total
+  *exposed* range, not the per-call quantity.
+
+Test names:
+`S7_1200_FC03_126_Registers_Returns_IllegalDataValue`,
+`S7_1200_FC16_124_Registers_Returns_IllegalDataValue`,
+`S7_1200_FC03_Past_MB_HOLD_REG_End_Returns_IllegalDataAddress`,
+`S7_1200_FC17_ReportServerId_Returns_IllegalFunction`.
+
+## Exception Codes
+
+S7 Modbus servers return only the four standard exception codes [1][4]:
+
+| Code | Name                  | Triggered by                                                         |
+|------|-----------------------|----------------------------------------------------------------------|
+| 01   | Illegal Function      | FC not in the supported list (17, 20-23, 43, any undefined FC)       |
+| 02   | Illegal Data Address  | Register outside `MB_HOLD_REG` / outside `MODBUSCP` param-block range |
+| 03   | Illegal Data Value    | Quantity exceeds spec (FC03/04 > 125, FC16 > 123, FC01/02 > 2000, FC15 > 1968) |
+| 04   | Server Failure        | Runtime error inside MB_SERVER (DB access fault, corrupt DB header, MB_SERVER disabled mid-request) [1][24] |
+
+- **No proprietary exception codes (05/06/0A/0B) are used** on any S7
+  Modbus server [1][4]. Our driver's status-code mapper can treat these as
+  "never observed" on the S7 profile.
+- **CPU in STOP → `MB_SERVER` keeps running if it's in OB1 of the firmware's
+  communication task, but OB1 itself is not scanned.** In practice:
+  - Holding-register *reads* (FC03) continue to return the last DB values
+    frozen at the moment the CPU entered STOP. The `MB_SERVER` block is in
+    OB1 so it isn't re-invoked; however the TCP stack keeps the socket open
+    and returns cached data on subsequent polls [1][21]. **Unconfirmed**
+    whether this is cached in the CP or in the CPU's communication processor;
+    behaviour varies between firmware 4.0 and 4.5 [21].
+  - Holding-register *writes* (FC06/FC16) during STOP return exception `04`
+    (Server Failure) on S7-1200 V4.2+, and return success-but-discarded on
+    older firmware [1][24]. Our driver should treat FC06/FC16 during STOP as
+    non-deterministic and not rely on the response code.
+  - Coil *writes* (FC05/FC15) to `%Q` are *accepted* by the process image
+    during STOP, but the physical output freezes at its last RUN-mode value
+    (or the configured STOP-mode substitute value) until RUN resumes [1][21].
+- **Writing a read-only address via FC06/FC16**: returns `02` (Illegal Data
+  Address), not `04`. S7 does not have "write-protected" holding registers —
+  the programmer either exposes a DB for read-write or doesn't expose it at
+  all [1][12].
+
+STATUS codes (returned in the `STATUS` output of the block, not on the wire):
+
+- `0x0000` — no error.
+- `0x7001` — first call, connection being established.
+- `0x7002` — subsequent cyclic call, connection in progress.
+- `0x8383` — data access error (optimized DB, DB too small, or type mismatch)
+  [10][24].
+- `0x8188` — invalid parameter combination (e.g. MB_MODE out of range) [24].
+- `0x80C8` — mismatched UNIT_ID between MB_CLIENT and `MB_SERVER` [25].
+
+Test names:
+`S7_1200_FC03_Outside_HoldReg_Returns_IllegalDataAddress`,
+`S7_1200_FC16_In_STOP_Returns_ServerFailure`,
+`S7_1200_FC03_In_STOP_Returns_Cached_Values`,
+`S7_1200_No_Proprietary_ExceptionCodes_0x05_0x06_0x0A_0x0B`.
+
+## Connection Behavior
+
+- **Max simultaneous Modbus TCP connections**:
+  - **S7-1200**: shares a pool of 8 open-communication connections across
+    all TCP/UDP/Modbus use. On a CPU 1211C you get 8 total; on 1215C/1217C
+    still 8 shared among PG/HMI/OUC/Modbus. Each `MB_SERVER` instance
+    reserves one. A typical site with a PG + 1 HMI + 2 Modbus clients uses
+    4 of the 8 [1][26].
+  - **S7-1500**: up to **8 concurrent Modbus TCP server connections** per
+    `MB_SERVER` port, across multiple `MB_SERVER` instance DBs each with a
+    unique port. Total open-communication resources depend on CPU (e.g.
+    CPU 1515-2 PN supports 128 OUC connections total; Modbus is a subset)
+    [1][27].
+  - **CP 343-1 Lean**: up to **8** simultaneous Modbus TCP connections on
+    port 502 [4][5]. Exceeding this refuses at TCP accept.
+  - **CP 443-1 Advanced**: up to **16** simultaneous Modbus TCP connections
+    [4].
+- **Multi-connection model on `MB_SERVER`**: one instance DB per connection.
+  An instance DB listening on port 502 serves exactly one connection at a
+  time; to serve N simultaneous clients you need N instance DBs each with a
+  unique port (502/503/504...). **This is a real trap** — most users expect
+  port 502 to multiplex [27][28]. Our driver must not assume port 502 is the
+  only listener.
+- **Keep-alive**: S7-1500's TCP stack does send TCP keepalives (default
+  every ~30 s) but the interval is not exposed as a configurable. S7-1200 is
+  the same. CP 343-1 keepalives are configured via HW Config → CP properties
+  → Options → "Send keepalive" (default **off** on older firmware, default
+  **on** on firmware V3.0+) [1][29]. Driver-side keepalive is still
+  advisable for S7-300/CP 343-1 on old firmware.
+- **Idle-timeout close**: `MB_SERVER` does *not* close idle sockets on its
+  own. However, the TCP stack on S7-1500 will close a socket that fails
+  three consecutive keepalive probes (~2 minutes). Forum reports describe
+  `MB_SERVER` connections "dying overnight" on S7-1500 when an HMI stops
+  polling — the fix is to enable driver-side periodic reads or driver-side
+  TCP keepalive [29][30].
+- **Reconnect after power cycle**: MB_SERVER starts listening ~1-2 seconds
+  after the CPU reaches RUN. If the client reconnects during STARTUP OB
+  (OB100), the connection is refused until OB1 runs the block at least once.
+  Our driver should back off and retry on `ECONNREFUSED` for the first 5
+  seconds after a power-cycle detection [1][24].
+- **Unit Identifier**: `MB_SERVER` accepts **any** Unit ID by default — there
+  is no configurable filter; the PLC ignores the Unit ID field entirely.
+  `MB_CLIENT` defaults to Unit ID = 255 as "ignore" [25][31]. Some
+  third-party Modbus-TCP gateways *require* a specific Unit ID; sending
+  anything to S7 is safe. **CP 343-1 `MODBUSCP`** also accepts any Unit ID
+  in server mode, but the parameter DB exposes a `single_write` / `unit_id`
+  field on newer firmware to allow filtering [4].
+
+Test names:
+`S7_1200_9th_TCP_Connection_Refused_On_8_Conn_Pool`,
+`S7_1500_Port_503_Required_For_Second_Instance`,
+`S7_1200_Reconnect_After_Power_Cycle_Succeeds_Within_5s`,
+`S7_1200_Unit_ID_Ignored_Any_Accepted`.
+
+## Behavioral Oddities
+
+- **Transaction ID echo** is reliable on all S7 variants. `MB_SERVER` copies
+  the MBAP TxId verbatim. No known firmware that drops TxId under load [1][31].
+- **Request serialization**: a single `MB_SERVER` instance serializes
+  requests from its one connected client — the block processes one PDU per
+  call and calls happen once per OB1 scan. OB1 scan time of 5-50 ms puts an
+  upper bound on throughput at ~20-200 requests/sec per connection [1][30].
+  Multiple `MB_SERVER` instances (one per port) run in parallel because OB1
+  calls them sequentially within the same scan.
+- **OB1 scan coupling**: `MB_SERVER` must be called cyclically from OB1 (or
+  another cyclic OB). If the programmer puts it in a conditional branch
+  that doesn't fire every scan, requests time out. The STATUS `0x7002`
+  "in progress" is *expected* between calls, not an error [1][24].
+- **Optimized DB backing `MB_HOLD_REG`** — already covered in Address
+  Mapping; STATUS becomes `0x8383`. This is the most common deployment bug
+  on S7-1500 projects migrated from older S7-1200 examples [10][11].
+- **CPU STOP behaviour** — covered in Exception Codes section. The short
+  version: reads may return stale data without error; writes return exception
+  04 on modern firmware.
+- **Partial-frame disconnect**: S7-1200/1500 TCP stack closes the socket on
+  any MBAP header where the `Length` field doesn't match the PDU length.
+  Driver must detect half-close and reconnect [1][29].
+- **MBAP `Protocol ID` must be 0**. Any non-zero value causes the CP/CPU to
+  drop the frame silently (no response, no RST) on S7-1500 firmware V2.0
+  through V2.9; firmware V3.0+ sends an RST [1][30]. *Unconfirmed* whether
+  V3.1 still sends RST or returns to silent drop.
+- **FC01/FC02 access outside `%Q`/`%I` range**: on S7-1200, requesting
+  coil address 8192 (= `%Q1024.0`) returns exception `02` (Illegal Data
+  Address) [1][9]. The 8192-bit hard cap is a process-image size limit on
+  the CPU, not a Modbus protocol limit.
+- **`MB_CLIENT` UNIT_ID mismatch with remote `MB_SERVER`** produces STATUS
+  `0x80C8` on the client side, and the server silently discards the frame
+  (no response on the wire) [25]. This matters for Modbus-TCP-to-RTU
+  gateway scenarios where the Unit ID picks the RTU slave.
+- **Non-IEEE REAL / BCD**: S7 does *not* use BCD like DirectLOGIC. `Real` is
+  always IEEE 754 single-precision. `LReal` (8-byte double) occupies 4
+  Modbus registers in `ABCDEFGH` order (big-endian byte, big-endian word)
+  [15][18].
+- **`MODBUSCP` single-write** on CP 343-1: a parameter `single_write` in the
+  param DB controls whether FC06 on a register in the "holding register"
+  area triggers a callback to the user program vs. updates the DB directly.
+  Default is direct update. If a ladder programmer enables the callback
+  without implementing the callback OB, FC06 writes hang for 5 seconds then
+  return exception `04` [4].
+
+Test names:
+`S7_1200_TxId_Preserved_Across_Burst_Of_50_Requests`,
+`S7_1200_MBSERVER_Throughput_Capped_By_OB1_Scan`,
+`S7_1200_MBAP_ProtocolID_NonZero_Frame_Dropped`,
+`S7_1200_Partial_MBAP_Causes_Half_Close`.
+
+## Model-specific Differences Worth Separate Test Coverage
+
+- **S7-1200 V4.0 vs V4.4+**: Older firmware does not support `WString` over
+  `MB_HOLD_REG` and returns `0x8383` if the DB contains one [18][24]. Test
+  both firmware bands separately.
+- **S7-1500 vs S7-1200**: S7-1500 supports multiple `MB_SERVER` instances on
+  the *same* CPU with different ports cleanly; S7-1200 can too but its
+  8-connection pool is shared tighter [1][27]. Throughput per-connection is
+  ~5× faster on S7-1500 because the comms task runs on a dedicated core.
+- **S7-300 + CP 343-1 vs S7-1200/1500**: parameter-block mapping (not
+  `MB_HOLD_REG` pointer), per-connection license, no `%Q`/`%I` direct
+  access for coils (everything goes through a DB), different STATUS codes
+  (`DONE`/`ERROR`/`STATUS` word pairs vs. the single STATUS word) [4][14].
+  Driver-side it's a different profile.
+- **CP 343-1 Lean vs CP 343-1 Advanced**: Lean is server-only; Advanced is
+  client + server. Lean's max connections = 8; Advanced = 16 [4][5].
+- **CP 443-1 in S7-400H**: uses `MODBUSCP_REDUNDANT` which presents two
+  Ethernet endpoints that fail over. Our driver's redundancy support should
+  recognize the S7-400H profile as "two IP addresses, same server state,
+  advertise via `ServerUriArray`" [6].
+- **ET 200SP CPU (1510SP / 1512SP)**: behaves as S7-1500 from `MB_SERVER`
+  perspective. No known deltas [3].
+
+## References
+
+1. Siemens Industry Online Support, *Modbus/TCP Communication between SIMATIC S7-1500 / S7-1200 and Modbus/TCP Controllers with Instructions `MB_CLIENT` and `MB_SERVER`*, Entry ID 102020340, V6 (Feb 2021). https://cache.industry.siemens.com/dl/files/340/102020340/att_118119/v6/net_modbus_tcp_s7-1500_s7-1200_en.pdf
+2. Siemens TIA Portal Online Docs, *MB_SERVER instruction*. https://docs.tia.siemens.cloud/r/simatic_s7_1200_manual_collection_eses_20/communication-processor-and-modbus-tcp/modbus-communication/modbus-tcp/modbus-tcp-instructions/mb_server-communicate-using-profinet-as-modbus-tcp-server-instruction
+3. Siemens, *SIMATIC S7-1500 Communication Function Manual* (covers ET 200SP CPU). http://public.eandm.com/Public_Docs/s71500_communication_function_manual_en-US_en-US.pdf
+4. Siemens Industry Online Support, *SIMATIC Modbus/TCP communication using CP 343-1 and CP 443-1 — Programming Manual*, Entry ID 103447617. https://cache.industry.siemens.com/dl/files/617/103447617/att_106971/v1/simatic_modbus_tcp_cp_en-US_en-US.pdf
+5. Siemens Industry Online Support FAQ *"Which technical data applies for the SIMATIC Modbus/TCP software for CP 343-1 / CP 443-1?"*, Entry ID 104946406. https://www.industry-mobile-support.siemens-info.com/en/article/detail/104946406
+6. Siemens Industry Online Support, *Redundant Modbus/TCP communication via CP 443-1 in S7-400H systems*, Entry ID 109739212. https://cache.industry.siemens.com/dl/files/212/109739212/att_887886/v1/SIMATIC_modbus_tcp_cp_red_e_en-US.pdf
+7. Siemens Industry Online Support, *SIMATIC MODBUS (TCP) PN CPU Library — Programming and Operating Manual 06/2014*, Entry ID 75330636. https://support.industry.siemens.com/cs/attachments/75330636/ModbusTCPPNCPUen.pdf
+8. DMC Inc., *Using an S7-1200 PLC as a Modbus TCP Slave*. https://www.dmcinfo.com/blog/27313/using-an-s7-1200-plc-as-a-modbus-tcp-slave/
+9. Siemens, *SIMATIC S7-1200 System Manual* (V4.x), "MB_SERVER" pages 736-742. https://www.manualslib.com/manual/1453610/Siemens-S7-1200.html?page=736
+10. lamaPLC, *Simatic Modbus S7 error- and statuscodes*. https://www.lamaplc.com/doku.php?id=simatic:errorcodes
+11. ScadaProtocols, *How to Configure Modbus TCP on Siemens S7-1200 (TIA Portal Step-by-Step)*. https://scadaprotocols.com/modbus-tcp-siemens-s7-1200-tia-portal/
+12. Industrial Monitor Direct, *Reading and Writing Memory Bits via Modbus TCP on S7-1200*. https://industrialmonitordirect.com/blogs/knowledgebase/reading-and-writing-memory-bits-via-modbus-tcp-on-s7-1200
+13. PLCtalk forum *"Siemens S7-1200 modbus understanding"*. https://www.plctalk.net/forums/threads/siemens-s7-1200-modbus-understanding.104119/
+14. Siemens SIMATIC S7 Manual, "Function block MODBUSCP — Functionality" (ManualsLib p29). https://www.manualslib.com/manual/1580661/Siemens-Simatic-S7.html?page=29
+15. Chipkin, *How Real (Floating Point) and 32-bit Data is Encoded in Modbus*. https://store.chipkin.com/articles/how-real-floating-point-and-32-bit-data-is-encoded-in-modbus-rtu-messages
+16. Siemens Industry Online Support forum, *MODBUS DATA conversion in S7-1200 CPU*, Entry ID 97287. https://support.industry.siemens.com/forum/WW/en/posts/modbus-data-converson-in-s7-1200-cpu/97287
+17. Industrial Monitor Direct, *Siemens S7-1500 MB_SERVER Modbus TCP Configuration Guide*. https://industrialmonitordirect.com/de/blogs/knowledgebase/siemens-s7-1500-mb-server-modbus-tcp-configuration-guide
+18. Siemens TIA Portal, *Data types in SIMATIC S7-1200/1500 — String/WString header layout* (system manual, "Elementary Data Types").
+19. Kepware / PTC, *Siemens TCP/IP Ethernet Driver Help*, "Byte / Word Order" tag property. https://www.opcturkey.com/uploads/siemens-tcp-ip-ethernet-manual.pdf
+20. Siemens SiePortal forum, *Transfer float out of words*, Entry ID 187811. https://sieportal.siemens.com/en-ww/support/forum/posts/transfer-float-out-of-words/187811 _(operator-reported "S7 swaps float" claim — traced to remote-device issue; **unconfirmed**.)_
+21. Siemens SiePortal forum, *S7-1200 communication with Modbus TCP*, Entry ID 133086. https://support.industry.siemens.com/forum/WW/en/posts/s7-1200-communication-with-modbus-tcp/133086
+22. Siemens SiePortal forum, *S7-1500 MB Server Holding Register Max Word*, Entry ID 224636. https://support.industry.siemens.com/forum/WW/en/posts/s7-1500-mb-server-holding-register-max-word/224636
+23. Siemens, *SIMATIC S7-1500 Technical Specifications* — CPU-specific DB size limits in each CPU manual's "Memory" table.
+24. Siemens TIA Portal Online Docs, *Error messages (S7-1200, S7-1500) — Modbus instructions*. https://docs.tia.siemens.cloud/r/en-us/v20/modbus-rtu-s7-1200-s7-1500/error-messages-s7-1200-s7-1500
+25. Industrial Monitor Direct, *Fix Siemens S7-1500 MB_Client UnitID Error 80C8*. https://industrialmonitordirect.com/blogs/knowledgebase/troubleshooting-mb-client-on-s7-1500-cpu-1515sp-modbus-tcp
+26. Siemens SiePortal forum, *How many TCP connections can the S7-1200 make?*, Entry ID 275570. https://support.industry.siemens.com/forum/WW/en/posts/how-many-tcp-connections-can-the-s7-1200-make/275570
+27. Siemens SiePortal forum, *Simultaneous connections of Modbus TCP*, Entry ID 189626. https://support.industry.siemens.com/forum/ww/en/posts/simultaneous-connections-of-modbus-tcp/189626
+28. Siemens SiePortal forum, *How many Modbus TCP IP clients can read simultaneously from S7-1517*, Entry ID 261569. https://support.industry.siemens.com/forum/WW/en/posts/how-many-modbus-tcp-ip-client-can-read-simultaneously-in-s7-1517/261569
+29. Industrial Monitor Direct, *Troubleshooting Intermittent Modbus TCP Connections on S7-1500 PLC*. https://industrialmonitordirect.com/blogs/knowledgebase/troubleshooting-intermittent-modbus-tcp-connections-on-s7-1500-plc
+30. PLCtalk forum *"S7-1500 modbus tcp speed?"*. https://www.plctalk.net/forums/threads/s7-1500-modbus-tcp-speed.114046/
+31. Siemens SiePortal forum, *MB_Unit_ID parameter in Modbus TCP*, Entry ID 156635. https://support.industry.siemens.com/forum/WW/en/posts/mb-unit-id-parameter-in-modbus-tcp/156635

src/ZB.MOM.WW.OtOpcUa.Driver.Modbus/DirectLogicAddress.cs

@@ -0,0 +1,165 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
+
+/// <summary>
+///     AutomationDirect DirectLOGIC address-translation helpers. DL205 / DL260 / DL350 CPUs
+///     address V-memory in OCTAL while the Modbus wire uses DECIMAL PDU addresses — operators
+///     see "V2000" in the PLC ladder-logic editor but the Modbus client must write PDU 0x0400.
+///     The formulas differ between user V-memory (simple octal-to-decimal) and system V-memory
+///     (fixed bank mappings), so the two cases are separate methods rather than one overloaded
+///     "ToPdu" call.
+/// </summary>
+/// <remarks>
+///     See <c>docs/v2/dl205.md</c> §V-memory for the full CPU-family matrix + rationale.
+///     References: D2-USER-M appendix (DL205/D2-260), H2-ECOM-M §6.5 (absolute vs relative
+///     addressing), AutomationDirect forum guidance on V40400 system-base.
+/// </remarks>
+public static class DirectLogicAddress
+{
+    /// <summary>
+    ///     Convert a DirectLOGIC user V-memory address (octal) to a 0-based Modbus PDU address.
+    ///     Accepts bare octal (<c>"2000"</c>) or <c>V</c>-prefixed (<c>"V2000"</c>). Range
+    ///     depends on CPU model — DL205 D2-260 user memory is V1400-V7377 + V10000-V17777
+    ///     octal, DL260 extends to V77777 octal.
+    /// </summary>
+    /// <exception cref="ArgumentException">Input is null / empty / contains non-octal digits (8,9).</exception>
+    /// <exception cref="OverflowException">Parsed value exceeds ushort.MaxValue (0xFFFF).</exception>
+    public static ushort UserVMemoryToPdu(string vAddress)
+    {
+        if (string.IsNullOrWhiteSpace(vAddress))
+            throw new ArgumentException("V-memory address must not be empty", nameof(vAddress));
+        var s = vAddress.Trim();
+        if (s[0] == 'V' || s[0] == 'v') s = s.Substring(1);
+        if (s.Length == 0)
+            throw new ArgumentException($"V-memory address '{vAddress}' has no digits", nameof(vAddress));
+
+        // Octal conversion. Reject 8/9 digits up-front — int.Parse in the obvious base would
+        // accept them silently because .NET has no built-in base-8 parser.
+        uint result = 0;
+        foreach (var ch in s)
+        {
+            if (ch < '0' || ch > '7')
+                throw new ArgumentException(
+                    $"V-memory address '{vAddress}' contains non-octal digit '{ch}' — DirectLOGIC V-addresses are octal (0-7)",
+                    nameof(vAddress));
+            result = result * 8 + (uint)(ch - '0');
+            if (result > ushort.MaxValue)
+                throw new OverflowException(
+                    $"V-memory address '{vAddress}' exceeds the 16-bit Modbus PDU address range");
+        }
+        return (ushort)result;
+    }
+
+    /// <summary>
+    ///     DirectLOGIC system V-memory starts at octal V40400 on DL260 / H2-ECOM100 in factory
+    ///     "absolute" addressing mode. Unlike user V-memory, the mapping is NOT a simple
+    ///     octal-to-decimal conversion — the CPU relocates the system bank to Modbus PDU 0x2100
+    ///     (decimal 8448). This helper returns the CPU-family base plus a user-supplied offset
+    ///     within the system bank.
+    /// </summary>
+    public const ushort SystemVMemoryBasePdu = 0x2100;
+
+    /// <param name="offsetWithinSystemBank">
+    ///     0-based register offset within the system bank. Pass 0 for V40400 itself; pass 1 for
+    ///     V40401 (octal), and so on. NOT an octal-decoded value — the system bank lives at
+    ///     consecutive PDU addresses, so the offset is plain decimal.
+    /// </param>
+    public static ushort SystemVMemoryToPdu(ushort offsetWithinSystemBank)
+    {
+        var pdu = SystemVMemoryBasePdu + offsetWithinSystemBank;
+        if (pdu > ushort.MaxValue)
+            throw new OverflowException(
+                $"System V-memory offset {offsetWithinSystemBank} maps past 0xFFFF");
+        return (ushort)pdu;
+    }
+
+    // Bit-memory bases per DL260 user manual §I/O-configuration.
+    // Numbers after X / Y / C / SP are OCTAL in DirectLOGIC notation. The Modbus base is
+    // added to the octal-decoded offset; e.g. Y017 = Modbus coil 2048 + octal(17) = 2048 + 15 = 2063.
+
+    /// <summary>
+    ///     DL260 Y-output coil base. Y0 octal → Modbus coil address 2048 (0-based).
+    /// </summary>
+    public const ushort YOutputBaseCoil = 2048;
+
+    /// <summary>
+    ///     DL260 C-relay coil base. C0 octal → Modbus coil address 3072 (0-based).
+    /// </summary>
+    public const ushort CRelayBaseCoil = 3072;
+
+    /// <summary>
+    ///     DL260 X-input discrete-input base. X0 octal → Modbus discrete input 0.
+    /// </summary>
+    public const ushort XInputBaseDiscrete = 0;
+
+    /// <summary>
+    ///     DL260 SP special-relay discrete-input base. SP0 octal → Modbus discrete input 1024.
+    ///     Read-only; writing SP relays is rejected with Illegal Data Address.
+    /// </summary>
+    public const ushort SpecialBaseDiscrete = 1024;
+
+    /// <summary>
+    ///     Translate a DirectLOGIC Y-output address (e.g. <c>"Y0"</c>, <c>"Y17"</c>) to its
+    ///     0-based Modbus coil address on DL260. The trailing number is OCTAL, matching the
+    ///     ladder-logic editor's notation.
+    /// </summary>
+    public static ushort YOutputToCoil(string yAddress) =>
+        AddOctalOffset(YOutputBaseCoil, StripPrefix(yAddress, 'Y'));
+
+    /// <summary>
+    ///     Translate a DirectLOGIC C-relay address (e.g. <c>"C0"</c>, <c>"C1777"</c>) to its
+    ///     0-based Modbus coil address.
+    /// </summary>
+    public static ushort CRelayToCoil(string cAddress) =>
+        AddOctalOffset(CRelayBaseCoil, StripPrefix(cAddress, 'C'));
+
+    /// <summary>
+    ///     Translate a DirectLOGIC X-input address (e.g. <c>"X0"</c>, <c>"X17"</c>) to its
+    ///     0-based Modbus discrete-input address. Reading an unpopulated X returns 0, not an
+    ///     exception — the CPU sizes the table to configured I/O, not installed modules.
+    /// </summary>
+    public static ushort XInputToDiscrete(string xAddress) =>
+        AddOctalOffset(XInputBaseDiscrete, StripPrefix(xAddress, 'X'));
+
+    /// <summary>
+    ///     Translate a DirectLOGIC SP-special-relay address (e.g. <c>"SP0"</c>) to its 0-based
+    ///     Modbus discrete-input address. Accepts <c>"SP"</c> prefix case-insensitively.
+    /// </summary>
+    public static ushort SpecialToDiscrete(string spAddress)
+    {
+        if (string.IsNullOrWhiteSpace(spAddress))
+            throw new ArgumentException("SP address must not be empty", nameof(spAddress));
+        var s = spAddress.Trim();
+        if (s.Length >= 2 && (s[0] == 'S' || s[0] == 's') && (s[1] == 'P' || s[1] == 'p'))
+            s = s.Substring(2);
+        return AddOctalOffset(SpecialBaseDiscrete, s);
+    }
+
+    private static string StripPrefix(string address, char expectedPrefix)
+    {
+        if (string.IsNullOrWhiteSpace(address))
+            throw new ArgumentException("Address must not be empty", nameof(address));
+        var s = address.Trim();
+        if (s.Length > 0 && char.ToUpperInvariant(s[0]) == char.ToUpperInvariant(expectedPrefix))
+            s = s.Substring(1);
+        return s;
+    }
+
+    private static ushort AddOctalOffset(ushort baseAddr, string octalDigits)
+    {
+        if (octalDigits.Length == 0)
+            throw new ArgumentException("Address has no digits", nameof(octalDigits));
+        uint offset = 0;
+        foreach (var ch in octalDigits)
+        {
+            if (ch < '0' || ch > '7')
+                throw new ArgumentException(
+                    $"Address contains non-octal digit '{ch}' — DirectLOGIC I/O addresses are octal (0-7)",
+                    nameof(octalDigits));
+            offset = offset * 8 + (uint)(ch - '0');
+        }
+        var result = baseAddr + offset;
+        if (result > ushort.MaxValue)
+            throw new OverflowException($"Address {baseAddr}+{offset} exceeds 0xFFFF");
+        return (ushort)result;
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusDriver.cs

@@ -37,7 +37,7 @@ public sealed class ModbusDriver(ModbusDriverOptions options, string driverInsta
     private CancellationTokenSource? _probeCts;
     private readonly ModbusDriverOptions _options = options;
     private readonly Func<ModbusDriverOptions, IModbusTransport> _transportFactory =
-        transportFactory ?? (o => new ModbusTcpTransport(o.Host, o.Port, o.Timeout));
+        transportFactory ?? (o => new ModbusTcpTransport(o.Host, o.Port, o.Timeout, o.AutoReconnect));
 
     private IModbusTransport? _transport;
     private DriverHealth _health = new(DriverState.Unknown, null, null);
@@ -141,9 +141,16 @@ public sealed class ModbusDriver(ModbusDriverOptions options, string driverInsta
                 results[i] = new DataValueSnapshot(value, 0u, now, now);
                 _health = new DriverHealth(DriverState.Healthy, now, null);
             }
+            catch (ModbusException mex)
+            {
+                results[i] = new DataValueSnapshot(null, MapModbusExceptionToStatus(mex.ExceptionCode), null, now);
+                _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, mex.Message);
+            }
             catch (Exception ex)
             {
-                results[i] = new DataValueSnapshot(null, StatusBadInternalError, null, now);
+                // Non-Modbus-layer failure: socket dropped, timeout, malformed response. Surface
+                // as communication error so callers can distinguish it from tag-level faults.
+                results[i] = new DataValueSnapshot(null, StatusBadCommunicationError, null, now);
                 _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead, ex.Message);
             }
         }
@@ -171,11 +178,14 @@ public sealed class ModbusDriver(ModbusDriverOptions options, string driverInsta
             {
                 var quantity = RegisterCount(tag);
                 var fc = tag.Region == ModbusRegion.HoldingRegisters ? (byte)0x03 : (byte)0x04;
-                var pdu = new byte[] { fc, (byte)(tag.Address >> 8), (byte)(tag.Address & 0xFF),
-                                       (byte)(quantity >> 8), (byte)(quantity & 0xFF) };
-                var resp = await transport.SendAsync(_options.UnitId, pdu, ct).ConfigureAwait(false);
-                // resp = [fc][byte-count][data...]
-                var data = new ReadOnlySpan<byte>(resp, 2, resp[1]);
+                // Auto-chunk when the tag's register span exceeds the caller-configured cap.
+                // Affects long strings (FC03/04 > 125 regs is spec-forbidden; DL205 caps at 128,
+                // Mitsubishi Q caps at 64). Non-string tags max out at 4 regs so the cap never
+                // triggers for numerics.
+                var cap = _options.MaxRegistersPerRead == 0 ? (ushort)125 : _options.MaxRegistersPerRead;
+                var data = quantity <= cap
+                    ? await ReadRegisterBlockAsync(transport, fc, tag.Address, quantity, ct).ConfigureAwait(false)
+                    : await ReadRegisterBlockChunkedAsync(transport, fc, tag.Address, quantity, cap, ct).ConfigureAwait(false);
                 return DecodeRegister(data, tag);
             }
             default:
@@ -183,6 +193,33 @@ public sealed class ModbusDriver(ModbusDriverOptions options, string driverInsta
         }
     }
 
+    private async Task<byte[]> ReadRegisterBlockAsync(
+        IModbusTransport transport, byte fc, ushort address, ushort quantity, CancellationToken ct)
+    {
+        var pdu = new byte[] { fc, (byte)(address >> 8), (byte)(address & 0xFF),
+                               (byte)(quantity >> 8), (byte)(quantity & 0xFF) };
+        var resp = await transport.SendAsync(_options.UnitId, pdu, ct).ConfigureAwait(false);
+        // resp = [fc][byte-count][data...]
+        var data = new byte[resp[1]];
+        Buffer.BlockCopy(resp, 2, data, 0, resp[1]);
+        return data;
+    }
+
+    private async Task<byte[]> ReadRegisterBlockChunkedAsync(
+        IModbusTransport transport, byte fc, ushort address, ushort totalRegs, ushort cap, CancellationToken ct)
+    {
+        var assembled = new byte[totalRegs * 2];
+        ushort done = 0;
+        while (done < totalRegs)
+        {
+            var chunk = (ushort)Math.Min(cap, totalRegs - done);
+            var chunkBytes = await ReadRegisterBlockAsync(transport, fc, (ushort)(address + done), chunk, ct).ConfigureAwait(false);
+            Buffer.BlockCopy(chunkBytes, 0, assembled, done * 2, chunkBytes.Length);
+            done += chunk;
+        }
+        return assembled;
+    }
+
     // ---- IWritable ----
 
     public async Task<IReadOnlyList<WriteResult>> WriteAsync(
@@ -208,6 +245,10 @@ public sealed class ModbusDriver(ModbusDriverOptions options, string driverInsta
                 await WriteOneAsync(transport, tag, w.Value, cancellationToken).ConfigureAwait(false);
                 results[i] = new WriteResult(0u);
             }
+            catch (ModbusException mex)
+            {
+                results[i] = new WriteResult(MapModbusExceptionToStatus(mex.ExceptionCode));
+            }
             catch (Exception)
             {
                 results[i] = new WriteResult(StatusBadInternalError);
@@ -239,8 +280,13 @@ public sealed class ModbusDriver(ModbusDriverOptions options, string driverInsta
                 }
                 else
                 {
-                    // FC 16 (Write Multiple Registers) for 32-bit types
+                    // FC 16 (Write Multiple Registers) for 32-bit types.
                     var qty = (ushort)(bytes.Length / 2);
+                    var writeCap = _options.MaxRegistersPerWrite == 0 ? (ushort)123 : _options.MaxRegistersPerWrite;
+                    if (qty > writeCap)
+                        throw new InvalidOperationException(
+                            $"Write of {qty} registers to {tag.Name} exceeds MaxRegistersPerWrite={writeCap}. " +
+                            $"Split the tag (e.g. shorter StringLength) — partial FC16 chunks would lose atomicity.");
                     var pdu = new byte[6 + 1 + bytes.Length];
                     pdu[0] = 0x10;
                     pdu[1] = (byte)(tag.Address >> 8); pdu[2] = (byte)(tag.Address & 0xFF);
@@ -404,8 +450,8 @@ public sealed class ModbusDriver(ModbusDriverOptions options, string driverInsta
     /// </summary>
     internal static ushort RegisterCount(ModbusTagDefinition tag) => tag.DataType switch
     {
-        ModbusDataType.Int16 or ModbusDataType.UInt16 or ModbusDataType.BitInRegister => 1,
-        ModbusDataType.Int32 or ModbusDataType.UInt32 or ModbusDataType.Float32 => 2,
+        ModbusDataType.Int16 or ModbusDataType.UInt16 or ModbusDataType.BitInRegister or ModbusDataType.Bcd16 => 1,
+        ModbusDataType.Int32 or ModbusDataType.UInt32 or ModbusDataType.Float32 or ModbusDataType.Bcd32 => 2,
         ModbusDataType.Int64 or ModbusDataType.UInt64 or ModbusDataType.Float64 => 4,
         ModbusDataType.String => (ushort)((tag.StringLength + 1) / 2), // 2 chars per register
         _ => throw new InvalidOperationException($"Non-register data type {tag.DataType}"),
@@ -435,6 +481,17 @@ public sealed class ModbusDriver(ModbusDriverOptions options, string driverInsta
         {
             case ModbusDataType.Int16: return BinaryPrimitives.ReadInt16BigEndian(data);
             case ModbusDataType.UInt16: return BinaryPrimitives.ReadUInt16BigEndian(data);
+            case ModbusDataType.Bcd16:
+            {
+                var raw = BinaryPrimitives.ReadUInt16BigEndian(data);
+                return (int)DecodeBcd(raw, nibbles: 4);
+            }
+            case ModbusDataType.Bcd32:
+            {
+                var b = NormalizeWordOrder(data, tag.ByteOrder);
+                var raw = BinaryPrimitives.ReadUInt32BigEndian(b);
+                return (int)DecodeBcd(raw, nibbles: 8);
+            }
             case ModbusDataType.BitInRegister:
             {
                 var raw = BinaryPrimitives.ReadUInt16BigEndian(data);
@@ -510,6 +567,21 @@ public sealed class ModbusDriver(ModbusDriverOptions options, string driverInsta
                 var v = Convert.ToUInt16(value);
                 var b = new byte[2]; BinaryPrimitives.WriteUInt16BigEndian(b, v); return b;
             }
+            case ModbusDataType.Bcd16:
+            {
+                var v = Convert.ToUInt32(value);
+                if (v > 9999) throw new OverflowException($"BCD16 value {v} exceeds 4 decimal digits");
+                var raw = (ushort)EncodeBcd(v, nibbles: 4);
+                var b = new byte[2]; BinaryPrimitives.WriteUInt16BigEndian(b, raw); return b;
+            }
+            case ModbusDataType.Bcd32:
+            {
+                var v = Convert.ToUInt32(value);
+                if (v > 99_999_999u) throw new OverflowException($"BCD32 value {v} exceeds 8 decimal digits");
+                var raw = EncodeBcd(v, nibbles: 8);
+                var b = new byte[4]; BinaryPrimitives.WriteUInt32BigEndian(b, raw);
+                return NormalizeWordOrder(b, tag.ByteOrder);
+            }
             case ModbusDataType.Int32:
             {
                 var v = Convert.ToInt32(value);
@@ -579,15 +651,77 @@ public sealed class ModbusDriver(ModbusDriverOptions options, string driverInsta
         ModbusDataType.Float32 => DriverDataType.Float32,
         ModbusDataType.Float64 => DriverDataType.Float64,
         ModbusDataType.String => DriverDataType.String,
+        ModbusDataType.Bcd16 or ModbusDataType.Bcd32 => DriverDataType.Int32,
         _ => DriverDataType.Int32,
     };
 
+    /// <summary>
+    ///     Decode an N-nibble binary-coded-decimal value. Each nibble of <paramref name="raw"/>
+    ///     encodes one decimal digit (most-significant nibble first). Rejects nibbles &gt; 9 —
+    ///     the hardware sometimes produces garbage during transitions and silent non-BCD reads
+    ///     would quietly corrupt the caller's data.
+    /// </summary>
+    internal static uint DecodeBcd(uint raw, int nibbles)
+    {
+        uint result = 0;
+        for (var i = nibbles - 1; i >= 0; i--)
+        {
+            var digit = (raw >> (i * 4)) & 0xF;
+            if (digit > 9)
+                throw new InvalidDataException(
+                    $"Non-BCD nibble 0x{digit:X} at position {i} of raw=0x{raw:X}");
+            result = result * 10 + digit;
+        }
+        return result;
+    }
+
+    /// <summary>
+    ///     Encode a decimal value as N-nibble BCD. Caller is responsible for range-checking
+    ///     against the nibble capacity (10^nibbles - 1).
+    /// </summary>
+    internal static uint EncodeBcd(uint value, int nibbles)
+    {
+        uint result = 0;
+        for (var i = 0; i < nibbles; i++)
+        {
+            var digit = value % 10;
+            result |= digit << (i * 4);
+            value /= 10;
+        }
+        return result;
+    }
+
     private IModbusTransport RequireTransport() =>
         _transport ?? throw new InvalidOperationException("ModbusDriver not initialized");
 
     private const uint StatusBadInternalError = 0x80020000u;
     private const uint StatusBadNodeIdUnknown = 0x80340000u;
     private const uint StatusBadNotWritable = 0x803B0000u;
+    private const uint StatusBadOutOfRange = 0x803C0000u;
+    private const uint StatusBadNotSupported = 0x803D0000u;
+    private const uint StatusBadDeviceFailure = 0x80550000u;
+    private const uint StatusBadCommunicationError = 0x80050000u;
+
+    /// <summary>
+    ///     Map a server-returned Modbus exception code to the most informative OPC UA
+    ///     StatusCode. Keeps the driver's outward-facing status surface aligned with what a
+    ///     Modbus engineer would expect when reading the spec: exception 02 (Illegal Data
+    ///     Address) surfaces as BadOutOfRange so clients can distinguish "tag wrong" from
+    ///     generic BadInternalError, exception 04 (Server Failure) as BadDeviceFailure so
+    ///     operators see a CPU-mode problem rather than a driver bug, etc. Per
+    ///     <c>docs/v2/dl205.md</c>, DL205/DL260 returns only codes 01-04 — no proprietary
+    ///     extensions.
+    /// </summary>
+    internal static uint MapModbusExceptionToStatus(byte exceptionCode) => exceptionCode switch
+    {
+        0x01 => StatusBadNotSupported,     // Illegal Function — FC not in supported list
+        0x02 => StatusBadOutOfRange,       // Illegal Data Address — register outside mapped range
+        0x03 => StatusBadOutOfRange,       // Illegal Data Value — quantity over per-FC cap
+        0x04 => StatusBadDeviceFailure,    // Server Failure — CPU in PROGRAM mode during protected write
+        0x05 or 0x06 => StatusBadDeviceFailure, // Acknowledge / Server Busy — long-running op / busy
+        0x0A or 0x0B => StatusBadCommunicationError, // Gateway path unavailable / target failed to respond
+        _ => StatusBadInternalError,
+    };
 
     public void Dispose() => DisposeAsync().AsTask().GetAwaiter().GetResult();
     public async ValueTask DisposeAsync()

src/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusDriverOptions.cs

@@ -25,6 +25,37 @@ public sealed class ModbusDriverOptions
     ///     <see cref="IHostConnectivityProbe"/>.
     /// </summary>
     public ModbusProbeOptions Probe { get; init; } = new();
+
+    /// <summary>
+    ///     Maximum registers per FC03 (Read Holding Registers) / FC04 (Read Input Registers)
+    ///     transaction. Modbus-TCP spec allows 125; many device families impose lower caps:
+    ///     AutomationDirect DL205/DL260 cap at <c>128</c>, Mitsubishi Q/FX3U cap at <c>64</c>,
+    ///     Omron CJ/CS cap at <c>125</c>. Set to the lowest cap across the devices this driver
+    ///     instance talks to; the driver auto-chunks larger reads into consecutive requests.
+    ///     Default <c>125</c> — the spec maximum, safe against any conforming server. Setting
+    ///     to <c>0</c> disables the cap (discouraged — the spec upper bound still applies).
+    /// </summary>
+    public ushort MaxRegistersPerRead { get; init; } = 125;
+
+    /// <summary>
+    ///     Maximum registers per FC16 (Write Multiple Registers) transaction. Spec maximum is
+    ///     <c>123</c>; DL205/DL260 cap at <c>100</c>. Matching caller-vs-device semantics:
+    ///     exceeding the cap currently throws (writes aren't auto-chunked because a partial
+    ///     write across two FC16 calls is no longer atomic — caller must explicitly opt in
+    ///     by shortening the tag's <c>StringLength</c> or splitting it into multiple tags).
+    /// </summary>
+    public ushort MaxRegistersPerWrite { get; init; } = 123;
+
+    /// <summary>
+    ///     When <c>true</c> (default) the built-in <see cref="ModbusTcpTransport"/> detects
+    ///     mid-transaction socket failures (<see cref="System.IO.EndOfStreamException"/>,
+    ///     <see cref="System.Net.Sockets.SocketException"/>) and transparently reconnects +
+    ///     retries the PDU exactly once. Required for DL205/DL260 because the H2-ECOM100
+    ///     does not send TCP keepalives — intermediate NAT / firewall devices silently close
+    ///     idle sockets and the first send after the drop would otherwise surface as a
+    ///     connection error to the caller even though the PLC is up.
+    /// </summary>
+    public bool AutoReconnect { get; init; } = true;
 }
 
 public sealed class ModbusProbeOptions
@@ -89,6 +120,18 @@ public enum ModbusDataType
     BitInRegister,
     /// <summary>ASCII string packed 2 chars per register, <see cref="ModbusTagDefinition.StringLength"/> characters long.</summary>
     String,
+    /// <summary>
+    ///     16-bit binary-coded decimal. Each nibble encodes one decimal digit (0-9). Register
+    ///     value <c>0x1234</c> decodes as decimal <c>1234</c> — NOT binary <c>0x04D2 = 4660</c>.
+    ///     DL205/DL260 and several Mitsubishi / Omron families store timers, counters, and
+    ///     operator-facing numerics as BCD by default.
+    /// </summary>
+    Bcd16,
+    /// <summary>
+    ///     32-bit (two-register) BCD. Decodes 8 decimal digits. Word ordering follows
+    ///     <see cref="ModbusTagDefinition.ByteOrder"/> the same way <see cref="Int32"/> does.
+    /// </summary>
+    Bcd32,
 }
 
 /// <summary>

src/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusTcpTransport.cs

@@ -8,22 +8,40 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
 ///     support concurrent transactions, but the single-flight model keeps the wire trace
 ///     easy to diagnose and avoids interleaved-response correlation bugs.
 /// </summary>
+/// <remarks>
+///     <para>
+///         Survives mid-transaction socket drops: when a send/read fails with a socket-level
+///         error (<see cref="IOException"/>, <see cref="SocketException"/>, <see cref="EndOfStreamException"/>)
+///         the transport disposes the dead socket, reconnects, and retries the PDU exactly
+///         once. Deliberately limited to a single retry — further failures bubble up so the
+///         driver's health surface reflects the real state instead of masking a dead PLC.
+///     </para>
+///     <para>
+///         Why this matters for DL205/DL260: the AutomationDirect H2-ECOM100 does NOT send
+///         TCP keepalives per <c>docs/v2/dl205.md</c> §behavioral-oddities, so any NAT/firewall
+///         between the gateway and PLC can silently close an idle socket after 2-5 minutes.
+///         Also enables OS-level <c>SO_KEEPALIVE</c> so the driver's own side detects a stuck
+///         socket in reasonable time even when the application is mostly idle.
+///     </para>
+/// </remarks>
 public sealed class ModbusTcpTransport : IModbusTransport
 {
     private readonly string _host;
     private readonly int _port;
     private readonly TimeSpan _timeout;
+    private readonly bool _autoReconnect;
     private readonly SemaphoreSlim _gate = new(1, 1);
     private TcpClient? _client;
     private NetworkStream? _stream;
     private ushort _nextTx;
     private bool _disposed;
 
-    public ModbusTcpTransport(string host, int port, TimeSpan timeout)
+    public ModbusTcpTransport(string host, int port, TimeSpan timeout, bool autoReconnect = true)
     {
         _host = host;
         _port = port;
         _timeout = timeout;
+        _autoReconnect = autoReconnect;
     }
 
     public async Task ConnectAsync(CancellationToken ct)
@@ -39,12 +57,34 @@ public sealed class ModbusTcpTransport : IModbusTransport
         var target = ipv4 ?? (addresses.Length > 0 ? addresses[0] : System.Net.IPAddress.Loopback);
 
         _client = new TcpClient(target.AddressFamily);
+        EnableKeepAlive(_client);
+
         using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
         cts.CancelAfter(_timeout);
         await _client.ConnectAsync(target, _port, cts.Token).ConfigureAwait(false);
         _stream = _client.GetStream();
     }
 
+    /// <summary>
+    ///     Enable SO_KEEPALIVE with aggressive probe timing. DL205/DL260 doesn't send keepalives
+    ///     itself; having the OS probe the socket every ~30s lets the driver notice a dead PLC
+    ///     or broken NAT path long before the default 2-hour Windows idle timeout fires.
+    ///     Non-fatal if the underlying OS rejects the option (some older Linux / container
+    ///     sandboxes don't expose the fine-grained timing levers — the driver still works,
+    ///     application-level probe still detects problems).
+    /// </summary>
+    private static void EnableKeepAlive(TcpClient client)
+    {
+        try
+        {
+            client.Client.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.KeepAlive, true);
+            client.Client.SetSocketOption(SocketOptionLevel.Tcp, SocketOptionName.TcpKeepAliveTime, 30);
+            client.Client.SetSocketOption(SocketOptionLevel.Tcp, SocketOptionName.TcpKeepAliveInterval, 10);
+            client.Client.SetSocketOption(SocketOptionLevel.Tcp, SocketOptionName.TcpKeepAliveRetryCount, 3);
+        }
+        catch { /* best-effort; older OSes may not expose the granular knobs */ }
+    }
+
     public async Task<byte[]> SendAsync(byte unitId, byte[] pdu, CancellationToken ct)
     {
         if (_disposed) throw new ObjectDisposedException(nameof(ModbusTcpTransport));
@@ -53,43 +93,18 @@ public sealed class ModbusTcpTransport : IModbusTransport
         await _gate.WaitAsync(ct).ConfigureAwait(false);
         try
         {
-            var txId = ++_nextTx;
-
-            // MBAP: [TxId(2)][Proto=0(2)][Length(2)][UnitId(1)] + PDU
-            var adu = new byte[7 + pdu.Length];
-            adu[0] = (byte)(txId >> 8);
-            adu[1] = (byte)(txId & 0xFF);
-            // protocol id already zero
-            var len = (ushort)(1 + pdu.Length); // unit id + pdu
-            adu[4] = (byte)(len >> 8);
-            adu[5] = (byte)(len & 0xFF);
-            adu[6] = unitId;
-            Buffer.BlockCopy(pdu, 0, adu, 7, pdu.Length);
-
-            using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
-            cts.CancelAfter(_timeout);
-            await _stream.WriteAsync(adu.AsMemory(), cts.Token).ConfigureAwait(false);
-            await _stream.FlushAsync(cts.Token).ConfigureAwait(false);
-
-            var header = new byte[7];
-            await ReadExactlyAsync(_stream, header, cts.Token).ConfigureAwait(false);
-            var respTxId = (ushort)((header[0] << 8) | header[1]);
-            if (respTxId != txId)
-                throw new InvalidDataException($"Modbus TxId mismatch: expected {txId} got {respTxId}");
-            var respLen = (ushort)((header[4] << 8) | header[5]);
-            if (respLen < 1) throw new InvalidDataException($"Modbus response length too small: {respLen}");
-            var respPdu = new byte[respLen - 1];
-            await ReadExactlyAsync(_stream, respPdu, cts.Token).ConfigureAwait(false);
-
-            // Exception PDU: function code has high bit set.
-            if ((respPdu[0] & 0x80) != 0)
+            try
             {
-                var fc = (byte)(respPdu[0] & 0x7F);
-                var ex = respPdu[1];
-                throw new ModbusException(fc, ex, $"Modbus exception fc={fc} code={ex}");
+                return await SendOnceAsync(unitId, pdu, ct).ConfigureAwait(false);
+            }
+            catch (Exception ex) when (_autoReconnect && IsSocketLevelFailure(ex))
+            {
+                // Mid-transaction drop: tear down the dead socket, reconnect, resend. Single
+                // retry — if it fails again, let it propagate so health/status reflect reality.
+                await TearDownAsync().ConfigureAwait(false);
+                await ConnectAsync(ct).ConfigureAwait(false);
+                return await SendOnceAsync(unitId, pdu, ct).ConfigureAwait(false);
             }
-
-            return respPdu;
         }
         finally
         {
@@ -97,6 +112,68 @@ public sealed class ModbusTcpTransport : IModbusTransport
         }
     }
 
+    private async Task<byte[]> SendOnceAsync(byte unitId, byte[] pdu, CancellationToken ct)
+    {
+        if (_stream is null) throw new InvalidOperationException("Transport not connected");
+        var txId = ++_nextTx;
+
+        // MBAP: [TxId(2)][Proto=0(2)][Length(2)][UnitId(1)] + PDU
+        var adu = new byte[7 + pdu.Length];
+        adu[0] = (byte)(txId >> 8);
+        adu[1] = (byte)(txId & 0xFF);
+        // protocol id already zero
+        var len = (ushort)(1 + pdu.Length); // unit id + pdu
+        adu[4] = (byte)(len >> 8);
+        adu[5] = (byte)(len & 0xFF);
+        adu[6] = unitId;
+        Buffer.BlockCopy(pdu, 0, adu, 7, pdu.Length);
+
+        using var cts = CancellationTokenSource.CreateLinkedTokenSource(ct);
+        cts.CancelAfter(_timeout);
+        await _stream.WriteAsync(adu.AsMemory(), cts.Token).ConfigureAwait(false);
+        await _stream.FlushAsync(cts.Token).ConfigureAwait(false);
+
+        var header = new byte[7];
+        await ReadExactlyAsync(_stream, header, cts.Token).ConfigureAwait(false);
+        var respTxId = (ushort)((header[0] << 8) | header[1]);
+        if (respTxId != txId)
+            throw new InvalidDataException($"Modbus TxId mismatch: expected {txId} got {respTxId}");
+        var respLen = (ushort)((header[4] << 8) | header[5]);
+        if (respLen < 1) throw new InvalidDataException($"Modbus response length too small: {respLen}");
+        var respPdu = new byte[respLen - 1];
+        await ReadExactlyAsync(_stream, respPdu, cts.Token).ConfigureAwait(false);
+
+        // Exception PDU: function code has high bit set.
+        if ((respPdu[0] & 0x80) != 0)
+        {
+            var fc = (byte)(respPdu[0] & 0x7F);
+            var ex = respPdu[1];
+            throw new ModbusException(fc, ex, $"Modbus exception fc={fc} code={ex}");
+        }
+
+        return respPdu;
+    }
+
+    /// <summary>
+    ///     Distinguish socket-layer failures (eligible for reconnect-and-retry) from
+    ///     protocol-layer failures (must propagate — retrying the same PDU won't help if the
+    ///     PLC just returned exception 02 Illegal Data Address).
+    /// </summary>
+    private static bool IsSocketLevelFailure(Exception ex) =>
+        ex is EndOfStreamException
+        || ex is IOException
+        || ex is SocketException
+        || ex is ObjectDisposedException;
+
+    private async Task TearDownAsync()
+    {
+        try { if (_stream is not null) await _stream.DisposeAsync().ConfigureAwait(false); }
+        catch { /* best-effort */ }
+        _stream = null;
+        try { _client?.Dispose(); } catch { }
+        _client = null;
+    }
+
     private static async Task ReadExactlyAsync(Stream s, byte[] buf, CancellationToken ct)
     {
         var read = 0;

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/DL205/DL205BcdQuirkTests.cs

@@ -0,0 +1,56 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.DL205;
+
+/// <summary>
+///     Verifies DL205/DL260 binary-coded-decimal register handling against the
+///     <c>dl205.json</c> pymodbus profile. HR[1072] = 0x1234 on the profile represents
+///     decimal 1234 (BCD nibbles). Reading it as <see cref="ModbusDataType.Int16"/> would
+///     return 0x1234 = 4660; the <see cref="ModbusDataType.Bcd16"/> path decodes 1234.
+/// </summary>
+[Collection(ModbusSimulatorCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "DL205")]
+public sealed class DL205BcdQuirkTests(ModbusSimulatorFixture sim)
+{
+    [Fact]
+    public async Task DL205_BCD16_decodes_HR1072_as_decimal_1234()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "dl205",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != dl205 — skipping (standard profile does not seed HR[1072]).");
+        }
+
+        var options = new ModbusDriverOptions
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags =
+            [
+                new ModbusTagDefinition("DL205_Count_Bcd",
+                    ModbusRegion.HoldingRegisters, Address: 1072,
+                    DataType: ModbusDataType.Bcd16, Writable: false),
+                new ModbusTagDefinition("DL205_Count_Int16",
+                    ModbusRegion.HoldingRegisters, Address: 1072,
+                    DataType: ModbusDataType.Int16, Writable: false),
+            ],
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+        await using var driver = new ModbusDriver(options, driverInstanceId: "dl205-bcd");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["DL205_Count_Bcd", "DL205_Count_Int16"],
+            TestContext.Current.CancellationToken);
+
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe(1234, "DL205 BCD register 0x1234 represents decimal 1234 per the DirectLOGIC convention");
+
+        results[1].StatusCode.ShouldBe(0u);
+        results[1].Value.ShouldBe((short)0x1234, "same register read as Int16 returns the raw 0x1234 = 4660 value — proves BCD path is distinct");
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/DL205/DL205CoilMappingTests.cs

@@ -0,0 +1,109 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.DL205;
+
+/// <summary>
+///     Verifies DL260 I/O-memory coil mappings against the <c>dl205.json</c> pymodbus profile.
+///     DirectLOGIC Y-outputs and C-relays are exposed to Modbus as FC01/FC05 coils, but at
+///     non-zero base addresses that confuse operators used to "Y0 is the first coil". The sim
+///     seeds Y0 → coil 2048 = ON and C0 → coil 3072 = ON as fixed markers.
+/// </summary>
+[Collection(ModbusSimulatorCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "DL205")]
+public sealed class DL205CoilMappingTests(ModbusSimulatorFixture sim)
+{
+    [Fact]
+    public async Task DL260_Y0_maps_to_coil_2048()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "dl205",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != dl205 — skipping.");
+        }
+
+        var coil = DirectLogicAddress.YOutputToCoil("Y0");
+        coil.ShouldBe((ushort)2048);
+
+        var options = BuildOptions(sim, [
+            new ModbusTagDefinition("DL260_Y0",
+                ModbusRegion.Coils, Address: coil,
+                DataType: ModbusDataType.Bool, Writable: false),
+        ]);
+        await using var driver = new ModbusDriver(options, driverInstanceId: "dl205-y0");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["DL260_Y0"], TestContext.Current.CancellationToken);
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe(true, "dl205.json seeds coil 2048 (Y0) = ON");
+    }
+
+    [Fact]
+    public async Task DL260_C0_maps_to_coil_3072()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "dl205",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != dl205 — skipping.");
+        }
+
+        var coil = DirectLogicAddress.CRelayToCoil("C0");
+        coil.ShouldBe((ushort)3072);
+
+        var options = BuildOptions(sim, [
+            new ModbusTagDefinition("DL260_C0",
+                ModbusRegion.Coils, Address: coil,
+                DataType: ModbusDataType.Bool, Writable: false),
+        ]);
+        await using var driver = new ModbusDriver(options, driverInstanceId: "dl205-c0");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["DL260_C0"], TestContext.Current.CancellationToken);
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe(true, "dl205.json seeds coil 3072 (C0) = ON");
+    }
+
+    [Fact]
+    public async Task DL260_scratch_Crelay_supports_write_then_read()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "dl205",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != dl205 — skipping.");
+        }
+
+        // Scratch C-relay at coil 4000 (per dl205.json _quirk note) is writable. Write=true then
+        // read back to confirm FC05 round-trip works against the DL-mapped coil bank.
+        var options = BuildOptions(sim, [
+            new ModbusTagDefinition("DL260_C_Scratch",
+                ModbusRegion.Coils, Address: 4000,
+                DataType: ModbusDataType.Bool, Writable: true),
+        ]);
+        await using var driver = new ModbusDriver(options, driverInstanceId: "dl205-cscratch");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var writeResults = await driver.WriteAsync(
+            [new(FullReference: "DL260_C_Scratch", Value: true)],
+            TestContext.Current.CancellationToken);
+        writeResults[0].StatusCode.ShouldBe(0u);
+
+        var readResults = await driver.ReadAsync(["DL260_C_Scratch"], TestContext.Current.CancellationToken);
+        readResults[0].StatusCode.ShouldBe(0u);
+        readResults[0].Value.ShouldBe(true);
+    }
+
+    private static ModbusDriverOptions BuildOptions(ModbusSimulatorFixture sim, IReadOnlyList<ModbusTagDefinition> tags)
+        => new()
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags = tags,
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/DL205/DL205ExceptionCodeTests.cs

@@ -0,0 +1,53 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.DL205;
+
+/// <summary>
+///     Verifies the driver's Modbus-exception → OPC UA StatusCode translation end-to-end
+///     against the dl205.json pymodbus profile. pymodbus returns exception 02 (Illegal Data
+///     Address) for reads outside the configured register ranges, matching real DL205/DL260
+///     firmware behavior per <c>docs/v2/dl205.md</c> §exception-codes. The driver must surface
+///     that as <c>BadOutOfRange</c> (0x803C0000) — not <c>BadInternalError</c> — so the
+///     operator sees a tag-config diagnosis instead of a generic driver-fault message.
+/// </summary>
+[Collection(ModbusSimulatorCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "DL205")]
+public sealed class DL205ExceptionCodeTests(ModbusSimulatorFixture sim)
+{
+    [Fact]
+    public async Task DL205_FC03_at_unmapped_register_returns_BadOutOfRange()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "dl205",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != dl205 — skipping.");
+        }
+
+        // Address 16383 is the last cell of hr-size=16384 in dl205.json; address 16384 is
+        // beyond the configured HR range. pymodbus validates and returns exception 02
+        // (Illegal Data Address).
+        var options = new ModbusDriverOptions
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags =
+            [
+                new ModbusTagDefinition("Unmapped",
+                    ModbusRegion.HoldingRegisters, Address: 16383,
+                    DataType: ModbusDataType.UInt16, Writable: false),
+            ],
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+        await using var driver = new ModbusDriver(options, driverInstanceId: "dl205-exc");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["Unmapped"], TestContext.Current.CancellationToken);
+        results[0].StatusCode.ShouldBe(0x803C0000u,
+            "DL205 returns exception 02 for an FC03 at an unmapped register; driver must translate to BadOutOfRange (not BadInternalError)");
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/DL205/DL205FloatCdabQuirkTests.cs

@@ -0,0 +1,64 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.DL205;
+
+/// <summary>
+///     Verifies DL205/DL260 CDAB word ordering for 32-bit floats against the
+///     <c>dl205.json</c> pymodbus profile. DirectLOGIC stores IEEE-754 singles with the low
+///     word at the lower register address (CDAB) rather than the high word (ABCD). Reading
+///     <c>HR[1056..1057]</c> with <see cref="ModbusByteOrder.BigEndian"/> produces a tiny
+///     denormal (~5.74e-41) instead of the intended 1.5f — a silent "value is 0" bug in the
+///     field unless the caller opts into <see cref="ModbusByteOrder.WordSwap"/>.
+/// </summary>
+[Collection(ModbusSimulatorCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "DL205")]
+public sealed class DL205FloatCdabQuirkTests(ModbusSimulatorFixture sim)
+{
+    [Fact]
+    public async Task DL205_Float32_CDAB_decodes_1_5f_from_HR1056()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "dl205",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != dl205 — skipping (standard profile does not seed HR[1056..1057]).");
+        }
+
+        var options = new ModbusDriverOptions
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags =
+            [
+                new ModbusTagDefinition("DL205_Float_CDAB",
+                    ModbusRegion.HoldingRegisters, Address: 1056,
+                    DataType: ModbusDataType.Float32, Writable: false,
+                    ByteOrder: ModbusByteOrder.WordSwap),
+                // Control: same address, BigEndian — proves the default decode produces garbage.
+                new ModbusTagDefinition("DL205_Float_ABCD",
+                    ModbusRegion.HoldingRegisters, Address: 1056,
+                    DataType: ModbusDataType.Float32, Writable: false,
+                    ByteOrder: ModbusByteOrder.BigEndian),
+            ],
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+        await using var driver = new ModbusDriver(options, driverInstanceId: "dl205-cdab");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["DL205_Float_CDAB", "DL205_Float_ABCD"],
+            TestContext.Current.CancellationToken);
+
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe(1.5f, "DL205 Float32 with WordSwap (CDAB) must decode HR[1056..1057] as 1.5f");
+
+        // The BigEndian read of the same wire bytes should differ — not asserting the exact
+        // denormal value (that couples the test to IEEE-754 bit math) but the two decodes MUST
+        // disagree, otherwise the word-order flag is a no-op.
+        results[1].StatusCode.ShouldBe(0u);
+        results[1].Value.ShouldNotBe(1.5f);
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/DL205/DL205VMemoryQuirkTests.cs

@@ -0,0 +1,91 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.DL205;
+
+/// <summary>
+///     Verifies the DL205/DL260 V-memory octal addressing quirk end-to-end: use
+///     <see cref="DirectLogicAddress.UserVMemoryToPdu"/> to translate <c>V2000</c> octal into
+///     the Modbus PDU address actually dispatched, then read the marker the dl205.json profile
+///     placed at that address. HR[0x0400] = 0x2000 proves the translation was performed
+///     correctly — a naïve caller treating "V2000" as decimal 2000 would read HR[2000] (which
+///     the profile leaves at 0) and miss the marker entirely.
+/// </summary>
+[Collection(ModbusSimulatorCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "DL205")]
+public sealed class DL205VMemoryQuirkTests(ModbusSimulatorFixture sim)
+{
+    [Fact]
+    public async Task DL205_V2000_user_memory_resolves_to_PDU_0x0400_marker()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "dl205",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != dl205 — skipping (standard profile does not seed V-memory markers).");
+        }
+
+        var pdu = DirectLogicAddress.UserVMemoryToPdu("V2000");
+        pdu.ShouldBe((ushort)0x0400);
+
+        var options = new ModbusDriverOptions
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags =
+            [
+                new ModbusTagDefinition("DL205_V2000",
+                    ModbusRegion.HoldingRegisters, Address: pdu,
+                    DataType: ModbusDataType.UInt16, Writable: false),
+            ],
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+        await using var driver = new ModbusDriver(options, driverInstanceId: "dl205-vmem");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["DL205_V2000"], TestContext.Current.CancellationToken);
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe((ushort)0x2000, "dl205.json seeds HR[0x0400] with marker 0x2000 (= V2000 value)");
+    }
+
+    [Fact]
+    public async Task DL205_V40400_system_memory_resolves_to_PDU_0x2100_marker()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "dl205",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != dl205 — skipping.");
+        }
+
+        // V40400 is system memory on DL260 / H2-ECOM100 absolute mode; it does NOT follow the
+        // simple octal-to-decimal formula (40400 octal = 16640 decimal, which would read HR[0x4100]).
+        // The CPU places the system bank at PDU 0x2100 instead. Proving the helper routes there.
+        var pdu = DirectLogicAddress.SystemVMemoryToPdu(0);
+        pdu.ShouldBe((ushort)0x2100);
+
+        var options = new ModbusDriverOptions
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags =
+            [
+                new ModbusTagDefinition("DL205_V40400",
+                    ModbusRegion.HoldingRegisters, Address: pdu,
+                    DataType: ModbusDataType.UInt16, Writable: false),
+            ],
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+        await using var driver = new ModbusDriver(options, driverInstanceId: "dl205-sysv");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["DL205_V40400"], TestContext.Current.CancellationToken);
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe((ushort)0x4040, "dl205.json seeds HR[0x2100] with marker 0x4040 (= V40400 value)");
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/DL205/DL205XInputTests.cs

@@ -0,0 +1,71 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.DL205;
+
+/// <summary>
+///     Verifies the DL260 X-input discrete-input mapping against the <c>dl205.json</c>
+///     pymodbus profile. X-inputs are FC02 discrete-input-only (Modbus doesn't allow writes
+///     to discrete inputs), and the DirectLOGIC convention is X0 → DI 0 with octal offsets
+///     for subsequent addresses. The sim seeds X20 octal (= DI 16) = ON so the test can
+///     prove the helper routes through to the right cell.
+/// </summary>
+/// <remarks>
+///     X0 / X1 / …X17 octal all share cell 0 (DI 0-15 → cell 0 bits 0-15) which conflicts
+///     with the V0 uint16 marker; we can't seed both types at cell 0 under shared-blocks
+///     semantics. So the test uses X20 octal (first address beyond the cell-0 boundary) which
+///     lands cleanly at cell 1 bit 0 and leaves the V0 register-zero quirk intact.
+/// </remarks>
+[Collection(ModbusSimulatorCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "DL205")]
+public sealed class DL205XInputTests(ModbusSimulatorFixture sim)
+{
+    [Fact]
+    public async Task DL260_X20_octal_maps_to_DiscreteInput_16_and_reads_ON()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "dl205",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != dl205 — skipping.");
+        }
+
+        // X20 octal = decimal 16 = DI 16 per the DL260 convention (X-inputs start at DI 0).
+        var di = DirectLogicAddress.XInputToDiscrete("X20");
+        di.ShouldBe((ushort)16);
+
+        var options = BuildOptions(sim, [
+            new ModbusTagDefinition("DL260_X20",
+                ModbusRegion.DiscreteInputs, Address: di,
+                DataType: ModbusDataType.Bool, Writable: false),
+            // Unpopulated-X control: pymodbus returns 0 (not exception) for any bit in the
+            // configured DI range that wasn't explicitly seeded — per docs/v2/dl205.md
+            // "Reading a non-populated X input ... returns zero, not an exception".
+            new ModbusTagDefinition("DL260_X21_off",
+                ModbusRegion.DiscreteInputs, Address: DirectLogicAddress.XInputToDiscrete("X21"),
+                DataType: ModbusDataType.Bool, Writable: false),
+        ]);
+        await using var driver = new ModbusDriver(options, driverInstanceId: "dl205-xinput");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["DL260_X20", "DL260_X21_off"], TestContext.Current.CancellationToken);
+
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe(true, "dl205.json seeds cell 1 bit 0 (X20 octal = DI 16) = ON");
+
+        results[1].StatusCode.ShouldBe(0u, "unpopulated X inputs must read cleanly — DL260 does NOT raise an exception");
+        results[1].Value.ShouldBe(false);
+    }
+
+    private static ModbusDriverOptions BuildOptions(ModbusSimulatorFixture sim, IReadOnlyList<ModbusTagDefinition> tags)
+        => new()
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags = tags,
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Pymodbus/dl205.json

@@ -36,9 +36,10 @@
         [1280, 1282],
         [1343, 1343],
         [1407, 1407],
-        [2048, 2050],
-        [3072, 3074],
-        [4000, 4007],
+        [1, 1],
+        [128, 128],
+        [192, 192],
+        [250, 250],
         [8448, 8448]
       ],
 
@@ -88,25 +89,17 @@
       ],
 
       "bits": [
-        {"_quirk": "Y0 marker. DL260 maps Y0 to coil 2048 (0-based). Coil 2048 = ON proves the mapping.",
-         "addr": 2048, "value": 1},
-        {"addr": 2049, "value": 0},
-        {"addr": 2050, "value": 1},
+        {"_quirk": "X-input bank marker cell. X0 -> DI 0 conflicts with uint16 V0 at cell 0, so this marker covers X20 octal (= decimal 16 = DI 16 = cell 1 bit 0). X20=ON, X23 octal (DI 19 = cell 1 bit 3)=ON -> cell 1 value = 0b00001001 = 9.",
+         "addr": 1, "value": 9},
 
-        {"_quirk": "C0 marker. DL260 maps C0 to coil 3072 (0-based). Coil 3072 = ON proves the mapping.",
-         "addr": 3072, "value": 1},
-        {"addr": 3073, "value": 0},
-        {"addr": 3074, "value": 1},
+        {"_quirk": "Y-output bank marker cell. pymodbus's simulator maps Modbus FC01/02/05 bit-addresses to cell index = bit_addr / 16; so Modbus coil 2048 lives at cell 128 bit 0. Y0=ON (bit 0), Y1=OFF (bit 1), Y2=ON (bit 2) -> value=0b00000101=5 proves DL260 mapping Y0 -> coil 2048.",
+         "addr": 128, "value": 5},
 
-        {"_quirk": "Scratch C-relays for write-roundtrip tests against the writable C range.",
-         "addr": 4000, "value": 0},
-        {"addr": 4001, "value": 0},
-        {"addr": 4002, "value": 0},
-        {"addr": 4003, "value": 0},
-        {"addr": 4004, "value": 0},
-        {"addr": 4005, "value": 0},
-        {"addr": 4006, "value": 0},
-        {"addr": 4007, "value": 0}
+        {"_quirk": "C-relay bank marker cell. Modbus coil 3072 -> cell 192 bit 0. C0=ON (bit 0), C1=OFF (bit 1), C2=ON (bit 2) -> value=5 proves DL260 mapping C0 -> coil 3072.",
+         "addr": 192, "value": 5},
+
+        {"_quirk": "Scratch cell for coil 4000..4015 write round-trip tests. Cell 250 holds Modbus coils 4000-4015; all bits start at 0 and tests set specific bits via FC05.",
+         "addr": 250, "value": 0}
       ],
 
       "uint32":  [],

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Pymodbus/s7_1500.json

@@ -0,0 +1,77 @@
+{
+  "_comment": "s7_1500.json -- Siemens SIMATIC S7-1500 + MB_SERVER quirk simulator. Models docs/v2/s7.md behaviors as concrete register values. Unlike DL260 (CDAB word order default) or Mitsubishi (CDAB default), S7 MB_SERVER uses ABCD word order by default because Siemens native CPU types are big-endian top-to-bottom both within the register pair and byte pair. This profile exists so the driver's S7 profile default ByteOrder.BigEndian can be validated end-to-end. pymodbus bit-address semantics are the same as dl205.json (FC01/02/05/15 address X maps to cell index X/16); seed bits at the appropriate cell-indexed positions.",
+
+  "server_list": {
+    "srv": {
+      "comm": "tcp",
+      "host": "0.0.0.0",
+      "port": 5020,
+      "framer": "socket",
+      "device_id": 1
+    }
+  },
+
+  "device_list": {
+    "dev": {
+      "setup": {
+        "co size":    4096,
+        "di size":    4096,
+        "hr size":    4096,
+        "ir size":    1024,
+        "shared blocks": true,
+        "type exception": false,
+        "defaults": {
+          "value":  {"bits": 0, "uint16": 0, "uint32": 0, "float32": 0.0, "string": " "},
+          "action": {"bits": null, "uint16": null, "uint32": null, "float32": null, "string": null}
+        }
+      },
+      "invalid": [],
+      "write": [
+        [0, 0],
+        [25, 25],
+        [100, 101],
+        [200, 209],
+        [300, 301]
+      ],
+
+      "uint16": [
+        {"_quirk": "DB1 header marker. On an S7-1500 with MB_SERVER pointing at DB1, operators often reserve DB1.DBW0 for a fingerprint word so clients can verify they're talking to the right DB. 0xABCD = 43981.",
+         "addr": 0, "value": 43981},
+
+        {"_quirk": "Scratch HR range 200..209 -- mirrors the standard.json scratch range so the smoke test (S7_1500Profile.SmokeHoldingRegister=200) round-trips identically against either profile.",
+         "addr": 200, "value": 0},
+        {"addr": 201, "value": 0},
+        {"addr": 202, "value": 0},
+        {"addr": 203, "value": 0},
+        {"addr": 204, "value": 0},
+        {"addr": 205, "value": 0},
+        {"addr": 206, "value": 0},
+        {"addr": 207, "value": 0},
+        {"addr": 208, "value": 0},
+        {"addr": 209, "value": 0},
+
+        {"_quirk": "Float32 1.5f in ABCD word order (Siemens big-endian default, OPPOSITE of DL260 CDAB). IEEE-754 1.5 = 0x3FC00000. ABCD = high word first: HR[100]=0x3FC0=16320, HR[101]=0x0000=0.",
+         "addr": 100, "value": 16320},
+        {"_quirk": "Float32 1.5f ABCD low word.",
+         "addr": 101, "value": 0},
+
+        {"_quirk": "Int32 0x12345678 in ABCD word order. HR[300]=0x1234=4660, HR[301]=0x5678=22136. Demonstrates the contrast with DL260 CDAB Int32 encoding.",
+         "addr": 300, "value": 4660},
+        {"addr": 301, "value": 22136}
+      ],
+
+      "bits": [
+        {"_quirk": "Coil bank marker cell. S7 MB_SERVER doesn't fix coil addresses; this simulates a user-wired DB where coil 400 (=bit 0 of cell 25) represents a latched digital output. Cell 25 bit 0 = 1 proves the wire-format round-trip works for coils on S7 profile.",
+         "addr": 25, "value": 1},
+
+        {"_quirk": "Discrete-input bank marker cell. DI 500 (=bit 0 of cell 31) = 1. Like coils, discrete inputs on S7 MB_SERVER are per-site; we assert the end-to-end FC02 path only.",
+         "addr": 31, "value": 1}
+      ],
+
+      "uint32":  [],
+      "float32": [],
+      "string":  [],
+      "repeat":  []
+    }
+  }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/Pymodbus/serve.ps1

@@ -21,7 +21,7 @@
 #>
 [CmdletBinding()]
 param(
-    [Parameter(Mandatory)] [ValidateSet('standard', 'dl205')] [string]$Profile,
+    [Parameter(Mandatory)] [ValidateSet('standard', 'dl205', 's7_1500', 'mitsubishi')] [string]$Profile,
     [int]$HttpPort = 8080
 )
 

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/S7/S7_1500Profile.cs

@@ -0,0 +1,44 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.S7;
+
+/// <summary>
+///     Tag map for the Siemens SIMATIC S7-1500 device class with the <c>MB_SERVER</c> library
+///     block mapping HR[0..] to DB1.DBW0+. Mirrors <c>s7_1500.json</c> in <c>Pymodbus/</c>.
+/// </summary>
+/// <remarks>
+///     Unlike DL205, S7 has no fixed Modbus memory map — every site wires MB_SERVER to a
+///     different DB. The profile here models the *default* user layout documented in
+///     <c>docs/v2/s7.md</c> §per-model-matrix: DB1.DBW0 = fingerprint marker, a scratch HR
+///     range 200..209 for write-roundtrip tests, and ABCD-order Float32 / Int32 markers at
+///     HR[100..101] and HR[300..301] to prove the driver's S7 profile default is correct.
+/// </remarks>
+public static class S7_1500Profile
+{
+    /// <summary>
+    ///     Scratch HR the smoke test writes + reads. Address 200 mirrors the DL205 /
+    ///     standard scratch range so one smoke test pattern works across all device profiles.
+    /// </summary>
+    public const ushort SmokeHoldingRegister = 200;
+
+    /// <summary>Value the smoke test writes then reads back.</summary>
+    public const short SmokeHoldingValue = 4321;
+
+    public static ModbusDriverOptions BuildOptions(string host, int port) => new()
+    {
+        Host = host,
+        Port = port,
+        UnitId = 1,
+        Timeout = TimeSpan.FromSeconds(2),
+        Tags =
+        [
+            new ModbusTagDefinition(
+                Name: "Smoke_HReg200",
+                Region: ModbusRegion.HoldingRegisters,
+                Address: SmokeHoldingRegister,
+                DataType: ModbusDataType.Int16,
+                Writable: true),
+        ],
+        // Disable the background probe loop — integration tests drive reads explicitly and
+        // the probe would race with assertions.
+        Probe = new ModbusProbeOptions { Enabled = false },
+    };
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/S7/S7_1500SmokeTests.cs

@@ -0,0 +1,54 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.S7;
+
+/// <summary>
+///     End-to-end smoke against the S7-1500 <c>MB_SERVER</c> pymodbus profile (or a real
+///     S7-1500 + MB_SERVER deployment when <c>MODBUS_SIM_ENDPOINT</c> points at one). Drives
+///     the full <see cref="ModbusDriver"/> + real <see cref="ModbusTcpTransport"/> stack —
+///     no fake transport. Success proves the driver initializes against the S7 simulator,
+///     writes a known value, and reads it back with the correct status and value, which is
+///     the baseline every S7-specific test (PR 57+) builds on.
+/// </summary>
+/// <remarks>
+///     S7-specific quirk tests (MB_SERVER requires non-optimized DBs, ABCD word order
+///     default, port-per-connection, FC23 Illegal Function, STOP-mode behaviour, etc.) land
+///     as separate test classes in this directory as each quirk is validated in pymodbus.
+///     Keep this smoke test deliberately narrow — filtering by device class
+///     (<c>--filter DisplayName~S7</c>) should surface the quirk-specific failure mode when
+///     something goes wrong, not a blanket smoke failure that could mean anything.
+/// </remarks>
+[Collection(ModbusSimulatorCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "S7")]
+public sealed class S7_1500SmokeTests(ModbusSimulatorFixture sim)
+{
+    [Fact]
+    public async Task S7_1500_roundtrip_write_then_read_of_holding_register()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "s7_1500",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != s7_1500 — skipping (other profiles don't seed the S7 scratch range identically).");
+        }
+
+        var options = S7_1500Profile.BuildOptions(sim.Host, sim.Port);
+        await using var driver = new ModbusDriver(options, driverInstanceId: "s7-smoke");
+        await driver.InitializeAsync(driverConfigJson: "{}", TestContext.Current.CancellationToken);
+
+        var writeResults = await driver.WriteAsync(
+            [new(FullReference: "Smoke_HReg200", Value: (short)S7_1500Profile.SmokeHoldingValue)],
+            TestContext.Current.CancellationToken);
+        writeResults.Count.ShouldBe(1);
+        writeResults[0].StatusCode.ShouldBe(0u, "write must succeed against the S7-1500 MB_SERVER profile");
+
+        var readResults = await driver.ReadAsync(
+            ["Smoke_HReg200"],
+            TestContext.Current.CancellationToken);
+        readResults.Count.ShouldBe(1);
+        readResults[0].StatusCode.ShouldBe(0u);
+        readResults[0].Value.ShouldBe((short)S7_1500Profile.SmokeHoldingValue);
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/S7/S7_ByteOrderTests.cs

@@ -0,0 +1,132 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.S7;
+
+/// <summary>
+///     Verifies the Siemens S7 big-endian (<c>ABCD</c>) word-order default for Float32 and
+///     Int32 against the <c>s7_1500.json</c> pymodbus profile. S7's native CPU types are
+///     big-endian end-to-end, so <c>MB_SERVER</c> places the high word at the lower register
+///     address — <b>opposite</b> of DL260's CDAB. The driver's S7-family tag config must
+///     therefore default to <see cref="ModbusByteOrder.BigEndian"/>; selecting
+///     <see cref="ModbusByteOrder.WordSwap"/> against an S7 would decode garbage.
+/// </summary>
+[Collection(ModbusSimulatorCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "S7")]
+public sealed class S7_ByteOrderTests(ModbusSimulatorFixture sim)
+{
+    [Fact]
+    public async Task S7_Float32_ABCD_decodes_1_5f_from_HR100()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "s7_1500",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != s7_1500 — skipping (s7_1500 profile is the only one seeding HR[100..101] ABCD).");
+        }
+
+        var options = new ModbusDriverOptions
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags =
+            [
+                new ModbusTagDefinition("S7_Float_ABCD",
+                    ModbusRegion.HoldingRegisters, Address: 100,
+                    DataType: ModbusDataType.Float32, Writable: false,
+                    ByteOrder: ModbusByteOrder.BigEndian),
+                // Control: same address with WordSwap should decode garbage — proves the
+                // two code paths diverge on S7 wire bytes.
+                new ModbusTagDefinition("S7_Float_CDAB_control",
+                    ModbusRegion.HoldingRegisters, Address: 100,
+                    DataType: ModbusDataType.Float32, Writable: false,
+                    ByteOrder: ModbusByteOrder.WordSwap),
+            ],
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+        await using var driver = new ModbusDriver(options, driverInstanceId: "s7-float-abcd");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(
+            ["S7_Float_ABCD", "S7_Float_CDAB_control"],
+            TestContext.Current.CancellationToken);
+
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe(1.5f, "S7 MB_SERVER stores Float32 in ABCD word order; BigEndian decode returns 1.5f");
+
+        results[1].StatusCode.ShouldBe(0u);
+        results[1].Value.ShouldNotBe(1.5f, "applying CDAB swap to S7 ABCD bytes must produce a different value — confirms the flag is not a no-op and S7 profile default must be BigEndian");
+    }
+
+    [Fact]
+    public async Task S7_Int32_ABCD_decodes_0x12345678_from_HR300()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "s7_1500",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != s7_1500 — skipping.");
+        }
+
+        var options = new ModbusDriverOptions
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags =
+            [
+                new ModbusTagDefinition("S7_Int32_ABCD",
+                    ModbusRegion.HoldingRegisters, Address: 300,
+                    DataType: ModbusDataType.Int32, Writable: false,
+                    ByteOrder: ModbusByteOrder.BigEndian),
+            ],
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+        await using var driver = new ModbusDriver(options, driverInstanceId: "s7-int-abcd");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["S7_Int32_ABCD"], TestContext.Current.CancellationToken);
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe(0x12345678,
+            "S7 Int32 stored as HR[300]=0x1234, HR[301]=0x5678 with ABCD order decodes to 0x12345678 — DL260 would store the reverse order");
+    }
+
+    [Fact]
+    public async Task S7_DB1_fingerprint_marker_at_HR0_reads_0xABCD()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "s7_1500",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != s7_1500 — skipping.");
+        }
+
+        // Real-world MB_SERVER deployments typically reserve DB1.DBW0 as a fingerprint so
+        // clients can verify they're pointing at the right DB (protects against typos in
+        // the MB_SERVER.MB_HOLD_REG.DB_number parameter). 0xABCD is the convention.
+        var options = new ModbusDriverOptions
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags =
+            [
+                new ModbusTagDefinition("S7_Fingerprint",
+                    ModbusRegion.HoldingRegisters, Address: 0,
+                    DataType: ModbusDataType.UInt16, Writable: false),
+            ],
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+        await using var driver = new ModbusDriver(options, driverInstanceId: "s7-fingerprint");
+        await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["S7_Fingerprint"], TestContext.Current.CancellationToken);
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe((ushort)0xABCD);
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.csproj

@@ -26,6 +26,7 @@
     <ItemGroup>
         <None Update="Pymodbus\**\*" CopyToOutputDirectory="PreserveNewest"/>
         <None Update="DL205\**\*" CopyToOutputDirectory="PreserveNewest"/>
+        <None Update="S7\**\*" CopyToOutputDirectory="PreserveNewest"/>
     </ItemGroup>
 
     <ItemGroup>

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/DirectLogicAddressTests.cs

@@ -0,0 +1,139 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
+
+[Trait("Category", "Unit")]
+public sealed class DirectLogicAddressTests
+{
+    [Theory]
+    [InlineData("V0", (ushort)0x0000)]
+    [InlineData("V1", (ushort)0x0001)]
+    [InlineData("V7", (ushort)0x0007)]
+    [InlineData("V10", (ushort)0x0008)]
+    [InlineData("V2000", (ushort)0x0400)]  // canonical DL205/DL260 user-memory start
+    [InlineData("V7777", (ushort)0x0FFF)]
+    [InlineData("V10000", (ushort)0x1000)]
+    [InlineData("V17777", (ushort)0x1FFF)]
+    public void UserVMemoryToPdu_converts_octal_V_prefix(string v, ushort expected)
+        => DirectLogicAddress.UserVMemoryToPdu(v).ShouldBe(expected);
+
+    [Theory]
+    [InlineData("0", (ushort)0)]
+    [InlineData("2000", (ushort)0x0400)]
+    [InlineData("v2000", (ushort)0x0400)]   // lowercase v
+    [InlineData(" V2000 ", (ushort)0x0400)] // surrounding whitespace
+    public void UserVMemoryToPdu_accepts_bare_or_prefixed_or_padded(string v, ushort expected)
+        => DirectLogicAddress.UserVMemoryToPdu(v).ShouldBe(expected);
+
+    [Theory]
+    [InlineData("V8")]     // 8 is not a valid octal digit
+    [InlineData("V19")]
+    [InlineData("V2009")]
+    public void UserVMemoryToPdu_rejects_non_octal_digits(string v)
+    {
+        Should.Throw<ArgumentException>(() => DirectLogicAddress.UserVMemoryToPdu(v))
+            .Message.ShouldContain("octal");
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    [InlineData("V")]
+    public void UserVMemoryToPdu_rejects_empty_input(string? v)
+        => Should.Throw<ArgumentException>(() => DirectLogicAddress.UserVMemoryToPdu(v!));
+
+    [Fact]
+    public void UserVMemoryToPdu_overflow_rejected()
+    {
+        // 200000 octal = 0x10000 — one past ushort range.
+        Should.Throw<OverflowException>(() => DirectLogicAddress.UserVMemoryToPdu("V200000"));
+    }
+
+    [Fact]
+    public void SystemVMemoryBasePdu_is_0x2100_for_V40400()
+    {
+        // V40400 on DL260 / H2-ECOM100 absolute mode → PDU 0x2100 (decimal 8448), NOT 0x4100
+        // which a naive octal-to-decimal of 40400 octal would give (= 16640).
+        DirectLogicAddress.SystemVMemoryBasePdu.ShouldBe((ushort)0x2100);
+        DirectLogicAddress.SystemVMemoryToPdu(0).ShouldBe((ushort)0x2100);
+    }
+
+    [Fact]
+    public void SystemVMemoryToPdu_offsets_within_bank()
+    {
+        DirectLogicAddress.SystemVMemoryToPdu(1).ShouldBe((ushort)0x2101);
+        DirectLogicAddress.SystemVMemoryToPdu(0x100).ShouldBe((ushort)0x2200);
+    }
+
+    [Fact]
+    public void SystemVMemoryToPdu_rejects_overflow()
+    {
+        // ushort wrap: 0xFFFF - 0x2100 = 0xDEFF; anything above should throw.
+        Should.NotThrow(() => DirectLogicAddress.SystemVMemoryToPdu(0xDEFF));
+        Should.Throw<OverflowException>(() => DirectLogicAddress.SystemVMemoryToPdu(0xDF00));
+    }
+
+    // --- Bit memory: Y-output, C-relay, X-input, SP-special ---
+
+    [Theory]
+    [InlineData("Y0", (ushort)2048)]
+    [InlineData("Y1", (ushort)2049)]
+    [InlineData("Y7", (ushort)2055)]
+    [InlineData("Y10", (ushort)2056)]    // octal 10 = decimal 8
+    [InlineData("Y17", (ushort)2063)]    // octal 17 = decimal 15
+    [InlineData("Y777", (ushort)2559)]   // top of DL260 Y range per doc table
+    public void YOutputToCoil_adds_octal_offset_to_2048(string y, ushort expected)
+        => DirectLogicAddress.YOutputToCoil(y).ShouldBe(expected);
+
+    [Theory]
+    [InlineData("C0", (ushort)3072)]
+    [InlineData("C1", (ushort)3073)]
+    [InlineData("C10", (ushort)3080)]
+    [InlineData("C1777", (ushort)4095)]  // top of DL260 C range
+    public void CRelayToCoil_adds_octal_offset_to_3072(string c, ushort expected)
+        => DirectLogicAddress.CRelayToCoil(c).ShouldBe(expected);
+
+    [Theory]
+    [InlineData("X0", (ushort)0)]
+    [InlineData("X17", (ushort)15)]
+    [InlineData("X777", (ushort)511)]    // top of DL260 X range
+    public void XInputToDiscrete_adds_octal_offset_to_0(string x, ushort expected)
+        => DirectLogicAddress.XInputToDiscrete(x).ShouldBe(expected);
+
+    [Theory]
+    [InlineData("SP0", (ushort)1024)]
+    [InlineData("SP7", (ushort)1031)]
+    [InlineData("sp0", (ushort)1024)]     // lowercase prefix
+    [InlineData("SP777", (ushort)1535)]
+    public void SpecialToDiscrete_adds_octal_offset_to_1024(string sp, ushort expected)
+        => DirectLogicAddress.SpecialToDiscrete(sp).ShouldBe(expected);
+
+    [Theory]
+    [InlineData("Y8")]
+    [InlineData("C9")]
+    [InlineData("X18")]
+    public void Bit_address_rejects_non_octal_digits(string bad)
+        => Should.Throw<ArgumentException>(() =>
+        {
+            if (bad[0] == 'Y') DirectLogicAddress.YOutputToCoil(bad);
+            else if (bad[0] == 'C') DirectLogicAddress.CRelayToCoil(bad);
+            else DirectLogicAddress.XInputToDiscrete(bad);
+        });
+
+    [Theory]
+    [InlineData("Y")]
+    [InlineData("C")]
+    [InlineData("")]
+    public void Bit_address_rejects_empty(string bad)
+        => Should.Throw<ArgumentException>(() => DirectLogicAddress.YOutputToCoil(bad));
+
+    [Fact]
+    public void YOutputToCoil_accepts_lowercase_prefix()
+        => DirectLogicAddress.YOutputToCoil("y0").ShouldBe((ushort)2048);
+
+    [Fact]
+    public void CRelayToCoil_accepts_bare_octal_without_C_prefix()
+        => DirectLogicAddress.CRelayToCoil("0").ShouldBe((ushort)3072);
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusCapTests.cs

@@ -0,0 +1,165 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
+
+[Trait("Category", "Unit")]
+public sealed class ModbusCapTests
+{
+    /// <summary>
+    ///     Records every PDU sent so tests can assert request-count and per-request quantity —
+    ///     the only observable behaviour of the auto-chunking path.
+    /// </summary>
+    private sealed class RecordingTransport : IModbusTransport
+    {
+        public readonly ushort[] HoldingRegisters = new ushort[1024];
+        public readonly List<(ushort Address, ushort Quantity)> Fc03Requests = new();
+        public readonly List<(ushort Address, ushort Quantity)> Fc16Requests = new();
+
+        public Task ConnectAsync(CancellationToken ct) => Task.CompletedTask;
+
+        public Task<byte[]> SendAsync(byte unitId, byte[] pdu, CancellationToken ct)
+        {
+            var fc = pdu[0];
+            if (fc == 0x03)
+            {
+                var addr = (ushort)((pdu[1] << 8) | pdu[2]);
+                var qty = (ushort)((pdu[3] << 8) | pdu[4]);
+                Fc03Requests.Add((addr, qty));
+                var byteCount = (byte)(qty * 2);
+                var resp = new byte[2 + byteCount];
+                resp[0] = 0x03;
+                resp[1] = byteCount;
+                for (var i = 0; i < qty; i++)
+                {
+                    resp[2 + i * 2] = (byte)(HoldingRegisters[addr + i] >> 8);
+                    resp[3 + i * 2] = (byte)(HoldingRegisters[addr + i] & 0xFF);
+                }
+                return Task.FromResult(resp);
+            }
+            if (fc == 0x10)
+            {
+                var addr = (ushort)((pdu[1] << 8) | pdu[2]);
+                var qty = (ushort)((pdu[3] << 8) | pdu[4]);
+                Fc16Requests.Add((addr, qty));
+                for (var i = 0; i < qty; i++)
+                    HoldingRegisters[addr + i] = (ushort)((pdu[6 + i * 2] << 8) | pdu[7 + i * 2]);
+                return Task.FromResult(new byte[] { 0x10, pdu[1], pdu[2], pdu[3], pdu[4] });
+            }
+            return Task.FromException<byte[]>(new ModbusException(fc, 0x01, $"fc={fc} unsupported"));
+        }
+
+        public ValueTask DisposeAsync() => ValueTask.CompletedTask;
+    }
+
+    [Fact]
+    public async Task Read_within_cap_issues_single_FC03_request()
+    {
+        var tag = new ModbusTagDefinition("S", ModbusRegion.HoldingRegisters, 0, ModbusDataType.String,
+            StringLength: 40); // 20 regs — fits in default cap (125).
+        var transport = new RecordingTransport();
+        var opts = new ModbusDriverOptions { Host = "fake", Tags = [tag], Probe = new ModbusProbeOptions { Enabled = false } };
+        await using var drv = new ModbusDriver(opts, "modbus-1", _ => transport);
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        _ = await drv.ReadAsync(["S"], TestContext.Current.CancellationToken);
+
+        transport.Fc03Requests.Count.ShouldBe(1);
+        transport.Fc03Requests[0].Quantity.ShouldBe((ushort)20);
+    }
+
+    [Fact]
+    public async Task Read_above_cap_splits_into_two_FC03_requests()
+    {
+        // 240-char string = 120 regs. Cap = 100 (a typical sub-spec device cap). Expect 100 + 20.
+        var tag = new ModbusTagDefinition("LongString", ModbusRegion.HoldingRegisters, 100, ModbusDataType.String,
+            StringLength: 240);
+        var transport = new RecordingTransport();
+        // Seed cells so the re-assembled payload is stable — confirms chunks are stitched in order.
+        for (ushort i = 100; i < 100 + 120; i++)
+            transport.HoldingRegisters[i] = (ushort)((('A' + (i - 100) % 26) << 8) | ('A' + (i - 100) % 26));
+
+        var opts = new ModbusDriverOptions
+        {
+            Host = "fake",
+            Tags = [tag],
+            MaxRegistersPerRead = 100,
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+        await using var drv = new ModbusDriver(opts, "modbus-1", _ => transport);
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await drv.ReadAsync(["LongString"], TestContext.Current.CancellationToken);
+        results[0].StatusCode.ShouldBe(0u);
+
+        transport.Fc03Requests.Count.ShouldBe(2, "120 regs / cap 100 → 2 requests");
+        transport.Fc03Requests[0].ShouldBe(((ushort)100, (ushort)100));
+        transport.Fc03Requests[1].ShouldBe(((ushort)200, (ushort)20));
+
+        // Payload continuity: re-assembled string starts where register 100 does and keeps going.
+        var s = (string)results[0].Value!;
+        s.Length.ShouldBeGreaterThan(0);
+        s[0].ShouldBe('A'); // register[100] high byte
+    }
+
+    [Fact]
+    public async Task Read_cap_honors_Mitsubishi_lower_cap_of_64()
+    {
+        // 200-char string = 100 regs. Mitsubishi Q cap = 64. Expect: 64, 36.
+        var tag = new ModbusTagDefinition("MitString", ModbusRegion.HoldingRegisters, 0, ModbusDataType.String,
+            StringLength: 200);
+        var transport = new RecordingTransport();
+        var opts = new ModbusDriverOptions { Host = "fake", Tags = [tag], MaxRegistersPerRead = 64, Probe = new ModbusProbeOptions { Enabled = false } };
+        await using var drv = new ModbusDriver(opts, "modbus-1", _ => transport);
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        _ = await drv.ReadAsync(["MitString"], TestContext.Current.CancellationToken);
+
+        transport.Fc03Requests.Count.ShouldBe(2);
+        transport.Fc03Requests[0].Quantity.ShouldBe((ushort)64);
+        transport.Fc03Requests[1].Quantity.ShouldBe((ushort)36);
+    }
+
+    [Fact]
+    public async Task Write_exceeding_cap_throws_instead_of_splitting()
+    {
+        // Partial FC16 across two transactions is not atomic. Forcing an explicit exception so the
+        // caller knows their tag definition is incompatible with the device cap rather than silently
+        // writing half a string and crashing between chunks.
+        var tag = new ModbusTagDefinition("LongStringWrite", ModbusRegion.HoldingRegisters, 0, ModbusDataType.String,
+            StringLength: 220); // 110 regs.
+        var transport = new RecordingTransport();
+        var opts = new ModbusDriverOptions { Host = "fake", Tags = [tag], MaxRegistersPerWrite = 100, Probe = new ModbusProbeOptions { Enabled = false } };
+        await using var drv = new ModbusDriver(opts, "modbus-1", _ => transport);
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await drv.WriteAsync(
+            [new WriteRequest("LongStringWrite", new string('A', 220))],
+            TestContext.Current.CancellationToken);
+
+        // Driver catches the internal exception and surfaces BadInternalError — the Fc16Requests
+        // list must still be empty because nothing was sent.
+        results[0].StatusCode.ShouldNotBe(0u);
+        transport.Fc16Requests.Count.ShouldBe(0);
+    }
+
+    [Fact]
+    public async Task Write_within_cap_proceeds_normally()
+    {
+        var tag = new ModbusTagDefinition("ShortStringWrite", ModbusRegion.HoldingRegisters, 0, ModbusDataType.String,
+            StringLength: 40); // 20 regs.
+        var transport = new RecordingTransport();
+        var opts = new ModbusDriverOptions { Host = "fake", Tags = [tag], MaxRegistersPerWrite = 100, Probe = new ModbusProbeOptions { Enabled = false } };
+        await using var drv = new ModbusDriver(opts, "modbus-1", _ => transport);
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await drv.WriteAsync(
+            [new WriteRequest("ShortStringWrite", "HELLO")],
+            TestContext.Current.CancellationToken);
+
+        results[0].StatusCode.ShouldBe(0u);
+        transport.Fc16Requests.Count.ShouldBe(1);
+        transport.Fc16Requests[0].Quantity.ShouldBe((ushort)20);
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusDataTypeTests.cs

@@ -219,4 +219,97 @@ public sealed class ModbusDataTypeTests
         ModbusDriver.DecodeRegister(wire, hi).ShouldBe("He");
         ModbusDriver.DecodeRegister(wire, lo).ShouldBe("eH");
     }
+
+    // --- BCD (binary-coded decimal, DL205/DL260 default numeric encoding) ---
+
+    [Theory]
+    [InlineData(0x0000u, 0u)]
+    [InlineData(0x0001u, 1u)]
+    [InlineData(0x0009u, 9u)]
+    [InlineData(0x0010u, 10u)]
+    [InlineData(0x1234u, 1234u)]
+    [InlineData(0x9999u, 9999u)]
+    public void DecodeBcd_16_bit_decodes_expected_decimal(uint raw, uint expected)
+        => ModbusDriver.DecodeBcd(raw, nibbles: 4).ShouldBe(expected);
+
+    [Fact]
+    public void DecodeBcd_rejects_nibbles_above_nine()
+    {
+        Should.Throw<InvalidDataException>(() => ModbusDriver.DecodeBcd(0x00A5u, nibbles: 4))
+            .Message.ShouldContain("Non-BCD nibble");
+    }
+
+    [Theory]
+    [InlineData(0u, 0x0000u)]
+    [InlineData(5u, 0x0005u)]
+    [InlineData(42u, 0x0042u)]
+    [InlineData(1234u, 0x1234u)]
+    [InlineData(9999u, 0x9999u)]
+    public void EncodeBcd_16_bit_encodes_expected_nibbles(uint value, uint expected)
+        => ModbusDriver.EncodeBcd(value, nibbles: 4).ShouldBe(expected);
+
+    [Fact]
+    public void Bcd16_decodes_DL205_register_1234_as_decimal_1234()
+    {
+        // HR[1072] = 0x1234 on the DL205 profile represents decimal 1234. A plain Int16 decode
+        // would return 0x04D2 = 4660 — proof the BCD path is different.
+        var tag = new ModbusTagDefinition("T", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Bcd16);
+        ModbusDriver.DecodeRegister(new byte[] { 0x12, 0x34 }, tag).ShouldBe(1234);
+
+        var int16Tag = tag with { DataType = ModbusDataType.Int16 };
+        ModbusDriver.DecodeRegister(new byte[] { 0x12, 0x34 }, int16Tag).ShouldBe((short)0x1234);
+    }
+
+    [Fact]
+    public void Bcd16_encode_round_trips_with_decode()
+    {
+        var tag = new ModbusTagDefinition("T", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Bcd16);
+        var wire = ModbusDriver.EncodeRegister(4321, tag);
+        wire.ShouldBe(new byte[] { 0x43, 0x21 });
+        ModbusDriver.DecodeRegister(wire, tag).ShouldBe(4321);
+    }
+
+    [Fact]
+    public void Bcd16_encode_rejects_out_of_range_values()
+    {
+        var tag = new ModbusTagDefinition("T", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Bcd16);
+        Should.Throw<OverflowException>(() => ModbusDriver.EncodeRegister(10000, tag))
+            .Message.ShouldContain("4 decimal digits");
+    }
+
+    [Fact]
+    public void Bcd32_decodes_8_digits_big_endian()
+    {
+        // 0x12345678 as BCD = decimal 12_345_678.
+        var tag = new ModbusTagDefinition("T", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Bcd32);
+        ModbusDriver.DecodeRegister(new byte[] { 0x12, 0x34, 0x56, 0x78 }, tag).ShouldBe(12_345_678);
+    }
+
+    [Fact]
+    public void Bcd32_word_swap_handles_CDAB_layout()
+    {
+        // PLC stored 12_345_678 with word swap: low-word 0x5678 first, high-word 0x1234 second.
+        // Wire bytes [0x56, 0x78, 0x12, 0x34] + WordSwap → decode to decimal 12_345_678.
+        var tag = new ModbusTagDefinition("T", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Bcd32,
+            ByteOrder: ModbusByteOrder.WordSwap);
+        ModbusDriver.DecodeRegister(new byte[] { 0x56, 0x78, 0x12, 0x34 }, tag).ShouldBe(12_345_678);
+    }
+
+    [Fact]
+    public void Bcd32_encode_round_trips_with_decode()
+    {
+        var tag = new ModbusTagDefinition("T", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Bcd32);
+        var wire = ModbusDriver.EncodeRegister(87_654_321u, tag);
+        wire.ShouldBe(new byte[] { 0x87, 0x65, 0x43, 0x21 });
+        ModbusDriver.DecodeRegister(wire, tag).ShouldBe(87_654_321);
+    }
+
+    [Fact]
+    public void Bcd_RegisterCount_matches_underlying_width()
+    {
+        var b16 = new ModbusTagDefinition("A", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Bcd16);
+        var b32 = new ModbusTagDefinition("B", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Bcd32);
+        ModbusDriver.RegisterCount(b16).ShouldBe((ushort)1);
+        ModbusDriver.RegisterCount(b32).ShouldBe((ushort)2);
+    }
 }

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusExceptionMapperTests.cs

@@ -0,0 +1,88 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
+
+/// <summary>
+///     Unit tests for the Modbus-exception-code → OPC UA StatusCode mapping added in PR 52.
+///     Before PR 52 every server exception + every transport failure collapsed to
+///     BadInternalError (0x80020000), which made field diagnosis "is this a bad tag or a bad
+///     driver?" impossible. These tests lock in the translation table documented on
+///     <see cref="ModbusDriver.MapModbusExceptionToStatus"/>.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class ModbusExceptionMapperTests
+{
+    [Theory]
+    [InlineData((byte)0x01, 0x803D0000u)] // Illegal Function → BadNotSupported
+    [InlineData((byte)0x02, 0x803C0000u)] // Illegal Data Address → BadOutOfRange
+    [InlineData((byte)0x03, 0x803C0000u)] // Illegal Data Value → BadOutOfRange
+    [InlineData((byte)0x04, 0x80550000u)] // Server Failure → BadDeviceFailure
+    [InlineData((byte)0x05, 0x80550000u)] // Acknowledge (long op) → BadDeviceFailure
+    [InlineData((byte)0x06, 0x80550000u)] // Server Busy → BadDeviceFailure
+    [InlineData((byte)0x0A, 0x80050000u)] // Gateway path unavailable → BadCommunicationError
+    [InlineData((byte)0x0B, 0x80050000u)] // Gateway target failed to respond → BadCommunicationError
+    [InlineData((byte)0xFF, 0x80020000u)] // Unknown code → BadInternalError fallback
+    public void MapModbusExceptionToStatus_returns_informative_status(byte code, uint expected)
+        => ModbusDriver.MapModbusExceptionToStatus(code).ShouldBe(expected);
+
+    private sealed class ExceptionRaisingTransport(byte exceptionCode) : IModbusTransport
+    {
+        public Task ConnectAsync(CancellationToken ct) => Task.CompletedTask;
+        public Task<byte[]> SendAsync(byte unitId, byte[] pdu, CancellationToken ct)
+            => Task.FromException<byte[]>(new ModbusException(pdu[0], exceptionCode, $"fc={pdu[0]} code={exceptionCode}"));
+        public ValueTask DisposeAsync() => ValueTask.CompletedTask;
+    }
+
+    [Fact]
+    public async Task Read_surface_exception_02_as_BadOutOfRange_not_BadInternalError()
+    {
+        var transport = new ExceptionRaisingTransport(exceptionCode: 0x02);
+        var tag = new ModbusTagDefinition("T", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16);
+        var opts = new ModbusDriverOptions { Host = "fake", Tags = [tag], Probe = new ModbusProbeOptions { Enabled = false } };
+        await using var drv = new ModbusDriver(opts, "modbus-1", _ => transport);
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await drv.ReadAsync(["T"], TestContext.Current.CancellationToken);
+        results[0].StatusCode.ShouldBe(0x803C0000u, "FC03 at an unmapped register must bubble out as BadOutOfRange so operators can spot a bad tag config");
+    }
+
+    [Fact]
+    public async Task Write_surface_exception_04_as_BadDeviceFailure()
+    {
+        var transport = new ExceptionRaisingTransport(exceptionCode: 0x04);
+        var tag = new ModbusTagDefinition("T", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16);
+        var opts = new ModbusDriverOptions { Host = "fake", Tags = [tag], Probe = new ModbusProbeOptions { Enabled = false } };
+        await using var drv = new ModbusDriver(opts, "modbus-1", _ => transport);
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var writes = await drv.WriteAsync(
+            [new WriteRequest("T", (short)42)],
+            TestContext.Current.CancellationToken);
+
+        writes[0].StatusCode.ShouldBe(0x80550000u, "FC06 returning exception 04 (CPU in PROGRAM mode) maps to BadDeviceFailure");
+    }
+
+    private sealed class NonModbusFailureTransport : IModbusTransport
+    {
+        public Task ConnectAsync(CancellationToken ct) => Task.CompletedTask;
+        public Task<byte[]> SendAsync(byte unitId, byte[] pdu, CancellationToken ct)
+            => Task.FromException<byte[]>(new EndOfStreamException("socket closed mid-response"));
+        public ValueTask DisposeAsync() => ValueTask.CompletedTask;
+    }
+
+    [Fact]
+    public async Task Read_non_modbus_failure_maps_to_BadCommunicationError_not_BadInternalError()
+    {
+        // Socket drop / timeout / malformed frame → transport-layer failure. Should surface
+        // distinctly from tag-level faults so operators know to check the network, not the config.
+        var tag = new ModbusTagDefinition("T", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16);
+        var opts = new ModbusDriverOptions { Host = "fake", Tags = [tag], Probe = new ModbusProbeOptions { Enabled = false } };
+        await using var drv = new ModbusDriver(opts, "modbus-1", _ => new NonModbusFailureTransport());
+        await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
+
+        var results = await drv.ReadAsync(["T"], TestContext.Current.CancellationToken);
+        results[0].StatusCode.ShouldBe(0x80050000u);
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusTcpReconnectTests.cs

@@ -0,0 +1,146 @@
+using System.Net;
+using System.Net.Sockets;
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
+
+/// <summary>
+///     Exercises <see cref="ModbusTcpTransport"/> against a real TCP listener that can close
+///     its socket mid-session on demand. Verifies the PR 53 reconnect-on-drop behavior: after
+///     the "first" socket is forcibly torn down, the next SendAsync must re-establish the
+///     connection and complete the PDU without bubbling an error to the caller.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class ModbusTcpReconnectTests
+{
+    /// <summary>
+    ///     Minimal in-process Modbus-TCP stub. Accepts one TCP connection at a time, reads an
+    ///     MBAP + PDU, replies with a canned FC03 response echoing the request quantity of
+    ///     zeroed bytes, then optionally closes the socket to simulate a NAT/firewall drop.
+    /// </summary>
+    private sealed class FlakeyModbusServer : IAsyncDisposable
+    {
+        private readonly TcpListener _listener;
+        public int Port => ((IPEndPoint)_listener.LocalEndpoint).Port;
+        public int DropAfterNTransactions { get; set; } = int.MaxValue;
+        private readonly CancellationTokenSource _stop = new();
+        private int _txCount;
+
+        public FlakeyModbusServer()
+        {
+            _listener = new TcpListener(IPAddress.Loopback, 0);
+            _listener.Start();
+            _ = Task.Run(AcceptLoopAsync);
+        }
+
+        private async Task AcceptLoopAsync()
+        {
+            while (!_stop.IsCancellationRequested)
+            {
+                TcpClient? client = null;
+                try { client = await _listener.AcceptTcpClientAsync(_stop.Token); }
+                catch { return; }
+
+                _ = Task.Run(() => ServeAsync(client!));
+            }
+        }
+
+        private async Task ServeAsync(TcpClient client)
+        {
+            try
+            {
+                using var _ = client;
+                var stream = client.GetStream();
+                while (!_stop.IsCancellationRequested && client.Connected)
+                {
+                    var header = new byte[7];
+                    if (!await ReadExactly(stream, header)) return;
+                    var len = (ushort)((header[4] << 8) | header[5]);
+                    var pdu = new byte[len - 1];
+                    if (!await ReadExactly(stream, pdu)) return;
+
+                    var fc = pdu[0];
+                    var qty = (ushort)((pdu[3] << 8) | pdu[4]);
+                    var respPdu = new byte[2 + qty * 2];
+                    respPdu[0] = fc;
+                    respPdu[1] = (byte)(qty * 2);
+                    // data bytes stay 0
+
+                    var respLen = (ushort)(1 + respPdu.Length);
+                    var adu = new byte[7 + respPdu.Length];
+                    adu[0] = header[0]; adu[1] = header[1];
+                    adu[4] = (byte)(respLen >> 8); adu[5] = (byte)(respLen & 0xFF);
+                    adu[6] = header[6];
+                    Buffer.BlockCopy(respPdu, 0, adu, 7, respPdu.Length);
+                    await stream.WriteAsync(adu);
+                    await stream.FlushAsync();
+
+                    _txCount++;
+                    if (_txCount >= DropAfterNTransactions)
+                    {
+                        // Simulate NAT/firewall silent close: slam the socket without a
+                        // protocol-level goodbye, which is what DL260 + an intermediate
+                        // middlebox would look like from the client's perspective.
+                        client.Client.Shutdown(SocketShutdown.Both);
+                        client.Close();
+                        return;
+                    }
+                }
+            }
+            catch { /* best-effort */ }
+        }
+
+        private static async Task<bool> ReadExactly(NetworkStream s, byte[] buf)
+        {
+            var read = 0;
+            while (read < buf.Length)
+            {
+                var n = await s.ReadAsync(buf.AsMemory(read));
+                if (n == 0) return false;
+                read += n;
+            }
+            return true;
+        }
+
+        public async ValueTask DisposeAsync()
+        {
+            _stop.Cancel();
+            _listener.Stop();
+            await Task.CompletedTask;
+        }
+    }
+
+    [Fact]
+    public async Task Transport_recovers_from_mid_session_drop_and_retries_successfully()
+    {
+        await using var server = new FlakeyModbusServer { DropAfterNTransactions = 1 };
+        await using var transport = new ModbusTcpTransport("127.0.0.1", server.Port, TimeSpan.FromSeconds(2), autoReconnect: true);
+        await transport.ConnectAsync(TestContext.Current.CancellationToken);
+
+        // First transaction succeeds; server then closes the socket.
+        var pdu = new byte[] { 0x03, 0x00, 0x00, 0x00, 0x01 };
+        var first = await transport.SendAsync(unitId: 1, pdu, TestContext.Current.CancellationToken);
+        first[0].ShouldBe((byte)0x03);
+
+        // Second transaction: the connection is dead, but auto-reconnect must transparently
+        // spin up a new socket, resend, and produce a valid response. Before PR 53 this would
+        // surface as EndOfStreamException / IOException to the caller.
+        var second = await transport.SendAsync(unitId: 1, pdu, TestContext.Current.CancellationToken);
+        second[0].ShouldBe((byte)0x03);
+    }
+
+    [Fact]
+    public async Task Transport_without_AutoReconnect_propagates_drop_to_caller()
+    {
+        await using var server = new FlakeyModbusServer { DropAfterNTransactions = 1 };
+        await using var transport = new ModbusTcpTransport("127.0.0.1", server.Port, TimeSpan.FromSeconds(2), autoReconnect: false);
+        await transport.ConnectAsync(TestContext.Current.CancellationToken);
+
+        var pdu = new byte[] { 0x03, 0x00, 0x00, 0x00, 0x01 };
+        _ = await transport.SendAsync(unitId: 1, pdu, TestContext.Current.CancellationToken);
+
+        await Should.ThrowAsync<Exception>(async () =>
+            await transport.SendAsync(unitId: 1, pdu, TestContext.Current.CancellationToken));
+    }
+}