Implement Multicast

Author: jdomnitz

Examples.md

@@ -63,9 +63,18 @@ async Task Meter_Update(Node sender, CommandClassEventArgs args)
 }
 ```
 
-#### Broadcasting Commands:
+#### Broadcast Commands:
 The controller contains a broadcast node with a set of command classes prepopulated. Broadcast commands do not reflect what command classes the network may or may not support.
 ```c#
 await controller.BroadcastNode.GetCommandClass<SwitchBinary>()!.Set(true);
 ```
-_This example turns on all switches in the network_
+_This example turns on all switches in the network_
+
+#### Multicast Commands:
+The controller can create Multicast Groups of multiple Nodes. Multicast Command Classes will be the minimum set supported by all group members.
+```c#
+1: NodeGroup group = controller.CreateGroup(node1, node2);
+2: await group.GetCommandClass<SwitchBinary>()!.Set(true, TimeSpan.FromSeconds(1));
+```
+_Line 1 Creates a group with two members._\
+_Line 2 Turn on all binary switches in the group with a single multicast command._

README.md

@@ -17,7 +17,7 @@ An implementation of ZWave Plus using the 2024a public specification.
 * See our [Examples Page](Examples.md)
 
 #### Not Supported:
-* Multicast is not fully implemented (including secure multicast)
+* Secure Multicast is not fully implemented
 
 #### Other Projects
 * Check out my other projects for [HomeKit](https://github.com/SmartHomeOS/HomeKitDotNet) and [Matter](https://github.com/SmartHomeOS/MatterDotNet).

ZWaveDotNet/CommandClasses/CommandClassBase.cs

@@ -49,9 +49,9 @@ public abstract class CommandClassBase
         /// Parent Controller
         /// </summary>
         protected Controller controller;
-        private CommandClass commandClass;
-        private byte endpoint;
-        private ConcurrentDictionary<byte, BlockingCollection<TaskCompletionSource<ReportMessage>>> callbacks = new ConcurrentDictionary<byte, BlockingCollection<TaskCompletionSource<ReportMessage>>>();
+        private readonly CommandClass commandClass;
+        private readonly byte endpoint;
+        private readonly ConcurrentDictionary<byte, BlockingCollection<TaskCompletionSource<ReportMessage>>> callbacks = new ConcurrentDictionary<byte, BlockingCollection<TaskCompletionSource<ReportMessage>>>();
 
         /// <summary>
         /// Base Class
@@ -319,10 +319,26 @@ protected async Task<bool> SendCommand(Enum command, CancellationToken token, pa
         /// <param name="supervised"></param>
         /// <param name="payload"></param>
         /// <returns></returns>
-        protected async Task<bool> SendCommand(Enum command, CancellationToken token, bool supervised = false, params byte[] payload)
+        protected Task<bool> SendCommand(Enum command, CancellationToken token, bool supervised = false, params byte[] payload)
         {
-            // TODO - Multicast
-            CommandMessage data = new CommandMessage(controller, node.ID, endpoint, commandClass, Convert.ToByte(command), supervised, payload);
+            return SendCommand(Convert.ToByte(command), token, supervised, payload);
+        }
+
+        /// <summary>
+        /// Send a command (no response expected)
+        /// </summary>
+        /// <param name="command"></param>
+        /// <param name="token"></param>
+        /// <param name="supervised"></param>
+        /// <param name="payload"></param>
+        /// <returns></returns>
+        protected async Task<bool> SendCommand(byte command, CancellationToken token, bool supervised = false, params byte[] payload)
+        {
+            CommandMessage data;
+            if (node is NodeGroup group)
+                data = new CommandMessage(controller, group.MemberIDs, 0, commandClass, command, supervised, payload);
+            else
+                data = new CommandMessage(controller, [node.ID], endpoint, commandClass, Convert.ToByte(command), supervised, payload);
             return await SendCommand(data, token).ConfigureAwait(false);
         }
 
@@ -339,9 +355,7 @@ internal async Task<bool> SendCommand(CommandMessage data, CancellationToken tok
             {
                 if (controller.SecurityManager == null)
                     throw new InvalidOperationException("Secure command requires security manager");
-                SecurityManager.NetworkKey? key = controller.SecurityManager.GetHighestKey(node.ID);
-                if (key == null)
-                    throw new InvalidOperationException($"Command classes are secure but no keys exist for node {node.ID}");
+                SecurityManager.NetworkKey key = controller.SecurityManager.GetHighestKey(node.ID) ?? throw new InvalidOperationException($"Command classes are secure but no keys exist for node {node.ID}");
                 if (key.Key == SecurityManager.RecordType.S0)
                     await node.GetCommandClass<Security0>()!.Encapsulate(data.Payload, token).ConfigureAwait(false);
                 else if (key.Key > SecurityManager.RecordType.S0)
@@ -350,10 +364,12 @@ internal async Task<bool> SendCommand(CommandMessage data, CancellationToken tok
                     throw new InvalidOperationException("Security required but no keys are available");
             }
 
-            DataMessage message = data.ToMessage();
+            CallbackBase message = data.ToMessage();
             if ((!node.LongRange && data.Payload.Count > 46) || (data.Payload.Count > 120))
             {
-                return await TransportService.Transmit(message, token);
+                if (message is DataMessage msg)
+                    return await TransportService.Transmit(msg, token);
+                throw new InvalidOperationException("Multicast Transport Commands are not supported");
             }
 
             for (int i = 0; i < 3; i++)
@@ -374,7 +390,7 @@ internal async Task<bool> SendCommand(CommandMessage data, CancellationToken tok
         /// <param name="ex"></param>
         /// <returns></returns>
         /// <exception cref="Exception"></exception>
-        internal async Task<bool> AttemptTransmission(DataMessage message, CancellationToken cancellationToken, bool ex = false)
+        internal async Task<bool> AttemptTransmission(CallbackBase message, CancellationToken cancellationToken, bool ex = false)
         {
             DataCallback dc = await controller.Flow.SendAcknowledgedResponseCallback(message, b => b != 0x0, cancellationToken).ConfigureAwait(false);
             if (dc.Status != TransmissionStatus.CompleteOk && dc.Status != TransmissionStatus.CompleteNoAck && dc.Status != TransmissionStatus.CompleteVerified)
@@ -471,8 +487,10 @@ internal Task<ReportMessage> Receive(Enum response, CancellationToken token)
                 cbList.Add(src, token);
             else
             {
-                BlockingCollection<TaskCompletionSource<ReportMessage>> newCallbacks = new BlockingCollection<TaskCompletionSource<ReportMessage>>();
-                newCallbacks.Add(src, token);
+                BlockingCollection<TaskCompletionSource<ReportMessage>> newCallbacks = new BlockingCollection<TaskCompletionSource<ReportMessage>>
+                {
+                    { src, token }
+                };
                 if (!callbacks.TryAdd(cmd, newCallbacks))
                     callbacks[cmd].Add(src, token);
             }

ZWaveDotNet/CommandClasses/NoOperation.cs

@@ -26,7 +26,7 @@ internal NoOperation(Node node, byte endpoint) : base(node, endpoint, CommandCla
 
         public async Task<bool> Ping(CancellationToken cancellationToken = default)
         {
-            CommandMessage data = new CommandMessage(controller, node.ID, (byte)(EndPoint & 0x7F), CommandClass, 0x0);
+            CommandMessage data = new CommandMessage(controller, [node.ID], (byte)(EndPoint & 0x7F), CommandClass, 0x0);
             data.Payload.RemoveAt(1); //This class sends no command
             DataCallback dc = await controller.Flow.SendAcknowledgedResponseCallback(data.ToMessage(), b => b != 0x0, cancellationToken);
             return (dc.Status == TransmissionStatus.CompleteOk || dc.Status == TransmissionStatus.CompleteNoAck || dc.Status == TransmissionStatus.CompleteVerified);

ZWaveDotNet/CommandClasses/Security0.cs

@@ -66,7 +66,7 @@ internal async Task SchemeGet(CancellationToken cancellationToken = default)
         internal async Task KeySet(CancellationToken cancellationToken = default)
         {
             Log.Verbose($"Setting Network Key on {node.ID}");
-            CommandMessage data = new CommandMessage(controller, node.ID, EndPoint, CommandClass, (byte)Security0Command.NetworkKeySet, false, controller.NetworkKeyS0);
+            CommandMessage data = new CommandMessage(controller, [node.ID], EndPoint, CommandClass, (byte)Security0Command.NetworkKeySet, false, controller.NetworkKeyS0);
             await TransmitTemp(data.Payload, cancellationToken).ConfigureAwait(false);
         }
 
@@ -95,7 +95,7 @@ internal async Task TransmitTemp(List<byte> payload, CancellationToken cancellat
             Log.Verbose("Creating Temp Payload for " + node.ID.ToString());
             byte[] receiversNonce = report.Payload.ToArray();
             byte[] sendersNonce = new byte[8];
-            new Random().NextBytes(sendersNonce);
+            Random.Shared.NextBytes(sendersNonce);
             payload.Insert(0, 0x0); //Sequenced = False
             byte[] encrypted = EncryptDecryptPayload(payload.ToArray(), sendersNonce, receiversNonce, controller.tempE);
             byte[] mac = AES.ComputeMAC(controller.ID, node.ID, (byte)Security0Command.MessageEncap, sendersNonce, receiversNonce, encrypted, controller.tempA);
@@ -118,7 +118,7 @@ internal async Task Encapsulate(List<byte> payload, CancellationToken cancellati
             Log.Verbose("Creating Payload for " + node.ID.ToString());
             byte[] receiversNonce = report.Payload.ToArray();
             byte[] sendersNonce = new byte[8];
-            new Random().NextBytes(sendersNonce);
+            Random.Shared.NextBytes(sendersNonce);
             payload.Insert(0, 0x0); //Sequenced = False
             byte[] encrypted = EncryptDecryptPayload(payload.ToArray(), sendersNonce, receiversNonce, controller.EncryptionKey);
             byte[] mac = AES.ComputeMAC(controller.ID, node.ID, (byte)Security0Command.MessageEncap, sendersNonce, receiversNonce, encrypted, controller.AuthenticationKey);

ZWaveDotNet/CommandClasses/Security2.cs

@@ -34,7 +34,7 @@ public class Security2 : CommandClassBase
         private const byte TRANSFER_COMPLETE = 0x1;
         public event CommandClassEvent<ErrorReport>? SecurityError;
         TaskCompletionSource bootstrapComplete = new TaskCompletionSource();
-        private static uint sequence = (uint)new Random().Next();
+        private static uint sequence = (uint)Random.Shared.Next();
 
         internal enum Security2Command
         {
@@ -128,7 +128,7 @@ internal async Task KexFail(KexFailType type, CancellationToken cancellationToke
             controller.SecurityManager?.GetRequestedKeys(node.ID, true);
             if (type == KexFailType.KEX_FAIL_AUTH || type == KexFailType.KEX_FAIL_DECRYPT || type == KexFailType.KEX_FAIL_KEY_VERIFY || type == KexFailType.KEX_FAIL_KEY_GET)
             {
-                CommandMessage reportKex = new CommandMessage(controller, node.ID, EndPoint, CommandClass, (byte)Security2Command.KEXFail, false, (byte)type);
+                CommandMessage reportKex = new CommandMessage(controller, [node.ID], EndPoint, CommandClass, (byte)Security2Command.KEXFail, false, (byte)type);
                 await Transmit(reportKex.Payload, SecurityManager.RecordType.ECDH_TEMP, cancellationToken).ConfigureAwait(false);
             }
             else
@@ -386,6 +386,8 @@ internal override async Task<SupervisionStatus> Handle(ReportMessage message)
                     {
                         if (controller.SecurityManager == null)
                             return SupervisionStatus.Fail;
+                        if (message.IsMulticastMethod)
+                            return SupervisionStatus.Fail;
                         KeyExchangeReport? requestedKeys = controller.SecurityManager.GetRequestedKeys(node.ID);
                         if (requestedKeys != null)
                         {
@@ -396,7 +398,7 @@ internal override async Task<SupervisionStatus> Handle(ReportMessage message)
                             }
                             requestedKeys.Echo = true;
                             Log.Verbose("Responding: " + requestedKeys.ToString());
-                            CommandMessage reportKex = new CommandMessage(controller, node.ID, EndPoint, CommandClass, (byte)Security2Command.KEXReport, false, requestedKeys.ToBytes());
+                            CommandMessage reportKex = new CommandMessage(controller, [node.ID], EndPoint, CommandClass, (byte)Security2Command.KEXReport, false, requestedKeys.ToBytes());
                             await Transmit(reportKex.Payload, SecurityManager.RecordType.ECDH_TEMP).ConfigureAwait(false);
                         }
                     }
@@ -445,13 +447,15 @@ internal override async Task<SupervisionStatus> Handle(ReportMessage message)
                         default:
                             return SupervisionStatus.Fail; //Invalid Key Type - Ignore this
                     }
-                    CommandMessage data = new CommandMessage(controller, node.ID, EndPoint, CommandClass, (byte)Security2Command.NetworkKeyReport, false, resp);
+                    CommandMessage data = new CommandMessage(controller, [node.ID], EndPoint, CommandClass, (byte)Security2Command.NetworkKeyReport, false, resp);
                     await Transmit(data.Payload, SecurityManager.RecordType.ECDH_TEMP).ConfigureAwait(false);
                     Log.Verbose($"Provided Network Key {key}");
                     return SupervisionStatus.Success;
                 case Security2Command.NetworkKeyVerify:
                     if (controller.SecurityManager == null)
                         return SupervisionStatus.Fail;
+                    if (message.IsMulticastMethod)
+                        return SupervisionStatus.Fail;
                     Log.Verbose("Network Key Verified!");
                     if (message.SecurityLevel == SecurityKey.None || (message.Flags & ReportFlags.Security) != ReportFlags.Security)
                     {
@@ -460,7 +464,7 @@ internal override async Task<SupervisionStatus> Handle(ReportMessage message)
                     }
                     Log.Information($"Revoking {message.SecurityLevel}");
                     controller.SecurityManager.RevokeKey(node.ID, SecurityManager.KeyToType(message.SecurityLevel));
-                    CommandMessage transferEnd = new CommandMessage(controller, node.ID, EndPoint, CommandClass, (byte)Security2Command.TransferEnd, false, KEY_VERIFIED);
+                    CommandMessage transferEnd = new CommandMessage(controller, [node.ID], EndPoint, CommandClass, (byte)Security2Command.TransferEnd, false, KEY_VERIFIED);
                     await Transmit(transferEnd.Payload, SecurityManager.RecordType.ECDH_TEMP);
                     return SupervisionStatus.Success;
                 case Security2Command.NonceGet:
@@ -534,6 +538,8 @@ internal override async Task<SupervisionStatus> Handle(ReportMessage message)
                     bootstrapComplete.TrySetResult();
                     return SupervisionStatus.Success;
                 case Security2Command.KEXFail:
+                    if (message.IsMulticastMethod)
+                        return SupervisionStatus.Fail;
                     ErrorReport errorMessage = new ErrorReport(message.Payload.Span[0], ((KexFailType)message.Payload.Span[0]).ToString());
                     Log.Error("Key Exchange Failure " +  errorMessage);
                     await FireEvent(SecurityError, errorMessage);

ZWaveDotNet/CommandClasses/TransportService.cs

@@ -81,8 +81,8 @@ internal static async Task<bool> Transmit (DataMessage message, CancellationToke
             bool success = true;
             for (int i = 0; i < message.Data.Count; i += MAX_SEGMENT)
             {
-                DataMessage segment = new DataMessage(message.controller, message.DestinationNodeID, message.Data.GetRange(i, Math.Min(message.Data.Count, i + MAX_SEGMENT) - i), true, (message.Options & TransmitOptions.ExploreNPDUs) == TransmitOptions.ExploreNPDUs);
-                success &= await message.controller.Nodes[message.SourceNodeID].GetCommandClass<TransportService>()!.TransmitSegment(segment, sessionId, i, message.Data.Count, token);
+                DataMessage segment = new DataMessage(message.Controller, message.DestinationNodeID, message.Data.GetRange(i, Math.Min(message.Data.Count, i + MAX_SEGMENT) - i), true, (message.Options & TransmitOptions.ExploreNPDUs) == TransmitOptions.ExploreNPDUs);
+                success &= await message.Controller.Nodes[message.SourceNodeID].GetCommandClass<TransportService>()!.TransmitSegment(segment, sessionId, i, message.Data.Count, token);
             }
             return success;
         }
@@ -231,8 +231,8 @@ internal override async Task<SupervisionStatus> Handle(ReportMessage msg)
                         int offset = ((0x7 & msg.Payload.Span[0] << 8) | msg.Payload.Span[1]);
                         Log.Information("Retransmitting segment " + offset + " for session " + (msg.Payload.Span[0] >> 4));
 
-                        DataMessage segment = new DataMessage(message.controller, message.DestinationNodeID, message.Data.GetRange(offset, Math.Min(message.Data.Count, offset + MAX_SEGMENT) - offset), true, (message.Options & TransmitOptions.ExploreNPDUs) == TransmitOptions.ExploreNPDUs);
-                        await message.controller.Nodes[message.SourceNodeID].GetCommandClass<TransportService>()!.TransmitSegment(segment, (byte)(msg.Payload.Span[0] >> 4), offset, message.Data.Count);
+                        DataMessage segment = new DataMessage(message.Controller, message.DestinationNodeID, message.Data.GetRange(offset, Math.Min(message.Data.Count, offset + MAX_SEGMENT) - offset), true, (message.Options & TransmitOptions.ExploreNPDUs) == TransmitOptions.ExploreNPDUs);
+                        await message.Controller.Nodes[message.SourceNodeID].GetCommandClass<TransportService>()!.TransmitSegment(segment, (byte)(msg.Payload.Span[0] >> 4), offset, message.Data.Count);
                     }
                     break;
             }

ZWaveDotNet/Entities/Controller.cs

@@ -104,6 +104,7 @@ public class Controller : IDisposable
         private readonly List<Memory<byte>> provisionList = new List<Memory<byte>>();
         private static readonly SemaphoreSlim nodeListLock = new SemaphoreSlim(1, 1);
         private CancellationTokenSource running = new CancellationTokenSource();
+        private volatile byte GroupID = 1;
 
         /// <summary>
         /// Create a new controller for the given serial port
@@ -800,6 +801,22 @@ public async Task<bool> RemoveFailedNode(ushort nodeId, CancellationToken cancel
             return (int)dc.Status == 0x1;
         }
 
+        /// <summary>
+        /// Create a Node Group which supports Multicast Commands to all members
+        /// </summary>
+        /// <param name="nodes"></param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentException"></exception>
+        public NodeGroup CreateGroup(params Node[] nodes)
+        {
+            if (nodes == null || nodes.Length == 0)
+                throw new ArgumentException("Cannot create a group without members");
+            NodeGroup group = new NodeGroup(GroupID++, this, nodes[0]);
+            for (int i = 1; i < nodes.Length; i++)
+                group.AddNode(nodes[i]);
+            return group;
+        }
+
         private async Task<bool> BootstrapUnsecure(Node node)
         {
             await Task.Delay(1000); //Give including node a chance to get ready