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

Quality handling

Some Sparkplug B publishers, such as Ignition, include a Quality property on individual metrics. When present, Clarify reads this property from the metric's properties field.

In properties, each entry in properties.keys maps to the value at the same index in properties.values. For example, if properties.keys[0] is Quality, then the corresponding quality value is found in properties.values[0].

Example:

{
  "name": "Quality test/Sine/Sine0 clamp low 0",
  "timestamp": 1773401342375,
  "datatype": 9,
  "is_null": false,
  "properties": {
    "keys": [
      "Quality"
    ],
    "values": [
      {
        "type": 3,
        "Value": {
          "IntValue": 2147484172
        }
      }
    ]
  },
  "Value": {
    "FloatValue": -7.7451754
  }
}

Clarify decodes the quality value and checks the resulting Ignition quality subcode. The following non-good quality ranges are used:

• 226-511: Uncertain
• 512-767: Bad
• 768-1023: Error

If the decoded subcode falls within one of these ranges, the metric is omitted.

If the Quality property is missing, unknown, or cannot be decoded into a known non-good subcode, the metric is accepted and processed as Good_Unspecified.

In the example above the value decodes to subcode 524, which is in the bad range. The metric is therefore omitted.

See Ignition's Quality Codes and Overlays documentation for more information.

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