Task #138 — Modbus addressing grammar docs + e2e
Closes the docs/e2e end of the Modbus addressing line shipped across #136-#145. Docs: - docs/v2/modbus-addressing.md (new) — full grammar reference. Region+offset (Modicon 5-digit / 6-digit / mnemonic), bit suffix, type codes (BOOL / I / UI / DI / UDI / LI / ULI / F / D / BCD / LBCD / STR<n>), all four byte-order mnemonics (ABCD / CDAB / BADC / DCBA), array-count semantics, family-native syntax (DL205 V/Y/C/X/SP and MELSEC D/M/X/Y with hex-vs-octal sub-family selection), driver-instance options (KeepAlive / Reconnect / IdleDisconnect, MaxCoilsPerRead and FC15/16 forcing, Deadband + WriteOnChangeOnly, MaxReadGap + CoalesceProhibited, multi-unit IPerCallHostResolver). Includes a worked JSON DTO example mixing AddressString + structured tag forms. - docs/Driver.Modbus.Cli.md — appended a "v2 addressing grammar" section pointing users at the full reference, with quick-reference examples. - Vendor-compatibility caveat documented: type codes and byte-order mnemonics were synthesised from training-era vendor docs (Wonderware DASMBTCP, Kepware KEPServerEX, Ignition, Matrikon, OAS) and should be verified against current vendor manuals before locking for production. E2E tests (4 new AddressingGrammarTests in IntegrationTests): - Modicon 5-digit and 6-digit forms map to identical wire offsets. - Float32 + WordSwap (CDAB) round-trips end-to-end through the pymodbus simulator. - Int16[5] array round-trips as a typed short[] surface. - Block-read coalescing produces a wire-acceptable PDU when MaxReadGap=5 bridges three nearby tags. All tests skip gracefully when the pymodbus simulator at localhost:5020 is unreachable (matches the existing ModbusSimulatorFixture pattern). Final test count across the Modbus addressing surface: - 107 ModbusAddressing.Tests (parser + family + Modicon) - 231 Driver.Modbus.Tests (driver, byte order, array, multi-unit, coalescing, protocol, subscribe, connection options) - 110 Admin.Tests (incl. ModbusOptionsViewModel defaults pinning) - 4 new AddressingGrammar integration tests (skip when sim down)
This commit is contained in:
@@ -119,3 +119,31 @@ address.
|
||||
**"What's the right byte order for this family?"** → `read` with
|
||||
`--byte-order BigEndian`, then with `--byte-order WordSwap`. The one that
|
||||
gives plausible values is the correct one for that device.
|
||||
|
||||
## v2 addressing grammar
|
||||
|
||||
The driver accepts the industry-standard tag-address grammar so you can
|
||||
paste tag spreadsheets from Wonderware / Kepware / Ignition without
|
||||
per-row manual translation. Full reference + grammar rules:
|
||||
[`docs/v2/modbus-addressing.md`](v2/modbus-addressing.md).
|
||||
|
||||
Quick examples:
|
||||
|
||||
```
|
||||
40001 HoldingRegisters[0], Int16
|
||||
400001 same, 6-digit form
|
||||
40001:F Float32
|
||||
40001:F:CDAB Float32 word-swapped
|
||||
40001:STR20 20-char ASCII string
|
||||
40001:I:5 Int16[5] array (3-field shorthand)
|
||||
40001:F:CDAB:10 Float32[10] with explicit word-swap (4-field strict)
|
||||
40001.5 bit 5 of HR[0]
|
||||
HR1:DI Int32 via mnemonic region prefix
|
||||
C100 Coil 100 (mnemonic, 1-based)
|
||||
V2000:F:CDAB DL205 V-memory at PDU 1024 + Float32 + word-swap (Family=DL205)
|
||||
D100:I MELSEC D-register 100 (Family=MELSEC)
|
||||
```
|
||||
|
||||
In `DriverConfig` JSON, set the per-tag `addressString` field instead of
|
||||
the structured `region` + `address` + `dataType` fields. Both styles can
|
||||
coexist within one driver instance.
|
||||
|
||||
Reference in New Issue
Block a user