IMD SolutionComputing LibraryShop main store

How-to

Writing MQTT Distributor ACL topic filters for Sparkplug B

Edge computing and IIoT Published 7 min read

Short answer

Give each Sparkplug B edge node its own credential with one write filter, spBv1.0/GroupID/+/EdgeNodeID/#, and two read filters, STATE/PrimaryHostID and the same node filter. The ACL is a plain MQTT topic matcher: pin the namespace, group and node as literals, wildcard the message type with + and the device level with #. Any publish or subscribe outside the granted filters disconnects the client, so the NDEATH will and the STATE subscription must be inside the entries.

On this page
  1. What the ACL entry matches
  2. Map the Sparkplug topic onto the filter
  3. The entries that scope one edge node
  4. The operations that disconnect a narrowed client
  5. Worked example: one node, three devices
  6. Apply the entries step by step
  7. Failure signatures
  8. What the primary host credential needs
  9. Questions asked

Scope each Sparkplug B edge node with its own username and two ACL entries in the Distributor: a write filter, spBv1.0/GroupID/+/EdgeNodeID/#, and read filters, STATE/PrimaryHostID plus spBv1.0/GroupID/+/EdgeNodeID/#, with the node's actual Group ID, Edge Node ID and primary host ID substituted in. The ACL is not Sparkplug-aware — it is a plain MQTT topic-filter matcher — but the Sparkplug topic structure is exactly what lets one entry cover everything a node does. The documented example W device_one/temp/#,R state/# shows the whole grammar: W grants publish, R grants subscribe, and a comma separates entries. Design around one behavior: outside the granted filters, the Distributor drops the client.

What the ACL entry matches #

Element Meaning
W Write privilege: the client may publish to topics matching the filter
R Read privilege: the client may subscribe to topics matching the filter
, Separates entries in the ACL field
/ Topic level separator
+ Matches exactly one topic level
# Matches any number of remaining levels, parent included, and must be the last character

Entries attach to a username and password pair, so the scope travels with the credential, not with the IP address. The policy behaves like a firewall rule set: a broad wildcard covers everything, and once you narrow the filters, every topic the client touches must be permitted explicitly. The wildcards are where most filters go wrong, so understand the failure modes behind mixing up # and * in topic rules before writing yours.

Map the Sparkplug topic onto the filter #

The Sparkplug specification defines the topic namespace as namespace/group_id/message_type/edge_node_id/[device_id] — five levels, the last present only on device messages. Map each level to a filter strategy:

Level Element Strategy
1 spBv1.0 Literal. Pin the namespace.
2 Group ID Literal. This is the isolation boundary between publishers.
3 Message type +. One level covers every verb the protocol uses.
4 Edge Node ID Literal. This is the per-gateway boundary.
5 Device ID, optional #. Covers node-level and device-level topics together.

The message type sits between the group and the node, so no prefix wildcard can pin both ends — the single-level + at level 3 is what makes the pattern work. The eight message types split across two depths: NBIRTH, NDATA, NDEATH and NCMD are node topics at four levels; DBIRTH, DDATA, DDEATH and DCMD are device topics at five. Because # also matches its parent level, one filter catches both depths: spBv1.0/PlantA/NDATA/Line1 (4 levels) and spBv1.0/PlantA/DDATA/Line1/Motor1 (5 levels) both match spBv1.0/PlantA/+/Line1/#.

The decision at level 3: never pin it to a literal. A node must publish births, data and its own death message, so the + stays no matter how narrow you make the rest.

The entries that scope one edge node #

W spBv1.0/GroupID/+/EdgeNodeID/#
R STATE/PrimaryHostID, spBv1.0/GroupID/+/EdgeNodeID/#

Enter these against a dedicated username and password created for that one gateway, whether the client is an Ignition edge node or a third-party Sparkplug B box. Read the entry in plain words: this credential may publish every Sparkplug message type for exactly this group and node, including every device under it, and may read the primary host's state topic plus its own command topics. GroupID, EdgeNodeID and PrimaryHostID are the exact strings configured on the gateway and the host application — substitution is the only edit you make.

The operations that disconnect a narrowed client #

  • The NDEATH will. A Sparkplug node registers its death topic, spBv1.0/PlantA/NDEATH/Line1, as the MQTT Will inside the CONNECT packet. If the will topic falls outside the write filter, the connection is refused or torn down at connect time, before the first birth ever publishes. The filter above already covers it, because + occupies the message-type level.
  • The state subscription. The node subscribes to the host application's state topic to decide whether the primary host is online; STATE/PrimaryHostID in the read entries is what permits that subscription, and omitting it drops the client like any other denied operation. Applying role-based rules on the STATE/PrimaryHostID topic is its own design subject when several hosts share a broker. The primary host registers its own will on that same topic, a separate rejection path covered in why a broker rejects a Sparkplug client over its STATE will.
  • Command subscriptions. The node subscribes to NCMD and DCMD for its own node, which is why the read entry mirrors the write entry. If commands still fail once the ACL is correct, the causes are the ones behind Sparkplug B sending data but receiving no SCADA commands.
  • Additional Group IDs. One gateway configured with a second transmitter set — a different Group ID or node ID — needs its own W and R entries for that set, or the client drops the moment the extra set publishes.

Worked example: one node, three devices #

Take a gateway with Group ID PlantA, Edge Node ID Line1, devices Motor1, Pump2 and VFD3, and a primary host SCADA1.

Write filter: spBv1.0/PlantA/+/Line1/#. Count what that one entry covers:

  • Node-level publishes: 3 message types (NBIRTH, NDATA, NDEATH) × 1 node = 3 topics.
  • Device-level publishes: 3 message types (DBIRTH, DDATA, DDEATH) × 3 devices = 9 topics.
  • Total: 3 + 9 = 12 publish topics matched by a single entry.

Read side: 1 NCMD topic + 3 DCMD topics + STATE/SCADA1 = 5 subscriptions, covered by the two read filters. Written out as literal topics, the same scope is 12 write entries plus 5 read entries — 17 lines. The two wildcards collapse that to 3.

Level check: spBv1.0/PlantA/NBIRTH/Line1 is 4 levels, spBv1.0/PlantA/DDATA/Line1/Motor1 is 5 levels, the + consumes exactly level 3 and # the remainder, so one filter spans both depths.

Rejection check: a test node publishing spBv1.0/PlantB/NDATA/Line1 misses at level 2 (PlantB does not equal PlantA), the publish is denied, and the Distributor disconnects the client. That is the acceptance test: if the rogue publish succeeds, the ACL is not applied to that credential.

Apply the entries step by step #

  1. Record the exact Group ID, Edge Node ID and primary host ID from the gateway configuration.
  2. Create a dedicated username and password in the Distributor for that one node; do not share the credential across gateways.
  3. In the lab, start permissive: W spBv1.0/# and R spBv1.0/# plus STATE/#, and confirm the node connects, births and streams.
  4. Subscribe to # with an administrator credential and capture every topic the node publishes and subscribes to.
  5. Narrow the entries to W spBv1.0/PlantA/+/Line1/# and R STATE/SCADA1, spBv1.0/PlantA/+/Line1/#.
  6. Restart the gateway connection and verify birth, data and a command round-trip.
  7. Point a test gateway at a foreign Group ID and confirm the Distributor disconnects it — run this in the lab, never against the running plant.
  8. Repeat per node and roll the entries to production in a maintenance window.

Failure signatures #

Symptom Likely ACL cause Fix
Connects, then drops, repeating Publish or subscribe outside the filters — often the NDEATH will or a second transmitter set Compare the captured topic list with the entries and add the exact missing topic
Connects but never births Write filter does not span the message-type level Use spBv1.0/PlantA/+/Line1/#, not a filter with level 3 pinned or missing
Data flows but commands never reach the device Read entries miss the node's NCMD/DCMD scope Mirror the write filter in the read entries
Disconnects as soon as it subscribes to the host state STATE/PrimaryHostID absent from the read entries Add the state topic to the read list

What the primary host credential needs #

The consuming side holds the inverse scope. The host application reads the whole namespace it serves — one entry, R spBv1.0/# — and writes the command topics it issues, which follow the same namespace: spBv1.0/PlantA/NCMD/Line1 for node commands, spBv1.0/PlantA/DCMD/Line1/Motor1 for device commands, plus its own STATE/SCADA1 topic where it publishes online and offline. Give the host one broad read entry, write entries limited to the command topics of the groups it actually commands, and a state write scoped to its own host ID. The consuming module's side is worked through entry by entry in the MQTT Engine ACL configuration for Sparkplug B.

Questions asked

Is the ACL scope tied to the username or the IP address?

To the username. ACL entries attach to a username and password pair in the Distributor, so the scope follows the credential wherever the gateway connects from. That is why each edge node needs its own username: two gateways sharing one credential inherit the same filters, and whichever node is not named in the entries is disconnected on its first publish.

Does capitalization matter in the topic filters?

Yes. Topic filters are case-sensitive, so the Group ID and Edge Node ID in the filter must match the gateway configuration character for character. A trailing space in either identifier is a common failure: the filter then names a node that does not exist, every publish misses it, and the client is disconnected. Copy the identifiers from the configuration rather than retyping them.

Can one credential cover a whole group instead of one node?

Yes. Write and read spBv1.0/PlantA/# grants that credential every node and device in group PlantA. Use it only when one gateway genuinely owns the whole group, for example a single box publishing several edge nodes under one Group ID. When separate gateways share a group, pin the Edge Node ID as well, so a misconfigured device cannot publish over a neighbor's data.

Do these ACL rules also work for non-Sparkplug MQTT devices?

Yes, because the ACL is a plain MQTT topic matcher and knows nothing about Sparkplug. For a device publishing ordinary topics, grant write on its own prefix, for example W workshop3/oven/#, and read only on the topics it actually subscribes to. Sparkplug simply hands you stable topic levels to pin; with arbitrary topics you choose the boundary yourself, and the same disconnect rule applies.

Keep reading

  • How-to

    Run a secure Mosquitto MQTT lab broker with Node-RED

    Run Mosquitto on port 8883 with TLS, per-user passwords and an ACL that lets each team write only under lab/teamN/# and read all of lab/#, with a separate Node-RED user that reads everything. Distribute ca.crt only, and prove the ACL by publishing to another team's prefix and seeing nothing arrive.

    Edge computing and IIoT

  • Explainer

    Securing ctrlX MQTT data paths to AWS or GCP

    Yes — Node-RED plus Mosquitto can carry ctrlX Data Layer values under X.509 authentication and TLS 1.2, but each of the three connections (publisher to broker, device to broker, uploader to cloud) needs its own trust and client-certificate configuration. DeviceBridge joins only when the chosen AWS or GCP service's protocol calls for it.

    Edge computing and IIoT

  • Troubleshooting

    Fix MQTT sensor data missing in Node-RED

    A green MQTT connection in Node-RED proves only a broker session, not that the GSM module published a value or that the flow subscribes to its topic. An http in node cannot receive MQTT publications at all: use an mqtt in node. Trace RS-485 acquisition, publish result, broker identity and topic match in order, and fix the first stage with no positive result.

    Edge computing and IIoT