Basic Message Components

Topic

The topic is published in the format spBv1.0/[Group ID]/[Verb]/[Edge Node ID]/[Device ID] where:

Group ID
- This identifies a logical grouping of Edge nodes and devices. This can be a region, a facility name, or any meaningful grouping of Edge Nodes within your application.
Verb
- This provides an indication on how to handle the payload of the message. This includes whether the message is a birth certificate, death certificate, data message, command message, etc.
- Options include
  NBIRTH: Edge node BIRTH certificate. This is a startup message from an Edge node to announce its presence and share its configurations.
  - If Ignition User Defined Types (UDTs) are being used, definitions are included in NBIRTH messages
  NDEATH: Notification of an edge node’s disconnection or failure.
  DBIRTH: Device BIRTH certificate. This is a startup message from a device to announce its presence and share its configurations.
  DDEATH: Notification of a device’s disconnection or failure.
  NDATA: Data messages from an edge node which include edge node metric data.
  DDATA: Data messages from a device which include device metrics.
  NCMD: Command to an edge node.
  - Also used for REBIRTH requests to an edge node
  DCMD: Command to a device.
  STATE: It represents the state of the primary host application. Edge nodes subscribe to it to get the online status of the host.
Edge Node ID
- The ID of the logical Edge Node. This is often the name of the system running Ignition with MQTT Transmission or Injectors.
Device ID (Optional)
- The ID of a device attached to the Ignition instance. This can be a PLC or logical grouping of tags that represent a physical or logical device connected to Ignition.

MQTT Transmission transmitters or the Injector Tag Agents are designed to use the Ignition tag folder hierarchy (Tag Path) in combination with any configured Sparkplug IDs to dynamically build the Group ID, Edge Node Id and Device ID used in the topic.

Payload

The payload contains the following :

timestamp
- The time stamp the payload was created
metrics
- An array containing the metrics being published.
- For each metric parameters include:
- name
  - Metric name when aliasing not used
  - For Ignition tags this is 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
  - Currently not used by MQTT Modules
  - Set to null
- metaData
  - Used for customisation on top of the Sparkplug B protocol
  - Used by MQTT Modules 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.
  - Included in BIRTH messages if values have been changed from the Ignition default or if they are custom properties.
    Cirrus Link modules often optimise payloads by excluding Good metric qualities from a payload. If the payload is missing the quality property, it should be considered to be Good
- value
  - Value associated with the metric
  - If Ignition User Defined Types (UDTs) are being used, definitions are included in NBIRTH messages
- 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
uuid
- Currently not used by MQTT Modules
- Set to null
body
- Currently not used by MQTT Modules
- Set to null

Where a parameter is not specific to the metric being published, it is set to null

Examples

NBIRTH

spBv1.0/TestGroup/NBIRTH/TestEdge

[timestamp=1713266473578, metrics=[ Metric [name=Node Control/Next Server, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], isHistorical=null, isTransient=null, metaData=null, properties=null, value=false, isNull=false], Metric [ name=Motor, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Template, intValue=19, clazz=class org.eclipse.tahu.message.model.Template], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=03081691ee14510415e1036a4d1f416d, description=], properties=PropertySet [propertyMap={}], value=Template [version=, templateRef=, isDefinition=true, metrics=[Metric [name=T1, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={}], value=null, isNull=true]], parameters=[]], isNull=false], Metric [name=E_T1, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=String, intValue=12, clazz=class java.lang.String], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=application/json, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={engLow=PropertyValue [type=PropertyDataType [type=Double, intValue=10, clazz=class java.lang.Double], value=1.0, isNull=false], Quality=PropertyValue [type=PropertyDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], value=-2147483133, isNull=false], enabled=PropertyValue [type=PropertyDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], value=false, isNull=false]}], value=null, isNull=true], Metric [name=Node Info/Transmission Version, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=String, intValue=12, clazz=class java.lang.String], isHistorical=null, isTransient=null, metaData=null, properties=null, value=4.0.22-SNAPSHOT (b2024041611), isNull=false], Metric [name=bdSeq, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Int64, intValue=4, clazz=class java.lang.Long], isHistorical=null, isTransient=null, metaData=null, properties=null, value=2, isNull=false], Metric [ name=E_M1, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Template, intValue=19, clazz=class org.eclipse.tahu.message.model.Template], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={enabled=PropertyValue [type=PropertyDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], value=false, isNull=false]}], value=Template [version=, templateRef=Motor, isDefinition=false, metrics=[Metric [name=T1, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=false, isTransient=false, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={engUnit=PropertyValue [type=PropertyDataType [type=String, intValue=12, clazz=class java.lang.String], value=RPM, isNull=false], Quality=PropertyValue [type=PropertyDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], value=-2147483133, isNull=false]}], value=null, isNull=true]], parameters=[]], isNull=false], Metric [name=Node Control/Rebirth, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], isHistorical=null, isTransient=null, metaData=null, properties=null, value=false, isNull=false]], seq=0, uuid=null, body=null]

Metric [name=Node Control/Next Server, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], isHistorical=null, isTransient=null, metaData=null, properties=null, value=false, isNull=false]

Metric [name=Node Info/Transmission Version, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=String, intValue=12, clazz=class java.lang.String], isHistorical=null, isTransient=null, metaData=null, properties=null, value=4.0.22-SNAPSHOT (b2024041611), isNull=false]

Metric [name=bdSeq, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Int64, intValue=4, clazz=class java.lang.Long], isHistorical=null, isTransient=null, metaData=null, properties=null, value=2, isNull=false]

Metric [ name=Motor, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Template, intValue=19, clazz=class org.eclipse.tahu.message.model.Template], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=03081691ee14510415e1036a4d1f416d, description=], properties=PropertySet [propertyMap={}], value=Template [version=, templateRef=, isDefinition=true, metrics=[Metric [name=T1, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={}], value=null, isNull=true]], parameters=[]], isNull=false]

Metric [name=E_T1, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=String, intValue=12, clazz=class java.lang.String], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=application/json, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={engLow=PropertyValue [type=PropertyDataType [type=Double, intValue=10, clazz=class java.lang.Double], value=1.0, isNull=false], Quality=PropertyValue [type=PropertyDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], value=-2147483133, isNull=false], enabled=PropertyValue [type=PropertyDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], value=false, isNull=false]}], value=null, isNull=true]

Metric [name=T1, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=false, isTransient=false, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={engUnit=PropertyValue [type=PropertyDataType [type=String, intValue=12, clazz=class java.lang.String], value=RPM, isNull=false], Quality=PropertyValue [type=PropertyDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], value=-2147483133, isNull=false]}], value=null, isNull=true]], parameters=[]], isNull=false]

DBIRTH

spBv1.0/TestGroup/DBIRTH/TestEdge/TestDevice

[timestamp=1713266459127, metrics=[Metric [name=D_T1, alias=null, timestamp=1713266459127, dataType=MetricDataType [type=String, intValue=12, clazz=class java.lang.String], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=application/json, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={Quality=PropertyValue [type=PropertyDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], value=192, isNull=false], enabled=PropertyValue [type=PropertyDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], value=true, isNull=false], documentation=PropertyValue [type=PropertyDataType [type=String, intValue=12, clazz=class java.lang.String], value=Some helpful docs, isNull=false]}], value={ "Key1": "Value3" }, isNull=false], Metric [name=Device Control/Rebirth, alias=null, timestamp=1713266459127, dataType=MetricDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], isHistorical=null, isTransient=null, metaData=null, properties=null, value=false, isNull=false], Metric [name=D_M1, alias=null, timestamp=1713266459127, dataType=MetricDataType [type=Template, intValue=19, clazz=class org.eclipse.tahu.message.model.Template], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={enabled=PropertyValue [type=PropertyDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], value=true, isNull=false]}], value=Template [version=, templateRef=Motor, isDefinition=false, metrics=[Metric [name=T1, alias=null, timestamp=1713266459127, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=false, isTransient=false, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={engHigh=PropertyValue [type=PropertyDataType [type=Double, intValue=10, clazz=class java.lang.Double], value=60.0, isNull=false]}], value=12, isNull=false]], parameters=[]], isNull=false]], seq=1, uuid=null, body=null]

Metric [name=Device Control/Rebirth, alias=null, timestamp=1713266459127, dataType=MetricDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], isHistorical=null, isTransient=null, metaData=null, properties=null, value=false, isNull=false]

Metric [name=D_T1, alias=null, timestamp=1713266459127, dataType=MetricDataType [type=String, intValue=12, clazz=class java.lang.String], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=application/json, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={Quality=PropertyValue [type=PropertyDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], value=192, isNull=false], enabled=PropertyValue [type=PropertyDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], value=true, isNull=false], documentation=PropertyValue [type=PropertyDataType [type=String, intValue=12, clazz=class java.lang.String], value=Some helpful docs, isNull=false]}], value={ "Key1": "Value3" }, isNull=false]

Metric [name=D_M1, alias=null, timestamp=1713266459127, dataType=MetricDataType [type=Template, intValue=19, clazz=class org.eclipse.tahu.message.model.Template], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={enabled=PropertyValue [type=PropertyDataType [type=Boolean, intValue=11, clazz=class java.lang.Boolean], value=true, isNull=false]}], value=Template [version=, templateRef=Motor, isDefinition=false, metrics=[Metric [name=T1, alias=null, timestamp=1713266459127, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=false, isTransient=false, metaData=MetaData [isMultiPart=false, contentType=, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={engHigh=PropertyValue [type=PropertyDataType [type=Double, intValue=10, clazz=class java.lang.Double], value=60.0, isNull=false]}], value=12, isNull=false]], parameters=[]], isNull=false]]

NDATA

spBv1.0/TestGroup/NDATA/TestEdge

[timestamp=1713266453938, metrics=[ Metric [name=E_M1, alias=null, timestamp=1713266452937, dataType=MetricDataType [type=Template, intValue=19, clazz=class org.eclipse.tahu.message.model.Template], isHistorical=null, isTransient=null, metaData=null, properties=null, value=Template [version=, templateRef=Motor, isDefinition=false, metrics=[Metric [name=T1, alias=null, timestamp=1713266445706, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=null, isTransient=null, metaData=null, properties=null, value=12, isNull=false]], parameters=[]], isNull=false], Metric [name=E_T1, alias=null, timestamp=1713266452939, dataType=MetricDataType [type=String, intValue=12, clazz=class java.lang.String], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=application/json, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={}], value={ "Key1": "Value3" }, isNull=false]], seq=6, uuid=null, body=null]

Metric [name=E_M1, alias=null, timestamp=1713266452937, dataType=MetricDataType [type=Template, intValue=19, clazz=class org.eclipse.tahu.message.model.Template], isHistorical=null, isTransient=null, metaData=null, properties=null, value=Template [version=, templateRef=Motor, isDefinition=false, metrics=[Metric [name=T1, alias=null, timestamp=1713266445706, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=null, isTransient=null, metaData=null, properties=null, value=12, isNull=false]], parameters=[]], isNull=false]

Metric [name=E_T1, alias=null, timestamp=1713266452939, dataType=MetricDataType [type=String, intValue=12, clazz=class java.lang.String], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=application/json, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={}], value={ "Key1": "Value3" }, isNull=false]]

DDATA

spBv1.0/TestGroup/DDATA/TestEdge/TestDevice

[timestamp=1713266761298, metrics=[Metric [name=DT1, alias=null, timestamp=1713266730315, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=true, isTransient=null, metaData=null, properties=null, value=5, isNull=false], Metric [name=DT1, alias=null, timestamp=1713266730416, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=true, isTransient=null, metaData=null, properties=null, value=6, isNull=false], Metric [name=DT1, alias=null, timestamp=1713266730516, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=true, isTransient=null, metaData=null, properties=null, value=7, isNull=false], Metric [name=DT1, alias=null, timestamp=1713266730617, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=true, isTransient=null, metaData=null, properties=null, value=8, isNull=false], Metric [name=DT1, alias=null, timestamp=1713266730718, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=true, isTransient=null, metaData=null, properties=null, value=9, isNull=false]], seq=15, uuid=null, body=null]

Metric [name=DT1, alias=null, timestamp=1713266730315, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=true, isTransient=null, metaData=null, properties=null, value=5, isNull=false]

Metric [name=DT1, alias=null, timestamp=1713266730416, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=true, isTransient=null, metaData=null, properties=null, value=6, isNull=false]

Metric [name=DT1, alias=null, timestamp=1713266730516, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=true, isTransient=null, metaData=null, properties=null, value=7, isNull=false]

[timestamp=1713266453943, metrics=[ Metric [name=D_M1, alias=null, timestamp=1713266452942, dataType=MetricDataType [type=Template, intValue=19, clazz=class org.eclipse.tahu.message.model.Template], isHistorical=null, isTransient=null, metaData=null, properties=null, value=Template [version=, templateRef=Motor, isDefinition=false, metrics=[Metric [name=T1, alias=null, timestamp=1713266445725, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=null, isTransient=null, metaData=null, properties=null, value=12, isNull=false]], parameters=[]], isNull=false], Metric [name=D_T1, alias=null, timestamp=1713266452947, dataType=MetricDataType [type=String, intValue=12, clazz=class java.lang.String], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=application/json, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={}], value={ "Key1": "Value3" }, isNull=false]], seq=7, uuid=null, body=null]

Metric [name=D_M1, alias=null, timestamp=1713266452942, dataType=MetricDataType [type=Template, intValue=19, clazz=class org.eclipse.tahu.message.model.Template], isHistorical=null, isTransient=null, metaData=null, properties=null, value=Template [version=, templateRef=Motor, isDefinition=false, metrics=[Metric [name=T1, alias=null, timestamp=1713266445725, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=null, isTransient=null, metaData=null, properties=null, value=12, isNull=false]], parameters=[]], isNull=false]

Metric [name=D_T1, alias=null, timestamp=1713266452947, dataType=MetricDataType [type=String, intValue=12, clazz=class java.lang.String], isHistorical=null, isTransient=null, metaData=MetaData [isMultiPart=false, contentType=application/json, size=0, seq=0, fileName=, fileType=, md5=, description=], properties=PropertySet [propertyMap={}], value={ "Key1": "Value3" }, isNull=false]]

NDEATH

spBv1.0/TestGroup/NDEATH/TestEdge

[timestamp=1713266459127, metrics=[Metric [name=bdSeq, alias=null, timestamp=1713266473578, dataType=MetricDataType [type=Int64, intValue=4, clazz=class java.lang.Long], isHistorical=null, isTransient=null, metaData=null, properties=null, value=2, isNull=false]], seq=7, uuid=null, body=null]

DDEATH

spBv1.0/TestGroup/DDEATH/TestEdge/TestDevice

[timestamp=1713266459127, metrics=[Metric [name=bdSeq, alias=null, timestamp=1713266442358, dataType=MetricDataType [type=Int64, intValue=4, clazz=class java.lang.Long], isHistorical=null, isTransient=null, metaData=null, properties=null, value=5, isNull=false]], seq=7, uuid=null, body=null]

NCMD

spBv1.0/TestGroup/NCMD/TestEdge

[timestamp=1713266761298, metrics=[Metric [name=ET1, alias=null, timestamp=1713266730315, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=true, isTransient=null, metaData=null, properties=null, value=5, isNull=false]], seq=15, uuid=null, body=null]

DCMD

spBv1.0/TestGroup/DCMD/TestEdge/TestDevice

[timestamp=1713266761298, metrics=[Metric [name=DT1, alias=null, timestamp=1713266785263, dataType=MetricDataType [type=Int32, intValue=3, clazz=class java.lang.Integer], isHistorical=true, isTransient=null, metaData=null, properties=null, value=25, isNull=false]], seq=12, uuid=null, body=null]

STATE

Sparkplug™ B payloads are not used for encoding in this payload and this allows Host/backend application(s) to work across Sparkplug™ payload types.

spBv1.0/STATE/primary_host_id

{ "online" : true, "timestamp" : 1668114759262} or { "offline" : true, "timestamp" : 1668114759452}