| title | description | services | documentationcenter | author | manager | ms.assetid | ms.service | ms.devlang | ms.topic | ms.tgt_pltfrm | ms.workload | ms.date | ms.author | ms.custom |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Synchronize device state from Azure IoT Hub | Microsoft Docs |
Use device twins to synchronize state between your devices and your IoT hub |
iot-hub |
dominicbetts |
timlt |
iot-hub |
dotnet |
tutorial |
na |
na |
05/14/2018 |
dobett |
mvc |
As well as receiving telemetry from your devices, you may need to configure your devices from your back-end service. When you send a desired configuration to your devices, you may also want to receive status and compliance updates from those devices. For example, you might set a target operational temperature range for a device or collect firmware version information from your devices.
To synchronize state information between a device and an IoT hub, you use device twins. A device twin is a JSON document, associated with a specific device, and stored by IoT Hub in the cloud where you can query them. A device twin contains desired properties, reported properties, and tags. A desired property is set by a back-end application and read by a device. A reported property is set by a device and read by a back-end application. A tag is set by a back-end application and is never sent to a device. You use tags to organize your devices. This tutorial shows you how to use desired and reported properties to synchronize state information:
In this tutorial, you perform the following tasks:
[!div class="checklist"]
- Create an IoT hub and add a test device to the identity registry.
- Use desired properties to send state information to your simulated device.
- Use reported properties to receive state information from your simulated device.
[!INCLUDE cloud-shell-try-it.md]
If you don’t have an Azure subscription, create a free account before you begin.
The two sample applications you run in this quickstart are written using Node.js. You need Node.js v4.x.x or later on your development machine.
You can download Node.js for multiple platforms from nodejs.org.
You can verify the current version of Node.js on your development machine using the following command:
node --version
Download the sample Node.js project from https://github.com/Azure-Samples/azure-iot-samples-node/archive/master.zip and extract the ZIP archive.
To complete this tutorial, your Azure subscription must contain an IoT hub with a device added to the device identity registry. The entry in the device identity registry enables the simulated device you run in this tutorial to connect to your hub.
If you don't already have an IoT hub set up in your subscription, you can set one up with following CLI script. This script uses the name tutorial-iot-hub for the IoT hub, you should replace this name with your own unique name when you run it. The script creates the resource group and hub in the Central US region, which you can change to a region closer to you. The script retrieves your IoT hub service connection string, which you use in the back-end sample to connect to your IoT hub:
hubname=tutorial-iot-hub
location=centralus
# Install the IoT extension if it's not already installed:
az extension add --name azure-cli-iot-ext
# Create a resource group:
az group create --name tutorial-iot-hub-rg --location $location
# Create your free-tier IoT Hub. You can only have one free IoT Hub per subscription:
az iot hub create --name $hubname --location $location --resource-group tutorial-iot-hub-rg --sku F1
# Make a note of the service connection string, you need it later:
az iot hub show-connection-string --hub-name $hubname -o table
This tutorial uses a simulated device called MyTwinDevice. The following script adds this device to your identity registry and retrieves its connection string:
# Set the name of your IoT hub:
hubname=tutorial-iot-hub
# Create the device in the identity registry:
az iot hub device-identity create --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg
# Retrieve the device connection string, you need this later:
az iot hub device-identity show-connection-string --device-id MyTwinDevice --hub-name $hubname --resource-group tutorial-iot-hub-rg -o table
You use desired properties to send state information from a back-end application to a device. In this section, you see how to:
- Receive and process desired properties on a device.
- Send desired properties from a back-end application.
To view the simulated device sample code that receives desired properties, navigate to the iot-hub/Tutorials/DeviceTwins folder in the sample Node.js project you downloaded. Then open the SimulatedDevice.js file in a text editor.
The following sections describe the code that runs on the simulated device that responds to desired property changes sent from the back end application:
The following code connects to your IoT hub using a device connection string:
[!code-javascriptCreate IoT Hub client]
The following code gets a twin from the client object:
[!code-javascriptGet twin]
You can structure your desired properties in any way that's convenient to your application. This example uses one top-level property called fanOn and groups the remaining properties into separate components. The following JSON snippet shows the structure of the desired properties this tutorial uses:
[!codeSample desired properties]
You can create handlers for desired property updates that respond to updates at different levels in the JSON hierarchy. For example, this handler sees all desired property changes sent to the device from a back-end application. The delta variable contains the desired properties sent from the solution back end:
[!code-javascriptHandle all properties]
The following handler only reacts to changes made to the fanOn desired property:
[!code-javascriptHandle fan property]
In the example desired properties JSON shown previously, the climate node under components contains two properties, minTemperature and maxTemperature.
A device's local twin object stores a complete set of desired and reported properties. The delta sent from the back end might update just a subset of desired properties. In the following code snippet, if the simulated device receives an update to just one of minTemperature and maxTemperature, it uses the value in the local twin for the other value to configure the device:
[!code-javascriptHandle climate component]
The local twin object stores a complete set of desired and reported properties. The delta sent from the back end might update just a subset of desired properties.
The desired properties sent from the back end don't indicate what operation is being performed on a particular desired property. Your code needs to infer the operation from the current set of desired properties stored locally and the changes sent from the hub.
The following snippet shows how the simulated device handles insert, update, and delete operations on the list of components in the desired properties. You can see how to use null values to indicate that a component should be deleted:
[!code-javascriptHandle components]
You've seen how a device implements handlers for receiving desired property updates. This section shows you how to send desired property changes to a device from a back-end application.
To view the simulated device sample code that receives desired properties, navigate to the iot-hub/Tutorials/DeviceTwins folder in the sample Node.js project you downloaded. Then open the ServiceClient.js file in a text editor.
The following code snippet shows how to connect to the device identity registry and access the twin for a specific device:
[!code-javascriptCreate registry and get twin]
The following snippet shows different desired property patches the back end application sends to the device:
[!code-javascriptPatches sent to device]
The following snippet shows how the back-end application sends a desired property update to a device:
[!code-javascriptSend desired properties]
In this section, you run two sample applications to observe as a back-end application sends desired property updates to a simulated device application.
To run the simulated device and back-end applications, you need the device and service connection strings. You made a note of the connection strings when you created the resources at the start of this tutorial.
To run the simulated device application, open a shell or command prompt window and navigate to the iot-hub/Tutorials/DeviceTwins folder in the Node.js project you downloaded. Then run the following commands:
npm install
node SimulatedDevice.js "{your device connection string}"
To run the back-end application, open another shell or command prompt window. Then navigate to the iot-hub/Tutorials/DeviceTwins folder in the Node.js project you downloaded. Then run the following commands:
npm install
node ServiceClient.js "{your service connection string}"
The following screenshot shows the output from the simulated device application and highlights how it handles an update to the maxTemperature desired property. You can see how both the top-level handler and the climate component handlers run:
The following screenshot shows the output from the back-end application and highlights how it sends an update to the maxTemperature desired property:
Your back-end application receives state information from a device as reported properties. A device sets the reported properties, and sends them to your hub. A back-end application can read the current values of the reported properties from the device twin stored in your hub.
You can send updates to reported property values as a patch. The following snippet shows a template for the patch the simulated device sends. The simulated device updates the fields in the patch before sending it to the hub:
[!code-javascriptReported properties patches]
The simulated device uses the following function to send the patch that contains the reported properties to the hub:
[!code-javascriptSend reported properties]
A back-end application accesses the current reported property values for a device through the device twin. The following snippet shows you how the back-end application reads the reported property values for the simulated device:
[!code-javascriptDisplay reported properties]
In this section, you run two sample applications to observe as a simulated device application sends reported property updates to a back-end application.
You run the same two sample applications that you ran to see how desired properties are sent to a device.
To run the simulated device and back-end applications, you need the device and service connection strings. You made a note of the connection strings when you created the resources at the start of this tutorial.
To run the simulated device application, open a shell or command prompt window and navigate to the iot-hub/Tutorials/DeviceTwins folder in the Node.js project you downloaded. Then run the following commands:
npm install
node SimulatedDevice.js "{your device connection string}"
To run the back-end application, open another shell or command prompt window. Then navigate to the iot-hub/Tutorials/DeviceTwins folder in the Node.js project you downloaded. Then run the following commands:
npm install
node ServiceClient.js "{your service connection string}"
The following screenshot shows the output from the simulated device application and highlights how it sends a reported property update to your hub:
The following screenshot shows the output from the back-end application and highlights how it receieves and processes a reported property update from a device:
If you plan to complete the next tutorial, leave the resource group and IoT hub and reuse them later.
If you don't need the IoT hub any longer, delete it and the resource group in the portal. To do so, select the tutorial-iot-hub-rg resource group that contains your IoT hub and click Delete.
Alternatively, use the CLI:
# Delete your resource group and its contents
az group delete --name tutorial-iot-hub-rg
In this tutorial, you learned how to synchronize state information between your devices and your IoT hub. Advance to the next tutorial to learn how to use device twins to implement a firmware update process.
[!div class="nextstepaction"] Implement a device firmware update process