cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

Community Tip - Did you know you can set a signature that will be added to all your posts? Set it here! X

Connect Azure IoT Devices Part 1

No ratings

 

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 this guide is 60 minutes

 

 

 

Step 1: Overview Diagram

 

The ThingWorx Azure IoT Hub Connector maintains a network connection to both an Azure IoT and a ThingWorx Foundation instance:

  ThingWorx-Azure-IoT-Connector-diagram.jpg

 

 

The ThingWorx Azure IoT Hub Connector enables remote devices that connect to the Azure IoT Hub, to connect to the ThingWorx Foundation server. The Azure IoT Connector handles message routing for the devices that communicate through the Azure IoT system. It also handles message routing from the ThingWorx Foundation server to devices via the Azure IoT Hub.

 

The ThingWorx Azure IoT Connector is a separate, stand-alone application that must be run on a server that can connect to both the ThingWorx server and the Azure IoT service.

 

 

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. You can provision a free tier account for these resources. 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 a free 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.

 

1. Create message routes to direct DeviceLifecycleEvents and TwinChangeEvents events to the built-in events endpoint. For a tutorial, refer to Tutorial: Use the Azure CLI and Azure portal to configure IoT Hub message routing

2. Register at least one Azure IoT Device or Azure IoT Edge Device to your Azure IoT Hub. For a tutorial, refer to Register an IoT Edge device in IoT Hub

 

 

Create Storage Account

 

Follow the Microsoft documentation to create an Azure Storage account.

 

NOTE: Select Blob storage as the account type and the Hot Access Tier.

 

 

 

Step 3: Import Extensions

 

The ThingWorx Azure IoT Hub Connector distribution bundle comes packaged with all the software you will need to connect ThingWorx and Azure.

  1. Download the Azure IoT Hub Connector from PTC Support
  2. Extract the application bundle 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-4.2.0.
    • On Windows, extract the bundle so that the subdirectories and files reside in C:\ThingWorx-Azure-IoT-Hub-Connector-4.2.0
  3. In the lower-left side of Composer, click Import/Export, then Import. 

    v90_import.png

  4. In the Import From File pop-up, under Import Option select Extension from the drop-down, then click Browse.
  5. Navigate to the /extensions directory and click on ConnectionServicesExtension-2.2.4.zip file.

    v90_Google_Map_import.png

     

  6. Click Import in the Import From File pop-up, then click Close after file is successfully imported.
  7. Repeat the above steps for the azure-iot-hub-adapter-extension-4.2.0.4.zip file.
  8. Follow the steps to Create an Application Key and note the value, it will be used in the the next step.

 

 

Step 4: Install Azure Connector

 

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.

 

  1. Copy the file azure-iot-sample.conf in the connector > conf directory and save the file with the name azure-iot.conf
  2. 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.

      service_key.png

       

    • 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.

      event-hub-compatible-name.png

       

    • 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.

      hub_hostname.png

       

    • 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.

      blobstore_credentials.png

       

    • 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

  3. Enter your ThingWorx Foundation server host, port, and appKey  in the transport.websockets section.

transport.websockets { 
  app-key = "6d70dfca-fe88-4d8c-83aa-686449b52cb2"
  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.

 

 

 

Step 5: Launch IoT Hub Connector

 

  1. Open a shell or a command prompt window. On a Windows machine, open the command prompt as Administrator.
  2. The AZURE_IOT_OPTS environment variable must be set before starting the Azure IoT Hub Connector. Below are sample commands using the default installation directory.
    • On Windows: set AZURE_IOT_OPTS=-Dconfig.file=C:\ThingWorx-Azure-IoT-Connector-<version>\azure-iot-<version>-application\conf\azure-iot.conf -Dlogback.configurationFile=C:\ThingWorx-Azure-IoT-Connector-<version>\azure-iot-<version>-application\conf\logback.xml
    • On Linux: export AZURE_IOT_OPTS="-Dconfig.file=/var/opt/ThingWorx-Azure-IoT-Connector-<version>/azure-iot-<version>-application/conf/azure-iot.conf -Dlogback.configurationFile=/var/opt/ThingWorx-Azure-IoT-Connector-<version>/azure-iot-<version>-application/conf/logback.xml"

      NOTE: You must run the export command each time you open a shell or command prompt window.

  3. Change directories to the bin subdirectory of the Azure IoT Hub Connector installation.

  4. Start the Azure IoT Hub Connector with the appropriate command for your operating system.

    • On Windows: azure-iot.bat
    • On Linux: /azureiot

      Connector_start.png

      NOTE: On Windows you may have to shorten the installation directory name or move the bin directory closer to the root directory of your system to prevent exceeding the Windows limit on the classpath length.

       

  5. The Connection Server should start with no errors or stack traces displayed. If the program ends, check the following:
    • Java version is 1.8.0, update 92 or greater and is Java(TM) not OpenJDK.
    • Open azure-iot.conf and confirm ThingWorx Foundation is set to the correct URL and port.
    • Confirm the platform scheme is ws if http is used to access ThingWorx.
    • Confirm all Azure credentials are correct for your Azure account.
  6. In ThingWorx Foundation click the Monitoring tab then click Connection Servers. You should see a server named azure-iot-cxserver-{server-uuid}, where {server-uuid} is a unique identifier that is assigned automatically to the server.

    connection-servers.png

     

 

 

Step 6: Import Device from Azure

 

With the ThingWorx Azure IoT Connector, you can import into ThingWorx any existing devices that are currently provisioned to the Azure IoT Hub.

 

Add Device Azure IoT Hub

 

If you have not provisioned any devices to your Azure IoT Hub you can learn more about Azure IoT Hub device identity before following the steps below to create a test device.

 

  1. In your Azure Portal, click All Resources, then select the name of your IoT Hub.
  2. Under Explorers click IoT devices, then click + Add.
  3. Enter a name for your device, then click Save.
  4. When the device name appears in the list it is ready to use.

    AddDevice.png

     

Import Device into ThingWorx

 

We will manually execute a service in ThingWorx that will import Azure IoT Hub devices into ThingWorx.

 

  1. In ThingWorx Composer, navigate to the ConnectionServicesHub Thing.

  2. Click Services tab and scroll to the ImportAzureIotDevices service and click the execute Arrow.

    import-azure-iot-devices.png
    NOTE: The * in the pattern field will act as a wildcard and import all devices, you can enter a string to match that will only import a subset of all available devices.

    ImportAzureIotDevice_execute.png

  3. Click Execute to import the devices then click Done.
  4. Click Things in the left column to see the Things that were created.

    imported-azure-things.png

     

Click here to view Part 2 of this guide.
Was this tip helpful? Yes No
Version history
Last update:
‎Mar 07, 2023 01:50 PM
Updated by:
6-Contributor
Labels (2)
Contributors