Add and configure an MQTT Broker connection

Add an MQTT broker connection

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. Multiple MQTT Broker connections can be added to one IOT - MQTT instance.

Configure the connection to the MQTT Broker

1. In the Broker Address field, enter the IP address of the MQTT Broker or host name. The number of characters cannot exceed 255 and this field cannot be blank.

   The MQTT Communication Driver also supports IPv6 network connectivity with the MQTT Broker. The MQTT Broker can be configured with the link-local IPv6 address of the machine on which the MQTT Broker runs.

2. The default Port Number 1883 provided is the network port parameter used by default by MQTT brokers for unsecure connections. If you enable encrypted connection in Step 2: (Optional) Encrypt connection with TLS below, the port number automatically switches to 8883, which is the default network port parameter for secure connections to MQTT brokers. You should only edit this port number if the MQTT broker uses a non-standard port.

3. The Subscriber Client ID is used to uniquely identify the subscriber connection to the broker. The specified string must be unique across all client IDs connected to the same broker. If it is blank, the MQTT Communication Driver will automatically generate a unique string.

4. The Persist Session ensures that the MQTT broker saves all the information that is relevant for the client on the broker. When persistence is enabled, the broker will store any QoS1 or Qos2 messages that have not been retrieved. In the traditional MQTT standard, the setting is referred to as the “Clean” Session. The MQTT Sparkplug standard refers to it as “Persist Session”. You enable Persistence when you want the broker to store relevant information.

   1. Select the Persist Session check box if you are a subscriber client in the MQTT network and need the broker to store QoS1 and QoS2 messages that have not been retrieved.

   2. Clear the Persist Session check box if you are a subscriber client in the MQTT network and do not need to get messages that you missed while you were offline.

      IMPORTANT: Persistence only applies to messages that have been sent with Quality of Service 1 or 2.

5. If you select the Enable checkbox inside the Subscribe to Sparkplug Infrastructure section, the subscribed data can originate from both Sparkplug and non-Sparkplug infrastructure, and the Sparkplug STATE message will be subscribed. If you do not select the Enable checkbox, the subscribed data must be in JSON and/or plain text format and the Sparkplug STATE message will not be subscribed. When the Enable checkbox is selected, the following fields will be enabled.

   3. When the Primary Application check box is checked, the broker hierarchy acts as a Primary Host and sends an Online message to the broker on the 'STATE/<Scada Host Id>' topic on the broker. This topic is used to direct Sparkplug publishers to publish the NBIRTH/DBIRTH messages to the broker.

   4. The SCADA Host ID is the name by which this application is known in the network so that all Edge Gateway (EON) nodes can monitor its connectivity to the broker as described above. Refer to the Sparkplug specification for information on the role of the SCADA Host ID.

   IMPORTANT: In an MQTT Sparkplug-based network there should only be a single node designated as the Primary Application.

   5. Specify the Listener Client ID to uniquely identify a background service to connect to the MQTT broker. The background service is used to monitor birth and death messages sent/received by the MQTT broker. You can change the Listener Client ID to fit your naming nomenclature, but you must ensure that it is unique across all MQTT connections to the same broker.

6. 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.

Enable a TLS-based secure 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 identity of the broker and is also used to encrypt communications with the broker. Trusted digital certificates are issued by the 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 secure 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 secure 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 unsecure 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 secure 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.

Enable a TLS-based secured connection:

7. To enable security, under Step 2: (Optional) Encrypt connection with TLS, select the Enable check box.

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

8. To set up encryption and privacy to the MQTT Broker, select the highest version of the TLS from the Select Transport Layer Security (TLS) version. The options available are tlsv1, tlsv1.1, tlsv1.2, and tlsv1.3.

   Note: tlsv1 and tlsv1.1 have been deprecated and are provided only for compatibility purposes.

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

   1. Click the Download button.

   2. Verify the self-signed certificate of the broker. Do not connect to a broker if you do not trust its self-signed certificate.

   3. Select Validate Security to confirm that the certificate is trusted when the security icon changes to green.

   4. If the broker prescribes a self-signed CA certificate, the validation may still fail. In this case, consult broker configuration instruction.

      1. Manually download a CA certificate from the broker.

         Note: This indicates that you are trusting the CA certificate.

      2. Save the CA certificate into one of the file locations on the machine.

      3. Specify the location of the saved CA certificate in the CA File field.

      4. Select Validation Security to confirm again if the certificate is trusted.

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 green, yellow, or red security icon is displayed, along with the corresponding description of the connection.

    • If the security validation is not successful, a dialog will be prompted advising the reason and possible corrective action.

Note: You can reset the value of the CA certificate to the system default by clearing the CA File field and selecting Validation Security.

Enter Connection and/or User Identity (optional)

Note: Before configuring this section, you should enable the secure connection to the broker by selecting the Enable checkbox under Step 2: (Optional) Encrypt connection with TLS section.

11. Select the Client Authentication check box if the broker provides a certificate which must be used for connection.

    1. In the Client Certificate File field, browse or specify the location of the applicable client certificate.

    2. In the Client Key File field, browse or specify the location of the respective client key file.

    3. In the Client Key Password (optional) field, enter the password of the client key file if applicable. Clear this field if the Client Key file is not password-protected.

12. Under User Identity, select the Enable check box to turn on user authentication for subscribing/publishing to MQTT messages.

    Note: If you enable this option, it is highly recommended that you enable MQTT Connection Security to protect the username and password.

    MQTT Communication Driver uses the user name and password settings that you enter here to connect to the configured MQTT broker.

13. Select Validate Identity, to verify that the MQTT Broker can be accessed on the configured MQTT channel.