MQTT & Sparkplug B

One connection type covers both classic MQTT (you choose the topics and payload shape) and Sparkplug B (a self-describing convention with birth/death certificates and metric metadata). The payload format switch decides which.

Configuration

Field	Description
Name	Connection identifier.
Broker	Hostname or IP.
Port	1883 plain, 8883 TLS, 9001/443 for WebSocket transports.
Protocol	tcp, ssl/tls, ws, wss.
Client ID	Optional. Leave blank for a generated one. Must be unique on the broker.
Username / Password	Optional broker credentials.
Clean session	On: no persistent broker-side subscription state. Off: the broker queues messages for this client ID while it is away.
Keep alive	Seconds between pings.
QoS	0 at most once, 1 at least once, 2 exactly once.
Payload format	mqtt (classic) or sparkplug_b.

Sparkplug-only fields

Field	Description
Group filter	Subscribe to spBv1.0/{group}/# instead of everything. Essential on a busy shared broker.
Primary host ID	If set, QUBIQ advertises spBv1.0/STATE/{id}, so edge nodes know a primary application is online.
Rebirth on sequence gap	auto (detect the edge node's scheme — default), on (always request rebirth), off (never).

Classic MQTT

In classic mode, a tag binding names the topic and, for structured payloads, a path into it.

Field	Example
Address	plant/line1/motor1/speed
QoS	Per-binding override of the connection default
JSON path	A dot path to a field in a JSON payload, e.g. data.speed for {"data":{"speed":1480}} — no leading $.

Wildcards (+, #) are for subscription scope, not for tag addresses — a tag must resolve to one value.

Sparkplug B

Sparkplug adds structure that QUBIQ uses automatically:

• Birth certificates (NBIRTH/DBIRTH) declare every metric with its name, data type, engineering unit and properties. QUBIQ reads them, so discovered metrics arrive already typed.
• Death certificates (NDEATH/DDEATH) signal that an edge node or device has gone away. Bound tags go to Bad quality immediately, instead of silently holding a stale value.
• Sequence numbers detect lost or out-of-order messages. On a gap, QUBIQ requests a rebirth so state is resynchronised rather than drifting.
• State topic. With a primary host ID configured, QUBIQ publishes its own STATE, which is what lets compliant edge nodes decide whether a primary application is listening.

Discovery

Sparkplug discovery in the connection's editor (needs View connections) returns the groups, edge nodes, devices and metrics observed from birth certificates. Discovery is how you populate the namespace from a Sparkplug plant without typing a single topic.

A Sparkplug tag address follows the hierarchy:

{group}/{edge_node}/{device}/{metric}

Writes

Writing a tag bound to a Sparkplug metric sends a command to the edge node — an NCMD for a node metric, a DCMD for a device metric — typed with the data type the metric's birth declared.

The value is converted to that type correctly now. 1.0.7 Two conversions were wrong without anything saying so:

• A write of an integer to a Boolean metric — 1, from a numeric input or a script — went out as false. Non-zero is now true.
• A write of a text timestamp (2026-09-23T08:00:00Z) to a DateTime metric went out as 1 January 1970. It now carries the time it names.

JSON and byte values also go out as JSON text and as the text the bytes hold, rather than in an internal notation no edge node can read.

This page is the inbound half. To publish QUBIQ's own tags to a broker, as a Sparkplug edge node, see MQTT publishing.

Choosing between them

Use classic MQTT when	Use Sparkplug B when
The publisher is not Sparkplug-aware	Edge devices already speak it
Payloads are your own JSON or scalars	You want typed, self-describing metrics
Topic structure is fixed and small	You want automatic discovery of a large plant
You do not need liveness semantics	You need death certificates to invalidate stale values

If you control both ends and the deployment is more than a handful of tags, Sparkplug pays for itself in the metadata alone.

TLS

Set the protocol to ssl/tls (or wss) and use the TLS port. QUBIQ validates the broker's certificate chain. For a private CA, ensure the CA is trusted by the host — QUBIQ uses the system trust store.

Quality and liveness

Condition	Tag quality
Message received and parsed	Good
Broker connection lost	Bad after the connection is marked down
Sparkplug DDEATH/NDEATH for the device	Bad
Payload could not be parsed or the JSON path did not resolve	Bad
No message yet since subscribe	Last known, or Uncertain until the first arrives

Because MQTT is push-only, a tag that never changes also never publishes, and "stable" cannot be told from "dead" on the tag itself: a tag's stale after is not enforced in this release. → Tag properties

Troubleshooting

Symptom	Check
Connects then immediately drops, repeatedly	Duplicate client ID — another client is stealing the session. Set a unique one.
Subscribed but no data	Topic mismatch (MQTT topics are case-sensitive), or the publisher only sends on change and nothing has changed.
Sparkplug metrics never appear	No birth certificate received. Restart the edge node, or force a rebirth.
Sequence gaps logged repeatedly	Network loss or an edge node restarting. Leave rebirth on auto.
Values stop after a broker restart	Clean session on, and the publisher used retained messages that were lost.
TLS handshake failure	Private CA not in the host trust store, or hostname mismatch.

Next

→ Modbus · Binding tags