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:
Joseph Doherty
@@ -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.
|
||||
|
||||
195
docs/v2/modbus-addressing.md
Normal file
195
docs/v2/modbus-addressing.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# Modbus tag-addressing reference
|
||||
|
||||
Foundational doc for the Modbus addressing grammar shipped across #136–#144.
|
||||
Covers the address-string parser (`ModbusAddressParser`) that the wire driver
|
||||
and the Admin UI both consume, the per-tag suffix modifiers, and the family-
|
||||
native branch.
|
||||
|
||||
## Grammar
|
||||
|
||||
```
|
||||
<region><offset>[.<bit>][:<type>[<len>]][:<order>][:<count>]
|
||||
```
|
||||
|
||||
Each field is optional from left to right; the parser fills defaults.
|
||||
|
||||
### Region + offset
|
||||
|
||||
Three accepted forms — pick whichever matches your tag spreadsheet's
|
||||
convention. All three resolve to the same `(Region, ushort PduOffset)`
|
||||
on the wire.
|
||||
|
||||
| Form | Example | Means |
|
||||
|---|---|---|
|
||||
| Modicon 5-digit | `40001` | Holding register 1 (PDU 0) |
|
||||
| Modicon 6-digit | `400001` | Holding register 1 (PDU 0); supports up to `465536` (PDU 65535) |
|
||||
| Mnemonic | `HR1`, `IR1`, `C100`, `DI1` | Same regions; `1`-based register number |
|
||||
|
||||
Modicon leading-digit → region:
|
||||
|
||||
| Digit | Region | OPC UA wire FC |
|
||||
|---|---|---|
|
||||
| `0` | Coils | FC01 / FC05 / FC15 |
|
||||
| `1` | DiscreteInputs | FC02 (read-only) |
|
||||
| `3` | InputRegisters | FC04 (read-only) |
|
||||
| `4` | HoldingRegisters | FC03 / FC06 / FC16 |
|
||||
|
||||
### Bit suffix `.N`
|
||||
|
||||
`40001.5` = bit 5 (LSB-first) of HR[0]. Implies `DataType=BitInRegister`;
|
||||
mixing with an explicit type or array-count is rejected.
|
||||
|
||||
### Type code `:T`
|
||||
|
||||
| Code | Type | Registers |
|
||||
|---|---|---|
|
||||
| `BOOL` | Boolean | 1 (region must be Coils / DiscreteInputs) |
|
||||
| `I` | Int16 | 1 |
|
||||
| `UI` | UInt16 | 1 |
|
||||
| `DI`, `L` | Int32 | 2 |
|
||||
| `UDI`, `UL` | UInt32 | 2 |
|
||||
| `LI` | Int64 | 4 |
|
||||
| `ULI` | UInt64 | 4 |
|
||||
| `F` | Float32 | 2 |
|
||||
| `D` | Float64 | 4 |
|
||||
| `BCD` | 16-bit BCD | 1 |
|
||||
| `LBCD` | 32-bit BCD | 2 |
|
||||
| `STR<len>` | ASCII string, `len` chars (2 chars / register) | `ceil(len/2)` |
|
||||
|
||||
Default when omitted:
|
||||
- Coils / DiscreteInputs → `BOOL`
|
||||
- HoldingRegisters / InputRegisters → `I` (Int16)
|
||||
|
||||
### Byte order `:O`
|
||||
|
||||
| Mnemonic | Meaning | Wire |
|
||||
|---|---|---|
|
||||
| `ABCD` | Big-endian (Modbus spec default) | `[A,B,C,D]` |
|
||||
| `CDAB` | Word swap (Siemens, several AB) | `[C,D,A,B]` |
|
||||
| `BADC` | Byte swap (legacy little-endian-internal devices) | `[B,A,D,C]` |
|
||||
| `DCBA` | Full reverse (some EtherNet/IP gateways) | `[D,C,B,A]` |
|
||||
|
||||
For 8-byte values (Int64 / Float64) the same labels apply pairwise.
|
||||
|
||||
### Array count `:N`
|
||||
|
||||
`40001:F:5` = `Float32[5]` (consumes HR[0..9]). Array + bit suffix is
|
||||
rejected. Strings are not arrays.
|
||||
|
||||
### Composition
|
||||
|
||||
The 3-field shorthand `40001:F:5` is parsed as `(type=F, count=5)` because
|
||||
`5` isn't a valid byte-order mnemonic. Use the explicit 4-field form
|
||||
`40001:F:CDAB:5` when you need a non-default order.
|
||||
|
||||
## Family-native syntax (#144)
|
||||
|
||||
When the driver instance has `Family != Generic`, the parser tries the
|
||||
family's native syntax FIRST, then falls back to Modicon / mnemonic.
|
||||
|
||||
### DL205 (AutomationDirect DirectLOGIC)
|
||||
|
||||
| Form | Example | Mapping |
|
||||
|---|---|---|
|
||||
| `Vnnnn` (octal) | `V2000` | HoldingRegisters[1024] (octal 2000 = decimal 1024) |
|
||||
| `Ynn` (octal) | `Y17` | Coils[2048 + 15] (Y-output base + offset) |
|
||||
| `Cnn` (octal) | `C100` | Coils[3072 + 64] (C-relay base + offset) |
|
||||
| `Xnn` (octal) | `X17` | DiscreteInputs[15] |
|
||||
| `SPnn` (octal) | `SP10` | DiscreteInputs[1024 + 8] |
|
||||
|
||||
**Cross-family ambiguity**: `C100` means Coils[99] under `Generic`
|
||||
(mnemonic) but Coils[3136] under `DL205`. Per-driver Family choice
|
||||
disambiguates.
|
||||
|
||||
### MELSEC (Mitsubishi)
|
||||
|
||||
| Form | Example | Mapping (sub-family Q_L_iQR / F_iQF) |
|
||||
|---|---|---|
|
||||
| `Dnnn` (decimal) | `D100` | HoldingRegisters[100] |
|
||||
| `Mnnn` (decimal) | `M50` | Coils[50] |
|
||||
| `Xnn` | `X20` | DiscreteInputs[32 hex / 16 octal] |
|
||||
| `Ynn` | `Y20` | Coils[32 hex / 16 octal] |
|
||||
|
||||
X / Y digit interpretation depends on `MelsecSubFamily`:
|
||||
- `Q_L_iQR` → hex (default)
|
||||
- `F_iQF` → octal
|
||||
|
||||
Bank-base offsets default to 0 in the grammar string. Sites with non-zero
|
||||
"Modbus Device Assignment" bases use the structured tag form.
|
||||
|
||||
## Driver-instance options
|
||||
|
||||
Beyond per-tag addressing, `ModbusDriverOptions` exposes (#139–#143):
|
||||
|
||||
### Connection (#139)
|
||||
- `KeepAlive { Enabled, Time, Interval, RetryCount }` — TCP-level probes.
|
||||
Defaults match the historical PR 53 wire output (Enabled=true, Time=30s,
|
||||
Interval=10s, RetryCount=3).
|
||||
- `IdleDisconnectTimeout` — proactively close + reconnect after this much
|
||||
socket idle time. Default null = disabled.
|
||||
- `Reconnect { InitialDelay, MaxDelay, BackoffMultiplier }` — geometric
|
||||
backoff for the post-drop reconnect loop. Default
|
||||
`(0, 30s, 2.0)` = immediate first retry, geometric thereafter.
|
||||
|
||||
### Protocol (#140)
|
||||
- `MaxCoilsPerRead` (default 2000) — separate cap for FC01/FC02 coil reads.
|
||||
- `UseFC15ForSingleCoilWrites` — force FC15 (write multiple coils
|
||||
qty=1) for single-coil writes. Safety/audit PLCs may require this.
|
||||
- `UseFC16ForSingleRegisterWrites` — same for FC16 vs FC06.
|
||||
- `DisableFC23` — kill switch for FC23 (currently unused; reserved).
|
||||
|
||||
### Subscribe (#141)
|
||||
- Per-tag `Deadband` — suppress sub-threshold publishes on numeric tags.
|
||||
- `WriteOnChangeOnly` (driver-level) — short-circuit identical-value
|
||||
writes. Cache invalidates on read-divergence.
|
||||
|
||||
### Multi-unit (#142)
|
||||
- Per-tag `UnitId` — overrides the driver-level UnitId in the MBAP
|
||||
header. Required for one-Ethernet-gateway / N-RTU-slave deployments.
|
||||
- `IPerCallHostResolver.ResolveHost` returns `host:port/unitN` per tag so
|
||||
per-PLC circuit breakers fire per slave.
|
||||
- Per-tag `CoalesceProhibited` — escape hatch for #143's planner (read
|
||||
this tag in isolation regardless of `MaxReadGap`).
|
||||
|
||||
### Block-read coalescing (#143)
|
||||
- `MaxReadGap` (default 0 = off) — gap budget the planner is willing to
|
||||
bridge between adjacent register tags. With `MaxReadGap=10`, three tags
|
||||
at HR 100/102/110 collapse into one FC03 of quantity 11.
|
||||
|
||||
## JSON DTO shape
|
||||
|
||||
The factory accepts both the structured form (legacy) and the new
|
||||
`AddressString` form per-tag. Mix freely — newer pasted rows use the
|
||||
grammar string; legacy rows keep the structured fields.
|
||||
|
||||
```json
|
||||
{
|
||||
"host": "10.1.2.3",
|
||||
"port": 502,
|
||||
"unitId": 1,
|
||||
"family": "DL205",
|
||||
"keepAlive": { "enabled": true, "timeMs": 30000, "intervalMs": 10000, "retryCount": 3 },
|
||||
"idleDisconnectMs": 120000,
|
||||
"reconnect": { "initialDelayMs": 0, "maxDelayMs": 30000, "backoffMultiplier": 2.0 },
|
||||
"maxCoilsPerRead": 2000,
|
||||
"writeOnChangeOnly": false,
|
||||
"maxReadGap": 8,
|
||||
"tags": [
|
||||
{ "name": "Temp", "addressString": "V2000:F:CDAB" },
|
||||
{ "name": "Setpoint", "addressString": "40001:I" },
|
||||
{ "name": "Outputs", "addressString": "Y0:5" },
|
||||
{ "name": "AlarmCount", "region": "HoldingRegisters", "address": 200, "dataType": "Int16", "deadband": 5.0 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Vendor compatibility caveat
|
||||
|
||||
The exact spelling of type codes (e.g. `I` vs `INT`, `BCD` vs `L_BCD`) and
|
||||
the byte-order mnemonics were synthesised from training-era vendor docs
|
||||
(Wonderware DASMBTCP, Kepware KEPServerEX, Ignition, Matrikon, OAS).
|
||||
Before locking the grammar for a production deployment, verify against
|
||||
the current Kepware "Modbus Ethernet Driver Help" PDF and Ignition's
|
||||
"Modbus Addressing" user-manual page — if a critical tool's mnemonics
|
||||
have shifted, add aliases in `ModbusAddressParser.TryParseType` rather
|
||||
than asking users to rewrite spreadsheets.
|
||||
@@ -0,0 +1,108 @@
|
||||
using Shouldly;
|
||||
using Xunit;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
using ZB.MOM.WW.OtOpcUa.Driver.Modbus;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests;
|
||||
|
||||
/// <summary>
|
||||
/// #138 e2e coverage for the new addressing grammar (#136-#144) against a live pymodbus
|
||||
/// simulator. Skips when the simulator is unreachable so the suite stays portable on dev
|
||||
/// boxes without Docker. Coverage is breadth-first — one round-trip per major feature
|
||||
/// (Modicon parse, suffix grammar, byte order, array, multi-unit) — rather than exhaustive,
|
||||
/// because the unit tests already pin the per-call semantics; the integration tests prove
|
||||
/// the wire glue agrees with the simulator end-to-end.
|
||||
/// </summary>
|
||||
[Trait("Category", "Integration")]
|
||||
[Collection("ModbusSimulator")]
|
||||
public sealed class AddressingGrammarTests
|
||||
{
|
||||
private readonly ModbusSimulatorFixture _sim;
|
||||
public AddressingGrammarTests(ModbusSimulatorFixture sim) => _sim = sim;
|
||||
|
||||
private async Task<ModbusDriver> NewDriverAsync(params ModbusTagDefinition[] tags)
|
||||
{
|
||||
var opts = new ModbusDriverOptions
|
||||
{
|
||||
Host = _sim.Host, Port = _sim.Port, Tags = tags,
|
||||
Probe = new ModbusProbeOptions { Enabled = false },
|
||||
};
|
||||
var drv = new ModbusDriver(opts, "addressing-e2e");
|
||||
await drv.InitializeAsync("{}", CancellationToken.None);
|
||||
return drv;
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task Modicon_5_And_6_Digit_Both_Map_To_Same_Wire_Offset()
|
||||
{
|
||||
if (_sim.SkipReason is not null) Assert.Skip(_sim.SkipReason);
|
||||
|
||||
// Both tags target HR offset 0 via different grammar forms; reads should be equivalent.
|
||||
var t5 = new ModbusTagDefinition("Five", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16);
|
||||
var t6 = new ModbusTagDefinition("Six", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16);
|
||||
var drv = await NewDriverAsync(t5, t6);
|
||||
|
||||
var values = await drv.ReadAsync(["Five", "Six"], CancellationToken.None);
|
||||
values[0].StatusCode.ShouldBe(values[1].StatusCode);
|
||||
values[0].Value.ShouldBe(values[1].Value);
|
||||
|
||||
await drv.ShutdownAsync(CancellationToken.None);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task Float32_With_CDAB_Roundtrips_Through_Wire()
|
||||
{
|
||||
if (_sim.SkipReason is not null) Assert.Skip(_sim.SkipReason);
|
||||
|
||||
var tag = new ModbusTagDefinition("Tank", ModbusRegion.HoldingRegisters, 100, ModbusDataType.Float32,
|
||||
ByteOrder: ModbusByteOrder.WordSwap);
|
||||
var drv = await NewDriverAsync(tag);
|
||||
|
||||
await drv.WriteAsync([new WriteRequest("Tank", 12.5f)], CancellationToken.None);
|
||||
var read = await drv.ReadAsync(["Tank"], CancellationToken.None);
|
||||
read[0].Value.ShouldBe(12.5f);
|
||||
|
||||
await drv.ShutdownAsync(CancellationToken.None);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task Int16_Array_Reads_Surface_As_Typed_Array()
|
||||
{
|
||||
if (_sim.SkipReason is not null) Assert.Skip(_sim.SkipReason);
|
||||
|
||||
var tag = new ModbusTagDefinition("Levels", ModbusRegion.HoldingRegisters, 200, ModbusDataType.Int16, ArrayCount: 5);
|
||||
var drv = await NewDriverAsync(tag);
|
||||
|
||||
await drv.WriteAsync([new WriteRequest("Levels", new short[] { 10, 20, 30, 40, 50 })], CancellationToken.None);
|
||||
var read = await drv.ReadAsync(["Levels"], CancellationToken.None);
|
||||
var arr = read[0].Value.ShouldBeOfType<short[]>();
|
||||
arr.ShouldBe(new short[] { 10, 20, 30, 40, 50 });
|
||||
|
||||
await drv.ShutdownAsync(CancellationToken.None);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task Block_Read_Coalescing_Reduces_PDU_Count_End_To_End()
|
||||
{
|
||||
if (_sim.SkipReason is not null) Assert.Skip(_sim.SkipReason);
|
||||
|
||||
// Sanity check that the simulator accepts the larger PDU coalescing produces.
|
||||
var t1 = new ModbusTagDefinition("T1", ModbusRegion.HoldingRegisters, 300, ModbusDataType.Int16);
|
||||
var t2 = new ModbusTagDefinition("T2", ModbusRegion.HoldingRegisters, 302, ModbusDataType.Int16);
|
||||
var t3 = new ModbusTagDefinition("T3", ModbusRegion.HoldingRegisters, 304, ModbusDataType.Int16);
|
||||
var opts = new ModbusDriverOptions
|
||||
{
|
||||
Host = _sim.Host, Port = _sim.Port, Tags = [t1, t2, t3], MaxReadGap = 5,
|
||||
Probe = new ModbusProbeOptions { Enabled = false },
|
||||
};
|
||||
var drv = new ModbusDriver(opts, "addressing-e2e");
|
||||
await drv.InitializeAsync("{}", CancellationToken.None);
|
||||
|
||||
var read = await drv.ReadAsync(["T1", "T2", "T3"], CancellationToken.None);
|
||||
read.Count.ShouldBe(3);
|
||||
// All three should read Good (the simulator accepts a 5-register coalesced read).
|
||||
read.All(v => v.StatusCode == 0u).ShouldBeTrue("coalesced read must succeed against the simulator");
|
||||
|
||||
await drv.ShutdownAsync(CancellationToken.None);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user