Updates

Author: gsteve88

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

@@ -52,7 +52,7 @@ using Microsoft.Azure.Devices.Client;
 using Microsoft.Azure.Devices.Shared;
 using Newtonsoft.Json;
 
-static string DeviceConnectionString = "{IoT Hub device connection string}";
+static string DeviceConnectionString = "{IoT hub device connection string}";
 static _deviceClient = null;
 _deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
    TransportType.Mqtt);
@@ -162,7 +162,7 @@ To install the **Microsoft.Azure.Devices** NuGet package:
 
 ### 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. The backend application connects to the device through 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.
 
 ```csharp
 using Microsoft.Azure.Devices;
@@ -177,7 +177,7 @@ You can retrieve current device twin fields into a [Twin](/dotnet/api/microsoft.
 
 The `Twin` class includes [properties](/dotnet/api/microsoft.azure.devices.shared.twin?&#properties) that correspond to each section of a device twin. Use the `Twin` class properties to view and update device twin fields. You can use the `Twin` object properties to update multiple twin fields before writing the updates to the device using `UpdateTwinAsync`.
 
-After making twin field updates, call [UpdateTwinAsync](/dotnet/api/microsoft.azure.devices.registrymanager.updatetwinasync?#microsoft-azure-devices-registrymanager-updatetwinasync(system-string-microsoft-azure-devices-shared-twin-system-string)) to write `Twin` object field updates back to a device. Use a `try` and `catch` logic coupled with an error handler to catch incorrectly formatted patch errors from `UpdateTwinAsync`.
+After making twin field updates, call [UpdateTwinAsync](/dotnet/api/microsoft.azure.devices.registrymanager.updatetwinasync?#microsoft-azure-devices-registrymanager-updatetwinasync(system-string-microsoft-azure-devices-shared-twin-system-string)) to write `Twin` object field updates back to a device. Use `try` and `catch` logic coupled with an error handler to catch incorrectly formatted patch errors from `UpdateTwinAsync`.
 
 #### Read and update device twin tags
 
@@ -205,7 +205,7 @@ var tagspatch =
 // Assign the patch to the Twin object
 twin.Tags["location"] = tagspatch;
 
-// Apply the patch to update the device twin tags
+// Apply the patch to update the device twin tags section
 try
 {
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);
@@ -218,7 +218,7 @@ catch (Exception e)
 
 ##### Update using a JSON string
 
-You can also create and apply a device twin information update patch that contains a block of field updates, including different field types such as tags mixed with desired properties. IoT Hub parses and applies the patch if it is correctly formatted and the fields are updatable. For example, device twin reported properties cannot be updated by a backend application and the patch for these fields are not be applied.
+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.
 
 This example calls `GetTwinAsync` to retrieve the current device twin fields into a `Twin` object, creates a JSON-formatted `tag` patch with region and plant location information, then calls `UpdateTwinAsync` to apply the patch to update the device twin. An error message is displayed if `UpdateTwinAsync` failed.
 
@@ -249,9 +249,9 @@ catch (Exception e)
 
 #### View and update twin desired properties
 
-Use device twin [Properties.Desired](/dotnet/api/microsoft.azure.devices.shared.twinproperties.desired?#microsoft-azure-devices-shared-twinproperties-desired) to read and write device property information. Update twin `Desired` properties using a JSON-formatted patch.
+Use device twin [TwinProperties.Desired](/dotnet/api/microsoft.azure.devices.shared.twinproperties.desired?#microsoft-azure-devices-shared-twinproperties-desired) property to read and write device property information. Update twin `Desired` properties using a JSON-formatted patch.
 
-This example calls `GetTwinAsync` to retrieve the current device twin fields into a `Twin` object, updates the twin `speed` desired property, and then calls `UpdateTwinAsync` to apply the patch to update the device twin.
+This example calls `GetTwinAsync` to retrieve the current device twin fields into a `Twin` object, updates the twin `speed` desired property, and then calls `UpdateTwinAsync` to apply the `Twin` object to update the device twin.
 
 ```csharp
 // Retrieve the device twin
@@ -265,14 +265,14 @@ await registryManager.UpdateTwinAsync(twin.DeviceId, twin, twin.ETag);
 
 You can also apply twin updates using these SDK methods:
 
-* Call [ReplaceTwinAsync](/dotnet/api/microsoft.azure.devices.registrymanager.replacetwinasync) to replace the entire device twin schema.
+* Call [ReplaceTwinAsync](/dotnet/api/microsoft.azure.devices.registrymanager.replacetwinasync) to replace the entire device twin.
 * Call [UpdateTwins2Async](/dotnet/api/microsoft.azure.devices.registrymanager.updatetwins2async) to update a list of twins previously created within the system.
 
 ### Create a device twin query
 
 This section demonstrates two device twin queries. Device twin queries are SQL-like queries that return a result set of device twins.
 
-To create a device twin query, call [CreateQuery](/dotnet/api/microsoft.azure.devices.registrymanager.createquery) to submit a digital twins SQL query and obtain an [IQuery](/dotnet/api/microsoft.azure.devices.iquery) Interface. You can optionally `CreateQuery` with a second parameter to specify a maximum number of items per page.
+To create a device twin query, call [CreateQuery](/dotnet/api/microsoft.azure.devices.registrymanager.createquery) to submit a twins SQL query and obtain an [IQuery](/dotnet/api/microsoft.azure.devices.iquery) Interface. You can optionally call `CreateQuery` with a second parameter to specify a maximum number of items per page.
 
 Next call `GetNextAsTwinAsync` or `GetNextAsJsonAsync` method as many times as needed to retrieve all twin results.
 

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

@@ -23,7 +23,7 @@ Device applications can read and write twin reported properties, and be notified
 
 This section describes how to create device application code to:
 
-* Retrieve a device twin and examine reported properties
+* Retrieve and view a device twin
 * Update reported device twin properties
 * Subscribe to desired property changes
 
@@ -61,13 +61,14 @@ To connect to a device:
     client.open(true);
     ```
 
-### Retrieve a device twin and examine reported properties
+### Retrieve and view a device twin
 
-After opening the client connection, call [getTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwin-gettwin(com-microsoft-azure-sdk-iot-service-devicetwin-devicetwindevice)) to retrieve the current twin properties.
+After opening the client connection, call [getTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwin-gettwin(com-microsoft-azure-sdk-iot-service-devicetwin-devicetwindevice)) to retrieve the current twin properties into a `Twin` object.
 
 For example:
 
 ```java
+private static Twin twin;
 System.out.println("Getting current twin");
 twin = client.getTwin();
 System.out.println("Received current twin:");
@@ -82,9 +83,9 @@ To update reported properties:
 
 1. Call [getReportedProperties](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwindevice?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwindevice-getreportedproperties()) to fetch the twin reported properties into a [TwinCollection](/java/api/com.microsoft.azure.sdk.iot.deps.twin.twincollection) object.
 
-1. Use [put](/java/api/com.microsoft.azure.sdk.iot.deps.twin.twincollection?#com-microsoft-azure-sdk-iot-deps-twin-twincollection-put(java-lang-string-java-lang-object)) to update a reported property. Call `put` for each reported property update.
+1. Use [put](/java/api/com.microsoft.azure.sdk.iot.deps.twin.twincollection?#com-microsoft-azure-sdk-iot-deps-twin-twincollection-put(java-lang-string-java-lang-object)) to update a reported property within the `TwinCollection` object. Call `put` for each reported property update.
 
-1. Use [updateReportedProperties](/java/api/com.microsoft.azure.sdk.iot.device.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-device-devicetwin-devicetwin-updatereportedproperties(java-util-set(com-microsoft-azure-sdk-iot-device-devicetwin-property))) to update the group of reported properties that were updated using the `put` method.
+1. Use [updateReportedProperties](/java/api/com.microsoft.azure.sdk.iot.device.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-device-devicetwin-devicetwin-updatereportedproperties(java-util-set(com-microsoft-azure-sdk-iot-device-devicetwin-property))) to apply the group of reported properties that were updated using the `put` method.
 
 For example:
 
@@ -159,6 +160,8 @@ To connect to IoT Hub to view and update device twin information:
 1. Use a [DeviceTwin](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwin?#com-microsoft-azure-sdk-iot-service-devicetwin-devicetwin-devicetwin(java-lang-string)) constructor to create the connection to IoT hub. The `DeviceTwin` object handles the communication with your IoT hub. As parameters, supply the **IoT Hub service connection string** that you created in the Prerequisites section and the `DeviceTwinClientOptions` object.
 1. The [DeviceTwinDevice](/java/api/com.microsoft.azure.sdk.iot.service.devicetwin.devicetwindevice) object represents the device twin with its properties and tags.
 
+For example:
+
 ```java
 import com.microsoft.azure.sdk.iot.service.devicetwin.*;
 import com.microsoft.azure.sdk.iot.service.exceptions.IotHubException;
@@ -218,7 +221,7 @@ To update device twin fields:
     twinClient.updateTwin(device);
     }
 
-    // Retrieve the device twin with the tag values from IoT Hub
+    // Retrieve and display the device twin with the tag values from IoT Hub
     System.out.println("Device twin after update:");
     twinClient.getTwin(device);
     System.out.println(device);

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

@@ -29,24 +29,14 @@ This section describes how to use the [azure-iot-device](/javascript/api/azure-i
 
 ### Install SDK packages
 
-Run these command to install the **azure-iot-device** device SDK, the **azure-iot-device-mqtt** on your development machine:
+Run this command to install the **azure-iot-device** device SDK on your development machine:
 
 ```cmd/sh
 npm init --yes
-npm install azure-iot-device azure-iot-device-mqtt --save
 ```
 
 The [azure-iot-device](/javascript/api/azure-iot-device) package contains objects that interface with IoT devices. The [Twin](/javascript/api/azure-iot-device/twin) class includes twin-specific objects. This section describes `Client` class code that is used to read and write device twin data.
 
-### Create modules
-
-Create Client and Protocol modules using the installed packages.
-
-```javascript
-const Client = require('azure-iot-device').Client;
-const Protocol = require('azure-iot-device-mqtt').Mqtt;
-```
-
 ### Choose a transport protocol
 
 The `Client` object supports these protocols:
@@ -57,31 +47,52 @@ The `Client` object supports these protocols:
 * `MqttWs`
 * `AmqpWs`
 
+Install needed transport protocols on your development machine.
+
+For example, this command installs the `Mqtt` protocol:
+
+```cmd/sh
+npm install azure-iot-device azure-iot-device-mqtt --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).
 
-This example assigns the AMQP protocol to a `Protocol` variable.
+### Create Client and Protocol modules
+
+Create a Client module using the installed package.
+
+For example,
 
 ```javascript
-const Protocol = require('azure-iot-device-mqtt').Amqp;
+const Client = require('azure-iot-device').Client;
+```
+
+Create a Protocol module using an installed transport package.
+
+This example assigns the MQTT protocol:
+
+```javascript
+const Protocol = require('azure-iot-device-mqtt').Mqtt;
 ```
 
 ### Add the IoT Hub string and transport protocol
 
-Call [fromConnectionString](/javascript/api/azure-iot-device/client?#azure-iot-device-client-fromconnectionstring) to establish a device-to-IoT hub connection using these parameters:
+Call [fromConnectionString](/javascript/api/azure-iot-device/client?#azure-iot-device-client-fromconnectionstring) to supply device connection parameters:
 
 * **connStr** - A connection string which encapsulates "device connect" permissions for an IoT hub. The connection string contains Hostname, Device ID & Shared Access Key in this format:
-"HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>". See the prerequisites section for how to look up the device primary connection string.
+"HostName=<iothub_host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>".
 * **transportCtor** - The transport protocol.
 
 ```javascript
+const deviceConnectionString = "{IoT hub device 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 call handler code.
+Use [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.
 
 For example:
 
@@ -94,19 +105,19 @@ client.open()  //open the connection
 
 ### Retrieve a device twin and examine reported properties
 
-Call [getTwin](/javascript/api/azure-iot-device/client?#azure-iot-device-client-gettwin-1) to assign the twin object. This object can be used to read device twin information.
+Call [getTwin](/javascript/api/azure-iot-device/client?#azure-iot-device-client-gettwin-1) to retrieve current device twin information into a [Twin](/javascript/api/azure-iot-device/twin) object.
 
 For example:
 
 ```javascript
-client.getTwin(function(err, twin) {
+client.getTwin(function(err, twin))
 if (err)
     console.error('could not get twin');
 ```
 
 ### Update reported device twin 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 callback method as the second parameter to the method.
+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.
 
 In this example, a JSON-formatted device twin patch is stored in the `patch` variable. The patch contains a device twin `connectivity` update value of `cellular`. The patch and error handler are passed to the `update` method. If there is an error, a console error message is displayed.
 
@@ -134,9 +145,9 @@ The desired property event listener can take one of the following forms:
 
 #### Receive all patches with a single event handler
 
-You can create code to receive any desired property change.
+You can create a listener to receive any desired property change.
 
-This code will output any properties that are received from the service.
+This example code outputs any properties that are received from the service.
 
 ```javascript
 twin.on('properties.desired', function (delta) {
@@ -147,7 +158,7 @@ twin.on('properties.desired', function (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.
+You can create a listener to receive an event if anything under a property grouping changes.
 
 For example:
 
@@ -181,7 +192,7 @@ For example:
 
 You can set up a listener for a single property change. In this example, the code for this event is executed only if the `fanOn` boolean value is part of the patch. The code outputs the new desired `fanOn` state whenever the service updates it.
 
-In this example, a backend application applies this desired property patch:
+1. A backend application applies this desired property patch:
 
 ```javascript
  const twinPatch2 = {
@@ -197,7 +208,7 @@ In this example, a backend application applies this desired property patch:
 };
 ```
 
-The listener triggers only when the `fanOn` property changes:
+1. The listener triggers only when the `fanOn` property changes:
 
 ```javascript
 twin.on('properties.desired.climate.hvac.systemControl', function (fanOn) {
@@ -215,15 +226,12 @@ The SDK contains two device twin samples:
 
 ## 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
+A backend application connects to a device through IoT Hub and 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:
 
-* Retrieve and update a device twin
-* Create a device twin query
+* Retrieves and updates a device twin
+* Creates a device twin query
 
 ### Install service SDK packages
 
@@ -297,7 +305,7 @@ Use [createQuery](/javascript/api/azure-iothub/registry?#azure-iothub-registry-c
 * **sqlQuery** - The query written as an SQL string.
 * **pageSize** - The desired number of results per page (optional. default: 1000, max: 10000).
 
-When the code creates the query object, it specifies the maximum number of returned documents in the second parameter. The query object contains a `hasMoreResults` boolean property that you can use to invoke the `nextAsTwin` methods multiple times to retrieve all results. A method called `next` is available for results that are not device twins, for example, the results of aggregation queries.
+If the **pageSize** parameter is specified, the query object contains a `hasMoreResults` boolean property that you can check and use the `nextAsTwin` method to get the next twin results page as many times as needed to retrieve all results. A method called `next` is available for results that are not device twins, for example, the results of aggregation queries.
 
 This example query selects only the device twins of devices located in the `Redmond43` plant.