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

feat(modbus): wire Family / MelsecSubFamily / DisableFC23, and the form's timing keys

Browse Source 
U1: a tag's addressString (Modicon / mnemonic / DL205 V-memory / MELSEC
D-X-Y grammar) now resolves through ModbusAddressParser with the DRIVER's
Family and MelsecSubFamily at every initialize and is authoritative; the
family-unaware gates (deploy Inspect, AdminUI parse consult) accept what
some family resolves. The tag editor gets an address-text field that
resolves with the owning driver's family and persists both the string and
the resolved region/offset/type fields; a hand edit drops the string.
DisableFC23 now gates FC23: by default a 2..121-register holding write is
one FC23 write + read-back (a unit answering exception 01, or failing FC23 at
the transport, moves to FC16 for the rest of the generation); RTU framing
deframes the FC23 reply. Live-checked: the pymodbus fixture implements FC23.
Also: the AdminUI driver form serialises ModbusDriverOptions (TimeSpan
strings), which the factory DTO never read - every timing field on the form
was dead. The DTO now accepts both shapes (*Ms keys win).

Refs #741
Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
This commit is contained in:
Joseph Doherty
2026-10-22 15:35:58 -04:00
parent 1adc9d65e1
commit 4a3d7a9361
13 changed files with 656 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Contracts/ModbusDriverOptions.cs
+12 -8
View File
@@ -89,10 +89,13 @@ public sealed class ModbusDriverOptions
public bool UseFC16ForSingleRegisterWrites { get; init; } = false;
/// <summary>
/// <b>Reserved / no-op</b> kill-switch for FC23 (Read/Write Multiple Registers). The
/// driver does not currently emit FC23 — toggling this option has no observable effect
/// today. The slot exists so a future block-read-coalescing enhancement that opts into
/// FC23 can be disabled per-deployment without a code change. Default <c>false</c>.
/// Kill-switch for FC23 (Read/Write Multiple Registers). By default a multi-register holding
/// write (2–121 registers: 32/64-bit values, arrays, strings) is sent as ONE FC23 that writes
/// the block and reads the same block back, so the device confirms what it now holds. A unit
/// that answers FC23 with exception 01 (MELSEC QJ71MT91, S7 Modbus servers) is moved to FC16
/// automatically, for that write and every later one; one that fails FC23 at the transport is
/// moved too (that one write is reported as a comms failure). Set <c>true</c> to always use
/// FC16. Default <c>false</c>.
/// </summary>
public bool DisableFC23 { get; init; } = false;
@@ -128,10 +131,11 @@ public sealed class ModbusDriverOptions
public bool DisableReadCoalescing { get; init; } = false;
/// <summary>
/// PLC family hint that drives the parser's family-native branch. When set to a
/// non-Generic value, address strings using that family's native syntax (DL205 V2000 /
/// MELSEC D100) parse to the right region + offset directly. Defaults to
/// <see cref="ModbusFamily.Generic"/> = Modicon-only behaviour preserved by default.
/// PLC family hint that drives the parser's family-native branch. A tag authored with an
/// <c>addressString</c> is resolved with this family at every initialize, so with a non-Generic
/// value that family's native syntax (DL205 V2000 octal / MELSEC D100) parses to the right
/// region + offset. Defaults to <see cref="ModbusFamily.Generic"/> (Modicon / mnemonic grammar).
/// Tags authored by region + numeric address are unaffected.
/// </summary>
public ModbusFamily Family { get; init; } = ModbusFamily.Generic;
src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Contracts/ModbusTagDefinitionFactory.cs
+122 -26
View File
@@ -32,6 +32,24 @@ public static class ModbusTagDefinitionFactory
/// <param name="def">The mapped definition when this returns <see langword="true"/>.</param>
/// <returns><see langword="true"/> when <paramref name="tagConfig"/> is a valid Modbus address object.</returns>
public static bool FromTagConfig(string tagConfig, string rawPath, out ModbusTagDefinition def)
=> FromTagConfig(tagConfig, rawPath, ModbusFamily.Generic, MelsecFamily.Q_L_iQR, out def);
/// <summary>
/// Family-aware overload: an <c>addressString</c> key (the Modicon / mnemonic / family-native grammar
/// of <see cref="ModbusAddressParser"/> — <c>40001:F:CDAB</c>, DL205 <c>V2000</c>, MELSEC <c>D100</c>)
/// is resolved with the DRIVER's <paramref name="family"/> / <paramref name="melsecSubFamily"/> and is
/// authoritative for region, offset, type, bit, string length, byte order and array count; the
/// editor also persists the resolved <c>region</c> / <c>address</c> keys beside it for display and for
/// readers that predate it. Without an <c>addressString</c> this is exactly the 3-argument overload.
/// </summary>
/// <param name="tagConfig">The authored equipment-tag TagConfig JSON.</param>
/// <param name="rawPath">The tag's RawPath — becomes the definition's identity (<c>Name</c>).</param>
/// <param name="family">The driver's PLC family (from its <c>DriverConfig</c>).</param>
/// <param name="melsecSubFamily">The driver's MELSEC sub-family; consulted only for MELSEC.</param>
/// <param name="def">The mapped definition when this returns <see langword="true"/>.</param>
/// <returns><see langword="true"/> when <paramref name="tagConfig"/> is a valid Modbus address object.</returns>
public static bool FromTagConfig(string tagConfig, string rawPath, ModbusFamily family, MelsecFamily melsecSubFamily,
out ModbusTagDefinition def)
{
def = null!;
if (string.IsNullOrWhiteSpace(tagConfig)) return false;
@@ -39,28 +57,60 @@ public static class ModbusTagDefinitionFactory
{
using var doc = JsonDocument.Parse(tagConfig);
var root = doc.RootElement;
if (root.ValueKind != JsonValueKind.Object
|| !root.TryGetProperty("region", out _)
|| !root.TryGetProperty("address", out var addr))
return false;
if (addr.ValueKind != JsonValueKind.Number
|| !addr.TryGetInt32(out var address)
|| address < 0 || address > ushort.MaxValue)
return false;
// Strict enum reads: a present-but-invalid (typo'd) enum rejects the tag
// (→ BadNodeIdUnknown) instead of silently defaulting to a wrong-width Good.
if (!TagConfigJson.TryReadEnumStrict(root, "region", ModbusRegion.HoldingRegisters, out var region)) return false;
// An absent dataType defaults per region: a bit region (Coils / DiscreteInputs) only carries
// Bool, so defaulting it to Int16 would reject every bit tag authored without the key.
if (!TagConfigJson.TryReadEnumStrict(root, "dataType", DefaultDataType(region), out var dataType)) return false;
if (root.ValueKind != JsonValueKind.Object) return false;
ModbusRegion region;
int address;
ModbusDataType dataType;
ModbusByteOrder byteOrder;
byte bitIndex;
ushort stringLength;
int? arrayCount;
var addressText = ReadAddressString(root, out var addressStringInvalid);
if (addressStringInvalid) return false;
if (addressText is not null)
{
if (!ModbusAddressParser.TryParse(addressText, family, melsecSubFamily, out var parsed, out _) || parsed is null)
return false;
region = parsed.Region;
address = parsed.Offset;
dataType = parsed.DataType;
byteOrder = parsed.ByteOrder;
bitIndex = parsed.Bit ?? 0;
stringLength = parsed.StringLength;
arrayCount = parsed.ArrayCount;
}
else
{
if (!root.TryGetProperty("region", out _) || !root.TryGetProperty("address", out var addr))
return false;
if (addr.ValueKind != JsonValueKind.Number
|| !addr.TryGetInt32(out address)
|| address < 0 || address > ushort.MaxValue)
return false;
// Strict enum reads: a present-but-invalid (typo'd) enum rejects the tag
// (→ BadNodeIdUnknown) instead of silently defaulting to a wrong-width Good.
if (!TagConfigJson.TryReadEnumStrict(root, "region", ModbusRegion.HoldingRegisters, out region)) return false;
// An absent dataType defaults per region: a bit region (Coils / DiscreteInputs) only carries
// Bool, so defaulting it to Int16 would reject every bit tag authored without the key.
if (!TagConfigJson.TryReadEnumStrict(root, "dataType", DefaultDataType(region), out dataType)) return false;
if (!TagConfigJson.TryReadEnumStrict(root, "byteOrder", ModbusByteOrder.BigEndian, out byteOrder)) return false;
bitIndex = (byte)ReadInt(root, "bitIndex");
stringLength = (ushort)ReadInt(root, "stringLength");
// isArray / arrayLength — optional keys authored by the typed Modbus tag editor.
// Canonical rule: a tag is an array iff isArray:true AND arrayLength >= 1.
// isArray:false (with any arrayLength) is scalar — the foundation materialises a
// scalar OPC UA node, so returning an array value would cause a shape mismatch.
// A 1-element array (isArray:true, arrayLength:1) IS valid and reads as short[1].
var isArray = ReadBool(root, "isArray");
var arrayLength = ReadInt(root, "arrayLength");
arrayCount = (isArray && arrayLength >= 1) ? arrayLength : null;
}
// Region/type compatibility: a bit region carries only Bool, a register region never Bool.
// A mismatch used to throw out of the coalescing planner (killing every tag's poll) or
// silently return a bool into an Int32 node.
if (!IsRegionTypeCompatible(region, dataType)) return false;
if (!TagConfigJson.TryReadEnumStrict(root, "byteOrder", ModbusByteOrder.BigEndian, out var byteOrder)) return false;
if (!TagConfigJson.TryReadEnumStrict(root, "stringByteOrder", ModbusStringByteOrder.HighByteFirst, out var stringByteOrder)) return false;
var bitIndex = (byte)ReadInt(root, "bitIndex");
var stringLength = (ushort)ReadInt(root, "stringLength");
// Guard: String tags require StringLength >= 1. RegisterCount = (StringLength+1)/2,
// so StringLength=0 → 0 registers → spec-illegal FC03/FC04 with quantity=0 → PLC
// returns exception 03. Reject here so the driver surfaces BadNodeIdUnknown rather
@@ -69,14 +119,6 @@ public static class ModbusTagDefinitionFactory
// Guard: BitInRegister tags require BitIndex 0–15. Shift by ≥ 16 on an int overflows
// a ushort mask silently — reads always return false, writes have no effect.
if (dataType == ModbusDataType.BitInRegister && bitIndex > 15) return false;
// isArray / arrayLength — optional keys authored by the typed Modbus tag editor.
// Canonical rule: a tag is an array iff isArray:true AND arrayLength >= 1.
// isArray:false (with any arrayLength) is scalar — the foundation materialises a
// scalar OPC UA node, so returning an array value would cause a shape mismatch.
// A 1-element array (isArray:true, arrayLength:1) IS valid and reads as short[1].
var isArray = ReadBool(root, "isArray");
var arrayLength = ReadInt(root, "arrayLength");
int? arrayCount = (isArray && arrayLength >= 1) ? arrayLength : null;
// "writable" defaults to true when absent (today's value) — makes read-only equipment tags
// authorable. Node-level authz remains the effective write gate.
var writable = TagConfigJson.ReadWritable(root);
@@ -100,6 +142,42 @@ public static class ModbusTagDefinitionFactory
catch (InvalidOperationException) { return false; }
}
/// <summary>
/// Family-unaware acceptance, for the gates that do not know the owning driver's family (the deploy
/// gate's <see cref="Inspect"/>, CSV import, the AdminUI parse consult): accepts a blob SOME family
/// resolves, so the gate is never stricter than the driver it guards. Blobs without an
/// <c>addressString</c> behave exactly like <see cref="FromTagConfig(string,string,out ModbusTagDefinition)"/>.
/// </summary>
/// <param name="tagConfig">The authored equipment-tag TagConfig JSON.</param>
/// <param name="rawPath">The tag's RawPath.</param>
/// <param name="def">The definition under the first family that resolves it.</param>
/// <returns><see langword="true"/> when any family's driver would serve the tag.</returns>
public static bool FromTagConfigAnyFamily(string tagConfig, string rawPath, out ModbusTagDefinition def)
{
foreach (var (family, sub) in AllFamilies)
if (FromTagConfig(tagConfig, rawPath, family, sub, out def)) return true;
def = null!;
return false;
}
private static readonly (ModbusFamily Family, MelsecFamily Sub)[] AllFamilies =
[
(ModbusFamily.Generic, MelsecFamily.Q_L_iQR),
(ModbusFamily.DL205, MelsecFamily.Q_L_iQR),
(ModbusFamily.MELSEC, MelsecFamily.Q_L_iQR),
(ModbusFamily.MELSEC, MelsecFamily.F_iQF),
];
/// <summary>Reads the optional <c>addressString</c>: null when absent or blank; flags a non-string value.</summary>
private static string? ReadAddressString(JsonElement root, out bool invalid)
{
invalid = false;
if (!root.TryGetProperty("addressString", out var e) || e.ValueKind == JsonValueKind.Null) return null;
if (e.ValueKind != JsonValueKind.String) { invalid = true; return null; }
var text = e.GetString();
return string.IsNullOrWhiteSpace(text) ? null : text.Trim();
}
/// <summary>The data type an authored tag gets when its <c>dataType</c> key is absent.</summary>
/// <param name="region">The tag's region.</param>
/// <returns><c>Bool</c> for Coils / DiscreteInputs, <c>Int16</c> for the register regions.</returns>
@@ -194,7 +272,7 @@ public static class ModbusTagDefinitionFactory
// The accept gate: whatever the driver reads draws nothing. See the remarks. The RAW reference is
// handed to the mapper — the driver reads the stored blob, not a trimmed copy of it.
if (FromTagConfig(reference, InspectionRawPath, out _)) return warnings;
if (FromTagConfigAnyFamily(reference, InspectionRawPath, out _)) return warnings;
try
{
@@ -235,6 +313,24 @@ public static class ModbusTagDefinitionFactory
/// <param name="warnings">The list to append warnings to.</param>
private static void DescribeRejection(JsonElement root, List<string> warnings)
{
var addressText = ReadAddressString(root, out var addressStringInvalid);
if (addressStringInvalid)
{
warnings.Add("Modbus TagConfig 'addressString' is not a string — the tag will not resolve (BadNodeIdUnknown).");
return;
}
if (addressText is not null)
{
// The addressString is authoritative; the other address keys are not read at all.
if (!ModbusAddressParser.TryParse(addressText, out _, out var error))
warnings.Add($"Modbus 'addressString' '{addressText}' does not parse under any PLC family ({error}) — "
+ "the tag will not resolve (BadNodeIdUnknown).");
else
warnings.Add($"Modbus 'addressString' '{addressText}' resolves to an unusable tag (check its type against "
+ "the region) — the tag will not resolve (BadNodeIdUnknown).");
return;
}
if (!root.TryGetProperty("region", out _))
{
warnings.Add(