The MQTT SparkplugB Collector Plugin

This plugin provides access to MQTT topics serving SparkplugB payloads with protobuf encoding

Simple Configuration

Settings

Subscribing to Topics and Excluding Tags

Introduction

The Collector config provides a front end editor for the MQTT Sparkplug Collector. By default, this is found at localhost:4521 or the appropriate port number if you have multiple Collectors.

Select the Config tab.

Modifying data from this page will effect multiple config files, all located within C:\Program Data\Flow Software\Timebase\Collector\Config for Windows, or /config for Docker.

Changing the Data Source Type or Targeted Historian will write to collector.config, adding or modifying the Target Historians will write to historians.config, and using the Settings window and editing the JSON object to define how to connect to an broker, to subscribe to tags, and to interpret the messages received from those subscriptions will modify the settings.config file.

Simple Configuration Example

When subscribing to a SparkplugB topic, you can specify your Group ID to subscribe on.

The following example plugin configuration file can be used to subscribe and parse the SparkplugB message. Notice the Subscription Type is set to 1(This is a placeholder for potential future versions of the Sparkplug specification):

{
  "Settings": {
    "Host": "<MQTTHostOrIPAddress>",
    "Port": 8883,
    "Username": "<UsernameGoesHere>",
    "Password": "<PasswordGoesHere>",
    "UseTls": false,
    "Subscriptions": [
      {
        "Type": 1,
        "QoS": 2,
        "Topics": [
          "spBv1.0/<GroupIDHere>/#"
        ]
      }
    ]
  }
}

The plugin type will be SparkplugB.

The dataset created in the Historian will be Sparkplug Data.

The Settings section has defined the broker connection and one Subscription.

The Subscription expects a SparkplugB message on a topic that matches spBv1.0/<GroupIDHere>/#.

Settings

The following settings can be set for the SparkplugB plugin:

  "Settings": {
    "Host": "broker.hivemq.com",
    "Port": 8883,
    "UseTls": true,
    "Subscriptions": [
      {
        "Type": 1,
        "QoS": 2,
        "Topics": [
          "spBv1.0/<GroupIDHere>/#"
        ]
      }
    ]
  }

Connection

Host string required The hostname or IP address of the Historian to connect to
Port int The port number of the Historian broker. Default value is 4511.
UseTls bool Specifies whether to use TLS/SSL for secure communication with the broker. Default value is false
ClientId string Specifies a unique identifier that identifies the client connecting to the broker. Default value is a `random identifier`

Authentication

Username string The username required to authenticate with the MQTT broker
Password string The password required to authenticate with the MQTT broker. If a Username is provided, then a Password must also be provided.

Subscriptions

Subscriptions array of Subscription required

Subscription Definition

Payload

Type PayloadTypes required The data format of the payload expected from topics on this subscription. Currently there is only one type for SparkplugB message types and is reserved for future implementations of the Sparkplug protocol.

QoS QualityOfServiceTypes The MQTT Quality of Service required for topics on this subscription. Default value is Exactly once.

Topics

Topics array of string Topics are case-sensitive and composed of one or more levels, separated by a forward slash ("/"). "+" represents a single-level wildcard (e.g. "rooms/+/temperature"). "#" represents a multi-level wildcard that can only be used as the last character in the topic, preceded by a forward slash (e.g. "rooms/#"). Avoid leading or trailing slashes. Avoid empty topics (e.g. "rooms/temperature"). All Sparkplug messages are posted on a topic starting with a topic prefix called spBv1.0 followed by a GroupID
Filter string A tag filter is case-sensitive regex string applied to the resultant tagnames (e.g. "Line 1|.*RPM$" will exclude any tagname that contains "Line 1" or ends with "RPM". The regex string can be used to specify multiple filters where required.

If using an escape character \ in your regex, you must use a double escape \\ since the regex is contained within a JSON object.

{
 "Settings": {
 "Host": "<MQTTHostOrIPAddress>",
 "Port": 8883,
 "Username": "<UsernameGoesHere>",
 "Password": "<PasswordGoesHere>",
 "UseTls": false,
 "Subscriptions": [
  {
 "Type": 1,
 "QoS": 2,
 "Topics": [
 "spBv1.0/<GroupIDHere>/#"
  ],
 "Filter": "spBv1.0/<GroupIDHere>/<FilterTopicHere>"
  }
 ]
 }
}

Quality of Service Types

0 At most once The message arrives at the receiver either once or not at all, "fire and forget"
1 At least once Ensures that the message arrives at the receiver at least once
2 Exactly once For use when neither loss nor duplication of messages are acceptable