Updates

Author: gsteve88

articles/iot-hub/how-to-module-twins.md

@@ -22,16 +22,16 @@ ms.custom: mqtt, devx-track-csharp, devx-track-dotnet
 This article shows you how to develop two types of applications:
 
 * Device apps that view and update reported properties and handle requests to update module desired properties.
-* Service apps that can add modules and read and set new desired properties.
+* Service apps that can add modules, and read and set desired properties.
 
 > [!NOTE]
 > This article is meant to complement [Azure IoT SDKs](iot-hub-devguide-sdks.md) samples that are referenced from within this article. You can use SDK tools to build both device and back-end applications.
 
 ## Prerequisites
 
-* **An IoT hub**. Some SDK calls require the IoT Hub primary connection string, so make a note of the connection string.
-
-* **A registered device**. Some SDK calls require the device primary connection string, so make a note of the connection string.
+* An IoT hub
+* An IoT hub device
+* An IoT hub device module identity
 
 * If your application uses the MQTT protocol, make sure that **port 8883** is open in your firewall. The MQTT protocol communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see [Connecting to IoT Hub (MQTT)](../iot/iot-mqtt-connect-to-iot-hub.md#connecting-to-iot-hub).
 

includes/iot-hub-howto-module-twins-dotnet.md

@@ -42,10 +42,13 @@ using Microsoft.Azure.Devices.Shared;
 
 The [ModuleClient](/dotnet/api/microsoft.azure.devices.client.moduleclient) class exposes all the methods required to interact with module identity twins from the device.
 
-Connect to the device using the [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.client.moduleclient.createfromconnectionstring) method with the module connection string. `CreateFromConnectionString` connects using the default AMQP transport.
+Connect to the device using the [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.client.moduleclient.createfromconnectionstring) method with the module connection string.
+For example:
+
+Calling `CreateFromConnectionString` without a transport parameter connects using the default AMQP transport.
 
 ```csharp
-static string ModuleConnectionString = "{Device module connection string}";
+static string ModuleConnectionString = "{Device module identity connection string}";
 private static ModuleClient _moduleClient = null;
 
 _moduleClient = ModuleClient.CreateFromConnectionString(ModuleConnectionString, 
@@ -128,7 +131,10 @@ private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredPropertie
 
 ### SDK module sample
 
-The Azure IoT SDK for .NET provides a working sample of a device app that handles module identity twin tasks. For more information, see [TwinSample](https://github.com/Azure/azure-iot-sdk-csharp/tree/main/iothub/device/samples/getting%20started/TwinSample).
+The Azure IoT SDK for .NET provides working samples of device apps that handle module identity twin tasks. For more information, see:
+
+* [TwinSample](https://github.com/Azure/azure-iot-sdk-csharp/tree/main/iothub/device/samples/getting%20started/TwinSample)
+* [Device Client Tests](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/iothub/device/tests/DeviceClientTests.cs)
 
 ## Create a backend application
 
@@ -163,6 +169,8 @@ The SDK methods in this section require these shared access policy permissions:
 
 As a parameter to `CreateFromConnectionString`, supply a shared access policy connection string that includes these permissions. For more information about shared access policies, see [Control access to IoT Hub with shared access signatures](/azure/iot-hub/authenticate-authorize-sas).
 
+For example:
+
 ```csharp
 static RegistryManager registryManager;
 static string connectionString = "{IoT hub shared access policy connection string}";
@@ -199,7 +207,7 @@ Console.WriteLine("Generated module key: {0}", module.Authentication.SymmetricKe
 
  Call [GetModuleAsync](/dotnet/api/microsoft.azure.devices.registrymanager.getmoduleasync) to retrieve current module identity twin fields into a [Module](/dotnet/api/microsoft.azure.devices.module) object.
 
-The `Module` class includes [properties](/dotnet/api/microsoft.azure.devices.shared.twin?&#properties) that correspond to sections of an identity module twin. Use the `Module` class properties to view and update module identity twin fields. You can use the `Module` object properties to update multiple fields before writing the updates to the device using `UpdateModuleAsync`.
+The `Module` class includes `properties` that correspond to sections of an identity module twin. Use the Module class properties to view and update module identity twin fields. You can use the `Module` object properties to update multiple fields before writing the updates to the device using `UpdateModuleAsync`.
 
 After making module identity twin field updates, call [UpdateModuleAsync](/dotnet/api/microsoft.azure.devices.registrymanager.updatemoduleasync) to write `Module` object field updates back to a device. Use `try` and `catch` logic coupled with an error handler to catch incorrectly formatted patch errors from `UpdateModuleAsync`.
 

includes/iot-hub-howto-module-twins-node.md

@@ -7,7 +7,7 @@ ms.author: kgremban
 ms.service: iot-hub
 ms.devlang: nodejs
 ms.topic: include
-ms.date: 09/03/2024
+ms.date: 10/02/2024
 ms.custom: mqtt, devx-track-js
 ---
 
@@ -22,8 +22,8 @@ Device applications can read and write module identity twin reported properties,
 This section describes how to use the [azure-iot-device](/javascript/api/azure-iot-device) package in the Azure IoT SDK for Node.js to create a device application to:
 
 * Retrieve a module identity twin and examine reported properties
-* Update reported module identity twin properties
-* Receive notice of module desired property changes
+* Update module identity reported twin properties
+* Receive notice of module identity twin desired property changes
 
 ### Install SDK packages
 
@@ -55,19 +55,19 @@ npm install azure-iot-device-amqp --save
 
 For more information about the differences between MQTT, AMQP, and HTTPS support, see [Cloud-to-device communications guidance](../articles/iot-hub/iot-hub-devguide-c2d-guidance.md) and [Choose a communication protocol](../articles/iot-hub/iot-hub-devguide-protocols.md).
 
-### Create a client module
+### Create a client object
 
-Create a `Client` module using the installed package.
+Create a `Client` object using the installed package.
 
 For example:
 
 ```javascript
 const Client = require('azure-iot-device').Client;
 ```
 
-### Create a protocol module
+### Create a protocol object
 
-Create a `Protocol` module using an installed transport package.
+Create a `Protocol` object using an installed transport package.
 
 This example assigns the AMQP protocol:
 
@@ -86,29 +86,32 @@ Call [fromConnectionString](/javascript/api/azure-iot-device/client?#azure-iot-d
 This example uses the `Amqp` transport protocol:
 
 ```javascript
-const deviceConnectionString = "{IoT hub module connection string}"
+const deviceConnectionString = "{IoT hub identity module connection string}"
 const Protocol = require('azure-iot-device-mqtt').Amqp;
 let client = Client.fromConnectionString(deviceConnectionString, Protocol);
 ```
 
 ### Open the connection to IoT Hub
 
-Use the [open](/javascript/api/azure-iot-device/client?#azure-iot-device-client-open) method to open a connection between an IoT device and IoT Hub.
-Use `.catch(err)` to catch an error and execute handler code.
+Use the [open](/javascript/api/azure-iot-device/client?#azure-iot-device-client-open) method to open connection between an IoT device and IoT Hub.
 
 For example:
 
 ```javascript
-client.open()  //open the connection
-.catch((err) => {
-  console.error('Could not connect: ' + err.message);
-});
+client.open(function(err) {
+  if (err) {
+    console.error('error connecting to hub: ' + err);
+    process.exit(1);
+  }
+})
 ```
 
 ### Retrieve a module identity twin and examine reported properties
 
 Call [getTwin](/javascript/api/azure-iot-device/client?#azure-iot-device-client-gettwin-1) to retrieve current module identity twin information into a [Twin](/javascript/api/azure-iot-device/twin) object.
 
+Device code can then access the twin properties.
+
 For example:
 
 ```javascript
@@ -122,7 +125,7 @@ console.log('twin contents:');
 console.log(twin.properties);
 ```
 
-### Update reported module identity twin properties
+### Update module identity twin reported properties
 
 Use [update](/javascript/api/azure-iothub/twin?#azure-iothub-twin-update) to update device reported properties. Include a JSON-formatted patch as the first parameter and function execution status callback method as the second parameter to the method.
 
@@ -154,11 +157,11 @@ twin.properties.reported.update(patch, function(err)
   });
 ```
 
-### Receive notice of desired property changes
+### Receive notice of module identity twin desired property changes
 
-Create a desired property update event listener that executes when a desired property is changed in the device by passing the callback handler method name to [twin.on](/javascript/api/azure-iot-device/twin?#azure-iot-device-twin-on).
+Create a module identity twin desired property update event listener that executes when a desired property is changed by passing the callback handler method name to [twin.on](/javascript/api/azure-iot-device/twin?#azure-iot-device-twin-on).
 
-The desired property event listener can take one of the following forms:
+The desired property event listener can take the following forms:
 
 * Receive all patches with a single event handler
 * Receive an event if anything changes under a properties grouping
@@ -237,22 +240,71 @@ You can set up a listener for a single property change. In this example, the cod
       });
     ```
 
+#### Complete example
+
+This example encapsulates the principles of this section, including callback funcation nesting.
+
+```javascript
+var Client = require('azure-iot-device').Client;
+var Protocol = require('azure-iot-device-amqp').Amqp;
+// Copy/paste your module connection string here.
+var connectionString = 'HostName=xxx.azure-devices.net;DeviceId=myFirstDevice2;ModuleId=myFirstModule2;SharedAccessKey=xxxxxxxxxxxxxxxxxx';
+// Create a client using the Amqp protocol.
+var client = Client.fromConnectionString(connectionString, Protocol);
+client.on('error', function (err) {
+  console.error(err.message);
+});
+// connect to the hub
+client.open(function(err) {
+  if (err) {
+    console.error('error connecting to hub: ' + err);
+    process.exit(1);
+  }
+  console.log('client opened');
+// Create device Twin
+  client.getTwin(function(err, twin) {
+    if (err) {
+      console.error('error getting twin: ' + err);
+      process.exit(1);
+    }
+    // Output the current properties
+    console.log('twin contents:');
+    console.log(twin.properties);
+    // Add a handler for desired property changes
+    twin.on('properties.desired', function(delta) {
+        console.log('new desired properties received:');
+        console.log(JSON.stringify(delta));
+    });
+    // create a patch to send to the hub
+    var patch = {
+      updateTime: new Date().toString(),
+      firmwareVersion:'1.2.1',
+      weather:{
+        temperature: 75,
+        humidity: 20
+      }
+    };
+    // send the patch
+    twin.properties.reported.update(patch, function(err) {
+      if (err) throw err;
+      console.log('twin state reported');
+    });
+
+  });
+});
+```
+
 ### Device SDK samples
 
-The Azure IoT SDK for Node.js provides working samples of a service app that handles module identity twin tasks. For more information, see:
+The Azure IoT SDK for Node.js provides working samples of a device apps that handle module identity twin tasks. For more information, see:
 
 * [Module Identity Twin](https://github.com/Azure/azure-iot-sdk-node/blob/main/e2etests/test/module_twin.js)
 * [Module Test Helper](https://github.com/Azure/azure-iot-sdk-node/blob/main/e2etests/test/module_test_helper.js)
 * [Twin e2e tests](https://github.com/Azure/azure-iot-sdk-node/blob/main/e2etests/test/twin_e2e_tests.js)
 
 ## Create a backend application
 
-A backend application connects to a device through IoT Hub and can read and write device desired properties.
-
-This section describes how to create a backend application that:
-
-* Creates a module
-* Retrieve a module identity twin and update desired properties
+This section describes how to create a backend application that retrieves a module identity twin and update desired properties.
 
 ### Install service SDK packages
 
@@ -262,6 +314,8 @@ Run this command to install **azure-iothub** on your development machine:
 npm install azure-iothub --save
 ```
 
+### Create a Registry object
+
 The [Registry](/javascript/api/azure-iothub/registry) class exposes all methods required to interact with module identity twins from a backend application.
 
 ### Connect to IoT hub
@@ -276,70 +330,60 @@ The SDK methods in this section require these shared access policy permissions:
 As a parameter to `CreateFromConnectionString`, supply a shared access policy connection string that includes these permissions. For more information about shared access policies, see [Control access to IoT Hub with shared access signatures](/azure/iot-hub/authenticate-authorize-sas).
 
 ```javascript
-var iothub = require('azure-iothub');
-var connectionString = '{IoT hub shared access policy connection string}';
-var registry = iothub.Registry.fromConnectionString(connectionString);
-```
-
-### Create a module
-
-Call [addModule](/javascript/api/azure-iothub/registry?#azure-iothub-registry-addmodule-1) to add a module to a device.
-
-For example:
-
-```javascript
-// Add a module to a device
-var deviceId = 'myFirstDevice';
-var moduleId = 'myFirstModule';
-registry.addModule({ deviceId: deviceId, moduleId: moduleId }, function(err) {
-  if (err) {
-    console.log('Error creating module identity: ' + err);
-    process.exit(1);
-  }
+let Registry = require('azure-iothub').Registry;
+let connectionString = '{IoT hub shared access policy connection string}';
+let registry = Registry.fromConnectionString(serviceConnectionString);
 ```
 
 ### Retrieve a module identity twin and update desired properties
 
-You can create a patch that contains tag and desired property updates for a module identity twin.
+You can create a patch that contains desired property updates for a module identity twin.
 
 To update a module identity twin:
 
 1. Call [getModuleTwin](/javascript/api/azure-iothub/registry?#azure-iothub-registry-getmoduletwin-1) to retrieve the device [Twin](/javascript/api/azure-iothub/twin) object.
 
-1. Format a patch that contains the module identity twin update. The patch is formatted in JSON as described in [Twin class](/javascript/api/azure-iothub/twin). A backend service patch can contain tag and desired property updates. For more patch format information, see [Tags and properties format](/azure/iot-hub/iot-hub-devguide-device-twins#tags-and-properties-format).
+1. Format a patch that contains the module identity twin update. The patch is formatted in JSON as described in [Twin class](/javascript/api/azure-iothub/twin). A backend service patch contains desired property updates. For more patch format information, see [Tags and properties format](/azure/iot-hub/iot-hub-devguide-device-twins#tags-and-properties-format).
 
 1. Call [updateModuleTwin](/javascript/api/azure-iothub/registry?&#azure-iothub-registry-updatemoduletwin-1) to update the module identity twin with the patch.
 
 In this example, the module identity twin is retrieved for `myDeviceId` and `myModuleId`. Then a patch is applied to the twins that contains `updateTime`, `firmwareVersion`, and `weather` information.
 
 ```javascript
-registry.getModuleTwin('myDeviceId', 'myModuleId', function(err, twin){
-    if (err) {
-        console.error(err.constructor.name + ': ' + err.message);
-    } else {
-        var patch = {
-          updateTime: new Date().toString(),
-          firmwareVersion:'1.2.0',
-          weather:{
-            temperature: 75,
-            humidity: 23
-          }
-        };
-
-        twin.updateModuleTwin('myDeviceId', 'myModuleId', patch, twin.etag,function(err) {
-          if (err) {
-            console.error('Could not update twin: ' + err.constructor.name + ': ' + err.message);
-          } else {
-            console.log(twin.deviceId + ' twin updated successfully');
-          }
-        });
-    }
+// Insert your device ID and moduleId here.
+var deviceId = 'myFirstDevice2';
+var moduleId = 'myFirstModule2';
+
+// Retrieve the current module identity twin
+registry.getModuleTwin(deviceId, moduleId, function (err, twin) {
+  console.log('getModuleTwin returned ' + (err ? err : 'success'));
+  if (err) {
+    console.log(err);
+  } else {
+    console.log('success');
+    console.log('Current twin:' + JSON.stringify(twin))
+
+    // Format a desired property patch
+    const twinPatch1 = {
+      properties: {
+        desired: {
+          climate: { minTemperature: 69, maxTemperature: 77, },
+        },
+      },
+    };
+
+    // Send the desired property patch to IoT Hub
+    twin.update(twinPatch1, function(err) {
+    if (err) throw err;
+    console.log('twin state reported');
+    });
+  }
 });
 ```
 
 ### Service SDK samples
 
-The Azure IoT SDK for Node.js provides working samples of a service app that handles module identity twin tasks. For more information, see:
+The Azure IoT SDK for Node.js provides working samples of service apps that handle module identity twin tasks. For more information, see:
 
 * [Module Identity Twin](https://github.com/Azure/azure-iot-sdk-node/blob/main/e2etests/test/module_twin.js)
 * [Module Test Helper](https://github.com/Azure/azure-iot-sdk-node/blob/main/e2etests/test/module_test_helper.js)