Minimal Configuration for Connecting to a ThingWorx Platform in Single-Server Mode
This topic presents the minimal configuration requirements for a ThingWorx Azure IoT Hub Connector to connect to a single-server ThingWorx Platform and the
Next Steps. If you are using the Connector in a ThingWorx High Availability Clustering environment, refer to
High Availability Configuration.
Required Configuration
These instructions create a configuration file for the Azure IoT Hub Connector that has the properties required to communicate with a single-server ThingWorx Platform, an Azure IoT Hub, and your Azure IoT Blob Storage. Your Edge devices communicate with the Azure IoT Hub, which in turn sends the messages to the ThingWorx Azure IoT Hub Connector. The Connector does not communicate directly with your Edge devices.
 |
Recall that the connection between the Connector and the Azure IoT Hub is protected by SSL. When you set the connection string properties for the AzureIotHubTemplate Thing in ThingWorx Composer, you are providing this protection.
|
1. Navigate to the <azure_connector_install>/conf directory.
2. Copy the azure-iot-sample.conf configuration file, rename it to azure-iot.conf, and open the new file in a text editor.
The rest of this procedure takes you through the required properties. You must set these properties for the configuration file to be valid. An invalid configuration file will prevent the Connector from starting.
3. Application key for the Azure IoT Hub Connector to use when authenticating with ThingWorx Platform — Replace <Your App Key Here> with the application key you created for this Connector:
cx-server {
transport.websockets {
app-key = "<Your App Key Here>"
For example: app-key = "88888888-4444-4444-aaaa-cccccccccccc"
4. The URI of the ThingWorx Platform to which the Connector will connect — Replace "wss://<host>:<port>/Thingworx/WS" with the URL for the ThingWorx Platform:
cx-server {
transport.websockets {
app-key = <your_application-key>
platforms = "wss://<host>:<port>/Thingworx/WS"
The URI scheme must be wss for a secure (SSL/TLS) connection and ws for an insecure connection. The URI path must be /Thingworx/WS for either secure or insecure connections. For example:
◦ Secure: platforms = "wss://twxplatform:8443/Thingworx/WS"
◦ Insecure: platforms = "ws://twxplatform:8080/Thingworx/WS"
 |
Although it is still possible to specify more than one URI for the platforms property, only the first URI is used. Any subsequent URI is ignored.
|
5. To communicate with the Azure IoT Hub and Blob Storage, the Azure IoT Hub Connector needs to know the Thing names of your AzureIotHubTemplate Thing and AzureIotBlobStorageTemplate Thing. To supply these names, edit the following properties:
a. hub-thing-name — Enter the thingName of the AzureIotHub Thing you created using ThingWorx Composer.
b. repository-thing-name — Enter the thingName of your AzureIotBlobStorageTemplate Thing.
|
|
If you skipped
Step 5. Create Azure IoT Entities in ThingWorx Composer and do not have these Things, go back to that step and create them now.
|
6. If you are using the Connector with ThingWorx Azure Industrial IoT (IIoT) OPC UA, you need to add the protocol.opcua.enabled property to the cx-server.protocol group in the configuration file and set it to true, as shown here:
cx-server {
protocol {
. . .
opcua {
enabled = true
}
}
}
You should have already configured the AzureIoTHubTemplate Thing in ThingWorx Composer. If you have not done so, do so after you finish this procedure. Refer to
Step 5. Create Azure IoT Entities in ThingWorx Composer for details; Step 6 of the procedure in that topic explains the configuration required for the AzureIoTHubTemplate Thing when using the ThingWorx Azure Industrial IoT OPC UA integration.
7. To validate the certificate presented by the ThingWorx Platform, the Azure IoT Hub Connector uses the trust store provided by the JRE (cacerts). If you are using a self-signed certificate (for development purposes only, NEVER in production), you need to import the self-signed certificate into the $JAVA_HOME/jre/lib/security/cacerts file.
If you want to use your own trust store, refer to
Minimal Configuration for Connecting to a ThingWorx Platform in Single-Server Mode for information on how to create a trust store. Then return here to add the path to and the password for your trust store, as follows:
cx-server {
protocol {
ssl {
trust-store {
file = /path/to/truststore.pfx
password = myTru$St0r2
}
}
}
}
8. Save the configuration file. You have completed the minimum required configuration. Continue to the next section.
Next Steps
At this point, you may want to configure additional properties, such as metrics reporting. If so, leave your configuration file open and follow the steps in the appropriate topic:
When you have completed the configuration, follow these steps:
1. As a best practice, encrypt the configuration for optimal security. Do this before setting the environment variable. For instructions, refer to
Step 7. Encrypt the Configuration File.
 |
If you are setting up an internal testing environment, it is strongly recommended but not required that you encrypt the configuration file. Make sure that you encrypt the Connector configuration file when setting up a production environment.
|