dohertj2/lmxopcua
1
0
Fork 0
Code Issues 12 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(modbus-rtu): Modbus RTU-over-TCP transport (Wave 1) #495

Open
dohertj2 wants to merge 15 commits from feat/modbus-rtu-driver into master
pull from: feat/modbus-rtu-driver
merge into: dohertj2:master
Conversation 0 Commits 15 Files Changed 30
+1565 -192
dohertj2 commented 2026-07-24 15:52:26 -04:00
Owner
Copy Link
Copy Source

Summary

Adds a Modbus RTU-over-TCP transport (RTU CRC-16 framing tunnelled to a serial→Ethernet gateway) to the existing ModbusDriver, selected by a new Transport config field. Purely additive behind the existing IModbusTransport seam — the application protocol (function codes, codecs, planner, coalescing, write path, probe, materialisation, HistoryRead) is byte-for-byte identical across TCP and RTU; only the wire framing differs ([addr][PDU][CRC-16], no MBAP, no TxId). Zero changes to codecs/planner/health.

Wave 1 of the driver-expansion program. Plan: docs/plans/2026-07-24-modbus-rtu-driver.md (11 tasks).

What changed

  • ModbusTransportMode enum (Tcp | RtuOverTcp); ModbusCrc (CRC-16/MODBUS, golden vectors); ModbusRtuFraming (ADU build + FC-aware length-less deframe + response-unit validation + partial-read/truncation handling).
  • ModbusSocketLifecycle extracted from ModbusTcpTransport (behaviour-preserving) and composed by both transports; new ModbusRtuOverTcpTransport (single-flight gate — no TxId, per-op CancelAfter deadline, timeout-vs-caller-cancel distinction, ForTest stream-injection seam).
  • ModbusTransportFactory switch (throws on unknown mode); Transport bound on options/DTO/factory with the string-enum guard; driver default closure + Test-Connect probe routed through the factory.
  • AdminUI Transport selector on ModbusDriverForm (Protocol panel).
  • rtu_over_tcp pymodbus docker profile (framer=rtu, host :5021, co-runs with standard) + fixture + read/write integration tests. Confirmed on the wire that pymodbus 3.13 honours framer=rtu on a TCP server — no stdlib fallback needed.

Descoped (by design)

Direct-serial transport (System.IO.Ports) and Modbus ASCII — RTU buses are reached exclusively via a serial→Ethernet gateway. No per-tag config changes (the existing per-tag UnitId already makes a multi-drop bus work).

Test Plan

  • Modbus unit suite 344/344 green; full solution build 0 errors.
  • RTU integration tests pass live against a real framer=rtu pymodbus fixture (10.100.0.35:5021): read HR5→5, write+readback HR200←4242.
  • Per-task spec+code review chain + a final whole-branch review — all approved-to-merge.
  • Live /run gate on docker-dev (rig rebuilt from this branch): AdminUI Transport selector renders + persists RtuOverTcp; device Test Connect → OK · 23 ms (probe spoke FC03 over RTU framing); deployment 06ec1632 Sealed (6/6 nodes); Client.CLI read ns=2;s=rtu-gate/Device1/HR5 → 5/Good, write HR200=4242 → readback 4242/Good.

Follow-ups (non-blocking, tracked)

  • Add CrcMismatch / UnitMismatch members to DesyncReason (currently all RTU desync modes report TruncatedFrame; no downstream .Reason consumer today).

https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW

## Summary Adds a **Modbus RTU-over-TCP** transport (RTU CRC-16 framing tunnelled to a serial→Ethernet gateway) to the existing `ModbusDriver`, selected by a new `Transport` config field. Purely additive behind the existing `IModbusTransport` seam — the application protocol (function codes, codecs, planner, coalescing, write path, probe, materialisation, HistoryRead) is byte-for-byte identical across TCP and RTU; only the wire framing differs (`[addr][PDU][CRC-16]`, no MBAP, no TxId). **Zero** changes to codecs/planner/health. Wave 1 of the driver-expansion program. Plan: `docs/plans/2026-07-24-modbus-rtu-driver.md` (11 tasks). ### What changed - `ModbusTransportMode` enum (`Tcp` | `RtuOverTcp`); `ModbusCrc` (CRC-16/MODBUS, golden vectors); `ModbusRtuFraming` (ADU build + FC-aware length-less deframe + response-unit validation + partial-read/truncation handling). - `ModbusSocketLifecycle` extracted from `ModbusTcpTransport` (behaviour-preserving) and composed by both transports; new `ModbusRtuOverTcpTransport` (single-flight gate — no TxId, per-op `CancelAfter` deadline, timeout-vs-caller-cancel distinction, `ForTest` stream-injection seam). - `ModbusTransportFactory` switch (throws on unknown mode); `Transport` bound on options/DTO/factory with the string-enum guard; driver default closure + Test-Connect probe routed through the factory. - AdminUI `Transport` selector on `ModbusDriverForm` (Protocol panel). - `rtu_over_tcp` pymodbus docker profile (`framer=rtu`, host `:5021`, co-runs with `standard`) + fixture + read/write integration tests. **Confirmed on the wire that pymodbus 3.13 honours `framer=rtu` on a TCP server** — no stdlib fallback needed. ### Descoped (by design) Direct-serial transport (`System.IO.Ports`) and Modbus ASCII — RTU buses are reached exclusively via a serial→Ethernet gateway. No per-tag config changes (the existing per-tag `UnitId` already makes a multi-drop bus work). ## Test Plan - [x] Modbus unit suite **344/344** green; full solution build **0 errors**. - [x] RTU integration tests pass **live** against a real `framer=rtu` pymodbus fixture (`10.100.0.35:5021`): read HR5→5, write+readback HR200←4242. - [x] Per-task spec+code review chain + a final whole-branch review — all approved-to-merge. - [x] **Live `/run` gate on docker-dev (rig rebuilt from this branch):** AdminUI Transport selector renders + persists `RtuOverTcp`; device **Test Connect → OK · 23 ms** (probe spoke FC03 over RTU framing); deployment `06ec1632` **Sealed** (6/6 nodes); Client.CLI **read** `ns=2;s=rtu-gate/Device1/HR5` → 5/Good, **write** HR200=4242 → readback 4242/Good. ## Follow-ups (non-blocking, tracked) - Add `CrcMismatch` / `UnitMismatch` members to `DesyncReason` (currently all RTU desync modes report `TruncatedFrame`; no downstream `.Reason` consumer today). https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
dohertj2 added 15 commits 2026-07-24 15:52:27 -04:00
chore: gitignore .worktrees/ for subagent-driven-development 963eec1b32 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
feat(modbus-rtu): add ModbusTransportMode enum (Tcp | RtuOverTcp) e787aa572b 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
feat(modbus-rtu): add ModbusCrc CRC-16/MODBUS helper + golden vectors 8d0f60ec51 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
feat(modbus-rtu): add ModbusRtuFraming (ADU build + FC-aware length-less deframe) eed6617784 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
feat(modbus-rtu): validate response unit + cover partial-read/truncation in ModbusRtuFraming 20100c36ad 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
refactor(modbus): extract ModbusSocketLifecycle from ModbusTcpTransport (behaviour-preserving) 2f38b5b285 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
feat(modbus-rtu): add ModbusRtuOverTcpTransport (RTU framing over socket lifecycle) 47e9cd56ef 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
feat(modbus-rtu): bind Transport mode on options/DTO/factory (string-enum guard) 20be5416b9 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
feat(modbus-rtu): add ModbusTransportFactory switch on Transport mode 1d90bf3611 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
feat(modbus-rtu): route driver + probe transports through ModbusTransportFactory 13bd9820b0 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
feat(modbus-rtu): add Transport selector to the AdminUI Modbus driver form 132e7b63f6 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
test(modbus-rtu): add rtu_over_tcp pymodbus fixture + RTU-over-TCP integration tests 650e27075f 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
docs(modbus-rtu): note the co-running :5021 rtu_over_tcp fixture in Docker README + Dockerfile 4a8c9badce 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
harden(modbus-rtu): factory throws on unknown transport + document RTU FC-shape assumption fcc7ed698e 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
docs(modbus-rtu): record Wave-1 RTU-over-TCP live /run gate result (PASSED)
v2-ci / build (pull_request) Successful in 3m45s
Details
v2-ci / unit-tests (pull_request) Failing after 13m54s
Details
e27eb77187 
Claude-Session: https://claude.ai/code/session_01GASWkNEi68FSCtvr6rLoEW
Some checks are pending
v2-ci / build (pull_request) Successful in 3m45s
Details
v2-ci / unit-tests (pull_request) Failing after 13m54s
Details
This pull request can be merged automatically.
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feat/modbus-rtu-driver:feat/modbus-rtu-driver
git checkout feat/modbus-rtu-driver
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
auto-managed
queue management
 cross-driver
queue management
 driver/abcip
queue management
 driver/ablegacy
queue management
 driver/focas
queue management
 driver/opcuaclient
queue management
 driver/s7
queue management
 driver/twincat
queue management
 phase/1
queue management
 phase/2
queue management
 phase/3
queue management
 phase/4
queue management
 phase/5
queue management
 phase/6
queue management
 queue/blocked
queue management
 queue/done
queue management
 queue/failed
queue management
 queue/in-progress
queue management
 queue/queued
queue management
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
dohertj2 (dohertj2)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: dohertj2/lmxopcua#495
Delete Branch "feat/modbus-rtu-driver"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?