Sparkplug B

Clarify supports Sparkplug B which allows compatible clients to create signals with meta-data and transmit timeseries directly to Clarify. This page will focus on how messages are parsed by Clarify, for an in-depth look at the protocol itself, you can check out the full specification.

DDATA / DBIRTH

Example

Topic

spBv1.0/<group_id>/<message_type>/<edge_node_id>/[device_id]

Payload

{
  "timestamp": 1486144502122,
  "metrics": [
    {
      "name": "Machine A/Part B/Temperature",
      "alias": 1,
      "timestamp": 1479123452194,
      "dataType": "Float",
      "value": 23.52,
      "properties": {
        "keys": ["engUnit"],
        "values": [{
          "type": "String",
          "value": "°C"
        }]
      }
    },
    {
      "name": "Machine A/Part B/Humidity",
      "alias": 1,
      "timestamp": 1479123452194,
      "dataType": "Float",
      "value": 64.12,
      "properties": {
        "keys": ["engUnit"],
        "values": [{
          "type": "String",
          "value": "%"
        }]
      }
    }
  ],
  "seq": 2
}

Given the payload above, two signals would be created in Clarify with information from the topic and the payload combined.

[
  {
    "name": "Temperature",
    "engUnit": "°C",
    "labels": {
      "group-id": ["<group_id>"],
      "edge-node-id": ["<edge_node_id>"],
      "device": ["<device_id>"],
      "folder-0": ["Machine A"],
      "folder-1": ["Part B"],
      "property-engUnit": ["°C"]
    }
  },
  {
    "name": "Humidity",
    "engUnit": "%",
    "labels": {
      "group-id": ["<group_id>"],
      "edge-node-id": ["<edge_node_id>"],
      "device": ["<device_id>"],
      "folder-0": ["Machine A"],
      "folder-1": ["Part B"],
      "property-engUnit": ["%"]
    }
  }
]

Name and label parsing

Forward slashes (/) in payload metric names are used to create a hierarchical structure in Clarify. Each segment separated by a slash is mapped to a folder label, while the final segment becomes the signal's name.

For example, the payload metric Machine A/Part B/Temperature will be interpreted as:

• folder-0 = Machine A
• folder-1 = Part B
• name = Temperature

Sparkplug B properties are typically written to labels with the prefix property-. For example, the property my-key will be mapped to the label property-my-key. However, the engUnit property is an exception: it is mapped both to a signal's engUnit field and to the label property-engUnit.

Controlling signal input ID

By default, the signal input ID is generated based on the name of the payload metric. This means that changing a metric's name will create a new signal in Clarify.

To have control over the input ID, you can use one of two fields:

1. clarify-input-id: Use this field if your desired input ID complies with the regex pattern ^[a-zA-Z0-9-_:.#+/]{1,128}$. If the value does not comply with the regex, the input ID will default back to being generated based on the metric name.
2. clarify-input-id-hash-source: Use this field if your input ID does not comply with the above regex.

If both fields are provided, clarify-input-id takes precedence over clarify-input-id-hash-source.

Controlling signal name

In some cases, engineering tools may impose limitations on signal naming. The clarify-signal-name field allows you to override the last part of a signal name, providing flexibility in how signals are named in Clarify.

For example, if the metric name is Machine A/Part B/Temperature and you set clarify-signal-name = MyTemperature, the resulting structure will be:

• folder-0 = Machine A
• folder-1 = Part B
• name = MyTemperature

Payload fields

This format supports properly formatted and protobuf encoded Sparkplug B messages. Currently DBIRTH and DDATA messages are used to create signals and insert data. Please see the Sparkplug B specification for details.

Supported message types

• DDATA
• DBIRTH

Supported value types

• UInt32
• UInt64
• Float
• Double
• Bool