← All Posts

MQTT Sparkplug B Explained, With Real Payloads

MQTT moves bytes between clients through a broker. It says nothing about topic names, what the bytes mean, or how a subscriber knows that a device has gone quiet. Every vendor fills those gaps differently, so two MQTT systems rarely understand each other without glue code.

Sparkplug B fills them with one specification on top of MQTT 3.1.1 or 5: a fixed topic namespace, a Protocol Buffers payload with typed metrics, and a session model built from birth and death certificates. The current version is Eclipse Sparkplug 3.0.0, also published as ISO/IEC 20237:2023. The "B" is the payload format; every topic starts with spBv1.0 whatever the spec version.

This guide walks through a real session: one edge node with one device, encoded with the official Eclipse Tahu schema and decoded with MQTT Explorer, which reads Sparkplug B for free.

The topic namespace

Edge node and device messages use one of two shapes:

spBv1.0/<group_id>/<message_type>/<edge_node_id>
spBv1.0/<group_id>/<message_type>/<edge_node_id>/<device_id>

The group is usually a site or area, the edge node is the gateway or PLC that holds the MQTT connection, and a device is something behind it, such as a drive or a filler. Node messages have no device id; device messages must have one. The primary host uses a third shape, spBv1.0/STATE/<host_id>, covered below.

Type
Sent by
When
QoS / retain
NBIRTH
Edge node
After every connect, and on Rebirth. Carries every node metric and bdSeq
0 / no
DBIRTH
Edge node
For each device, after NBIRTH. Carries every device metric
0 / no
NDATA, DDATA
Edge node
When values change. Only changed metrics
0 / no
NDEATH
Broker (MQTT Will) or edge node
The edge node's connection ends
1 / no
DDEATH
Edge node
A device stops answering
0 / no
NCMD, DCMD
Host application
Writes, and Rebirth requests
0 / no
STATE
Primary host application
On connect (online) and as its Will (offline)
1 / yes

Sparkplug clients connect with a clean session (MQTT 5: session expiry 0). Nothing except STATE is retained, which is why the session rules below matter.

A session, message by message

1. Connect with a death certificate

Before it publishes anything, the edge node registers an NDEATH as its MQTT Will. The payload holds one metric, bdSeq (birth/death sequence), which goes up by one on every new connection and wraps after 255. If the network drops, the broker publishes this NDEATH for the edge node.

2. NBIRTH

Right after connecting, the edge node publishes NBIRTH on spBv1.0/Plant1/NBIRTH/Edge1. It lists every node metric with its name, datatype, current value, and optionally an alias. Its seq is 0 and its bdSeq matches the Will. Decoded by MQTT Explorer (129 bytes on the wire):

{
  "topic": { "group_id": "Plant1", "message_type": "NBIRTH", "edge_node_id": "Edge1" },
  "timestamp": 1731571200000,
  "seq": 0,
  "bd_seq": 3,
  "metrics": [
    { "name": "bdSeq", "datatype": "Int64", "value": 3 },
    { "name": "Node Control/Rebirth", "alias": 0, "datatype": "Boolean", "value": false },
    { "name": "Line/Speed", "alias": 1, "datatype": "Double", "value": 0.0 },
    { "name": "Line/Running", "alias": 2, "datatype": "Boolean", "value": false }
  ]
}

Node Control/Rebirth is the metric a host writes to ask for a new birth. Every edge node should declare it.

3. DBIRTH

Each device then gets a DBIRTH on spBv1.0/Plant1/DBIRTH/Edge1/Filler with the next seq:

{
  "topic": { "group_id": "Plant1", "message_type": "DBIRTH", "edge_node_id": "Edge1", "device_id": "Filler" },
  "seq": 1,
  "metrics": [
    { "name": "Temperature", "alias": 10, "datatype": "Float", "value": 71.5 },
    { "name": "Count", "alias": 11, "datatype": "UInt32", "value": 1200 },
    { "name": "Mode", "alias": 12, "datatype": "String", "value": "AUTO" },
    { "name": "Delta", "alias": 13, "datatype": "Int32", "value": -5 }
  ]
}

Delta is an Int32 of -5. Sparkplug carries Int8, Int16 and Int32 in an unsigned 32-bit field, so a decoder that ignores the datatype shows 4294967291. MQTT Explorer applies the declared datatype.

4. NDATA and DDATA with aliases

After the births, the edge node reports by exception: a DATA message carries only metrics that changed. When the BIRTH declared aliases, DATA can carry the alias alone and leave out the name. This NDATA is 46 bytes against 129 for the NBIRTH:

{
  "topic": { "group_id": "Plant1", "message_type": "NDATA", "edge_node_id": "Edge1" },
  "timestamp": 1731571201000,
  "seq": 2,
  "metrics": [
    { "alias": 1, "name": "Line/Speed", "name_from_alias": true, "datatype": "Double", "value": 1450.5 },
    { "alias": 2, "name": "Line/Running", "name_from_alias": true, "datatype": "Boolean", "value": true }
  ]
}

The payload contains aliases 1 and 2. The names come from the NBIRTH, which is why a subscriber that missed the BIRTH sees numbers without names. name_from_alias marks names that MQTT Explorer filled in from the BIRTH.

5. Death

When the edge node loses its connection, the broker publishes the registered NDEATH. A host marks the node and all of its devices offline and their values stale. A host must compare bdSeq: an NDEATH that does not match the current NBIRTH belongs to an older session and is ignored. Without that check, a late Will from a previous connection would take a healthy node offline.

seq and bdSeq rules

  • seq runs 0 to 255 and wraps. NBIRTH is always 0. Every NBIRTH, DBIRTH, NDATA, DDATA and DDEATH from one edge node takes the next number, devices included.
  • A gap in seq means a message was lost or reordered. A host then usually asks for a Rebirth instead of trusting its picture of the node.
  • bdSeq appears only in NBIRTH and NDEATH, and the two must match within a session.
  • NDEATH carries no seq: the broker can publish it at any time.

Here is a DDATA where seq 4 never arrived and the edge node sent an alias its DBIRTH never declared, with the checks MQTT Explorer attached:

{
  "topic": { "group_id": "Plant1", "message_type": "DDATA", "edge_node_id": "Edge1", "device_id": "Filler" },
  "seq": 5,
  "metrics": [
    { "alias": 11, "name": "Count", "name_from_alias": true, "datatype": "UInt32", "value": 1203 },
    { "alias": 99, "datatype": "UInt32", "value": 1 }
  ],
  "checks": [
    "seq 5, expected 4: messages from this edge node were lost or arrived out of order",
    "Alias 99 not declared in the BIRTH"
  ]
}

Rebirth

Births are not retained. If you subscribe after an edge node came online, you get DATA with aliases you cannot resolve. The fix is a Rebirth: publish an NCMD to spBv1.0/<group>/NCMD/<edge_node> with the Boolean metric Node Control/Rebirth set to true. The edge node answers with a fresh NBIRTH (seq 0, same bdSeq) and all its DBIRTHs.

In MQTT Explorer, the Sparkplug B tab has a Rebirth button on every edge node. It publishes that NCMD at QoS 0 without retain.

Primary host and STATE

A host application such as SCADA or a historian announces itself on spBv1.0/STATE/<host_id>. In Sparkplug 3.0 the payload is JSON:

{ "online": true, "timestamp": 1731571199000 }

The host publishes it retained at QoS 1 after connecting, and registers the same topic with "online": false as its Will. Edge nodes subscribe to it. An edge node configured with a primary host waits for it to be online before sending births, and disconnects when it goes offline, so data is not published while nobody is recording it. Sparkplug 2.2 used STATE/<host_id> with plain ONLINE and OFFLINE text; you still see that in older systems.

Data types

Each metric declares one of these datatypes, so a consumer never guesses whether a register is signed:

  • Integers: Int8, Int16, Int32, Int64 and UInt8 to UInt64.
  • Float, Double, Boolean, String, Text, UUID, and DateTime (milliseconds since the epoch).
  • Bytes and File for binary content.
  • Arrays of the numeric, Boolean, String and DateTime types.
  • DataSet: a table with typed columns.
  • Template: a reusable structure, such as a Motor with speed, current and temperature, defined once and instantiated per motor. Ignition UDTs travel as Templates.

Metrics can also carry properties (engineering units, ranges) and the is_historical, is_transient and is_null flags.

Sparkplug B and Ignition

Most Sparkplug traffic in plants today comes from Ignition with the Cirrus Link modules. MQTT Transmission makes an Ignition gateway an edge node: it publishes tag folders as Sparkplug devices and UDTs as Templates. MQTT Engine is the host side: it subscribes to spBv1.0/#, creates tags from the births, and publishes the STATE message. MQTT Distributor is a broker module; any MQTT 3.1.1 broker works instead.

When tags stop updating in MQTT Engine, point a second client at the same broker and watch the raw traffic. Common causes are an edge node waiting for a STATE that never arrives (host id mismatch), births sent before you subscribed (send a Rebirth), and sequence gaps from a congested link.

Debugging Sparkplug B with MQTT Explorer

  1. Download MQTT Explorer (macOS, free) and connect to your broker.
  2. Subscribe to spBv1.0/#.
  3. Open the Sparkplug B tab. Each edge node appears under its group with online or offline, its bdSeq and last seq, its metrics, and its devices with their metrics. Names come from the BIRTH aliases.
  4. If a node shows "no birth seen", press Rebirth.
  5. An issues badge on a node lists what the checks found: seq gaps, an NDEATH from an older session, DATA before BIRTH, undeclared aliases, data after death.
  6. To read one message, choose Decoded as the payload format and open it from the Topics or History view.

Decoding needs no setup and is part of the free version. Protobuf decoding with your own .proto schema, for non-Sparkplug topics, is part of Pro.

Which broker?

Sparkplug needs nothing broker-specific beyond retained messages, Will messages and QoS 0 and 1, so Mosquitto, EMQX, HiveMQ and the Ignition Distributor all work. Two things to check: the maximum message size, because a BIRTH with thousands of metrics or large Templates can be big, and whether the service lets you publish to arbitrary topics with a Will. Some cloud IoT hubs restrict both.

Voltrus Broker runs a dedicated Mosquitto per customer. We tested Sparkplug against its tenant configuration: retained STATE reaches late subscribers, an edge node that drops off the network gets its NDEATH published with the payload unchanged, a clean disconnect does not fire the Will, and messages up to 256 KiB pass.

Voltrus Gateway 2.2.0 publishes Modbus, OPC UA, EtherNet/IP, S7, DNP3 and BACnet tags as a Sparkplug B edge node: each PLC connection becomes a device, with births, aliases, Rebirth and optional DCMD writes. We test it against the same Mosquitto configuration, with MQTT Explorer's decoder checking every message (setup).

Sparkplug B vs plain MQTT vs OPC UA

Factor
Plain MQTT
Sparkplug B
OPC UA
Payload
Anything
Protobuf, typed metrics
Binary, typed
Topics
Your own convention
Fixed namespace
Address space
Online / offline
Only what you build with Will
Birth and death certificates
Sessions and subscriptions
Discovery
None
BIRTH lists every metric
Browse
Information model
None
Metrics, properties, Templates
Types, methods, events
Connection direction
Outbound to broker
Outbound to broker
Client to server

Use Sparkplug B when many edge devices report to several consumers through a broker and you want them to agree on names, types and online state. Use plain MQTT when you own both ends and JSON is enough. Use OPC UA for client-server access to one machine with a rich model, method calls or certificate-based security. For more, see OPC UA vs MQTT.

Questions

What is the difference between Sparkplug A and Sparkplug B?

Sparkplug A used an older payload format based on Eclipse Kura and is no longer used. Sparkplug B replaced it with the Tahu protobuf schema, richer datatypes, aliases, DataSets and Templates. When people say Sparkplug today, they mean B.

Does Sparkplug B need MQTT 5?

No. It works on MQTT 3.1.1, which is what most edge devices and Ignition use. On MQTT 5 the same rules apply, with session expiry 0 in place of clean session.

Where is the specification?

The Eclipse Sparkplug project publishes the 3.0.0 specification and a compatibility test kit (TCK). The protobuf schema, sparkplug_b.proto, is in the Eclipse Tahu repository along with client libraries for Java, Python, C and JavaScript.

Why do my DATA messages show numbers instead of names?

The edge node uses aliases and you subscribed after its BIRTH. Send a Rebirth, or subscribe before the edge node connects.

Read Sparkplug B on your Mac, free

MQTT Explorer decodes Sparkplug B payloads, shows edge nodes, devices and metrics with names from BIRTH aliases, checks seq and bdSeq, and sends Rebirth. It also connects to any MQTT 3.1.1 broker. Free download; Pro ($29.99 one-time) adds a built-in broker, several connections and charts.

Get MQTT Explorer

Further reading