Add module support (#174)

* Initial commit

* adjusting auth

Co-authored-by: José Simões <[email protected]>

Author: Ellerbach

README.md

@@ -313,6 +313,20 @@ Here are existing QoS levels that you can use:
 
 While it's possible to configure QoS 0 (AtMostOnce) for faster message exchange, you should note that the delivery isn't guaranteed nor acknowledged. For this reason, QoS 0 is often referred as "fire and forget".
 
+## Module support
+
+Modules are supported, you will have to use the constructor to pass the module ID either with a SAS token, either with a certificate. The rest fully works like a normal device. Everything is fully supported including module direct method, telemetry and of course twins!
+
+For example here with a SAS token. Note that the certificates are fully supported as well. And if you are not storing the Azure root certificate on the device, you'll need to pass it in the constructor.
+
+```csharp
+const string DeviceID = "nanoEdgeTwin";
+const string ModuleID = "myModule";
+const string IotBrokerAddress = "youriothub.azure-devices.net";
+const string SasKey = "yoursaskey";
+DeviceClient module = new DeviceClient(IotBrokerAddress, DeviceID, ModuleID, SasKey);
+```
+
 ## Azure IoT Device Provisioning Service (DPS) support
 
 This SDK also supports the Azure IoT Device Provisioning Service. Group and individual provisioning scenarios are supported either with a symmetric key either with certificates. To understand the mechanism behind DPS, it is recommended to read the [documentation](https://docs.microsoft.com/azure/iot-dps/).

nanoFramework.Azure.Devices.Client/DeviceClient.cs

@@ -15,13 +15,14 @@
 namespace nanoFramework.Azure.Devices.Client
 {
     /// <summary>
-    /// Azure IoT Client SDK for .NET nanoFramework using MQTT
+    /// Azure IoT Client SDK for .NET nanoFramework using MQTT.
     /// </summary>
     public class DeviceClient : IDisposable
     {
-        const string TwinReportedPropertiesTopic = "$iothub/twin/PATCH/properties/reported/";
-        const string TwinDesiredPropertiesTopic = "$iothub/twin/GET/";
-        const string DirectMethodTopic = "$iothub/methods/POST/";
+        private const string TwinReportedPropertiesTopic = "$iothub/twin/PATCH/properties/reported/";
+        private const string TwinDesiredPropertiesTopic = "$iothub/twin/GET/";
+        private const string DirectMethodTopic = "$iothub/methods/POST/";
+        private const string ApiVersion = "2021-04-12";
 
         private readonly string _iotHubName;
         private readonly string _deviceId;
@@ -59,61 +60,120 @@ public class DeviceClient : IDisposable
         /// <summary>
         /// Creates an <see cref="DeviceClient"/> class.
         /// </summary>
-        /// <param name="iotHubName">The Azure IoT name fully qualified (ex: youriothub.azure-devices.net)</param>
+        /// <param name="iotHubName">The Azure IoT name fully qualified (ex: youriothub.azure-devices.net).</param>
         /// <param name="deviceId">The device ID which is the name of your device.</param>
+        /// <param name="moduleId">The module ID which is attached to the device ID.</param>
         /// <param name="sasKey">One of the SAS Key either primary, either secondary.</param>
-        /// <param name="qosLevel">The default quality level delivery for the MQTT messages, default to the lower quality</param>
-        /// <param name="azureCert">Azure certificate for the connection to Azure IoT Hub</param>
-        /// <param name="modelId">Azure Plug and Play model ID</param>
-        public DeviceClient(string iotHubName, string deviceId, string sasKey, MqttQoSLevel qosLevel = MqttQoSLevel.AtLeastOnce, X509Certificate azureCert = null, string modelId = null)
+        /// <param name="qosLevel">The default quality level delivery for the MQTT messages, default to the lower quality.</param>
+        /// <param name="azureCert">Azure certificate for the connection to Azure IoT Hub.</param>
+        /// <param name="modelId">Azure Plug and Play model ID.</param>
+        public DeviceClient(string iotHubName, string deviceId, string moduleId, string sasKey, MqttQoSLevel qosLevel = MqttQoSLevel.AtLeastOnce, X509Certificate azureCert = null, string modelId = null)
+
         {
             _isCertificate = false;
             _clientCert = null;
             _privateKey = null;
             _iotHubName = iotHubName;
-            _deviceId = deviceId;
+            ModelId = modelId;
+            ModuleId = moduleId;
             _sasKey = sasKey;
-            _telemetryTopic = $"devices/{_deviceId}/messages/events/";
-            _ioTHubStatus.Status = Status.Disconnected;
-            _ioTHubStatus.Message = string.Empty;
-            _deviceMessageTopic = $"devices/{_deviceId}/messages/devicebound/";
             QosLevel = qosLevel;
             _azureRootCACert = azureCert;
-            ModelId = modelId;
+
+            if (string.IsNullOrEmpty(moduleId))
+            {
+                _telemetryTopic = $"devices/{deviceId}/messages/events/";
+                _deviceId = deviceId;
+            }
+            else
+            {
+                _telemetryTopic = $"devices/{deviceId}/modules/{ModuleId}/messages/events/";
+                _deviceId = deviceId + "/" + moduleId;
+            }
+
+            _deviceMessageTopic = $"devices/{_deviceId}/messages/devicebound/";
+
+            _ioTHubStatus.Status = Status.Disconnected;
+            _ioTHubStatus.Message = string.Empty;
         }
 
         /// <summary>
         /// Creates an <see cref="DeviceClient"/> class.
         /// </summary>
         /// <param name="iotHubName">Your Azure IoT Hub fully qualified domain name (example: youriothub.azure-devices.net).</param>
         /// <param name="deviceId">The device ID (name of your device).</param>
-        /// <param name="clientCert">The certificate to connect the device (containing both public and private keys). Pass null if you are using the certificate store on the device</param>
+        /// /// <param name="moduleId">The module ID which is attached to the device ID.</param>
+        /// <param name="clientCert">The certificate to connect the device (containing both public and private keys). Pass null if you are using the certificate store on the device.</param>
         /// <param name="qosLevel">The default quality of assurance level for delivery for the MQTT messages (defaults to the lowest quality).</param>
-        /// /// <param name="azureCert">Azure certificate for the connection to Azure IoT Hub</param>
-        /// /// <param name="modelId">Azure Plug and Play model ID</param>
-        public DeviceClient(string iotHubName, string deviceId, X509Certificate2 clientCert, MqttQoSLevel qosLevel = MqttQoSLevel.AtMostOnce, X509Certificate azureCert = null, string modelId = null)
+        /// /// <param name="azureCert">Azure certificate for the connection to Azure IoT Hub.</param>
+        /// /// <param name="modelId">Azure Plug and Play model ID.</param>
+        public DeviceClient(string iotHubName, string deviceId, string moduleId, X509Certificate2 clientCert, MqttQoSLevel qosLevel = MqttQoSLevel.AtMostOnce, X509Certificate azureCert = null, string modelId = null)
         {
             _isCertificate = true;
             _clientCert = clientCert;
             // In case we are using the store, the magic should happen automaticall
             _privateKey = _clientCert != null ? Convert.ToBase64String(clientCert.PrivateKey) : null;
             _iotHubName = iotHubName;
-            _deviceId = deviceId;
-            _sasKey = null;
-            _telemetryTopic = $"devices/{_deviceId}/messages/events/";
-            _ioTHubStatus.Status = Status.Disconnected;
-            _ioTHubStatus.Message = string.Empty;
-            _deviceMessageTopic = $"devices/{_deviceId}/messages/devicebound/";
+            ModelId = modelId;
+            ModuleId = moduleId;
             QosLevel = qosLevel;
             _azureRootCACert = azureCert;
-            ModelId = modelId;
+
+            if (string.IsNullOrEmpty(moduleId))
+            {
+                _telemetryTopic = $"devices/{deviceId}/messages/events/";
+                _deviceId = deviceId;
+            }
+            else
+            {
+                _telemetryTopic = $"devices/{deviceId}/modules/{ModuleId}/messages/events/";
+                _deviceId = deviceId + "/" + moduleId;
+            }
+
+            _deviceMessageTopic = $"devices/{_deviceId}/messages/devicebound/";
+
+            _ioTHubStatus.Status = Status.Disconnected;
+            _ioTHubStatus.Message = string.Empty;
         }
 
         /// <summary>
-        /// Azure Plug and Play model ID
+        /// Creates an <see cref="DeviceClient"/> class.
+        /// </summary>
+        /// <param name="iotHubName">The Azure IoT name fully qualified (ex: youriothub.azure-devices.net).</param>
+        /// <param name="deviceId">The device ID which is the name of your device.</param>
+        /// <param name="sasKey">One of the SAS Key either primary, either secondary.</param>
+        /// <param name="qosLevel">The default quality level delivery for the MQTT messages, default to the lower quality.</param>
+        /// <param name="azureCert">Azure certificate for the connection to Azure IoT Hub.</param>
+        /// <param name="modelId">Azure Plug and Play model ID.</param>
+        public DeviceClient(string iotHubName, string deviceId, string sasKey, MqttQoSLevel qosLevel = MqttQoSLevel.AtLeastOnce, X509Certificate azureCert = null, string modelId = null)
+            : this(iotHubName, deviceId, string.Empty, sasKey, qosLevel, azureCert, modelId)
+        {
+        }
+
+        /// <summary>
+        /// Creates an <see cref="DeviceClient"/> class.
+        /// </summary>
+        /// <param name="iotHubName">Your Azure IoT Hub fully qualified domain name (example: youriothub.azure-devices.net).</param>
+        /// <param name="deviceId">The device ID (name of your device).</param>
+        /// <param name="clientCert">The certificate to connect the device (containing both public and private keys). Pass null if you are using the certificate store on the device.</param>
+        /// <param name="qosLevel">The default quality of assurance level for delivery for the MQTT messages (defaults to the lowest quality).</param>
+        /// /// <param name="azureCert">Azure certificate for the connection to Azure IoT Hub.</param>
+        /// /// <param name="modelId">Azure Plug and Play model ID.</param>
+        public DeviceClient(string iotHubName, string deviceId, X509Certificate2 clientCert, MqttQoSLevel qosLevel = MqttQoSLevel.AtMostOnce, X509Certificate azureCert = null, string modelId = null)
+             : this(iotHubName, deviceId, string.Empty, clientCert, qosLevel, azureCert, modelId)
+        {
+        }
+
+        /// <summary>
+        /// Azure Plug and Play model ID.
         /// </summary>
         public string ModelId { get; internal set; }
 
+        /// <summary>
+        /// The module ID attached to the device ID.
+        /// </summary>
+        public string ModuleId { get; internal set; }
+
         /// <summary>
         /// The latest Twin received.
         /// </summary>
@@ -137,7 +197,7 @@ public DeviceClient(string iotHubName, string deviceId, X509Certificate2 clientC
         /// <summary>
         /// Open the connection with Azure IoT. This will initiate a connection from the device to the Azure IoT Hub instance.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>True if open.</returns>
         public bool Open()
         {
             // Creates MQTT Client usinf the default port of 8883 and the TLS 1.2 protocol
@@ -156,7 +216,7 @@ public bool Open()
             // event when connection has been dropped
             _mqttc.ConnectionClosed += ClientConnectionClosed;
 
-            string userName = $"{_iotHubName}/{_deviceId}/api-version=2020-09-30";
+            string userName = $"{_iotHubName}/{_deviceId}/?api-version={ApiVersion}";
             if (!string.IsNullOrEmpty(ModelId))
             {
                 userName += $"&model-id={HttpUtility.UrlEncode(ModelId)}";
@@ -210,7 +270,7 @@ public bool Open()
         }
 
         /// <summary>
-        /// Reconnect to Azure Iot Hub
+        /// Reconnect to Azure Iot Hub.
         /// </summary>
         public void Reconnect()
         {
@@ -247,7 +307,7 @@ public void Close()
         /// <summary>
         /// Gets the twin.
         /// </summary>
-        /// <param name="cancellationToken">A cancellation token</param>
+        /// <param name="cancellationToken">A cancellation token.</param>
         /// <returns>The twin.</returns>
         /// <remarks>It is strongly recommended to use a cancellation token that can be canceled and manage this on the 
         /// caller code level. A reasonable time of few seconds is recommended with a retry mechanism.</remarks>
@@ -282,11 +342,11 @@ public bool UpdateReportedProperties(TwinCollection reported, CancellationToken
             StatusUpdated?.Invoke(this, new StatusUpdatedEventArgs(_ioTHubStatus));
 
             if (cancellationToken.CanBeCanceled)
-            {                
+            {
                 while (!conf.Received && !cancellationToken.IsCancellationRequested)
                 {
                     cancellationToken.WaitHandle.WaitOne(200, true);
-                }                
+                }
             }
 
             _waitForConfirmation.Remove(conf);
@@ -332,11 +392,11 @@ public bool SendMessage(string message, CancellationToken cancellationToken = de
             _waitForConfirmation.Add(conf);
 
             if (cancellationToken.CanBeCanceled)
-            {                
+            {
                 while (!conf.Received && !cancellationToken.IsCancellationRequested)
                 {
                     cancellationToken.WaitHandle.WaitOne(200, true);
-                }                
+                }
             }
 
             _waitForConfirmation.Remove(conf);
@@ -398,7 +458,7 @@ private void ClientMqttMsgReceived(object sender, MqttMsgPublishEventArgs e)
                     const string C9PatternMainStyle = "<<Main>$>g__";
                     string method = e.Topic.Substring(DirectMethodTopic.Length);
                     string methodName = method.Substring(0, method.IndexOf('/'));
-                    int rid = Convert.ToInt32(method.Substring(method.IndexOf('=') + 1),16);
+                    int rid = Convert.ToInt32(method.Substring(method.IndexOf('=') + 1), 16);
                     _ioTHubStatus.Status = Status.DirectMethodCalled;
                     _ioTHubStatus.Message = $"{method}/{message}";
                     StatusUpdated?.Invoke(this, new StatusUpdatedEventArgs(_ioTHubStatus));

nanoFramework.Azure.Devices.Client/SHA256.cs

@@ -7,6 +7,9 @@
 
 namespace System.Security.Cryptography
 {
+    /// <summary>
+    /// Computes the SHA256 hash for the input data.
+    /// </summary>
     public class SHA256
     {
         // Number used in SHA256 hash function 
@@ -28,6 +31,9 @@ public class SHA256
         /// <returns></returns>
         public static SHA256 Create() => new SHA256();
 
+        /// <summary>
+        /// Initializes a new instance of SHA256.
+        /// </summary>
         protected SHA256()
         { }