Add and Configure an MQTT Collector

Before you begin

  1. Ensure that you have an MQTT broker.
    Note: We have tested with the MQTT brokers Mosquitto 2.0.15 and HiveMQ-4.2.1. You can, however, use other MQTT brokers as well.
  2. If you want to use username/password-based authentication or certificate-based authentication to connect the MQTT broker and the MQTT collector, configure the authentication in the MQTT broker.
  3. If you want to use certificate-based authentication, ensure that the following files are available on your collector machine:
    • CA server root file
    • Private key file
    • Client certificate file

About this task

The MQTT collector collects data published to a topic using an MQTT broker. For more information, refer to the Overview of the MQTT Collector.

This topic describes how to add a collector instance using Configuration Hub. You can also add a collector instance using the RemoteCollectorConfigurator utility, which does not require you to install Web-based Clients.

Procedure

  1. Access Configuration Hub.
  2. In the NAVIGATION section, under the Configuration Hub plugin for Historian, select Collectors.
    A list of collectors in the default system appears.
  3. In the upper-right corner of the main section, select .
    The Add Collector Instance: <system name> window appears, displaying the Collector Selection section. The MACHINE NAME field contains a list of machines on which you have installed collectors.
  4. In the MACHINE NAME field, select the machine in which you want to add a collector instance.
  5. In the COLLECTOR TYPE field, select MQTT Collector, and then select Get Details.
    The INSTALLATION DRIVE and DATA DIRECTORY fields are disabled and populated.
  6. Select Next.
    The Source Configuration section appears.
  7. Enter values as described in the following table.
    Field Description
    MQTT BROKER ADDRESS Enter the host name of the MQTT broker using which you want to collect data. A value is required.
    MQTT BROKER PORT Enter the port number of the MQTT broker. A value is required.
    TOPIC Enter the MQTT topic from which you want to collect data. A value is required. You can enter multiple topics separated by commas.

    If you want to use the SparkplugB format, enter a value in the following format: namespace/group_id/message_type/edge_node_id/device_id

    where:
    • namespace is the Sparkplug version. Enter spBv1.0.
    • group_id is the ID of the group of nodes from which you want to collect data.
    • message_type is the message type from which you want to collect data. The collector processes data only from NDATA and DDATA message types.
    • edge_node_id is used to identify the MQTT EoN node within the infrastructure.
    • device_id a device attached to the MQTT EoN node either physically or logically.
    You can use the wildcard character # for any of these parameters (except for namespace).
    USERNAME Enter the username to connect to the MQTT broker. A value is required if you have configured username/password-based authentication in the MQTT broker.
    PASSWORD Enter the password to connect to the MQTT broker. A value is required if you have configured username/password-based authentication in the MQTT broker.
    CA SERVER ROOT FILE Enter the path to the CA server root file to connect to the MQTT broker. A value is required if you have configured certificate-based authentication in the MQTT broker.
    PRIVATE KEY FILE Enter the path to the private key file to connect to the MQTT broker. A value is required if you have configured certificate-based authentication in the MQTT broker.
    CLIENT CERTIFICATE FILE Enter the path to the client certificate file to connect to the MQTT broker. A value is required if you have configured certificate-based authentication in the MQTT broker.
    REQUESTED QUALITY OF SERVICE (QOS) LEVEL Select the quality of service that you want to use while collecting data from an MQTT broker.
    • QoS 0: Indicates that the message is delivered at most once or it is not delivered at all.
    • QoS 1: Indicates that the message is always delivered at least once.
    • QoS 2: Indicates that the message is delivered once.
    For more information, refer to https://www.hivemq.com/blog/mqtt-essentials-part-6-mqtt-quality-of-service-levels/.
    MQTT VERSION Select the version of the MQTT that you want to use.
    CLEAN SESSION Select one of the following options:
    • True: Select this option if you do not want to create a new session when the MQTT broker and the collector are disconnected from each other.
    • False: Select this option if you want to retain the session when the MQTT broker and the collector are disconnected from each other. This ensures that there is no loss of data. If you want to choose this option, ensure that you have selected QoS 1 or QoS 2 in the REQUESTED QUALITY OF SERVICE (QOS) LEVEL field.
    SESSION EXPIRY INTERVAL Enter the duration, in seconds, after which the data will be discarded when connection between the MQTT broker and collector is re-established.

    For example, if you enter 100 in this field, and if the MQTT broker and collector are disconnected for 90 seconds, the data is collected. If, however, the MQTT broker and the collector are disconnected for more than 100 seconds, the data will be discarded.

    This field is applicable only for MQTT V5 and only if you set the CLEAN SESSION field to False.
    CONTENT TYPE Select the format that you want to use for the payload:
    • JSON: Select this option if you want to use the KairosDB format.
    • SparkPlug B v1.0: Select this option if you want to use the Sparkplug format.
  8. Select Next.
    The Destination Configuration section appears. Under CHOOSE DESTINATION, the Historian Server option is selected by default. In addition, the DESTINATION HISTORIAN SERVER field is disabled and populated with the value you selected in the MACHINE NAME field in the Collector Selection section.
  9. Select the destination to which you want to send data, and then enter values in the available fields. You can send data to an on-premises Historian server or to a cloud destination such as Alibaba Cloud, AWS Cloud, Azure Cloud, Google Cloud, or Predix Cloud.
  10. Select Next.
    The Collector Initiation section appears.
  11. If needed, modify the value in the COLLECTOR NAME field. The value must be unique, must contain the string MQTT, and must not contain a space.
    The value that you enter:
    • Must be unique.
    • Must contain the string MQTT.
    • Must not exceed 15 characters.
    • Must not contain a space.
    • Must not contain special characters except a hyphen, period, and an underscore.
  12. In the RUNNING MODE field, select one of the following options.
    • Service - Local System Account: Select this option if you want to run the collector as a Windows service using the credentials of the local user (that is, the currently logged-in user). If you select this option, the USERNAME and PASSWORD fields are disabled.
    • Service Under Specific User Account: Select this option if you want to run the collector as a Windows service using a specific user account. If you select this option, you must enter values in the USERNAME and PASSWORD fields.
      If you have enabled the Enforce Strict Collector Authentication option in Historian Administrator, you must provide the credentials of a user who is added to at least one of the following security groups:
      • iH Security Admins
      • iH Collector Admins
      • iH Tag Admins

    You can also configure the collector to start automatically when you start the computer.

  13. Select Add.
    The collector instance is added. The fields specific to the collector section appear in the DETAILS section.
  14. If needed, enter values in available fields.
  15. In the upper-left corner of the page, select Save.
    The changes to the collector instance are saved.
  16. If needed, restart the collector.

What to do next

Specify the tags whose data you want to collect using the collector. In the CHOOSE CONFIGURATION field,
  • If you have selected Historian Configuration, specify the tags using Configuration Hub.
  • If you have selected Offline Configuration, modify the offline configuration file of the collector. By default, the file is available in the following location: <installation folder of Historian>\GE Digital\<collector name>. For information, refer to Offline Configuration for Collectors. This option is applicable only if you have selected a cloud destination.