From 8d3dc321485981b776461e616416008df57f23d7 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 16 Jun 2026 21:51:55 -0400 Subject: [PATCH] feat(modbus): String + BitInRegister array decode + equipment-tag arrayLength MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - DecodeRegisterArray: add String and BitInRegister cases replacing the default:throw; each element decoded by reusing DecodeRegister on its contiguous register slice → string[] / bool[] - ModbusEquipmentTagParser.TryParse: read optional arrayLength key from TagConfig JSON and thread it into ModbusTagDefinition.ArrayCount (null when absent or zero, preserving scalar behaviour) - ModbusArrayTests: 8 new tests covering the two decode cases and the equipment-tag parser/resolver path; 285/285 green --- .../ModbusEquipmentTagParser.cs | 7 +- .../ModbusDriver.cs | 19 ++ .../ModbusArrayTests.cs | 172 ++++++++++++++++++ 3 files changed, 197 insertions(+), 1 deletion(-) diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Contracts/ModbusEquipmentTagParser.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Contracts/ModbusEquipmentTagParser.cs index 8fd480da..a8ef9e5e 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Contracts/ModbusEquipmentTagParser.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Contracts/ModbusEquipmentTagParser.cs @@ -34,9 +34,14 @@ public static class ModbusEquipmentTagParser var byteOrder = ReadEnum(root, "byteOrder", ModbusByteOrder.BigEndian); var bitIndex = (byte)ReadInt(root, "bitIndex"); var stringLength = (ushort)ReadInt(root, "stringLength"); + // isArray / arrayLength — optional keys authored by the typed Modbus tag editor. + // When arrayLength > 0 we expose an array tag of that count; otherwise scalar. + var arrayLength = ReadInt(root, "arrayLength"); + int? arrayCount = arrayLength > 0 ? arrayLength : null; def = new ModbusTagDefinition( Name: reference, Region: region, Address: (ushort)address, DataType: dataType, - Writable: true, ByteOrder: byteOrder, BitIndex: bitIndex, StringLength: stringLength); + Writable: true, ByteOrder: byteOrder, BitIndex: bitIndex, StringLength: stringLength, + ArrayCount: arrayCount); return true; } catch (JsonException) { return false; } diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusDriver.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusDriver.cs index c9163936..d55e3a99 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusDriver.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus/ModbusDriver.cs @@ -479,6 +479,25 @@ public sealed class ModbusDriver arr[i] = (double)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag); return arr; } + case ModbusDataType.String: + { + // Each element occupies elementRegs registers = elementBytes bytes, encoding + // StringLength chars packed high-byte-first or low-byte-first per tag.StringByteOrder. + // DecodeRegister handles the per-element slice identically to the scalar path. + var arr = new string[count]; + for (var i = 0; i < count; i++) + arr[i] = (string)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag); + return arr; + } + case ModbusDataType.BitInRegister: + { + // Each element is 1 holding register (2 bytes). The same BitIndex is applied to + // every element. DecodeRegister returns bool for BitInRegister scalar slices. + var arr = new bool[count]; + for (var i = 0; i < count; i++) + arr[i] = (bool)DecodeRegister(data.AsSpan(i * elementBytes, elementBytes), tag); + return arr; + } default: throw new InvalidOperationException( $"Array decode not supported for {tag.DataType} (use scalar tags or split by element)"); diff --git a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusArrayTests.cs b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusArrayTests.cs index 25e00a65..7fde3cb6 100644 --- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusArrayTests.cs +++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusArrayTests.cs @@ -160,6 +160,178 @@ public sealed class ModbusArrayTests captured[0].ArrayDim.ShouldBeNull(); } + // ---- Gap: String array + BitInRegister array decode ---- + + /// + /// Verifies that a String array (N string elements backed by contiguous register blocks) + /// decodes to a string[]. Each element occupies (StringLength+1)/2 + /// registers packed high-byte-first (standard HighByteFirst order). + /// + [Fact] + public async Task Read_String_Array_Returns_String_Array() + { + // 3-element array of 4-char strings → each element = 2 registers = 4 bytes. + // "AB" → reg0_hi='A'(0x41), reg0_lo='B'(0x42), reg1_hi=0x00, reg1_lo=0x00 + // "CD" → reg2_hi='C'(0x43), reg2_lo='D'(0x44), reg3_hi=0x00, reg3_lo=0x00 + // "EF" → reg4_hi='E'(0x45), reg4_lo='F'(0x46), reg5_hi=0x00, reg5_lo=0x00 + // StringLength=4 means 4 chars max; "AB" uses 2 then nul-terminates at index 2. + var tag = new ModbusTagDefinition("Names", ModbusRegion.HoldingRegisters, 0, + ModbusDataType.String, StringLength: 4, ArrayCount: 3); + var (drv, fake) = NewDriver(tag); + // Element 0: "AB\0\0" → reg0=(0x41<<8|0x42)=0x4142, reg1=0x0000 + fake.HoldingRegisters[0] = 0x4142; // 'A','B' + fake.HoldingRegisters[1] = 0x0000; // nul nul + // Element 1: "CD\0\0" → reg2=0x4344, reg3=0x0000 + fake.HoldingRegisters[2] = 0x4344; // 'C','D' + fake.HoldingRegisters[3] = 0x0000; + // Element 2: "EF\0\0" → reg4=0x4546, reg5=0x0000 + fake.HoldingRegisters[4] = 0x4546; // 'E','F' + fake.HoldingRegisters[5] = 0x0000; + await drv.InitializeAsync("{}", CancellationToken.None); + + var values = await drv.ReadAsync(["Names"], CancellationToken.None); + var arr = values[0].Value.ShouldBeOfType(); + arr.Length.ShouldBe(3); + arr[0].ShouldBe("AB"); + arr[1].ShouldBe("CD"); + arr[2].ShouldBe("EF"); + } + + /// + /// Verifies that a String array with full-length strings (no nul terminator within the + /// element block) decodes correctly. + /// + [Fact] + public async Task Read_String_Array_Full_Length_Elements() + { + // 2-element array of 2-char strings → each element = 1 register = 2 bytes. + // "AB" → reg0=(0x41<<8|0x42), "CD" → reg1=(0x43<<8|0x44) + var tag = new ModbusTagDefinition("Codes", ModbusRegion.HoldingRegisters, 10, + ModbusDataType.String, StringLength: 2, ArrayCount: 2); + var (drv, fake) = NewDriver(tag); + fake.HoldingRegisters[10] = 0x4142; // "AB" + fake.HoldingRegisters[11] = 0x4344; // "CD" + await drv.InitializeAsync("{}", CancellationToken.None); + + var values = await drv.ReadAsync(["Codes"], CancellationToken.None); + var arr = values[0].Value.ShouldBeOfType(); + arr.ShouldBe(new[] { "AB", "CD" }); + } + + /// + /// Verifies that a BitInRegister array (N register-backed bits at the same bit position) + /// decodes to a bool[]. Each element is 1 register; the same BitIndex is applied + /// to each. + /// + [Fact] + public async Task Read_BitInRegister_Array_Returns_Bool_Array() + { + // 4-element BitInRegister array at bit 3 (0-based). + // reg0 = 0x0008 → bit3=1, reg1 = 0x0000 → bit3=0, + // reg2 = 0x000F → bit3=1, reg3 = 0x0001 → bit3=0 + var tag = new ModbusTagDefinition("Bits", ModbusRegion.HoldingRegisters, 5, + ModbusDataType.BitInRegister, BitIndex: 3, ArrayCount: 4); + var (drv, fake) = NewDriver(tag); + fake.HoldingRegisters[5] = 0x0008; // bit3 = 1 + fake.HoldingRegisters[6] = 0x0000; // bit3 = 0 + fake.HoldingRegisters[7] = 0x000F; // bit3 = 1 + fake.HoldingRegisters[8] = 0x0001; // bit3 = 0 + await drv.InitializeAsync("{}", CancellationToken.None); + + var values = await drv.ReadAsync(["Bits"], CancellationToken.None); + var arr = values[0].Value.ShouldBeOfType(); + arr.ShouldBe(new[] { true, false, true, false }); + } + + /// + /// Verifies that a BitInRegister array at bit 0 correctly distinguishes set / clear. + /// + [Fact] + public async Task Read_BitInRegister_Array_Bit0_Returns_Bool_Array() + { + var tag = new ModbusTagDefinition("Lsb", ModbusRegion.HoldingRegisters, 0, + ModbusDataType.BitInRegister, BitIndex: 0, ArrayCount: 3); + var (drv, fake) = NewDriver(tag); + fake.HoldingRegisters[0] = 0x0001; // bit0 = 1 + fake.HoldingRegisters[1] = 0x0002; // bit0 = 0 + fake.HoldingRegisters[2] = 0xFFFF; // bit0 = 1 + await drv.InitializeAsync("{}", CancellationToken.None); + + var values = await drv.ReadAsync(["Lsb"], CancellationToken.None); + var arr = values[0].Value.ShouldBeOfType(); + arr.ShouldBe(new[] { true, false, true }); + } + + // ---- Gap: equipment-tag resolver threads arrayLength → ArrayCount ---- + + /// + /// Verifies that the equipment-tag parser threads arrayLength from the TagConfig + /// JSON blob into ModbusTagDefinition.ArrayCount so that an isArray + /// equipment tag reads the correct number of elements as an array. + /// + [Fact] + public async Task Equipment_Tag_With_ArrayLength_Reads_As_Array() + { + var json = """{"region":"HoldingRegisters","address":20,"dataType":"Int16","byteOrder":"BigEndian","bitIndex":0,"stringLength":0,"isArray":true,"arrayLength":3}"""; + var fake = new ModbusDriverTests.FakeTransport(); + var opts = new ModbusDriverOptions { Host = "fake", Tags = [] }; + var drv = new ModbusDriver(opts, "modbus-eq-arr", _ => fake); + await drv.InitializeAsync("{}", CancellationToken.None); + fake.HoldingRegisters[20] = 100; + fake.HoldingRegisters[21] = 200; + fake.HoldingRegisters[22] = 300; + + var r = await drv.ReadAsync([json], CancellationToken.None); + + r[0].StatusCode.ShouldBe(0u); + var arr = r[0].Value.ShouldBeOfType(); + arr.ShouldBe(new short[] { 100, 200, 300 }); + } + + /// + /// Verifies that an equipment-tag without arrayLength (or arrayLength=0) + /// still reads as a scalar (regression guard). + /// + [Fact] + public async Task Equipment_Tag_Without_ArrayLength_Reads_As_Scalar() + { + var json = """{"region":"HoldingRegisters","address":30,"dataType":"UInt16","byteOrder":"BigEndian","bitIndex":0,"stringLength":0}"""; + var fake = new ModbusDriverTests.FakeTransport(); + var opts = new ModbusDriverOptions { Host = "fake", Tags = [] }; + var drv = new ModbusDriver(opts, "modbus-eq-scalar", _ => fake); + await drv.InitializeAsync("{}", CancellationToken.None); + fake.HoldingRegisters[30] = 1234; + + var r = await drv.ReadAsync([json], CancellationToken.None); + + r[0].StatusCode.ShouldBe(0u); + r[0].Value.ShouldBe((ushort)1234); + } + + /// + /// Verifies that the equipment-tag parser correctly reads the parsed ArrayCount + /// value when arrayLength is present in the JSON blob. + /// + [Fact] + public void Equipment_Tag_Parser_Threads_ArrayLength_Into_ArrayCount() + { + var json = """{"region":"HoldingRegisters","address":0,"dataType":"Int16","byteOrder":"BigEndian","bitIndex":0,"stringLength":0,"isArray":true,"arrayLength":5}"""; + ModbusEquipmentTagParser.TryParse(json, out var def).ShouldBeTrue(); + def!.ArrayCount.ShouldBe(5); + } + + /// + /// Verifies that the equipment-tag parser leaves ArrayCount null when + /// arrayLength is absent or zero. + /// + [Fact] + public void Equipment_Tag_Parser_No_ArrayLength_Leaves_ArrayCount_Null() + { + var json = """{"region":"HoldingRegisters","address":0,"dataType":"Int16","byteOrder":"BigEndian","bitIndex":0,"stringLength":0}"""; + ModbusEquipmentTagParser.TryParse(json, out var def).ShouldBeTrue(); + def!.ArrayCount.ShouldBeNull(); + } + /// Recording address space builder for capturing discovered attributes. /// List to capture discovered attributes into. private sealed class RecordingBuilder(List captured) : IAddressSpaceBuilder