Phase 3 PR 49 -- Per-device FC03/FC16 register caps with auto-chunking #48

dohertj2 · 2026-04-18T22:13:43-04:00

dohertj2 commented

2026-04-18 22:13:43 -04:00

Summary

Stacked on PR 48. Adds per-driver MaxRegistersPerRead (default 125, spec max) + MaxRegistersPerWrite (default 123, spec max) options and auto-chunks FC03 reads that exceed the cap.

Reads: driver transparently splits oversized requests into consecutive chunks and stitches the payload back together. One Read() call still produces one result.
Writes: over-cap explicitly rejected -- splitting FC16 breaks atomicity. Caller gets BadInternalError with a message naming the tag + cap + escape hatch.
Cap cheat-sheet in xml-doc: DL205/DL260 = 125 read / 100 write, Mitsubishi Q/FX3U = 64 / 64, Omron CJ/CS = 125 / 123.
Prevents silent-connection-drop failure mode on PLCs that reject over-cap requests without a clean exception code.

Validation

103/103 Modbus.Tests pass (including 5 new ModbusCapTests with RecordingTransport asserting exact chunk (Address, Quantity) tuples)
6/6 DL205 integration tests still pass

Test plan

Single-chunk path unchanged (no unnecessary chunking)
120 regs / cap 100 → 100+20 chunks at correct addresses
100 regs / cap 64 (Mitsubishi) → 64+36
Over-cap write rejected, no partial wire traffic
Under-cap write proceeds as single FC16

## Summary Stacked on PR 48. Adds per-driver `MaxRegistersPerRead` (default 125, spec max) + `MaxRegistersPerWrite` (default 123, spec max) options and auto-chunks FC03 reads that exceed the cap. - Reads: driver transparently splits oversized requests into consecutive chunks and stitches the payload back together. One `Read()` call still produces one result. - Writes: over-cap explicitly rejected -- splitting FC16 breaks atomicity. Caller gets `BadInternalError` with a message naming the tag + cap + escape hatch. - Cap cheat-sheet in xml-doc: DL205/DL260 = 125 read / 100 write, Mitsubishi Q/FX3U = 64 / 64, Omron CJ/CS = 125 / 123. - Prevents silent-connection-drop failure mode on PLCs that reject over-cap requests without a clean exception code. ## Validation - 103/103 Modbus.Tests pass (including 5 new `ModbusCapTests` with RecordingTransport asserting exact chunk (Address, Quantity) tuples) - 6/6 DL205 integration tests still pass ## Test plan - [x] Single-chunk path unchanged (no unnecessary chunking) - [x] 120 regs / cap 100 → 100+20 chunks at correct addresses - [x] 100 regs / cap 64 (Mitsubishi) → 64+36 - [x] Over-cap write rejected, no partial wire traffic - [x] Under-cap write proceeds as single FC16

dohertj2 added 1 commit 2026-04-18 22:13:44 -04:00

Phase 3 PR 49 -- Per-device FC03/FC16 register caps with auto-chunking. Adds MaxRegistersPerRead (default 125, spec max) + MaxRegistersPerWrite (default 123, spec max) to ModbusDriverOptions. Reads that exceed the cap automatically split into consecutive FC03 requests: the driver dispatches chunks of [cap] regs at incrementing addresses, copies each response into an assembled byte[] buffer, and hands the full payload to DecodeRegister. From the caller's view a 240-char string read against a cap-100 device is still one Read() call returning one string -- the chunking is invisible, the wire shows N requests of cap-sized quantity plus one tail chunk. Writes are NOT auto-chunked. Splitting an FC16 across two transactions would lose atomicity -- mid-split crash leaves half the value written, which is strictly worse than rejecting upfront. Instead, writes exceeding MaxRegistersPerWrite throw InvalidOperationException with a message naming the tag + cap + the caller's escape hatch (shorten StringLength or split into multiple tags). The driver catches the exception internally and surfaces it to IWritable as BadInternalError so the caller pattern stays symmetric with other failure modes. Per-family cap cheat-sheet (documented in xml-doc on the option): Modbus-TCP spec = 125 read / 123 write, AutomationDirect DL205/DL260 = 128 read / 100 write (128 exceeds spec byte-count capacity so in practice 125 is the working ceiling), Mitsubishi Q/FX3U = 64 / 64, Omron CJ/CS = 125 / 123. Not all PLCs reject over-cap requests cleanly -- some drop the connection silently -- so having the cap enforced client-side prevents the hard-to-diagnose 'driver just stopped' failure mode. Unit tests: Read_within_cap_issues_single_FC03_request (control: no unnecessary chunking), Read_above_cap_splits_into_two_FC03_requests (120 regs / cap 100 -> 100+20, asserts exact per-chunk (Address,Quantity) and end-to-end payload continuity starting with register[100] high byte = 'A'), Read_cap_honors_Mitsubishi_lower_cap_of_64 (100 regs / cap 64 -> 64+36), Write_exceeding_cap_throws_instead_of_splitting (110 regs / cap 100 -> status != 0 AND Fc16Requests.Count == 0 to prove nothing was sent), Write_within_cap_proceeds_normally (control: cap honored on short writes too). Tests use a new RecordingTransport that captures the (Address, Quantity) tuple of every FC03/FC16 request so the chunk layout is directly assertable -- the existing FakeTransport does not expose request history. 103/103 Modbus.Tests pass; 6/6 DL205 integration tests still pass against the live pymodbus dl205 profile with MODBUS_SIM_PROFILE=dl205. a3f2f95344

dohertj2 merged commit dae29f14c8 into v2

2026-04-18 22:13:48 -04:00

dohertj2 referenced this issue from a commit

2026-04-18 22:13:50 -04:00

Merge pull request 'Phase 3 PR 49 -- Per-device FC03/FC16 register caps with auto-chunking' (#48) from phase-3-pr49-dl205-fc-caps into v2

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dohertj2/lmxopcua#48