Running the Smoke Test
After installing, configuring, and starting up the Azure IoT Hub Connector, you need to determine if the system is set up properly. Make sure that you have
set up the environment variable, AZURE_IOT_OPTS. The Connector smoke test is a standalone executable that you can run. This test performs several validations to determine if the Connector is configured and working properly.
This simple Java program runs on the command line. The smoke test tool parses the Connector configuration parameters that are specified as Java system properties in the environment variable, AZURE_IOT_SMOKETEST_OPTS. Assuming that you are using an encrypted configuration file, the smoke test requires the following JRE properties be set:
• -Dsecret.management.config.file={path-to-encryption-conf-file}
• -Dconfig.file={path-to-Azure-Connector-encrypted-config-file}
 |
If you are using an unencrypted configuration file, the smoke test also requires that -Dconfig.plaintext be set to true.
|
• The tool establishes a connection to the Azure IoT Hub to send telemetry messages (events) and perform file transfers.
• The tool creates a connection to the ThingWorx Platform for purposes of creating Things and performing validations that the Connector is working as expected.
• The tool logs the outcome of each validation step (either SUCCESS or FAILURE) to the console.
• The tool logs an overall test result (either SUCCESS or FAILURE).
• Regardless of the outcome, the tool deletes the Thing that it created from the ThingWorx Platform.
If any of the verification steps fail, a diagnostic message that will help you resolve the issue appears.
|
Step
|
Validation
|
|---|---|
|
Verify that the Connector can establish a connection to the ThingWorx Platform, using the properties set in the configuration file.
|
|
|
Verify that the configuration parameters have been specified. For this test to run, you must have set the environment variable, AZURE_IOT_SMOKETEST_OPTS, to point to the configuration file for the Connector. This validation parses the configuration file to validate that all required settings are present.
In addition, retrieves the configuration of the hub Thing from the ThingWorx Platform and decrypts the encrypted credentials.
|
|
|
Verify that the ConnectionServicesHub specified in the configuration file of the Connector exists.
|
|
|
Verify that the Connector can create a Thing that extends the AzureIotThing Thing Template. The created Thing will have a random name and the remote properties to verify property writes sent to ThingWorx Platform from the Edge. This test runs in a ThingWorx Platform 9.0 instance that is running in single-server mode. It also runs in ThingWorx HA Clustering mode.
|
|
|
Verify sending telemetry event messages to Azure IoT and then validate that the Connector receives and converts those message into property writes on the ThingWorx Platform.
|
|
|
With v.3.0 of the Azure IoT Hub Connector, you need to manually clean up after the smoke test. This means removing the AzureIotThing that it created from the ThingWorx Platform and from Azure IoT. Note that, conversely, creating a Thing on the platform does NOT create an Azure IoT Device.
|
A log message is written at the completion of each test. If necessary, you can enable debug level logging to view other messages. For example, if a test throws an exception, first refer to the topic,
Troubleshooting the Smoke Test, for assistance, and if the information there does not suffice, try enabling debug level logging.
After all validations execute, the overall test result is calculated and logged. For example:
2020-12-0213:44:13.307INFO Overall test result=SUCCESS,5tests completed,0failed,0skipped
|
|
If you are using the ThingWorx Azure Industrial IoT OPC UA integration and have started the Connector and run the smoke test, go to
Step 6. Setting Permissions for Non-Administrative Users.
|
v
How to Run the Smoke Test
This procedure assumes that you have extracted the Azure IoT Hub Connector distribution bundle, configured the Connector, encrypted the credentials for the Azure IoT Hub, set up the platform and Connector for decrypting the credentials, encrypted the configuration file, and
set the AZURE_IOT_SMOKETEST_OPTS environment variable so that it points to the configuration file. To run the smoke test, follow these steps:
1. Start the ThingWorx Platform, if it is not running.
2. Start the Azure IoT Hub Connector, if it is not running.
3. Open a shell (Linux) or Command Prompt (Windows, Run as Administrator) and enter the commands appropriate to the operating system where your Connector is running:
◦ Linux
# cd Thingworx_Azure-IoT-Hub-Connector-<version>/connector/bin# ./azure-iot-smoketest
◦ Windows
c:\> cd Thingworx-Azure-Iot_Hub_connector-<version>\connector\bin:\> azure-iot-smoketest.bat
By default the tool prints log messages to stdout (e.g., the shell or Command Prompt window). Here is sample output from the tool:
INFO Finished test 1/5: Validate the Azure IoT Hub Connector configuration file result=SUCCESS
INFO Finished test 2/5: Validate connection to ThingWorx Platform result=SUCCESS
INFO Finished test 3/5: Validate that the ConnectionServicesHub Thing exists result=SUCCESS
INFO Finished test 4/5: Validate creating test Thing on the Thingworx Platform result=SUCCESS
INFO Finished test 5/5: Validate sending telemetry data (properties) to Azure IoT Hub device result=SUCCESS
INFO Overall test result=SUCCESS, 5 tests completed, 0 failed, 0 skipped
INFO Finished test 2/5: Validate connection to ThingWorx Platform result=SUCCESS
INFO Finished test 3/5: Validate that the ConnectionServicesHub Thing exists result=SUCCESS
INFO Finished test 4/5: Validate creating test Thing on the Thingworx Platform result=SUCCESS
INFO Finished test 5/5: Validate sending telemetry data (properties) to Azure IoT Hub device result=SUCCESS
INFO Overall test result=SUCCESS, 5 tests completed, 0 failed, 0 skipped
If any errors occur, an exception is written to the log. Refer to
Troubleshooting the Smoke Test for assistance.