The Tetra KEPServerEX Connector uses the KEPServerEX IoT Gateway Plugin to publish values from the KEPServerEX-connected devices to a Message Queuing Telemetry Transport (MQTT) broker. This workshop shows how to install an MQTT broker and set up IoT agents.

The following example procedure uses Eclipse Mosquitto for an MQTT broker and installs it on the same Microsoft Windows Amazon Elastic Compute Cloud (Amazon EC2) instance as the KEPServerEX software.

Set up a Mosquitto MQTT Broker

To set up a Mosquitto MQTT broker, do the following.

Install Eclipse Mosquitto

1. Download the Mosquitto installer for Windows x64 from the Download page in the Mosquitto documentation.
2. In File Explorer on your local machine, right click the Mosquitto installer file. Then, choose Copy.
3. Right click the desktop on your Windows Amazon EC2 instance.
4. Double click the installer to run it. Leave all default settings as they are and click through the prompts to complete the installation.
5. In the installation directory of Mosquitto (C:\Program Files\mosquitto) find the file named mosquitto.conf.
6. Open the mosquitto.conf file and replace its contents with the following:

listener 1883
allow_anonymous true

📘

NOTE

Windows may warn you that there are no default apps for opening the mosquitto.conf file. If this happens, you can use Windows Notepad to open and edit the file.

Set Up Mosquitto as a Windows Service

1. In Windows, open Windows PowerShell as an administrator.
2. In PowerShell, navigate to the Mosquitto install directory and run the following command:

./mosquitto install

3. After Mosquitto is installed, restart the Amazon EC2 instance.

📘

NOTE

Keep in mind the following when installing Mosquitto:

• You can choose to run the broker manually, but there may be times where you need to restart the Amazon EC2 instance, so running it as a service will enable the broker to start when Windows starts.
• When installing the service, you may get a warning that the service is already installed. You can ignore the warning and continue.
• If you don't want to restart the computer after installing the Mosquitto service, you can run the following commands in a command prompt as an administrator instead:

sc query mosquitto
sc start mosquitto
sc query mosquitto

Verify That the Mosquitto Service Is Running

Verify that the Mosquitto service is running and configured correctly by doing the following:

1. Open PowerShell as an administrator.
2. Navigate to the Mosquitto install directory (C:\Program Files\mosquitto).
3. Run the following command:

./mosquitto_sub.exe -t TEST

4. Open another PowerShell terminal session as an administrator.
5. Navigate to the Mosquitto install directory (C:\Program Files\mosquitto).
6. Run the following command:

./mosquitto_pub.exe -t TEST -m "hello world"

📘

NOTE

If the Mosquitto service is running and configured correctly, hello world appears in the first PowerShell terminal session that you opened.

Open the Mosquitto Port in Windows Firewall

After the Mosquitto service is running, it needs to be available outside of the Amazon EC2 instance for the connector to use it. This is done by opening the port that the Mosquitto broker uses in Windows Firewall.

To open the Mosquitto port in Windows Firewall, do the following:

1. Open Windows Firewall by using the search bar on your local machine.
2. On the Firewall & network protection settings page, choose Advanced Settings. Windows Defender opens in a new window.
3. Right click on Inbound Rules. Then, choose New Rule. The Inbound Rule Wizard opens.
4. For Rule Type, choose Port.
5. Choose Next. The Protocol and Ports page opens.
6. On the Protocol and Ports page, leave TCP checked. Then, choose Specific local ports and enter 1883 in the text field.

📘

NOTE

The default MQTT port is 1883. If you changed the port during configuration, make sure that you enter the configured port number. To verify that the port has been configured correctly, you can rerun the commands in the Verify That the Mosquitto Service Is Running section from your local machine. Make sure that you're connected to the non-production virtual private network (VPN) and use the -h flag to provide the IP address of your Amazon EC2 instance (for example, mosquitto_sub -t TEST -h 10.60.4.57).

7. Choose Next. The Action page appears.
8. Select Allow the connection. Then, choose Next. The Profile page appears.
9. Leave all options on the Profile page (Domain, Private, and Public) checked. Then, choose Next. The Name page appears.
10. For Name, enter a name of the new firewall rule, such as Allow inbound MQTT traffic.
11. Choose Finish.

Install the Java Runtime Engine

🚧

IMPORTANT

Make sure that you use the 32-bit version of Java and the Windows Offline installer.

Before setting up the KEPServerEx IoT Gateway Plugin, make sure that the Java Runtime Engine (JRE) is installed on your Windows Amazon EC2 instance. To download Java, see Java Downloads for All Operating Systems in the Java documentation. Then, copy the installer to your Windows Amazon EC2 instance and install it.

📘

NOTE

After setting up the IoT Gateway Plugin, you may get an error in the KEPServerEX configuration logs that says Failed to launch IoT Gateway: no suitable 32-bit JRE was configured or found. To resolve the error, stop and restart KEPServerEX. If that doesn’t resolve the issue, restart the Amazon EC2 instance.

Activate and Configure the KEPServerEX IoT Gateway Plugin

After the MQTT broker is set up, the KEPServerEX IoT Gateway Plugin must be activated and configured. This is the feature that connects data collected by KEPServerEX to the MQTT broker.

To activate and configure the IoT Gateway Plugin, do the following.

Configure an IoT Gateway Agent

1. In the Windows taskbar, right click the KEPServerEX Icon. Then, select Configuration.
2. In the Configuration pane, expand the IoT Gateway option. Then, select Add Agent. The New Agent window appears.
3. For Name, a name for the agent, such as Tetra Agent.
4. For Type, select MQTT Client from the drop-down list.
5. Choose Next. The MQTT Client - Broker window appears.
6. In the MQTT Client - Broker window, enter the following:
   • In the MQTT Broker section, for URL, leave the URL as the default value if you’ve installed the MQTT broker on the same server as KEPServerEX. If the broker is installed on another server, make sure that the URL points to your MQTT server.
   • For Topic, enter a topic name. This can be any name, but it should only be used for data to be uploaded to TetraScience. This example procedure uses tetrascience.
   • In the Publish section, for QoS, select 2 (Exactly Once).
   • For Rate (ms), enter 1500.
7. Choose Next. The MQTT Client - Security window appears.
8. In the MQTT Client - Security window, enter the following:
   • For Client ID, enter a descriptive client id, such as kepserverex.
   • If you configured your MQTT broker to require credentials, enter them in the Username and Password fields; otherwise, leave these fields blank.
9. Check the KEPServerEX configuration logs for a log message stating the IoT Gateway Plugin has started.

📘

NOTE

If you see an error log like the following one and have already installed the JRE, try restarting KEPServerEX. If that doesn’t resolve the error, restart the Amazon EC2 instance.

Example Error Message
Failed to launch IoT Gateway: no suitable 32-bit JRE was configured or found

Configure KEPServerEX Tags

To tell KEPServerEX which devices it should publish values for to the MQTT broker, you must add KEPServerEX tags to the IoT Gateway Agent that you configured. The following example procedure uses simulated tags.

To configure KEPServerEX tags, do the following:

1. In the Windows task bar, right click the KEPServerEX Icon. Then, select Configuration.
2. Expand the IoT Gateway section. Then, select the name of the IoT Gateway Agent that you set up earlier.
3. In the main panel, select the Add IoT Items button.
4. In the window that pops up, select Simulation Examples. Then, choose Functions. Choose as many of the simulation tags as you want.
5. Choose Apply. The IoT Items page opens.
6. On the IoT Items page, leave the default settings as they are. Then, choose OK.

Start the KEPServerEX Runtime Service

In the Windows taskbar, right click the KEPServerEX Icon. Then, choose Start Runtime Service.

📘

NOTE

If you're using a trial license for KEPServerEX, you will see a warning that the IoT feature is only available for two hours. When the time is up, stop the KEPServerEX instance and restart it. This action restarts the timer for two hours.

Verify the Connection Between KEPServerEX and the MQTT Broker

1. Open a PowerShell terminal session.
2. Navigate to the directory where Mosquitto was installed, by running the following command:

cd 'C:\Program Files\mosquitto'

3. Run the following command:

mosquitto_sub -t <topic_name>

📘

NOTE

Make sure that you replace <topic_name> with the name that you chose to verify that KEPServerEX is now publishing data to MQTT at the configured topic. The command lists any messages received from KEPServerEX on the console.