The Sparkplug topic namespace is the fixed structure every Sparkplug B message uses: spBv1.0/group_id/message_type/edge_node_id/device_id. In this guide you will learn what each element means, how to name groups, nodes and devices so they stay manageable, and which wildcard subscriptions you need for monitoring, commands and debugging.
Why Sparkplug Fixes the Topic Structure
Plain MQTT lets you invent any topic hierarchy you like. That freedom is great for a single project and painful across a plant, where every integrator picks a different scheme. Sparkplug removes the choice. Topics follow one pattern, so any Sparkplug-aware host application can discover every edge node and device without per-site configuration.
The trade-off is that the topic does not describe your plant hierarchy beyond group, node and device. Site, area and line live either in the group and node IDs or inside metric names. That distinction matters when you design a Unified Namespace, and we return to it below.
The Sparkplug Topic Namespace Element by Element
spBv1.0/{group_id}/{message_type}/{edge_node_id}/{device_id}
| Element | Example | Meaning | Required |
|---|---|---|---|
| Namespace | spBv1.0 |
Identifies Sparkplug B payload version | Always |
| group_id | factory1 |
Logical grouping of edge nodes | Always |
| message_type | DDATA |
What kind of message this is | Always |
| edge_node_id | line1 |
The gateway or edge node | Always |
| device_id | cnc1 |
A device behind the edge node | Only for D-messages |
Namespace: spBv1.0
The first level is always the literal string spBv1.0. It tells consumers the payload is Sparkplug B Protobuf. The older Sparkplug A used spAv1.0 and is deprecated. If you see a topic that starts with anything else, it is not Sparkplug B, even if the payload happens to be Protobuf.
group_id
The group ID groups edge nodes logically. Many teams use a site or an area, for example plant-izmir or packaging. A host application often subscribes per group, so pick groups that match how you want to split monitoring and permissions.
message_type
This is the heart of the namespace. It tells the consumer how to treat the payload:
| Type | Sender | Purpose |
|---|---|---|
| NBIRTH | Edge node | Node came online, announces all node metrics |
| NDEATH | Broker (will) or node | Node went offline |
| DBIRTH | Edge node | Device came online, announces device metrics |
| DDEATH | Edge node | Device went offline |
| NDATA | Edge node | Changed node metric values |
| DDATA | Edge node | Changed device metric values |
| NCMD | Host application | Command to the edge node, for example rebirth |
| DCMD | Host application | Command to a device, for example a setpoint write |
| STATE | Host application | Host online/offline status |
The birth and death types carry the state model that makes Sparkplug reliable. Our guide to Sparkplug birth and death certificates explains the full lifecycle.
edge_node_id
The edge node ID identifies the gateway, PLC or software that holds the MQTT connection. It must be unique within its group. Two nodes sharing the same ID will overwrite each other's births and corrupt sequence numbers, which is one of the most common commissioning bugs.
device_id
Devices sit behind an edge node: a CNC, a drive, a Modbus meter. Device-level messages (DBIRTH, DDEATH, DDATA, DCMD) add the device ID as the fifth level. Node-level messages stop at the edge node ID.
The STATE topic
The STATE message is the exception to the pattern. In Sparkplug 3.0 it is spBv1.0/STATE/{host_id} with a small JSON payload, published retained by the Sparkplug primary host application. Older 2.2 implementations used STATE/{host_id} without the namespace prefix. If you run mixed versions, check which form your host and nodes expect.
Naming Rules That Save You Later
The specification forbids the MQTT special characters +, # and / inside the group, node and device IDs, because they would break the topic levels. Beyond that, a few conventions help:
- Use lowercase letters, digits and hyphens only. Mixed case invites mismatches between systems.
- Keep IDs stable. Renaming an edge node creates a new node from the host's point of view, and history may be split.
- Do not encode values that change, like firmware version or IP address, in an ID.
- Put deeper hierarchy into metric names, for example
Spindle/Speed, rather than trying to add topic levels. - Document the meaning of each group so new integrators place nodes correctly.
- Keep IDs short. They are repeated in every topic and are visible in every log.
Useful Subscriptions
The fixed structure makes wildcard subscriptions predictable. Here are the patterns you will use most:
spBv1.0/# everything Sparkplug on the broker
spBv1.0/factory1/# everything in one group
spBv1.0/+/NBIRTH/# every node birth, all groups
spBv1.0/+/DDATA/+/+ every device data message
spBv1.0/factory1/+/line1/# everything from one edge node
spBv1.0/factory1/DDATA/line1/cnc1 one device's data
spBv1.0/STATE/+ host application status
You can try these against the public MQTT test broker. The public area is readable by everyone, so use a random group ID and never publish real plant data there:
mosquitto_sub -h broker.connectmq.com -p 1883 -i ns-explorer-5c21 -t "spBv1.0/demo-5c21/#" -v
In a second terminal, publish a test message on a device data topic. The payload here is plain text just to verify routing; a real node sends Protobuf:
mosquitto_pub -h broker.connectmq.com -p 1883 -i ns-pub-5c21 -t "spBv1.0/demo-5c21/DDATA/line1/cnc1" -m "routing test"
Note that Sparkplug topics on the public broker use five levels, comfortably inside its eight-level limit, so a Sparkplug simulator works there unchanged.
Browsing the Namespace in a Topic Explorer
A namespace is much easier to understand when you can see it as a tree. In ConnectMQ, the portal topic explorer shows spBv1.0 topics as they arrive, and because the broker decodes Sparkplug B, you can click a DDATA topic and read its metrics instead of raw bytes. That makes it quick to answer commissioning questions such as whether a new edge node has published its birth, or which devices sit under a given node.
ConnectMQ can also republish Sparkplug data into ISA-95 topics. A message on spBv1.0/factory1/DDATA/line1/cnc1 becomes available on connectmq/factory1/production/line1/cnc1/telemetry, which is friendlier for dashboards and tools that expect a plant hierarchy.
Sparkplug Topics and the Unified Namespace
The Sparkplug topic namespace is flat by design: group, node, device. A Unified Namespace usually follows ISA-95: enterprise, site, area, line, cell. These two views coexist in many architectures. Sparkplug handles reliable, state-aware transport from the edge, and an ISA-95 tree gives humans and applications a navigable model. For the design reasoning, read MQTT, Sparkplug B and the Unified Namespace, and for the broader context see the Industrial IoT with MQTT guide.
Troubleshooting Topic Problems
| Symptom | Likely cause | What to check |
|---|---|---|
| Host never sees a node | Topic typo or wrong case in spBv1.0 |
Exact namespace string, case-sensitive |
| Two nodes keep rebirthing | Duplicate edge node ID in one group | Unique IDs per group |
| Commands not received | Node not subscribed to its NCMD/DCMD topics | Node subscribes to spBv1.0/group/NCMD/node and DCMD |
| Device data ignored | DDATA sent before DBIRTH | Device must publish DBIRTH first |
| Host status missing | Host and nodes disagree on STATE topic format | 2.2 versus 3.0 STATE topic |
When you suspect a topic problem, subscribe to spBv1.0/your-group/# with verbose output and watch the order of messages during startup. Births should arrive first, then data.
Choosing Where to Run It
Sparkplug traffic works on any compliant MQTT broker, but production plants need credentials, TLS and someone responsible for uptime. A hosted MQTT broker handles the infrastructure so your team can focus on naming, modeling and integration. Once births and data flow, the next step is reading the payloads themselves, which is covered in our Sparkplug B payload guide.
Get Started with ConnectMQ
Create a free Serverless broker at app.connectmq.com, no credit card required. Connect your edge node with the generated credentials over TLS on port 8883, and browse your Sparkplug topic namespace, decoded and organised, in the ConnectMQ topic explorer.
Frequently Asked Questions
Can I add more levels to a Sparkplug topic?
No. The Sparkplug topic namespace is fixed at four levels for node messages and five for device messages. Put additional hierarchy in metric names or map the data into an ISA-95 tree.
Is the group ID the same as a site?
It can be, but the specification only defines it as a logical grouping of edge nodes. Many teams use one group per site or per area, depending on how host applications are scoped.
Why does the STATE topic look different?
STATE messages come from host applications, not edge nodes, so they do not follow the node and device pattern. In Sparkplug 3.0 the topic is spBv1.0/STATE/{host_id}.
Are Sparkplug topics case-sensitive?
Yes. MQTT topics are case-sensitive, so spBv1.0 and SPBV1.0 are different topics, and so are Line1 and line1.
