Sparkplug Specification

MQTT Topic Namespace and Payload Definition

Version 1.0

Sparkplug Specification Version 1.0 Page 1

Revision Number Date Author Description
1.0 5/26/16 Arlen Nipper Initial Release

Sparkplug Specification Version 1.0 Page 2

 Table of Contents
Table of Contents ......................................................................................................................................... 3
Table of Figures ............................................................................................................................................ 6
1. Introduction ......................................................................................................................................... 7
2. Background .......................................................................................................................................... 8
3. Infrastructure Components .................................................................................................................. 9
3.1. MQTT Server(s) ........................................................................................................................... 9
3.2. MQTT Edge of Network (EoN) Node ........................................................................................... 9
3.3. Device ......................................................................................................................................... 9
3.4. MQTT Enabled Device(Sparkplug) .............................................................................................. 9
3.5. MQTT Host Node ...................................................................................................................... 10
3.6. MQTT Application Node............................................................................................................ 10
3.7. Security ..................................................................................................................................... 10
4. Leveraging Standards and Open Source ............................................................................................. 11
4.1. OASIS MQTT V3.1.1 Specification ............................................................................................. 11
4.2. Eclipse Foundation IoT Resources ............................................................................................. 11
4.2.1. Paho ...................................................................................................................................... 11
4.2.2. Kura ...................................................................................................................................... 11
4.3. Raspberry Pi Hardware ............................................................................................................. 11
5. General Message Flow ....................................................................................................................... 12
5.1. State .......................................................................................................................................... 12
6. Sparkplug MQTT Topic Namespace .................................................................................................... 13
6.1. Sparkplug Topic Namespace Elements ..................................................................................... 13
6.1.1. namespace Element ............................................................................................................. 13
6.1.2. group_id Element ................................................................................................................. 13
6.1.3. message_type Element......................................................................................................... 13
6.1.4. edge_node_id Element ......................................................................................................... 14
6.1.5. device_id Element ................................................................................................................ 14
6.2. Example Ignition Folder Structure ............................................................................................ 14
7. Sparkplug MQTT Payloads .................................................................................................................. 16
7.1. Sparkplug MQTT Payload Encoding .......................................................................................... 16
7.1.1. Google Protocol Buffers........................................................................................................ 16

Sparkplug Specification Version 1.0 Page 3

 7.1.2. Leveraging Existing Kura Protocol Buffer Support ................................................................ 17
7.2. MQTT EoN Birth and Death Certificate ..................................................................................... 18
7.2.1. EoN Death Certificate (NDEATH) .......................................................................................... 18
7.2.1.1. Birth/Death Sequence Number - bdseq ....................................................................... 19
7.2.2. EoN Birth Certificate (NBIRTH) ............................................................................................. 19
7.2.2.1. Birth/Death Sequence Number - bdseq ....................................................................... 19
7.2.2.2. Message Sequence Number - seq ................................................................................ 19
7.2.2.3. UTC Milliseconds Timestamp - timestamp .................................................................. 20
7.2.2.4. Optional EoN Configuration and Control Parameters .................................................. 20
7.2.2.5. Ignition Folder Structure after an EoN Node Birth Certificate ..................................... 21
7.3. MQTT EoN Node Data Payload (NDATA) .................................................................................. 22
7.3.1. Message Sequence Number - seq ........................................................................................ 23
7.3.2. UTC Milliseconds Timestamp - timestamp ........................................................................... 23
7.3.3. Dynamic parameter values that have changed .................................................................... 23
7.4. MQTT Device Birth and Death Certificate ................................................................................. 23
7.4.1. MQTT Device Birth Certificate (DBIRTH)............................................................................... 24
7.4.1.1. Message Sequence Number - seq ................................................................................ 24
7.4.1.2. UTC Milliseconds Timestamp - timestamp .................................................................. 24
7.4.1.3. Required Device Process Variable Map ....................................................................... 24
7.4.1.1. Ignition Tag Structure after Device BIRTH Message .................................................... 25
7.4.2. MQTT Device Death Certificate (DDEATH) ........................................................................... 27
7.4.2.1. Message Sequence Number - seq ................................................................................ 27
7.4.2.2. UTC Milliseconds Timestamp - timestamp .................................................................. 27
7.4.2.3. Optional Death Certificate Parameters ........................................................................ 27
7.5. MQTT Device Data Messages (DDATA) ..................................................................................... 28
7.5.1. Message Sequence Number - seq ........................................................................................ 28
7.5.2. UTC Milliseconds Timestamp - timestamp ........................................................................... 28
7.5.3. Any Tag/PV value that has changed ..................................................................................... 28
7.6. Ignition Gateway Birth and Death Certificates ......................................................................... 29
7.6.1. Ignition Death Certificate Payload (STATE) ........................................................................... 29
7.6.1. Ignition Birth Certificate Payload .......................................................................................... 29
7.7. Ignition to EoN Node Data Command (NCMD) ......................................................................... 30
7.8. Ignition to Device Data Command (DCMD) .............................................................................. 30

Sparkplug Specification Version 1.0 Page 4

8. Sparkplug MQTT Session Management and Message Flow ............................................................... 32
8.1. Primary Ignition Session Establishment .................................................................................... 33
8.2. EoN Node Session Establishment ............................................................................................. 35
8.3. MQTT Device Session Establishment ........................................................................................ 37
8.4. General MQTT applications and non-primary Ignition Gateway. ............................................. 39
9. Sparkplug MQTT Data and Command Messages ............................................................................... 40
9.1. EoN NDATA and NCMD Messages ............................................................................................ 40
9.2. Device DDATA and DCMD Messages ........................................................................................ 42
10. Sparkplug Management of Multiple MQTT Servers ....................................................................... 45
10.1. Multiple MQTT Server Topology ............................................................................................... 45
10.2. Primary Ignition Gateway STATE in Multiple MQTT Server Topologies .................................... 48
11. Sparkplug Persistent versus Non-Persistent Connections .............................................................. 51
12. Glossary of Terms ........................................................................................................................... 52
13. Contact Information ....................................................................................................................... 53

Sparkplug Specification Version 1.0 Page 5

Table of Figures
Figure 1 - Ignition MQTT Infrastructure Overview ....................................................................................... 7

Figure 2 - MQTT SCADA Infrastructure ......................................................................................................... 9

Figure 3 - Simple MQTT Infrastructure ....................................................................................................... 12

Figure 4 – Initial MQTT Engine Tag Provider Folder Structure ................................................................... 15

Figure 5 – Ignition MQTT Engine Folder Structure using the Sparkplug Topic Namespace ....................... 15

Figure 6 - Kura Protocol Buffer Definition .................................................................................................. 18

Figure 7 - Ignition Tag Structure after EoN Node BIRTH ............................................................................ 22

Figure 8 - Ignition Tag Structure after Device BIRTH message ................................................................... 26

Figure 9 - Host Session Establishment ........................................................................................................ 33

Figure 10 - EoN Node MQTT Session Establishment .................................................................................. 35

Figure 11 - MQTT Device Session Establishment ....................................................................................... 37

Figure 12 - EoN Node NDATA and NCMD Message Flow ........................................................................... 42

Figure 13 - Device DDATA and DCMD Message Flow ................................................................................. 44

Figure 14 - Single MQTT Server Topology .................................................................................................. 45

Figure 15 - Multiple MQTT Server Topology .............................................................................................. 46

Figure 16 - MQTT Client tags in Ignition ..................................................................................................... 47

Figure 17 - EoN MQTT metric tags in Ignition ............................................................................................ 48

Figure 18 - Ignition STATE flow diagram .................................................................................................... 49

Sparkplug Specification Version 1.0 Page 6

1. Introduction
This document provides the open and freely available specification for how Edge of Network or MQTT
enabled end devices communicate in MQTT Infrastructure in the Inductive Automation Ignition
Application Platform. The document details the structure and implementation requirements for
compliant MQTT client devices to utilize Cirrus Link suite of MQTT Modules. The components of the
baseline MQTT infrastructure include Ignition, one or more MQTT Servers and at the Cirrus Link MQTT
Engine Module. A description of the Cirrus Link MQTT modules are as follows:

The MQTT Engine Module: Adds the functionality to the Ignition platform to
bidirectional communicate with MQTT enabled edge-of-the-network devices securely
via an MQTT Server.

The MQTT Distributor Module: Adds an MQTT server to the Ignition platform that
enables MQTT clients to securely connect, publish, and subscribe to data.

The MQTT Transmission Module: Enables the TAGs within Ignition to be published as
MQTT client data within the MQTT Infrastructure. It is a bridge from Ignition TAGs to
MQTT.

Below is a sample solution diagram.

Figure 1 - Ignition MQTT Infrastructure Overview

Sparkplug Specification Version 1.0 Page 7

2. Background
MQTT was originally designed as a message transport for Real Time SCADA systems. Within the context
of the MQTT specification, there are mechanisms defined to provide the state of an MQTT session to
provide SCADA Host applications the current state of any MQTT device node in the infrastructure. The
MQTT specification does not specify the Topic Namespace or Payload representation of the data being
published and/or subscribed. This was intended to provide flexibility in future system implementations.

The purpose of this document is to remain true to the original notion of keeping the Topic Namespace
and message sizes to a minimum while still making the overall message transactions between MQTT
Device Nodes and MQTT Engine installed on the Ignition Gateway simple, efficient and easy to
understand and implement.

Sparkplug Specification Version 1.0 Page 8

3. Infrastructure Components
This section details the infrastructure components implemented with use of Inductive Automation
Ignition Platform and Cirrus Link MQTT Modules.

Figure 2 - MQTT SCADA Infrastructure

3.1. MQTT Server(s)

MQTT enabled infrastructure requires one or more MQTT Servers are present in the infrastructure. The
MQTT Server component in the architecture is required to be compliant with the latest MQTT V3.1.1
specification and is sized to properly manage all MQTT message traffic.

One can implement the use (if required) of multiple MQTT servers for the purpose of redundancy, high
availability, and scalability within any given infrastructure.

3.2. MQTT Edge of Network (EoN) Node

In the context of this document, an MQTT Edge of Network (EoN) Node is any V3.1.1 compliant MQTT
Client application that manages an MQTT Session and provides the physical and/or logical gateway
functions required to participate in the Topic Namespace and Payload definitions described in this
document. The EoN Node is responsible for any local protocol interface to existing legacy devices (PLCs,
RTUs, Flow Computers, Sensors, etc.) and/or any local discrete I/O, and/or any logical internal process
variables(PVs).

3.3. Device
The Device represents any physical or logical device connected to the MQTT EoN Node providing any
data, process variables or metrics.

3.4. MQTT Enabled Device(Sparkplug)

This represents any device, sensor, or hardware that directly connects to MQTT infrastructure using a
compliant MQTT 3.1.1 connection with the payload and topic notation as outlined in this Sparkplug
specification.

Sparkplug Specification Version 1.0 Page 9

 3.5. MQTT Host Node
The MQTT Host Node is any MQTT Client application that subscribes to PV messages and publishes PV
Command messages defined in this document. In most SCADA infrastructure implementations, there
will be only one Primary MQTT Host Node responsible for the monitoring and control of a given group of
MQTT Device Nodes. This does not preclude any number of additional MQTT Host Nodes participating in
the infrastructure that are in either a pure monitoring mode, or in the role of a hot standby should the
Primary MQTT Host Node go offline.

Within the Inductive Automation Ignition platform, it becomes the Host Node where the MQTT Engine
module enables its MQTT sessions for subscribing and publishing data. MQTT EoN Nodes and associated
Devices that follow this specification are automatically recognized by MQTT Engine and become a part
of the Ignition tag structure dynamically. This specification details the folder and tag structure created
for each level of the Topic Namespace.

3.6. MQTT Application Node

A MQTT Application Node is any non-primary MQTT Client application that consumes the real time PV
messages or any other data being published with proper permission and security.

3.7. Security
There are several levels of security and access control configured within an MQTT infrastructure. From a
pure MQTT client perspective, the client does need to provide a unique Client ID, and an optional
Username and Password. Although access control is not mandated in the MQTT specification for use in
MQTT Server implementations, Access Control List (ACL) functionality is available for most MQTT Server
implementations. The ACL of an MQTT Server implementation is used to specify which Topic Namespace
any particular MQTT Client can subscribe to and publish on. Examples are provided on how to setup and
manage MQTT Client credentials and some considerations on setting up proper ACL’s on the MQTT
Servers.

The MQTT specification does not specify any particular TCP/IP security scheme as it was envisaged that
TCP/IP security would (and did) change over time. Although this document will not specify any TCP/IP
security schema it will provide examples on how to secure an MQTT infrastructure using TLS security.

Sparkplug Specification Version 1.0 Page 10

4. Leveraging Standards and Open Source
The Sparkplug specification leverages as much open source development and data encoding as possible
as this is a core belief within Cirrus Link Solutions.

4.1. OASIS MQTT V3.1.1 Specification

The Sparkplug specification specifies that MQTT Clients in the infrastructure adhere to the MQTT V3.1.1
specification. The specification documentation refers to “mqtt-v3.1.1-os.doc”:

http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html

Also referred is an addendum document to the MQTT V3.1.1 specification document that discusses best
practices for implementing security on MQTT TCP/IP networks:

http://docs.oasis-open.org/mqtt/mqtt-nist-cybersecurity/v1.0/mqtt-nist-cybersecurity-v1.0.doc

4.2. Eclipse Foundation IoT Resources

The Eclipse Foundation is an excellent resource for open source software support industry standards.
Within the Eclipse Foundation is an Internet of Things (IoT) working group providing a wealth of
information.

http://iot.eclipse.org/

4.2.1. Paho
Paho is an Eclipse Foundation project that offers excellent resources for mature, compliant MQTT Client
and MQTT Server implementations and well as additional resources for all things MQTT.

http://www.eclipse.org/paho/

4.2.2. Kura
Kura is another Eclipse Foundation project under IoT resources. Kura is a Java/OSGi-based framework
for IoT gateways, or EoN Nodes as defined in this specification. Kura also provides open source
resources for the Google Protocol Buffer representation of MQTT payloads as defined in this
specification:

https://www.eclipse.org/kura/

4.3. Raspberry Pi Hardware

For the sake of keeping the Sparkplug specification as real world as possible, a reference
implementation of an EoN Node and associated Device is provided for the examples and screen shots in
this document. All of this was implemented on Raspberry Pi hardware representing the EoN Node with a
Pibrella I/O board representing the Device.

Sparkplug Specification Version 1.0 Page 11

5. General Message Flow
This section discusses the generic topology shown in Figure 2 - MQTT SCADA Infrastructure identifying
how each of the component of the infrastructure interacts.

At the simplest level there are only two components required as shown below. An MQTT Client and an
MQTT Server. With proper credentials, any MQTT Client can connect to the MQTT Server without any
notion of other MQTT Client applications that are connected, and can issue subscriptions to any
particular MQTT message(data) that it might be interested in as well as start publishing any data that it
has. This is one of the principal notions of IIoT, that is the decoupling intelligent devices from any direct
connection to any one consumer application.

Figure 3 - Simple MQTT Infrastructure

5.1. State
In any network architecture, network connection State is important. In SCADA, connection State is
extremely important. State is the session awareness of the MQTT EoN and the MQTT Server. The very
reason that the majority of this market sector are still using legacy poll/response protocols to maintain a
notion of the State of the connection between the SCADA application and the connected devices. I poll, I
get a response, I know the State of all of the I/O points, but now I must poll again because that State
may have changed.

Many implementations of solutions using MQTT treat it as a simple, stateless, pub/sub state machine.
The is quite viable for IoT and some IIoT applications, however it is not taking advantage of the
capability of MQTT based infrastructures.

For the proper implementation of any MQTT based within a SCADA system, the built in session state
mechanism of MQTT must be understood and properly implemented. If real-time control or state is not
used for the data and application, state is not required and the system will operate based on using time-
stamped data as LKG (last-known-good) values. (CHECK)

One of the primary applications for MQTT as it was originally designed was to provide reliable SCADA
communications over VSAT topologies. Due to propagation delay and cost, it was not feasible to use a
poll/response protocol. Instead of a poll/response protocol where all of the data was sent in response to
every poll, MQTT was used to “publish” information from remote sites only when the data changed. This
technique is sometimes called Report by Exception or RBE. But in order for RBE to work properly in real
time SCADA, the “state” of the end device needs to be known at all times. In other words, the SCADA
host applications like Ignition could only rely on RBE data arriving reliably if it could be assured of the
state of the MQTT session.

Sparkplug Specification Version 1.0 Page 12

6. Sparkplug MQTT Topic Namespace
In order to get a working Message Oriented Middleware (MOM) based SCADA system working using
MQTT, the first thing that must be defined is a Topic Namespace to work within. The beauty of MQTT is
the fact that you can just come up with an arbitrary topic like “Portland/Temperature”, connect to an
MQTT Server, and start publishing the temperature value. In order for this data to be useful to other
MQTT Client applications that want to consume the temperature values, the Topic Namespace needs to
be understood by everyone participating in the data exchange.

Every MQTT message published consist of a topic and a payload component. These components are the
“overhead” of an MQTT message as measured in bytes on the wire. The Sparkplug specification is
designed to keep these components meaningful and easy to understand, but not to get so verbose as to
negatively impact bandwidth/time sensitive data exchange.

6.1. Sparkplug Topic Namespace Elements

All MQTT clients using the Sparkplug specification will use the following general topic structure:

namespace/group_id/message_type/edge_node_id/[device_id]
6.1.1. namespace Element
The namespace element of the Topic Namespace is the root element that will define both the structure
of the remaining namespace elements as well as the encoding used for the associated payload data. For
this initial version of the Sparkplug specification, the UTF-8 string constant for the namespace element
will be:

“spAv1.0”
This element identifies the message as being a Sparkplug “sp” defined message using version “A” of the
Sparkplug specification encoding scheme version “1.0”.

6.1.2. group_id Element

The group_id element of the Topic Namespace provides for a logical grouping of MQTT EoN and Devices
into the MQTT Server and back out to the consuming MQTT Clients. The format of the group_id element
is not dictated in that it can be any valid UTF-8 alphanumeric String with the exception of the reserved
characters of ‘+’ (plus), ‘/’ (forward slash), and ‘#’ (number sign). To minimize overhead if that is a goal
of your application, it should be as small as possible. Examples of where the [group_id] might be used
include Oil/Gas applications where MQTT Devices on a physical pipeline segment all have the same
[group_id]. Plant floor applications may group MQTT Devices based on logical cell or manufacturing line
requirements.

6.1.3. message_type Element

The message_type element of the Topic Namespace provides an indication as to what the MQTT
Payload of message will contain (Note: The Sparkplug MQTT Payload definitions are defined in detail
later is this document). The following message_type elements are defined for the Sparkplug Topic
Namespace:

• NBIRTH – Birth certificate for MQTT EoN Nodes.

Sparkplug Specification Version 1.0 Page 13

 • NDEATH – Death certificate for MQTT EoN Nodes.
• DBIRTH – Birth certificate for MQTT Devices.
• DDEATH – Death certificate for MQTT Devices.
• NDATA – Node data message.
• DDATA – Device data message.
• NCMD – Node command message.
• DCMD – Device command message.
• STATE – Critical application state message.

The specification for each of these message_type elements are detailed later in this document.

6.1.4. edge_node_id Element

The edge_node_id element of the Sparkplug Topic Namespace uniquely identifies the MQTT EoN Node
within the infrastructure. The format of the edge_node_id can be valid UTF-8 alphanumeric String with
the exception of the reserved characters of ‘+’ (plus), ‘/’(forward slash), and ‘#’(number sign). The topic
element edge_node_id travels with every message published and should be as short as possible.

6.1.5. device_id Element

The device_id element of the Sparkplug Topic Namespace identifies an MQTT Device attached to the
MQTT EoN Node. Note that the device_id is an optional element within the Topic Namespace as some
messages will be either originating or destined to the edge_node_id and the device_id would not be
required. The format of the device_id is a valid UTF-8 alphanumeric String with the exception of the
reserved characters of ‘+’ (plus), ‘/’ (forward slash), and ‘#’ (number sign). The device_id must be unique
from other devices connected to the same EoN Node, but can be duplicated from EoN Node to other
EoN Nodes.

6.2. Example Ignition Folder Structure

Upon installing the MQTT Engine module in Ignition and configuring one or more available MQTT
Servers, a new “Tag Provider” is added to the Ignition Tag structure named “MQTT Engine”. Until Edge
of Network devices join the MQTT infrastructure, the MQTT Engine structure primarily provides metrics
on the MQTT Engine internal MQTT Clients connected to the defined MQTT Servers.

Sparkplug Specification Version 1.0 Page 14

 Figure 4 – Initial MQTT Engine Tag Provider Folder Structure

But once an EoN Node connects to the MQTT infrastructure, MQTT Engine starts using the Topic
Namespace defined to build out the Ignition folder structure representing EoN Nodes, Devices, and the
various metric, parameter, and process variable folders.

Figure 5 – Ignition MQTT Engine Folder Structure using the Sparkplug Topic Namespace

Sparkplug Specification Version 1.0 Page 15

7. Sparkplug MQTT Payloads
The MQTT message transport specification does NOT define any data payload format, but just like in the
Topic Namespace section namespace design does have to take place. The same is true for the data
payloads being published and subscribed to by the participating MQTT clients in the infrastructure. This
section of the Sparkplug specification defines how an MQTT payload is encoded and the data that is
required. Note that Sparkplug can support multiple payloads definitions. The initial release is based on
the open source Eclipse Kura/Google Protobuf implementation.

Sparkplug is addressing the absolute fact that the majority of devices connecting into next generation
IIoT infrastructure is legacy equipment using poll/response protocols. This means we must take in
account register based data from devices that talk protocols like Modbus. The existing legacy equipment
needs to work in concert with emerging IIoT equipment that are able to leverage message transports
like MQTT natively.

7.1. Sparkplug MQTT Payload Encoding

The Sparkplug specification creates a bandwidth efficient data transport for real time device data. For
WAN based SCADA/IIoT infrastructures this equates to lower latency data updates while minimizing the
amount of traffic and therefore cellular and/or VSAT bandwidth required. For LAN based SCADA
infrastructures, this equates to enabling higher throughput of real time data to consumer applications
without requiring extreme networking topologies and/or equipment.

There is a plethora of data encoding technologies available that can ALL be used in conjunction with
MQTT. Conventional IT tooling provides XML and JSON as the most popular encoding technologies. But
neither of these encoding technologies are efficient in representing large quantities of register based,
real time process variables. These technologies all have their place in IT design strategies. Sparkplug
selected an existing, open, and highly available encoding scheme that efficiently encodes register based
process variables. The encoding technology selected for Sparkplug is Google Protocol Buffers also
referred to as Google protobufs.

7.1.1. Google Protocol Buffers

“Protocol Buffers are a way of encoding structured data in an efficient yet extensible format.”

Google Protocol Buffers, sometimes referred to as “Google protobufs”, provide the efficiency of packed
binary data encoding while providing the structure required to make it easy to create, transmit, and
parse register based process variables using a standard set of tools. Google Protocol Buffers
development tools are available for:

• C
• C++
• C#
• Java
• Python
• GO
• JavaScript

Additional information on Google Protocol Buffers can be found at:

Sparkplug Specification Version 1.0 Page 16

https://developers.google.com/protocol-buffers/

7.1.2. Leveraging Existing Kura Protocol Buffer Support

Although the Sparkplug specification could arbitrarily define a Google Protocol Buffer definition to
define MQTT payloads, it is the goal of this version “A” of the specification is to follow open source and
existing standards wherever possible. The Eclipse Software Foundation sponsors a mature Internet of
Things Gateway project called Kura (see the technical reference section at the end of this document for
more information). The Kura project has already defined a Google Protocol Buffers schema that targets
the type of machine Process Variable information that we want to have in the Sparkplug MQTT message
payloads. The Protocol Buffer schema can be found at the following URL:

https://github.com/eclipse/kura/blob/KURA_1.4.0_RELEASE/kura/org.eclipse.kura.core.cloud/src/main/
protobuf/kurapayload.proto

Sparkplug Specification Version 1.0 Page 17

 Figure 6 - Kura Protocol Buffer Definition

The important thing to note in this Protocol Buffer schema is that the required parameters are the name
and type parameters. For most use case applications in SCADA, think of this schema providing an
efficient way to encode key:value pairs of a tag (or PLC register number) and an associated value. The
value enumerations here cover all of the required data types that Process Variables require include:

• DOUBLE
• FLOAT
• INT64
• INT32
• BOOL
• STRING
• BYTES

There are some metadata structures defined within the current Kura Protocol Buffers schema that can
be utilized (optionally) as well. This includes the INT64 timestamp that used to time stamp UTC
millisecond values as well as the KuraPosition structure for any Location Based services that might be
provided by some MQTT EoN Nodes or Devices.

7.2. MQTT EoN Birth and Death Certificate

A critical aspect for MQTT in a real time SCADA application is making sure that the primary MQTT Host
Node is able to know the “STATE” of any EoN and/or Device in the infrastructure within the MQTT Keep
Alive period (refer to section 3.1.2.10 in the MQTT Specification). To implement the state a known Will
Topic and Will Message is defined and specified. The Will Topic and Will Message registered in the
MQTT CONNECT session establishment, collectively make up what we are calling the Death Certificate.
Note that the delivery of the Death Certificate upon any MQTT client going offline unexpectedly is part
of the MQTT protocol specification, not part of this Sparkplug specification (refer to section 3.1
CONNECT in the MQTT Specification for further details on how an MQTT Session is established and
maintained).

Unlike the Death Certificate mechanism which is part of the MQTT transport, the Birth Certificate is a
Sparkplug definition. The Birth Certificate is a logical reciprocal of the Death Certificate that is used to
convey the fact that the associate MQTT EoN Node and/or MQTT Device now has an MQTT session
established and can now start providing real time Process Variable information.

The first MQTT message that an EoN Node MUST publish upon the successful establishment of an
MQTT Session is an EoN BIRTH Certificate.

7.2.1. EoN Death Certificate (NDEATH)

The Death Certificate topic for an MQTT EoN Node is:

namespace/group_id/NDEATH/edge_node_id
The Death Certificate topic and payload described here are not “published” as an MQTT message, but
used as provided parameters within the MQTT CONNECT control packet when this MQTT EoN Node first
establishes the MQTT Client session.

Sparkplug Specification Version 1.0 Page 18

Immediately upon reception of an EoN Death Certification, MQTT Engine will set the associated Ignition
tag data quality to “STALE” for ALL tags and parameters assigned to any MQTT Device connected to this
EoN Node.

The MQTT payload associated with this topic will be a Google Protocol Buffer using the Kura schema
containing the following optional parameters:

7.2.1.1. Birth/Death Sequence Number - bdseq

‘bdseq’:INT32:[sequence_number] // Birth/Death Sequence Number

The Birth/Death sequence number is a required Sparkplug specification feature that is utilized when the
infrastructure contains multiple MQTT Servers. The bdseq metric value MUST be the same value used in
the associated Birth Certificate payload defined below, and MUST be an incrementing value on all
subsequent MQTT session establishments.

7.2.2. EoN Birth Certificate (NBIRTH)

The Birth Certificate topic for an MQTT EoN Node is:

namespace/group_id/NBIRTH/edge_node_id
The EoN Birth Certificate contains everything required to build out an Ignition tag tree structure for all
metrics and parameters for this EoN Node. Upon the reception of a valid EoN Birth Certificate, MQTT
Engine creates the tag folder information required to represent the EoN Node if it does not already
exist, and populate the provided metric information into the appropriate folders. The ONLINE state of
this EoN Node will be set to TRUE along with the associated ONLINE Date Time parameter. Note that the
EoN Birth Certificate ONLY indicates the node itself is online and in an MQTT Session, but any attached
MQTT Devices will still have “STALE” data quality until those devices come online with their associated
Birth Certificates.

The MQTT payload associated with this topic will be a Google Protocol Buffer using the Kura schema
containing the following optional parameters:

7.2.2.1. Birth/Death Sequence Number - bdseq

‘bdseq’:INT32:[session_number] // Birth/Death Sequence Number

The Birth/Death sequence number is a required Sparkplug specification feature utilized when the
infrastructure contains multiple MQTT Servers. The bdseq metric value MUST be the same value used in
the associated Death Certificate payload defined above, and MUST be an incrementing value on all
subsequent MQTT session establishments.

7.2.2.2. Message Sequence Number - seq

‘seq’:INT32:[message_sequence_number] // Message Sequence Number

The Message Sequence Number is a required parameter that guarantees proper message ordering
between an MQTT EoN Node and the SCADA /Host application. For real time solutions where Process
Variables are being published using Report by Exception (RBE), it is critical that all analog and state
Process Variables arrive in order. The MQTT specification state that all messages be delivered in the

Sparkplug Specification Version 1.0 Page 19

order they are published. But the Message Sequence Number provides an addition level of monitoring
and safety in instances where this might not be the case. The value of the Message Sequence Number
starts at a value of zero (0) with this NBIRTH Certificate message and increment on every subsequent
MQTT messages from this EoN Node and each subsequent message increments the Message Sequence
Number by a value of exactly one (1) and increment to a value of 255, and then roll over to 0 again. Any
primary MQTT SCADA Host node monitors the received Message Sequence Number, and if an out of
order message is detected, then ALL Process Variable data should be set to “STALE” quality and the
SCADA Host node will request a new MQTT Session from this EoN Node.

7.2.2.3. UTC Milliseconds Timestamp - timestamp

‘timestamp’:INT64:[current_utc_timestamp] // UTC Milliseconds Timestamp

UTC Milliseconds Timestamp is an optional parameter that can be provided in the EoN Birth Certificate.
Although any MQTT Host node can (and should) timestamp data on arrival, UTC timestamps in the
MQTT messages can provide important latency metrics to monitor the overall health of the MQTT
infrastructure. In many SCADA system implementations, all infrastructure components have access to
the same master time server (for example using a master NTP server). Including the UTC Millisecond
Timestamp with every MQTT message published allows the MQTT Host node the ability to provide real
time latency metrics from every MQTT EoN node in the system. This latency metric measures the time
for the message published from the EoN node traversing the infrastructure and arrive at the SCADA
host. For cellular and VSAT based systems, this is an important metric to keep track of. It can also be
used to ensure that there are no issues with the messages getting thru the MQTT Server infrastructure.

7.2.2.4. Optional EoN Configuration and Control Parameters

Each MQTT EoN Node can provide an optional number of metrics and parameters for additional
information about the node. MQTT Engine places these parameters into the EoN Node tag folder
structure with each parameter exposed as an Ignition tag. The difference between the EoN Node
configuration and control tags in this section versus the process variable tags detailed later in this
section is that these tags use the NDATA and NCMD message types and can be segregated from physical
device command/control access. This is an important aspect of the Sparkplug specification to
understand. Using proper credential and access management, users gain access to the configuration
parameters of an EoN Node without having access to the physical device command/control DCMD
messages.

Informational parameters like the Hardware Manufacture ID, Model Number, Software Revision
Number, Configuration Revision Number, etc. can be provided here along with any EoN Node control or
configuration parameter. By using an appropriate parameter structure here, complete configuration
dashboards can be built with the Ignition tooling. Using the Raspberry Pi example code
(https://github.com/Cirrus-Link/Sparkplug), the following EoN Node folder structure and tags are
exposed:

//Root level tag

‘Up Time ms’:INT64:[upTimeStart] //Up Time in ms

//Node Control folder tags

‘Node Control/Rebirth’:BOOL:false //Rebirth command coil
‘Node Control/Reboot’:BOOL:false //Reboot command coil into the

Sparkplug Specification Version 1.0 Page 20

‘Node Control/Next server’:BOOL:false //Move to next MQTT Server command coil
‘Node Control/scan_rate_ms’:INT32:250 //I/O scan rate in milliseconds

//Properties folder tags

‘Properties/Node Manf’:STRING:’Raspberry’ //Manufacture
‘Properties/Hardware Version’:STRING:’Pi 2 Model B’ //HW Version
‘Properties/Software Version’:STRING:’v1.0.0’ //SW Version
‘Properties/Config Change Count’:INT32:1 //Persistent configuration change counter

Note that the tag folder hierarchy as it appears in Ignition can be controlled by the structure of the Birth
Certificate tag names. In the example given above, the “Up Time ms” tag will appear at the root level of
the Node. Tags that control aspects of the EoN Node are placed into a folder called “Node Control”.
Other, information only tags are shown above being placed into the “Properties” folder.

The only EoN Node tag structure that is mandatory in the Sparkplug specification is the “Node
Control/Rebirth” node control Boolean. Any MQTT Client that connects to the MQTT Server
infrastructure will want to request that a new Birth Certificate needs to be published in order to learn
about the node and associated Devices. MQTT Engine will assume this control tag exists for any EoN
Node connecting into the infrastructure.

7.2.2.5. Ignition Folder Structure after an EoN Node Birth Certificate

Using the actual parameters given in the examples above, the reference Raspberry Pi code can publish
an EoN Node Birth Certificate on the following MQTT topic:

spA1.0/Sparkplug Devices/NBIRTH/Java Raspberry Pi

Upon receipt of this message, MQTT Engine builds out the following folder/tag structure within Ignition:

Sparkplug Specification Version 1.0 Page 21

 Figure 7 - Ignition Tag Structure after EoN Node BIRTH

After the EoN Node Birth Certificate has been published, all of the parameters defined in the BIRTH
message payload are now available as Ignition tags. These parameter tags have the same properties as
any other Ignition tag value. As shown in the tag browser view above, the EoN Node is online and
provides specific information about the node that can be displayed in dashboard views for the end user.
Various node commands are now available like sending a new scan_rate_ms parameter to read the
associated I/O t a new millisecond period. Commands like the Reboot node shown above can be
dynamically built into this structure very quickly. Metrics like the current node TCP/IP address and the
Configuration Change Counter can be used for alarming and diagnostics within Ignition.

7.3. MQTT EoN Node Data Payload (NDATA)

Once an MQTT EoN Node is online with proper Birth Certificates we’re in a mode of quiescent Report by
Exception (RBE) or time based reporting of any parameter information that changes. This enables the
advantage of the native Continuous Session Awareness of MQTT to monitor the STATE of all connected
MQTT EoN Node devices and to rely on Report by Exception (RBE) messages for any parameter or metric
state change over the MQTT session connection.

As defined above, the Data Topic for an MQTT EoN Node is:

Sparkplug Specification Version 1.0 Page 22

namespace/group_id/NDATA/edge_node_id
The payload for the Data message is a Google Protocol Buffer structure using the Kura schema.

7.3.1. Message Sequence Number - seq

‘seq’:INT32:[message_sequence_number] // Message Sequence Number

The Message Sequence Number is a required parameter that guarantees proper message ordering
between an MQTT EoN Node and the Host application.

7.3.2. UTC Milliseconds Timestamp - timestamp

‘timestamp’:INT64:[current_utc_timestamp] // UTC Milliseconds Timestamp

UTC Milliseconds Timestamp is an optional parameter and if provided is the current UTC timestamp
value at the point this message is published.

7.3.3. Dynamic parameter values that have changed

Any parameter value that has changed value is added to this structure in the same format used for the
parameter list in the EoN Birth Certificate above:

‘Tag Name’:Parameter Data Type:[Current Parameter Value]

From the example EoN Birth Certificate above, any parameters that change values is published and
placed into the corresponding tags in Ignition or any other interested MQTT client application. For
example, if someone were to update the configuration on the example Raspberry Pi example above the
following parameters would likely change value.

‘Properties/Software Version’:STRING:’v1.0.1’ //SW Version changed to 1.0.1

‘Properties/Config Change Count’:INT32:2 //Persistent configuration change counter

The new values would be published in a NDATA message with the topic of:

spAv1.0/Sparkplug Device/NDATA/Java Raspberry Pi

The corresponding tag values in the Parameter folder shown in Figure 7 - Ignition Tag Structure after
EoN Node BIRTH above would be dynamically updated with the new software version number and the
new configuration change counter.

7.4. MQTT Device Birth and Death Certificate

Sparkplug specifies how a MQTT EoN Node uses the MQTT transport layer Death Certificate along with
the Sparkplug defined Birth Certificate. MQTT Device Birth and Death certificates are defined and
managed by the Sparkplug specification i.e. they are application level payloads published by the EoN
Node and are not part of the MQTT transport specification.

Sparkplug Specification Version 1.0 Page 23

 7.4.1. MQTT Device Birth Certificate (DBIRTH)
The Topic Namespace for a Birth Certificate for an MQTT device is:

namespace/group_id/DBIRTH/edge_node_id/device_id
The MQTT EoN Node is responsible for the management of all attached physical and/or logical MQTT
Devices. Once the EoN Node has published its Birth Certificate, MQTT Engine ensures that the Ignition
tag folder structure has the EoN node in an ONLINE state. But each physical and/or logical device
connected to this node will still need to provide this Birth Certificate before MQTT Engine
creates/updates the tag folder structure (if this is the first time this device has been seen) and set any
associated Process Variable tags in Ignition to a “GOOD_DATA” state.

7.4.1.1. Message Sequence Number - seq

‘seq’:INT32:[message_sequence_number] // Message Sequence Number

The Message Sequence Number is a parameter that guarantees proper message ordering between an
MQTT EoN Node and the Host application.

7.4.1.2. UTC Milliseconds Timestamp - timestamp

‘timestamp’:INT64:[current_utc_timestamp] // UTC Milliseconds Timestamp

UTC Milliseconds Timestamp is an optional parameter and if provided is the current UTC timestamp
value at the point this message is published.

7.4.1.3. Required Device Process Variable Map

The folder/tag structure for Device process variables and metrics is identical to the way that EoN Node
parameters are built. This is a critical part of the overall Sparkplug specification as it provides all of the
tag information and current state that MQTT Engine requires to build out the tag structure in Ignition
and provide current Process Variable information. Each tag is a metric entry in the Google Protocol
Buffer structure using the Kura schema. Each entry provides the following data for each tag:

‘Tag Name’:PV Data Type:[Current PV Value]

With this information, MQTT Engine creates the tag structure within Ignition (if this is the first time this
device has connected) for each tag. Note that in most implementations this is the only time that ALL
tags are published. Since Sparkplug is leveraging the “Continuous Session Awareness” of MQTT using the
Birth/Death Certificates, once all current tag values are published, subsequent data messages can safely
report only tag values that have changed within the MQTT session.

Tag Names in the Sparkplug specification can be defined in a simple flat tag structure where all of the
process variable tags appear below the associated Device in the tag hierarchy. But in many cases it
makes sense to organize the tags in a hierarchical folder structure to make it easier to view and manage
the tags. The “Tag Name” parameter in the Birth Certificate payload can provide a hierarchical tag path
and MQTT Engine will create the required folder structure within Ignition. For the Raspberry Pi
reference implementation, the following device folder structure and process variable tags demonstrates
both a flat tag structure and well as creating more complex tag paths to better organize tag groups:

//Place some tags at the root level of the Device tag structure
‘button’:BOOL:[current button input state] //Pibrella Button input

Sparkplug Specification Version 1.0 Page 24

‘button count’:INT32:[current count] //Internal counter for button presses
‘button count setpoint’:INT32:[setpoint] //Read/write setpoint for max button count
‘buzzer’:BOOL:false //Pibrella buzzer

//Create a folder call “Inputs” for the Pibrella digital input process variables.

‘Inputs/a’:BOOL:[current input state] //Pibrella digital input_a state

‘Inputs/b’:BOOL:[current input state] //Pibrella digital input_b state
‘Inputs/c’:BOOL:[current input state] //Pibrella digital input_c state
‘Inputs/d’:BOOL:[current input state] //Pibrella digital input_d state

//Create a folder called “Ouputs” for the Pribrella digital ouputs

‘Outputs/e’:BOOL:[current output state] //Pibrella digital output_e state
‘Outputs/f’:BOOL:[current output state] //Pibrella digital output_f state
‘Outputs/g’:BOOL:[current output state] //Pibrella digital output_g state
‘Outputs/h’:BOOL:[current output state] //Pibrella digital output_h state

//Create a subfolder under Outputs called LEDs for associated LED control/state
‘Outputs/LEDs/green’:BOOL:[current LED state] //Pibrella GREEN LED state
‘Outputs/LEDs/red:BOOL:[current LED state] //Pibrella RED LED state
‘Outputs/LEDs/yellow:BOOL:[current LED state] //Pibrella YELLOW LED state

[*Note: It is the responsibility of the EoN Device application to “upcast” unsigned integer values to the next integer resolution
that Ignition tags support. For example, a Modbus unsigned 16-bit integer value would be upcast to a signed 32 bit so that
the full resolution of the unsigned integer value can be represented. If 32-bit unsigned integer process variables are present,
accumulator or counter values for example, these would need to be “upcast” to 64-bit integer values.]

ANY folder/tag value can be populated in the Tag Map. The map above represents physical and
calculated Raspberry Pi I/O values but other real time tag values calculated by the MQTT EoN Node
connected to the device can be added to this structure as well.

Once the MQTT Device Birth Certificate is delivered to MQTT Engine, the physical/logical device is
considered online and able to deliver discrete tag data updates in real time using the DDATA message
topic and receive commands using the DCMD message.

7.4.1.1. Ignition Tag Structure after Device BIRTH Message

Using the Raspberry Pi reference implementations with the parameter and process variable mappings
above a Device Birth Certificate is published on the topic:

spA1.0/Sparkplug Devices/DBIRTH/Java Raspberry Pi/Pibrella

Upon receipt of this message, MQTT Engine automatically builds out the following tag structure in
Ignition:

Sparkplug Specification Version 1.0 Page 25

 Figure 8 - Ignition Tag Structure after Device BIRTH message

Once the initial tag structure is built out in Ignition from the information in the Device Birth Certificate,
any subsequent process variable changes are published using the DDATA message structure detailed in
section 0 below.

Sparkplug Specification Version 1.0 Page 26

 7.4.2. MQTT Device Death Certificate (DDEATH)
As defined above, the Death Certificate for an MQTT device is:

namespace/group_id/DDEATH/edge_node_id/device_id
In typical use case scenarios, it is the responsibility of the MQTT EoN Node to indicate the real time state
of either physical legacy device using poll/response protocols and/or local logical devices. Regardless of
the device being monitored and providing the real time tag information, in the event that any tag
information could be bad or questionable, it is the responsibility of the EoN Node to publish a Death
Certificate on behalf of the end device.

For most use cases, the reception of a MQTT Device Death certificate only requires the optional
parameters of the Message Sequence Number (seq) and the UTC Millisecond Timestamp (timestamp).

7.4.2.1. Message Sequence Number - seq

Message Sequence Number – ‘seq’:INT32:[message_sequence_number]

The Message Sequence Number is a required parameter that guarantees proper message ordering
between an MQTT EoN Node and the Host application.

7.4.2.2. UTC Milliseconds Timestamp - timestamp

UTC Milliseconds Timestamp – ‘timestamp’:INT64:[current_utc_timestamp]

UTC Milliseconds Timestamp is an optional parameter and if provided is the current UTC timestamp
value at the point this message is published.

7.4.2.3. Optional Death Certificate Parameters

Where the use case dictates, optional Death Certificate parameters can be provided for any extra details
that might be required for why the Device Death occurred. For example, in typical use case scenarios the
legacy poll/response device being monitored timed out on “N” number of poll/response attempts the
MQTT payload for the Death could include:

‘death_cert_cause’:STRING:’No Response’ //No response from end device

or:

‘death_cert_cause’:STRING:’CRC Error’ //CRC Error from end device

Sparkplug Specification Version 1.0 Page 27

 7.5. MQTT Device Data Messages (DDATA)
Once an MQTT EoN Node and associated MQTT Devices are all online with proper Birth Certificates
we’re in a mode of quiescent Report by Exception (RBE) reporting of any PV information that changes.
This takes advantage of the native Continuous Session Awareness of MQTT to monitor the STATE of all
connected MQTT EoN Node devices and can rely on Report by Exception (RBE) messages for any PV
state change over the MQTT session connection.

As defined above, the Data Topic for an MQTT device is:

namespace/group_id/DDATA/edge_node_id/device_id
The payload for the Data message is a Google Protocol Buffer structure using the Kura schema.

7.5.1. Message Sequence Number - seq

‘seq’:INT32:[message_sequence_number] // Message Sequence Number

The Message Sequence Number is a required parameter that guarantees proper message ordering
between an MQTT EoN Node and the Host application.

7.5.2. UTC Milliseconds Timestamp - timestamp

‘timestamp’:INT64:[current_utc_timestamp] // UTC Milliseconds Timestamp

UTC Milliseconds Timestamp is an optional parameter and if provided is the current UTC timestamp
value at the point this message is published.

7.5.3. Any Tag/PV value that has changed

Any tag/PV value that has changed value can be added to this structure in the same format used for the
PV Map in the Device Birth Certificate above:

‘Tag Name’:PV Data Type:[Current PV Value]

Using the Raspberry Pi reference implementation example given above, if any of the Pibrella process
variable values change, then a DDATA message is created and published. For example, if the button on
the Pibrella board were pressed then the following message would be published:

spA1.0/Sparkplug Device/DDATA/Java Raspberry Pi/Pibrella [‘button’:BOOL:true]

As many process variables can be published as required within the DDATA message payload. The simple
example above shows only the button state encoded into the Google Protocol Buffer payload. But if all
of the inputs changed at the same time then the payload could contain all four of the input states:

‘Inputs/a’:BOOL:[new state]
‘Inputs/b’:BOOL:[new state]
‘Inputs/c’:BOOL:[new state]
‘Inputs/d’:BOOL:[new state]

spAv1.0/Sparkplug Devices/DDATA/Java Raspberry Pi/Pibrella [protobuf of all input states]

Sparkplug Specification Version 1.0 Page 28

 7.6. Ignition Gateway Birth and Death Certificates
In infrastructures where multiple MQTT Servers provide redundancy and scalability, the MQTT EoN
Nodes need to be aware of the “state” of the Primary Host. This is accomplished with a unique set of
Birth/Death Certificates that the Host MQTT Client MUST publish when a new MQTT session is obtained.
In the same manner used for the MQTT EoN Node Birth/Death certificate generation, the Host
Birth/Death certificates will use a combination of the built in MQTT Will Topic and Will Payload Death
Certificate in conjunction with an application level Birth Certificate that is published as an MQTT
message.

The topic that a Host node will use is identical for both the Birth and the Death certificate. The Topic
Namespace will be:

STATE/scada_host_id

It uses an aspect of the MQTT transport called a “RETAINED” publish in order to maintain the current
state of the Primary Host MQTT Client session state to all available MQTT Servers. How the Host state is
used is explained in detail in the section on Sparkplug MQTT Session Management.

7.6.1. Ignition Death Certificate Payload (STATE)

When the primary Ignition MQTT client establishes an MQTT session to the MQTT Server(s), the Death
Certificate will be part of the Will Topic and Will Payload registered in the MQTT CONNECT transaction.
The Will Topic as defined above will be:

STATE/scada_host_id
The Will Payload will be the STRING “OFFLINE”.

The Will RETAIN flag will be set to TRUE, and the Will QoS will be set to 0.

With these parameters set, the MQTT Client for the Host is an MQTT message published on the topic of
scada_host_id/STATE, with a string payload of “OFFLINE” and it will be a RETAINED MQTT message.

7.6.1. Ignition Birth Certificate Payload

The first message a primary Ignition Gateway MUST publish is a Birth Certificate. The Ignition Death
Certificate is registered above within the actual establishment of the MQTT session and is published as a
part of the native MQTT transport if the MQTT session terminates for any reason.

The Birth Certificate that is defined here is an application level message published by the Host MQTT
Client applications.

The topic used for the Host Birth Certificate is identical to the topic used for the Death Certificate:

STATE/scada_host_id

The Birth Certificate Payload is the STRING “ONLINE”.

The RETAIN flag for the Birth Certificate is set to TRUE, and the Quality of Service (QoS) is set to 0.

Sparkplug Specification Version 1.0 Page 29

 7.7. Ignition to EoN Node Data Command (NCMD)
The Ignition Gateway to EoN Node command topic above provides the Topic Namespace used to send
commands from the Ignition Gateway to any connected EoN Nodes. From an MQTT Engine perspective,
this means sending an updated tag value to an associated parameter mapped in the EoN Birth
Certificate parameters list.

namespace/group_id/NCMD/edge_node_id
The MQTT Payload is encoded using the same Google Protocol Buffers Kura Schema defined above.

‘Tag Name’:PV Data Type:[new_PV_value]

This becomes a VERY convenient mechanism for the display of configuration parameters and controls
that might be on various EoN devices or even adding new ones dynamically. In the example given above
for the EoN Node Birth Certificate, some EoN Node controls provided can now be written to using this
message. By clicking on the ‘Next server’ coil in the Ignition tag structure, a Kura encoded payload is
published to cause the EoN Node to disconnect from the current MQTT Server and walk to the next one
in its configuration table shown in the following structure of topic[payload]:

//Send command to walk to next avail MQTT Server

spAv1.0/Group_001/NCMD/EoN_001 [‘Next server’:BOOL:true]

Any time a new MQTT Application client joins the MQTT infrastructure it might want to see a completely
new set of Birth Certificates from this EoN Node to get in sync with all available data. Using the proper
group_id and device_id in the topic structure, a command message is sent to cause the EoN Node to
reissue all Birth Certificate information as:

//Send command to Reissue all EoN and Device Birth Certs

spvA1.0/Group_001/NCMD/EoN_001 [‘Rebirth’:BOOL:true]

With proper permissions in Ignition, the system could write to the Reboot coil mapped out in the
example above to cause the remove EoN Node to reboot:

//Reboot the target EoN Node

spvA1.0/Group_001/NCMD/EoN_001 [‘Reboot’:BOOL:true]

7.8. Ignition to Device Data Command (DCMD)

The Ignition Gateway to Device command topic above provides the Topic Namespace used to send
commands from Ignition to any connected Device. From an MQTT Engine perspective, this means
sending a new tag value to an associated parameter mapped in the Device Birth Certificate parameters
or tag list.

namespace/group_id/DCMD/edge_node_id/device_id
The MQTT Payload is encoded using the same Google Protocol Buffers Kura Schema defined above.

‘Tag Name’:PV Data Type:[new_PV_value]

Sparkplug Specification Version 1.0 Page 30

Using the MQTT Device tags map provided in the Device Birth Certificate example above, commands can
be issued to any writable PV within the Ignition tag structure:

//Send a command to turn the GREEN LED On

spAv1.0/Sparkplug Devices/DCMD/Java Raspberry Pi/Pibrella [‘Outputs/LEDs/green’:BOOL:true]

Sparkplug Specification Version 1.0 Page 31

8. Sparkplug MQTT Session Management and Message Flow
An MQTT based SCADA system is unique in that the Host node is NOT responsible for establishing and
maintaining connections to the devices as is the case in most existing legacy poll/response device
protocols. With an MQTT based SCADA system, both the Host application as well as the devices establish
MQTT Sessions with a central MQTT Server or Severs. This is the desired functionality as it provides the
necessary decoupling from any one application and any given device. Additional MQTT clients can
connect and subscribe to any of the real time data without impacting the primary SCADA Host
application.

Due to the nature of real time SCADA solutions, it is very important for the primary SCADA Host and all
connected MQTT EoN Nodes to have the MQTT Session STATE information for each other. In order to
accomplish this the Sparkplug Topic Namespace definitions for Birth/Death certificates along with the
defined payloads provide both state and context between the SCADA Host MQTT client and the
associated device side MQTT Clients. In most use cases and solution scenarios there are two primary
reasons for this “designation” of a primary SCADA Host:

1. Only the Primary Ignition Host should have the permission to issue commands to MQTT Devices.
2. In high availability and redundancy use cases where multiple MQTT Servers are used, MQTT EoN
Nodes need to be aware of whether Ignition has network connectivity to each and every MQTT
Server in the infrastructure. If the Primary Ignition STATE shows that an EoN Node is connected
to an MQTT Server that the Primary Ignition Gateway is NOT connected to, then the EoN Node
should walk to the next available MQTT Server where STATE for the Ignition Gateway is
‘ONLINE’.

Sparkplug Specification Version 1.0 Page 32

 8.1. Primary Ignition Session Establishment
Once the MQTT Engine module is installed in Ignition, the Ignition Gateway Console provides a new
MQTT Engine Settings tab in Configuration à MQTT Engine à Settings. This configuration menu allows
for the definition of one or more MQTT Servers that are present in the infrastructure as well as if this
Ignition instance is a PRIMARY instance in the infrastructure (Note: For Ignition instances that are not
primary, refer to section 8.4,General MQTT applications and non-primary Ignition Gateway. below).
Once the MQTT Engine module is installed and configured, it will immediately try to create a Host MQTT
Session with the configured MQTT Server infrastructure. Note that the establishment of an MQTT Host
Node session is asynchronous of any other MQTT Client session. If EoN nodes are already connected to
the MQTT Server infrastructure, MQTT Engine will be able to synchronize with them. If associated EoN
nodes are not connected, MQTT Engine will register them when they publish their Birth Certificate.

Figure 9 - Host Session Establishment

The session diagram in Figure 9 - Host Session Establishment shows a very simple topology with a single
MQTT Server. The steps outlined in the session diagram are defined as follows:

1. MQTT Engine will try to create an MQTT Session using the MQTT CONNECT Control Packet (refer
to section 3.1 in the MQTT V3.1.1 specification). A Death Certificate is constructed into the Will
Topic and Will Payload of the of the Connect Control Packet with a Will QoS = 0 and Will Retain =
true. The MQTT CONNECT Control Packet is acknowledged as successful with a valid CONNACK
Control Packet. From this point forward in time, the MQTT Server is ready to deliver a Host
Death Certificate any time the MQTT Engine MQTT Client loses TCP/IP connectivity to the MQTT
Server.

Sparkplug Specification Version 1.0 Page 33

2. Once an MQTT Session has been established, MQTT Engine will publish a new STATE message as
defined in in section 7.6.1, Ignition Birth Certificate Payload. At this point MQTT Engine can
update the MQTT Client metric tags in Ignition with a current state of ONLINE.
3. With the MQTT Session established, and a STATE Birth Certificate published, MQTT Engine will
issue an MQTT subscription for the defined Sparkplug Topic Namespace, “spv1.0/#”. MQTT
Engine is now ready to start receiving MQTT messages from any connected EoN node within the
infrastructure. Since MQTT Engine is also relying on the MQTT Session to the MQTT Server(s),
the availability of Servers to Ignition is also being monitored and reflected in the MQTT Client
metrics tag folder in Ignition.
4. If at any point in time MQTT Engine loses TCP/IP connectivity with the defined MQTT Server(s),
the ONLINE state of the Server is immediately reflected in the MQTT Client metrics tag folder in
Ignition. All tag data associated with any MQTT EoN Node that was connected to that MQTT
Server will up updated to a ‘STALE’ data quality.

Sparkplug Specification Version 1.0 Page 34

 8.2. EoN Node Session Establishment
Any EoN Node in the MQTT infrastructure must establish an MQTT Session prior to providing
information for connected MQTT Device nodes. Most implementations of an MQTT EoN Node for real
time SCADA will try to maintain a persistent MQTT Session with the MQTT Server infrastructure. But
there are use cases where the MQTT Session does not need to be persistent. In either case, an EoN
Node can try to establish an MQTT session at any time and is completely asynchronous from any other
MQTT Client in the infrastructure. The only exception to this rule is the use case where there are
multiple MQTT Servers and a Primary Host application.

Figure 10 - EoN Node MQTT Session Establishment

The session diagram in Figure 10 - EoN Node MQTT Session Establishment shows a very simple topology
with a single MQTT Server. The steps outlined in the session diagram are defined as follows:

1. The EoN Node MQTT client will attempt to create an MQTT session to the available MQTT
Server(s) using the MQTT CONNECT Control Packet (refer to section 3.1 in the MQTT V3.1.1
specification). The Death Certificate constructed into the Will Topic and Will Payload follows the
format defined in section 7.2.1, EoN Death Certificate (NDEATH). The MQTT CONNECT Control
Packet is acknowledged as successful with a valid CONNACK Control Packet. From this point
forward in time, the MQTT Server is ready to deliver an EoN Node Death Certificate to any
subscribing MQTT Client any time TCP/IP connectivity is lost.
2. Once an MQTT Session has been established, the EoN Node MQTT client will publish an
application level Birth Certificate as defined in section 7.2.2, EoN Birth Certificate (NBIRTH). At
this point MQTT Engine will have all of the information required to build out the EoN Node
metrics and parameters into an associated Ignition tag folder structure and show the EoN Node
in an “ONLINE” state.

Sparkplug Specification Version 1.0 Page 35

3. After publishing the EoN Node Birth Certificate, the last thing the EoN Node MQTT client needs
to do is to issue a subscription to specific Sparkplug defined topics. The subscription to NCMD
level topics ensures that EoN targeted messages from MQTT Engine are delivered. The
subscription to DCMD ensures that Device targeted messages from MQTT Engine are delivered.
In applications with multiple MQTT Servers and designated Primary Host applications, the
subscription to STATE informs the EoN Node the current state of the Primary SCADA Host. At
this point the EoN Node has fully completed the steps required for establishing a valid MQTT
Session with MQTT Engine and Ignition.
4. If at any point in time the EoN Node MQTT Client loses TCP/IP connectivity to the defined MQTT
Server(s), a Death Certificate is issue by the MQTT Server on behalf of the EoN Node. Upon
receipt of the Death Certificate, MQTT Engine will set the state of the EoN Node to ‘OFFLINE’
and update all timestamp metrics concerning the connection. Any defined metric and parameter
tags will be set to a ‘STALE’ data quality.

Sparkplug Specification Version 1.0 Page 36

 8.3. MQTT Device Session Establishment
The Sparkplug specification is provided to get real time process variable information from existing and
new end devices measuring, monitoring and controlling a physical process into and MQTT MOM
infrastructure and the Ignition Industrial Internet of Things application platform. In the context of this
document an MQTT device can represent anything from existing legacy poll/response driven PLCs, RTUs,
HART Smart Transmitter, etc., to new generation automation and instrumentation devices that can
implement a conformant MQTT client natively.

The preceding sections in this document detail how MQTT Engine interacts with the MQTT Server
infrastructure and how that infrastructure interacts with the notion of an MQTT EoN Node. But to a
large extent the technical requirements of those pieces of the infrastructure have already been
provided. For most use cases in this market sector the primary focus will be on the implementation of
the Sparkplug specification between the native device and the EoN Node API’s.

In order to expose and populate the metric, parameter, and process variable tag information from any
intelligent device, the following simple session diagram outlines the requirements:

Figure 11 - MQTT Device Session Establishment

The session diagram in Figure 11 - MQTT Device Session Establishment shows a simple topology with all
of the Sparkplug elements in place i.e. Ignition, MQTT Engine, MQTT Server(s), MQTT EoN Node and this
element, the MQTT Device element. The steps outlined in the session diagram are defined as follows:

1. This flow diagram assumes that at least one MQTT Server is available and operational within the
infrastructure. Without at least a single MQTT Server the remainder of the infrastructure is
unavailable.
2. The Session Establishment of Ignition using the MQTT Engine module is described in section 8.1,
Primary Ignition Session Establishment. The establishment of this session is actually VERY
arbitrary based on use case as EoN Nodes can and will establish sessions with MQTT
infrastructures with or without this component across “N” number of Host applications.
3. The Session Establishment of the associated MQTT EoN Node is described in section 8.2, EoN
Node Session Establishment. This flow diagram assumes that the EoN Node session has already
been established with MQTT Engine.

Sparkplug Specification Version 1.0 Page 37

Depending on the target platform, the EoN Node may be a physical “Edge of Network” gateway device
device polling physical legacy devices via Modbus, AB, DNP3.0, HART, etc., a MQTT enabled sensor or
sensor or device, or it might be a logical implementation of one of the Cirrus Link reference
implementations for prototype EoN Nodes running on the Raspberry PI platform. Regardless of the
the implementation, at some point the device interface will need to provide a state and associated
associated metrics, parameters, and process variable to publish to the MQTT infrastructure. State #4 in
State #4 in the session diagram represents the state at which the device is ready to report all of its
its metadata and process variable information to the MQTT EoN Node as defined in Sparkplug. It is the
is the responsibility of the EoN Node (logical or physical) to put this information in a form defined in 0,

defined in 0,

Sparkplug Specification Version 1.0 Page 38

 4. MQTT Device Birth Certificate (DBIRTH). Upon receiving the DBIRTH message, MQTT Engine can
build out the proper metric, parameter, and tag information in Ignition.

Following the Sparkplug specification in section 0,

Sparkplug Specification Version 1.0 Page 39

5. MQTT Device Data Messages (DDATA), all subsequent metric, parameter, and process variable
information are published to MQTT Engine on a Report by Exception (RBE) basis using the
DDATA message format.
6. In at any time the MQTT Device (logical or physical) cannot provide real time information, the
MQTT EoN Node specification requires that an MQTT Device Death Certificate be published. This
will inform MQTT Engine that all metric, parameter, and process variable information in Ignition
be set to a ‘STALE’ data quality.

Sparkplug Specification Version 1.0 Page 40

 8.4. General MQTT applications and non-primary Ignition Gateway.
As noted above, there is the notion of a Primary Ignition Gateway instance in the infrastructure that has
the required permissions to send command to Devices and the fact that all EoN Nodes need to be aware
of the fact that the Primary Ignition Gateway is connected to the same MQTT Server its connected to or
it needs to walk to another one in the infrastructure. But both of these are known requirements of a
mission critical SCADA system.

But unlike legacy SCADA system implementations, all real time process variable information being
published thru the MQTT infrastructure is available to any number of additional MQTT Clients in the
business that might be interested in subsets if not all of the real time data.

The ONLY difference between a Primary Ignition MQTT client and all other clients that non-primary
Client do NOT issue the STATE Birth/Death certificates.

Sparkplug Specification Version 1.0 Page 41

9. Sparkplug MQTT Data and Command Messages
Looking back in this document we’ve described the following components:

• Ignition Gateway
• MQTT Engine
• MQTT Server(s)
• Edge of Network (EoN) Nodes
• Devices
• Topic Namespace
• Payload Encoding
• Birth Certificates
• Death Certificates
• STATE Messages
• Ignition, EoN Node, and Device Session Establishment

All of these specifications and definitions get to the primary goal of Sparkplug, that is to deliver a rich set
of real time Device process variable data extremely efficiently to many data consumers within the
Enterprise while still providing a best in class Command/Control SCADA system.

The disruptive notion of the emerging IIoT mindset is that intelligent devices should be smart enough to
deliver process variable data to the infrastructure when it is required. But the fact of the matter is that
the existing population of 100’s of millions of the smart devices need to be “asked” if something has
changed using poll/response protocols. This is why we’re seeing the emergence of edge devices
throughout the industrial sector. For the decade or more that it will take for device manufactures to
embed IIoT technology natively, the solution being employed today is to place this capability in small
embedded devices closer to the data producers themselves. So within the Sparkplug specification these
devices called Edge of Network Nodes (EoN) represent this new class of Gateway, Edge Controller, Edge
of Network Node, Protocol Gateway, and many more acronyms for the same class of devices. The
capability of these devices are in an extreme range of low power microcontrollers to multicore Intel and
ARM based processors. The operating systems range from full embedded Linux kernels and Windows
embedded to small bare metal RTOS’s. Regardless of the category these gateway devices fall into, the
simplicity, of MQTT and the Sparkplug specification should be available across the board.

This section of the Sparkplug specification goes into detail on how metric, parameter, and process
variable data are published/subscribe within an MQTT infrastructure in real time and the resulting tag
information that Ignition can read/write to.

9.1. EoN NDATA and NCMD Messages

We’ll start this section with a description of how metric and parameter data is published to Ignition from
an EoN Node in the MQTT infrastructure. The definition of an EoN Node is generic in that it can
represent both physical “Edge of Network Gateway” devices that are interfacing with existing legacy
equipment and a logical MQTT endpoint for devices that natively implement the Sparkplug specification.
Section XXXXX above defines the Birth Certificate MQTT Payload and the fact that it can provide any
number of metric and parameter tags that will be exposed in Ignition. Some of these tags will be “read
only” such as:

Sparkplug Specification Version 1.0 Page 42

 • EoN Manufacture
• EoN Device Type
• EoN Serial Number
• EoN Software Version Number
• EoN Configuration Change Count
• EoN Position (if GPS device is available )
• EoN Cellular RSSI value (if cellular is being used)
• EoN Power Supply voltage level
• EoN Temperature

Other metrics may be dynamic and “read/write” tags such as:

• EoN Rebirth command to republish all EoN and Device Birth Certificates.
• EoN Next server command to move to next available MQTT Server.
• EoN Reboot command to reboot the EoN Node.
• EoN Primary Network (PRI_NETWORK) where 1 = Cellular, 2 = Ethernet

The important point to realize is that the tags exposed in Ignition for use in the design of applications
are completely determined by what metric and parameter values are published in the EoN Birth
Certificate. Each specific EoN Node can best determine what data to expose, and how to expose it, and
it will automatically appear in the Ignition tag structure. Parameters can even be added dynamically at
runtime and with a new Birth Certificate, these parameters will automatically be added to the Ignition
tag structure.

The other VERY important distinction to make here is that EoN Node NDATA and NCMD messages are
decoupled from the Device level command and control messages of DDATA and DCMD. This decoupling
in the Topic Namespace is important because it allows interaction from all MQTT Clients in the system
(to the level of permission and application) with the EoN Nodes, but NOT to the level of sending Device
commands. MQTT Engine provides a configuration parameter that will BLOCK output DDATA and DCMD
messages but still allow NDATA and NCMD messages to flow. In this manner, multiple Ignition systems
can be connected to the same MQTT infrastructure, but only the ones with Device commands enabled
can publish Device commands.

The following simple message flow diagram demonstrates the messages used to update a changing
cellular RSSI value in Ignition and sending a command from Ignition to the EoN Node to use a different
primary network path.

Sparkplug Specification Version 1.0 Page 43

 Figure 12 - EoN Node NDATA and NCMD Message Flow

1. Assuming MQTT Server is available.

2. Assuming that MQTT Engine as an established MQTT Session with the MQTT Server(s).
3. The EoN Node has an established MQTT Session and the Birth Certificate has been published.
Ignition now has all defined metric and parameter tags and their current value.
4. The EoN Node is monitoring its local cellular RSSI level. The level has changed and now the EoN
Node wants to publish the new value to the associated tag in Ignition.
5. From and operational requirement, the EoN Node needs to be told to switch its primary
network interface from cellular to Ethernet. From Ignition the new value is written to the tag
and MQTT Engine will automatically publish the new value to the EoN Node parameters.

9.2. Device DDATA and DCMD Messages

The ultimate intent of the Sparkplug specification is to facilitate the publishing of real time process
variable data from existing devices in the field or on the plant floor into a Message Oriented Middleware
infrastructure. It is recognized that this represents a HUGE plethora of devices across the spectrum in
the Industrial device market sector spanning decades of installed and legacy infrastructure. Through the
use of MQTT and the Sparkplug specification, Ignition can become the ultimate “Swiss Army Knife” as
the Industrial Application Development platform for the emerging IIoT infrastructures.

The reason that the notion of an EoN Node is present in Sparkplug is a realization that if existing smart
device infrastructure cannot be addressed with emerging tools and development platforms, the
migration from legacy methodologies, protocols, infrastructures, and data silos will never occur and the
envisaged benefits of Factory 4.0 will never come to fruition. EoN Nodes can represent physical
hardware in the plant or in the field that can address converting legacy poll/response protocols (while
providing the often required network security at the same time) into real time MQTT messages. At the
same time, EoN Nodes can represent a logical software agent in next generation devices that can
natively provide real time process variables via MQTT. By using Google Protocol Buffers and the Kura

Sparkplug Specification Version 1.0 Page 44

schema in concert with the Ignition tag structure, devices can be decoupled from applications and
valuable device information can be much more easily shared within the enterprise.

But ultimately the EoN Nodes are only in place to support the ultimate data producer/consumer, the
real devices on the plant floor or in the field. The Sparkplug specification provides a way to name the
process variables acquired from these devices along with defining the appropriate data type and current
value. Once the process variables are published into an MQTT infrastructure, they can be consumed by
any number of applications are are interested in the values, including one or more Ignition Gateway
instances.

Section 0,

Sparkplug Specification Version 1.0 Page 45

MQTT Device Birth Certificate (DBIRTH) above defines the Device Birth Certificate MQTT Payload that
defines all of the process variables being provided by the associated device. Upon the receipt of the
Birth Certificate, MQTT Engine builds out the entire Device folder under the associated EoN Node and
creates all of the defined tags with current values and states. The tag naming convention is left entirely
to the implementation of the Sparkplug specification on the EoN Node. For example, if an EoN Node was
using the Modbus protocol to poll a PLC locally, then the tag names used for Ignition might remain the
conventional Modbus register addresses of 0xxxx, 1xxxx, 3xxxx, and 4xxxx. Conversely the EoN Node
might provide the capability of assigning more meaningful tag names to the Modbus register process
variables such as Suction Pressure, Tank Level, Process Temp, etc. An EoN Node providing the interface
to HART enables 4-20ma Smart Transmitters could use the actual HART assigned process variables
names such as PV1, PV2, LRV, URV, etc.

Regardless of the tag naming convention used, upon receipt of the Device Birth Certificate, MQTT
Engine will create the process variable tag structure within Ignition where they will be immediately
usable by the Ignition platform. In the following message flow diagram, we’ll use the example of a
Modbus PLC. This example will also assume that the EoN Node connected to the PLC can provide
descriptive tag names to each of the Modbus register addresses:

• Valve Open //map Modbus Coil #1 to the Valve Open command.

• Valve Close //map Modbus Coil #2 to the Valve Close command.
• Valve LS1 //map Modbus Status Input 10,001 to the Valve Limit Switch #1
• Valve LS2 //map Modbus Status Input 10,002 to the Valve Limit Switch #2
• Suction Pressure //map Modbus Input Register 30,001 to the Suction Pressure
• Discharge Pressure //map Modbus Input Register 30,002 to the Discharge Pressure
• Setpoint //map Modbus Holding Register 40,001 to the setpoint value

Sparkplug Specification Version 1.0 Page 46

 Figure 13 - Device DDATA and DCMD Message Flow

1. Assuming MQTT Server is available.

2. Assuming that MQTT Engine has an established MQTT Session with the MQTT Server(s).
3. Assuming that the EoN Node has an established MQTT Session with the MQTT Server(s).
4. Upon receiving the Device Birth Certificate, MQTT Engine creates/updates the Device folder in
Ignition and all associated tags defined for this Device.
5. The EoN Node is polling the Modbus PLC locally and detects that the Suction Pressure in
Modbus Register 30,001 has changed values. This is immediately placed into the defined Device
MQTT Payload and published. Upon receipt, MQTT Engine updates the Suction Pressure tag
value.
6. The ‘Valve Open’ Boolean is commanded on an Ignition dashboard. MQTT Engine creates the
DCMD payload required by the EoN Node to send a Modbus Force Coil Command to Coil #1.
7. The Valve Open command causes the Motor Operated value to start moving which in turn
changes the state of the two MOV limit switches. The next Modbus poll results in both ‘Valve
LS1’ and ‘Valve LS2’ in changing state. Both changes are placed into a DDATA MQTT payload and
published. MQTT Engine receives the DDATA message and immediately updates the associated
tag values in Ignition.
8. On the next Modbus poll, the Discharge Pressure changes value. The new value is published to
the MQTT Server. MQTT Engine receives the messages and immediately updates the Discharge
Pressure tag.
The valve that was commanded in #6 above finally goes from an “in transit” state to fully open.
This causes both limit switch inputs to the PLC to change state. The EoN Node picks up this state
change, formats a DDATA message with the new values and publishes it to the MQTT Server.
MQTT Engine receives the message and immediately updates the associated tags in Ignition.

Sparkplug Specification Version 1.0 Page 47

10. Sparkplug Management of Multiple MQTT Servers
There are many instances where the MQTT infrastructure will contain multiple MQTT Servers. There are
several reason why multiple MQTT Servers are utilized. Certainly, applications where redundancy, high
availability, and disaster recovery require multiple MQTT servers. Multiple MQTT Servers can also be
deployed where scalability across a large number of MQTT EoN Nodes is required. Other hybrid models
use on premise MQTT servers as the primary and Cloud based MQTT Server and/or Services as
secondary and tertiary.

Regardless of the reason for multiple MQTT Servers, there are several architectural considerations that
need to be addressed by the Sparkplug specification.

10.1. Multiple MQTT Server Topology

For a comparison of the topologies, the following diagram shows a typical infrastructure with a single
MQTT Server instance:

Figure 14 - Single MQTT Server Topology

The single MQTT Server topology shown above is a perfectly viable solution in many instances. But it
does require a highly available MQTT Server and presents a single point of failure within the system.

In keeping with the KISS principal (Keep It Simple) all of the multiple MQTT Server topologies show non-
clustered MQTT Servers. The market today offers many choices of MQTT Servers, some of which are
clustered instances of MQTT Servers. But as a baseline functionality and to keep thing very simple the
current Sparkplug specification assumes that each and every MQTT Server is a standalone instance. One
of the unique features of MQTT Engine is that it seamlessly manages the multi-server topologies.

Sparkplug Specification Version 1.0 Page 48

 Figure 15 - Multiple MQTT Server Topology

In the drawing shown in Figure 15 above, there are multiple MQTT Servers available in the topology. In
this topology, MQTT Engine connects to all available MQTT Servers in the infrastructure and provides
detailed metrics on each instance. These metrics include:

• Number of EoN Nodes connected to each MQTT Server

• Latency check in milliseconds between MQTT Engine and the MQTT Server.
• The MQTT Client ID used for this MQTT Session
• The Offline DateTime time stamp of when the MQTT Server last went offline.
• The Online DateTime time stamp of when the MQTT Server came online.
• The current real time state of the connection to the MQTT Server
• Number of MQTT messages per second being processed by this MQTT Server
• The MQTT Server URL

Sparkplug Specification Version 1.0 Page 49

 Figure 16 - MQTT Client tags in Ignition

Note that all of the Ignition Gateway instances and well as any other “Line of Business” (LOB) application
can establish MQTT Sessions with all available MQTT Servers. In this manner, the EoN Nodes are free to
determine the best network path and MQTT Server availability to establish their MQTT Session with.

This topology does require that EoN Nodes using the Sparkplug specification keep a table of available
MQTT Servers and be able to connect to any number of them based on network and server availability.

Using this topology any EoN Node can use any of the available TCP/IP networks and connect to any one
of the available MQTT Servers. From the Ignition and LOB application side of the topology, they don’t
really care which of the N number of MQTT Servers the EoN Nodes connect to. The Birth/Death
certificate management automatically takes care of know which EoN Nodes are connected at any point
in time, and just as important, which nodes are not connected. MQTT Engine keeps metrics on every
EoN Node connecting into the MQTT infrastructure and includes:

• Current MQTT Server this EoN Node is connected to.

• DateTime time stamp of when this EoN went Offline last.
• DateTime time stamp of when this EoN Node came Online last.
• The number of Birth Certificates sent by this EoN Node.
• The number of Death Certificates seen from the MQTT Servers on behalf of this EoN Node.
• Current Online state of this EoN Node
• Total number of actual bytes received from this EoN Node.
• Total number of actual bytes sent to this EoN Node.

Sparkplug Specification Version 1.0 Page 50

 Figure 17 - EoN MQTT metric tags in Ignition

10.2. Primary Ignition Gateway STATE in Multiple MQTT Server Topologies

For implementations with multiple MQTT Servers, there is really only one additional aspect that needs
to be understood and managed properly. When multiple MQTT Servers are available there is the
possibility of “stranding” and EoN Node if the Primary command/control Ignition Gateway loses network
connectivity to one of the MQTT Servers. In this instance the EoN Node would stay properly connected
to the MQTT Server publishing information not knowing that Ignition was not able to receive the
messages. When using multiple MQTT Servers, the primary Ignition Gateway instance must be
configured to publish a STATE Birth Certificate and all EoN Nodes need to subscribe to this STATE
message.

MQTT Engine has a configuration option that specifies whether this Ignition Gateway instance is a
“Primary” command/control instance or not. If it is a primary instance then every time MQTT Engine
establishes a new MQTT Session with an MQTT Server, the STATE Birth Certificate defined in section
above is the first message that is published after a successful MQTT Session is established.

EoN Node devices in an infrastructure that provides multiple MQTT Servers can establish a session to
any one of the MQTT Servers. Upon establishing a session, the EoN Node should issue a subscription to
the STATE message published by Ignition. Since the STATE message is published with the RETAIN
message flag set, MQTT will guarantee that the last STATE message is always available. The EoN Node

Sparkplug Specification Version 1.0 Page 51

should examine the payload of this message to ensure that it is a value of “ONLINE”. If the value is
“OFFLINE”, this indicates the the Primary Ignition Gateway has lost its MQTT Session to this particular
MQTT Server. This should cause the EoN Node to terminate its session with this MQTT Server and move
to the next available MQTT Server that is available. This use of the STATE message in this manner
ensures that any loss of connectivity to an MQTT Server to the Primary Ignition Gateway does not result
in EoN Nodes being “stranded” on an MQTT server because of network issues. The following message
flow diagram outlines how the STATE message is used when three (3) MQTT Servers are available in the
infrastructure:

Figure 18 - Ignition STATE flow diagram

1. When an EoN Node is configured with multiple available MQTT Servers in the infrastructure it
should issue a subscription to the Primary Ignition Gateway STATE message. The EoN Nodes are
free to establish an MQTT Session to any of the available servers over any available network at
any time and examine the current STATE value. If the STATE message payload is ‘OFFLINE’ then
the EoN Node should disconnect and walk to the next available server.
2. Upon startup, if MQTT Engine is configured to be the Primary Ignition instance, the MQTT
Session will be configured to register an Ignition DEATH Certificate that indicates STATE is
‘OFFLINE’ with the message RETAIN flag set to true. Then an Ignition BIRTH Certificate will be
published with a STATE payload of ‘ONLINE’.
3. As the EoN Node walks its available MQTT Server table, it will establish an MQTT Session with a
server that has a STATE message with a payload of ‘ONLINE’. The EoN Node can stay connected
to this server as long as its MQTT Session stays intact and it does not receive an Ignition DEATH
Certificate.
4. Having a subscription registered to the MQTT Server on the STATE topic will result in any change
to the current Ignition STATE being received immediately. In this case, a network disruption
causes the Ignition MQTT Session to server #2 to be terminated. This will cause the MQTT
Server, on behalf of the now terminated Ignition MQTT Client to publish the DEATH certificate to

Sparkplug Specification Version 1.0 Page 52

 anyone that is currently subscribed to it. Upon receipt of the Ignition DEATH Certificate this EoN
Node will move to the next MQTT Server in its table.
5. The EoN Node moved to the next available MQTT Server and since the current STATE on this
server is ‘ONLINE’, it can stay connected.
6. In the meantime, the network disruption between Ignition and MQTT Server #2 has been
corrected. MQTT Engine has a new MQTT Session established to server #2 with an update Birth
Certificate of ‘ONLINE’. Now MQTT Server #2 is ready to accept new EoN Node session requests.

Sparkplug Specification Version 1.0 Page 53

11. Sparkplug Persistent versus Non-Persistent Connections
Persistent connections are intended to remain connected to the MQTT infrastructure at all times. They
never send an MQTT DISCONNECT message during normal operation. This fact lets MQTT Engine provide
the real time state of every persistent node in the infrastructure within the configured MQTT Keep Alive
time period using the Birth/Death mechanisms defined above.

But in some use cases, such as sending GPS coordinates for asset tracking or other IOT applications with
periodic data from sensors, MQTT enabled devices do not need to remain connected to the MQTT
infrastructure. In these use cases, all the Device needs to do is to issue an MQTT DISCONNECT control
packet prior to going offline in order to leave the MQTT infrastructure “gracefully”. In this case an MQTT
Device or associated Device DEATH certificate will most normally not be seen. System designers just
need to be aware that the tags in Ignition in this case will represent “Last Known Good” values with a
time stamp of this data where the current state of the of the MQTT Device is not a real time indication.
Ignition tag time stamp values can be used to determine when the values from this node were last
updated.

Non-persistent MQTT Enabled Devices should still register a proper DEATH Certificate upon the
establishment of an MQTT session. In this manner the Ignition can still have a good representation of
Last Known Good process variable versus the fact that the MQTT session was terminated prior to the
EoN Node being able to complete its transaction.

Sparkplug Specification Version 1.0 Page 54

12. Glossary of Terms
This section will be provided in the next version of the Sparkplug specification.

Sparkplug Specification Version 1.0 Page 55

13. Contact Information
For any questions regarding this Sparkplug specification or for more information, please use the
following details:

Cirrus link Solutions

Website: www.cirrus-link.com
Phone: 844-924-7787
Email: [email protected]

Sparkplug Specification Version 1.0 Page 56