Home


co⚡e: Sparkplug™ MQTT edge and host

This page: Introduction | Development | Progress | Download | Requirements

Sparkplug info: Infrastructure | Security | Messages

Guides: Setup a test system | Add SparkplugB to an existing CODESYS project


avg reading: 5 minutes

Introduction

Imagine IIoT without the burden of re-inventing the wheel! Just instantiate, configure, connect variables, done! No hassles and as little coding as possible. You just need an MQTT broker, the rest is Plug & Play - this is what co⚡e: Sparkplug™ MQTT edge and host library for CODESYS offers you.
A modern, free and open way for any of your devices to exchange data using MQTT. By exploiting the scalability of MQTT and adding a well defined payload to the MQTT with the Sparkplug specification, the protocol provides you a flexible architecture. It allows you to auto-discover Nodes, Devices and their Data (Metrics). By combining the properties of the existing MQTT infrastructure you get a very flexible and powerful system. You can add or remove nodes and devices to your infrastructure on the fly. Whether your devices are state-of-the-art or legacy, the Edge node is able to handle all types of devices. Last but not least, your data can be delivered securely and with rich meta data for added context.

Goal

Providing the CODESYS ecosystem a full specification compliant implementation of Sparkplug B edge and host nodes, which run on any sufficiently capable CODESYS based controller. Since the code is written 100% IEC code, the library is fully portable over various brands and types of controllers.

At this moment in time, there are two leading industrial IoT protocol families available: OPC-UA and the MQTT family based protocols. Sparkplug is part of the MQTT family based protocols. Both OPC-UA and MQTT families of protocols are good, very reliable and very secure and share a partly overlapping use case. However, there are caveats in using OPC-UA or MQTT. OPC-UA itself is not implemented in open IEC-ST and several extensions are currently not available, like "Store & Forward", and so OPC-UA has a lot of untapped potential. MQTT is merely a means to get bytes from point A to B. MQTT does not prescribe the user how data should be mapped or how often it is updated. The user is free to use any data format and is responsible for adding context, if any. The user is also responsible for regularly sending the data. Whilst this seems great on first sight, this hinders quick, smart and vendor neutral data exchange. The 'magic' needed is not readily in place and needs to be implemented and tested in every project.

This is where Sparkplug steps in - it provides you with open, lightweight, vendor-neutral, well defined data exchange, state aware transmission and state aware data on top of what MQTT already offers, while at the same time keeping CPU and bandwidth consumption to a minimum*. In short, you don't have to do anything special in order to enjoy a modern, state of the art data exchange which is secure, reliable and very very fast (sub second data update rates are possible but depend on your specific network architecture)

This project aims to "marry" a CODESYS based controller with the Sparkplug IIoT protocol and open up the vendor-independent CODESYS ecosystem with the IIoT market using all advantages that the Sparkplug protocol offers.

Benefits

With the benefits of MQTT we already have:

  • Simple and open,
  • Pub/Sub,
  • Last will and testament per MQTT node (allows subscribers to know when a node goes offline),
  • Bandwidth efficient (fast),
  • State aware connection,
  • Decouples devices from applications,
  • Utilizes latest TCP/IP security.

The benefits of Sparkplug add:

  • Full autodiscovery of nodes, devices, metrics and node/device capabilities,
  • Include metric-, node-, device metadata,
  • State awareness of all data, meta data, nodes and devices,
  • Report by Exception (RbE) i.e. updates of values are only sent if these value changes,
  • Polling is a thing of the past due to built in session and data state awareness,
  • User implemented watchdogs/heartbeats are unnecessary and redundant,
  • Historical Store & forward,
  • File Transfer,
  • High Availability,
  • Open standard,
  • Provides industry interoperability with other open standards

Sparkplug thus adds many powerful benefits on top of MQTT.

Last but not least;
Our library has been built in open source, which should allow experienced programmers 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 utilise are not open-source.

Stateful: Why do we need that?

Sparkplug is a specification for MQTT enabled devices and applications to send and receive messages in a stateful way. This means that each participant is fully aware of each other's connection state and data state. While MQTT itself is stateful by nature, it does not ensure that all data on a receiving MQTT application is current or valid.
Sparkplug provides a mechanism on top of MQTT for ensuring that device or application data is always current and valid.
Next to this, Sparkplug can be used to act as a gateway between legacy and modern devices for seamless interaction.
Lastly, Sparkplug is capable of leveraging file transmission and historical "store & forward" to ensure that data-gaps are a thing of the past.

Flexible Architecture

An overview of a typical architecture using a mix of CODESYS and third party capable SparkplugB MQTT devices;
SparkplugB CODESYS Architecture
Details on the different components in the infrastructure:

Development

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. When our Primary Host is finished you won't need Ignition anymore!

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 even free to implement and use another MQTT client implementation. If you do, we urge you to implement a stable and 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.

Additional Information about Sparkplug

Any additional information about Sparkplug can be found at the Eclipse™ Sparkplug™ Working Group website.
The Eclipse Sparkplug Working Group ensures open and interoperable IIoT.

https://sparkplug.eclipse.org/

Current Sparkplug specifications:

https://www.eclipse.org/tahu/spec/Sparkplug%20Topic%20Namespace%20and%20State%20ManagementV2.2-with%20appendix%20B%20format%20-%20Eclipse.pdf

Progress

Timeframe

Our software is aimed to be "best in class" and easy in use. It is being developed by professionals as individuals, not as a company. We chose to to give this project our valuable resources: time and effort. This experimental and open form of development stimulates our creativity in full freedom without any boundaries or limitations. This means that we do not have any hard deadlines to meet apart from those we impose on ourselves. Of course we set milestones and progress is being made as you can see.

31 mar 2021 : Major updates for Edge / Device and Primaryhost

The primaryhost, edge & devices now use a common 'FB_Metric' Function Block.
Usage of host-, edge-, and device-metrics is equalised which helps simplify and streamline your code significantly.
Edges and Devices publish data predictably and reliably, because of a major overhaul to the publish data notification architecture.
The change has proven to work outstandingly with large amounts of payload data in combination with a sub second update rate.
The Primaryhost utilizes this mechanism for sending NCMD's or DCMD's in due time.
Some bugs in the Device still exist and will be dealt with first.

5 mar 2021: CODESYS based Primary Host node (Bring Your Own SCADA)

The CODESYS based Sparkplug Primary Host acts as a lightweight CODESYS alternative to Ignition's Primary Host Node (Primary SCADA). Any compatible CODESYS runtime can be turned into a Primary Host and can detect any connected Edge Of Network node, Device, Metrics and capabilities associated, just like Ignition's Primary SCADA Host can!
Since we will (obviously) not implement a full fledged SCADA in the PLC, you can bring your own SCADA aka BYOS. Just install a SCADA of your favorite choice on a machine somewhere in your architecture and connect it with the CODESYS Primaryhost. No SCADA? No problem! You can always run a local target or web visualisation in the CODESYS controller on top of your project or even do both!

The current Primary Host version supports detection of Groups, Edges with metrics and Devices with metrics. Received NBIRTH certificates are processed and the detected resources are claimed from resource pools. Furthermore NDATA payloads and NDEATH certificates are processed and the corresponding Edges and Metrics are updated. DBIRTH, DDATA, DDEATH implemented.
The PrimaryHost will be extended with exciting new features during the next period, so check this page regularly.

The following preview shows a fully configured Primary Host (topmost FB) and some GetMetricByName() calls (bottom 4 FB's).
The GetMetricByName() calls are ideally suited in any M2M usecase (planned and in preparation).
If you only have need for a Primary Host, you can omit all optional GetMetricByName() calls and your are ready!

Roadmap

This roadmap is subjected to change without prior notice. No liabilities shall be taken!
Milestones which have been completed 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 of Basic Package v1.0.0.0, contains all previously mentioned milestones

v2.0.0.0

  • Standard Metrics Support,
  • Standard FB_Device, acts as a digital representation of a physical device sending simple metrics,
  • Standard Support for receiving Server Commands, setpoints etc,
  • Standard Bind Multiple Devices to an Edge (EoN)
  • 1.3.3.0 preview library and project released, contains all previously mentioned milestones
  • Standard FB_PrimaryHost, CODESYS based Primary Host Node Implementation,
  • Standard M2M calls for Machine to Machine communication,
  • Standard support for templates and aliases for optimized communication data bandwidth and CPU load,
  • Extended Metrics support (templates and alias, act as DUT datatypes),
  • Debugging / Optimization/ Refactoring of Standard package,
  • Release of Standard Package v2.0.0.0, containing all previously mentioned milestones

v3.0.0.0

  • Advanced File transfer,
  • Advanced Historical data support,
  • Advanced Store & forward,
  • Advanced Server High Availability (HA),
  • Advanced FB_Edge, support for select advanced capabilities ,
  • Advanced FB_Device, support for select advanced capabilities,
  • Advanced M2M calls for Machine to Machine communication, support for select advanced capabilities,
  • Advanced FB_PrimaryHost node, support for select advanced capabilities,
  • Debugging / Optimization/ Refactoring of Advanced package.
  • Release of Advanced Package v3.0.0.0, containing all previously mentioned milestones

Download

By downloading and using our software you abide by the MIT License
The Sparkplug library itself 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. Because the library is MIT licensed you can exchange the MQTT Client SL for any other flavour MQTT client as you see fit but you must do so yourself. Offcourse we are happy to provide you with our advice or some assistance.

  • NOTE If you have no 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,
  • Using our library, Ignition's SCADA as host is not needed, as we implemented a 'lightweight' primaryhost node!

  • Without proper licensing, Ignition Enterprise SCADA runs in a DEMO trial period for 2 hours or opt in for a FREE maker Edition,

  • On pricing, read this FAQ [questions:#9]

Sparkplug Preview Library v1.3.3.0

27 dec 2020: Bidirectional communication implemented.


* v1.3.1.1 Ignition SCADA with CODESYS based Edge of Network and 3 Devices

  • Implemented Bidirectional communication between Ignition's Primary SCADA Node and our CODESYS Edge of Network (EoN) and attached Devices.
  • Implemented handling of multiple devices connected to an EoN,
  • Updated TLS handling,
  • Updated MQTT Client version.
  • For a list of full capabilities see Roadmap
  • See Requirements for requirements


Download PREVIEW SparkplugB v1.3.3.0 library

Download PREVIEW SparkplugB v1.3.3.0 example

SparkplugB v1.0.0.0 Library

1/1
IEC SparkplugB v1.0.0.0 Installation
  • Turns your CODESYS controller into a SparkplugB Edge of Network Node (EoN).
  • This package contains all components in a convenient single installer.
  • See Roadmap for a list of full capabilities of this package.
  • See Requirements for information on system requirements and restrictions.

Download v1.0.0.0 Package

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.


@hermsen

@i-campbell

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