Sparkplug™ and the Sparkplug™ logo are trademarks of the Eclipse Foundation
Copyright © 10/11/19 Eclipse Foundation, Inc. https://www.eclipse.org/legal/efsl.php

co⚡e: Sparkplug™ MQTT edge and host

Information and guides
Sparkplug™ information | Preview how-to | Setup a test system with Ignition Primary Host | Add SparkplugB to an existing CODESYS project

This Page
Introduction | Components | Development | Progress | Download | Requirements | Acknowledgements

avg reading time: 5m

Introduction

Designed by the co-author of MQTT, Arlen Nipper, Sparkplug™ is designed to fit on top of regular MQTT. In 1999, when MQTT was invented, it was originally meant for SCADA systems and left out all specifications on how topics and payloads should be structured and how devices should behave. This allowed regular MQTT to be used in different industries like connected car, logistics but also smart manufacturing. Sparkplug™ fills this gap and provides a vendor-neutral specification for the data formats, topic structures, state management, and how topologies should be structured in IIoT scenarios. This way, Sparkplug™ adds several smart features on top of regular MQTT, resulting in a "Sparkplug™ enhanced MQTT". A flexible architecture which allows you to auto-discover edge nodes, devices and their metrics (data & metadata) as devices and applications can be added and removed anytime without affecting the system as a whole. Report by Exception (RBE) saves bandwidth, memory and computational power on the producer and the consumers of data. Last but not least, your data can be delivered securely via the latest industry strength security specifications and with rich meta-data for added context.

Imagine Industrial Internet of Things (IIoT) without the burden of re-inventing the wheel each time you change your installation. It has been designed to provide you a single point of truth at the edge. This is what co⚡e: Sparkplug™ MQTT edge and host offers you. It offers a flexible, modern, free and open way for any of your devices to exchange data using Sparkplug™ enhanced MQTT. You only need a proper MQTT broker and this library.

Instantiate, configure, connect, done!

Sparkplug™ Benefits at a glance

A comparison of regular MQTT with "Sparkplug™ enhanced MQTT".
The following list shows you what makes Sparkplug Powerful.

Benefit	Fullspec MQTT v3.1.1	Sparkplug™ B MQTT
Simple	⚡	⚡
Open	⚡	⚡
Pub / Sub	⚡	⚡
Last Will and Testament	⚡	⚡
Bandwidth efficient	⚡	⚡
Continuous Session Awareness	⚡	⚡
Persistent Connections	⚡	⚡
Decouples devices from applications	⚡	⚡
Latest in TCP/IP security	⚡	⚡
Setup with minimal coding		⚡
Standardized Payload definition		⚡
Standardized Topic Namespace		⚡
Auto discovery of Nodes, Devices and Metrics		⚡
Meta-data for Metrics		⚡
Metric Properties		⚡
Death and Birth Certificates		⚡
Report by Exception (RbE)		⚡
Bi-directional data-transfer between Host and Node (by design)		⚡
Aliases for optimized bandwidth usage		⚡
File Transfer *		⚡
Historical Store and Forward *		⚡
High Availability *		⚡

• Advanced features subjected to the roadmap
  ** Sparkplug™ MQTT needs a fully compliant v3.1.1 broker.
  *** Cloud services like AWS IoT Core, Azure IoT Hub and Google Cloud Iot Core are not supported!
  since they are not fully v3.1.1 compliant. Plenty of good alternatives are available.

Goal

Providing the CODESYS ecosystem a full specification compliant implementation of Sparkplug B Edge and Host nodes, which runs on any sufficient capable CODESYS based controller. Since the code is fully IEC compliant, the library is portable over various fully IEC compliant brands and types of industrial controllers. Since stability is key, the code is continuously and rigorously tested.
In short, this solution aims to "marry" CODESYS with the Sparkplug™ MQTT protocol and further open up the vendor-independent CODESYS ecosystem with the IIoT market, thus fully exploiting the synergy between CODESYS and Sparkplug.

Last but not least

Our library has been built in open source, which should allow any experienced programmer to add/remove or alter parts of the code*. It allows a for peer to peer code review and to build/expand on the existing code base. The Sparkplug™ specification has been released with open-source in mind, and we are delighted to share our library also! Of course the CODESYS runtime and MQTT library we utilize are not open-source.

*The library contains OOP coding, following the S.O.L.I.D. principles.

Components

An overview of the components in this library, mixed with regular third party capable Sparkplug™ MQTT devices;

Details on the different components in the infrastructure:

• [Infrastructure] explains various node functions like Edge, Device, Primary Host, etc etc.
• [Security] explains the available security levels,
• [Messages] explains the various defined sparkplug messages and their payloads.

Development

Some tools we use to develop our library.

• Ignition Primary Host node
  We test our code against Ignition as Primary Host node and against the Sparkplug TCK when it is available.
  However, we are also in full preparation of developing a CODESYS variant of a Primary Host.
  To experience the full capabilities of Sparkplug in action, you can create your own free test system using this setup guide: Setup a test system with Ignition Primary Host. When our Primary Host node has finished, there will be no explicit need for Ignition anymore.

• TCK Toolkit
  We will test and verify our library against the TCK toolkit once it comes publicly available.

• co♻e: A unittest framework for CODESYS based systems
  We aim to cover the entire solution with pragmatic unit, integration and pov tests.

For more information see #co♻e

• MQTT Explorer
  MQTT.fx supports limited SparkplugB payload protobuffer decoding so it is a very good & flexible test client.

http://www.jensd.de/apps/mqttfx for more information
MQTT.fx is published under Apache License, Version 2.0.

• MQTT Client Library Usage
  Under the MIT license you are free to use the co⚡e: Sparkplug™ MQTT edge and host library. You are free to implement and use another MQTT client implementation. If you do, we urge you to implement a stable & 100% MQTT v3.1.1 capable library. However, in this project we will use the following library;

https://store.codesys.com/iiot-libraries-sl.html
Without a valid license, the software runs for 30 minutes in demo mode.

Progress

Timeframe

Milestones are set and progress is being made. You can read our progress blog here

Roadmap

This roadmap is subjected to change without prior notice. No liabilities shall be taken! Completed milestones are clearly marked.

v1.0.0.0

• Basic MQTT Publisher/Subscriber implementation (FB_MQTT_PubSub),
• Basic Google Protobuf payload encoder / decoder (FB_Payload_Simple),
• Basic Metric Support for Bool, Real, DWord, Int, Byte etc, etc (FB_SparkplugBSimple, etc, etc.),
• Basic SparkplugB implementation, responsible Topics & sending messages (No support for receiving commands apart from Rebirth),
• Basic EoN Node, responsible for publishing Node/Device metrics (FB_Edge_Of_Network_Node),
• Basic EoN Node TLS Connection Support,
• Basic EoN Node Server Command support: Rebirth,
• Debugging / Optimization/ Refactoring of Minimal Viable Product.
• Release ofPackage v1.0.0.0

v2.0.0.0

• Basic datatypes metrics support,
• Device support, acts as a digital representation of a physical device sending metrics,
• Receiving Server commands, setpoints etc,
• Bind multiple Devices to an Edge (on the fly capable),
• Machine to Machine communication,
• Primary Host node, CODESYS based Primary Host Node implementation proof of concept,
• [x] Divided the solution into seperate libraries:
  • co⚡e: Sparkplug™ MQTT Stack - Contains the common basis for Edge and Host solutions,
  • co⚡e: Sparkplug™ MQTT Edge - Contains the Edge of Network and Device solution,
  • co⚡e: Sparkplug™ MQTT Host - Contains the Primary Host solution,
  • co🔗e: A Linked List Solution.
• [x] Support for Metric Properties,
  • ReadOnly
• Support for Metric Aliases (experimental),
• Support for Metric Templates,
• Unittesting and TDD - CI/CD integration to (auto)test the solution to maturity,
• Debugging / Optimization/ Refactoring of Standard package
• Release of Package v2.0.0.0

v3.0.0.0

• File transfer,
• Historical data support,
• Payload compression,
• IoDriver,
• Debugging / Optimization/ Refactoring of Advanced package.
• Release of Package v3.0.0.0

Download

By downloading and using our software you abide by the MIT License
The co⚡e: Sparkplug™ MQTT edge and host library is MIT licensed and open sourced, but to run it for more than 30 minutes you will need to purchase an IIoT Libraries Bundle SL from the CODESYS Store, as we make use of the MQTT Client contained in it.

Support for Metric Properties

30 oktober 2021: Edge Nodes are now able to send Metric Properties.

A property or a set of properties can now be assigned to a Metric. This means that for instance an analog value can now be decorated with properties like "Min Value", "Max Value", "unit", etc etc.
The property is scanned for changes just like the value, however since properties are mostly static in nature, the overhead of the properties in communication is negligible.

In order to run the example you need to download and install ALL four following libraries;

Stack library contains a shared basis for the Edge and Host solution.

Edge library contains the Edge of Network (EoN or Edge) and Device solution.

Host library contains the Primary Host solution.

Contains an open source Linked List solution.

After all four libraries are installed you can run this example;

A small guide on how to run the example can be found here Preview how-to

• For a list of full capabilities see Roadmap
• See Requirements for requirements
• Numerous bugfixes and improvements
• Implemented support for Metric Properties (Ignition only)
• Splitted main library into 4 parts for modularization
• all features from the roadmap are demonstrated within this example, Enjoy!

Requirements

System requirements and restrictions	Info
Programming System	CODESYS Development System Version 3.5.16.0 or higher
Runtime System	CODESYS Control Version 3.5.14.0 or higher
Licensing	A separate CODESYS IIoT libraries SL per PLC or Machine
Required Accessories	Any 100% fully compliant MQTT v3.1.1 broker or cloud service. Sparkplug requires the following: QoS 0 and 1, Retained Messages, Last Will and Testament, A flexible security system.
Restrictions	Brokers or cloud services like AWS IoT Core, Azure IoT Hub or Google Cloud Iot Core are not supported. They do not not implement MQTT v3.1.1 in full. Ask Google, Amazon or Microsoft for a fully compliant MQTT v3.1.1 implementation.

NOTES

If you have no CODESYS licenses available, you can still enjoy Sparkplug with the following limitations in mind:

• Any unlicensed CODESYS runtime runs in a DEMO trial period for 2 hours, after that period you must restart the runtime,'
• Any unlicensed IIoT SL library runs in a DEMO trial period for 30 minutes, after that period you must re-download the runtime.
• On pricing read this FAQ [questions:#9]
• Because this library is MIT licensed you can exchange the licensed MQTT Client SL for any other flavour MQTT client as you see fit, but you must do so yourself. Ofcourse we are happy to provide you with our advice and / or some assistance.
• Ignition's SCADA as host is not necessarily needed since we implement a 'lightweight' primary host node, but if you wish you can always choose it;
• Ignition Enterprise SCADA runs in a DEMO trial period for 2 hours or choose to opt in for a FREE maker Edition.

Acknowledgements

We are passionate software developers who maintain co⚡e in spare time.
CODESYS fully supports us in our efforts by providing a free and open source platform for everybody to use.
Read more on #co5e

Project Members:

• aliazzz
• hermsen (admin)
• i-campbell (admin)

Sparkplug™ and the Sparkplug™ logo are trademarks of the Eclipse Foundation
Copyright © 10/11/19 Eclipse Foundation, Inc. https://www.eclipse.org/legal/efsl.php