Step 10. Start the Azure IoT Hub Connector
Before You Begin
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