Step 10. Start the Azure IoT Hub Connector

Getting an Azure IoT Hub Connector Up and Running > Step 10. Start the Azure IoT Hub Connector

Before You Begin

Before you attempt to run the Azure IoT Hub Connector, make sure that you have set up environment variables, as explained in Step 9. Set the Environment Variables for the Azure IoT Hub Connector. In addition, make sure that you have run the service that grants permissions and visibility to the Connector (Step 10).

Running the Connector as a Service on Linux

For best security and operation practices always run the Connector as a service. Starting and stopping the service ensures that the Connector is always run as the proper user. However, for troubleshooting, additional information may be displayed, such as the stack trace of an exception, that does not make it into the logs but shows up in the console window.

To run the Connector as a service on Linux, create a systemctl startup file and store it in /usr/lib/systemd/system/. Here is an example:

# Systemd unit file for TWX MS IoT Hub Connector
# should go into /usr/lib/systemd/system
[Unit]
Description=ThingWorx Azure IoT Hub Connector

[Service]
Type=simple

EnvironmentFile=/appl/twxAzureIoTHubConnector/connector/bin/iothub_environment

ExecStart=/appl/twxAzureIoTHubConnector/connector/bin/azure-iot
ExecStop=/bin/kill -15 $MAINPID

User=twadmin
Group=twadmin
UMask=0007
RestartSec=300
Restart=always

[Install]
WantedBy=multi-user.target

The EnvironmentFile is used in conjunction with the systemd service file. It is a way of passing all the environment settings into the Connector when the service run. If you run the Connector from the command line, you need to use export to set all the variables in your shell session before running. All of the environment settings are listed in Sample Environment Settings.

If you are running the Connector on the same machine as ThingWorx (NOT recommended), add the line, After=tomcat.service, after Description=ThingWWorx Azure IoT Hub Connector.

To check that the Connector is running and communicating with ThingWorx and Azure log in to ThingWorx Composer, and navigate to the AzureIotHub Thing that represents your Azure IoT Hub. An icon next to the Thing name shows whether it is connected:

Connected

Not Connected

Starting the Connector from a Command Line

If you are in a development environment and just want to start up and run the smoke tests, you can start the Azure IoT Hub Connector from a command line:

1. Open a shell or a Command Prompt window.

2. Change the current directory to the bin subdirectory of the Azure IoT Hub Connector installation.

3. To start the Azure IoT Hub Connector, use the command appropriate to the base operating system. If you have NOT set the environment variable, make sure that you specify the required JRE properties listed above. For example:

a. For Linux users:

{baseDir}/ThingWorx-Azure-IoT-Hub-Connector-v.v.v/ThingWorx-
Azure-IoT-Hub-Connector-v.v.v.v/connector/bin/azure-iot

b. For Windows users, you first need to edit the azure-iot.bat file slightly, due to a problem with command size limitations. The command that launches the application uses a very long classpath. Near the top of the azure-iot.bat file, locate the following line:

set APP_HOME=%DIRNAME%..

Remove the %DIRNAME% variable, but leave the two periods. You must run the azure-iot.bat script from the bin directory. You may want to move the bin subdirectory closer to the root of your file system to prevent the classpath from becoming too long for command line limitations.

c. When ready, run the azure-iot.bat script:

C:\ThingWorx-Azure-IoT-Hub-Connector-v.v.v\ThingWorx-
Azure-IoT-Hub-Connector-v.v.v.v\bin\azure-iot.bat

d. The Connector starts up and begins processing data, displaying messages in the console where you started it.

e. If errors or stack traces appear, or if the program aborts unexpectedly, here are steps you can take:

a. Ensure that JRE 8 (1.8_u161) or later is installed and in use.

b. Check the configuration file for potential issues.

c. Check the name of your hub. If it exceeds 25 characters, change it so that it is shorter.

To check that the Connector is running and communicating with ThingWorx and Azure, log in to ThingWorx Composer, and navigate to the AzureIotHub Thing that represents your Azure IoT Hub. An icon next to the Thing name shows whether it is connected:

Connected

Not Connected

You can now run the smoke test.

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