MQTT Sparkplug B: topic namespace, birth and death messages, and payload

Catalin NegruPublished 6 min read

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

RoleWhat it is
Edge nodeAn MQTT client at the edge, typically a gateway, that publishes its own metrics and those of the devices behind it
DeviceA PLC, meter or sensor attached to an edge node. It has no MQTT connection of its own
Host applicationA consumer such as a SCADA system or historian. One can be designated the primary host
MQTT serverAn 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
ElementMeaning
spBv1.0The namespace, which also declares the payload encoding: Sparkplug B, version 1.0
group_idA logical grouping of edge nodes, such as a plant or a line
message_typeOne of the types listed below
edge_node_idThe edge node, unique within its group
device_idThe 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

TypeSent byPurpose
NBIRTHEdge nodeBirth certificate: the node is online, with every node metric and its current value
NDEATHBroker, on the node’s behalfDeath certificate: the node’s connection was lost
DBIRTHEdge nodeA device behind the node is online, with every device metric
DDEATHEdge nodeThe node lost contact with that device
NDATAEdge nodeNode metrics that changed
DDATAEdge nodeDevice metrics that changed
NCMDHost applicationA command to the node, such as a rebirth request
DCMDHost applicationA write to a device metric
STATEHost applicationWhether 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.

  1. Before connecting, the edge node builds an NDEATH payload and registers it as its MQTT Will on the NDEATH topic.
  2. It connects and publishes NBIRTH, listing every metric it will ever report, each with its name, datatype and current value.
  3. For each device, it publishes DBIRTH with the same full listing for that device.
  4. From then on it publishes NDATA and DDATA containing only the metrics whose values changed. This is report by exception; there is no polling interval in the protocol.
  5. If the node’s connection ends without a clean disconnect, the broker publishes the NDEATH will. Every host marks the node and all its devices as offline and their values as stale.
  6. If a device stops answering while the node stays connected, the node publishes DDEATH for 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.

  • seq is in every payload from an edge node. It is 0 in the NBIRTH, increases by one with each message the node sends, and wraps from 255 back to 0. 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 the NDEATH will and the following NBIRTH. It lets a host match a death certificate to the session it belongs to, so a delayed NDEATH from 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.