Merge branch 'howto-device-twins' into patch-2

Author: kgremban

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

@@ -33,9 +33,9 @@ This article shows you how to develop two types of applications. Device apps can
 
 ## Prerequisites
 
-* **An IoT hub**. Create one using the [Azure portal, CLI, or PowerShell](create-hub.md).
+* **An IoT hub**. Some SDK calls require the IoT Hub primary connection string, so make a note of the connection string.
 
-* **A registered device**. Register one in the [Azure portal](create-connect-device.md).
+* **A registered device**. Some SDK calls require the device primary connection string, so make a note of the connection string.
 
 * 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).
 
@@ -59,6 +59,12 @@ This article shows you how to develop two types of applications. Device apps can
 
   For more information about IoT Hub shared access policies and permissions, see [Access control and permissions](/azure/iot-hub/authenticate-authorize-sas).
 
+* Language SDK requirements:
+  * **.NET SDK** - Requres Visual Studio.
+  * **Python SDK** - [Python version 3.7 or later](https://www.python.org/downloads/) is recommended. Make sure to use the 32-bit or 64-bit installation as required by your setup. When prompted during the installation, make sure to add Python to your platform-specific environment variable.
+  * **Java** - [Java SE Development Kit 8](/azure/developer/java/fundamentals/) is required to use the SDK. Make sure you select **Java 8** under **Long-term support** to navigate to downloads for JDK 8.
+  * **Node.js** - Node.js version 10.0.x or later is required to use the SDK.
+
 :::zone pivot="programming-language-csharp"
 
 [!INCLUDE [iot-hub-howto-device-twins-dotnet](../../includes/iot-hub-howto-device-twins-dotnet.md)]

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

@@ -13,9 +13,7 @@ ms.custom: mqtt, devx-track-csharp, devx-track-dotnet
 
 ## Overview
 
-This unit describes how to use the Azure SDK for .NET to create device and backend service application code for device twins.
-
-Visual Studio is required to use the SDK.
+This article describes how to use the [Azure IoT SDK for .NET](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/readme.md) to create device and backend service application code for device twins.
 
 ## Create a device application
 
@@ -29,21 +27,24 @@ This section describes how to use device application code to:
 
 ### Add device NuGet Package
 
-Device client applications require the **Microsoft.Azure.Devices.Client** NuGet package.
-
-To install the **Microsoft.Azure.Devices.Client** NuGet package:
-
-1. In your application **Solution Explorer**, right-click your project, and then select **Manage NuGet Packages**.
-1. Select **Browse** and search for and choose **Microsoft.Azure.Devices.Client**.
-1. Select **Install**. This downloads, installs, and adds a reference to the Azure IoT device SDK NuGet package and its dependencies.
+Device client applications written in C# require the **Microsoft.Azure.Devices.Client** NuGet package.
 
 ### Connect to a device
 
-The [DeviceClient](/dotnet/api/microsoft.azure.devices.client.deviceclient) class exposes all the methods you require to interact with device twins from the device.
+The [DeviceClient](/dotnet/api/microsoft.azure.devices.client.deviceclient) class exposes all the methods required to interact with device twins from the device.
 
 Connect to the device using the [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.client.deviceclient.createfromconnectionstring?#microsoft-azure-devices-client-deviceclient-createfromconnectionstring(system-string)) method along with device connection string and the connection transport protocol.
 
-The `CreateFromConnectionString` [TransportType](/dotnet/api/microsoft.azure.devices.client.transporttype) transport protocol parameter supports `Mqtt`, `Mqtt_WebSocket_Only`, `Mqtt_Tcp_Only`, `Amqp`, `Amqp_WebSocket_Only`, and `Amqp_Tcp_Only`. `Http1` is not supported for device twin updates.
+The `CreateFromConnectionString` [TransportType](/dotnet/api/microsoft.azure.devices.client.transporttype) transport protocol parameter supports the following transport protocols:
+
+* `Mqtt`
+* `Mqtt_WebSocket_Only`
+* `Mqtt_Tcp_Only`
+* `Amqp`
+* `Amqp_WebSocket_Only`
+* `Amqp_Tcp_Only`
+
+The `Http1` protocol is not supported for device twin updates.
 
 This example connects to a device using the `Mqtt` transport protocol.
 
@@ -58,11 +59,11 @@ _deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString,
    TransportType.Mqtt);
 ```
 
-### Retrieve a device twin and examine reported properties
+### Retrieve a device twin and examine properties
 
- Call [GetTwinAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.gettwinasync?#microsoft-azure-devices-client-deviceclient-gettwinasync) to retrieve the current device twin properties. The result [Twin](/dotnet/api/microsoft.azure.devices.shared.twin?) object includes the device twin reported properties. There are many `Twin` object [properties](/dotnet/api/microsoft.azure.devices.shared.twin?&branch=main#properties) that you can use to access specific areas of the Twin JSON data including Twin `Properties`, `Status`, `Tags`, and `Version`.
+Call [GetTwinAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.gettwinasync?#microsoft-azure-devices-client-deviceclient-gettwinasync) to retrieve the current device twin properties. There are many [Twin](/dotnet/api/microsoft.azure.devices.shared.twin?) object [properties](/dotnet/api/microsoft.azure.devices.shared.twin?&branch=main#properties) that you can use to access specific areas of the Twin JSON data including Twin `Properties`, `Status`, `Tags`, and `Version`.
 
- This example retrieves device twin reported properties and prints the twin values in JSON format.
+ This example retrieves device twin properties and prints the twin values in JSON format.
 
 ```csharp
 Console.WriteLine("Retrieving twin...");
@@ -98,7 +99,7 @@ catch (Exception ex)
 
 ### Create a desired property update callback handler
 
-You can create a desired property update callback handler that executes when a desired property is changed in the device by passing the callback handler method name to [SetDesiredPropertyUpdateCallbackAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.setdesiredpropertyupdatecallbackasync?#microsoft-azure-devices-client-deviceclient-setdesiredpropertyupdatecallbackasync(microsoft-azure-devices-client-desiredpropertyupdatecallback-system-object)).
+Create a desired property update callback handler that executes when a desired property is changed in the device twin by passing the callback handler method name to [SetDesiredPropertyUpdateCallbackAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.setdesiredpropertyupdatecallbackasync?#microsoft-azure-devices-client-deviceclient-setdesiredpropertyupdatecallbackasync(microsoft-azure-devices-client-desiredpropertyupdatecallback-system-object)).
 
 For example, this call sets up the system to notify a method named`OnDesiredPropertyChangedAsync` whenever a desired property is changed.
 
@@ -134,7 +135,7 @@ private async Task OnDesiredPropertyChangedAsync(TwinCollection desiredPropertie
 
 ### SDK sample
 
-The SDK includes this [TwinSample](https://github.com/Azure/azure-iot-sdk-csharp/tree/main/iothub/device/samples/getting%20started/TwinSample).
+The Azure IoT SDK for .NET provides a working sample of a device app that handles device twin tasks. For more information, see [TwinSample](https://github.com/Azure/azure-iot-sdk-csharp/tree/main/iothub/device/samples/getting%20started/TwinSample).
 
 ## Create a backend application
 
@@ -154,15 +155,9 @@ This section describes how to create backend application code to:
 
 Backend service applications require the **Microsoft.Azure.Devices** NuGet package.
 
-To install the **Microsoft.Azure.Devices** NuGet package:
-
-1. In your application **Solution Explorer**, right-click your project, and then select **Manage NuGet Packages**.
-1. Select **Browse** and search for and choose **Microsoft.Azure.Devices**.
-1. Select **Install**. This downloads, installs, and adds a reference to the Azure IoT device SDK NuGet package and its dependencies.
-
 ### Connect to IoT hub
 
-Connect a backend application to a device using [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.client.deviceclient.createfromconnectionstring?#microsoft-azure-devices-client-deviceclient-createfromconnectionstring(system-string-microsoft-azure-devices-client-transporttype)). As a parameter, supply the **IoT Hub service connection string** that you created in the Prerequisites section.
+Connect a backend application to a device using [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.registrymanager.createfromconnectionstring). As a parameter, supply the **IoT Hub service connection string** that you created in the prerequisites section.
 
 ```csharp
 using Microsoft.Azure.Devices;
@@ -216,7 +211,7 @@ catch (Exception e)
 }
 ```
 
-##### Update using a JSON string
+##### Update tags using a JSON string
 
 You can create and apply a JSON-formatted device twin information update patch. IoT Hub parses and applies the patch if it is correctly formatted.
 

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

@@ -13,9 +13,7 @@ ms.custom: mqtt, devx-track-java, devx-track-extended-java
 
 ## Overview
 
-This unit describes how to use the Azure SDK for Java to create device and backend service application code for device twins.
-
-[Java SE Development Kit 8](/azure/developer/java/fundamentals/) is required to use the SDK. Make sure you select **Java 8** under **Long-term support** to navigate to downloads for JDK 8.
+This article describes how to use the [Azure IoT SDK for Java](https://github.com/Azure/azure-iot-sdk-java) to create device and backend service application code for device twins.
 
 ## Create a device application
 
@@ -29,9 +27,9 @@ This section describes how to create device application code to:
 
 The [DeviceClient](/java/api/com.microsoft.azure.sdk.iot.device.deviceclient) class exposes all the methods you require to interact with device twins from the device.
 
-### Import statements
+### Device import statements
 
-Use the following import statements to access the IoT Hub device SDK.
+Use the following device import statements to access the Azure IoT SDK for Java.
 
 ```java
 import com.microsoft.azure.sdk.iot.device.*;
@@ -75,7 +73,7 @@ System.out.println("Received current twin:");
 System.out.println(twin);
 ```
 
-### Update reported device twin properties
+### Update device twin reported properties
 
 After retrieving the current twin, you can begin making reported property updates. You can also make reported property updates without getting the current twin as long as you have the correct reported properties version. If you send reported properties and receive a "precondition failed" error, then your reported properties version is out of date. In that case, get the latest version by calling `getTwin` again.
 
@@ -102,7 +100,7 @@ System.out.println("Successfully set property \"HomeTemp(F)\" to value " + newTe
 
 ### 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 receives a callback with a `Twin` object each time a desired property is updated. That callback either contains the full desired properties set, or only the updated desired property depending on how the desired property was changed.
+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 property changes. This client receives a callback with a `Twin` object each time a desired property is updated. That callback either contains the full desired properties set, or only the updated desired property depending on how the desired property was changed.
 
 This example subscribes to desired property changes. Any desired property changes are passed to a handler named `DesiredPropertiesUpdatedHandler`.
 
@@ -136,22 +134,26 @@ In this example, the `DesiredPropertiesUpdatedHandler` desired property change c
 
 ### 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).
+The Azure IoT SDK for Java includes a working sample to test the device app concepts described in this article. For more information, see  [Device Twin Sample](https://github.com/Azure/azure-iot-sdk-java/tree/main/iothub/device/iot-device-samples/device-twin-sample).
 
 ## Create a backend application
 
-A backend application:
-
-* Connects to a device through IoT Hub
-* Can read device reported and desired properties, write device desired properties, and run device queries
-
 This section describes how to create a backend application that:
 
 * Updates device twin tags
 * Queries devices using filters on the tags and properties
 
 The `ServiceClient` [DeviceTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin) class contains methods that services can use to access device twins.
 
+### Service import statements
+
+Use the following service import statements to access the Azure IoT SDK for Java.
+
+```java
+import com.microsoft.azure.sdk.iot.service.devicetwin.*;
+import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;
+```
+
 ### Connect to the IoT hub service client
 
 To connect to IoT Hub to view and update device twin information:
@@ -163,13 +165,6 @@ To connect to IoT Hub to view and update device twin information:
 For example:
 
 ```java
-import com.microsoft.azure.sdk.iot.service.devicetwin.*;
-import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;
-
-import java.io.IOException;
-import java.util.HashSet;
-import java.util.Set;
-
 public static final String iotHubConnectionString = "{IoT hub service connection string}";
 public static final String deviceId = "myDeviceId";
 public static final String region = "US";