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 configuration file appconfig.json for Windows, or appconfig.Docker.json for Docker, contains the Settings definition to connect to a MQTT Broker, to subscribe to topics, and to interpret the messages received on those topics based on the SparkplugB specification using protobuf encoding.

By default this file can be found within C:\Program Files\Flow Software\Timebase\Collector\ for Windows, or /config for Docker.

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):

{
  "Historians": [
    {
      "Host": "<HistorianHostOrIPAddress>",
      "Port": 4511,
      "UseTls": false
    }
  ],
  "Active": true,

  "Type": "SparkplugB",
  "Dataset": "Sparkplug Data",

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

{
 "Historians": [
 {
  "Host": "<HistorianHostOrIPAddress>",
  "Port": 4511,
  "UseTls": false
 }
],
 "Active": true,

 "Type": "SparkplugB",
 "Dataset": "Sparkplug Data",

 "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