Use the ThingWorx Azure IoT Hub Connector with simulated appliances.
GUIDE CONCEPT
This project will introduce how to integrate ThingWorx with Azure IoT Hub. The combination of these two platforms extends the ThingWorx utilities to Azure IoT Hub edge devices and allows integration with Azure Blob Storage accounts.
Following the steps in this guide, you will install the ThingWorx Azure IoT Hub Connector and run a simulated Azure device.
We will teach you how to build powerful and scalable IoT applications by integrating ThingWorx and Azure IoT Hub.
YOU'LL LEARN HOW TO
- Install, configure, and run the ThingWorx Azure IoT Hub Connector
- Import devices that exist in Azure into ThingWorx
- Connect a simulated Azure device to ThingWorx Foundation server
NOTE: This guide's content aligns with ThingWorx 9.3. The estimated time to complete all parts of this guide is 60 minutes.
Step 1: Overview Diagram
The ThingWorx Azure IoT Hub Connector 4.0 connects edge devices running agents developed using a Microsoft Azure IoT SDK to the ThingWorx Platform.
The four systems that working together are show in the diagram below:
- Azure IoT Edge devices
- Azure IoT Hub
- ThingWorx Azure IoT Connector
- ThingWorx Foundation
Getting Started Overview
The diagram below shows an overview of the steps for installing and starting the ThingWorx Azure IoT Connector.
The machine where each task is completed is indicated by color.
Step 2: Configure Azure IoT Hub
In order to use the ThingWorx Azure IoT Connector, you must first configure an IoT Hub and a storage account in Microsoft Azure. In this step, we will create the Azure resources and gather the configuration information that enable you to connect to ThingWorx with the required credentials.
Log into Azure Portal
If you do not already have an Azure account you can create an account that will work with this guide.
Create Azure IoT Hub
Follow the Microsoft documentation to create an Azure IoT Hub, accepting any defaults.
TIP: The name your IoT Hub must be globally unique and include only lowercase letters and numbers.
Create Storage Account
Follow the Microsoft documentation to create an Azure Storage account in the same location as your Azure IoT Hub, as specified in the Current Location settings
NOTE: Select Blob storage as the account type and the Hot Access Tier.
Register Azure IoT Edge Device in IoT Hub
Follow the Microsoft documentation to register a new IoT Edge device in IoT Hub that you already created.
Step 3: Install Azure Connector
The ThingWorx Azure IoT Hub Connector distribution bundle comes packaged with all the software you will need to connect ThingWorx and Azure.
- Download the ThingWorx Azure IoT Hub Connector from PTC Support
Note: You must download the version of the Azure IoT Hub Connector compatible with your version of ThingWorx - Extract the download to a directory on the system where it will run. (where v.v.v represents the release number)
- On Linux, this guide uses the base directory, /opt. The subdirectories and files should reside in the directory, /opt/ThingWorx-Azure-IoTHub-Connector-v.v.v.
- On Windows, extract the bundle so that the subdirectories and files reside in C:\ThingWorx-Azure-IoT-Hub-Connector-v.v.v
Configure Connection Server
The Connection Server component of ThingWorx Azure IoT Connector must be configured with information specific to both your Azure IoT Hub and your ThingWorx Foundation server.
- Copy the file azure-iot-sample.conf in the connector > conf directory and save the file with the name azure-iot.conf
- Edit the configuration file to replace the ten placeholder values for the parameters listed below with values copied from your Azure control panel.
- consumerPolicyName - Whether you have a new or existing hub, you need to provide the name of the consumer policy and its related Primary or Secondary key. The policy to select is typically the built-in, pre-defined policy called service. Navigate to All Resources > your hub > Settings > Shared access policies > service. If you added a custom service policy to your hub with the permission service connect select that policy.
- consumerPolicyKey - Once you find the policy name, stay in the Shared access policies screen, and click the name. Copy the content of the Primary key. This key supplies the credentials to access services that are specified in the related policy.
- registryPolicyName - Specify a policy name that is related to the registryPolicyKey. This policy is typically a built in, predefined policy called registryReadWrite, but it is possible to use a custom policy if you add it to your hub. The shared access policy requires the registry read and registry write permissions.
- registryPolicyKey - The key that supplies credentials to access services in the policy specified in registryPolicyName.
- hubName - A name that defines the Azure IoT Hub related to this ThingWorx Connector. This Azure IoT Hub manages your things and their related messages. Hubs can be scaled via hub units at different price tiers per unit. Hubs are related to a resource group, which is related to a subscription Id and a cloud Location.
TIP: To find the name associated with your Azure IoT Hub that the ThingWorx Connector will use to communicate with it, navigate to All Resources > your hub > Settings > Properties > NAME. - eventHubName - The Event Hub-compatible name that is used by SDKs and integrations that expect to read from Event Hubs. An Event Hub is an internal component of an Azure IoT Hub that handles device-to-cloud events for related things. In many cases, the IoT Hub name and Event Hubcompatible name are the same, so this property defaults to the Azure IoT Hub name (hubName). Navigate to All Resources > your hub > Settings > Built-in endpoints > Events > Event Hub-compatible name to find this name.
- eventHubNamespace - To find the endpoint that is used by SDKs and integrations that expect to read from Event Hubs, navigate to All resources > your hub > Settings > Built-in endpoints > Events > Event Hub-compatible endpoint, and copy the host name, without the rest of the address (".servicebus.windows.net"). The ThingWorx Azure IoT Connector uses this endpoint to read messages from your hub.
- consumerGroup - To find a consumer group name to enable the Connector to pull data from the Azure IoT Hub, navigate to All Resources > your hub > Messaging > Endpoints > Built-in endpoints > Events > Consumer groups. To use the $Default consumer group, set this property to null.
- hubHostname - To find the host name for your hub, navigate to All Resources > your hub > Overview > Hostname. The host name is defined by the hubName plus a domain name that is chosen by Azure, typically azuredevices.net.
- blob-storage.account-name - The blob-storage section specifies the settings for an Azure blob storage account. The storage provides containers that are used for device export of an Azure IoT Hub to ThingWorx via the Connector and can also be created by the Connector if you create AzureStorageContainerFileRepository things in ThingWorx. If you do not have one, create a Storage Account in the Azure portal. To find the name of an existing account, navigate to Settings > Access Keys > Storage account name.
- blob-storage.account-key - The key to associate with the name of the blob storage account. To find the key for an existing account, navigate to Settings > Access Keys > Primary or secondary key.
- consumerPolicyName - Whether you have a new or existing hub, you need to provide the name of the consumer policy and its related Primary or Secondary key. The policy to select is typically the built-in, pre-defined policy called service. Navigate to All Resources > your hub > Settings > Shared access policies > service. If you added a custom service policy to your hub with the permission service connect select that policy.
- Enter your ThingWorx Foundation server host, port, and appKey in the transport.websockets section.
transport.websockets { // ThingWorx platform application key app-key = "6d70dfca-fe88-4d8c-83aa-686449b52cb2" // One or more platforms can be specified here, comma separated platforms = "ws://45.23.12.112:80/Thingworx/WS" }
NOTE: If you are using an SSL connection to your ThingWorx Foundation server use wss in place of ws in the platform parameter. If the URL for the ThingWorx Foundation server does not include a port, use 80 for http connections and 443 for https
Click here to view Part 2 of this guide.
