Sparkplug Payloads and Messages

In a Sparkplug MQTT network there is no direct link between end nodes and the primary application (control node).

All communication between nodes is via a central MQTT server.

In this tutorial we will look at the message payloads and  how the various components establish a session with the MQTT broker and what they publish.



A diagram of a Sparkplug network is shown below for reference.

Basic-Sparkplug-Infrastructure

Sparkplug Payload Basics

The Sparkplug payload uses Google Protocol buffers which is a way of representing complex data as a string and functions in a similar way to JSON.

Google Protocol buffersare more complex than JSON, but that complexity is taken care of in libraries which are available for all major languages.

A Sparkplug payload contains a series of metrics (readings). The metric has a:

  1. Name
  2. Alias
  3. Time stamp
  4. Data type
  5. Value

Below is an example taken from a EON birth message (NBIRTH)

sparkplug-metrics

Note: The alias published in the metric can be used in place of the name in subsequent messages.

All messages published have a sequence number starting at 0 and ending at 255 after which it is reset to 0.

All messages include a time stamp for the message and also a time stamp for each metric in the message.

Data Types aren’t part of the Sparkplug B specification but are defined in the client libraries. A numeric code is assigned to the data type.Below shows the python client library data type declaration.

sparkplug-datatypes-python

Sparkplug Message Basics

There are five basic message types:

  • Birth
  • Death
  • Data
  • Command
  • State

The content of these messages varies by message type. The required components of each message type are detailed in the section 16 of the specification.

Below is a screen shot taken from the specification for a NDATA message.

sparkplug-ndata

How Sparkplug Components Communicate

As shown in the diagram above we have several components in a Sparkplug system. There are:

  • Primary application
  • EON (Edge of Network) nodes
  • Device Nodes

In this section we look at the messages and message payloads that are exchanged by these nodes.

Primary Application Session Establishment and Messages

When the control application comes online it publishes:

  1. Last Will message
  2. Birth Message

The topic used is STATE/scada_host_id and the payload format is a simple UTF-8 string and does not use the standard Google protocol buffers format used by other messages.

The last will message is sent as part of the MQTT connection and uses the topic STATE/scada_host_id and plain text payload of OFFLINE and the retain flag is set.

The birth message is sent to the  topic STATE/scada_host_id and payload of ONLINE and the retain flag is set.

You can see this in the screen shot below captured using the mosquitto_sub tool:

state-sparkplug

Notice that the retained flag is set.

So the process for the primary application is

  1. Connect
  2. Publish State
  3. Subscribe to spBv1.0/#

It is now ready to receive messages and publish commands.

EON Node Session Establishment and Messages

When the EON (Edge of Network) node  goes on line it does the following

  1. Connects to the MQTT broker and sets the Will and Testament message (NDEATH)
  2. Subscribes to the STATE topic, NCMD and DCMD topics on spBv1.0/group/NCMD/myNodeName/# and spBv1.0/group/DCMD/myNodeName/#
  3. Publishes a birth message NBIRTH on the topic spBv1.0/group/NBIRTH/myNodeName

Note: the message payload for NDEATH and NBIRTH uses Google protocol buffers format.

Below is a screen shot showing the will message being sent and the Birth message from the EON node.

sparkplug-birth-death-messages

For the Will message (NDEATH) the only metric published is a sequence number(bdSeq).

This sequence number starts at 0 and is incremented on each connect.

The NBIRTH message also includes this same sequence number as shown in the screen shot above.

The NBIRTH message also includes all EON metrics that will be published by this Node and can be very large.

Also the NBIRTH message contains metrics that make public the commands that the EON node will accept as shown in the screen shot below:

 

sparkplug-metrics

If the control application publishes a message with the metric name Node Control/Next Server then the EON node will try to move to the next MQTT broker in its list.

MQTT Device Session Establishment and Messages

An MQTT sensor will function as an EON (Edge of Network) node.

It behaves as an EON + device Node.When it goes online it does the following

  1. Connects to the MQTT broker and sets the Will and Testament message (NDEATH)
  2. Subscribes to the STATE topic, NCMD and DCMD topics on spBv1.0/group/NCMD/myNodeName/# and spBv1.0/group/DCMD/myNodeName/#
  3. Publishes a birth message DBIRTH on the topic spBv1.0/group/DBIRTH/myNodeName

An example DBIRTH Message is shown below.

Dbirth-message

None MQTT Devices I.E Legacy Scada Devices

Legacy Scada devices don’t support MQTT directly but instead will connect ot a EON node probably using polling and report data to the EON device.

The EON node will publish data for the device using DDATA topic and messages and receive commands for the device on the DCMD topic.

The EON node will publish DBIRTH and DDEATH messages for the connected devices.

Using The MQTT tools mosqutto_pub and mosqutto_sub with Sparkplug

Unfortunately these tools cannot be used with Sparkplug as they don’t understand the message payload as shown in the screen shot below:

sparkplug-messages-tools

Python Sparkplug Message Monitor

This is an extension of the MQTT monitor I created a few years ago. It allows you to subscribe the a Sparkplug topic and displays data in a readable format.

There  switch -v will display topic and message and the default is to display topic only.

python-sparkplug monitor

Used in verbose mode e.g.

sparkplug-monitor -h test.mosquitto.org -t spBv1.0/# -v

we get.

python-sparkplug monitor-verbose

To work the monitor needs to decode the Google protocol buffers and this uses two files available on github but also included with the download. They are

  • sparkplug_b.py
  • sparkplug_b_pb2.py

I placed them in the same folder as the Sparkplug monitor file but they can go anywhere provided they are locatable by the module.

download

Summary

Sparkplug messages payloads use Google protocol buffers for encoding the message data.

The contents of messages depends on the message type and the each message type has mandatory fields that are detailed in the specification.

Resources:

Sparkplug specification

Related Tutorials

Please rate? And use Comments to let me know more

4 comments

  1. Hi Steve, I’ve just finished reading the sparkplub b specification document and I have not implemented it yet, but I’m confused a little, do we have manually to set the NBREATH and DDEATH Messages??

    1. Yes the script you used needs to send them. I have added the example.py script to the download> take alook as it shows you how to do it.
      Rgds
      Steve

  2. Hi Steve, would it be a bad idea or overkill to use Sparkplug B specification for IoT systems whose architecture is only Client + Broker + Server and doesn’t include any EoNs?

    1. I think Sparkplug is probably overkill and complicated for most small to medium projects> in a large industrial setting it makes sense but for a few dozen nodes then no.
      So in your case I would say forget it.

Leave a Reply

Your email address will not be published. Required fields are marked *