Quick overview of Sparkplug message format

A Cirrus Link Sparkplug message comprises two parts: the topic and the payload.

Topic

The topic is published in the format:

• spBv1.0/[GroupID]/[Verb]/[EdgeNodeID]/[DeviceID]

Payload

Payload in the format:

• timestamp
• metrics
  
  • name - the tag folder hierarchy not used in the topic namespace
  • alias - numeric value representing the metric when aliasing is used
  • timestamp - timestamp associated with the last metric change event
  • dataType - DataType associated with the metric
  • isHistorical - set to True to denote the metric represents a historical value
  • isTransient - set to null
  • metaData - used for file transfers and custom decoding information for the metric
  • properties - used for Ignition tag properties. See the Ignition Tag Properties reference for all available properties
  • value - value associated with the metric
  • isNull - flag denoting the metric has a null value
• seq 
  • The message sequence number used to ensure that messages are processed in the correct order

Default Tags

When configured to create Default Tags, MQTT Engine will parse the topic and payload to create tags under the 'Edge Nodes' folder in the MQTT Engine tag provider.

The metric name in the payload is used for the tag name prefixed by the Sparkplug Descriptors from the message topic resulting in a tag path of:

• [MQTT Engine]Edge Nodes/GroupID/EdgeNodeID/DeviceID/MetricName

For example the message below:

• Topic: spBv1.0/Site 1/DDATA/Area 1/Line 1
• Payload: {"timestamp":1643823757750,"metrics":[{"name":"Conveyer/Batch/Quantity","timestamp":1643823756467,"dataType":"Double","value":33.02}],"seq":23}

creates an MQTT Engine tag:

• [MQTT Engine]Edge Nodes/Site 1/Area 1/Line 1/Conveyer/Batch/Quantity

UNS Tags

When configured to create UNS Tags, MQTT Engine will obfuscate the Sparkplug Descriptors used in the topic and only parse the metric name included in the payload to create the tag structure under the configured UNS Folder prefix. 

For example the message below:

• Topic: spBv1.0/Site 1/DDATA/Area 1/Line 1
• Payload: {"timestamp":1643823757750,"metrics":[{"name":"Conveyer/Batch/Quantity","timestamp":1643823756467,"dataType":"Double","value":33.02}],"seq":23}

creates an MQTT Engine tag:

• [MQTT Engine]UNS/Conveyer/Batch/Quantity
  • Custom properties
    • SparkplugDeviceId - Line1
    • SparkplugEdgeNodeId - Area 1
    • SparkplugGroupId - Site 1

If using MQTT Transmission to publish the message, you may need to utilize the Sparkplug IDs configurable for each Transmitter to correctly build your UNS tag path rather than allow the Transmitter to dynamically pickup the Sparkplug Descriptors from the tag folder hierarchy.

In the example below we have four tag providers simulating four Edges - Site 1A, Site 1B, Site 1C and Site 2. 

For each Transmitter configuration we have set the Sparkplug IDs to use the the message topic allowing the tag folder hierarchy at the Edge to form the metric name. 

Messages published from the each edge node will now contain metric names which are the full folder hierarchy at the Edge

For example:

• Site 1A Edge node metric name of Enterprise/Site 1/Area 1/BMS/Rooftop/ ........
• Site 1B Edge node metric name of Enterprise/Site 1/Area 2/BMS/Rooftop/ ........
• Site 1C Edge node metric name of Enterprise/Site 1/Area 2/Line 2/DO1_EMU/........
• Site 2 Edge node metric name of Enterprise/Site 2/Area 1/BMS/Rooftop/ ........

At Engine, these tags published from Edge Nodes Site 1 A, Site 1 B and Site 1 C are then concatenated under the single UNS tag path of UNS> Enterprise > Site 1