Task #137 — Modbus per-tag suffix grammar (type / bit / byte-order / array)
Adds the full Wonderware/Kepware/Ignition-style address suffix grammar so users paste tag spreadsheets without per-tag manual translation: <region><offset>[.<bit>][:<type>[<len>]][:<order>][:<count>] Examples that now parse end-to-end: 40001 HoldingRegisters[0], Int16 400001 same, 6-digit form 40001.5 bit 5 of HR[0] 40001:F Float32 (HR[0..1]) 40001:F:CDAB word-swapped Float32 40001:STR20 20-char ASCII string HR1:DI Int32 via mnemonic region C100 Coils[99] (mnemonic) 40001:F:5 Float32[5] array (3-field shorthand) 40001:I:CDAB:10 Int16[10] word-swapped (4-field strict) Driver-side plumbing: - ModbusAddressParser + ParsedModbusAddress in the shared Addressing assembly. 91 parser tests (every grammar variant + malformed shapes). - ModbusDataType / ModbusByteOrder moved to shared (with the same namespace so callers compile unchanged). ModbusByteOrder gains ByteSwap (BADC) and FullReverse (DCBA) alongside the existing BigEndian (ABCD) and WordSwap (CDAB). - NormalizeWordOrder extended to honor all four orders for both 4-byte and 8-byte values. Old WordSwap behavior preserved bit-for-bit. - ModbusTagDefinition gains optional ArrayCount. - ReadOneAsync / WriteOneAsync handle array fan-out: one FC03/04 read covers N consecutive register-typed elements, decoded into a typed array (short[], float[], etc.). Coil arrays use FC01 reads + FC15 writes (FakeTransport in tests gains FC15 support to match). - DriverAttributeInfo IsArray / ArrayDim flow from ArrayCount so the OPC UA address space surfaces ValueRank=1 + ArrayDimensions to clients. - ModbusDriverFactoryExtensions gains AddressString DTO field. When present, the parser drives Region/Address/DataType/ByteOrder/Bit/ StringLength/ArrayCount; structured fields (Writable, WriteIdempotent, StringByteOrder) still come from the DTO. Existing structured tag rows keep working unchanged. Tests: 91 parser unit tests (Driver.Modbus.Addressing.Tests, all green) + 204 driver tests including new ModbusByteOrderTests (BADC/DCBA roundtrips across Int32/Float32/Float64) and ModbusArrayTests (Int16[5], Float32[3] CDAB, Coil[10], length-mismatch error, IsArray/ArrayDim discovery). Solution-wide build clean. Caveat: grammar names (type codes, byte-order mnemonics, the :count shorthand) were synthesized from training-era vendor docs. Verify against current Kepware Modbus Ethernet Driver Help and Ignition Modbus Addressing manuals before freezing for production deployments — naming may need a back-compat layer if vendor wording has shifted.
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,334 @@
|
||||
using System.Globalization;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
|
||||
|
||||
/// <summary>
|
||||
/// Parses the full Modbus tag-address grammar:
|
||||
/// <c><region><offset>[.<bit>][:<type>[<len>]][:<order>][:<count>]</c>.
|
||||
/// Output is a <see cref="ParsedModbusAddress"/> the driver-side config layer maps onto a
|
||||
/// <c>ModbusTagDefinition</c>.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// The grammar mirrors industry conventions (Wonderware suffix style, Kepware/Modicon
|
||||
/// digit prefixes, Ignition mnemonic prefixes — all accepted) so users can paste tag
|
||||
/// spreadsheets from any of those tools without per-tag manual translation.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Examples:
|
||||
/// <list type="bullet">
|
||||
/// <item><c>40001</c> — HoldingRegisters[0], Int16 (default).</item>
|
||||
/// <item><c>400001</c> — HoldingRegisters[0], Int16 (6-digit form).</item>
|
||||
/// <item><c>40001.5</c> — bit 5 of HoldingRegisters[0].</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:STR20</c> — 20-char ASCII string.</item>
|
||||
/// <item><c>HR1:DI</c> — Int32 at HR[0] using mnemonic region.</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>C100</c> — Coils[99] (mnemonic).</item>
|
||||
/// </list>
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class ModbusAddressParser
|
||||
{
|
||||
/// <summary>Parse an address string. Throws <see cref="FormatException"/> on invalid input.</summary>
|
||||
public static ParsedModbusAddress Parse(string address)
|
||||
{
|
||||
if (TryParse(address, out var parsed, out var error))
|
||||
return parsed!;
|
||||
throw new FormatException(error);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Try-parse variant for config-bind paths that surface diagnostics rather than throw.
|
||||
/// <paramref name="result"/> is null and <paramref name="error"/> non-null on failure.
|
||||
/// </summary>
|
||||
public static bool TryParse(string? address, out ParsedModbusAddress? result, out string? error)
|
||||
{
|
||||
result = null;
|
||||
|
||||
if (string.IsNullOrWhiteSpace(address))
|
||||
{
|
||||
error = "Modbus address is null or empty";
|
||||
return false;
|
||||
}
|
||||
|
||||
var s = address.Trim();
|
||||
|
||||
// Split on ':' — the fields are: <region+offset>[.bit] :type :order :count.
|
||||
// Empty fields (e.g. "40001:I::5") are allowed and mean "use default."
|
||||
var parts = s.Split(':');
|
||||
if (parts.Length > 4)
|
||||
{
|
||||
error = $"Modbus address has too many ':'-separated fields ({parts.Length} > 4): '{address}'";
|
||||
return false;
|
||||
}
|
||||
|
||||
var addressPart = parts[0];
|
||||
var typePart = parts.Length > 1 ? parts[1] : null;
|
||||
string? orderPart = null;
|
||||
string? countPart = null;
|
||||
|
||||
// 3-field form is shorthand: <addr>:<type>:<X>. X is either a byte-order mnemonic
|
||||
// (4 letters — ABCD/CDAB/BADC/DCBA) or an array count (digits). Disambiguate by shape
|
||||
// so users can write 40001:F:5 for Float[5] without the awkward 40001:F::5. Anything
|
||||
// else surfaces a clear error in whichever slot it lands.
|
||||
if (parts.Length == 3)
|
||||
{
|
||||
if (LooksLikeByteOrderToken(parts[2])) orderPart = parts[2];
|
||||
else if (parts[2].All(char.IsDigit)) countPart = parts[2];
|
||||
else
|
||||
{
|
||||
error = $"3rd field '{parts[2]}' must be a 4-letter byte order (ABCD/CDAB/BADC/DCBA) or a positive integer array count in '{address}'";
|
||||
return false;
|
||||
}
|
||||
}
|
||||
else if (parts.Length == 4)
|
||||
{
|
||||
orderPart = parts[2];
|
||||
countPart = parts[3];
|
||||
}
|
||||
|
||||
if (!TryParseRegionAndOffset(addressPart, out var region, out var offset, out var bit, out error))
|
||||
return false;
|
||||
|
||||
// Type field — defaults: Bool for Coils/DiscreteInputs, Int16 for InputRegisters/HoldingRegisters,
|
||||
// BitInRegister when bit-suffix is present.
|
||||
ModbusDataType dataType;
|
||||
ushort stringLen = 0;
|
||||
|
||||
if (bit.HasValue)
|
||||
{
|
||||
// Bit suffix forces BitInRegister; explicit type would conflict.
|
||||
if (!string.IsNullOrEmpty(typePart))
|
||||
{
|
||||
error = $"Bit suffix '.{bit.Value}' cannot combine with explicit type ':{typePart}' in '{address}'";
|
||||
return false;
|
||||
}
|
||||
dataType = ModbusDataType.BitInRegister;
|
||||
}
|
||||
else if (string.IsNullOrEmpty(typePart))
|
||||
{
|
||||
dataType = region is ModbusRegion.Coils or ModbusRegion.DiscreteInputs
|
||||
? ModbusDataType.Bool
|
||||
: ModbusDataType.Int16;
|
||||
}
|
||||
else
|
||||
{
|
||||
if (!TryParseType(typePart, out dataType, out stringLen, out error))
|
||||
return false;
|
||||
}
|
||||
|
||||
// Region/type compatibility check — Coils and DiscreteInputs only carry Bool semantics.
|
||||
if (region is ModbusRegion.Coils or ModbusRegion.DiscreteInputs && dataType != ModbusDataType.Bool)
|
||||
{
|
||||
error = $"Region {region} only supports Bool-typed tags; got {dataType} in '{address}'";
|
||||
return false;
|
||||
}
|
||||
|
||||
// Order field — defaults to BigEndian; only meaningful for multi-register types.
|
||||
var order = ModbusByteOrder.BigEndian;
|
||||
if (!string.IsNullOrEmpty(orderPart))
|
||||
{
|
||||
if (!TryParseByteOrder(orderPart, out order, out error))
|
||||
return false;
|
||||
}
|
||||
|
||||
// Count field — array length. Bit + array is rejected.
|
||||
int? arrayCount = null;
|
||||
if (!string.IsNullOrEmpty(countPart))
|
||||
{
|
||||
if (bit.HasValue)
|
||||
{
|
||||
error = $"Bit suffix and array count cannot combine in '{address}'";
|
||||
return false;
|
||||
}
|
||||
if (!int.TryParse(countPart, NumberStyles.None, CultureInfo.InvariantCulture, out var parsedCount) || parsedCount < 1)
|
||||
{
|
||||
error = $"Array count must be a positive integer; got '{countPart}' in '{address}'";
|
||||
return false;
|
||||
}
|
||||
arrayCount = parsedCount;
|
||||
}
|
||||
|
||||
result = new ParsedModbusAddress(region, offset, bit, dataType, stringLen, order, arrayCount);
|
||||
error = null;
|
||||
return true;
|
||||
}
|
||||
|
||||
private static bool TryParseRegionAndOffset(string text, out ModbusRegion region, out ushort offset, out byte? bit, out string? error)
|
||||
{
|
||||
region = default;
|
||||
offset = 0;
|
||||
bit = null;
|
||||
|
||||
if (string.IsNullOrEmpty(text))
|
||||
{
|
||||
error = "Region/offset segment is empty";
|
||||
return false;
|
||||
}
|
||||
|
||||
// Optional bit suffix: '.N' at the end, N in 0..15. Strip before parsing region/offset.
|
||||
var dotIdx = text.IndexOf('.');
|
||||
var addrText = dotIdx < 0 ? text : text[..dotIdx];
|
||||
if (dotIdx >= 0)
|
||||
{
|
||||
var bitText = text[(dotIdx + 1)..];
|
||||
if (!byte.TryParse(bitText, NumberStyles.None, CultureInfo.InvariantCulture, out var bitVal) || bitVal > 15)
|
||||
{
|
||||
error = $"Bit index must be 0..15; got '{bitText}'";
|
||||
return false;
|
||||
}
|
||||
bit = bitVal;
|
||||
}
|
||||
|
||||
// Try mnemonic prefix first (HR, IR, C, DI). Cheaper than the digit branch and
|
||||
// unambiguous when present. DI must be checked before D — we don't currently use D
|
||||
// alone but stay defensive.
|
||||
if (TryParseMnemonicAddress(addrText, out region, out offset, out error))
|
||||
return true;
|
||||
|
||||
// Fall back to Modicon (5/6-digit). Reuses #136's parser.
|
||||
if (ModbusModiconAddress.TryParse(addrText, out region, out offset, out error))
|
||||
return true;
|
||||
|
||||
// Both branches failed; the Modicon error is the more specific diagnostic.
|
||||
return false;
|
||||
}
|
||||
|
||||
private static bool TryParseMnemonicAddress(string text, out ModbusRegion region, out ushort offset, out string? error)
|
||||
{
|
||||
region = default;
|
||||
offset = 0;
|
||||
error = null;
|
||||
|
||||
// Mnemonic = letter prefix + 1-based register number. We require pure-digit suffix
|
||||
// after the prefix; anything else (including the Modicon-digit forms) falls through
|
||||
// to the Modicon parser.
|
||||
(string Prefix, ModbusRegion Region)[] candidates =
|
||||
[
|
||||
("HR", ModbusRegion.HoldingRegisters),
|
||||
("IR", ModbusRegion.InputRegisters),
|
||||
("DI", ModbusRegion.DiscreteInputs),
|
||||
("C", ModbusRegion.Coils),
|
||||
];
|
||||
|
||||
foreach (var (prefix, mnemonicRegion) in candidates)
|
||||
{
|
||||
if (!text.StartsWith(prefix, StringComparison.OrdinalIgnoreCase)) continue;
|
||||
var rest = text[prefix.Length..];
|
||||
if (rest.Length == 0 || !rest.All(char.IsDigit))
|
||||
{
|
||||
// Prefix matched but body is non-numeric — not a mnemonic address.
|
||||
continue;
|
||||
}
|
||||
if (!int.TryParse(rest, NumberStyles.None, CultureInfo.InvariantCulture, out var n) || n < 1 || n > 65536)
|
||||
{
|
||||
error = $"Mnemonic register number must be 1..65536; got '{rest}'";
|
||||
return false;
|
||||
}
|
||||
region = mnemonicRegion;
|
||||
offset = (ushort)(n - 1);
|
||||
return true;
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
private static bool TryParseType(string text, out ModbusDataType type, out ushort stringLen, out string? error)
|
||||
{
|
||||
type = default;
|
||||
stringLen = 0;
|
||||
error = null;
|
||||
|
||||
// STR<n> — string length glued to the type code.
|
||||
if (text.StartsWith("STR", StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
var lenText = text[3..];
|
||||
if (lenText.Length == 0)
|
||||
{
|
||||
error = "STR type requires a length: STR<n>";
|
||||
return false;
|
||||
}
|
||||
if (!ushort.TryParse(lenText, NumberStyles.None, CultureInfo.InvariantCulture, out var len) || len < 1)
|
||||
{
|
||||
error = $"STR length must be a positive integer; got '{lenText}'";
|
||||
return false;
|
||||
}
|
||||
type = ModbusDataType.String;
|
||||
stringLen = len;
|
||||
return true;
|
||||
}
|
||||
|
||||
type = text.ToUpperInvariant() switch
|
||||
{
|
||||
"BOOL" => ModbusDataType.Bool,
|
||||
"I" => ModbusDataType.Int16,
|
||||
"UI" => ModbusDataType.UInt16,
|
||||
"DI" or "L" => ModbusDataType.Int32,
|
||||
"UDI" or "UL" => ModbusDataType.UInt32,
|
||||
"LI" => ModbusDataType.Int64,
|
||||
"ULI" => ModbusDataType.UInt64,
|
||||
"F" => ModbusDataType.Float32,
|
||||
"D" => ModbusDataType.Float64,
|
||||
"BCD" => ModbusDataType.Bcd16,
|
||||
"LBCD" => ModbusDataType.Bcd32,
|
||||
_ => (ModbusDataType)(-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>";
|
||||
return false;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
private static bool LooksLikeByteOrderToken(string text) =>
|
||||
text.Length == 4 && text.All(char.IsLetter);
|
||||
|
||||
private static bool TryParseByteOrder(string text, out ModbusByteOrder order, out string? error)
|
||||
{
|
||||
order = ModbusByteOrder.BigEndian;
|
||||
error = null;
|
||||
|
||||
order = text.ToUpperInvariant() switch
|
||||
{
|
||||
"ABCD" => ModbusByteOrder.BigEndian,
|
||||
"CDAB" => ModbusByteOrder.WordSwap,
|
||||
"BADC" => ModbusByteOrder.ByteSwap,
|
||||
"DCBA" => ModbusByteOrder.FullReverse,
|
||||
_ => (ModbusByteOrder)(-1),
|
||||
};
|
||||
|
||||
if ((int)order == -1)
|
||||
{
|
||||
error = $"Unknown byte order '{text}'. Valid: ABCD, CDAB, BADC, DCBA";
|
||||
return false;
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Result of parsing a Modbus tag-address string. Maps directly onto the driver-side
|
||||
/// <c>ModbusTagDefinition</c> at config-bind time.
|
||||
/// </summary>
|
||||
/// <param name="Region">Coils / DiscreteInputs / InputRegisters / HoldingRegisters.</param>
|
||||
/// <param name="Offset">Zero-based PDU offset.</param>
|
||||
/// <param name="Bit">When non-null, the tag is a single-bit-in-register selector (0..15).</param>
|
||||
/// <param name="DataType">Inferred from explicit type code or region default.</param>
|
||||
/// <param name="StringLength">Character count for <see cref="ModbusDataType.String"/>; zero otherwise.</param>
|
||||
/// <param name="ByteOrder">Word/byte ordering for multi-register types.</param>
|
||||
/// <param name="ArrayCount">Element count when the tag is an array; null for scalars.</param>
|
||||
public sealed record ParsedModbusAddress(
|
||||
ModbusRegion Region,
|
||||
ushort Offset,
|
||||
byte? Bit,
|
||||
ModbusDataType DataType,
|
||||
ushort StringLength,
|
||||
ModbusByteOrder ByteOrder,
|
||||
int? ArrayCount);
|
||||
@@ -0,0 +1,95 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
|
||||
|
||||
/// <summary>
|
||||
/// The set of value types a Modbus tag can decode to. Each type implies a fixed
|
||||
/// register-count: <see cref="Bool"/> / <see cref="Int16"/> / <see cref="UInt16"/> /
|
||||
/// <see cref="BitInRegister"/> / <see cref="Bcd16"/> = 1 register; <see cref="Int32"/> /
|
||||
/// <see cref="UInt32"/> / <see cref="Float32"/> / <see cref="Bcd32"/> = 2 registers;
|
||||
/// <see cref="Int64"/> / <see cref="UInt64"/> / <see cref="Float64"/> = 4 registers;
|
||||
/// <see cref="String"/> = ceil(StringLength / 2) registers.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Lives in the shared addressing assembly (alongside <see cref="ModbusRegion"/>) so the
|
||||
/// Admin UI and the parser can speak about value types without taking a transport-layer
|
||||
/// dependency on the wire driver.
|
||||
/// </remarks>
|
||||
public enum ModbusDataType
|
||||
{
|
||||
Bool,
|
||||
Int16,
|
||||
UInt16,
|
||||
Int32,
|
||||
UInt32,
|
||||
Int64,
|
||||
UInt64,
|
||||
Float32,
|
||||
Float64,
|
||||
/// <summary>Single bit within a holding register. <c>BitIndex</c> selects 0-15 LSB-first.</summary>
|
||||
BitInRegister,
|
||||
/// <summary>ASCII string packed 2 chars per register, <c>StringLength</c> characters long.</summary>
|
||||
String,
|
||||
/// <summary>
|
||||
/// 16-bit binary-coded decimal. Each nibble encodes one decimal digit (0-9). Register
|
||||
/// value <c>0x1234</c> decodes as decimal <c>1234</c> — NOT binary <c>0x04D2 = 4660</c>.
|
||||
/// DL205/DL260 and several Mitsubishi / Omron families store timers, counters, and
|
||||
/// operator-facing numerics as BCD by default.
|
||||
/// </summary>
|
||||
Bcd16,
|
||||
/// <summary>
|
||||
/// 32-bit (two-register) BCD. Decodes 8 decimal digits. Word ordering follows the tag's
|
||||
/// <see cref="ModbusByteOrder"/> the same way <see cref="Int32"/> does.
|
||||
/// </summary>
|
||||
Bcd32,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Word/byte ordering for multi-register types. The four-letter mnemonic refers to the
|
||||
/// order in which bytes A, B, C, D appear on the wire when decoding a 4-byte value (e.g.
|
||||
/// a Float32) from two consecutive 16-bit registers.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <see cref="BigEndian"/> (<c>ABCD</c>) is the Modbus-spec default: high word at lower
|
||||
/// address, big-endian within each register.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <see cref="WordSwap"/> (<c>CDAB</c>): keeps bytes big-endian within each register
|
||||
/// but swaps the word pair. Common on Siemens S7 over Modbus, Allen-Bradley, several
|
||||
/// Modicon families.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <see cref="ByteSwap"/> (<c>BADC</c>): keeps the word pair in spec order but swaps
|
||||
/// bytes within each register. Encountered on a handful of legacy controllers exposing
|
||||
/// little-endian internals through Modbus.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <see cref="FullReverse"/> (<c>DCBA</c>): full byte reversal — equivalent to reading
|
||||
/// the value as little-endian. Some industrial PCs and gateways that bridge CAN /
|
||||
/// EtherNet/IP into Modbus surface their backplane order this way.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// For 8-byte (Int64 / UInt64 / Float64) values the same A/B/C/D semantics apply
|
||||
/// pairwise across the four registers; the implementation is straight-line.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public enum ModbusByteOrder
|
||||
{
|
||||
BigEndian,
|
||||
WordSwap,
|
||||
ByteSwap,
|
||||
FullReverse,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Per-register byte order for ASCII strings packed 2 chars per register. Standard Modbus
|
||||
/// convention is <see cref="HighByteFirst"/> — the first character of each pair occupies
|
||||
/// the high byte of the register. AutomationDirect DirectLOGIC (DL205, DL260, DL350) and a
|
||||
/// handful of legacy controllers pack <see cref="LowByteFirst"/>, which inverts that within
|
||||
/// each register. Word ordering across multiple registers is always ascending address for
|
||||
/// strings — only the byte order inside each register flips.
|
||||
/// </summary>
|
||||
public enum ModbusStringByteOrder
|
||||
{
|
||||
HighByteFirst,
|
||||
LowByteFirst,
|
||||
}
|
||||
Reference in New Issue
Block a user