Add an MQTT Sparkplug B Collector Instance using RemoteCollector Configurator

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 RemoteCollectorConfigurator utility. If you want to add an offline collector instance, refer to Add an Offline Collector Instance.

Procedure

  1. Run the RemoteCollectorConfigurator.exe file. By default, it is located in the following folder: C:\Program Files\GE Digital\NonWebCollectorInstantiationTool.
    A list of options to manage collector instances appears.
  2. Connect to the collector machine by entering 1 or 2, depending on whether collectors are installed locally or on a remote machine.
  3. To create a collector instance using the RemoteCollectorConfigurator utility, you need to provide parameters in a JSON format. For this you can create a sample JSON using this tool. To create sample JSON, enter 7.
  4. To create a sample JSON file for MQTT Sparkplug B collector, enter 21.
  5. To set Historian as the destination type, enter 1.
  6. Enter the folder path where you want the sample JSON file to be created. By default, the file will be created in the same folder in which the RemoteCollectorConfigurator utility is located.
    A sample JSON file with name “SampleSparkplugB.json” is created in the given location.

    Sample JSON File

    {
"CollectorSystemName":"TESTSYSTEM",
"DestinationHistorian":"TESTSYSTEM",
"General1":"HostName=localhost|Port=|ClientId=|PrimaryHostId=|GroupId=test|EdgeNodeId=#|DeviceId=|Username=|Password=|Cafile=|Certfile=|PrivateKeyfile=|Version=MQTT_V311|ReorderTimeout=",
"General2":"<interfacename>.<groupid>.<edgenodeid>.<deviceid>.",
"General3":"*",
"General4":"",
"General5":"",
"InterfaceDescription":"Sample SparkplugB Collector",
"InterfaceName":"SampleSparkplugBCollector",
"InterfaceSubType":"SparkplugB",
"SourceHistorianUserName":"",
"SourceHistorianPassword":"",
"Type":"16",
"SamplerId":"",
"MTLSEnable":"false",
"DataPathDirectory":"C:\\Proficy Historian Data",
"CollectorDestination":"Historian",
"DestinationHistorianUserName":"",
"DestinationHistorianPassword":"",
"mode":"1",
"winUserName":"",
"winPassword":""
}
  7. Configure the values as specified the following table:
    Table 1.
    Field Descriprion
    CollectorSystemName (Mandatory) Name of the machine on which the Collector is installed.
    DestinationHistorian (Mandatory) Name of the destination Historian machine.
    General1
    HostName (mandatory) MQTT broker Ip or hostname.
    Port (mandatory) MQTT broker port.
    ClientID Unique name to identify the client.
    PrimaryHostID (mandatory) 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.
    GroupId (mandatory) 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. Use of the wildcard "+" is supported.
    EdgeNodeId (mandatory) 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. Use of the wildcards "+" and "#" are supported.
    DeviceId (mandatory) 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. Use of the wildcards "+" and "#" are supported.
    Username 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 The password to connect to the MQTT broker. A value is required if you have configured username/password-based authentication in the MQTT broker.
    Cafile 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.
    Certfile 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.
    PrivateKeyfile 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.
    ReorderTimeout Enter the duration for waiting before sending a CMD message if a sequence is skipped. You can enter the duration in milliseconds.
    Version The version of the MQTT that you want to use. That is, MQTT_V311 or MQTT_V5.
    General2
    <interfacename>.<groupid>.<edgenodeid>.<deviceid>. The 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 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”.
    General3
    "*" Tag include mask field The 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.
    General4
    "" Tag exclude mask field The 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".
    General5
    InterfaceDescription A description of the collector instance.
    InterfaceName A name of the collector instance.
    Note: If you will use this collector on Historian Administrator, the name must include Sparkplug B in it.
    InterfaceSubType Sparkplug B. Do not change this field.
    SourceHistorianUserName (optional) username of the source Historian.
    SourceHistorianPassword (optional) password of the source Historian.
    Type 16. Do not change this field.
    SamplerId (optional) The ID of the sampler.
    MTLSEnable False.
    DataPathDirectory The directory path where you want the data to be stroed. It is recommended to use C:\\Proficy Historian Data.
    CollectorDestination Historian. Do not change this field.
    DestinationHistorianUserName (optional) username of the destination Historian.
    DestinationHistorianPassword (optional) password of the destination Historian.
    Mode 1. Do not change this field.
    winUserName (optional) username of the window user.
    winPassword (optional) password of the window user.
    Note: Do not change the case of the keys in the JSON file.
  8. Run the RemoteCollectorConfigurator.exe file. By default, it is located in the following folder: C:\Program Files\GE Digital\NonWebCollectorInstantiationTool.
    A list of options to manage collector instances appears.
  9. Connect to the collector machine by entering 1 or 2, depending on whether collectors are installed locally or on a remote machine.
  10. To create the collector instance, enter 4.
  11. To create the instance using the updated JSON file, enter 2.
  12. Enter the location where the updated JSON file is saved.
  13. On the keyboard, press Enter.
    The MQTT Sparkplug B collector instance is created.

What to do next

  • Specify the tags whose data you want to collect using the collector.
  • If you did not enter a value, modify the offline configuration file of the collector. By default, this file is available in the following location: <installation folder of Historian>\GE Digital\<collector name>. For information, refer to Creating Offline Configuration XML file.