MQTT Sparkplug B: topic namespace, birth and death messages, and payload
Part of the MQTT guide
MQTT Sparkplug B is a specification, maintained by the Eclipse Foundation, that defines how industrial data is carried over MQTT. Plain MQTT leaves three things open: what topics are called, what the payload contains, and how a consumer learns that a device has gone offline. Sparkplug fixes all three with a five-level topic namespace beginning spBv1.0, a Protocol Buffers payload made of typed metrics, and birth and death messages that track the state of every publisher.
This page is part of the MQTT guide. It assumes the basics in What is MQTT?, particularly the Last Will.
The roles
| Role | What it is |
|---|---|
| Edge node | An MQTT client at the edge, typically a gateway, that publishes its own metrics and those of the devices behind it |
| Device | A PLC, meter or sensor attached to an edge node. It has no MQTT connection of its own |
| Host application | A consumer such as a SCADA system or historian. One can be designated the primary host |
| MQTT server | An ordinary MQTT broker. Sparkplug needs no special broker features beyond the standard |
The Sparkplug topic namespace
Every Sparkplug topic from an edge node has the same shape:
spBv1.0/group_id/message_type/edge_node_id/device_id
spBv1.0/plant-a/NBIRTH/gateway-1
spBv1.0/plant-a/DBIRTH/gateway-1/pump3
spBv1.0/plant-a/DDATA/gateway-1/pump3
spBv1.0/plant-a/DCMD/gateway-1/pump3| Element | Meaning |
|---|---|
spBv1.0 | The namespace, which also declares the payload encoding: Sparkplug B, version 1.0 |
group_id | A logical grouping of edge nodes, such as a plant or a line |
message_type | One of the types listed below |
edge_node_id | The edge node, unique within its group |
device_id | The device behind the edge node. Present only in device messages |
The identifiers are ordinary topic levels, so they must not contain /, + or #. Note what the topic does not contain: the metric name. A message carries many metrics, and their names are inside the payload. A host that wants everything from a plant subscribes to spBv1.0/plant-a/#. General topic and wildcard rules are on the MQTT topics page.
Message types
| Type | Sent by | Purpose |
|---|---|---|
NBIRTH | Edge node | Birth certificate: the node is online, with every node metric and its current value |
NDEATH | Broker, on the node’s behalf | Death certificate: the node’s connection was lost |
DBIRTH | Edge node | A device behind the node is online, with every device metric |
DDEATH | Edge node | The node lost contact with that device |
NDATA | Edge node | Node metrics that changed |
DDATA | Edge node | Device metrics that changed |
NCMD | Host application | A command to the node, such as a rebirth request |
DCMD | Host application | A write to a device metric |
STATE | Host application | Whether the host is online |
Birth and death certificates
The birth and death messages are what turn MQTT’s Last Will into a complete state model.
- Before connecting, the edge node builds an
NDEATHpayload and registers it as its MQTT Will on theNDEATHtopic. - It connects and publishes
NBIRTH, listing every metric it will ever report, each with its name, datatype and current value. - For each device, it publishes
DBIRTHwith the same full listing for that device. - From then on it publishes
NDATAandDDATAcontaining only the metrics whose values changed. This is report by exception; there is no polling interval in the protocol. - If the node’s connection ends without a clean disconnect, the broker publishes the
NDEATHwill. Every host marks the node and all its devices as offline and their values as stale. - If a device stops answering while the node stays connected, the node publishes
DDEATHfor that device.
A host application never has to guess from silence. A value is either current, because a birth has been seen and no death since, or it is explicitly stale.
A host that connects late, or detects a problem, can ask for the births again by publishing an NCMD that writes true to the metric Node Control/Rebirth.
The payload
Sparkplug B payloads are encoded with Google Protocol Buffers, so they are binary and need the Sparkplug schema to decode. A JSON rendering of a DDATA payload looks like this:
{
"timestamp": 1647359121000,
"seq": 7,
"metrics": [
{
"name": "Flow",
"timestamp": 1647359120950,
"datatype": "Float",
"value": 42.7
},
{
"name": "Running",
"timestamp": 1647359120950,
"datatype": "Boolean",
"value": true
}
]
}Each metric has a name, a timestamp in milliseconds since the Unix epoch, a datatype and a value. The datatypes cover signed and unsigned integers from 8 to 64 bits, Float, Double, Boolean, String, DateTime and several structured types. Metric names may contain / to express a hierarchy, such as Tank1/Level, without affecting the MQTT topic.
A birth message may assign each metric a numeric alias. Data messages can then send the alias in place of the name, which shortens every later message.
A metric can also be flagged as historical, which tells the host that the value is a stored reading being sent late and should be recorded at its timestamp, not treated as the current value.
Sequence numbers
Two counters let a host detect missing messages.
seqis in every payload from an edge node. It is0in theNBIRTH, increases by one with each message the node sends, and wraps from255back to0. A host that sees a gap has missed a message and requests a rebirth.bdSeq, the birth and death sequence number, is a metric included in both theNDEATHwill and the followingNBIRTH. It lets a host match a death certificate to the session it belongs to, so a delayedNDEATHfrom an earlier connection is not mistaken for the loss of the current one.
Host state and store and forward
A host application publishes its own status on a STATE topic as a retained message, and registers the offline form as its MQTT Will. An edge node configured with a primary host subscribes to that topic. When the primary host goes offline, the node can stop publishing, store its data locally, and send it flagged as historical once the host returns. The format of the STATE topic and payload changed between Sparkplug versions 2.2 and 3.0, so both sides need to implement the same version.
Sparkplug B or plain MQTT
Sparkplug B is the better fit when several vendors’ publishers and consumers must interoperate, when consumers need to discover metrics without a separately maintained tag list, and when stale data must be flagged reliably.
Plain MQTT with a payload of your own, usually JSON, is the better fit when you control both ends, when the payload must be readable with general tools, or when the consumer expects a particular format. The costs of Sparkplug are that payloads cannot be read without a decoder, the topic structure is fixed, and each edge node has to implement the session rules correctly; a node that publishes data without a birth will be ignored by a compliant host.
Sparkplug B on the ControlCom Edge Server
The ControlCom Edge Server, the on-site component of ControlCom Connect, runs an embedded Sparkplug B broker. Three documented features use it.
The SparkplugB Listener rule accepts inbound spBv1.0 messages that an external publisher, such as a bridge, a gateway or another edge device, sends to the Edge Server’s local broker. In the rule, the Source Gateway is the edge_node_id the publisher uses, and each Source Device is a device_id; the Edge Server derives the group ID itself. A mapping pairs a source device and a Sparkplug metric name with a platform variable, with optional scale, offset, deadband and value transforms.
The MQTT Explorer tool in the Edge Server’s web interface connects to the broker over WebSockets and shows the topic tree by group, edge node, device and metric. It decodes each payload into a table of name, type, value and timestamp. Its Send Command dialog issues NCMD actions, including Rebirth, and DCMD writes to a chosen metric.
The Edge Server’s port reference lists port 8883 for Sparkplug B over mutual TLS.
Data sent directly to the hosted platform by your own device uses a different, documented format: a JSON payload published to the device’s topic, described in the MQTT documentation . The SparkplugB Listener documentation has every field of the rule, and the page for controls engineers describes the commissioning workflow around it.
Point a Sparkplug B publisher at the Edge Server’s local broker, map each metric to a variable, and the values are stored and trended in ControlCom Connect.