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

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

@@ -74,26 +74,48 @@ public sealed class ModbusAddressParserTests
// ----- 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]
[InlineData("40001:BOOL", ModbusDataType.Bool)]
[InlineData("40001:I", ModbusDataType.Int16)]
[InlineData("40001:UI", ModbusDataType.UInt16)]
[InlineData("40001:DI", ModbusDataType.Int32)]
[InlineData("40001:L", ModbusDataType.Int32)]
[InlineData("40001:UDI", ModbusDataType.UInt32)]
[InlineData("40001:UL", ModbusDataType.UInt32)]
[InlineData("40001:LI", ModbusDataType.Int64)]
[InlineData("40001:ULI", ModbusDataType.UInt64)]
[InlineData("40001:F", ModbusDataType.Float32)]
[InlineData("40001:D", ModbusDataType.Float64)]
[InlineData("40001:BCD", ModbusDataType.Bcd16)]
[InlineData("40001:LBCD", ModbusDataType.Bcd32)]
[InlineData("40001:f", ModbusDataType.Float32)] // lowercase
[InlineData("40001:BOOL", ModbusDataType.Bool)]
[InlineData("40001:S", ModbusDataType.Int16)]
[InlineData("40001:US", ModbusDataType.UInt16)]
[InlineData("40001:I", ModbusDataType.Int32)]
[InlineData("40001:UI", ModbusDataType.UInt32)]
[InlineData("40001:I_64", ModbusDataType.Int64)]
[InlineData("40001:UI_64", ModbusDataType.UInt64)]
[InlineData("40001:F", ModbusDataType.Float32)]
[InlineData("40001:D", ModbusDataType.Float64)]
[InlineData("40001:BCD", ModbusDataType.Bcd16)]
[InlineData("40001:BCD_32", ModbusDataType.Bcd32)]
[InlineData("40001:f", ModbusDataType.Float32)] // lowercase
[InlineData("40001:i_64", ModbusDataType.Int64)] // lowercase + underscore form
public void Type_Codes_Parse(string addr, ModbusDataType 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]
[InlineData("40001:STR1", 1)]
[InlineData("40001:STR20", 20)]
@@ -123,7 +145,7 @@ public sealed class ModbusAddressParserTests
public void Unknown_Type_Code_Rejected_With_Catalog()
{
Should.Throw<FormatException>(() => ModbusAddressParser.Parse("40001:WIDGET"))
.Message.ShouldContain("Valid: BOOL, I,");
.Message.ShouldContain("Valid: BOOL, S, US, I,");
}
// ----- Region-type compatibility -----
@@ -165,10 +187,13 @@ public sealed class ModbusAddressParserTests
[Fact]
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");
p.ByteOrder.ShouldBe(ModbusByteOrder.BigEndian);
p.ArrayCount.ShouldBe(5);
p.DataType.ShouldBe(ModbusDataType.Int32);
}
// ----- Array count -----
@@ -177,7 +202,7 @@ public sealed class ModbusAddressParserTests
[InlineData("40001:I:ABCD:1", 1)]
[InlineData("40001:F:5", 5)]
[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)
{
ModbusAddressParser.Parse(addr).ArrayCount.ShouldBe(expectedCount);
@@ -220,13 +245,25 @@ public sealed class ModbusAddressParserTests
[Fact]
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.DataType.ShouldBe(ModbusDataType.Int16);
p.ArrayCount.ShouldBe(10);
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]
public void Worked_Example_Float_Array_Word_Swap_6_Digit()
{