Updates

Author: gsteve88

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

@@ -13,7 +13,7 @@ zone_pivot_groups: iot-hub-howto-c2d-1
 ms.custom: mqtt, devx-track-csharp, devx-track-dotnet
 ---
 
-# Get started with device twins
+## Get started with device twins
 
 Device twins are JSON documents that store device state information, including metadata, configurations, and conditions. IoT Hub persists a device twin for each device that connects to it.
 
@@ -72,7 +72,7 @@ This article is meant to complement runnable SDK samples that are referenced fro
 
 * Make sure that port 8883 is open in your firewall. The device sample in this article uses MQTT protocol, which 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).
 
-## IoT Hub service connection string
+## Get the IoT Hub service connection string
 
 In this article, you create a back-end service that adds desired properties to a device twin and then queries the identity registry to find all devices with reported properties that have been updated accordingly. Your service needs the **service connect** permission to modify desired properties of a device twin, and it needs the **registry read** permission to query the identity registry. There is no default shared access policy that contains only these two permissions, so you need to create one.
 

includes/iot-hub-howto-device-twins-java.md

@@ -90,6 +90,40 @@ ReportedPropertiesUpdateResponse response = client.updateReportedProperties(repo
 System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTemperature);
 ```
 
+### Subscribe to desired property changes
+
+Call [subscribeToDesiredProperties](/java/api/com.microsoft.azure.sdk.iot.device.internalclient?#com-microsoft-azure-sdk-iot-device-internalclient-subscribetodesiredproperties(java-util-map(com-microsoft-azure-sdk-iot-device-devicetwin-property-com-microsoft-azure-sdk-iot-device-devicetwin-pair(com-microsoft-azure-sdk-iot-device-devicetwin-propertycallback(java-lang-string-java-lang-object)-java-lang-object)))) to subscribe to desired properties. This client will receive a callback each time a desired property is updated. That callback will either contain the full desired properties set, or only the updated desired property depending on how the desired property was changed.
+
+This example subscribes to desired propery changes. Any desired property changes will be passed to a handler named `DesiredPropertiesUpdatedHandler`.
+
+```java
+client.subscribeToDesiredProperties(new DesiredPropertiesUpdatedHandler(), null);
+```
+
+In this example, the `DesiredPropertiesUpdatedHandler` desired property change callback handler calls [getDesiredProperties](https://learn.microsoft.com/en-us/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwindevice?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwindevice-getdesiredproperties()) to retrieve the property changes, then prints out the updated twin properties.
+
+```java
+  private static class DesiredPropertiesUpdatedHandler implements DesiredPropertiesCallback
+  {
+      @Override
+      public void onDesiredPropertiesUpdated(Twin desiredPropertyUpdateTwin, Object context)
+      {
+          if (twin == null)
+          {
+              // No need to care about this update because these properties will be present in the twin retrieved by getTwin.
+              System.out.println("Received desired properties update before getting current twin. Ignoring this update.");
+              return;
+          }
+
+          // desiredPropertyUpdateTwin.getDesiredProperties() contains all the newly updated desired properties as well as the new version of the desired properties
+          twin.getDesiredProperties().putAll(desiredPropertyUpdateTwin.getDesiredProperties());
+          twin.getDesiredProperties().setVersion(desiredPropertyUpdateTwin.getDesiredProperties().getVersion());
+          System.out.println("Received desired property update. Current twin:");
+          System.out.println(twin);
+      }
+  }
+```
+
 ### SDK sample
 
 The SDK includes this [Device Twin Sample](https://github.com/Azure/azure-iot-sdk-java/tree/main/iothub/device/iot-device-samples/device-twin-sample).
@@ -190,13 +224,13 @@ The [Query](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.query) clas
 
 To create a device query:
 
-* Use [createSqlQuery](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.sqlquery?#com-microsoft-azure-sdk-iot-service-devicetwin-sqlquery-createsqlquery(java-lang-string-com-microsoft-azure-sdk-iot-service-devicetwin-sqlquery-fromtype-java-lang-string-java-lang-string)) to build the twins SQL query.
+1. Use [createSqlQuery](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.sqlquery?#com-microsoft-azure-sdk-iot-service-devicetwin-sqlquery-createsqlquery(java-lang-string-com-microsoft-azure-sdk-iot-service-devicetwin-sqlquery-fromtype-java-lang-string-java-lang-string)) to build the twins SQL query.
 
-* Use [queryTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwin-querytwin(java-lang-string-java-lang-integer)) to execute the query.
+1. Use [queryTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwin-querytwin(java-lang-string-java-lang-integer)) to execute the query.
 
-* Use [hasNextDeviceTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwin-hasnextdevicetwin(com-microsoft-azure-sdk-iot-service-devicetwin-query)) to check if there's another device twin in the result set.
+1. Use [hasNextDeviceTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwin-hasnextdevicetwin(com-microsoft-azure-sdk-iot-service-devicetwin-query)) to check if there's another device twin in the result set.
 
-* Use [getNextDeviceTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwin-getnextdevicetwin(com-microsoft-azure-sdk-iot-service-devicetwin-query)) to retrieve the next device twin from the result set.
+1. Use [getNextDeviceTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwin-getnextdevicetwin(com-microsoft-azure-sdk-iot-service-devicetwin-query)) to retrieve the next device twin from the result set.
 
 This example queries two IoT hub queries. Each query returns a maximum of 100 devices.
 

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

@@ -117,8 +117,88 @@ twin.properties.reported.update(patch, function(err) {
 });
 ```
 
+### Receive notice of desired property changes
+
+Use [twin.on](/javascript/api/azure-iot-device/twin?view=azure-node-latest#azure-iot-device-twin-on) to set up a desired property change event listener.
+
+The desired property event listener can take one of the following forms:
+
+#### Receive all patches with a single event handler
+
+This code will output any properties that are received from the service.
+
+```javascript
+twin.on('properties.desired', function (delta) {
+    console.log('new desired properties received:');
+    console.log(JSON.stringify(delta));
+});
+```
+
+#### Receive an event if anything changes under a properties grouping
+
+You can create code to receive an event if anything under a property grouping changes.
+
+For example:
+
+1. The `minTemperature` and `maxTemperature` properties are located under a property grouping named `properties.desired.climate changes`.
+
+1. A backend application applies this patch to update `minTemperature` and `maxTemperature` desired properties:
+
+    ```javascript
+    Example patch document for service API code:
+    const twinPatch1 = {
+    properties: {
+       desired: {
+        climate: { minTemperature: 68, maxTemperature: 76, },
+        },
+      },
+     };
+    ```
+
+1. This code sets up a desired properties change listener that triggers for any changes within the `properties.desired.climate` property grouping. If there is a desired property change within this group, min and max temp change messages will be displayed to the console:
+
+```javascript
+twin.on('properties.desired.climate', function (delta) {
+    if (delta.minTemperature || delta.maxTemperature) {
+        console.log('updating desired temp:');
+        console.log('min temp = ' + twin.properties.desired.climate.minTemperature);
+        console.log('max temp = ' + twin.properties.desired.climate.maxTemperature);
+    }
+});
+```
+
+#### Receive an event for a single property change
+
+You can set up a listener for a single property change. In this example, the code for this event is only fired if the `fanOn` boolean value is part of the patch. The code outputs the new desired fan state whenever the service updates it.
+
+In this example, a backend application applies this desired property patch:
+
+```javascript
+ const twinPatch2 = {
+  properties: {
+    desired: {
+      climate: {
+        hvac: {
+          systemControl: { fanOn: true, },
+        },
+      },
+    },
+  },
+};
+```
+
+The listener triggers only when the `fanOn` property changes:
+
+```javascript
+twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
+    console.log('setting fan state to ' + fanOn);
+});
+```
+
 ### SDK samples
 
+The SDK contains two device twin samples:
+
 * [Simple sample device twin](https://github.com/Azure/azure-iot-sdk-node/blob/main/device/samples/javascript/simple_sample_device_twin.js)
 
 * [Simple sample device twin with SAS](https://github.com/Azure/azure-iot-sdk-node/blob/main/device/samples/javascript/simple_sample_device_with_sas.js)