Sparkplug 3.0 is the first version of the Sparkplug specification released under the Eclipse Foundation's Sparkplug Working Group, and it mostly clarifies behaviour that 2.2 left open to interpretation. In this comparison you will learn exactly what changed between 2.2 and 3.0, which changes can break interoperability in a mixed fleet, and how to plan an upgrade of edge nodes and host applications without surprises.
The Short Version
Sparkplug 3.0 did not reinvent the protocol. The topic namespace is still spBv1.0, the Protobuf payload is still the Sparkplug B schema, and birth and death certificates still work the same way. What changed is precision. Version 2.2 described behaviour in prose that different vendors read differently. Version 3.0 rewrote the document as a formal specification with numbered normative statements, and backed it with a Technology Compatibility Kit (TCK) that tests implementations against those statements.
The one change that is visible on the wire for almost everyone is the host application STATE message. Most other changes affect edge cases: reconnects, late wills, session handling and datatype encoding.
Sparkplug 3.0 vs 2.2 at a Glance
| Area | Sparkplug 2.2 | Sparkplug 3.0 |
|---|---|---|
| Document style | Descriptive prose | Normative statements, testable |
| Conformance | No official test suite | TCK with compliance profiles |
| Topic namespace | spBv1.0/... |
Unchanged |
| Payload schema | Sparkplug B Protobuf | Unchanged, encoding rules clarified |
| STATE topic | STATE/{host_id} |
spBv1.0/STATE/{host_id} |
| STATE payload | String ONLINE / OFFLINE |
JSON {"online": true, "timestamp": ...} |
| bdSeq | Loosely described | Must match between NBIRTH and NDEATH, rules for incrementing |
| NDEATH will QoS | Not consistently specified | QoS 1, not retained |
| MQTT session | Implied | Edge nodes and hosts use clean sessions |
| Terminology | SCADA/IIoT host, primary application | Host Application, Primary Host Application |
| Array datatypes | Listed, encoding unclear | Encoding defined |
The Changes That Matter Most
The new STATE topic and payload
In 2.2 a primary host published a retained string ONLINE on STATE/{host_id} and registered OFFLINE as its will. That topic lived outside the spBv1.0 namespace, which complicated permissions, and a plain string gave no way to tell an old message from a new one.
In 3.0 the topic moves to spBv1.0/STATE/{host_id} and the payload becomes JSON:
{ "online": true, "timestamp": 1792137600000 }
The host publishes it retained at QoS 1 after connecting, and registers a will with "online": false and the same timestamp it used in the birth. Edge nodes compare timestamps and ignore a STATE message older than the one they already saw. This closes a race where a delayed OFFLINE will from a previous host session could make every edge node disconnect even though the host had already come back. The full flow is covered in our article on the Sparkplug primary host application.
This is a breaking change. A 2.2 edge node watching STATE/scada1 will never see a 3.0 host, and a 3.0 node waiting for spBv1.0/STATE/scada1 will wait forever behind a 2.2 host. Some products support both forms during a transition; check yours before upgrading anything.
bdSeq rules
The bdSeq metric links an NBIRTH to the NDEATH registered for the same MQTT session. Version 3.0 makes the rules explicit: the NDEATH will must contain a bdSeq, the NBIRTH that follows must carry the same value, and the value changes for each new connection. Hosts use the match to discard a death certificate that belongs to an older session. If you wrote your own edge node against 2.2, this is the first thing to verify. Our guide to Sparkplug birth and death certificates shows a working implementation.
Session and QoS behaviour
Version 3.0 requires a clean session for edge nodes and host applications (clean session true in MQTT 3.1.1, or clean start with a session expiry of zero in MQTT 5). Queued messages from an old session could otherwise arrive after a new birth and confuse the state model. The NDEATH will uses QoS 1 and is not retained; births and data are not retained either. Only the host STATE message is retained.
Clearer datatypes and aliases
The datatype must be present for every metric in birth messages. Aliases must be unique per edge node. Array types such as Int32Array or BooleanArray have a defined byte encoding, so vendors that both claim array support can actually exchange arrays. The Sparkplug B data types reference lists every code.
Compliance profiles
The TCK defines profiles for an Edge Node, a Host Application, an MQTT Server and an optional Sparkplug Aware MQTT Server. Any MQTT 3.1.1 broker that supports QoS 0 and 1, retained messages and wills can carry Sparkplug traffic. The "aware" profile adds optional broker-side features defined in the specification. When a vendor says it is Sparkplug 3.0 compatible, ask which profile and whether it passed the TCK.
What Sparkplug 3.0 Means for Your Broker
Because the payload is opaque to routing, the broker's job barely changes. It needs reliable last will handling, retained messages for STATE, QoS 1 and enough connection capacity for every node and host. A managed MQTT broker like ConnectMQ supports MQTT 3.1.1 and 5.0 on the same endpoints, so 2.2 and 3.0 nodes can connect side by side while you migrate. ConnectMQ also decodes Sparkplug B payloads and shows them in the portal topic explorer, which makes it easy to check during a migration that births carry datatypes, that bdSeq values match and that the new STATE topic is retained with the expected JSON.
Before touching production, you can rehearse on the public MQTT test broker with a random group ID. For example, publish and read a 3.0 STATE message:
mosquitto_pub -h broker.connectmq.com -p 1883 -i host-test-4e1b -r -q 1 \
-t "spBv1.0/STATE/demo-host-4e1b" -m '{"online": true, "timestamp": 1792137600000}'
mosquitto_sub -h broker.connectmq.com -p 1883 -i host-watch-4e1b -t "spBv1.0/STATE/demo-host-4e1b" -v
Clear the retained message afterwards by publishing an empty retained payload to the same topic, since the public area is shared.
Upgrade Checklist from 2.2 to 3.0
- Inventory every edge node and host and record which Sparkplug version each supports.
- Decide the STATE topic strategy: upgrade hosts and nodes together, or use products that support both forms during the transition.
- Verify each edge node registers an NDEATH will with bdSeq before connecting and repeats that bdSeq in the NBIRTH.
- Confirm clean session settings on nodes and hosts.
- Check that birth messages include a datatype for every metric and that aliases are unique per node.
- Test array and template metrics between vendors if you use them.
- Run the new host in parallel against a test group, watching decoded births and STATE in a topic explorer.
- Cut over one group at a time and keep a rollback plan for the host.
Should You Upgrade?
For new projects, start with 3.0. Tools built on current Eclipse Tahu releases follow it, and the TCK gives you a way to hold vendors to the specification. For existing 2.2 plants that work, upgrade when you replace or add host applications, because the STATE change forces coordination. Edge nodes that already handle bdSeq correctly often need only a firmware or configuration update. For the wider architectural context, read the Industrial IoT with MQTT guide. The official text is on the Eclipse Sparkplug site.
Get Started with ConnectMQ
Create a free Serverless broker at app.connectmq.com, no credit card required. Connect your Sparkplug 3.0 edge nodes and host over TLS on port 8883 and verify births, deaths and STATE messages decoded in the ConnectMQ portal before you migrate production.
Frequently Asked Questions
Is Sparkplug 3.0 backward compatible with 2.2?
The payload and the spBv1.0 topic namespace are compatible. The host STATE topic and payload changed, so 2.2 nodes and 3.0 hosts (or the reverse) will not recognise each other's host state without a compatibility mode.
Does Sparkplug 3.0 require MQTT 5?
No. Sparkplug works over MQTT 3.1.1, and MQTT 5 brokers can carry it with equivalent session settings. A broker that supports both versions lets you migrate gradually.
Is the topic still spBv1.0 in Sparkplug 3.0?
Yes. The namespace identifies the Sparkplug B payload format, which did not change, so the topics stay spBv1.0/.... Only STATE moved into that namespace.
What is the Sparkplug TCK?
The Technology Compatibility Kit is a test suite from the Eclipse Sparkplug project that checks implementations against the normative statements in the 3.0 specification, per profile such as edge node or host application.
