Azure IoT Hub Connector — Device Twin Support
The device twin is a JSON document that is persisted in an Azure IoT Hub. A device twin stores device state information, including metadata, configurations, and conditions. The Azure IoT Hub persists a device twin for each Azure IoT Device and Azure IoT Edge device that you connect to the Azure IoT Hub.
In general, devices that communicate through the ThingWorx Azure IoT Hub Connector are represented in ThingWorx Platform as “Things.” ThingWorx Things contain a combination of property types: those that are infrequently updated (configuration properties) and those that are persisted within value streams (time-series data). Device twin data should be used for data that is updated infrequently and plays a role in logic that is used in Azure services, such as Device Queries and Device Jobs.
ThingWorx properties for Azure IoT devices are defined in the AzureIotThing Thing Template. Three types of Thing properties correspond to the tags, properties.desired, and properties.reported groups of the JSON document. They contain current values of the device twin data.
Azure IoT Hub Explorer
Although the device twin data is not currently editable or visible through the Azure Dashboard, it is manageable through the Azure IoT Hub Explorer command line utility. Installation and basic instructions are available here:
https://github.com/azure/iothub-explorer. A tutorial about the tool is available at
https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-device-management-iothub-explorer.
ThingWorx Properties for a Device Twin
The AzureIotThing Thing Template, contains three JSON properties that contain current values of the device twin data, divided up into three pieces:
• twinDesired — Data that the Azure IoT Hub back-end application can modify, and the device receives notifications for each change. Specific change event handlers can be created for each key in the desired field. The Azure IoT Service SDK, which the ThingWorx Azure IoT Hub Connector interfaces with, can modify this data. Both the Azure IoT Device and Service SDKs can read this data.
• twinReported — Data that only the device can modify (NOT time-series data). The Azure IoT back-end application can access this data, but no notifications are received for changes that occur to the reported field.
• twinTags—Data that only the Azure IoT Hub back-end application knows about. This data is not available to the edge device application. Only the Azure IoT Service SDK can read and write this data. Notifications are not sent when changes to this data occur.
The device twin properties are NOT pushed through ingress. Updating the current values requires clicking the Refresh button or reloading the Thing in ThingWorx Composer or in a mashup. These properties are managed with the Azure IoT Services SDK, so only twinDesired and twinTags can be modified from ThingWorx Composer.
 |
Device twin updates and reads are limited, based on the type of hub in use and the number of hub units. In addition, the data format is limited. The size of each chunk of the device twin (tags, reported and desired properties) is limited to 8KB. Data is structured like JSON, but no array values are allowed. Key values are limited to 64 UTF-8 bytes and cannot contain periods, spaces, or dollar signs. The size of any string property is limited to 512 bytes, and overall depth of the JSON structure is limited to five levels, not including the final leaf values. Refer to the documentation at
https://docs.microsoft.com/en-us/azure/guides/developer/azure-developer-guide and
https://docs.microsoft.com/en-us/cli/azure/ext/azure-cli-iot-ext/iot/hub/device-twin?view=azure-cli-latest for more information.
|
Change Events
Since Azure IoT Hub supports device-twin change notifications, the Connector can publish events to the ThingWorx Platform when the twin changes. The event, DeviceTwinChange, is defined on the AzureIotThing Thing Template in ThingWorx and contains a single property, patch. The value of this property is the patch document submitted to the device-twin update operation. The patch document contains any properties that were submitted to the operation, regardless of whether those values were different from the then-current twin state. Here is a sample patch document:
{
"properties": {
"desired": {
"$metadata": {
"$lastUpdated": "2019-02-30T16:24:48.789Z"
},
"$version": 1
},
"reported": {
"$metadata": {
"$lastUpdated": "2019-02-30T16:24:48.789Z"
},
"$version": 1
}
}
}
"properties": {
"desired": {
"$metadata": {
"$lastUpdated": "2019-02-30T16:24:48.789Z"
},
"$version": 1
},
"reported": {
"$metadata": {
"$lastUpdated": "2019-02-30T16:24:48.789Z"
},
"$version": 1
}
}
}
Enabling Change Events
Azure IoT Hub does not deliver the twin change events by default; it 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. Enabling the twin-change events can be done through the Azure IoT portal. To enable these events and run an example, refer to
Device Twin Demo — Change Events.