Change the callback signature from Action<string, string, Level> to a

  named BitfieldChangedCallback delegate declared alongside IModbusClient.
  The callback now passes both the previous and current enum values as
  boxed objects instead of a pre-computed description string. Consumers
  can call ToString() for flag names, cast to the typed enum, or convert
  to ulong for the numeric value. Add braces around all generated if
  statement bodies.

Author: mattd-bp

Modspec.Model/Generation/ModspecModelGenerator.cs

@@ -110,7 +110,7 @@ namespace {schema.Name};
                     if (groupHasChangeDetection)
                     {
                         hasChangeDetection = true;
-                        mainWriter.WriteLine("\t\tprivate readonly Action<string, string, Level>? _onBitfieldChanged;");
+                        mainWriter.WriteLine("\t\tprivate readonly BitfieldChangedCallback? _onBitfieldChanged;");
                     }
                     groupFieldInitialisers.Add("_offset = offset;");
                     if (groupHasChangeDetection)
@@ -148,7 +148,7 @@ namespace {schema.Name};
 
                 if (hasChangeDetection)
                 {
-                    mainWriter.WriteLine("\tprivate readonly Action<string, string, Level>? _onBitfieldChanged;");
+                    mainWriter.WriteLine("\tprivate readonly BitfieldChangedCallback? _onBitfieldChanged;");
                 }
                 WriteFieldsAndConstructor(schema.Name + "Client", mainWriter, bufferInitialisers, fieldInitialisers, constructorParams, hasChangeDetection: hasChangeDetection);
                 mainWriter.WriteLine("}");
@@ -169,7 +169,7 @@ private static void WriteFieldsAndConstructor(string name, StringWriter mainWrit
             }
             if (hasChangeDetection)
             {
-                mainWriter.Write(", Action<string, string, Level>? onBitfieldChanged = null");
+                mainWriter.Write(", BitfieldChangedCallback? onBitfieldChanged = null");
             }
             mainWriter.WriteLine(")");
             mainWriter.WriteLine($"{indent}\t{{");
@@ -240,7 +240,10 @@ private static void WriteGroups(IReadOnlyCollection<Group> groups, StringWriter
                 mainWriter.WriteLine($"\t\t{indent}await _client.Read{group.Table}Async({readOffsetField}{group.BaseRegister}, {bufferName});");
                 if (groupBitfieldPoints.Count > 0)
                 {
-                    mainWriter.WriteLine($"\t\t{indent}if (_onBitfieldChanged is not null) Check{group.Name}();");
+                    mainWriter.WriteLine($"\t\t{indent}if (_onBitfieldChanged is not null)");
+                    mainWriter.WriteLine($"\t\t{indent}{{");
+                    mainWriter.WriteLine($"\t\t\t{indent}Check{group.Name}();");
+                    mainWriter.WriteLine($"\t\t{indent}}}");
                 }
                 mainWriter.WriteLine($"\t{indent}}}");
                 mainWriter.WriteLine();
@@ -250,7 +253,10 @@ private static void WriteGroups(IReadOnlyCollection<Group> groups, StringWriter
                 mainWriter.WriteLine($"\t\t{indent}_client.Read{group.Table}({readOffsetField}{group.BaseRegister}, {bufferName}.Span);");
                 if (groupBitfieldPoints.Count > 0)
                 {
-                    mainWriter.WriteLine($"\t\t{indent}if (_onBitfieldChanged is not null) Check{group.Name}();");
+                    mainWriter.WriteLine($"\t\t{indent}if (_onBitfieldChanged is not null)");
+                    mainWriter.WriteLine($"\t\t{indent}{{");
+                    mainWriter.WriteLine($"\t\t\t{indent}Check{group.Name}();");
+                    mainWriter.WriteLine($"\t\t{indent}}}");
                 }
                 mainWriter.WriteLine($"\t{indent}}}");
                 mainWriter.WriteLine();
@@ -265,7 +271,8 @@ private static void WriteGroups(IReadOnlyCollection<Group> groups, StringWriter
                     {
                         mainWriter.WriteLine($"\t\t{indent}if (!current.Slice({bp.Offset}, {bp.SizeInBytes}).SequenceEqual(previous.Slice({bp.Offset}, {bp.SizeInBytes})))");
                         mainWriter.WriteLine($"\t\t{indent}{{");
-                        mainWriter.WriteLine($"\t\t\t{indent}_onBitfieldChanged!(\"{bp.PointName}\", {bp.PointName}.ToString(), {bp.PointName}.GetLevel());");
+                        mainWriter.WriteLine($"\t\t\t{indent}{bp.PointName} oldValue = ({bp.PointName}){bp.ReadMethod}(previous.Slice({bp.Offset}, {bp.SizeInBytes}));");
+                        mainWriter.WriteLine($"\t\t\t{indent}_onBitfieldChanged!(\"{bp.PointName}\", oldValue, {bp.PointName}, {bp.PointName}.GetLevel());");
                         mainWriter.WriteLine($"\t\t{indent}}}");
                     }
                     mainWriter.WriteLine($"\t\t{indent}current.CopyTo(previous);");
@@ -403,7 +410,7 @@ private static void WritePoint(Point point, string bufferName, Table table, Stri
                 appendixWriter.WriteLine();
                 if (isFlags && masksByLevel.Count > 0)
                 {
-                    groupBitfieldPoints?.Add(new BitfieldPointInfo(point.Name, maxOffset, point.SizeInBytes));
+                    groupBitfieldPoints?.Add(new BitfieldPointInfo(point.Name, maxOffset, point.SizeInBytes, readMethod));
                     appendixWriter.WriteLine($"public static class {point.Name}Extensions");
                     appendixWriter.WriteLine("{");
                     appendixWriter.WriteLine($"\tpublic static Level GetLevel(this {point.Name} self)");
@@ -535,5 +542,5 @@ private static string Pluralise(string self)
     }
 
     private record ConstructorParameter(string Name, int Count);
-    private record BitfieldPointInfo(string PointName, int Offset, int SizeInBytes);
+    private record BitfieldPointInfo(string PointName, int Offset, int SizeInBytes, string ReadMethod);
 }

Modspec.Model/IModbusClient.cs

@@ -8,6 +8,15 @@
 
 namespace Modspec.Model;
 
+/// <summary>
+/// Callback invoked when a bitfield point with level annotations changes between reads.
+/// </summary>
+/// <param name="name">The name of the bitfield point that changed.</param>
+/// <param name="oldValue">The previous value of the bitfield (boxed enum).</param>
+/// <param name="newValue">The current value of the bitfield (boxed enum).</param>
+/// <param name="level">The highest severity level among the currently set flags.</param>
+public delegate void BitfieldChangedCallback(string name, object oldValue, object newValue, Level level);
+
 /// <summary>
 /// Interface for a Modbus client.
 /// </summary>

Modspec.Test/Tests.cs

@@ -92,9 +92,9 @@ public void TestErrorLevels()
     public async Task TestInlineChangeDetectionNoChange()
     {
         MockModbusClient mockClient = new MockModbusClient();
-        List<(string name, string description, Level level)> changes = [];
+        List<(string name, object oldValue, object newValue, Level level)> changes = [];
         SomeBmsClient bmsClient = new SomeBmsClient(mockClient, 2, 2, 480, 100,
-            onBitfieldChanged: (name, desc, level) => changes.Add((name, desc, level)));
+            onBitfieldChanged: (name, oldVal, newVal, level) => changes.Add((name, oldVal, newVal, level)));
 
         // no errors — no callback
         await bmsClient.ReadWarningsErrorsEmergenciesAsync();
@@ -109,16 +109,18 @@ public async Task TestInlineChangeDetectionNoChange()
     public async Task TestInlineChangeDetectionDetectsChange()
     {
         MockModbusClient mockClient = new MockModbusClient();
-        List<(string name, string description, Level level)> changes = [];
+        List<(string name, object oldValue, object newValue, Level level)> changes = [];
         SomeBmsClient bmsClient = new SomeBmsClient(mockClient, 2, 2, 480, 100,
-            onBitfieldChanged: (name, desc, level) => changes.Add((name, desc, level)));
+            onBitfieldChanged: (name, oldVal, newVal, level) => changes.Add((name, oldVal, newVal, level)));
 
         // introduce an error and read
         mockClient.DiscreteInputs.Span[1] = 0b10000000; // StringTerminalDischargeOverCurrentError
         await bmsClient.ReadWarningsErrorsEmergenciesAsync();
         Assert.That(changes, Has.Count.EqualTo(1));
         Assert.That(changes[0].name, Is.EqualTo("StringErrors1"));
-        Assert.That(changes[0].description, Does.Contain("StringTerminalDischargeOverCurrentError"));
+        Assert.That(changes[0].oldValue, Is.EqualTo((StringErrors1)0));
+        Assert.That(changes[0].newValue, Is.EqualTo(StringErrors1.StringTerminalDischargeOverCurrentError));
+        Assert.That(changes[0].newValue.ToString(), Does.Contain("StringTerminalDischargeOverCurrentError"));
         Assert.That(changes[0].level, Is.EqualTo(Level.Error));
 
         // same state again — no callback
@@ -131,9 +133,9 @@ public async Task TestInlineChangeDetectionDetectsChange()
     public async Task TestInlineChangeDetectionReportsHighestLevel()
     {
         MockModbusClient mockClient = new MockModbusClient();
-        List<(string name, string description, Level level)> changes = [];
+        List<(string name, object oldValue, object newValue, Level level)> changes = [];
         SomeBmsClient bmsClient = new SomeBmsClient(mockClient, 2, 2, 480, 100,
-            onBitfieldChanged: (name, desc, level) => changes.Add((name, desc, level)));
+            onBitfieldChanged: (name, oldVal, newVal, level) => changes.Add((name, oldVal, newVal, level)));
 
         // set both a warning (bit 0) and an emergency (bit 2) on StringErrors1
         mockClient.DiscreteInputs.Span[1] = 0b00000101;