Merge lane Modbus: Modbus driver remediation (#741)

Claude-Session: https://claude.ai/code/session_01Ub9hGmYLQvn9XETzw7CMsT
This commit is contained in:
Joseph Doherty
2026-10-22 16:53:49 -04:00
41 changed files with 4156 additions and 390 deletions
@@ -0,0 +1,162 @@
using System.Diagnostics;
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests;
/// <summary>
/// Comms-loss → recovery against the real pymodbus <c>standard</c> fixture, with a loopback
/// <see cref="TcpRelay"/> in front of it so the device can disappear and come back without touching the
/// shared container. Covers the review 07 High findings P3 (transport self-heal) and H2 (deadband
/// recovery publish).
/// </summary>
[Collection(ModbusSimulatorCollection.Name)]
[Trait("Category", "Integration")]
[Trait("Device", "Standard")]
public sealed class CommsRecoveryTests(ModbusSimulatorFixture sim)
{
private const uint StatusGood = 0u;
private void SkipUnlessStandardLive()
{
if (sim.SkipReason is not null) Assert.Skip(sim.SkipReason);
var profile = Environment.GetEnvironmentVariable("MODBUS_SIM_PROFILE");
if (profile is not null && !string.Equals(profile, "standard", StringComparison.OrdinalIgnoreCase))
Assert.Skip($"MODBUS_SIM_PROFILE={profile} — these tests need the standard profile (HR[0..31] = address).");
}
private ModbusDriverOptions Options(TcpRelay relay, params ModbusTagDefinition[] tags) => new()
{
Host = "127.0.0.1",
Port = relay.Port,
UnitId = 1,
Timeout = TimeSpan.FromSeconds(2),
RawTags = ModbusRawTags.Entries(tags),
Probe = new ModbusProbeOptions { Enabled = false },
};
private static async Task<T> WaitFor<T>(Func<Task<T>> probe, Func<T, bool> done, TimeSpan budget)
{
var sw = Stopwatch.StartNew();
T last;
do
{
last = await probe();
if (done(last)) return last;
await Task.Delay(200, TestContext.Current.CancellationToken);
} while (sw.Elapsed < budget);
return last;
}
/// <summary>
/// P3: after the device drops (two failed calls in a row, socket torn down, reconnect refused) the
/// transport must reconnect ON ITS OWN once the device is back — before this fix every later call
/// failed fast with "Transport not connected" until the 90 s comms-loss watchdog re-initialised the
/// driver.
/// </summary>
[Fact]
public async Task Driver_reads_again_after_the_device_drops_and_returns_without_reinit()
{
SkipUnlessStandardLive();
await using var relay = new TcpRelay(sim.Host, sim.Port);
var tag = new ModbusTagDefinition("HR5", ModbusRegion.HoldingRegisters, 5, ModbusDataType.UInt16, Writable: false);
await using var driver = new ModbusDriver(Options(relay, tag), "modbus-p3");
await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
var good = await driver.ReadAsync(["HR5"], TestContext.Current.CancellationToken);
good[0].StatusCode.ShouldBe(StatusGood);
good[0].Value.ShouldBe((ushort)5);
relay.Cut();
for (var i = 0; i < 2; i++)
{
var bad = await driver.ReadAsync(["HR5"], TestContext.Current.CancellationToken);
bad[0].StatusCode.ShouldNotBe(StatusGood);
}
driver.GetHealth().State.ShouldBe(DriverState.Degraded);
relay.Restore();
var recovered = await WaitFor(
() => driver.ReadAsync(["HR5"], TestContext.Current.CancellationToken),
r => r[0].StatusCode == StatusGood,
TimeSpan.FromSeconds(20));
recovered[0].StatusCode.ShouldBe(StatusGood, "the transport must reconnect by itself once the device is back");
recovered[0].Value.ShouldBe((ushort)5);
driver.GetHealth().State.ShouldBe(DriverState.Healthy);
}
/// <summary>
/// U1 (FC23 opt-in, DisableFC23 kill-switch): a multi-register write on the opted-in FC23 write + read-back path
/// round-trips against the real server — whether it implements FC23 or answers Illegal Function and
/// is moved to FC16 — and so does the default FC16 path. Uses the standard profile's scratch HR[200..209].
/// </summary>
[Theory]
[InlineData(true, 200)]
[InlineData(false, 202)]
public async Task Multi_register_write_round_trips_with_and_without_FC23(bool useFc23, int address)
{
SkipUnlessStandardLive();
var tag = new ModbusTagDefinition("F", ModbusRegion.HoldingRegisters, (ushort)address, ModbusDataType.Float32);
var opts = new ModbusDriverOptions
{
Host = sim.Host, Port = sim.Port, UnitId = 1, Timeout = TimeSpan.FromSeconds(2), UseFC23ForMultiRegisterWrites = useFc23,
RawTags = ModbusRawTags.Entries([tag]), Probe = new ModbusProbeOptions { Enabled = false },
};
await using var driver = new ModbusDriver(opts, "modbus-u1");
await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
var value = useFc23 ? 6.5f : 12.25f;
for (var i = 0; i < 2; i++) // second write exercises the latched path when the server lacks FC23
{
var w = await driver.WriteAsync([new WriteRequest("F", value + i)], TestContext.Current.CancellationToken);
w[0].StatusCode.ShouldBe(StatusGood);
var r = await driver.ReadAsync(["F"], TestContext.Current.CancellationToken);
r[0].Value.ShouldBe(value + i);
}
driver.GetHealth().State.ShouldBe(DriverState.Healthy);
}
/// <summary>
/// H2: a deadbanded tag whose device returns holding the SAME value must publish the Good recovery.
/// HR[5] is a constant 5 in the standard profile, so the recovery value is identical by construction.
/// Positive control: the Bad publish during the outage is observed first.
/// </summary>
[Fact]
public async Task Deadbanded_subscription_publishes_the_Good_recovery_with_an_identical_value()
{
SkipUnlessStandardLive();
await using var relay = new TcpRelay(sim.Host, sim.Port);
var tag = new ModbusTagDefinition("HR5", ModbusRegion.HoldingRegisters, 5, ModbusDataType.UInt16,
Writable: false, Deadband: 10.0);
await using var driver = new ModbusDriver(Options(relay, tag), "modbus-h2");
await driver.InitializeAsync("{}", TestContext.Current.CancellationToken);
var published = new System.Collections.Concurrent.ConcurrentQueue<DataValueSnapshot>();
driver.OnDataChange += (_, e) => published.Enqueue(e.Snapshot);
var handle = await driver.SubscribeAsync(["HR5"], TimeSpan.FromMilliseconds(200), TestContext.Current.CancellationToken);
try
{
(await WaitFor(() => Task.FromResult(published.ToArray()),
p => p.Any(s => s.StatusCode == StatusGood), TimeSpan.FromSeconds(10)))
.ShouldContain(s => s.StatusCode == StatusGood, "initial Good publish");
relay.Cut();
(await WaitFor(() => Task.FromResult(published.ToArray()),
p => p.Any(s => s.StatusCode != StatusGood), TimeSpan.FromSeconds(20)))
.ShouldContain(s => s.StatusCode != StatusGood, "the outage must publish Bad (positive control)");
var badCount = published.Count;
relay.Restore();
var after = await WaitFor(() => Task.FromResult(published.Skip(badCount).ToArray()),
p => p.Any(s => s.StatusCode == StatusGood), TimeSpan.FromSeconds(30));
var recovery = after.FirstOrDefault(s => s.StatusCode == StatusGood);
recovery.ShouldNotBeNull("the Good recovery with the same value must not be swallowed by the deadband");
recovery.Value.ShouldBe((ushort)5);
}
finally
{
await driver.UnsubscribeAsync(handle, TestContext.Current.CancellationToken);
}
}
}
@@ -0,0 +1,101 @@
using System.Net;
using System.Net.Sockets;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.IntegrationTests;
/// <summary>
/// Loopback TCP relay in front of the real Modbus fixture, so a test can make the device "disappear"
/// (<see cref="Cut"/>: every relayed connection is closed and new connects are refused) and "come back"
/// (<see cref="Restore"/>: listen again on the SAME port) without touching the shared container.
/// </summary>
internal sealed class TcpRelay : IAsyncDisposable
{
private readonly string _upstreamHost;
private readonly int _upstreamPort;
private readonly object _lock = new();
private readonly List<TcpClient> _live = [];
private TcpListener? _listener;
private CancellationTokenSource _stop = new();
private int _accepted;
public TcpRelay(string upstreamHost, int upstreamPort)
{
_upstreamHost = upstreamHost;
_upstreamPort = upstreamPort;
var probe = new TcpListener(IPAddress.Loopback, 0);
probe.Start();
Port = ((IPEndPoint)probe.LocalEndpoint).Port;
probe.Stop();
Restore();
}
/// <summary>Gets the loopback port clients dial.</summary>
public int Port { get; }
/// <summary>Gets the number of client connections the relay has accepted.</summary>
public int AcceptedConnections => Volatile.Read(ref _accepted);
/// <summary>Starts (or resumes) relaying on <see cref="Port"/>.</summary>
public void Restore()
{
_stop = new CancellationTokenSource();
var listener = new TcpListener(IPAddress.Loopback, Port);
listener.Server.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.ReuseAddress, true);
listener.Start();
_listener = listener;
var token = _stop.Token;
_ = Task.Run(() => AcceptLoopAsync(listener, token));
}
/// <summary>Closes every relayed connection and refuses new ones until <see cref="Restore"/>.</summary>
public void Cut()
{
try { _stop.Cancel(); } catch { }
try { _listener?.Stop(); } catch { }
_listener = null;
lock (_lock)
{
foreach (var c in _live) { try { c.Close(); } catch { } }
_live.Clear();
}
}
private async Task AcceptLoopAsync(TcpListener listener, CancellationToken token)
{
while (!token.IsCancellationRequested)
{
TcpClient downstream;
try { downstream = await listener.AcceptTcpClientAsync(token); }
catch { return; }
Interlocked.Increment(ref _accepted);
_ = Task.Run(() => RelayAsync(downstream, token));
}
}
private async Task RelayAsync(TcpClient downstream, CancellationToken token)
{
var upstream = new TcpClient(AddressFamily.InterNetwork);
lock (_lock) { _live.Add(downstream); _live.Add(upstream); }
try
{
var addr = (await Dns.GetHostAddressesAsync(_upstreamHost, token))
.First(a => a.AddressFamily == AddressFamily.InterNetwork);
await upstream.ConnectAsync(addr, _upstreamPort, token);
var a = downstream.GetStream();
var b = upstream.GetStream();
await Task.WhenAny(a.CopyToAsync(b, token), b.CopyToAsync(a, token));
}
catch { /* cut or upstream gone */ }
finally
{
try { downstream.Close(); } catch { }
try { upstream.Close(); } catch { }
}
}
public ValueTask DisposeAsync()
{
Cut();
return ValueTask.CompletedTask;
}
}
@@ -25,10 +25,41 @@ public sealed class ModbusArrayWriteSupportParityTests
return data;
}
/// <summary>
/// Shapes where the driver has moved ahead of the server-side table (review 07 P6 / U3, Modbus lane) and
/// <see cref="DriverArrayWriteSupport"/> — owned outside the Modbus lane — has not followed yet
/// (follow-up F1): the tag factory now REFUSES a Coils tag with a non-Bool type (so the driver serves no
/// such tag), and the driver now encodes String[] and BitInRegister[] holding-register writes.
/// <see cref="Pending_F1_divergences_still_exist"/> fails the moment the table follows, so this list
/// is removed with it rather than left to rot.
/// </summary>
private static bool PendingF1(ModbusRegion region, ModbusDataType dataType) =>
(region == ModbusRegion.Coils && dataType != ModbusDataType.Bool)
|| (region == ModbusRegion.HoldingRegisters && dataType is ModbusDataType.String or ModbusDataType.BitInRegister);
public static TheoryData<ModbusRegion, ModbusDataType> PendingShapes()
{
var data = new TheoryData<ModbusRegion, ModbusDataType>();
foreach (var (region, dt) in Shapes().Where(s => PendingF1(s.Region, s.DataType))) data.Add(region, dt);
return data;
}
[Theory]
[MemberData(nameof(PendingShapes))]
public void Pending_F1_divergences_still_exist(ModbusRegion region, ModbusDataType dataType)
{
var json = $$"""{"region":"{{region}}","address":10,"dataType":"{{dataType}}","stringLength":4,"isArray":true,"arrayLength":2}""";
var driverAccepts = region == ModbusRegion.HoldingRegisters; // String[] / BitInRegister[] encode; mistyped Coils are refused
DriverArrayWriteSupport.Supports(DriverTypeNames.Modbus, "Int16", json).ShouldNotBe(driverAccepts,
"F1 landed — DriverArrayWriteSupport now agrees with the driver for this shape; delete it from PendingF1");
}
[Theory]
[MemberData(nameof(AllShapes))]
public async Task Table_agrees_with_the_driver_write_path(ModbusRegion region, ModbusDataType dataType)
{
if (PendingF1(region, dataType)) return; // covered by Pending_F1_divergences_still_exist
var json = $$"""{"region":"{{region}}","address":10,"dataType":"{{dataType}}","stringLength":4,"isArray":true,"arrayLength":2}""";
var fake = new ModbusDriverTests.FakeTransport();
var drv = new ModbusDriver(
@@ -0,0 +1,181 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// Review 07 U2: block-read coalescing is ON by default (gap 8), and it covers coils, discrete inputs,
/// <c>BitInRegister</c> and <c>String</c> tags — 16 bit tags on one status word used to cost 16 reads of
/// the same register, and 64 adjacent coils 64 FC01s.
/// </summary>
[Trait("Category", "Unit")]
public sealed class ModbusCoalescingDefaultsTests
{
private static async Task<(ModbusDriver, ScriptedTransport)> StartAsync(ModbusDriverOptions opts)
{
var t = new ScriptedTransport();
var d = new ModbusDriver(opts, "m1", _ => t);
await d.InitializeAsync("{}", TestContext.Current.CancellationToken);
return (d, t);
}
private static ModbusDriverOptions Opts(IEnumerable<ModbusTagDefinition> tags, bool disable = false) => new()
{
Host = "f", RawTags = ModbusRawTags.Entries(tags), DisableReadCoalescing = disable,
Probe = new ModbusProbeOptions { Enabled = false },
};
[Fact]
public void Default_options_coalesce_with_a_gap_of_8()
{
new ModbusDriverOptions().MaxReadGap.ShouldBe((ushort)8);
new ModbusDriverOptions().DisableReadCoalescing.ShouldBeFalse();
ModbusDriverFactoryExtensions.ParseOptions("m1", """{"host":"h"}""").MaxReadGap.ShouldBe((ushort)8);
}
[Fact]
public async Task Default_configured_holding_registers_are_read_in_one_PDU()
{
var tags = Enumerable.Range(0, 10).Select(i =>
new ModbusTagDefinition($"HR{i}", ModbusRegion.HoldingRegisters, (ushort)(100 + i * 3), ModbusDataType.Int16)).ToArray();
var (drv, t) = await StartAsync(Opts(tags));
await using var _ = drv;
for (var i = 0; i < 10; i++) t.Bank.HoldingRegisters[100 + i * 3] = (ushort)(i + 1);
var r = await drv.ReadAsync([.. tags.Select(x => x.Name)], TestContext.Current.CancellationToken);
t.Requests(0x03).Count.ShouldBe(1);
r.Select(s => (short)s.Value!).ShouldBe(Enumerable.Range(1, 10).Select(i => (short)i));
}
/// <summary>
/// Fix round 1 (coordinator ruling 2): an explicitly authored maxReadGap 0 — what the pre-#741 form
/// persisted on every driver — keeps its old meaning, NO coalescing; the gap-8 default applies only to an
/// absent key (positive control).
/// </summary>
[Theory]
[InlineData("""{"host":"h","maxReadGap":0,"disableFC23":false}""", 2)]
[InlineData("""{"host":"h"}""", 1)]
public async Task A_persisted_maxReadGap_0_keeps_coalescing_off(string legacyConfig, int expectedReads)
{
var parsed = ModbusDriverFactoryExtensions.ParseOptions("m1", legacyConfig);
var tags = new[]
{
new ModbusTagDefinition("A", ModbusRegion.HoldingRegisters, 100, ModbusDataType.Int16),
new ModbusTagDefinition("B", ModbusRegion.HoldingRegisters, 101, ModbusDataType.Int16),
};
var (drv, t) = await StartAsync(new ModbusDriverOptions
{
Host = "f", MaxReadGap = parsed.MaxReadGap, DisableReadCoalescing = parsed.DisableReadCoalescing,
RawTags = ModbusRawTags.Entries(tags), Probe = new ModbusProbeOptions { Enabled = false },
});
await using var _ = drv;
await drv.ReadAsync(["A", "B"], TestContext.Current.CancellationToken);
t.Requests(0x03).Count.ShouldBe(expectedReads);
}
[Fact]
public async Task DisableReadCoalescing_reads_every_tag_alone()
{
// Positive control for the default-on test: the off switch really is per-tag.
var tags = new[]
{
new ModbusTagDefinition("A", ModbusRegion.HoldingRegisters, 100, ModbusDataType.Int16),
new ModbusTagDefinition("B", ModbusRegion.HoldingRegisters, 101, ModbusDataType.Int16),
};
var (drv, t) = await StartAsync(Opts(tags, disable: true));
await using var _ = drv;
await drv.ReadAsync(["A", "B"], TestContext.Current.CancellationToken);
t.Requests(0x03).Count.ShouldBe(2);
}
[Theory]
[InlineData(ModbusRegion.Coils, (byte)0x01)]
[InlineData(ModbusRegion.DiscreteInputs, (byte)0x02)]
public async Task Adjacent_bit_tags_fold_into_one_bit_read(ModbusRegion region, byte fc)
{
var tags = Enumerable.Range(0, 64).Select(i =>
new ModbusTagDefinition($"B{i}", region, (ushort)(10 + i), ModbusDataType.Bool)).ToArray();
var (drv, t) = await StartAsync(Opts(tags));
await using var _ = drv;
var bank = region == ModbusRegion.Coils ? t.Bank.Coils : t.Bank.DiscreteInputs;
for (var i = 0; i < 64; i++) bank[10 + i] = i % 3 == 0;
var r = await drv.ReadAsync([.. tags.Select(x => x.Name)], TestContext.Current.CancellationToken);
t.Requests(fc).ShouldBe([(fc, (ushort)10, (ushort)64)]);
for (var i = 0; i < 64; i++) r[i].Value.ShouldBe(i % 3 == 0, $"bit {i}");
}
[Fact]
public async Task Bit_tags_on_one_status_word_fold_into_one_register_read()
{
var tags = Enumerable.Range(0, 16).Select(b =>
new ModbusTagDefinition($"S{b}", ModbusRegion.HoldingRegisters, 40, ModbusDataType.BitInRegister, BitIndex: (byte)b)).ToArray();
var (drv, t) = await StartAsync(Opts(tags));
await using var _ = drv;
t.Bank.HoldingRegisters[40] = 0b1010_0000_0000_0101;
var r = await drv.ReadAsync([.. tags.Select(x => x.Name)], TestContext.Current.CancellationToken);
t.Requests(0x03).ShouldBe([((byte)0x03, (ushort)40, (ushort)1)]);
for (var b = 0; b < 16; b++) r[b].Value.ShouldBe(((0b1010_0000_0000_0101 >> b) & 1) == 1, $"bit {b}");
}
[Fact]
public async Task A_string_tag_coalesces_with_its_neighbours()
{
var tags = new[]
{
new ModbusTagDefinition("Num", ModbusRegion.HoldingRegisters, 50, ModbusDataType.Int16),
new ModbusTagDefinition("Str", ModbusRegion.HoldingRegisters, 51, ModbusDataType.String, StringLength: 4),
new ModbusTagDefinition("After", ModbusRegion.HoldingRegisters, 53, ModbusDataType.UInt16),
};
var (drv, t) = await StartAsync(Opts(tags));
await using var _ = drv;
t.Bank.HoldingRegisters[50] = 7;
t.Bank.HoldingRegisters[51] = ('A' << 8) | 'B';
t.Bank.HoldingRegisters[52] = ('C' << 8) | 'D';
t.Bank.HoldingRegisters[53] = 9;
var r = await drv.ReadAsync(["Num", "Str", "After"], TestContext.Current.CancellationToken);
t.Requests(0x03).ShouldBe([((byte)0x03, (ushort)50, (ushort)4)]);
r[0].Value.ShouldBe((short)7);
r[1].Value.ShouldBe("ABCD");
r[2].Value.ShouldBe((ushort)9);
}
[Fact]
public async Task A_refused_coil_range_is_prohibited_and_reprobed_with_FC01()
{
var tags = Enumerable.Range(0, 4).Select(i =>
new ModbusTagDefinition($"C{i}", ModbusRegion.Coils, (ushort)(20 + i), ModbusDataType.Bool)).ToArray();
var opts = new ModbusDriverOptions
{
Host = "f", RawTags = ModbusRawTags.Entries(tags), Probe = new ModbusProbeOptions { Enabled = false },
AutoProhibitReprobeInterval = TimeSpan.FromHours(1),
};
var (drv, t) = await StartAsync(opts);
await using var _ = drv;
var refuseMerged = true;
t.Handler = (_, pdu, _) =>
{
var qty = (pdu[3] << 8) | pdu[4];
return pdu[0] == 0x01 && qty > 1 && refuseMerged
? Task.FromException<byte[]>(new ModbusException(0x01, 0x02, "protected"))
: null;
};
var r = await drv.ReadAsync([.. tags.Select(x => x.Name)], TestContext.Current.CancellationToken);
r.ShouldAllBe(s => s.StatusCode == 0u, "the per-tag fallback still reads every coil");
drv.AutoProhibitedRangeCount.ShouldBe(1);
refuseMerged = false;
while (t.Sent.TryDequeue(out var _1)) { }
await drv.RunReprobeOnceForTestAsync(TestContext.Current.CancellationToken);
t.Sent.ShouldAllBe(s => s.Pdu[0] == 0x01, "a coil range is re-probed with FC01, never a register read");
drv.AutoProhibitedRangeCount.ShouldBe(0);
}
}
@@ -42,9 +42,9 @@ public sealed class ModbusCoalescingTests
public ValueTask DisposeAsync() => ValueTask.CompletedTask;
}
/// <summary>Verifies that MaxReadGap=0 defaults to per-tag reads without coalescing.</summary>
/// <summary>MaxReadGap=0 means no coalescing (its historical meaning, kept for persisted configs).</summary>
[Fact]
public async Task MaxReadGap_Zero_Defaults_To_Per_Tag_Reads()
public async Task MaxReadGap_Zero_Means_No_Coalescing()
{
var fake = new CountingTransport();
var t1 = new ModbusTagDefinition("T1", ModbusRegion.HoldingRegisters, 100, ModbusDataType.Int16);
@@ -56,7 +56,7 @@ public sealed class ModbusCoalescingTests
await drv.ReadAsync(["T1", "T2"], CancellationToken.None);
// With coalescing off, expect 2 separate FC03 reads.
// MaxReadGap=0 is coalescing OFF: expect 2 separate FC03 reads.
var fc03Reads = fake.Reads.Where(r => r.Fc == 0x03).ToList();
fc03Reads.Count.ShouldBe(2);
}
@@ -0,0 +1,53 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// Review 07 H2: the deadband baseline is keyed on (value, status). A Good-after-Bad recovery carrying
/// the IDENTICAL value must publish — the value-only dedup left the node Bad until the value drifted.
/// </summary>
[Trait("Category", "Unit")]
public sealed class ModbusDeadbandRecoveryTests
{
private const uint Good = 0u;
private const uint Uncertain = 0x40000000u;
private const uint BadComm = 0x80050000u;
private static async Task<ModbusDriver> NewDriverAsync()
{
var tag = new ModbusTagDefinition("Temp", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16, Deadband: 5.0);
var opts = new ModbusDriverOptions
{
Host = "f", RawTags = ModbusRawTags.Entries([tag]), Probe = new ModbusProbeOptions { Enabled = false },
};
var drv = new ModbusDriver(opts, "m1", _ => new ModbusDriverTests.FakeTransport());
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
return drv;
}
private static DataValueSnapshot Snap(object? v, uint status) => new(v, status, DateTime.UtcNow, DateTime.UtcNow);
[Fact]
public async Task Good_after_Bad_with_the_same_value_publishes()
{
await using var drv = await NewDriverAsync();
drv.ShouldPublish("Temp", Snap((short)10, Good)).ShouldBeTrue(); // baseline
drv.ShouldPublish("Temp", Snap(null, BadComm)).ShouldBeTrue(); // comms drop
drv.ShouldPublish("Temp", Snap((short)10, Good)).ShouldBeTrue("the recovery publish must not be swallowed");
// Positive control: the deadband is still active after the recovery re-seeded the baseline.
drv.ShouldPublish("Temp", Snap((short)11, Good)).ShouldBeFalse();
drv.ShouldPublish("Temp", Snap((short)16, Good)).ShouldBeTrue();
}
[Fact]
public async Task A_status_change_with_the_same_value_publishes()
{
await using var drv = await NewDriverAsync();
drv.ShouldPublish("Temp", Snap((short)10, Good)).ShouldBeTrue();
drv.ShouldPublish("Temp", Snap((short)10, Uncertain)).ShouldBeTrue("a quality change must publish");
drv.ShouldPublish("Temp", Snap((short)12, Uncertain)).ShouldBeFalse("within deadband at the same quality");
drv.ShouldPublish("Temp", Snap((short)10, Good)).ShouldBeTrue("back to Good must publish");
}
}
@@ -46,6 +46,7 @@ public sealed class ModbusDriverTests
0x06 => Task.FromResult(WriteSingleReg(pdu)),
0x0F => Task.FromResult(WriteMultipleCoils(pdu)),
0x10 => Task.FromResult(WriteMultipleRegs(pdu)),
0x17 => Task.FromResult(ReadWriteMultipleRegs(pdu)),
_ => Task.FromException<byte[]>(new ModbusException(fc, 0x01, $"fc={fc} not supported by fake")),
};
}
@@ -102,6 +103,26 @@ public sealed class ModbusDriverTests
return new byte[] { 0x10, pdu[1], pdu[2], pdu[3], pdu[4] };
}
// FC23 Read/Write Multiple Registers: write first, then read back the read range.
private byte[] ReadWriteMultipleRegs(byte[] pdu)
{
var readAddr = (ushort)((pdu[1] << 8) | pdu[2]);
var readQty = (ushort)((pdu[3] << 8) | pdu[4]);
var writeAddr = (ushort)((pdu[5] << 8) | pdu[6]);
var writeQty = (ushort)((pdu[7] << 8) | pdu[8]);
for (var i = 0; i < writeQty; i++)
HoldingRegisters[writeAddr + i] = (ushort)((pdu[10 + i * 2] << 8) | pdu[11 + i * 2]);
var resp = new byte[2 + readQty * 2];
resp[0] = 0x17;
resp[1] = (byte)(readQty * 2);
for (var i = 0; i < readQty; i++)
{
resp[2 + i * 2] = (byte)(HoldingRegisters[readAddr + i] >> 8);
resp[3 + i * 2] = (byte)(HoldingRegisters[readAddr + i] & 0xFF);
}
return resp;
}
private byte[] WriteMultipleCoils(byte[] pdu)
{
var addr = (ushort)((pdu[1] << 8) | pdu[2]);
@@ -0,0 +1,252 @@
using System.Text.Json;
using System.Text.Json.Serialization;
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// Review 07 U1: <c>Family</c>, <c>MelsecSubFamily</c> and <c>DisableFC23</c> were authored in the
/// AdminUI and consumed by nothing. A tag's <c>addressString</c> now resolves through
/// <see cref="ModbusAddressParser"/> with the driver's family; <c>DisableFC23</c> gates the FC23
/// write-and-read-back path for multi-register writes. Also pins that the AdminUI form's own
/// (TimeSpan-shaped) config keys reach the driver.
/// </summary>
[Trait("Category", "Unit")]
public sealed class ModbusFamilyWiringTests
{
// ---------------- addressString through the family-aware parser ----------------
[Fact]
public void A_MELSEC_D_register_resolves_only_under_the_MELSEC_family()
{
const string json = """{"addressString":"D100"}""";
ModbusTagDefinitionFactory.FromTagConfig(json, "T", ModbusFamily.MELSEC, MelsecFamily.Q_L_iQR, out var def).ShouldBeTrue();
def.Region.ShouldBe(ModbusRegion.HoldingRegisters);
def.Address.ShouldBe((ushort)100);
// Positive control: the same text means nothing to a Generic (Modicon) driver.
ModbusTagDefinitionFactory.FromTagConfig(json, "T", ModbusFamily.Generic, MelsecFamily.Q_L_iQR, out _).ShouldBeFalse();
}
[Fact]
public void A_DL205_V_memory_address_resolves_octal_under_DL205()
{
ModbusTagDefinitionFactory.FromTagConfig("""{"addressString":"V2000"}""", "T", ModbusFamily.DL205, MelsecFamily.Q_L_iQR, out var def)
.ShouldBeTrue();
def.Region.ShouldBe(ModbusRegion.HoldingRegisters);
def.Address.ShouldBe((ushort)0x400); // V2000 octal = 1024
}
[Fact]
public void A_string_only_blob_carries_type_order_and_count_and_keeps_the_other_keys()
{
ModbusTagDefinitionFactory.FromTagConfig(
"""{"addressString":"40011:F:CDAB:4","writable":false,"unitId":3}""",
"T", ModbusFamily.Generic, MelsecFamily.Q_L_iQR, out var def).ShouldBeTrue();
def.Region.ShouldBe(ModbusRegion.HoldingRegisters);
def.Address.ShouldBe((ushort)10);
def.DataType.ShouldBe(ModbusDataType.Float32);
def.ByteOrder.ShouldBe(ModbusByteOrder.WordSwap);
def.ArrayCount.ShouldBe(4);
def.Writable.ShouldBeFalse();
def.UnitId.ShouldBe((byte)3);
}
/// <summary>
/// Fix round 1 (review m2): persisted region/address are authoritative over an addressString, so a
/// later Family / MelsecSubFamily change can never silently remap a live tag the editor resolved. (Since
/// fix round 3 the keys win by PRESENCE; the marker in this blob is display state only.)
/// </summary>
[Fact]
public void Persisted_resolved_keys_win_over_the_address_string_so_a_family_change_cannot_remap()
{
// The editor resolved D100 under MELSEC, persisted HR 100 and MARKED it; the driver is later switched.
const string json = """{"addressString":"D100","addressResolved":true,"region":"HoldingRegisters","address":100,"dataType":"Int16"}""";
foreach (var family in new[] { ModbusFamily.MELSEC, ModbusFamily.DL205, ModbusFamily.Generic })
{
ModbusTagDefinitionFactory.FromTagConfig(json, "T", family, MelsecFamily.Q_L_iQR, out var def).ShouldBeTrue();
def.Address.ShouldBe((ushort)100, $"family {family}");
}
}
/// <summary>
/// Fix round 3 (review r2 N2): the persisted-shape matrix. Every shape that carries region + address loads
/// from them under every family — including the pre-#741 "keys + addressString, no marker" row, which the
/// old driver served from its keys and must keep serving so. Only a string-only blob (no keys) resolves
/// the string.
/// </summary>
[Theory]
[InlineData("keys only", """{"region":"InputRegisters","address":5}""", ModbusRegion.InputRegisters, 5)]
[InlineData("pre-lane keys + string", """{"region":"InputRegisters","address":5,"dataType":"Int16","addressString":"40011:F"}""", ModbusRegion.InputRegisters, 5)]
[InlineData("pre-lane stamped HR/0 + string", """{"region":"HoldingRegisters","address":0,"dataType":"Int16","addressString":"D100"}""", ModbusRegion.HoldingRegisters, 0)]
[InlineData("string only", """{"addressString":"40011:F"}""", ModbusRegion.HoldingRegisters, 10)]
[InlineData("string + marker + keys (editor-pinned)", """{"addressString":"D100","addressResolved":true,"region":"HoldingRegisters","address":100}""", ModbusRegion.HoldingRegisters, 100)]
[InlineData("string + marker, no keys", """{"addressString":"40011:F","addressResolved":true}""", ModbusRegion.HoldingRegisters, 10)]
public void Every_persisted_shape_resolves_to_its_address_under_every_family(
string shape, string json, ModbusRegion region, int address)
{
foreach (var (family, sub) in new[]
{
(ModbusFamily.Generic, MelsecFamily.Q_L_iQR), (ModbusFamily.DL205, MelsecFamily.Q_L_iQR),
(ModbusFamily.MELSEC, MelsecFamily.Q_L_iQR), (ModbusFamily.MELSEC, MelsecFamily.F_iQF),
})
{
ModbusTagDefinitionFactory.FromTagConfig(json, "T", family, sub, out var def).ShouldBeTrue($"{shape} / {family}");
def.Region.ShouldBe(region, $"{shape} / {family}");
def.Address.ShouldBe((ushort)address, $"{shape} / {family}");
}
}
[Fact]
public void A_string_only_blob_no_family_parses_is_refused_not_served_as_HR0()
{
ModbusTagDefinitionFactory.FromTagConfig("""{"addressString":"D100"}""", "T", ModbusFamily.Generic, MelsecFamily.Q_L_iQR, out _)
.ShouldBeFalse();
}
[Fact]
public void An_unparseable_address_string_rejects_the_tag_and_the_deploy_gate_says_why()
{
const string json = """{"addressString":"ZZ9"}""";
ModbusTagDefinitionFactory.FromTagConfig(json, "T", out _).ShouldBeFalse();
ModbusTagDefinitionFactory.Inspect(json).ShouldContain(w => w.Contains("addressString"));
// The family-unaware gate accepts what SOME family resolves (it must never be stricter than the driver).
ModbusTagDefinitionFactory.Inspect("""{"addressString":"D100"}""").ShouldBeEmpty();
}
[Fact]
public async Task The_driver_resolves_address_strings_with_its_configured_family()
{
var fake = new ScriptedTransport();
fake.Bank.HoldingRegisters[100] = 1234;
var opts = new ModbusDriverOptions
{
Host = "f", Family = ModbusFamily.MELSEC, Probe = new ModbusProbeOptions { Enabled = false },
RawTags = [new RawTagEntry("D100", """{"addressString":"D100"}""", false)],
};
await using var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
var r = await drv.ReadAsync(["D100"], TestContext.Current.CancellationToken);
r[0].StatusCode.ShouldBe(0u);
r[0].Value.ShouldBe((short)1234);
}
[Fact]
public void Family_and_MelsecSubFamily_parse_from_the_driver_config()
{
var o = ModbusDriverFactoryExtensions.ParseOptions("m1",
"""{"host":"h","family":"MELSEC","melsecSubFamily":"F_iQF","disableFC23":true,"useFC23ForMultiRegisterWrites":true}""");
o.Family.ShouldBe(ModbusFamily.MELSEC);
o.MelsecSubFamily.ShouldBe(MelsecFamily.F_iQF);
o.DisableFC23.ShouldBeTrue();
o.UseFC23ForMultiRegisterWrites.ShouldBeTrue();
}
// ---------------- FC23 is OPT-IN; DisableFC23 is the kill-switch ----------------
private static async Task<(ModbusDriver, ScriptedTransport)> StartWriteAsync(string driverConfigJson)
{
var t = new ScriptedTransport();
var opts = ModbusDriverFactoryExtensions.ParseOptions("m1", driverConfigJson) is var parsed
? new ModbusDriverOptions
{
Host = "f", DisableFC23 = parsed.DisableFC23,
UseFC23ForMultiRegisterWrites = parsed.UseFC23ForMultiRegisterWrites,
Probe = new ModbusProbeOptions { Enabled = false },
RawTags = ModbusRawTags.Entries([new ModbusTagDefinition("F", ModbusRegion.HoldingRegisters, 20, ModbusDataType.Float32)]),
}
: null!;
var drv = new ModbusDriver(opts, "m1", _ => t);
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
return (drv, t);
}
/// <summary>
/// Fix round 1 (coordinator ruling 1): a config without the opt-in key keeps the FC16 wire — including the
/// legacy shape every form-saved config carries ("disableFC23": false).
/// </summary>
[Theory]
[InlineData("""{"host":"h"}""")]
[InlineData("""{"host":"h","disableFC23":false,"maxReadGap":0,"useFC15ForSingleCoilWrites":false}""")]
public async Task Without_the_opt_in_multi_register_writes_stay_on_FC16(string legacyConfig)
{
var (drv, t) = await StartWriteAsync(legacyConfig);
await using var _ = drv;
(await drv.WriteAsync([new WriteRequest("F", 1.5f)], TestContext.Current.CancellationToken))[0].StatusCode.ShouldBe(0u);
t.Sent.Select(s => s.Pdu[0]).ShouldBe([(byte)0x10]);
}
[Fact]
public async Task Opted_in_multi_register_writes_use_FC23_write_and_read_back()
{
var (drv, t) = await StartWriteAsync("""{"host":"h","useFC23ForMultiRegisterWrites":true}""");
await using var _ = drv;
var w = await drv.WriteAsync([new WriteRequest("F", 1.5f)], TestContext.Current.CancellationToken);
w[0].StatusCode.ShouldBe(0u);
t.Sent.Select(s => s.Pdu[0]).ShouldBe([(byte)0x17]);
(await drv.ReadAsync(["F"], TestContext.Current.CancellationToken))[0].Value.ShouldBe(1.5f);
}
[Fact]
public async Task DisableFC23_overrides_the_opt_in()
{
var (drv, t) = await StartWriteAsync("""{"host":"h","useFC23ForMultiRegisterWrites":true,"disableFC23":true}""");
await using var _ = drv;
(await drv.WriteAsync([new WriteRequest("F", 1.5f)], TestContext.Current.CancellationToken))[0].StatusCode.ShouldBe(0u);
t.Sent.Select(s => s.Pdu[0]).ShouldBe([(byte)0x10]);
}
[Fact]
public async Task An_opted_in_device_without_FC23_falls_back_to_FC16_once_and_stays_on_it()
{
var (drv, t) = await StartWriteAsync("""{"host":"h","useFC23ForMultiRegisterWrites":true}""");
await using var _ = drv;
t.Handler = (_, pdu, _) => pdu[0] == 0x17
? Task.FromException<byte[]>(new ModbusException(0x17, 0x01, "illegal function"))
: null;
(await drv.WriteAsync([new WriteRequest("F", 1.5f)], TestContext.Current.CancellationToken))[0].StatusCode.ShouldBe(0u);
(await drv.WriteAsync([new WriteRequest("F", 2.5f)], TestContext.Current.CancellationToken))[0].StatusCode.ShouldBe(0u);
t.Sent.Select(s => s.Pdu[0]).ShouldBe([(byte)0x17, (byte)0x10, (byte)0x10]);
drv.GetHealth().State.ShouldBe(DriverState.Healthy);
}
// ---------------- the AdminUI form's own keys reach the driver ----------------
[Fact]
public void The_AdminUI_form_shape_of_the_timing_keys_is_honoured()
{
// The form serialises ModbusDriverOptions itself (camelCase, TimeSpan strings), not the *Ms DTO keys.
var formShape = JsonSerializer.Serialize(new ModbusDriverOptions
{
Host = "h",
Timeout = TimeSpan.FromSeconds(7),
IdleDisconnectTimeout = TimeSpan.FromSeconds(90),
AutoProhibitReprobeInterval = TimeSpan.FromSeconds(45),
Probe = new ModbusProbeOptions { Interval = TimeSpan.FromSeconds(11), Timeout = TimeSpan.FromSeconds(3) },
KeepAlive = new ModbusKeepAliveOptions { Time = TimeSpan.FromSeconds(60), Interval = TimeSpan.FromSeconds(20) },
Reconnect = new ModbusReconnectOptions { InitialDelay = TimeSpan.FromSeconds(2), MaxDelay = TimeSpan.FromSeconds(40) },
}, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase, Converters = { new JsonStringEnumConverter() } });
var o = ModbusDriverFactoryExtensions.ParseOptions("m1", formShape);
o.Timeout.ShouldBe(TimeSpan.FromSeconds(7));
o.IdleDisconnectTimeout.ShouldBe(TimeSpan.FromSeconds(90));
o.AutoProhibitReprobeInterval.ShouldBe(TimeSpan.FromSeconds(45));
o.Probe.Interval.ShouldBe(TimeSpan.FromSeconds(11));
o.Probe.Timeout.ShouldBe(TimeSpan.FromSeconds(3));
o.KeepAlive.Time.ShouldBe(TimeSpan.FromSeconds(60));
o.KeepAlive.Interval.ShouldBe(TimeSpan.FromSeconds(20));
o.Reconnect.InitialDelay.ShouldBe(TimeSpan.FromSeconds(2));
o.Reconnect.MaxDelay.ShouldBe(TimeSpan.FromSeconds(40));
}
[Fact]
public void The_millisecond_keys_still_win_when_both_are_present()
{
var o = ModbusDriverFactoryExtensions.ParseOptions("m1", """{"host":"h","timeoutMs":1500,"timeout":"00:00:07"}""");
o.Timeout.ShouldBe(TimeSpan.FromMilliseconds(1500));
}
}
@@ -0,0 +1,402 @@
using System.Text.Json;
using Microsoft.Extensions.Logging;
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// The driver health contract (review 07 H4 + H7, and the lifecycle/fail-fast rules every driver lane
/// must meet): a device REFUSAL is per-tag Bad with no Degraded and proves the device answered; a comms
/// fault degrades and preserves LastSuccessfulRead; health is one write per batch; a comms timeout on
/// one unit fails the rest of that unit's batch fast; writes map transport failures to
/// BadCommunicationError and value problems to BadOutOfRange / BadTypeMismatch.
/// </summary>
[Trait("Category", "Unit")]
public sealed class ModbusHealthContractTests
{
private const uint Good = 0u;
private const uint BadOutOfRange = 0x803C0000u;
private const uint BadDeviceFailure = 0x808B0000u;
private const uint BadCommunicationError = 0x80050000u;
private const uint BadTypeMismatch = 0x80740000u;
private const uint BadNodeIdUnknown = 0x80340000u;
private static ModbusDriverOptions Opts(params ModbusTagDefinition[] tags) => new()
{
Host = "f", RawTags = ModbusRawTags.Entries(tags), Probe = new ModbusProbeOptions { Enabled = false },
};
private static ModbusTagDefinition Hr(string name, ushort addr, byte? unit = null, ModbusDataType type = ModbusDataType.Int16) =>
new(name, ModbusRegion.HoldingRegisters, addr, type, UnitId: unit);
private static Task<byte[]> Refuse(byte code, byte[] pdu) =>
Task.FromException<byte[]>(new ModbusException(pdu[0], code, $"exception {code}"));
private static ushort Addr(byte[] pdu) => (ushort)((pdu[1] << 8) | pdu[2]);
private static async Task<(ModbusDriver Driver, ScriptedTransport Transport)> StartAsync(
ModbusDriverOptions opts, ILogger<ModbusDriver>? logger = null)
{
var t = new ScriptedTransport();
var d = new ModbusDriver(opts, "m1", _ => t, logger);
await d.InitializeAsync("{}", TestContext.Current.CancellationToken);
return (d, t);
}
// ---------------- H4: refusals ----------------
[Fact]
public async Task All_tags_refused_keeps_Healthy_and_advances_LastSuccessfulRead()
{
var (drv, t) = await StartAsync(Opts(Hr("A", 10), Hr("B", 11)));
await using var _ = drv;
t.Handler = (_, pdu, _) => Refuse(0x02, pdu);
var before = drv.GetHealth().LastSuccessfulRead;
var r = await drv.ReadAsync(["A", "B"], TestContext.Current.CancellationToken);
r.ShouldAllBe(s => s.StatusCode == BadOutOfRange);
var h = drv.GetHealth();
h.State.ShouldBe(DriverState.Healthy, "a refusal means the device answered — no Degraded, no watchdog fodder");
h.LastSuccessfulRead.ShouldNotBeNull();
h.LastSuccessfulRead!.Value.ShouldBeGreaterThanOrEqualTo(before!.Value);
}
[Fact]
public async Task A_refusal_after_a_comms_fault_restores_Healthy()
{
var (drv, t) = await StartAsync(Opts(Hr("A", 10)));
await using var _ = drv;
t.Handler = (_, _, _) => Task.FromException<byte[]>(new IOException("socket dropped"));
await drv.ReadAsync(["A"], TestContext.Current.CancellationToken);
var degraded = drv.GetHealth();
degraded.State.ShouldBe(DriverState.Degraded);
t.Handler = (_, pdu, _) => Refuse(0x02, pdu);
await drv.ReadAsync(["A"], TestContext.Current.CancellationToken);
var h = drv.GetHealth();
h.State.ShouldBe(DriverState.Healthy);
h.LastSuccessfulRead!.Value.ShouldBeGreaterThanOrEqualTo(degraded.LastSuccessfulRead!.Value);
}
[Theory]
[InlineData(0x04)]
[InlineData(0x0B)]
public async Task Non_refusal_exception_codes_still_degrade(byte code)
{
// Positive control for the refusal tests: a server-failure / gateway code is NOT a refusal.
var (drv, t) = await StartAsync(Opts(Hr("A", 10)));
await using var _ = drv;
t.Handler = (_, pdu, _) => Refuse(code, pdu);
await drv.ReadAsync(["A"], TestContext.Current.CancellationToken);
drv.GetHealth().State.ShouldBe(DriverState.Degraded);
}
[Theory]
[InlineData(false)]
[InlineData(true)]
public async Task Mixed_refused_and_good_batch_is_Healthy_regardless_of_tag_order(bool refusedFirst)
{
var (drv, t) = await StartAsync(Opts(Hr("Refused", 10), Hr("Fine", 50)));
await using var _ = drv;
t.Handler = (_, pdu, _) => Addr(pdu) == 10 ? Refuse(0x02, pdu) : null;
string[] refs = refusedFirst ? ["Refused", "Fine"] : ["Fine", "Refused"];
var r = await drv.ReadAsync(refs, TestContext.Current.CancellationToken);
r.Count(s => s.StatusCode == Good).ShouldBe(1);
drv.GetHealth().State.ShouldBe(DriverState.Healthy);
}
[Fact]
public async Task A_refused_tag_warns_once_not_once_per_poll()
{
var logger = new ListLogger();
var (drv, t) = await StartAsync(Opts(Hr("A", 10)), logger);
await using var _ = drv;
t.Handler = (_, pdu, _) => Refuse(0x02, pdu);
for (var i = 0; i < 3; i++) await drv.ReadAsync(["A"], TestContext.Current.CancellationToken);
logger.Warnings.Count(m => m.Contains("refused") && m.Contains("A")).ShouldBe(1);
}
// ---------------- fail fast per unit / endpoint ----------------
[Fact]
public async Task A_comms_timeout_on_one_unit_fails_the_rest_of_that_units_batch_fast()
{
var (drv, t) = await StartAsync(Opts(Hr("U2a", 10, 2), Hr("U2b", 11, 2), Hr("U2c", 12, 2), Hr("U1", 13, 1)));
await using var _ = drv;
t.Bank.HoldingRegisters[13] = 42;
t.Handler = (unit, _, _) => unit == 2
? Task.FromException<byte[]>(new ModbusTransportDesyncException(
ModbusTransportDesyncException.DesyncReason.Timeout, "timeout"))
: null;
var r = await drv.ReadAsync(["U2a", "U2b", "U2c", "U1"], TestContext.Current.CancellationToken);
t.SendsTo(2).ShouldBe(1, "one timeout per unit per batch, not one per tag");
r.Take(3).ShouldAllBe(s => s.StatusCode == BadCommunicationError);
// Positive control: the healthy unit in the same batch is still read.
r[3].StatusCode.ShouldBe(Good);
r[3].Value.ShouldBe((short)42);
drv.GetHealth().State.ShouldBe(DriverState.Degraded);
}
[Fact]
public async Task An_unreachable_endpoint_fails_the_whole_batch_fast()
{
var (drv, t) = await StartAsync(Opts(Hr("A", 10, 1), Hr("B", 11, 2), Hr("C", 12, 3)));
await using var _ = drv;
t.Handler = (_, _, _) => Task.FromException<byte[]>(new ModbusTransportUnavailableException("throttled"));
var r = await drv.ReadAsync(["A", "B", "C"], TestContext.Current.CancellationToken);
t.TotalSends.ShouldBe(1);
r.ShouldAllBe(s => s.StatusCode == BadCommunicationError);
}
// ---------------- H7: write status mapping + write-side health ----------------
[Fact]
public async Task Write_transport_failure_is_BadCommunicationError_and_a_good_read_clears_it()
{
// Fix round 1 (review Important #3): ONE health writer for reads and writes. A single write blip used
// to latch Degraded until the next good WRITE — forever, in a read-mostly plant.
var (drv, t) = await StartAsync(Opts(Hr("A", 10)));
await using var _ = drv;
t.Handler = (_, pdu, _) => pdu[0] == 0x06 ? Task.FromException<byte[]>(new IOException("dropped")) : null;
var w = await drv.WriteAsync([new WriteRequest("A", (short)1)], TestContext.Current.CancellationToken);
w[0].StatusCode.ShouldBe(BadCommunicationError);
drv.GetHealth().State.ShouldBe(DriverState.Degraded);
(await drv.ReadAsync(["A"], TestContext.Current.CancellationToken))[0].StatusCode.ShouldBe(Good);
drv.GetHealth().State.ShouldBe(DriverState.Healthy, "a good read proves the shared transport answered");
}
[Fact]
public async Task A_good_write_clears_a_read_side_comms_fault()
{
var (drv, t) = await StartAsync(Opts(Hr("A", 10)));
await using var _ = drv;
t.Handler = (_, pdu, _) => pdu[0] == 0x03 ? Task.FromException<byte[]>(new IOException("dropped")) : null;
await drv.ReadAsync(["A"], TestContext.Current.CancellationToken);
drv.GetHealth().State.ShouldBe(DriverState.Degraded);
(await drv.WriteAsync([new WriteRequest("A", (short)2)], TestContext.Current.CancellationToken))[0].StatusCode.ShouldBe(Good);
drv.GetHealth().State.ShouldBe(DriverState.Healthy);
}
[Fact]
public async Task A_malformed_reply_does_not_fail_the_rest_of_the_unit_fast()
{
// Review m3: a byte-count mismatch is a reply that ARRIVED — only a timeout / desync / IO fails the unit fast.
var (drv, t) = await StartAsync(Opts(Hr("Bad", 10), Hr("Fine", 50)) is var o
? new ModbusDriverOptions { Host = o.Host, RawTags = o.RawTags, Probe = o.Probe, DisableReadCoalescing = true }
: null!);
await using var _ = drv;
t.Bank.HoldingRegisters[50] = 9;
t.Handler = (_, pdu, _) => Addr(pdu) == 10 ? Task.FromResult(new byte[] { 0x03, 0x04, 0, 0 }) : null;
var r = await drv.ReadAsync(["Bad", "Fine"], TestContext.Current.CancellationToken);
r[0].StatusCode.ShouldBe(BadCommunicationError);
r[1].Value.ShouldBe((short)9, "the sibling on the same unit is still read");
}
[Fact]
public async Task DisposeAsync_leaves_health_Unknown()
{
// Review m1: Dispose bumps the generation (dropping a concurrent shutdown's write), so it must write its own.
var (drv, _) = await StartAsync(Opts(Hr("A", 10)));
drv.GetHealth().State.ShouldBe(DriverState.Healthy);
await drv.DisposeAsync();
drv.GetHealth().State.ShouldBe(DriverState.Unknown);
}
[Fact]
public async Task A_write_refusal_counts_as_answered_and_clears_a_write_side_fault()
{
var (drv, t) = await StartAsync(Opts(Hr("A", 10)));
await using var _ = drv;
t.Handler = (_, pdu, _) => pdu[0] == 0x06 ? Task.FromException<byte[]>(new IOException("dropped")) : null;
await drv.WriteAsync([new WriteRequest("A", (short)1)], TestContext.Current.CancellationToken);
drv.GetHealth().State.ShouldBe(DriverState.Degraded);
t.Handler = (_, pdu, _) => pdu[0] == 0x06 ? Refuse(0x03, pdu) : null;
var w = await drv.WriteAsync([new WriteRequest("A", (short)1)], TestContext.Current.CancellationToken);
w[0].StatusCode.ShouldBe(BadOutOfRange);
drv.GetHealth().State.ShouldBe(DriverState.Healthy);
}
[Fact]
public async Task Write_value_problems_map_to_OutOfRange_and_TypeMismatch_without_touching_health()
{
var arr = new ModbusTagDefinition("Arr", ModbusRegion.HoldingRegisters, 20, ModbusDataType.Int16, ArrayCount: 3);
var (drv, t) = await StartAsync(Opts(Hr("Bcd", 10, type: ModbusDataType.Bcd16), Hr("I16", 11), arr));
await using var _ = drv;
var w = await drv.WriteAsync([
new WriteRequest("Bcd", 12345), // > 4 BCD digits
new WriteRequest("I16", 70000), // > Int16
new WriteRequest("I16", "not a number"),
new WriteRequest("Arr", new short[] { 1, 2 }), // length mismatch
new WriteRequest("Arr", new int[] { 1, 2, 3 }), // CLR list of another element type converts (ScadaBridge shape)
], TestContext.Current.CancellationToken);
w[0].StatusCode.ShouldBe(BadOutOfRange);
w[1].StatusCode.ShouldBe(BadOutOfRange);
w[2].StatusCode.ShouldBe(BadTypeMismatch);
w[3].StatusCode.ShouldBe(BadOutOfRange);
w[4].StatusCode.ShouldBe(Good);
t.Bank.HoldingRegisters[22].ShouldBe((ushort)3);
drv.GetHealth().State.ShouldBe(DriverState.Healthy);
}
[Fact]
public async Task A_failed_read_invalidates_the_WriteOnChangeOnly_cache()
{
// Value-only suppression is the write-side twin of the #527 dedup trap: after a comms fault the
// device's register is unknown (it may have rebooted), so re-asserting the same setpoint must reach it.
var opts = new ModbusDriverOptions
{
Host = "f", RawTags = ModbusRawTags.Entries([Hr("A", 10)]), WriteOnChangeOnly = true,
Probe = new ModbusProbeOptions { Enabled = false },
};
var (drv, t) = await StartAsync(opts);
await using var _ = drv;
int Fc06() => t.Sent.Count(s => s.Pdu[0] == 0x06);
await drv.WriteAsync([new WriteRequest("A", (short)5)], TestContext.Current.CancellationToken);
await drv.WriteAsync([new WriteRequest("A", (short)5)], TestContext.Current.CancellationToken);
Fc06().ShouldBe(1, "positive control: an identical re-write is suppressed while nothing failed");
t.Handler = (_, pdu, _) => pdu[0] == 0x03 ? Task.FromException<byte[]>(new IOException("dropped")) : null;
await drv.ReadAsync(["A"], TestContext.Current.CancellationToken);
t.Handler = null;
await drv.WriteAsync([new WriteRequest("A", (short)5)], TestContext.Current.CancellationToken);
Fc06().ShouldBe(2, "after a failed read the device value is unknown; the write must go to the wire");
}
// ---------------- lifecycle generation ----------------
[Fact]
public async Task A_superseded_initialize_never_publishes_over_the_shutdown_that_overtook_it()
{
var t = new ScriptedTransport { ConnectGate = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously) };
var drv = new ModbusDriver(Opts(Hr("A", 10)), "m1", _ => t) { LifecycleGateTimeout = TimeSpan.FromSeconds(1) };
var init = drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
await t.ConnectEntered.Task.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
// The init is wedged in its connect; shutdown waits out the gate timeout and tears down anyway.
await drv.ShutdownAsync(TestContext.Current.CancellationToken);
drv.GetHealth().State.ShouldBe(DriverState.Unknown);
t.ConnectGate.SetResult(); // the abandoned connect finally completes
await Should.ThrowAsync<OperationCanceledException>(() => init);
drv.GetHealth().State.ShouldBe(DriverState.Unknown, "the superseded init must not publish Healthy");
t.DisposeCount.ShouldBe(1, "the superseded init releases the transport it built");
await Should.ThrowAsync<InvalidOperationException>(() => drv.ReadAsync(["A"], TestContext.Current.CancellationToken));
}
[Fact]
public async Task A_read_that_straddles_a_reinitialize_does_not_write_health_about_the_new_transport()
{
var first = new ScriptedTransport();
var second = new ScriptedTransport();
var release = new TaskCompletionSource<byte[]>(TaskCreationOptions.RunContinuationsAsynchronously);
var entered = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
first.Handler = (_, _, _) => { entered.TrySetResult(); return release.Task; };
var calls = 0;
var drv = new ModbusDriver(Opts(Hr("A", 10)), "m1", _ => Interlocked.Increment(ref calls) == 1 ? first : second);
await using var _ = drv;
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
var read = drv.ReadAsync(["A"], TestContext.Current.CancellationToken);
await entered.Task.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken); // re-init onto `second`
drv.GetHealth().State.ShouldBe(DriverState.Healthy);
release.SetException(new IOException("old socket died")); // the straddling read now fails
(await read)[0].StatusCode.ShouldBe(BadCommunicationError);
drv.GetHealth().State.ShouldBe(DriverState.Healthy, "a read on the superseded transport must not degrade the new one");
// Positive control: a failure on the CURRENT transport still degrades.
second.Handler = (_, _, _) => Task.FromException<byte[]>(new IOException("new socket died"));
await drv.ReadAsync(["A"], TestContext.Current.CancellationToken);
drv.GetHealth().State.ShouldBe(DriverState.Degraded);
}
[Fact]
public async Task Reinitialize_with_a_new_tag_set_drops_tags_the_new_config_no_longer_has()
{
var t = new ScriptedTransport();
var drv = new ModbusDriver(Opts(Hr("Old", 10)), "m1", _ => t);
await using var _ = drv;
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
(await drv.ReadAsync(["Old"], TestContext.Current.CancellationToken))[0].StatusCode.ShouldBe(Good);
var config = JsonSerializer.Serialize(new
{
host = "f",
probe = new { enabled = false },
rawTags = ModbusRawTags.Entries([Hr("New", 11)]),
});
await drv.InitializeAsync(config, TestContext.Current.CancellationToken);
var r = await drv.ReadAsync(["Old", "New"], TestContext.Current.CancellationToken);
r[0].StatusCode.ShouldBe(BadNodeIdUnknown, "a re-init publishes a fresh table, it does not merge into the old one");
r[1].StatusCode.ShouldBe(Good);
}
// ---------------- complete teardown ----------------
[Fact]
public async Task Shutdown_joins_the_probe_loop_so_no_host_transition_fires_after_it_returns()
{
var t = new ScriptedTransport();
var probeBlocked = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
var probes = 0;
t.Handler = async (_, pdu, ct) =>
{
if (Interlocked.Increment(ref probes) == 1) return await t.Bank.SendAsync(1, pdu, ct); // first probe: Running
probeBlocked.TrySetResult();
try { await Task.Delay(Timeout.Infinite, ct); }
catch (OperationCanceledException) { }
throw new ObjectDisposedException("transport"); // a teardown-time failure, NOT an OCE
};
var opts = new ModbusDriverOptions
{
Host = "f", RawTags = ModbusRawTags.Entries([Hr("A", 10)]),
Probe = new ModbusProbeOptions { Enabled = true, Interval = TimeSpan.FromMilliseconds(50), Timeout = TimeSpan.FromSeconds(30) },
};
var drv = new ModbusDriver(opts, "m1", _ => t);
var running = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
var afterShutdown = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
var shutdownReturned = false;
drv.OnHostStatusChanged += (_, e) =>
{
if (e.NewState == HostState.Running) running.TrySetResult();
if (Volatile.Read(ref shutdownReturned)) afterShutdown.TrySetResult();
};
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
await running.Task.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken); // positive control
await probeBlocked.Task.WaitAsync(TimeSpan.FromSeconds(5), TestContext.Current.CancellationToken);
await drv.ShutdownAsync(TestContext.Current.CancellationToken);
Volatile.Write(ref shutdownReturned, true);
await Should.ThrowAsync<TimeoutException>(
() => afterShutdown.Task.WaitAsync(TimeSpan.FromSeconds(1), TestContext.Current.CancellationToken));
}
private sealed class ListLogger : ILogger<ModbusDriver>
{
public System.Collections.Concurrent.ConcurrentQueue<string> Messages { get; } = new();
public IEnumerable<string> Warnings => Messages.Where(m => m.StartsWith("Warning:", StringComparison.Ordinal));
public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
public bool IsEnabled(LogLevel logLevel) => true;
public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
=> Messages.Enqueue($"{logLevel}: {formatter(state, exception)}");
}
}
@@ -92,7 +92,7 @@ public sealed class ModbusLoggerInjectionTests
// Scan 1 — coalesced read fails. Expect exactly one warning.
await drv.ReadAsync(["T100", "T102", "T104"], CancellationToken.None);
var warnings = logger.Entries.Where(e => e.Level == LogLevel.Warning).ToList();
var warnings = logger.Entries.Where(e => e.Level == LogLevel.Warning && e.Message.Contains("auto-prohibited")).ToList();
warnings.Count.ShouldBe(1);
warnings[0].Message.ShouldContain("drv-logged");
warnings[0].Message.ShouldContain("Start=100");
@@ -102,7 +102,13 @@ public sealed class ModbusLoggerInjectionTests
// the prohibition and skips the merge; even if it didn't, the de-dupe in
// RecordAutoProhibition would suppress).
await drv.ReadAsync(["T100", "T102", "T104"], CancellationToken.None);
logger.Entries.Count(e => e.Level == LogLevel.Warning).ShouldBe(1, "re-fire of same range stays silent");
logger.Entries.Count(e => e.Level == LogLevel.Warning && e.Message.Contains("auto-prohibited"))
.ShouldBe(1, "re-fire of same range stays silent");
// The protected register's per-tag fallback is a device refusal: one Warning for that tag across
// both scans (once-per-tag), and none for its readable neighbours.
var refusals = logger.Entries.Where(e => e.Level == LogLevel.Warning && e.Message.Contains("refused")).ToList();
refusals.Count.ShouldBe(1);
refusals[0].Message.ShouldContain("T102");
await drv.ShutdownAsync(CancellationToken.None);
}
@@ -0,0 +1,103 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// Review 07 P6: region/type compatibility is enforced at the tag factory (and so at the deploy gate
/// and the AdminUI parse consult). A <c>HoldingRegisters</c> + <c>Bool</c> tag used to throw out of the
/// coalescing planner and kill the whole subscription's poll cycle; <c>Coils</c> + <c>Int16</c> silently
/// returned a bool into an Int32 node.
/// </summary>
[Trait("Category", "Unit")]
public sealed class ModbusRegionTypeValidationTests
{
[Theory]
[InlineData("""{"region":"HoldingRegisters","address":1,"dataType":"Bool"}""")]
[InlineData("""{"region":"InputRegisters","address":1,"dataType":"Bool"}""")]
public void A_register_region_with_Bool_is_rejected(string json)
{
// That pair never read (RegisterCount threw), so refusing it breaks nothing that worked.
ModbusTagDefinitionFactory.FromTagConfig(json, "T", out _).ShouldBeFalse();
ModbusTagDefinitionFactory.Inspect(json).ShouldContain(w => w.Contains("register"));
}
/// <summary>
/// Fix round 1 (review Important #2): the pre-#741 editor defaulted dataType to Int16 and persisted it for
/// coil / DI tags, and the old driver ignored it for bit regions — those tags worked and must keep loading.
/// A bit region with any type is coerced to Bool and draws no deploy warning (a warning can be promoted to
/// a blocking error by TagConfigValidationMode.Error, which would refuse an existing config).
/// </summary>
[Theory]
[InlineData("""{"region":"Coils","address":3,"dataType":"Int16","byteOrder":"BigEndian","bitIndex":0,"stringLength":0}""")]
[InlineData("""{"region":"DiscreteInputs","address":1,"dataType":"Float32"}""")]
public void A_legacy_bit_region_tag_with_a_register_type_still_loads_as_Bool(string legacyJson)
{
ModbusTagDefinitionFactory.FromTagConfig(legacyJson, "T", out var def).ShouldBeTrue();
def.DataType.ShouldBe(ModbusDataType.Bool);
ModbusTagDefinitionFactory.Inspect(legacyJson).ShouldBeEmpty();
}
[Fact]
public async Task A_legacy_Int16_coil_tag_reads_and_writes_the_coil()
{
var fake = new ModbusDriverTests.FakeTransport();
fake.Coils[3] = true;
var opts = new ModbusDriverOptions
{
Host = "f", Probe = new ModbusProbeOptions { Enabled = false },
RawTags = [new RawTagEntry("Run", """{"region":"Coils","address":3,"dataType":"Int16","byteOrder":"BigEndian","bitIndex":0,"stringLength":0}""", false)],
};
await using var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
(await drv.ReadAsync(["Run"], TestContext.Current.CancellationToken))[0].Value.ShouldBe(true);
(await drv.WriteAsync([new WriteRequest("Run", false)], TestContext.Current.CancellationToken))[0].StatusCode.ShouldBe(0u);
fake.Coils[3].ShouldBeFalse();
}
[Theory]
[InlineData("""{"region":"Coils","address":1,"dataType":"Bool"}""", ModbusDataType.Bool)]
[InlineData("""{"region":"Coils","address":1}""", ModbusDataType.Bool)]
[InlineData("""{"region":"DiscreteInputs","address":1}""", ModbusDataType.Bool)]
[InlineData("""{"region":"InputRegisters","address":1,"dataType":"BitInRegister","bitIndex":3}""", ModbusDataType.BitInRegister)]
[InlineData("""{"region":"HoldingRegisters","address":1}""", ModbusDataType.Int16)]
public void Compatible_region_and_type_is_accepted(string json, ModbusDataType expected)
{
// Positive control for the rejection theory, including the absent-dataType default per region.
ModbusTagDefinitionFactory.FromTagConfig(json, "T", out var def).ShouldBeTrue();
def.DataType.ShouldBe(expected);
ModbusTagDefinitionFactory.Inspect(json).ShouldBeEmpty();
}
[Fact]
public async Task A_mis_typed_tag_no_longer_kills_the_coalesced_poll_of_its_neighbours()
{
var fake = new ModbusDriverTests.FakeTransport();
fake.HoldingRegisters[100] = 7;
fake.HoldingRegisters[102] = 9;
var good1 = new ModbusTagDefinition("G1", ModbusRegion.HoldingRegisters, 100, ModbusDataType.Int16);
var good2 = new ModbusTagDefinition("G2", ModbusRegion.HoldingRegisters, 102, ModbusDataType.Int16);
var opts = new ModbusDriverOptions
{
Host = "f",
MaxReadGap = 5,
RawTags =
[
ModbusRawTags.Entry(good1),
new RawTagEntry("Bad", """{"region":"HoldingRegisters","address":101,"dataType":"Bool"}""", false),
ModbusRawTags.Entry(good2),
],
Probe = new ModbusProbeOptions { Enabled = false },
};
await using var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", TestContext.Current.CancellationToken);
var r = await drv.ReadAsync(["G1", "Bad", "G2"], TestContext.Current.CancellationToken);
r[0].Value.ShouldBe((short)7);
r[1].StatusCode.ShouldBe(0x80340000u); // BadNodeIdUnknown — skipped at init, reported
r[2].Value.ShouldBe((short)9);
drv.GetSkippedTags()!.Sample.ShouldContain(s => s.RawPath == "Bad");
}
}
@@ -25,6 +25,17 @@ public sealed class ModbusRtuFramingTests
pdu.ShouldBe(new byte[] { 0x03, 0x02, 0x00, 0x0A }); // fc + byteCount + data, no addr/CRC
}
/// <summary>FC23 (Read/Write Multiple) replies like a read: byte count + data. It used to be sized as a
/// fixed 4-byte write echo and desync.</summary>
[Fact]
public async Task ReadResponse_FC23_returns_bare_pdu()
{
var body = new byte[] { 0x01, 0x17, 0x04, 0x00, 0x0A, 0x00, 0x0B };
await using var s = Canned(ModbusCrc.Append(body));
var pdu = await ModbusRtuFraming.ReadResponsePduAsync(s, 0x01, TestContext.Current.CancellationToken);
pdu.ShouldBe(new byte[] { 0x17, 0x04, 0x00, 0x0A, 0x00, 0x0B });
}
[Fact]
public async Task ReadResponse_exception_frame_throws_ModbusException()
{
@@ -0,0 +1,82 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// Review 07 U3: <c>String[]</c> and <c>BitInRegister[]</c> tags read fine; their writes used to fail
/// <c>BadInternalError</c> (no element width for String, <c>Convert.ToBoolean(bool[])</c> for the bit
/// array). Both now encode <c>count</c> elements at the tag's element width; a length mismatch is
/// <c>BadOutOfRange</c>.
/// </summary>
[Trait("Category", "Unit")]
public sealed class ModbusStringAndBitArrayWriteTests
{
private static async Task<(ModbusDriver, ScriptedTransport)> StartAsync(params ModbusTagDefinition[] tags)
{
var t = new ScriptedTransport();
var d = new ModbusDriver(new ModbusDriverOptions
{
Host = "f", RawTags = ModbusRawTags.Entries(tags), Probe = new ModbusProbeOptions { Enabled = false },
}, "m1", _ => t);
await d.InitializeAsync("{}", TestContext.Current.CancellationToken);
return (d, t);
}
[Fact]
public async Task String_array_write_encodes_each_element_at_its_register_width()
{
var tag = new ModbusTagDefinition("S", ModbusRegion.HoldingRegisters, 10, ModbusDataType.String,
StringLength: 3, ArrayCount: 2); // 2 registers per element
var (drv, t) = await StartAsync(tag);
await using var _ = drv;
var w = await drv.WriteAsync([new WriteRequest("S", new[] { "AB", "XYZ" })], TestContext.Current.CancellationToken);
w[0].StatusCode.ShouldBe(0u);
t.Bank.HoldingRegisters[10].ShouldBe((ushort)(('A' << 8) | 'B'));
t.Bank.HoldingRegisters[11].ShouldBe((ushort)0);
t.Bank.HoldingRegisters[12].ShouldBe((ushort)(('X' << 8) | 'Y'));
t.Bank.HoldingRegisters[13].ShouldBe((ushort)('Z' << 8));
// Round trip through the read path.
(await drv.ReadAsync(["S"], TestContext.Current.CancellationToken))[0].Value.ShouldBe(new[] { "AB", "XYZ" });
}
[Fact]
public async Task BitInRegister_array_write_sets_only_the_addressed_bit_of_each_register()
{
var tag = new ModbusTagDefinition("B", ModbusRegion.HoldingRegisters, 30, ModbusDataType.BitInRegister,
BitIndex: 4, ArrayCount: 3);
var (drv, t) = await StartAsync(tag);
await using var _ = drv;
t.Bank.HoldingRegisters[30] = 0xFFFF;
t.Bank.HoldingRegisters[31] = 0x0001;
t.Bank.HoldingRegisters[32] = 0x8000;
var w = await drv.WriteAsync([new WriteRequest("B", new object[] { false, true, 1 })], TestContext.Current.CancellationToken);
w[0].StatusCode.ShouldBe(0u);
t.Bank.HoldingRegisters[30].ShouldBe((ushort)0xFFEF, "bit 4 cleared, neighbours kept");
t.Bank.HoldingRegisters[31].ShouldBe((ushort)0x0011);
t.Bank.HoldingRegisters[32].ShouldBe((ushort)0x8010);
(await drv.ReadAsync(["B"], TestContext.Current.CancellationToken))[0].Value.ShouldBe(new[] { false, true, true });
}
[Theory]
[InlineData("S")]
[InlineData("B")]
public async Task A_length_mismatch_is_BadOutOfRange_and_sends_nothing(string tagName)
{
var (drv, t) = await StartAsync(
new ModbusTagDefinition("S", ModbusRegion.HoldingRegisters, 10, ModbusDataType.String, StringLength: 2, ArrayCount: 2),
new ModbusTagDefinition("B", ModbusRegion.HoldingRegisters, 30, ModbusDataType.BitInRegister, BitIndex: 1, ArrayCount: 3));
await using var _ = drv;
object value = tagName == "S" ? new[] { "only one" } : new[] { true };
var w = await drv.WriteAsync([new WriteRequest(tagName, value)], TestContext.Current.CancellationToken);
w[0].StatusCode.ShouldBe(0x803C0000u);
t.Sent.Where(s => s.Pdu[0] is 0x06 or 0x10).ShouldBeEmpty();
}
}
@@ -0,0 +1,64 @@
using Shouldly;
using Xunit;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// #741 fix round 4 (review r3 N3): <see cref="ModbusTagAddressResolution"/> is the one authority for which part
/// of a Modbus TagConfig names the address. The cross-consumer agreement matrix lives in AdminUI.Tests
/// (<c>ModbusAddressAuthorityAgreementTests</c>); these pin the resolver's own classification and refusals.
/// </summary>
[Trait("Category", "Unit")]
public sealed class ModbusTagAddressResolutionTests
{
[Theory]
[InlineData("""{"region":"InputRegisters","address":5}""", ModbusAddressShape.Keys)]
[InlineData("""{"region":"HoldingRegisters","address":0,"addressString":"D100"}""", ModbusAddressShape.Keys)]
[InlineData("""{"addressString":"D100","addressResolved":true,"region":"HoldingRegisters","address":100}""", ModbusAddressShape.Keys)]
[InlineData("""{"addressString":"40011:F"}""", ModbusAddressShape.StringOnly)]
[InlineData("""{"addressString":"40011:F","addressResolved":true}""", ModbusAddressShape.StringOnly)]
[InlineData("""{"addressString":"40011:F","region":"InputRegisters"}""", ModbusAddressShape.StringOnly)]
[InlineData("""{"addressString":"ZZ9"}""", ModbusAddressShape.StringOnly)]
[InlineData("""{"addressString":5}""", ModbusAddressShape.InvalidAddressString)]
[InlineData("""{"addressString":" "}""", ModbusAddressShape.NoAddress)]
[InlineData("""{"addressString":null}""", ModbusAddressShape.NoAddress)]
[InlineData("""{}""", ModbusAddressShape.NoAddress)]
[InlineData("""[1]""", ModbusAddressShape.NoAddress)]
[InlineData("""not json""", ModbusAddressShape.NoAddress)]
public void Classify_decides_shape_by_key_presence_never_by_the_marker(string json, ModbusAddressShape shape)
=> ModbusTagAddressResolution.Classify(json).ShouldBe(shape);
[Fact]
public void A_string_only_blob_is_refused_with_a_reason_when_the_family_cannot_parse_it()
{
var r = ModbusTagAddressResolution.Resolve("""{"addressString":"D100"}""", ModbusFamily.Generic, MelsecFamily.Q_L_iQR);
r.IsResolved.ShouldBeFalse();
r.Shape.ShouldBe(ModbusAddressShape.StringOnly);
r.Refusal.ShouldNotBeNull().ShouldContain("D100");
var melsec = ModbusTagAddressResolution.Resolve("""{"addressString":"D100"}""", ModbusFamily.MELSEC, MelsecFamily.Q_L_iQR);
melsec.Address.ShouldNotBeNull().Address.ShouldBe((ushort)100);
}
[Fact]
public void Keys_are_read_strictly_and_a_bit_region_is_coerced_to_Bool()
{
ModbusTagAddressResolution.Resolve("""{"region":"Holding","address":1}""", ModbusFamily.Generic, MelsecFamily.Q_L_iQR)
.IsResolved.ShouldBeFalse();
ModbusTagAddressResolution.Resolve("""{"region":"HoldingRegisters","address":70000}""", ModbusFamily.Generic, MelsecFamily.Q_L_iQR)
.IsResolved.ShouldBeFalse();
var coil = ModbusTagAddressResolution.Resolve("""{"region":"Coils","address":3,"dataType":"Int16"}""", ModbusFamily.Generic, MelsecFamily.Q_L_iQR);
coil.Address.ShouldNotBeNull().DataType.ShouldBe(ModbusDataType.Bool);
}
[Fact]
public void AddressStringDescribes_matches_only_the_fields_some_family_parses_it_to()
{
ModbusTagAddressResolution.AddressStringDescribes("D100", ModbusRegion.HoldingRegisters, 100, ModbusDataType.Int16,
ModbusByteOrder.BigEndian, 0, 0).ShouldBeTrue();
ModbusTagAddressResolution.AddressStringDescribes("D100", ModbusRegion.HoldingRegisters, 101, ModbusDataType.Int16,
ModbusByteOrder.BigEndian, 0, 0).ShouldBeFalse();
ModbusTagAddressResolution.AddressStringDescribes("ZZ9", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16,
ModbusByteOrder.BigEndian, 0, 0).ShouldBeFalse();
}
}
@@ -0,0 +1,139 @@
using Shouldly;
using Xunit;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// Transport self-heal (review 07 P3), single in-gate connect attempt + failed-client disposal (L3)
/// and the response-PDU length check (H9).
/// </summary>
[Trait("Category", "Unit")]
public sealed class ModbusTransportSelfHealTests
{
private static readonly byte[] ReadHr0 = [0x03, 0x00, 0x00, 0x00, 0x01];
/// <summary>
/// P3: two lost replies in a row leave the socket torn down. The NEXT call must reconnect on its own
/// instead of failing fast with "Transport not connected" until the 90 s comms-loss watchdog.
/// </summary>
[Fact]
public async Task After_two_consecutive_timeouts_the_next_call_reconnects()
{
await using var server = new ScriptedModbusTcpServer
{
Script = i => i < 2 ? ScriptedModbusTcpServer.Action.Stall : ScriptedModbusTcpServer.Action.Answer,
};
await using var transport = new ModbusTcpTransport("127.0.0.1", server.Port, TimeSpan.FromMilliseconds(500));
await transport.ConnectAsync(TestContext.Current.CancellationToken);
// First call: stall → teardown → reconnect → resend → stall again → propagates.
await Should.ThrowAsync<ModbusTransportDesyncException>(
() => transport.SendAsync(1, ReadHr0, TestContext.Current.CancellationToken));
// Second call: the socket is gone; the transport must dial again and succeed.
var resp = await transport.SendAsync(1, ReadHr0, TestContext.Current.CancellationToken);
resp[0].ShouldBe((byte)0x03);
server.AcceptedConnections.ShouldBe(3);
}
/// <summary>
/// P3 throttle: after a FAILED connect, calls inside the backoff window fail fast with
/// <see cref="ModbusTransportUnavailableException"/> and make no connect attempt; once the window has
/// passed the next call dials again. Positive control: the device is back before the throttled call,
/// so an un-throttled transport would have reconnected.
/// </summary>
[Fact]
public async Task Failed_connect_is_throttled_then_retried_after_the_window()
{
await using var server = new ScriptedModbusTcpServer();
await using var transport = new ModbusTcpTransport("127.0.0.1", server.Port, TimeSpan.FromSeconds(2));
var now = 1_000_000L;
transport.Lifecycle.NowMs = () => now;
await transport.ConnectAsync(TestContext.Current.CancellationToken);
(await transport.SendAsync(1, ReadHr0, TestContext.Current.CancellationToken))[0].ShouldBe((byte)0x03);
server.Stop();
// Dead socket → EOF → teardown → ONE reconnect attempt → refused.
var first = await Should.ThrowAsync<Exception>(
() => transport.SendAsync(1, ReadHr0, TestContext.Current.CancellationToken));
ModbusSocketLifecycle.IsSocketLevelFailure(first).ShouldBeTrue();
server.Start();
var acceptedBefore = server.AcceptedConnections;
await Should.ThrowAsync<ModbusTransportUnavailableException>(
() => transport.SendAsync(1, ReadHr0, TestContext.Current.CancellationToken));
server.AcceptedConnections.ShouldBe(acceptedBefore, "a throttled call must not dial");
now += 60_000; // past any window (MaxDelay default 30 s)
(await transport.SendAsync(1, ReadHr0, TestContext.Current.CancellationToken))[0].ShouldBe((byte)0x03);
server.AcceptedConnections.ShouldBe(acceptedBefore + 1);
}
/// <summary>
/// L3: the reconnect never sleeps inside the transport gate. With a 30 s InitialDelay the old
/// <c>ConnectWithBackoffAsync</c> held the gate for 30 s before even dialling; now one attempt is made
/// and the call returns at once.
/// </summary>
[Fact]
public async Task Reconnect_after_drop_does_not_sleep_inside_the_gate()
{
await using var server = new ScriptedModbusTcpServer();
await using var transport = new ModbusTcpTransport("127.0.0.1", server.Port, TimeSpan.FromSeconds(2),
reconnect: new ModbusReconnectOptions { InitialDelay = TimeSpan.FromSeconds(30) });
await transport.ConnectAsync(TestContext.Current.CancellationToken);
server.Stop();
var call = transport.SendAsync(1, ReadHr0, TestContext.Current.CancellationToken);
var ex = await Should.ThrowAsync<Exception>(() => call.WaitAsync(TimeSpan.FromSeconds(10), TestContext.Current.CancellationToken));
ex.ShouldNotBeOfType<TimeoutException>("the send must not wait out the 30 s backoff inside the gate");
}
/// <summary>H9: an MBAP frame carrying no PDU is a truncated-frame desync, not an IndexOutOfRangeException.</summary>
[Fact]
public async Task Empty_response_pdu_is_a_truncated_frame_desync()
{
await using var server = new ScriptedModbusTcpServer
{
RawReply = (_, header, _) => ScriptedModbusTcpServer.Adu(header, []),
};
await using var transport = new ModbusTcpTransport("127.0.0.1", server.Port, TimeSpan.FromSeconds(2), autoReconnect: false);
await transport.ConnectAsync(TestContext.Current.CancellationToken);
var ex = await Should.ThrowAsync<ModbusTransportDesyncException>(
() => transport.SendAsync(1, ReadHr0, TestContext.Current.CancellationToken));
ex.Reason.ShouldBe(ModbusTransportDesyncException.DesyncReason.TruncatedFrame);
}
/// <summary>H9: an exception frame missing its exception code is a truncated-frame desync.</summary>
[Fact]
public async Task Exception_frame_without_code_is_a_truncated_frame_desync()
{
await using var server = new ScriptedModbusTcpServer
{
RawReply = (_, header, _) => ScriptedModbusTcpServer.Adu(header, [0x83]),
};
await using var transport = new ModbusTcpTransport("127.0.0.1", server.Port, TimeSpan.FromSeconds(2), autoReconnect: false);
await transport.ConnectAsync(TestContext.Current.CancellationToken);
var ex = await Should.ThrowAsync<ModbusTransportDesyncException>(
() => transport.SendAsync(1, ReadHr0, TestContext.Current.CancellationToken));
ex.Reason.ShouldBe(ModbusTransportDesyncException.DesyncReason.TruncatedFrame);
}
/// <summary>Positive control for the two H9 tests: a well-formed exception frame still surfaces as a
/// <see cref="ModbusException"/> carrying its code.</summary>
[Fact]
public async Task Well_formed_exception_frame_still_surfaces_as_ModbusException()
{
await using var server = new ScriptedModbusTcpServer
{
RawReply = (_, header, _) => ScriptedModbusTcpServer.Adu(header, [0x83, 0x02]),
};
await using var transport = new ModbusTcpTransport("127.0.0.1", server.Port, TimeSpan.FromSeconds(2), autoReconnect: false);
await transport.ConnectAsync(TestContext.Current.CancellationToken);
var ex = await Should.ThrowAsync<ModbusException>(
() => transport.SendAsync(1, ReadHr0, TestContext.Current.CancellationToken));
ex.ExceptionCode.ShouldBe((byte)0x02);
}
}
@@ -0,0 +1,160 @@
using System.Net;
using System.Net.Sockets;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// Loopback Modbus-TCP stub whose reply to each request is scripted by the test, and whose listener can
/// be stopped (connection refused) and restarted on the SAME port. Used by the transport self-heal tests
/// that need a device which disappears and comes back.
/// </summary>
internal sealed class ScriptedModbusTcpServer : IAsyncDisposable
{
/// <summary>What the server does with one request.</summary>
public enum Action
{
/// <summary>Answer with an FC03-shaped response of zeroed registers.</summary>
Answer,
/// <summary>Read the request and never answer it (the client's per-op timeout fires).</summary>
Stall,
/// <summary>Close the socket without answering.</summary>
Drop,
}
private TcpListener? _listener;
private CancellationTokenSource _stop = new();
private int _requests;
private int _accepted;
/// <summary>Optional scripted reply. Receives the 0-based request index and the request PDU; returns
/// the raw bytes to write AFTER the MBAP TxId (i.e. the full ADU is built by the test), or null to fall
/// through to <see cref="Script"/>.</summary>
public Func<int, byte[], byte[], byte[]?>? RawReply { get; set; }
/// <summary>Per-request action; defaults to <see cref="Action.Answer"/>.</summary>
public Func<int, Action> Script { get; set; } = _ => Action.Answer;
/// <summary>Gets the port the server listens on (stable across <see cref="Stop"/>/<see cref="Start"/>).</summary>
public int Port { get; }
/// <summary>Gets the number of accepted TCP connections.</summary>
public int AcceptedConnections => Volatile.Read(ref _accepted);
/// <summary>Gets the number of requests received.</summary>
public int Requests => Volatile.Read(ref _requests);
public ScriptedModbusTcpServer()
{
var probe = new TcpListener(IPAddress.Loopback, 0);
probe.Start();
Port = ((IPEndPoint)probe.LocalEndpoint).Port;
probe.Stop();
Start();
}
/// <summary>(Re)starts listening on <see cref="Port"/>.</summary>
public void Start()
{
_stop = new CancellationTokenSource();
_listener = new TcpListener(IPAddress.Loopback, Port);
_listener.Server.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.ReuseAddress, true);
_listener.Start();
var listener = _listener;
var token = _stop.Token;
_ = Task.Run(() => AcceptLoopAsync(listener, token));
}
/// <summary>Stops listening and closes every live connection — new connects are refused.</summary>
public void Stop()
{
try { _stop.Cancel(); } catch { }
try { _listener?.Stop(); } catch { }
_listener = null;
}
private async Task AcceptLoopAsync(TcpListener listener, CancellationToken token)
{
while (!token.IsCancellationRequested)
{
TcpClient client;
try { client = await listener.AcceptTcpClientAsync(token); }
catch { return; }
Interlocked.Increment(ref _accepted);
_ = Task.Run(() => ServeAsync(client, token));
}
}
private async Task ServeAsync(TcpClient client, CancellationToken token)
{
using var _ = client;
using var reg = token.Register(() => { try { client.Close(); } catch { } });
try
{
var stream = client.GetStream();
while (!token.IsCancellationRequested)
{
var header = new byte[7];
if (!await ReadExactly(stream, header, token)) return;
var len = (ushort)((header[4] << 8) | header[5]);
var pdu = new byte[len - 1];
if (!await ReadExactly(stream, pdu, token)) return;
var idx = Interlocked.Increment(ref _requests) - 1;
var raw = RawReply?.Invoke(idx, header, pdu);
if (raw is not null)
{
await stream.WriteAsync(raw, token);
await stream.FlushAsync(token);
continue;
}
switch (Script(idx))
{
case Action.Stall:
continue;
case Action.Drop:
client.Client.Shutdown(SocketShutdown.Both);
return;
}
var qty = (ushort)((pdu[3] << 8) | pdu[4]);
var respPdu = new byte[2 + qty * 2];
respPdu[0] = pdu[0];
respPdu[1] = (byte)(qty * 2);
await stream.WriteAsync(Adu(header, respPdu), token);
await stream.FlushAsync(token);
}
}
catch { /* connection torn down */ }
}
/// <summary>Builds a reply ADU echoing the request's TxId/unit around <paramref name="respPdu"/>.</summary>
public static byte[] Adu(byte[] requestHeader, byte[] respPdu)
{
var respLen = (ushort)(1 + respPdu.Length);
var adu = new byte[7 + respPdu.Length];
adu[0] = requestHeader[0]; adu[1] = requestHeader[1];
adu[4] = (byte)(respLen >> 8); adu[5] = (byte)(respLen & 0xFF);
adu[6] = requestHeader[6];
Buffer.BlockCopy(respPdu, 0, adu, 7, respPdu.Length);
return adu;
}
private static async Task<bool> ReadExactly(Stream s, byte[] buf, CancellationToken token)
{
var read = 0;
while (read < buf.Length)
{
var n = await s.ReadAsync(buf.AsMemory(read), token);
if (n == 0) return false;
read += n;
}
return true;
}
public ValueTask DisposeAsync()
{
Stop();
return ValueTask.CompletedTask;
}
}
@@ -0,0 +1,59 @@
using System.Collections.Concurrent;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// In-memory transport whose every send is answered by a test-supplied handler; falls back to the
/// register/coil bank fake (<see cref="ModbusDriverTests.FakeTransport"/>) when the handler returns null.
/// Counts sends per unit and dispose calls; the connect can be blocked on a gate.
/// </summary>
internal sealed class ScriptedTransport : IModbusTransport
{
private readonly ConcurrentDictionary<byte, int> _sendsByUnit = new();
private int _disposeCount;
/// <summary>The bank answering un-scripted sends.</summary>
public ModbusDriverTests.FakeTransport Bank { get; } = new();
/// <summary>Per-send handler; return null to fall through to <see cref="Bank"/>.</summary>
public Func<byte, byte[], CancellationToken, Task<byte[]>?>? Handler { get; set; }
/// <summary>When set, <see cref="ConnectAsync"/> waits for it before completing.</summary>
public TaskCompletionSource? ConnectGate { get; set; }
/// <summary>Signalled when <see cref="ConnectAsync"/> is entered.</summary>
public TaskCompletionSource ConnectEntered { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
public int DisposeCount => Volatile.Read(ref _disposeCount);
public int SendsTo(byte unit) => _sendsByUnit.TryGetValue(unit, out var n) ? n : 0;
public int TotalSends => _sendsByUnit.Values.Sum();
/// <summary>Every PDU sent, in order.</summary>
public ConcurrentQueue<(byte Unit, byte[] Pdu)> Sent { get; } = new();
/// <summary>The (function code, start, quantity) of every sent request with that function code.</summary>
public List<(byte Fc, ushort Start, ushort Qty)> Requests(byte fc) =>
[.. Sent.Where(s => s.Pdu[0] == fc).Select(s => (s.Pdu[0], (ushort)((s.Pdu[1] << 8) | s.Pdu[2]), (ushort)((s.Pdu[3] << 8) | s.Pdu[4])))];
public async Task ConnectAsync(CancellationToken ct)
{
ConnectEntered.TrySetResult();
if (ConnectGate is { } gate) await gate.Task.WaitAsync(ct);
}
public Task<byte[]> SendAsync(byte unitId, byte[] pdu, CancellationToken ct)
{
_sendsByUnit.AddOrUpdate(unitId, 1, (_, n) => n + 1);
Sent.Enqueue((unitId, pdu));
var scripted = Handler?.Invoke(unitId, pdu, ct);
return scripted ?? Bank.SendAsync(unitId, pdu, ct);
}
public ValueTask DisposeAsync()
{
Interlocked.Increment(ref _disposeCount);
return ValueTask.CompletedTask;
}
}