Add an MQTT Sparkplug B Collector Instance using Configuration Hub

Before you begin

  1. Install the Historian server and collectors.
  2. Ensure that you have an MQTT broker.
  3. If you want to use username/password-based authentication or certificate-based authentication to connect the MQTT broker and the MQTT Sparkplug B collector, configure the authentication in the MQTT broker.
  4. 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

This topic describes how to add and configure an MQTT Sparkplug B collector instance using Configuration hub. You can also add and configure an MQTT Sparkplug B collector instance using RemoteCollectorConfigurator.

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 Sparkplug B Collector, and then select Get Details.
    Note: The INSTALLATION DRIVE and BASE DATA DIRECTORY fields cannot be changed. This is the drive location and the data directory folder that you provided during Collectors installation.
    The INSTALLATION DRIVE and DATA DIRECTORY fields are populated with the drive location and the data directory folder.
  6. Select Next.
    The Source Configuration section appears.
  7. Enter the values as described in the following table:
    Field Description
    BROKER CONFIGURATION
    BROKER ADDRESS Enter the host name of the MQTT broker using which you want to collect data. A value is required.
    BROKER PORT Enter the port number of the MQTT broker. A value is required.
    CLIENT ID Enter the client ID of the MQTT Sparkplug B collector is running. This is required if you want to send the data to a cloud destination. If you do not have a client ID set up, by default, the interface name is taken.
    PRIMARY HOST ID Enter the unique host ID of the Collector. The Collector will publish the STATE message topic using this host ID and then the Publisher will subscribe and start publishing the topics to this host ID.
    REORDER TIMEOUT Enter the duration for waiting before sending a CMD message if a sequence is skipped. You can enter the duration in milliseconds.
    MQTT VERSION Select the version of the MQTT that you want to use. The following versions are supported:
    • MQTT_V311
    • MQTT_V5
    TOPIC: The parameters that need to be included in the topic:
    Namespace/Groupname/<Message Type>/NodeID/<DeviceID>

    You can also use wildcards in the GROUP ID, EDGE NODE ID, and DEVICE ID fields. The following wildcards are supported:

    • + (single-level wildcard): Supported for all the three fields.
    • # (Multi-level wildcard): Supported for the EDGE NODE ID and DEVICE ID
    + (Single-level wildcard): Can be used to subscribe to only one topic level. For example, if you subscribe to a topic <Admin>/+/<ABC-123>, you will receive messages from all the nodes corresponding to the group and device. That is,
    <Admin>/Node1/<ABC-123>
    <Admin>/Node2/<ABC-123>
    <Admin>/Node3/<ABC-123>
    ...
    <Admin>/Noden/<ABC-123>
    # (Multi-level wildcard): Can be used to subscribe to any number of levels within a topic. For example, if you subscribe to a topic <Admin>/#, you will receive messages from all the nodes and devices corresponding to the group,
    <Admin>/Node1/<ABC-123>
    <Admin>/Node2/<ABC-123>
    <Admin>/Node3/<ABC-123>
    <Admin>/Node1/<ABC-124
    <Admin>/Node2/<ABC-124>
    ...
    <Admin>/Noden/<Devicen>
    
    GROUP ID Enter the Sparkplug B group name to which you want your collector to subscribe. If this is empty along with the other fields below TOPIC, the collector will subscribe to all the available groups, nodes, and devices.
    EDGE NODE ID Enter the Sparkplug B edge node ID to which you want your collector to subscribe. If this is empty, then the Collector will subscribe to all the edge nodes corresponding to the entered GROUP ID. If the GROUP ID and DEVICE ID are also empty, then the collector will subscribe to all the available groups, nodes and devices.
    DEVICE ID Enter the Sparkplug B device name. If this is empty, the collector subscribes to node messages if a NODE ID is entered, otherwise, if a DEVICE ID is entered, it subscribes to device messages.
    TAG CONFIGURATION
    TAG NAME PREFIX FORMAT
    ELEMENT Enter a prefix to be included in the tag. By using this field, you can clearly identify a tag. For example, you can clearly differentiate the tags that are collected.

    The following options are available:

    • <interfacename>
    • <groupid>
    • <edgenodeid>
    • <deviceid>

    For example, if all four fields are provided and the interface/collector name is "sparkplug1" and the Topic contains group id = g1 edge node id = n1, device id = d1 then device tags will be created in Historian as “sparkplug1.g1. n1.d1.tag1”.

    DELIMITER Enter a delimiter you need to be included in the tag. You can use any special characters as delimiter. However, it is recommended that you use a delimiter that is ideal and clear to be identified. For example, "/", ".", "_".
    Note: "?" and "*" are not allowed.
    PREVIEW The preview of how the tags will be created and stored based on the TAG PREFIX and the DELIMTER that you selected.
    TAG MASK
    TAGS TO ADD Provide a mask along with wildcard to collect those tags that include the mask you provided and store in Historian. For example, *Pressure*. This will collect all the tags that begin with "Pressure". If you enter Pressure*, all the tags that end with "Pressure" will be collected. Similarly, if you enter *Pres?, all the tags that contain "pres" at the beginning will be collected. It can be "Pressure", "Press", or "Pres1".
    Note: Whenever a new tag is collected, the collector verifies the tag availability in the Historian and, if not present, adds the tag, then adds the data samples, streaming the data to the Historian server or a cloud destination.
    TAGS TO EXCLUDE Provide a mask along with wildcard to exclude those tags that include the mask you provided. For example, *Pressure*. This will exclude all the tags that begin with "Pressure". If you enter Pressure*, all the tags that end with "Pressure" will be excluded. Similarly, if you enter *Pres?, all the tags that contain "pres" at the beginning will be excluded. It can be "Pressure", "Press", or "Pres1".
    AUTHENTICATION
    USER CREDENTIALS
    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.
    SSL/TLS
    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.
  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 collector machine name.

  9. Select the destination to which you want to send data, and then enter the values in the corresponding fields. You can send data to an on-premises Historian server or to a cloud destination.
    1. If you need to send data to a cloud destination, select the cloud destinations as needed.
      • Predix Timeseries- Select this if you need to send data to Predix cloud. For more information, refer to Predix Cloud.
      • Azure IoT Hub- Select this if you need to send data to Azure Cloud in KairosDB format. For more information, refer to Azure IoT Hub (KairosDB format).
      • MQTT- Select this if you need to send data to any of the following cloud destination.
        • Alibaba cloud. For more information, refer to Alibaba Cloud.
        • AWS cloud. For more information, refer to AWS Cloud.
        • Google cloud. For more information, refer to Google Cloud.
    2. If you need to send data to an on-premises Historian server, select Historian Server.
      If you created security groups or enabled a strict client/collector authentication, enter the USERNAME and PASSWORD of the on-premises Historian server that you created during the installation of the collector.
      If you entered the USERNAMEand PASSWORD, select Test Connection. This will help you to test if the Historian server that you are trying to connect is valid or if the credentials that you entered are valid.
      If the entered credentials are valid, a successful connection message appears.
  10. After you selected the destination, select Next.
    The Collector Initiation section appears.
  11. If needed, modify the value in the COLLECTOR NAME field.
    Note: If you will be using the collector in Historian Administrator, the COLLECTOR NAME must include Sparkplug B in it.
    The value that you enter:
    • Must be unique.
    • 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.
  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.
  • If needed, you can configure the collector instance.