Phase 3 PR 45 -- DL205 string byte-order quirk (low-byte-first ASCII packing). Adds ModbusStringByteOrder enum {HighByteFirst, LowByteFirst} + StringByteOrder field on ModbusTagDefinition (default HighByteFirst, the standard Modbus convention). DecodeRegister + EncodeRegister String branches now respect per-tag byte order. Under LowByteFirst each register packs the first char in the low byte instead of the high byte -- the AutomationDirect DirectLOGIC DL205/DL260/DL350 family's headline string quirk. Without the flag the driver decodes 'eHllo' garbage from HR[1040..1042] even though wire bytes are identical. Unit tests: String_LowByteFirst_decodes_DL205_packed_Hello (5 chars across 3 regs with nul pad), String_LowByteFirst_decode_truncates_at_first_nul, String_LowByteFirst_encode_round_trips_with_decode (asserts exact DL205-documented byte sequence {0x65,0x48,0x6C,0x6C,0x00,0x6F} + symmetric encode->decode), String_HighByteFirst_and_LowByteFirst_differ_on_same_wire (control: same wire, different flag => different decode). 56/56 Modbus.Tests pass. Integration test: DL205StringQuirkTests.DL205_string_low_byte_first_decodes_Hello_from_HR1040 against the dl205.json pymodbus profile; reads HR[1040..1042] with both flags on the same tag map and asserts LowByteFirst='Hello' + HighByteFirst!='Hello'. Gated on MODBUS_SIM_PROFILE=dl205 since the standard profile doesn't seed HR[1040..1042]. Verified 2/2 integration tests pass against running pymodbus dl205 simulator. Baseline for PR 46 (BCD decoder), PR 47 (V-memory octal helper), PR 48 (CDAB float order), PR 49 (FC03/FC16 per-device caps) -- each lands its own DL205_<behavior> test class in tests/.../DL205/.

2026-04-18 21:43:32 -04:00
parent 5ee9acb255
commit cd19022d19
4 changed files with 170 additions and 6 deletions
--- a/tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/DL205/DL205StringQuirkTests.cs
+++ b/tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests/DL205/DL205StringQuirkTests.cs
@@ -0,0 +1,81 @@
+using Shouldly;
+using Xunit;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests.DL205;
+
+/// <summary>
+///     Verifies the DL205/DL260 low-byte-first ASCII string packing quirk against the
+///     <c>dl205.json</c> pymodbus profile. Standard Modbus packs the first char of each pair
+///     in the high byte of the register; DirectLOGIC packs it in the low byte instead. Without
+///     <see cref="ModbusStringByteOrder.LowByteFirst"/> the driver decodes "eHllo" garbage
+///     even though the bytes on the wire are identical.
+/// </summary>
+/// <remarks>
+///     <para>
+///         Requires the dl205 profile (<c>Pymodbus\serve.ps1 -Profile dl205</c>). The standard
+///         profile does not seed HR[1040..1042] with string bytes, so running this against the
+///         standard profile returns <c>"\0\0\0\0\0"</c> and the test fails. Skip when the env
+///         var <c>MODBUS_SIM_PROFILE</c> is not set to <c>dl205</c>.
+///     </para>
+/// </remarks>
+[Collection(ModbusSimulatorCollection.Name)]
+[Trait("Category", "Integration")]
+[Trait("Device", "DL205")]
+public sealed class DL205StringQuirkTests(ModbusSimulatorFixture sim)
+{
+    [Fact]
+    public async Task DL205_string_low_byte_first_decodes_Hello_from_HR1040()
+    {
+        if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
+        if (!string.Equals(Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE"), "dl205",
+                StringComparison.OrdinalIgnoreCase))
+        {
+            Assert.Skip("MODBUS_SIM_PROFILE != dl205 — skipping (standard profile does not seed HR[1040..1042]).");
+        }
+
+        var options = new ModbusDriverOptions
+        {
+            Host = sim.Host,
+            Port = sim.Port,
+            UnitId = 1,
+            Timeout = TimeSpan.FromSeconds(2),
+            Tags =
+            [
+                new ModbusTagDefinition(
+                    Name: "DL205_Hello_Low",
+                    Region: ModbusRegion.HoldingRegisters,
+                    Address: 1040,
+                    DataType: ModbusDataType.String,
+                    Writable: false,
+                    StringLength: 5,
+                    StringByteOrder: ModbusStringByteOrder.LowByteFirst),
+                // Control: same address, HighByteFirst, to prove the driver would have decoded
+                // garbage without the quirk flag.
+                new ModbusTagDefinition(
+                    Name: "DL205_Hello_High",
+                    Region: ModbusRegion.HoldingRegisters,
+                    Address: 1040,
+                    DataType: ModbusDataType.String,
+                    Writable: false,
+                    StringLength: 5,
+                    StringByteOrder: ModbusStringByteOrder.HighByteFirst),
+            ],
+            Probe = new ModbusProbeOptions { Enabled = false },
+        };
+        await using var driver = new ModbusDriver(options, driverInstanceId: "dl205-string");
+        await driver.InitializeAsync(driverConfigJson: "{}", TestContext.Current.CancellationToken);
+
+        var results = await driver.ReadAsync(["DL205_Hello_Low", "DL205_Hello_High"],
+            TestContext.Current.CancellationToken);
+
+        results.Count.ShouldBe(2);
+        results[0].StatusCode.ShouldBe(0u);
+        results[0].Value.ShouldBe("Hello", "DL205 low-byte-first ordering must produce 'Hello' from HR[1040..1042]");
+
+        // The high-byte-first read of the same wire bytes should differ — not asserting the
+        // exact garbage string (that would couple the test to the ASCII byte math) but the two
+        // decodes MUST disagree, otherwise the quirk flag is a no-op.
+        results[1].StatusCode.ShouldBe(0u);
+        results[1].Value.ShouldNotBe("Hello");
+    }
+}