Sparkplug B Route

Give industrial MQTT data a shared structure

The SPARKPLUG_B route connects Coreflux to a Sparkplug B namespace. It can decode binary Sparkplug payloads into readable JSON, publish local MQTT topics as a Sparkplug edge node, or run both directions in one route.

Sparkplug is a shared vocabulary for industrial MQTT. MQTT carries the messages; Sparkplug defines how devices announce themselves, report values, and signal whether they are online.

When to use it

Use this route when you need to:

consume spBv1.0/# traffic in LoT Actions, dashboards, or storage Routes;
publish Coreflux topics as NBIRTH, NDATA, and NDEATH;
group edge-node metrics into Sparkplug devices;
accept NCMD or DCMD writes for selected metrics; or
gate edge-node publishing on an external Primary Host.

Use the separate Sparkplug Host Route when Coreflux must be the Primary Host Application.

Start by choosing the direction in which Coreflux participates.

Quick Start

Decode to JSON
Publish as an edge node
Decode and publish

Decode every Sparkplug B publisher on the local broker into readable MQTT topics:

DEFINE ROUTE PlantDecoder WITH TYPE SPARKPLUG_B
    ADD SPARKPLUG_CONFIG
        WITH MODE "DECODE"

This mode listens to all spBv1.0/# traffic. You do not need a Group ID or Edge Node ID.

Publish a local temperature topic as a Sparkplug edge-node metric:

DEFINE ROUTE Line1Edge WITH TYPE SPARKPLUG_B
    ADD SPARKPLUG_CONFIG
        WITH MODE "ENCODE"
        WITH GROUP_ID "Factory"
        WITH EDGE_NODE_ID "Line1"
    ADD METRIC "Temperature"
        WITH DATA_TYPE "Float"
        WITH SOURCE_TOPIC "factory/line1/temperature"

Coreflux publishes a birth certificate when the route connects and sends data when the source topic changes.

Decode the namespace while publishing Coreflux metrics as a gateway edge node:

DEFINE ROUTE PlantGateway WITH TYPE SPARKPLUG_B
    ADD SPARKPLUG_CONFIG
        WITH MODE "BOTH"
        WITH GROUP_ID "Factory"
        WITH EDGE_NODE_ID "CorefluxGateway"
    ADD METRIC "Uptime"
        WITH DATA_TYPE "Int64"
        WITH SOURCE_TOPIC "gateway/uptime"

The decode and encode paths operate independently inside the same route.

Choose the Coreflux role

Mode	Coreflux role	Inbound behavior	Outbound behavior
`DECODE`	Translator and consumer	Decodes all `spBv1.0/#` traffic	None
`ENCODE`	Sparkplug edge node	Handles commands for writable metrics	Publishes birth, data, and death messages
`BOTH`	Translator and edge node	Decodes the namespace and handles commands	Publishes Coreflux metrics

MODE is the canonical setting. DIRECTION remains accepted as a deprecated alias with the same values.

Only one namespace consumer can run per broker. Deploy either one SPARKPLUG_B route in DECODE or BOTH mode, or one SPARKPLUG_HOST route. Multiple ENCODE-only routes are allowed.

Configure the Sparkplug connection

The SPARKPLUG_CONFIG block controls the route mode, edge-node identity, target MQTT broker, and optional Primary Host gating.

Setting	Required	Default	Description
`MODE`	No	`DECODE`	`DECODE`, `ENCODE`, or `BOTH`
`GROUP_ID`	For `ENCODE`/`BOTH`	—	Group identity Coreflux publishes on the Sparkplug wire
`EDGE_NODE_ID`	For `ENCODE`/`BOTH`	—	Unique edge-node identity within the group
`PRIMARY_HOST_ID`	No	—	External Primary Host whose retained `STATE` gates edge publishing
`SERVER`	No	`localhost`	MQTT broker used by the encode path
`PORT`	No	`1883`	Target MQTT broker port
`USERNAME`	No	—	Target broker username
`PASSWORD`	No	—	Target broker password; use `GET SECRET`
`USE_TLS`	No	`false`	Enables TLS for the target broker connection

GROUP_ID and EDGE_NODE_ID do not filter decoded traffic. The decode path always consumes the complete spBv1.0/# namespace.

Declare edge-node metrics

In ENCODE or BOTH mode, add node-level metrics directly to the route and device-level metrics inside ADD DEVICE.

Setting	Required	Description
`DATA_TYPE`	Yes	Sparkplug datatype for the metric
`SOURCE_TOPIC`	Yes	Local MQTT topic whose value Coreflux publishes
`WRITE_TOPIC` or `DESTINATION_TOPIC`	For command write-back	Local topic that receives an inbound command value
`WRITABLE`	No	Set to `"true"` to accept `NCMD` or `DCMD` writes

This complete route publishes a node metric and a writable device metric to a remote broker:

DEFINE ROUTE Line1Edge WITH TYPE SPARKPLUG_B
    ADD SPARKPLUG_CONFIG
        WITH MODE "ENCODE"
        WITH GROUP_ID "Factory"
        WITH EDGE_NODE_ID "Line1"
        WITH SERVER GET ENV "SPARKPLUG_BROKER"
        WITH PORT 8883
        WITH USERNAME GET ENV "SPARKPLUG_USER"
        WITH PASSWORD GET SECRET "SPARKPLUG_PASSWORD"
        WITH USE_TLS true
    ADD METRIC "Uptime"
        WITH DATA_TYPE "Int64"
        WITH SOURCE_TOPIC "factory/line1/uptime"
    ADD DEVICE "Press01"
        ADD METRIC "Setpoint"
            WITH DATA_TYPE "Float"
            WITH SOURCE_TOPIC "factory/line1/press01/setpoint"
            WITH WRITE_TOPIC "factory/line1/press01/setpoint/write"
            WITH WRITABLE "true"

Supported scalar and array datatypes include signed and unsigned integers, Float, Double, Boolean, String, Text, UUID, DateTime, and Bytes. DataSet and Template values can be decoded but not encoded.

Understand the message lifecycle

When the encode path connects, Coreflux:

publishes NBIRTH, including bdSeq and Node Control/Rebirth;
publishes one DBIRTH for each declared device;
publishes NDATA or DDATA when a source topic changes;
republishes births after a Node Control/Rebirth command; and
publishes death messages on a graceful stop or delivers NDEATH through the MQTT Will after a crash.

Writable node and device metrics accept inbound NCMD and DCMD values. Coreflux republishes each accepted value to its local write topic.

Gate publishing on a Primary Host

Set PRIMARY_HOST_ID when an external Primary Host must be online before the edge node publishes:

DEFINE ROUTE GatedEdge WITH TYPE SPARKPLUG_B
    ADD SPARKPLUG_CONFIG
        WITH MODE "ENCODE"
        WITH GROUP_ID "Factory"
        WITH EDGE_NODE_ID "Line1"
        WITH PRIMARY_HOST_ID "PlantHost"
    ADD METRIC "Temperature"
        WITH DATA_TYPE "Float"
        WITH SOURCE_TOPIC "factory/line1/temperature"

The route watches the retained spBv1.0/STATE/PlantHost topic. It defers births and suppresses data until the host reports online:true, then publishes fresh births and resumes data.

Primary Host gating does not buffer values. Data produced while the host is offline is dropped, and multi-server Primary Host failover is not supported.

Consume decoded topics

The decode path converts the fixed Sparkplug wire namespace into a JSON topic tree:

spBv1.0/<group>/<verb>/<node>/<device>
  → sparkplug/decoded/<group>/<node>/<device>/<metric>

spBv1.0/<group>/<verb>/<node>
  → sparkplug/decoded/<group>/<node>/<metric>

Each decoded metric contains its canonical name, value, datatype, timestamp, and quality:

{
  "name": "Inputs/Temperature",
  "value": 24.6,
  "type": "Double",
  "timestamp": 1717160400123,
  "quality": "GOOD"
}

The route also publishes:

Topic suffix	Retained	Purpose
`/<metric>`	No	Latest decoded metric event
`/$status`	Yes	Node or device online state from BIRTH and DEATH
`/$error`	No	Decode or alias-resolution error

Metric names containing / create deeper topic levels. The name field in the JSON payload remains authoritative.

Verify the route

Check route health

Publish the connection check command to $SYS/Coreflux/Command:

-checkRouteConnection PlantDecoder

Confirm $SYS/Coreflux/Routes/PlantDecoder/status reports the route as connected or active.

Observe Sparkplug traffic

Use any MQTT client to confirm messages arrive under spBv1.0/#.

Subscribe to decoded output

Subscribe to sparkplug/decoded/#. After a BIRTH message, named metric topics and retained $status topics appear.

Troubleshooting

No decoded topics appear

Confirm the route is active and that a Sparkplug B publisher is sending valid protobuf payloads under spBv1.0/#. Decoded output appears under sparkplug/decoded/#.

Metrics appear with unresolved aliases

Alias-only DATA arrived before its matching BIRTH. Wait for or request a rebirth and monitor $error for alias_map_unavailable.

The edge node remains silent

If PRIMARY_HOST_ID is configured, confirm the matching host publishes retained {"online":true} state on the same target broker configured by SERVER and PORT.

Commands do not reach local topics

Confirm the metric has WRITABLE "true" and a WRITE_TOPIC or DESTINATION_TOPIC. Read-only metrics reject inbound commands.

Best Practices

Give every edge node a unique GROUP_ID and EDGE_NODE_ID pair.
Build automations on sparkplug/decoded/#, not on opaque protobuf topics.
Use retained $status topics for availability checks.
Load broker credentials with GET ENV and GET SECRET.
Monitor $error and route status for repeated alias or decode failures.

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Using AI with Coreflux

Product Updates

Give industrial MQTT data a shared structure

When to use it

Quick Start

Choose the Coreflux role

Configure the Sparkplug connection

Declare edge-node metrics

Understand the message lifecycle

Gate publishing on a Primary Host

Consume decoded topics

Verify the route

Troubleshooting

Best Practices

Next Steps

Configure Sparkplug Host

Store decoded data

​Give industrial MQTT data a shared structure

​When to use it

​Quick Start

​Choose the Coreflux role

​Configure the Sparkplug connection

​Declare edge-node metrics

​Understand the message lifecycle

​Gate publishing on a Primary Host

​Consume decoded topics

​Verify the route

​Troubleshooting

​Best Practices

​Next Steps

Configure Sparkplug Host

Store decoded data

Give industrial MQTT data a shared structure

When to use it

Quick Start

Choose the Coreflux role

Configure the Sparkplug connection

Declare edge-node metrics

Understand the message lifecycle

Gate publishing on a Primary Host

Consume decoded topics

Verify the route

Troubleshooting

Best Practices

Next Steps