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

Task #146 — Modbus addressing: align type codes with Wonderware DASMBTCP + Ignition

Browse Source 
Web verification (2026-04-25) against current vendor docs surfaced concrete
grammar conflicts in the v1 suffix grammar shipped in #137. Hard cutover
before the Admin UI rolls out widely so users don't paste `:I` from a
Wonderware spreadsheet and silently get wrong-typed reads.

Sources:
- Wonderware DASMBTCP user guide
  https://cdn.logic-control.com/media/DASMBTCP.pdf
- Ignition Modbus addressing (8.1)
  https://www.docs.inductiveautomation.com/docs/8.1/ignition-modules/opc-ua/opc-ua-drivers/modbus/modbus-addressing

Type-code changes:

| Code   | Pre-#146 | Post-#146  | Vendor reference            |
|--------|----------|------------|------------------------------|
| `:S`   | (n/a)    | Int16      | Wonderware DASMBTCP `S`      |
| `:US`  | (n/a)    | UInt16     | Ignition `HRUS`              |
| `:I`   | Int16    | **Int32**  | Wonderware `I` + Ignition `HRI` |
| `:UI`  | UInt16   | **UInt32** | Ignition `HRUI`              |
| `:I_64`  | (n/a)  | Int64      | Ignition `HRI_64`            |
| `:UI_64` | (n/a)  | UInt64     | Ignition `HRUI_64`           |
| `:BCD_32`| (n/a)  | BCD32      | Ignition `HRBCD_32`          |

Codes REMOVED (no clear vendor precedent + conflict with the new mapping):
`:DI`, `:L`, `:UDI`, `:UL`, `:LI`, `:ULI`, `:LBCD`. Pre-#146 configs that
use them get an "Unknown type code" diagnostic at parse time so users get
a fast surface-level error rather than silent wrong-typed reads.

Codes UNCHANGED (already vendor-aligned): `:BOOL`, `:F`, `:D`, `:BCD`,
`:STR<n>`. Modicon 5/6-digit + mnemonic regions (HR/IR/C/DI) + bit suffix
`.N` are also unchanged.

Defaults:
- Coils / DiscreteInputs → `BOOL` (unchanged)
- HoldingRegisters / InputRegisters with no explicit type → Int16 (matches
  Ignition's bare `HR` default)

Byte-order mnemonics (`:ABCD` / `:CDAB` / `:BADC` / `:DCBA`) are kept but
documented as OtOpcUa-specific — they aren't in any major vendor's per-tag
address string. Ignition uses a `-R` suffix per prefix; Wonderware
configures word-order at the topic level.

Tests:
- 12 Type_Codes_Parse rows updated to assert the new mappings.
- New Removed_Aliases_Are_Rejected (×7) confirms each pre-#146 alias now
  fails fast with "Unknown type code".
- Worked_Example_Int16_Array uses the new `:S` code.
- New Worked_Example_Int32_Array_Via_I_Code documents the `:I = Int32`
  vendor-alignment intent so a future "fix" doesn't accidentally regress.
- Unknown_Type_Code_Rejected_With_Catalog updated to match the new error
  message ("Valid: BOOL, S, US, I, ...").

Docs:
- docs/v2/modbus-addressing.md — table replaced with the post-#146 codes,
  each row cites its Wonderware / Ignition reference. New "Codes removed
  in #146" subsection documents the cutover.
- docs/Driver.Modbus.Cli.md — example grammar list updated; explicit
  type-code reminder appended.

114 addressing tests + 231 driver tests still green. Solution build clean.
This commit is contained in:
Joseph Doherty
2026-04-25 00:51:50 -04:00
parent 5ea57d2d70
commit dfd027ebca
5 changed files with 116 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/Driver.Modbus.Cli.md
View File

@@ -135,15 +135,21 @@ Quick examples:
40001:F Float32 40001:F Float32
40001:F:CDAB Float32 word-swapped 40001:F:CDAB Float32 word-swapped
40001:STR20 20-char ASCII string 40001:STR20 20-char ASCII string
40001:I:5 Int16[5] array (3-field shorthand) 40001:S:5 Int16[5] array (3-field shorthand)
40001:F:CDAB:10 Float32[10] with explicit word-swap (4-field strict) 40001:F:CDAB:10 Float32[10] with explicit word-swap (4-field strict)
40001.5 bit 5 of HR[0] 40001.5 bit 5 of HR[0]
HR1:DI Int32 via mnemonic region prefix HR1:I Int32 via mnemonic region prefix (matches Wonderware)
C100 Coil 100 (mnemonic, 1-based) C100 Coil 100 (mnemonic, 1-based)
V2000:F:CDAB DL205 V-memory at PDU 1024 + Float32 + word-swap (Family=DL205) V2000:F:CDAB DL205 V-memory at PDU 1024 + Float32 + word-swap (Family=DL205)
D100:I MELSEC D-register 100 (Family=MELSEC) D100:I MELSEC D-register 100, Int32 (Family=MELSEC)
``` ```
**Type-code reminder** (post-#146): `:I` is **Int32** (matches Wonderware
DASMBTCP + Ignition `HRI`). The explicit Int16 code is `:S`. Bare HR/IR
with no type still defaults to Int16. Pre-#146 codes `:DI` / `:L` /
`:UDI` / `:UL` / `:LI` / `:ULI` / `:LBCD` are removed; configs that use
them get a clear "Unknown type code" diagnostic at parse time.
In `DriverConfig` JSON, set the per-tag `addressString` field instead of In `DriverConfig` JSON, set the per-tag `addressString` field instead of
the structured `region` + `address` + `dataType` fields. Both styles can the structured `region` + `address` + `dataType` fields. Both styles can
coexist within one driver instance. coexist within one driver instance.

43
docs/v2/modbus-addressing.md
View File

@@ -41,24 +41,37 @@ mixing with an explicit type or array-count is rejected.
### Type code `:T` ### Type code `:T`
| Code | Type | Registers | Codes verified 2026-04-25 against [Wonderware DASMBTCP user
|---|---|---| guide](https://cdn.logic-control.com/media/DASMBTCP.pdf) and the
| `BOOL` | Boolean | 1 (region must be Coils / DiscreteInputs) | [Ignition Modbus addressing
| `I` | Int16 | 1 | manual](https://www.docs.inductiveautomation.com/docs/8.1/ignition-modules/opc-ua/opc-ua-drivers/modbus/modbus-addressing).
| `UI` | UInt16 | 1 | The `I` / `UI` / `I_64` / `UI_64` / `BCD_32` shapes match Wonderware's
| `DI`, `L` | Int32 | 2 | suffix convention and Ignition's underscore-N prefix variants where
| `UDI`, `UL` | UInt32 | 2 | those vendors agree.
| `LI` | Int64 | 4 |
| `ULI` | UInt64 | 4 | | Code | Type | Registers | Vendor reference |
| `F` | Float32 | 2 | |---|---|---|---|
| `D` | Float64 | 4 | | `BOOL` | Boolean | 1 (region must be Coils / DiscreteInputs) | universal |
| `BCD` | 16-bit BCD | 1 | | `S` | Int16 | 1 | Wonderware DASMBTCP `S` = 16-bit signed |
| `LBCD` | 32-bit BCD | 2 | | `US` | UInt16 | 1 | Ignition `HRUS` = Unsigned Short |
| `STR<len>` | ASCII string, `len` chars (2 chars / register) | `ceil(len/2)` | | `I` | Int32 | 2 | Wonderware DASMBTCP `I` = 32-bit signed; Ignition `HRI` |
| `UI` | UInt32 | 2 | Ignition `HRUI` |
| `I_64` | Int64 | 4 | Ignition `HRI_64` |
| `UI_64` | UInt64 | 4 | Ignition `HRUI_64` |
| `F` | Float32 | 2 | Wonderware `F`; Ignition `HRF` |
| `D` | Float64 | 4 | Ignition `HRD` |
| `BCD` | 16-bit BCD | 1 | Ignition `HRBCD` |
| `BCD_32` | 32-bit BCD | 2 | Ignition `HRBCD_32` |
| `STR<len>` | ASCII string, `len` chars (2 chars / register) | `ceil(len/2)` | analogous to Ignition `HRS<addr>:<len>` |
Default when omitted: Default when omitted:
- Coils / DiscreteInputs → `BOOL` - Coils / DiscreteInputs → `BOOL`
- HoldingRegisters / InputRegisters → `I` (Int16) - HoldingRegisters / InputRegisters → `S` (Int16) — matches Ignition's bare-`HR` default
**Codes removed in #146** (silent wrong-data risk, never compatible with the
two reference vendors): `:DI`, `:L`, `:UDI`, `:UL`, `:LI`, `:ULI`, `:LBCD`.
Pre-#146 configs that use these get a clear "Unknown type code" diagnostic at
parse time; rewrite to the post-#146 codes per the table above.
### Byte order `:O` ### Byte order `:O`

34
src/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Addressing/ModbusAddressParser.cs
View File

@@ -15,7 +15,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
/// spreadsheets from any of those tools without per-tag manual translation. /// spreadsheets from any of those tools without per-tag manual translation.
/// </para> /// </para>
/// <para> /// <para>
/// Examples: /// Examples (post-#146 type codes — verified against Wonderware DASMBTCP + Ignition):
/// <list type="bullet"> /// <list type="bullet">
/// <item><c>40001</c> — HoldingRegisters[0], Int16 (default).</item> /// <item><c>40001</c> — HoldingRegisters[0], Int16 (default).</item>
/// <item><c>400001</c> — HoldingRegisters[0], Int16 (6-digit form).</item> /// <item><c>400001</c> — HoldingRegisters[0], Int16 (6-digit form).</item>
@@ -23,9 +23,9 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
/// <item><c>40001:F</c> — Float32 starting at HR[0] (consumes HR[0..1]).</item> /// <item><c>40001:F</c> — Float32 starting at HR[0] (consumes HR[0..1]).</item>
/// <item><c>40001:F:CDAB</c> — same with word-swap byte order.</item> /// <item><c>40001:F:CDAB</c> — same with word-swap byte order.</item>
/// <item><c>40001:STR20</c> — 20-char ASCII string.</item> /// <item><c>40001:STR20</c> — 20-char ASCII string.</item>
/// <item><c>HR1:DI</c> — Int32 at HR[0] using mnemonic region.</item> /// <item><c>HR1:I</c> — Int32 at HR[0] using mnemonic region (Wonderware-aligned).</item>
/// <item><c>40001:F:5</c> — Float32[5] array (consumes HR[0..9]).</item> /// <item><c>40001:F:5</c> — Float32[5] array (consumes HR[0..9]).</item>
/// <item><c>40001:I::10</c> — Int16[10] using default byte order (empty order field).</item> /// <item><c>40001:S::10</c> — Int16[10] using default byte order (empty order field).</item>
/// <item><c>C100</c> — Coils[99] (mnemonic).</item> /// <item><c>C100</c> — Coils[99] (mnemonic).</item>
/// </list> /// </list>
/// </para> /// </para>
@@ -365,25 +365,37 @@ public static class ModbusAddressParser
return true; return true;
} }
// #146 — codes aligned with Wonderware DASMBTCP + Ignition Modbus driver after the
// 2026-04-25 vendor-doc verification:
// - `:I` is Int32 (Wonderware: "letter 'I' follow ... 32-bit signed quantity, two
// consecutive registers"). Ignition's HRI is also Int32. The pre-#146 mapping
// `:I` = Int16 silently produced wrong-typed data + offset-shifted neighbours when
// a tag spreadsheet was pasted from another vendor.
// - `:S` is the explicit Int16 code (Wonderware: "letter 'S' ... 16-bit signed").
// - `:US` is UInt16 (Ignition: HRUS = "Unsigned Short").
// - `:UI` is UInt32 (parallel to `:I` shape; matches Ignition HRUI).
// - `:I_64` / `:UI_64` for 64-bit (Ignition HRI_64 / HRUI_64 underscore-N convention).
// - `:BCD_32` for 32-bit BCD (Ignition HRBCD_32). The pre-#146 `:LBCD` is dropped.
// - HR/IR with no explicit type still default to Int16 (matches Ignition `HR`).
type = text.ToUpperInvariant() switch type = text.ToUpperInvariant() switch
{ {
"BOOL" => ModbusDataType.Bool, "BOOL" => ModbusDataType.Bool,
"I" => ModbusDataType.Int16, "S" => ModbusDataType.Int16,
"UI" => ModbusDataType.UInt16, "US" => ModbusDataType.UInt16,
"DI" or "L" => ModbusDataType.Int32, "I" => ModbusDataType.Int32,
"UDI" or "UL" => ModbusDataType.UInt32, "UI" => ModbusDataType.UInt32,
"LI" => ModbusDataType.Int64, "I_64" => ModbusDataType.Int64,
"ULI" => ModbusDataType.UInt64, "UI_64" => ModbusDataType.UInt64,
"F" => ModbusDataType.Float32, "F" => ModbusDataType.Float32,
"D" => ModbusDataType.Float64, "D" => ModbusDataType.Float64,
"BCD" => ModbusDataType.Bcd16, "BCD" => ModbusDataType.Bcd16,
"LBCD" => ModbusDataType.Bcd32, "BCD_32" => ModbusDataType.Bcd32,
_ => (ModbusDataType)(-1), _ => (ModbusDataType)(-1),
}; };
if ((int)type == -1) if ((int)type == -1)
{ {
error = $"Unknown type code '{text}'. Valid: BOOL, I, UI, DI, L, UDI, UL, LI, ULI, F, D, BCD, LBCD, STR<n>"; error = $"Unknown type code '{text}'. Valid: BOOL, S, US, I, UI, I_64, UI_64, F, D, BCD, BCD_32, STR<n>";
return false; return false;
} }

2
src/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusDriverFactoryExtensions.cs
View File

@@ -208,7 +208,7 @@ public static class ModbusDriverFactoryExtensions
/// Address grammar string per <c>ModbusAddressParser</c> — when present, takes /// Address grammar string per <c>ModbusAddressParser</c> — when present, takes
/// precedence over the structured Region/Address/DataType/ByteOrder/BitIndex/ /// precedence over the structured Region/Address/DataType/ByteOrder/BitIndex/
/// StringLength/ArrayCount fields. Examples: <c>"40001"</c>, <c>"40001:F"</c>, /// StringLength/ArrayCount fields. Examples: <c>"40001"</c>, <c>"40001:F"</c>,
/// <c>"40001:F:CDAB:5"</c>, <c>"HR1:DI"</c>, <c>"C100"</c>. /// <c>"40001:F:CDAB:5"</c>, <c>"HR1:I"</c>, <c>"C100"</c>.
/// </summary> /// </summary>
public string? AddressString { get; init; } public string? AddressString { get; init; }

73
tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Addressing.Tests/ModbusAddressParserTests.cs
View File

@@ -74,26 +74,48 @@ public sealed class ModbusAddressParserTests
// ----- Type codes ----- // ----- Type codes -----
// #146 — codes verified against current Wonderware DASMBTCP + Ignition Modbus docs
// (2026-04-25). `:I` = Int32 (was Int16) per Wonderware; `:S` is the explicit Int16 code.
// `:US` for UInt16 (Ignition HRUS). `:I_64` / `:UI_64` for 64-bit (Ignition HRI_64).
// `:BCD_32` for 32-bit BCD (Ignition HRBCD_32). The pre-#146 `:DI`/`:L`/`:UDI`/`:UL`/
// `:LI`/`:ULI`/`:LBCD` aliases are removed — they conflict with the Wonderware mapping
// and have no clear vendor precedent.
[Theory] [Theory]
[InlineData("40001:BOOL", ModbusDataType.Bool)] [InlineData("40001:BOOL", ModbusDataType.Bool)]
[InlineData("40001:I", ModbusDataType.Int16)] [InlineData("40001:S", ModbusDataType.Int16)]
[InlineData("40001:UI", ModbusDataType.UInt16)] [InlineData("40001:US", ModbusDataType.UInt16)]
[InlineData("40001:DI", ModbusDataType.Int32)] [InlineData("40001:I", ModbusDataType.Int32)]
[InlineData("40001:L", ModbusDataType.Int32)] [InlineData("40001:UI", ModbusDataType.UInt32)]
[InlineData("40001:UDI", ModbusDataType.UInt32)] [InlineData("40001:I_64", ModbusDataType.Int64)]
[InlineData("40001:UL", ModbusDataType.UInt32)] [InlineData("40001:UI_64", ModbusDataType.UInt64)]
[InlineData("40001:LI", ModbusDataType.Int64)] [InlineData("40001:F", ModbusDataType.Float32)]
[InlineData("40001:ULI", ModbusDataType.UInt64)] [InlineData("40001:D", ModbusDataType.Float64)]
[InlineData("40001:F", ModbusDataType.Float32)] [InlineData("40001:BCD", ModbusDataType.Bcd16)]
[InlineData("40001:D", ModbusDataType.Float64)] [InlineData("40001:BCD_32", ModbusDataType.Bcd32)]
[InlineData("40001:BCD", ModbusDataType.Bcd16)] [InlineData("40001:f", ModbusDataType.Float32)] // lowercase
[InlineData("40001:LBCD", ModbusDataType.Bcd32)] [InlineData("40001:i_64", ModbusDataType.Int64)] // lowercase + underscore form
[InlineData("40001:f", ModbusDataType.Float32)] // lowercase
public void Type_Codes_Parse(string addr, ModbusDataType expected) public void Type_Codes_Parse(string addr, ModbusDataType expected)
{ {
ModbusAddressParser.Parse(addr).DataType.ShouldBe(expected); ModbusAddressParser.Parse(addr).DataType.ShouldBe(expected);
} }
[Theory]
[InlineData("40001:DI")] // pre-#146 alias removed
[InlineData("40001:L")]
[InlineData("40001:UDI")]
[InlineData("40001:UL")]
[InlineData("40001:LI")]
[InlineData("40001:ULI")]
[InlineData("40001:LBCD")]
public void Removed_Aliases_Are_Rejected(string addr)
{
// Defensive — these used to be accepted; now they fail with a clear "Unknown type code"
// diagnostic so users with legacy spreadsheets get a fast surface-level error rather
// than silent wrong-typed reads.
Should.Throw<FormatException>(() => ModbusAddressParser.Parse(addr))
.Message.ShouldContain("Unknown type code");
}
[Theory] [Theory]
[InlineData("40001:STR1", 1)] [InlineData("40001:STR1", 1)]
[InlineData("40001:STR20", 20)] [InlineData("40001:STR20", 20)]
@@ -123,7 +145,7 @@ public sealed class ModbusAddressParserTests
public void Unknown_Type_Code_Rejected_With_Catalog() public void Unknown_Type_Code_Rejected_With_Catalog()
{ {
Should.Throw<FormatException>(() => ModbusAddressParser.Parse("40001:WIDGET")) Should.Throw<FormatException>(() => ModbusAddressParser.Parse("40001:WIDGET"))
.Message.ShouldContain("Valid: BOOL, I,"); .Message.ShouldContain("Valid: BOOL, S, US, I,");
} }
// ----- Region-type compatibility ----- // ----- Region-type compatibility -----
@@ -165,10 +187,13 @@ public sealed class ModbusAddressParserTests
[Fact] [Fact]
public void Empty_Order_Field_Means_Default() public void Empty_Order_Field_Means_Default()
{ {
// 40001:I::5 → Int16 array, no order override, default (BigEndian). // 40001:I::5 → Int32 array (5 elements), no order override, default (BigEndian).
// The empty middle field is the strict-mode marker that "third position is array count,
// not byte order" — exercises the 4-field positional parse without a byte-order value.
var p = ModbusAddressParser.Parse("40001:I::5"); var p = ModbusAddressParser.Parse("40001:I::5");
p.ByteOrder.ShouldBe(ModbusByteOrder.BigEndian); p.ByteOrder.ShouldBe(ModbusByteOrder.BigEndian);
p.ArrayCount.ShouldBe(5); p.ArrayCount.ShouldBe(5);
p.DataType.ShouldBe(ModbusDataType.Int32);
} }
// ----- Array count ----- // ----- Array count -----
@@ -177,7 +202,7 @@ public sealed class ModbusAddressParserTests
[InlineData("40001:I:ABCD:1", 1)] [InlineData("40001:I:ABCD:1", 1)]
[InlineData("40001:F:5", 5)] [InlineData("40001:F:5", 5)]
[InlineData("40001:F:CDAB:10", 10)] [InlineData("40001:F:CDAB:10", 10)]
[InlineData("40001:DI:100", 100)] [InlineData("40001:S:100", 100)] // Int16[100] via the post-#146 :S code
public void Array_Count_Parses(string addr, int expectedCount) public void Array_Count_Parses(string addr, int expectedCount)
{ {
ModbusAddressParser.Parse(addr).ArrayCount.ShouldBe(expectedCount); ModbusAddressParser.Parse(addr).ArrayCount.ShouldBe(expectedCount);
@@ -220,13 +245,25 @@ public sealed class ModbusAddressParserTests
[Fact] [Fact]
public void Worked_Example_Int16_Array() public void Worked_Example_Int16_Array()
{ {
var p = ModbusAddressParser.Parse("40001:I::10"); // Post-#146: :S is the explicit Int16 code. (`:I` is now Int32 per Wonderware.)
var p = ModbusAddressParser.Parse("40001:S::10");
p.Region.ShouldBe(ModbusRegion.HoldingRegisters); p.Region.ShouldBe(ModbusRegion.HoldingRegisters);
p.DataType.ShouldBe(ModbusDataType.Int16); p.DataType.ShouldBe(ModbusDataType.Int16);
p.ArrayCount.ShouldBe(10); p.ArrayCount.ShouldBe(10);
p.ByteOrder.ShouldBe(ModbusByteOrder.BigEndian); p.ByteOrder.ShouldBe(ModbusByteOrder.BigEndian);
} }
[Fact]
public void Worked_Example_Int32_Array_Via_I_Code()
{
// Companion to the above — `:I` now means Int32 (matches Wonderware DASMBTCP and
// Ignition HRI). Anyone with `:I` in legacy spreadsheets gets a different type than
// pre-#146; that's the intended semantic alignment.
var p = ModbusAddressParser.Parse("40001:I::10");
p.DataType.ShouldBe(ModbusDataType.Int32);
p.ArrayCount.ShouldBe(10);
}
[Fact] [Fact]
public void Worked_Example_Float_Array_Word_Swap_6_Digit() public void Worked_Example_Float_Array_Word_Swap_6_Digit()
{ {