Configure an MQTT data source connection

Note: The MQTT subscriber within the Gateway has been superseded with a standalone MQTT Communication Driver. The MQTT Gateway subscriber will be phased out in a future release of the Communication Drivers. We recommend you to modify your configuration to start using the standalone MQTT Communication Driver instead.

Add an MQTT data source connection to your Gateway Communication Driver hierarchy

• 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 Gateway Communication Driver instance. If you need to connect to multiple brokers, you can create multiple instances of the GatewayCommunication Driver. See Instantiating the Gateway for additional information.

Configure the MQTT Connection

Follow the steps below to configure the MQTT Connection.

1. Configure Broker Connection

2. Enable TLS based secure connection.

3. Enable identity based username and password (at group level)

4. Enable Store and Forward (at group level)

   Note: The steps 2, 3 and 4 are optional. The steps 3 and 4 are configured at the group level.

Step 1: Configure Broker Connection

To configure the broker connection:

5. Network Address: Enter the IP address or host name of the MQTT Broker. The number of characters must not exceed 255. The field cannot be blank. The MQTT broker connection can be configured with an IPv4 or an IPv6 address space.

6. Port Number: Specify the Port Number. The default value is 1883 (without security-enabled). For a secure connection to the broker, the default port number is 8883. Edit the value if the MQTT broker uses a non-default port.

7. To verify that the MQTT Broker is accessible, select Validate Address and Port.

   The status of the test is displayed in a Test Connection 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." Ensure that the network address, and port number are correct.

Step 2: (Optional) Enable TLS based secured connection

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.

8. Select the Secure Connection with Broker checkbox.

   The Port Number in Step1 automatically changes to 8883. Edit the port number if necessary.

9. To set up encryption and privacy to the MQTT Broker, select the version of the TLS from the Select Transport Layer Security (TLS) version. The options available are tlsv1, tlsv1.1, and tlsv1.2. The TLS version depends on the configuration settings of the MQTT broker. Adding TLS in SuiteLink encrypts the data flow between SuiteLink Client and SuiteLink Server.

   If using a self-signed certificate, it is recommended to first verify the certificate. To verify the digital certificate:

   1. Select the Download button.

   2. Select the browse (...) button to view the self-signed certificate of the broker. Do not connect to a broker if you do not trust its self-signed certificate.

      Replace the existing certificates with your own certificates in the following file path:

      C:\ProgramData\Wonderware\CertStore\sample.pem

10. Select 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." Select OK.

      Either the green, yellow or red security icon is displayed, along with the corresponding description of the connection.

      • A green security icon with the status message: Connection to the broker is secured and trusted indicates that connection to the broker is encrypted and the broker certificate is issued by a trusted certification authority (CA).

      • A yellow security icon with the status message: Connection to the broker is secured and untrusted icon indicates that connection to the broker is encrypted, but the broker certificate is self-signed and is therefore untrusted.

      • A red security icon with the status message: Connection to the broker is unsecured and untrusted indicates that the identity of the broker cannot be verified (unknown and untrusted), and the connection is unencrypted.

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

    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.

Step 3: (Optional) Enable identity based username and password in each group.

You can enable the identity based username and password in each group. This step is configured at the group level, and does not required TLS to be enabled. For more information, see Configure an MQTT group connection.

Step 4: (Optional) Enable Store and Forward settings in each group.

You can enable Store and Forward settings for each group connection. For more information, see Configure an MQTT group connection.