Sparkplug B to Cloud MQTT Brokers¶

Flowgate's Sparkplug B connector publishes to any MQTT 3.1.1 broker over TLS. This page documents the two managed cloud brokers it has been verified against, end to end: AWS IoT Core and Azure Event Grid MQTT broker. Everything below was measured against a live deployment of Flowgate 0.13.1 on 2026-09-01.

One broker is deliberately absent: Azure IoT Hub cannot carry Sparkplug B. IoT Hub's MQTT front end only accepts publishes on its own devices/{device}/messages/events/ topics, and Sparkplug's spBv1.0/... topic namespace cannot be expressed there. For IoT Hub, use Flowgate's MQTT JSON publisher with the Azure IoT Hub provider preset instead.

What the connector sends¶

A Sparkplug B connector acts as one Sparkplug edge node. The broker must permit these topics, where {group} and {edge} are the connector's group_id and edge_node_id settings:

Direction	Topic	Carries
Publish	`spBv1.0/{group}/NBIRTH/{edge}`	Edge node birth, on every connect
Publish	`spBv1.0/{group}/NDEATH/{edge}`	Edge node death: sent gracefully on disable, and registered as the MQTT Last Will for abrupt disconnects
Publish	`spBv1.0/{group}/DBIRTH/{edge}/{device}`	Device birth with the full metric set
Publish	`spBv1.0/{group}/DDATA/{edge}/{device}`	Metric updates
Subscribe	`spBv1.0/{group}/NCMD/{edge}`	Rebirth requests from host applications

The connector never sets the MQTT retain flag, on any message including the Will. It requires QoS 0 or 1 only. Neither cloud broker supports QoS 2, and the connector never asks for it.

{device} is a single topic level built from the first device_levels segments of each tag path, joined by device_separator (default :). Keep the separator at its default: setting it to / would split the device id across topic levels and break single-level topic permissions.

AWS IoT Core¶

Broker side. Create a Thing, an X.509 device certificate, and an IoT policy permitting the topics above, then attach the policy to the certificate and the certificate to the Thing. The policy must also permit iot:Connect for the client id the connector will use. Use the account's ATS data endpoint (Settings, "Device data endpoint", or aws iot describe-endpoint --endpoint-type iot:Data-ATS).

Connector settings.

type: sparkplugb
broker_url: ssl://<your-ats-endpoint>.iot.<region>.amazonaws.com:8883
client_id: <a client id your IoT policy permits>
group_id: <group>
edge_node_id: <edge>
qos: 1

Upload the device certificate and private key through the connector's certificate upload (Connections page, or POST /api/v1/connectors/{id}/certificates), together with Amazon Root CA 1 as the CA certificate. AWS IoT's server certificate chains to Amazon's own root, which is not in every system trust store, so the CA upload is required here.

Azure Event Grid MQTT broker¶

Microsoft documents Sparkplug B as a supported workload on Event Grid's MQTT broker. An Event Grid namespace is a paid resource from the moment it exists (Standard tier, throughput-unit hourly base price plus per-operation pricing after the first million operations each month); there is no free tier. Namespaces bill hourly, so short-lived test namespaces are inexpensive, and deleting the namespace is the only way to stop the meter: MQTT cannot be disabled on a namespace once enabled.

Broker side. Create an Event Grid namespace with topic spaces enabled, then:

Register a client for the connector. With the ThumbprintMatch validation scheme a self-signed certificate works: register the certificate's SHA-256 thumbprint. The client's authentication name is permanent and must be unique in the namespace.
Create a topic space with the single template spBv1.0/#.
Create two permission bindings on that topic space for the client's group: one with the publisher permission, one with the subscriber permission. The subscriber binding is what allows the NCMD rebirth subscription. Bindings can take a couple of minutes to propagate.

The MQTT hostname is on the namespace overview page, in the form <namespace>.<region>-1.ts.eventgrid.azure.net.

Connector settings.

type: sparkplugb
broker_url: ssl://<namespace>.<region>-1.ts.eventgrid.azure.net:8883
client_id: <the client's authentication name>
username: <the client's authentication name>
group_id: <group>
edge_node_id: <edge>
qos: 0        # see "Throughput and QoS" below

Two settings differ from the AWS recipe, and both matter:

username is required. Event Grid authenticates the certificate, but the CONNECT packet's username field must carry the client's authentication name. The simplest working shape is authentication name, client_id, and username all set to the same value. Leave the password empty.
Do not upload a CA certificate. Event Grid's server certificate chains to a public root that is already in the operating system trust store, and a CA uploaded to a connector replaces the system trust store rather than adding to it. Upload only the client certificate and key. A connector that suddenly cannot verify the broker after a CA upload has hit exactly this.

Throughput and QoS¶

The connector publishes messages one at a time and, at QoS 1, waits for the broker's acknowledgment before sending the next. Sustained throughput at QoS 1 is therefore bounded by the network round trip to the broker: roughly one message per round-trip time.

Measured from the same site on 2026-09-01, publishing 5 tags at 2 updates per second each (10 messages per second):

Broker	Publish round trip	QoS	Delivered per tag
AWS IoT Core (us-east-2)	47 ms	1	2.0 per second (full rate)
Azure Event Grid (canadacentral)	113 ms	1	1.6 per second (bounded by acknowledgments)
Azure Event Grid (canadacentral)	113 ms	0	1.9 per second (full rate)

Guidance: estimate your aggregate message rate and compare it against one message per round-trip time to your broker. If the stream is faster, either use qos: 0 and accept best-effort delivery on the last hop, or reduce the route's delivery rate. For loss-sensitive data, Flowgate's store and forward stream inside the chain remains the durable path; the cloud leg's QoS choice does not change what is durable inside the chain.

Verify it worked¶

Subscribe a second MQTT client (for Event Grid: a second registered client; for AWS: a second permitted client id) to spBv1.0/{group}/# and enable the connector. You should see, in order: one NBIRTH, one DBIRTH per device, then a steady DDATA stream at the route's delivery rate. Disabling the connector publishes an NDEATH.

Two broker behaviors to know while verifying:

Event Grid does not deliver a publish back to the session that sent it. A single client subscribing to its own publishes sees nothing. Use two sessions or two clients.
A denied subscription is silent in Flowgate's logs. If the NCMD subscription is not permitted, the broker's rejection is not surfaced; rebirth-on-request simply does not work. Confirm the subscribe permission on the broker side.

Troubleshooting¶

Symptom	Likely cause
Connector status stays `error`, log shows `timed out after 30s` on connect	The broker rejected the connection: wrong client id for the policy (AWS), authentication name mismatch in `client_id` or `username` (Event Grid), unregistered certificate thumbprint, or permission bindings still propagating. The broker closes the connection without a reason the client can log, so diagnose from the broker's own logs and metrics.
Connects, then drops on the first publish	A published topic is outside the broker's permitted set. Check the topic table above against the policy or topic space, including the `{device}` level.
TLS verification failure against Event Grid	A CA certificate was uploaded to the connector. Remove it: Event Grid needs the system trust store.
Data rate lower than the route's delivery rate	QoS 1 acknowledgment bound. See "Throughput and QoS".
Repeated NBIRTHs shortly after enabling against a fresh Event Grid namespace	The namespace settles for a minute or two after creation; the connector's reconnect loop rides through it. No action needed if it stabilizes.