Sparkplug B: Stale Data, Missing Tags, and a Client Stuck Out of Sync

intermediate · 25 min

A Sparkplug B consumer showing frozen values or blank tags almost never has a network problem. It has a session problem. Here is how to tell a missed BIRTH from an alias mismatch from a duplicate node ID — and how to fix each without stopping the line.

ℹ️ Sparkplug B is not a stream of values — it is a session. The full tag list is sent exactly once, at connection, in a BIRTH message that is never retained. Everything after that is a delta that only makes sense if you caught that BIRTH. So when data looks stale, stop testing the network. Ask instead: did this consumer ever see the BIRTH, and is it still counting from the same place the edge node is?

A Sparkplug B session end to end — the NBIRTH that ships the alias map, NDATA that ships only numbers, a SCADA client that connected too late to resolve them, the NCMD rebirth that repairs it (same bdSeq, seq back to 0), and the registered NDEATH the broker fires when the node dies.

Why plain MQTT goes stale

MQTT is a delivery pipe. The broker forwards a published message to whoever is subscribed at that instant. It stores no tag list, no data types, no history. Connect one second after a value was published and you get nothing — you wait for the next change. If a tag only moves once a shift, your screen sits blank or shows a default for hours. That is not a fault. That is MQTT working as designed.

Retained messages patch exactly one message per topic. They do not describe a machine.

What Sparkplug B adds

Define these before you troubleshoot:

• Edge node — the gateway or device that publishes on behalf of itself and its attached devices.
• Edge node descriptor — group_id + edge_node_id. This pair is the node's address and must be unique across the whole Sparkplug system.
• BIRTH certificate — NBIRTH (node) and DBIRTH (device). The full tag set: every metric the node will ever report, each carrying at minimum a name, a data type and a current value. Aliases are optional; if the node uses them, the BIRTH carries name and alias together.
• Alias — an optional integer that stands in for a long tag name, to shrink every later message.
• NDATA / DDATA — report-by-exception. Only metrics that changed since the last BIRTH or DATA. When aliases are in use, the name is omitted and only the alias is sent — and the same rule applies to NCMD/DCMD.
• NDEATH / DDEATH — death certificates. The NDEATH is registered as the MQTT Will Message inside the CONNECT packet, so the broker publishes it when the connection drops ungracefully. Detection is not instant: the broker only fires the Will once the keep-alive lapses (roughly 1.5 × the keep-alive interval), so a 60 s keep-alive means ~90 s to notice. That interval is the knob, not the protocol.
• seq — a counter 0–255 on every message from that edge node, wrapping back to zero after 255. The NBIRTH carries seq = 0.
• bdSeq — a birth/death sequence number that ties one NBIRTH to its matching NDEATH, so you know which session ended. It starts at zero, increments by one on every new MQTT CONNECT, and wraps to 0 after 255.
• STATE — every Sparkplug Host Application publishes spBv1.0/STATE/<host_id>, retained, at QoS 1, carrying JSON with online (boolean) and timestamp keys (Sparkplug 3.0 format; 2.2 used a plain ONLINE/OFFLINE UTF-8 string). "Primary" is a role assigned in the edge node's configuration — an edge node reacts only to the one host ID it is configured to watch, and ignores every other STATE topic on the broker.
• Payload encoding — Google Protocol Buffers, a binary format. A plain text MQTT client shows you bytes, not values.

The QoS and retain rules, in full

Every edge-node message — NBIRTH, DBIRTH, NDATA, DDATA, NDEATH, DDEATH, NCMD, DCMD — is published QoS 0, retain false. There are exactly two exceptions in the protocol:

Read the first row twice. The message that defines your entire tag set is fire-and-forget and never stored. Miss it and it is gone.

Tell the causes apart first

Step-by-step

1. Subscribe with a decoder, not a text client. Wireshark ships a Sparkplug B dissector implemented as a heuristic subdissector of MQTT that hands the payload to the protobuf dissector; MQTT Explorer has a built-in Sparkplug B decoder. If your tool shows binary garbage, you are reading protobuf raw — change the tool, do not conclude the payload is corrupt. Note that neither helps on TLS: if the broker is on 8883 the capture is opaque without keying material, so capture on the plaintext listener or decode at a client instead.
2. Read the STATE topics. Subscribe to spBv1.0/STATE/#. Three outcomes:

• Nothing at all — normal in systems with no Host Application configured as primary. Nothing to conclude; go to step 3.
• online: true for the host your edges are configured to watch — not your problem; go to step 3.
• online: false — the edges are doing what the spec tells them to. An edge node configured for that primary host must, on receiving an offline STATE whose timestamp is greater than or equal to the prior online STATE's timestamp, immediately publish its NDEATH, disconnect, and move to the next MQTT server in its list. Everything downstream will look dead and the edges are correct. Check the timestamp before you accept this: an offline STATE with an older timestamp must be ignored by the edge nodes, and a stale retained one that nobody cleared is its own bug.

1. Confirm whether a BIRTH exists at all. Subscribe to spBv1.0/+/NBIRTH/+ and watch. If you see DATA on a node but no BIRTH in your session history, you joined mid-stream. This is the single most common cause.
2. Check seq continuity. Log seq per edge node descriptor — one counter covers all of that node's messages, node and device alike. Clean systems increment by one and wrap 255 → 0. Sporadic gaps under load point to reordering; gaps that never resolve point to two publishers. If your host software offers a Reorder Timeout parameter, that is the window it waits before giving up and requesting a rebirth; the spec only recommends providing the parameter and mandates no value, so a host that never rebirths may simply have none configured.
3. Match bdSeq across NBIRTH and NDEATH. If an NDEATH's bdSeq does not match the NBIRTH you are holding, the death belongs to an older session and your view is a session behind. bdSeq changes only on a new MQTT CONNECT — a rebirth reuses the same value, so do not read an unchanged bdSeq after step 6 as a failed rebirth.
4. Request a rebirth — but read this first. On receiving a rebirth command the edge node must immediately stop sending DATA messages and republish the full BIRTH sequence. Values on every consumer pause for that window, and quality may flip to bad, which can trip alarms or any interlock reading those tags. Confirm with the operator before you do it. Then publish an NCMD to spBv1.0/<group_id>/NCMD/<edge_node_id> with a metric named Node Control/Rebirth set to true. This is the one deliberate exception to the alias rule: every NBIRTH must carry a Boolean Node Control/Rebirth metric with value false, and when the node uses aliases that metric must be published without an alias — precisely so any host can request a rebirth by name without a valid alias map. Every other NCMD on an aliased node goes the other way: alias only, name excluded.
5. Fix an alias mismatch by discarding, not remapping. On every NBIRTH, throw away the entire alias table for that node and rebuild it from the new BIRTH. Aliases are only valid within the session that declared them.
6. Resolve duplicate node IDs at the source. Compare group_id/edge_node_id in both gateway configs. If they also share an MQTT client ID, the broker will disconnect the existing client whenever the other connects — you will see a connect/NDEATH loop. Change the edge_node_id on one gateway. Warning: restarting a gateway drops its publishing session and fires an NDEATH; anything consuming those tags goes bad-quality until the new BIRTH lands.
7. Verify by watching one known tag change on the machine and confirming the value arrives with a seq that follows the previous one.

Never do this

Never publish to an edge-node Sparkplug topic — spBv1.0/<group_id>/<VERB>/<edge_node_id> — with the retain flag set. A mosquitto_pub -r to one of those during testing is the expensive mistake. The spec requires every edge-node message to be non-retained and consumers assume it. (The one topic that is retained by design is spBv1.0/STATE/<host_id>, published retained at QoS 1 by the Host Application itself — leave it alone; do not hand-publish to it either.)

A retained message on a data topic silently replays a stale value to every client that ever subscribes again. A retained message on an NCMD or DCMD topic is worse: because Sparkplug clients connect with Clean Session true (or Clean Start true with Session Expiry 0 on MQTT 5.0) they re-subscribe on every reconnect, so the edge node re-receives that command every single time it reconnects — a test setpoint or a control write firing again days later, unattended, with nobody at the keyboard. Nothing clears it on its own unless the publisher happened to set an MQTT 5.0 message-expiry interval. You must publish a zero-byte retained message to that exact topic to remove it — and finding which topic was poisoned, months later, on a running plant, is a very bad afternoon.

Also: never hardcode an alias-to-tag map captured from one BIRTH into a consumer. And never restart the broker to "clear" stale data — that drops every session at once and forces every edge node to reconnect and rebirth simultaneously.