Features of the ThingWorx - Azure IoT Integration
The ThingWorx Azure IoT Hub Connector requires the Azure IoT Extension for ThingWorx Platform. When imported into a ThingWorx Platform, this extension adds entities that are used to represent Azure IoT Edge Devices, Azure IoT Devices, an Azure IoT Hub, and Azure IoT Storage Containers, or "Blobs".
 |
Although v.2.0 of the Azure IoT Hub Extension supported creation and deletion of devices in Azure IoT, v.3.0 does NOT currently support these features. Given changes on both sides, the original implementation no longer works reliably with Azure IoT.
|
To represent devices connected to an Azure IoT Hub as well as Azure IoT Edge Devices, the Azure IoT Hub Extension includes a special Thing Template, called AzureIotThing, that serves as the Thing Template for any Azure IoT Edge device or Azure IoT Device. When the Azure IoT Hub Connector starts up, it retrieves the information needed to connect to its associated Azure IoT Hub from ThingWorx.
The ThingWorx Azure IoT Hub Connector supports the following aspects of Azure IoT:
Azure IoT Hub Configuration in ThingWorx Platform
As of v.3.0 of the ThingWorx Azure IoT Hub Connector, the configuration properties for its corresponding Azure IoT Hub are stored in the ThingWorx Platform. When it starts up, the Connector retrieves values for its configuration properties from the platform. What this change means for administrators is that you no longer need to configure this information for the Connector in its configuration file. With changes in Azure, it is easier to copy and then paste entire connection strings for the configuration of the AzureIotHub Thing in ThingWorx Composer.
Azure IoT Edge Device Support
The ThingWorx Azure IoT Hub Connector supports Azure IoT Edge Devices as well as IoT Devices that connect to an Azure IoT Hub. This section assumes that you are familiar with Azure IoT Edge and its three components, Azure IoT Edge Modules, IoT Edge Runtime, and IoT Edge Cloud Interface. If not, refer to the Microsoft Azure IoT Edge Documentation at
https://docs.microsoft.com/en-us/azure/iot-edge/. If you want to develop and deploy your own Azure IoT Edge module, follow one of the following tutorials in the Azure IoT Edge Documentation, available through the navigation panel at
https://docs.microsoft.com/en-us/azure/iot-edge/.
The Azure IoT Hub Connector supports the following activities with Azure IoT Edge Devices:
• Read and write edge module twin properties. These properties are represented as properties in ThingWorx.
• Convert telemetry messages that the edge Mmdule sends into ThingWorx as property updates.
• Execute direct methods.
For more information about support for the Azure IoT edge module support, refer to
Azure IoT edge module Twin.
Ingress Processing
Devices that are running Azure IoT Hub SDK applications send messages to the Azure IoT Hub. These messages arrive through an Azure Event Hub endpoint that is provided by the IoT Hub. Communication with the ThingWorx Platform is asynchronous to allow for optimal message throughput.
The messages typically contain updates to the values of properties of the respective devices. The ThingWorx Azure IoT Hub Connector listens for messages from the Azure IoT Hub, reads and translates them, and finally passes them to the ThingWorx Platform.
The Connector provides several metrics for ingress processing, all under the cxserver.azure.iot.ingress namespace. Refer to
Metrics for information about the metrics for ingress processing: msgCount, msgSize, and property.writes.
Egress Processing
Azure IoT devices do not connect directly to or bind with a ThingWorx Platform. However, there is a need to route outbound messages to them. More specifically, edge devices residing in the Azure IoT cloud are accessed through a mediator, such as an Azure IoT Hub. As long as communication is established between a ThingWorx Platform and an Azure IoT Hub, the platform can send and receive messages through the hub. The ThingWorx Azure IoT Hub Connector provides that communication.
The Connector enables Azure IoT devices to receive messages from a ThingWorx Platform when they next connect to the Azure IoT Hub. The Connector can connect to an IoT hub and upon successful connection, bind that IoT hub as an Azure IoT Hub Thing in the platform. When its connectivity and egress are delegated to an Azure IoT Hub Thing, an AzureIotThing sends and receives messages through that hub. There are two requirements for successful messaging:
• The value of the gatewayThing property of each Azure IoT device Thing must be the name of the AzureIotHub Thing that the device connects to in the Azure IoT Cloud.
• The Azure IoT Hub Thing needs to be bound on the ThingWorx Platform by the Connector when the Connector is actively connected to the Azure IoT Hub.
The following diagram illustrates the interaction among a ThingWorx Platform, an Azure IoT Hub Connector, an Azure IoT Hub, and Azure IoT devices (Thing1 and Thing2):
In this diagram:
• AzureThing1 and AzureThing2 extend the AzureIotThing Thing Template, which implements the RoutedEgress Thing Shape.
• The gatewayThing property of AzureThing1 and of AzureThing2 is set to the name of the Azure IoT Hub Thing derived from the AzureIotHubTemplate Thing Template. The AzureIotHub Thing implements the EgressGateway Thing Shape.
• Once it connects to its configured Azure IoT Hub, the Azure IoT Connector binds the hub to the HubThing in the ThingWorx Platform.
• While HubThing is bound/connected, AzureThing1 and AzureThing2 show as 'connected'.
• When egress messages such as property writes or service invocations occur on the platform for Azure IoT Edge devices, the Connector routes the messages to the Azure IoT Hub, which relays messages to the devices.
• When ingress messages such as property updates or service invocations occur from Azure IoT to a given Thing, the messages are routed directly from the Connector to the platform and related Things, not back through the HubThing.
Device Methods as Remote Services
The Azure IoT Hub enables you to invoke device (direct) methods on edge devices from the cloud. Direct methods take the form of a request-response interaction with an edge device, similar to an HTTP call. Direct methods allow you to specify a timeout period for a response, after which the method fails. These methods are most useful for scenarios in which you want to take a different action, based on whether the device responds. For example, instead of using an SMS wake-up call, you might use a direct method to check the status of an edge device. If the device responds, you might take actions such as forwarding a new temperature setting to the device from ThingWorx.
To support direct methods for Azure IoT Edge devices or Azure IoT Devices, you can declare remote services on Azure IoT Edge Device Things from ThingWorx Composer. The recommended way to apply the services to multiple devices is to add them to a Thing Template that extends the ThingWorx AzureIotThing Thing Template. When the Things for the devices are created in ThingWorx, they inherit the services.
 | For AzureIotThings that represent Azure IoT Edge Devices, the services must be defined using the format, {moduleID}::(serviceName). |
When the services are invoked from Composer, the requests are forwarded to Azure IoT Edge devices through Azure’s Direct Method invocations. Requests and responses are JSON documents (limited to 8KB in size). Using ThingWorx Mashup Builder, you can create a mashup that lets users enter the values for any input parameters for the service and then invoke it. The mashup could also display the response from the edge device once it has run the service.
For more information about direct methods on the Azure IoT Hub side, refer to
https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-direct-methods.
Azure Storage
The ThingWorx Azure IoT Hub Connector allows integration with Azure Blob Storage accounts. The Blob Storage account is used by the Event Processor of the ThingWorx Connector.
| | You configure the Event Processor Host (EPH) when configuring the AzureIotHub Thing in ThingWorx Composer To learn what information that you need to gather from Azure IoT, refer to
Step 1. Create and Configure Items in Azure IoT. |
In a ThingWorx Platform, the Azure Blob Storage container is represented as a File Repository Thing. You can view it through ThingWorx as you would any other File Repository Thing. Note that the File Repository is created as part of the Azure IoT Connector and therefore relies on the Connector for interactions with Azure. You cannot use Azure Storage as a file repository without the Connector. It is not stand-alone. The AzureBlobStorageTemplate Thing Template in the extension enables you to configure a Blob Storage Container in ThingWorx.
Multiple File Repository Things can exist within the same ThingWorx Platform instance, each bound to a particular Azure Blob Storage container. The containers must be within the same storage account, which is configured on the AzureIotHub Thing in ThingWorx.
| | Azure Storage has no concrete representation of a directory. A directory “exists” as long as there are files within it. The File Repository cannot represent empty directories, at least without adding empty “marker” files, which is NOT recommended. |
To create an Azure Blob Storage account, use the Azure Portal (“Storage Account”). When getting started with the Connector, you’ll find instructions to obtain the information about that account and then set the appropriate properties of the AzureIotHub Thing. Refer to
Getting an Azure IoT Hub Connector Up and Running for the steps to set up the AzureIotHub Thing. Refer to
Using the Azure Blob Storage in ThingWorx for information about setting up and using the Azure Blob Storage as a ThingWorx File Repository.
File Transfers
The ThingWorx Azure IoT Hub Connector supports transferring files between edge devices and an Azure Storage container that is set up as a File Repository Thing in ThingWorx. More specifically, the following transfers are supported:
• Transfer files to Azure file storage from a ThingWorx mashup
• Transfer files by issuing a FileTransferSubsystem.Copy operation that copies a file from an Azure Storage container to a ThingWorx File Repository that represents the Azure container (AzureBlobStorageTemplate Thing).
• Copy a file from a File Repository on ThingWorx Platform to the Azure Storage container.
• There is no support for "pushing" a file to an edge device. The AzureBlobStorageTemplate file repository provides a service to get a direct URL for a file within Azure. This URL can then be provided to an edge device to download the file directly from Azure IoT without requiring authentication. When invoking the service, you can configure an expiration date for the URL
In addition to these file transfers, the Connector integration support for file transfers includes event generation so that users can subscribe to the upload of files from an Azure IoT Device or Azure IoT Edge Device to an Azure Storage Container.
Encryption of Azure IoT Hub Thing Credentials
Starting with v.3.0 of the Connector, the Connector retrieves its Azure IoT Hub configuration settings from the AzureIotHub Thing that you configure using ThingWorx Composer. A service encrypts the AzureIotHub Thing configuration secrets and passes the encrypted secrets to the Connector. The following Azure IoT Hub Thing secrets are encrypted:
• consumerPolicyConnectionString
• registryPolicyConnectionString
• eventHubEndpoint
• deviceExportBlobThing.connectingString
• eventProcessorHostBlobThing.connectionString
• fileRepositoryBlobThing.connectionString
On the ThingWorx Platform, the Connector encryption key, must be added to the keystore of the Platform. The same encryption key must be added to the Connector keystore. On the Connector, use the default name, azure.connector.key, for the encryption key.
| | Starting with v.8.5.0 of the ThingWorx Platform and v.3.0.0 of the ThingWorx Azure IoT Hub Connector, the keystore files use the .pfx extension instead of .jks. For the procedures to set up the ThingWorx Platform and the Connector, refer to
Step 7. Set Up Encryption for Azure IoT Hub Credentials. Note that you CANNOT simply change the extension of an existing keystore file. You must go through the procedure. |
After loading the encryption key, the Connector validates the following conditions:
• Is the name of the encryption key defined in the configuration file?
• Is the Security Manager initialized through the property, -Dsecret.management.config.file? The Security Manager must be loaded to perform decryption of the Azure IoT Hub secrets.
If either condition returns false, the Connector throws an exception.