Device Twin Demo — Change Events

Using the Demo Applications > Device Twin Demo — Change Events

Located in the demo/twin-change-events-demo/ subdirectory of the ThingWorx Azure IoT Hub Connector installation, this application demonstrates the use of the Connector support for change events in a device twin. In this demo, a device sends the versions of its hardware and software when it starts. These version numbers are then copied into the tags section of the device twin. Note that the device SDK cannot change this information directly. A subscription to the DeviceTwinChange event handles the update to the device twin.

For simplicity, the device is represented by calls to the iothub-explorer tool. Since this tool does not currently support updating the device twin from the device-simulate sub-command, this demo uses the desired section instead of the reported section. A production-ready implementation of this scenario would use the reported section.

Although the update-twin command requires a reported section be provided, the command cannot update values in that section.

Before You Begin

In addition to the general prerequisites, ensure that you meet the following requirements before using this demo:

• Twin Change Events must be routed to the “events” endpoint of the Hub. Refer to the procedure in the next section.

• Azure IoT Hub Explorer or equivalent tool installed and running

Setting Up the Devices

Using the Import/Export menu in ThingWorx Composer, import the Things_twinChangeDemo.xml into your ThingWorx Platform. This file is located in the demo/twin-change-events-demo/platform/entities/ subdirectory of the Connector installation. This import creates all the entities needed for this demo.

You must either be an administrator or a user with the appropriate permissions to import a file into ThingWorx Platform. For more information on importing files into ThingWorx Platform, refer to Importing and Exporting Data, Entities, and Extensions.

From ThingWorx Composer, navigate to the TwinChangeDemo Thing, and follow these steps:

1. In the gatewayThing property field of the TwinChangeDemo Thing, enter the name of your AzureIotHub Thing.

2. Create the device in Azure IoT in one of the following ways:

◦ Use the Azure IoT Hub portal.

◦ Navigate to the ConnectionServicesHub Thing in ThingWorx and run the CreateAzureIotDevice service.

Setting Up the Route for Twin Change Events

An Azure IoT Hub does not deliver the change events for device twins by default. This feature must be enabled for the hub. Once the events are set up to forward to the events stream, the Connector can handle the messages without any further configuration. To enable change events for device twins, follow these steps:

1. In the Azure portal, navigate to the hub that is associated with your Connector.

2. In the hub blade, under Messaging, click Routes.

3. In the next blade, click Add.

4. In the Edit a Route dialog, provide the following information:

a. Choose any name for your route.

b. From the Data source menu, choose Twin Change Events.

c. From the Endpoint menu, choose events.

5. Click Save.

If other processes are reading from the events endpoint of the Hub, the twin change messages begin arriving. To distinguish these messages from other messages, look at the system property, iothub-message-source, on the message. Normal device messages have a source of Telemetry, while change messages for device twins use twinChangeEvents.

Running the Demo

After meeting the prerequisites and setting up the route, log in to ThingWorx Composer and navigate to the TwinChangeDemo Thing and look at the Subscription. The handler is very short, but notice that the twin is updated only if the supplied patch document includes the versions key within the desired section. This condition is important because the handler is called for any updates to the twin, which may contain data that the handler will ignore. Any updates to the device twin from within a handler trigger another change event for the twin and call the handler again.

Be careful to avoid an infinite loop of change events for device twins.

To trigger the event, log in to the iothub-explorer, as follows:

$ iothub-explorer login "HostName={HOSTNAME}.azure-devices.net;
SharedAccessKeyName=iothubowner;SharedAccessKey={ACCESS_KEY}"

Next, send an update to the device twin:

$ iothub-explorer update-twin TwinChangeDemo '{"tags": {},
"properties": {"reported": {},
"desired": {"versions":
{"hw": "0.9a", "sw": "1.0.2.14"} } } }'
deviceId: TwinChangeDemo
properties:
desired:
versions:
sw: 1.0.2.14
hw: 0.9a
$metadata:
$lastUpdated: 2019-06-28T20:28:43.3236137Z
$lastUpdatedVersion: 347
versions:
$lastUpdated: 2019-06-28T20:28:43.3236137Z
$lastUpdatedVersion: 347
hw:
$lastUpdated: 2019-06-28T20:28:43.3236137Z
$lastUpdatedVersion: 347
sw:
$lastUpdated: 2019-06-28T20:28:43.3236137Z
$lastUpdatedVersion: 347
$version: 347
reported:
$metadata:
$lastUpdated: 2019-06-28T19:50:14.2048647Z
$version: 1
tags:
etag: AAAAAAAAAVs=

Retrieving the device twin shows the newly added tags:

$ iothub-explorer get-twin TwinChangeDemo
deviceId: TwinChangeDemo
properties:
... elided ...
tags:
hw_version: 0.9a
sw_version: 1.0.2.14
etag:AAAAAAAAAVw=