Skip to content

Sparkplug B Protocol

Reference for Sparkplug B v1.0 implementation.

Topic Structure

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

Components

  • spBv1.0: Protocol version
  • group_id: Sparkplug group (logical grouping)
  • message_type: NBIRTH, NDEATH, DBIRTH, DDEATH, DDATA, DCMD, NCMD
  • edge_node_id: This gateway's ID
  • device_id: Modbus device ID (omit for node messages)

Message Types

NBIRTH (Node Birth)

Published: When edge node connects to broker

Topic: 

spBv1.0/{group}/NBIRTH/{node}

Contains: - Node metrics - bdSeq = 0 - Rebirth metric - Node Control/Metrics

NDEATH (Node Death)

Published: - Gracefully: Before disconnect - LWT: By broker on unexpected disconnect

Topic: 

spBv1.0/{group}/NDEATH/{node}

Contains: - bdSeq = 0

DBIRTH (Device Birth)

Published: When device starts polling

Topic: 

spBv1.0/{group}/DBIRTH/{node}/{device}

Contains: - All tag definitions - Metric aliases - Data types - seq = 0

DDATA (Device Data)

Published: Tag values on each poll

Topic: 

spBv1.0/{group}/DDATA/{node}/{device}

Contains: - Tag values (by alias) - Timestamp - Incrementing seq

DCMD (Device Command)

Received: Write commands from SCADA

Topic: 

spBv1.0/{group}/DCMD/{node}/{device}

Contains: - Metric name - Value to write - Data type

NCMD (Node Command)

Received: Node control commands

Topic: 

spBv1.0/{group}/NCMD/{node}

Commands: - Rebirth request

Sequence Numbers

bdSeq (Birth/Death Sequence)

  • Always = 0 for NBIRTH/NDEATH
  • Never incremented
  • Fixed value per Sparkplug spec

seq (Message Sequence)

  • Starts at 0 on DBIRTH
  • Increments with each DDATA
  • Wraps at 256
  • Used to detect missing messages

Metric Aliasing

DBIRTH

Defines all metrics with aliases: 

{
  "name": "Motor_Speed",
  "alias": 1,
  "dataType": "Float",
  "value": 0
}

DDATA

References by alias only: 

{
  "alias": 1,
  "value": 1750.5
}

Benefits: - Reduced message size - Lower bandwidth

Data Types

Sparkplug Type Description
Int8, Int16, Int32, Int64 Signed integers
UInt8, UInt16, UInt32, UInt64 Unsigned integers
Float 32-bit float
Double 64-bit float
Boolean True/false
String Text
DateTime Timestamp
Text UTF-8 text

Best Practices

  • Always publish NBIRTH on connect
  • Use LWT for unexpected disconnects
  • Increment seq properly
  • Use metric aliases
  • Include timestamps
  • Validate DCMD before writing

Example Flow

  1. Gateway connects to MQTT
  2. Publish NBIRTH
  3. Start device polling
  4. Publish DBIRTH with all tags
  5. Publish DDATA with values
  6. On disconnect, publish NDEATH

Next Steps