Sparkplug B Integration
How to use Connectware as the central MQTT broker for a Sparkplug B infrastructure, including the topic namespace, permissions for edge nodes and host applications, and the STATE mechanism.
This guide describes how to use Connectware as the central MQTT broker (MQTT Server) of a Sparkplug B infrastructure. Sparkplug edge nodes and host applications, such as a SCADA system, connect to the Connectware broker, and Connectware provides the users, permissions, and routing for the Sparkplug namespace. A complete example file is available at the end of this guide.
Objectives
Understanding the Sparkplug B topic namespace and how Connectware handles Sparkplug traffic.
Creating Connectware users and roles with least-privilege permissions for edge nodes and host applications.
Understanding the STATE mechanism that announces the availability of a host application.
Mirroring Sparkplug traffic to internal topics for monitoring.
Prerequisites
To follow this guide, you will need the following:
A running instance of Cybus Connectware.
One or more Sparkplug B edge nodes, for example devices based on the Eclipse Tahu client libraries or an Ignition gateway with the MQTT Transmission module, and a Sparkplug host application, such as a SCADA system. All of them must have network access to the Connectware MQTT broker on port
8883(TLS) or1883.Access to the Admin UI with sufficient user permissions.
Basic knowledge of MQTT and the Connectware services concept (for example, service commissioning files, mappings, and roles).
It helps to be familiar with Connecting an MQTT Client to Publish and Subscribe Data.
Connectware and Sparkplug B Integration
Sparkplug is an open specification by the Eclipse Foundation that defines a topic namespace, a payload encoding, and session state management on top of MQTT. Sparkplug is broker-centric by design: edge nodes publish their data to a central MQTT Server, and host applications consume it from there. The participants never talk to each other directly.
Sparkplug defines the clients, but not the broker. Connectware fills this role:
Central broker: Edge nodes from different vendors and any number of host applications all connect to the same Connectware instance.
Governed access: Connectware permissions restrict each edge node to its own topic subtree, so one misconfigured or compromised node cannot publish data or death certificates for another.
Standard MQTT features: Sparkplug relies on MQTT last will messages and retained messages for its session management. The Connectware broker supports both, so no Sparkplug-specific broker extensions are required.
This guide follows the Sparkplug 3.0 specification.
The Sparkplug B Topic Namespace
All Sparkplug B messages use the following topic structure, where the device_id element is only present on device-level messages:
The group ID logically groups edge nodes, for example by site or production line. The combination of group ID and edge node ID must be unique in the entire infrastructure. The message type determines the direction and the semantics of the message:
NBIRTH
Edge node
Birth certificate with every metric the edge node will ever report.
0
No
NDEATH
Broker or edge node
Death certificate containing the bdSeq number that links it to the NBIRTH.
1
No
DBIRTH
Edge node
Birth certificate for a device attached to the edge node.
0
No
DDEATH
Edge node
Death certificate for a device that became unavailable.
0
No
NDATA
Edge node
Metrics of the edge node that changed since the last message.
0
No
DDATA
Edge node
Metrics of a device that changed since the last message.
0
No
NCMD
Host application
Command that writes metrics on the edge node, including rebirth requests.
0
No
DCMD
Host application
Command that writes metrics on a device.
0
No
STATE
Host application
Birth and death certificate of a host application, as JSON.
1
Yes
The QoS and retained flags in the table are mandated by the specification. The clients set them on their own publishes; there is nothing to configure in Connectware for this.
The NDEATH message is special: the edge node registers it as an MQTT last will when it connects. If the connection drops unexpectedly, the Connectware broker publishes the NDEATH on behalf of the edge node, and every subscribed host application marks the metrics of that node as stale. Before a graceful disconnect, the edge node publishes the NDEATH itself. Because the broker publishes the last will under the identity of the edge node client, the edge node user needs write permission on its NDEATH topic like on any other topic it publishes to.
The STATE message does not follow the standard topic structure. It lives directly under the namespace element:
How Connectware Handles Sparkplug B Payloads
Except for the STATE message, all Sparkplug B payloads are binary data, encoded with Google Protocol Buffers (protobuf). Connectware routes these messages like any other MQTT message and enforces permissions on their topics, but it cannot decode the payloads out of the box:
The Rule Engine cannot parse, filter, or transform protobuf payloads.
Mappings can republish the messages to other topics, but the payload passes through unchanged. Do not attach
transformrules to Sparkplug topics.The Data Explorer shows that messages arrive on a topic, but cannot display the metric values inside.
Consumers that need the decoded metric values must either be Sparkplug-aware themselves, for example a SCADA system or a client built on the Eclipse Tahu libraries, or use a decoding service between the Sparkplug namespace and the rest of your infrastructure, for example a custom connector that subscribes to the Sparkplug topics and republishes the metrics as JSON.
The one exception is the STATE message: its payload is plain JSON, so Connectware can read and transform it. The monitoring mapping in this guide uses this.
If your edge nodes are Ignition gateways, you can avoid the protobuf limitation entirely: since release 4.0.25, the MQTT Transmission module includes the UNS Transmitter, which publishes tag values as plain JSON instead of Sparkplug B. For the trade-offs and the setup, see Ignition Integration.
Creating Users and Permissions
Edge nodes and host applications authenticate against Connectware with username and password, like any other MQTT client. For more information, see MQTT Client Authentication. We create the users and their roles in the service commissioning file with the Cybus::User and Cybus::Role resources.
Do not worry about copying the service commissioning file snippets together into one, the complete example file is available at the end of this guide.
Integration Parameters
We add the Sparkplug identifiers and the passwords as parameters, so you can set them when you install the service:
groupIdandedgeNodeId: Identify the edge node in the Sparkplug topic namespace. They must match the values configured on the edge node itself.hostId: The Sparkplug host ID of the host application, used in theSTATEtopic.edgeNodePasswordandhostAppPassword: The passwords for the two MQTT users.
Edge Node User and Role
The edge node publishes its birth, death, and data messages for itself and its attached devices, and subscribes to its own command topics. If the edge node is configured with a primary host application, it also subscribes to the STATE topic of that host to detect whether the host is online. The role grants exactly these permissions, restricted to the subtree of this one edge node:
The resource identifier of the user becomes the username, prefixed with the service ID that you assign when you install the service. For example, with the service ID sparkplug, the edge node authenticates as sparkplug.edge_press_line_01. If you change the edgeNodeId parameter, rename the user resource accordingly. When you operate several edge nodes, add one user and one role per node, so each node stays restricted to its own subtree.
Instead of defining edge node users in the service commissioning file, you can also let devices register themselves via the Client Registry and assign the permissions in the Admin UI. This is convenient when edge nodes are commissioned one by one on the shop floor.
Host Application User and Role
The host application needs the opposite permissions, across all edge nodes: it subscribes to the entire Sparkplug namespace, publishes commands, and publishes its own STATE birth and death certificates. The read permission on spBv1.0/# also covers the subscription to its own STATE topic, which the specification requires:
To allow the host application to send commands to edge nodes in more than one group, add one NCMD and one DCMD permission per group.
The STATE Mechanism
Edge nodes need to know whether their primary host application is online: if it is not, an edge node can buffer data locally instead of publishing into the void. Sparkplug solves this with the STATE message on the topic spBv1.0/STATE/<sparkplug_host_id>.
The mechanism uses the same last will pattern as the NDEATH message, but with a plain JSON payload:
When the host application connects, it registers an MQTT last will on its
STATEtopic with the payload{"online": false, "timestamp": ...}, QoS 1, and the retained flag.Immediately after subscribing to its own
STATEtopic, the host application publishes{"online": true, "timestamp": ...}as a retained message with QoS 1. The timestamp matches the one in the registered last will.If the host application disconnects gracefully, it publishes the
online: falsepayload itself. If the connection drops unexpectedly, the Connectware broker publishes the registered last will instead.
Because the message is retained, the STATE topic always carries the current availability of the host application. An edge node that connects later receives it immediately, without waiting for the next state change.
Clients that implement Sparkplug 2.2 or earlier publish the STATE message on the legacy topic STATE/<host_id>, outside the spBv1.0 namespace, with the plain-text payloads ONLINE and OFFLINE. If your infrastructure mixes specification versions, grant the host application write permission on STATE/${hostId} and the edge nodes read permission on it, in addition to the permissions shown in this guide.
Mirroring Sparkplug Traffic for Monitoring
Consumers outside the Sparkplug infrastructure sometimes need visibility into the namespace without receiving Sparkplug permissions themselves, for example a diagnostics dashboard that shows which nodes are alive. A Cybus::Mapping can mirror the Sparkplug namespace to an internal topic subtree. The named wildcard #topic carries the remainder of the topic path over to the output topic:
The first mapping entry re-routes every Sparkplug message to the sparkplug/monitor subtree. The payloads remain protobuf-encoded binary; the mapping changes where the messages go, not what they contain. Consumers of the mirrored topics can observe topic activity and message frequency, but still need a Sparkplug decoder to read the metric values.
The second mapping entry handles the one JSON message in the namespace: it republishes the availability of every host application to a retained topic per host, where any dashboard or alerting service can consume it directly.
Bridging Sparkplug Traffic to Another Broker
To forward Sparkplug traffic to an MQTT broker outside Connectware, use the MQTT connector. It passes payloads through unmodified in both directions, so the protobuf encoding is preserved.
A forwarded copy of the traffic is informational only: Sparkplug session management depends on last will messages, retained STATE messages, and bdSeq numbers on the broker that the clients are connected to. A bridge does not replicate this session state. Sparkplug participants that take part in the birth and death handshake must connect directly to the Connectware broker.
Verifying the Integration
Install the service and set the parameters, including the two passwords. See Installing Services.
Configure the edge node and the host application with the Connectware hostname, port
8883(TLS) or1883, and their usernames and passwords. Remember that the usernames are prefixed with the service ID, for examplesparkplug.edge_press_line_01andsparkplug.scada_primary.Open the Data Explorer and subscribe to
spBv1.0/#. When the host application connects, its retainedSTATEmessage appears. When the edge node connects, itsNBIRTHandDBIRTHmessages follow. The payloads of the birth and data messages are binary and are not displayed as readable values; seeing the messages arrive on the correct topics is the verification.Verify the permission enforcement: publish to the subtree of a different edge node with the edge node credentials, for example to
spBv1.0/plant-hamburg/NDATA/some-other-node. The Connectware broker denies the publish, and the message does not appear in the Data Explorer.
To check the mirrored host state, subscribe with an MQTT client such as mosquitto_sub:
Replace the following values:
${CONNECTWARE_HOST}: The hostname or IP address of your Connectware instance.${MONITOR_USER}and${MONITOR_PASSWORD}: A Connectware user with read permission onsparkplug/#, for example your own user.
The output shows one retained message per host application, for example sparkplug/host-state/scada-primary {"online":true,"timestamp":1752664800000}.
Service Commissioning File Example
Last updated
Was this helpful?