Configuring an MQTT Data Source Connection

To add an MQTT data source connection to your OI Gateway hierarchy

1. Right-click Configuration in the hierarchy, and select Add MQTT_BROKER Connection from the shortcut menu.

   A new connection is created in the hierarchy tree, named "New_MQTT_BROKER_000" by default. Rename it, if desired. Only one MQTT Broker connection can be added to each OI Gateway instance. If you need to connect to multiple brokers, you can create multiple instances of the OI Gateway. See Instantiating the Gateway for additional information.

   Note: An OI Server Professional level license is required to create multiple instances of the OI Gateway.

2. Configure the connection to the MQTT Broker.

   1. In the Network Address field, enter the MQTT Broker's IP address or host name. The number of characters cannot be more than 255. The field cannot be blank.

   2. Edit the Port Number if your MQTT broker uses a non-default port. TCP/IP port 1883 is the default port without security enabled. Port 8883 is the default port for a secure connection to the broker.

3. Click the Validate Address and Port button to verify that the MQTT Broker can be accessed. The status of the test is displayed in a dialog. The initial status is "Connecting to host...."

   • If the connection to the MQTT Broker is successful, the final status is "Connection to host successful."

   • If the MQTT Broker cannot be accessed, the final status is "Unable to connect to host." Check that the network address and port number are correct.

To enable a TLS-based secured connection (optional)

A digital certificate is required to establish a secure connection with an MQTT broker. The digital certificate, also called a public key certificate, confirms the identify of the broker and is also used to encrypt communications with the broker. Trusted digital certificates are issued by official, trusted agencies known as certification authorities (CA), and guarantee the identity of the broker. In contrast, self-signed digital certificates are issued by private parties and do not guarantee the identity of the broker.

When you validate the security setting of the broker connection, three results are possible:

• A green security icon is displayed with the text Connection to the broker is secured and trusted.

  The green security icon indicates that connection to the broker is encrypted and the broker's certificate is issued by a trusted certification authority (CA).

• A yellow security icon is displayed with the text, Connection to the broker is secured and untrusted.

  The yellow security icon indicates that connection to the broker is encrypted, but the broker's certificate is self-signed and is therefore untrusted. See Verifying a Self-Signed Certificate from an Untrusted MQTT Data Source for additional information.

• A red security icon is displayed with the text, Connection to the broker is unsecured and untrusted.

  The red security icon indicates that the identity of the broker cannot be checked and the connection is unencrypted. Since the broker's identity cannot be verified, it is considered unknown and untrusted.

Note: Enabling a secured connection is separate from connecting to a broker. Once security has been successfully enabled, it is possible to see a green security icon without being connected to the broker. However, you must be connected to the broker to be able to validate security.

4. To enable security, select the Secure Connection with Broker checkbox.

5. The port number automatically changes to 8883. Edit the port number if necessary.

6. Click Validate Security, to check that an encrypted connection over TLS can be established with the MQTT Broker.

   • If the security validation is successful, the final status is "Security Validation completed." Click OK, and either the green, yellow or red security icon is displayed, along with the corresponding description of the connection.

   • If the security validation is not successful, the final status is "Security Validation failed!" Click OK, and edit the settings as necessary.