SparkPlug B Integration Guide

Use MaestroHub's SparkPlug B connector to publish industrial metrics to SCADA systems, historians, and IoT platforms. MaestroHub operates as a SparkPlug B Edge Node (EoN), automatically managing birth/death certificates, sequence numbers, and Protocol Buffers encoding according to the SparkPlug B specification.

Overview

The SparkPlug B connector delivers:

• Edge Node (EoN) Publisher role with automatic NBIRTH/NDEATH lifecycle management
• Automatic DBIRTH/DDEATH handling for devices on first data and disconnect
• Protocol Buffers encoding for efficient, standardized message payloads
• Sequence number management ensuring proper message ordering
• Last Will and Testament (LWT) for graceful and unexpected disconnection handling
• Subscribe function that listens to SparkPlug B traffic from other edge nodes and drives the SparkPlug B Trigger in pipelines
• Discover tab to watch live SparkPlug B traffic on the broker and create subscribe functions from it

SparkPlug B Specification

SparkPlug B is an open specification that defines how to use MQTT in industrial environments. It provides a consistent topic namespace, payload format, and state management model. For more details, see the Eclipse SparkPlug Specification.

Connection Configuration

Creating a SparkPlug B Connection

Navigate to Connections → New Connection → SparkPlug B and fill in these details:

SparkPlug B Connection Creation Fields

1. Profile Information

Field	Default	Description
Profile Name	-	A descriptive name for this connection profile (required, max 100 characters)
Description	-	Optional description for this SparkPlug B connection

2. MQTT Broker Configuration

Field	Default	Description
Broker	-	MQTT broker hostname or IP address (e.g., broker.example.com) – required
Port	1883	MQTT broker port (1-65535)
Scheme	tcp	Connection scheme: tcp, ssl, ws, or wss. ssl and wss always use TLS; tcp with TLS enabled connects as ssl
Client ID	-	MQTT client identifier. Auto-generated as maestrohub-spb-{connectionId} if not provided

3. SparkPlug B Namespace Configuration

Field	Default	Description
Group ID	-	SparkPlug B group identifier (required). Represents a logical grouping of Edge Nodes (e.g., factory-floor, building-a)
Edge Node ID	-	Unique Edge Node identifier within the group (required). Represents this MaestroHub instance (e.g., edge-node-01, plc-gateway)

Topic Namespace

SparkPlug B uses a standardized topic structure:

spBv1.0/{group_id}/{message_type}/{edge_node_id}[/{device_id}]

Example topics:

• spBv1.0/factory/NBIRTH/edge-node-1 – Node birth certificate
• spBv1.0/factory/DDATA/edge-node-1/sensor-01 – Device data
• spBv1.0/factory/DDEATH/edge-node-1/sensor-01 – Device death certificate

4. Authentication

Field	Default	Description
Username	-	MQTT broker username (optional)
Password	-	MQTT broker password (optional)

5. TLS/SSL Settings

Field	Default	Description
Enable TLS	false	Use encrypted connection to the MQTT broker. Always on for ssl / wss; not available with ws (plain WebSocket) — use wss instead

TLS Configuration

When TLS is enabled on the tcp scheme, the connection uses ssl. TLS over WebSocket needs the wss scheme; ws with TLS enabled is refused at save time. For production environments, ensure your MQTT broker has proper certificate configuration.

6. Connection Settings

Field	Default	Description
Clean Session	true	Start with a clean session on connect
Keep Alive (seconds)	60	Keep-alive interval in seconds
Connect Timeout (seconds)	30	Connection timeout in seconds

7. Connection Labels

Field	Default	Description
Labels	-	Key-value pairs to categorize and organize this SparkPlug B connection (max 10 labels)

Example Labels

• environment: production – Deployment environment
• team: automation – Responsible team
• protocol: sparkplugb – Connection protocol
• region: us-east-1 – Geographical region

Notes

• Single Ownership: SparkPlug B connections require exclusive scaling because birth/death certificates and sequence numbers must be managed by a single instance.
• Automatic LWT: The connector automatically configures Last Will and Testament with NDEATH payload to ensure proper death certificate delivery on unexpected disconnection.
• Sequence Numbers: Message sequence numbers (0-255) and birth-death sequence numbers (bdSeq) are managed automatically and wrap at 256.

Function Builder

Creating SparkPlug B Functions

After the connection is configured:

1. Open the connection and go to its Functions tab → New Function
2. Choose Publish Device Data to publish metrics, or Subscribe to listen to SparkPlug B messages
3. Define the device ID and metrics to publish, or the subscription scope and message types

Publish Device Data Function

Purpose: Send device metric values (DDATA) to SCADA systems. The connector automatically manages device birth/death certificates — a DBIRTH is published on the first data message for each device.

Configuration Fields

Field	Type	Required	Default	Description
Device ID	String	Yes	-	Unique device identifier within this Edge Node (e.g., sensor-01, plc-line-1)
Metrics	Object	Yes	-	Map of metric names to values. Must contain at least one metric. Supports parameter templates

Metric Data Types

The Metrics editor shows each metric as a row with a name, a Type, and a value, and can switch to raw JSON. The Type list offers Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, Float, Double, Boolean, String, DateTime, Text, and UUID. When a metric is added from JSON, its type is pre-selected from the value: a negative whole number gets Int32, other whole numbers UInt32, decimals Double, true/false Boolean, and anything else String. Change it when the guess is wrong.

The editor uses the Type to convert what you type: integer types and Float/Double save the value as a number, Boolean as true/false, and String, DateTime, Text, and UUID as text.

When the function runs, the connector sets the published SparkPlug B data type from the value it receives, not from the Type column:

Value Type	SparkPlug B Type	Description
int, int64	Int64	64-bit signed integer
int8	Int8	8-bit signed integer
int16	Int16	16-bit signed integer
int32	Int32	32-bit signed integer
uint, uint64	UInt64	64-bit unsigned integer
uint8	UInt8	8-bit unsigned integer
uint16	UInt16	16-bit unsigned integer
uint32	UInt32	32-bit unsigned integer
float32	Float	32-bit floating point
float64	Double	64-bit floating point
bool	Boolean	True/false value
string	String	Text value
[]byte	Bytes	Binary data
time.Time	DateTime	Timestamp (milliseconds since epoch)

Numbers saved in the function are published as Double

A number saved in the function's metrics is read back as a 64-bit float, so it is published as Double whichever integer type the editor shows. Integer types are published only when the value arrives as an integer at run time, for example through a parameter bound to an upstream node's output.

Use Cases: Sensor data publishing, real-time telemetry, periodic data reporting, status metric updates

Example Metrics Configuration

{
  "temperature": 23.5,
  "pressure": 101.3,
  "running": true,
  "status": "operational",
  "count": 42
}

Using Parameters

SparkPlug B functions support parameterized metric values via the ((parameterName)) syntax.

Configuration	Description	Example
Type	Validate incoming pipeline data	string, number, boolean, datetime, json, buffer
Required	Force presence of the parameter	Required / Optional
Default Value	Provide fallback values	0, false, "unknown"
Description	Document intent for other authors	"Current temperature reading from sensor"

Example with Parameters

{
  "temperature": "((sensorTemp))",
  "pressure": "((sensorPressure))",
  "timestamp": "((now))"
}

Subscribe Function

Purpose: Listen to SparkPlug B messages that other edge nodes publish on the broker. The connector decodes each Protocol Buffers payload into a map of metric names to values. NDATA and DDATA carry metrics by numeric alias only, so the connector always tracks NBIRTH and DBIRTH messages to resolve aliases to names. Use the function as the source of a SparkPlug B Trigger node in a pipeline.

This is a passive listener, not a SparkPlug B Host Application: it does not publish STATE messages, request rebirths, or send NCMD/DCMD commands.

Configuration Fields

Field	Type	Required	Default	Description
Group ID	String	No	Connection's Group ID	Group to listen to. Use + for any group
Edge Node ID	String	No	Connection's Edge Node ID	Edge node to listen to. Use + for any edge node
Device ID	String	No	-	Device to listen to. Leave blank or use + for all devices under the edge node
Message Types	Array	No	NBIRTH, NDEATH, NDATA, DBIRTH, DDEATH, DDATA	Message types that fire the trigger. BIRTH messages are tracked for alias decoding even when unchecked
Timeout	Duration	No	-	Optional upper bound on how long the operation may run (1s - 1h)

Discover Tab

The connection's Discover tab, available once the connection is saved, shows the SparkPlug B traffic on the broker before you create functions:

1. Enter a topic filter, for example spBv1.0/# for all SparkPlug B traffic or spBv1.0/factory/# for one group, and click Start Discovery.
2. Arriving topics build up in the Topic Tree. Select a topic to see its latest message.
3. Click Create Subscribe Function to create a Subscribe function scoped to that topic's group, edge node, device, and message type.
4. Click Stop Discovery when you are done. Only one discovery session can run on a connection at a time.

SparkPlug B Message Lifecycle

Automatic Message Management

The SparkPlug B connector automatically manages the complete message lifecycle:

Message Type	When Published	Purpose
NBIRTH	Automatically on connection	Announces the Edge Node is online and provides its initial state
NDEATH	On graceful disconnect or via LWT on unexpected disconnect	Announces the Edge Node is offline
DBIRTH	Automatically on first DDATA for each device	Announces a device is online and provides its metric schema
DDEATH	Automatically on disconnect	Announces a device is offline
DDATA	When you call the Publish Device Data function	Contains updated metric values for a device

Birth-Death Sequence (bdSeq)

The bdSeq metric correlates NBIRTH and NDEATH messages. SCADA host applications use this to:

• Detect if they missed any death certificates
• Determine if the current birth certificate is the latest
• Properly handle reconnection scenarios

Pipeline Integration

Use the SparkPlug B connection functions you create here as nodes inside the Pipeline Designer to publish industrial metrics to SCADA systems. Drag in the Publish Device Data node, bind its parameters to upstream node outputs or constants, and build event-driven flows for your industrial data. To start a pipeline when SparkPlug B messages arrive, add a SparkPlug B Trigger node and select a Subscribe function.

If you are planning broader orchestration, review the Connector Nodes page for guidance on where SparkPlug B nodes fit within multi-system automation patterns.

Common Use Cases

SCADA Integration

Publish real-time process data from PLCs and sensors to SCADA systems that support SparkPlug B, enabling standardized data exchange without custom parsing.

Historian Connectivity

Stream time-series data to historians like Ignition, InfluxDB, or cloud-based solutions that consume SparkPlug B messages for long-term storage and analysis.

Edge-to-Cloud Telemetry

Bridge legacy industrial protocols (OPC UA, Modbus, Siemens S7) to cloud IoT platforms by combining reads from those protocols with SparkPlug B publish steps.

Multi-Site Data Aggregation

Use consistent Group ID naming across sites to aggregate data from multiple factories or buildings into a central SCADA or analytics platform.

Digital Twin Integration

Feed real-time equipment metrics to digital twin platforms that consume SparkPlug B messages, keeping virtual models synchronized with physical assets.

Quality on subscribed frames

Every frame a Sparkplug B trigger delivers carries _metadata.quality. For NDATA / DDATA it is the worst-of fold of the metrics' Quality property (192 → good, 500 → uncertain, 0 → bad; absent when no metric states one). NDEATH and DDEATH are always bad: a death certificate is the edge node's statement, or the broker's last-will on its behalf, that its data has stopped being trustworthy, and its payload carries only bdSeq, so the frame itself is the verdict. A UNS Publish node downstream inherits it, so the moment an edge node dies is stored as a Bad sample rather than a Good-looking event.