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

Task #141 — Modbus subscribe-side knobs (deadband + write-on-change)

Browse Source 
Two driver-side filters that ≥5 of 6 surveyed vendors expose:

1. Per-tag Deadband (double?, on ModbusTagDefinition) — when set, the
   PollGroupEngine onChange callback suppresses publishes whose distance
   from the last-published value is below the threshold. Reduces wire
   traffic to OPC UA clients on noisy analog signals (flow meters,
   temperatures). Numeric scalar types only — Bool / BitInRegister / String
   / array tags publish unconditionally.

2. WriteOnChangeOnly (bool, on ModbusDriverOptions) — when true, the driver
   short-circuits writes whose value matches the most recent successful
   write to that tag. Saves PLC bandwidth on clients that re-publish the
   same setpoint every scan. Cache invalidates on any read that returns a
   different value, so HMI-side changes don't get masked.

Both default off so existing deployments see no behaviour change.

Implementation:
- ShouldPublish guard wraps the existing OnDataChange invocation. First sample
  always passes through (no baseline); subsequent samples compare via
  Convert.ToDouble for the cross-numeric-type math.
- IsRedundantWrite check at the top of WriteAsync; on success the cache is
  populated. Object.Equals handles boxed-numeric equality; arrays are
  excluded (reference-equality would never match anyway).
- ReadAsync invalidates the WriteOnChangeOnly cache when the new value
  differs from the cached last-written value.

Tests (5 new ModbusSubscribeOptionsTests):
- Deadband suppresses sub-threshold changes (100 → 102 → 106 → 107 with
  deadband=5 publishes 100 and 106 only).
- Deadband=null still publishes every change.
- WriteOnChangeOnly suppresses 3 identical 42 writes (only first hits wire).
- WriteOnChangeOnly default false hits the wire every time.
- Read-divergence cache invalidation: external panel write to 99, our
  client's re-write of 42 must NOT be suppressed.

220/220 unit tests green; existing ProtocolOptions tests hardened against
probe-loop noise by disabling the probe in their fixtures.
This commit is contained in:
Joseph Doherty
2026-04-25 00:05:25 -04:00
parent 55f4044a69
commit 4bffe879c5
5 changed files with 282 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusProtocolOptionsTests.cs
View File

@@ -63,7 +63,7 @@ public sealed class ModbusProtocolOptionsTests
{
var fake = new CapturingTransport();
var tag = new ModbusTagDefinition("Run", ModbusRegion.Coils, 0, ModbusDataType.Bool);
var drv = new ModbusDriver(new ModbusDriverOptions { Host = "f", Tags = [tag] }, "m1", _ => fake);
var drv = new ModbusDriver(new ModbusDriverOptions { Host = "f", Tags = [tag], Probe = new ModbusProbeOptions { Enabled = false } }, "m1", _ => fake);
await drv.InitializeAsync("{}", CancellationToken.None);
await drv.WriteAsync([new WriteRequest("Run", true)], CancellationToken.None);
@@ -76,7 +76,7 @@ public sealed class ModbusProtocolOptionsTests
{
var fake = new CapturingTransport();
var tag = new ModbusTagDefinition("Run", ModbusRegion.Coils, 0, ModbusDataType.Bool);
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag], UseFC15ForSingleCoilWrites = true };
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag], UseFC15ForSingleCoilWrites = true, Probe = new ModbusProbeOptions { Enabled = false } };
var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", CancellationToken.None);
@@ -90,7 +90,7 @@ public sealed class ModbusProtocolOptionsTests
{
var fake = new CapturingTransport();
var tag = new ModbusTagDefinition("Sp", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16);
var drv = new ModbusDriver(new ModbusDriverOptions { Host = "f", Tags = [tag] }, "m1", _ => fake);
var drv = new ModbusDriver(new ModbusDriverOptions { Host = "f", Tags = [tag], Probe = new ModbusProbeOptions { Enabled = false } }, "m1", _ => fake);
await drv.InitializeAsync("{}", CancellationToken.None);
await drv.WriteAsync([new WriteRequest("Sp", (short)42)], CancellationToken.None);
@@ -103,7 +103,7 @@ public sealed class ModbusProtocolOptionsTests
{
var fake = new CapturingTransport();
var tag = new ModbusTagDefinition("Sp", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16);
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag], UseFC16ForSingleRegisterWrites = true };
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag], UseFC16ForSingleRegisterWrites = true, Probe = new ModbusProbeOptions { Enabled = false } };
var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", CancellationToken.None);
@@ -118,7 +118,7 @@ public sealed class ModbusProtocolOptionsTests
var fake = new CapturingTransport();
// 2500 coils with cap 2000 → 2 reads (2000 + 500).
var tag = new ModbusTagDefinition("Big", ModbusRegion.Coils, 0, ModbusDataType.Bool, ArrayCount: 2500);
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag], MaxCoilsPerRead = 2000 };
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag], MaxCoilsPerRead = 2000, Probe = new ModbusProbeOptions { Enabled = false } };
var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", CancellationToken.None);

172
tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests/ModbusSubscribeOptionsTests.cs Normal file
View File

@@ -0,0 +1,172 @@
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Tests;
/// <summary>
/// #141 subscribe-side knobs: per-tag Deadband, driver-wide WriteOnChangeOnly.
/// </summary>
[Trait("Category", "Unit")]
public sealed class ModbusSubscribeOptionsTests
{
/// <summary>
/// Programmable transport: caller seeds a bank-of-registers value, each FC03 returns
/// the current value. Lets tests step the underlying register through a sequence and
/// observe how the deadband filter responds.
/// </summary>
private sealed class ProgrammableTransport : IModbusTransport
{
public ushort CurrentValue;
public int WritesSent;
public int FC06Count;
public Task ConnectAsync(CancellationToken ct) => Task.CompletedTask;
public Task<byte[]> SendAsync(byte unitId, byte[] pdu, CancellationToken ct)
{
switch (pdu[0])
{
case 0x03:
{
var qty = (ushort)((pdu[3] << 8) | pdu[4]);
var resp = new byte[2 + qty * 2];
resp[0] = 0x03; resp[1] = (byte)(qty * 2);
for (var i = 0; i < qty; i++)
{
resp[2 + i * 2] = (byte)(CurrentValue >> 8);
resp[3 + i * 2] = (byte)(CurrentValue & 0xFF);
}
return Task.FromResult(resp);
}
case 0x06:
WritesSent++; FC06Count++;
CurrentValue = (ushort)((pdu[3] << 8) | pdu[4]);
return Task.FromResult(pdu);
default:
return Task.FromResult(new byte[] { pdu[0], 0, 0 });
}
}
public ValueTask DisposeAsync() => ValueTask.CompletedTask;
}
[Fact]
public async Task Deadband_Suppresses_SubThreshold_Changes()
{
var fake = new ProgrammableTransport();
var tag = new ModbusTagDefinition("Temp", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16, Deadband: 5.0);
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag], Probe = new ModbusProbeOptions { Enabled = false } };
var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", CancellationToken.None);
var publishes = new List<short>();
drv.OnDataChange += (_, e) => publishes.Add((short)e.Snapshot.Value!);
// First publish always passes (no baseline). Then step the value:
// 100 → 102 (delta 2 < 5, suppressed) → 106 (delta 6 ≥ 5, published) → 107 (delta 1, suppressed).
var sub = await drv.SubscribeAsync(["Temp"], TimeSpan.FromMilliseconds(50), CancellationToken.None);
try
{
fake.CurrentValue = 100;
await Task.Delay(150);
fake.CurrentValue = 102;
await Task.Delay(150);
fake.CurrentValue = 106;
await Task.Delay(150);
fake.CurrentValue = 107;
await Task.Delay(150);
}
finally
{
await drv.UnsubscribeAsync(sub, CancellationToken.None);
}
// Expect at most 2 distinct values surfaced (100 baseline + 106). The 102 and 107 should
// be suppressed by the deadband. Ordering can be flaky on slow CI so we assert the set,
// not the exact sequence.
publishes.ShouldContain((short)100);
publishes.ShouldContain((short)106);
publishes.ShouldNotContain((short)102);
publishes.ShouldNotContain((short)107);
}
[Fact]
public async Task Deadband_Null_Publishes_Every_Change()
{
var fake = new ProgrammableTransport();
var tag = new ModbusTagDefinition("Temp", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16); // no deadband
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag], Probe = new ModbusProbeOptions { Enabled = false } };
var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", CancellationToken.None);
var publishes = new List<short>();
drv.OnDataChange += (_, e) => publishes.Add((short)e.Snapshot.Value!);
var sub = await drv.SubscribeAsync(["Temp"], TimeSpan.FromMilliseconds(50), CancellationToken.None);
try
{
fake.CurrentValue = 100; await Task.Delay(150);
fake.CurrentValue = 101; await Task.Delay(150); // tiny change still publishes
}
finally { await drv.UnsubscribeAsync(sub, CancellationToken.None); }
publishes.ShouldContain((short)100);
publishes.ShouldContain((short)101);
}
[Fact]
public async Task WriteOnChangeOnly_Suppresses_Identical_Repeated_Writes()
{
var fake = new ProgrammableTransport();
var tag = new ModbusTagDefinition("Sp", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16);
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag], WriteOnChangeOnly = true,
Probe = new ModbusProbeOptions { Enabled = false } };
var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", CancellationToken.None);
await drv.WriteAsync([new WriteRequest("Sp", (short)42)], CancellationToken.None);
await drv.WriteAsync([new WriteRequest("Sp", (short)42)], CancellationToken.None); // suppressed
await drv.WriteAsync([new WriteRequest("Sp", (short)42)], CancellationToken.None); // suppressed
await drv.WriteAsync([new WriteRequest("Sp", (short)43)], CancellationToken.None); // distinct
fake.WritesSent.ShouldBe(2, "two distinct values written; identical-value repeats suppressed");
}
[Fact]
public async Task WriteOnChangeOnly_Default_False_Always_Writes()
{
var fake = new ProgrammableTransport();
var tag = new ModbusTagDefinition("Sp", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16);
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag],
Probe = new ModbusProbeOptions { Enabled = false } };
var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", CancellationToken.None);
await drv.WriteAsync([new WriteRequest("Sp", (short)42)], CancellationToken.None);
await drv.WriteAsync([new WriteRequest("Sp", (short)42)], CancellationToken.None);
await drv.WriteAsync([new WriteRequest("Sp", (short)42)], CancellationToken.None);
fake.WritesSent.ShouldBe(3, "default false → every write goes to the wire");
}
[Fact]
public async Task WriteOnChangeOnly_Cache_Invalidated_By_Read_Divergence()
{
var fake = new ProgrammableTransport();
var tag = new ModbusTagDefinition("Sp", ModbusRegion.HoldingRegisters, 0, ModbusDataType.Int16);
var opts = new ModbusDriverOptions { Host = "f", Tags = [tag], WriteOnChangeOnly = true,
Probe = new ModbusProbeOptions { Enabled = false } };
var drv = new ModbusDriver(opts, "m1", _ => fake);
await drv.InitializeAsync("{}", CancellationToken.None);
await drv.WriteAsync([new WriteRequest("Sp", (short)42)], CancellationToken.None);
fake.FC06Count.ShouldBe(1);
// External change at the PLC (panel writes 99). Read sees 99 → invalidates the cache.
fake.CurrentValue = 99;
var read = await drv.ReadAsync(["Sp"], CancellationToken.None);
read[0].Value.ShouldBe((short)99);
// Now writing 42 again should NOT be suppressed because the cache was invalidated.
await drv.WriteAsync([new WriteRequest("Sp", (short)42)], CancellationToken.None);
fake.FC06Count.ShouldBe(2, "post-divergence write not suppressed");
}
}