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 | Sparkplug |Components | Development | Progress | Download | Requirements | Acknowledgements

avg reading time: 5m

Introduction

co⚡e: Sparkplug™ MQTT edge and host is a free and open source IEC61131-3 implementation of Sparkplug™ B.
It offers free, open, easy, flexible, modern and secure way for all of your devices to exchange information using Sparkplug™ enhanced MQTT. All you need is an MQTT broker and our library and connect your CODESYS runtime as an Edge of Network (EoN) to the Sparkplug™ B infrastructure.

Sparkplug

Designed by the co-author of MQTT, Arlen Nipper, Sparkplug™ is designed to fit seamlessly "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, but regular MQTT lacks any standardized topic or data format.

Sparkplug™ now provides a true 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 into a "Sparkplug™ Enhanced Industrial MQTT". It provides you a "single point of truth" at the Edge of your installation.

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.

Usecases

Any size installation can be easily managed and controlled remotely through this library. Small and large tankparks, pipelines, power distribution, energy grids, potable water, waste water, surface water, oil refinery, food, pharma, vehicle park monitoring, or any other type of asset you see fit. This library offers you an open, free, simple, reliable and secure solution to your asset monitoring and control needs. By adding an Edge (EoN) to your CODESYS application, your application is connected to a Sparkplug™ B infrastructure in no time.

Sparkplug™ benefits at a glance

A comparison between regular MQTT and Sparkplug™ B enhanced MQTT.

• Advanced features subjected to the Roadmap,
• Please refer the Requirements.

Goal

Providing the CODESYS ecosystem a free of charge, secure and full specification compliant implementation of Sparkplug™ B Edge and Host node which run on any sufficiently capable CODESYS based PLC.

Since our code is implemented in 100% IEC (no embedded C or C++ components), the library is portable over various brands and types of industrial controllers.

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, IIoT and MQTT through Sparkplug™.

Last but not least

Our library is open source, which should allow any experienced programmer to add or alter the code. It allows for peer to peer code review and to 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.

Components

An overview of the components in this library are lined in red;

Sparkplug™ B Edge, ususally 1 per controller.
Sparkplug™ B Device (plugs into an Edge), usually several per controller
Sparkplug™ B Primary Host, Xperimental PLC based step in replacement for any full fledged PC based Sparkplug™ Primary SCADA Host.

The library allows for a mix any third party capable Sparkplug™ MQTT devices as long as they adhere the Sparkplug™ B standard. Details on the different components in the infrastructure:

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

Development

Some documents and (software) tools we use while developing are

• Sparkplug™ B Specification

  https://github.com/eclipse/sparkplug/blob/develop/specification/

• Ignition as 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 is finished, no explicit need for Ignition exists

• TCK Toolkit

  We will test and verify our solution against the TCK toolkit once 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 Sparkplug™B 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 use another MQTT Client implementation. You must implement it yourself.
  However, in this project we will use https://store.codesys.com/iiot-libraries-sl.html
  Why? stablility, full spec mqtt, TLS support and relatively easy.
  Without a valid license the software runs for 30 minutes in demo mode.

Progress

Progress blog

Milestones are set and progress is 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 version: Minimalistic Edge Node with TLS support

• MQTT Pub/Sub Support,
• Google Protobuffer payload encoding/decoding,
• Sparkplug™ for MQTT, responsible for publishing of Sparkplug™ Topics & Payloads,
• Metric Payload Support for: UINT8, UINT16, UINT32 UNIT64, INT8, INT16, etc,
• Edge Node, responsible for publishing Node metrics,
• Edge Server Commands supported: NCMD Rebirth,
• Edge TLS Support,
• Debugging / Optimization/ Refactoring of Minimal Viable Product.
• Package v1.0.0.0 Released

v2.0.0.0 Standard version: Full-spec Edge, Device and Host implementation

• All Datatype Metrics supported,
• Device support, acts as a digital representation of a physical device sending metrics,
• Receive Server Commands, setpoints etc, (xCMD),
• Bind multiple Devices to Edge,
• Machine to Machine communication,
• [x] Seperate libraries:
  • co⚡e: Sparkplug™ MQTT Stack - Contains a common basis for Edge and Host solutions,
  • co⚡e: Sparkplug™ MQTT Edge - Contains Edge and Device solution,
  • co⚡e: Sparkplug™ MQTT Host - Contains Primary Host solution,
  • co🔗e: A Linked List Solution.
• [x] Support for Metric Properties,
  • Read Only Property (Mandatory Included),
  • Any User Defined Property,
  • Ignition verified,
• [x] Support for Aliases,
  • Edge / Device send server xBIRTH & xDATA via Alias
  • Edge / Device receive server xCMD via Alias
  • Ignition verified
• [ ] Template i.e. Edge / Device complex variables (nested structs) support,
  • Stack Code implementation,
  • Edge / Device send server xBIRTH Template support,
  • Edge / Device send server xDATA Template support,
  • Edge / Device receive server xCMD Template support,
  • Ignition verified
• [x] WebSockets support,
  • HTTP ( ws://...:8080 ) verified,
  • HTTPS through TLS Support ( wss://...:8083 ) Experimental,
  • Proxy Settings (Server Address, Port, Username, Password)
• [x] Edge Publishes Properties like
  • ABOUT (mandatory),
  • Compiler version,
  • Runtime Version,
  • NIC (Up to 8 supported) name, MAC & IP addresses,
  • OS version, etc,
  • Extended Info Opt-Out,
  • Ignition verified
• [x] CODESYS based Primary Host Node implementation,
  • Server receive Edge / Device xBIRTH,
  • Server receive Edge / Device xDATA,
  • Server receive Edge / Device xCMD,
  • Server receive Edge / Device xDEATH & LWT -> Data becomes STALE
  • Server send Edge / device xCMD (DATA)
  • Strict enforcement of SEQ / BDSEQ check,
  • Server sends Edge REBIRTH to Edge or Device,
  • WebSocket support,
  • Metric property support,
  • Alias Support,
  • Template Support.
• 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 Advanced version: Mature Edge, Device and Host, sporting user-friendly advanced features

• File Transfer (event and command based)
• Store and Forward,
• Historical data support (store and forward based)
• Primary Host Advanced Node Commands Discovery Service,
• High Availability (HA) support,
• 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

Mandatory: Contains Linked List solution and contains the common basis for the Edge/Device and Primary Host solution. You need both libraries in order to run Edge/Device or Primary Host.

Download co🔗e: Linked List

Download co⚡e: Sparkplug™ MQTT Stack

Contains the Edge & Device solution.

Download co⚡e: Sparkplug™ MQTT Edge

Contains the Xperimental Primary Host solution.

Download co⚡e: Sparkplug™ MQTT Host

To run the example project you need all of the above libraries.
A small guide on how to get started with the example can be found here: Preview how-to

Download co⚡e: Sparkplug™ MQTT Example for Edge and Host

The co⚡e: Sparkplug™ MQTT edge and host library is MIT licensed and open source, however to run it for more than 30 minutes you will need to purchase an IIoT Libraries Bundle SL from the CODESYS Store, since we make use of the MQTT Client contained in it.

Enjoy!

Requirements

NOTES

If you have no CODESYS licenses available, you can still test Sparkplug with the following time limitations:

• Any unlicensed CODESYS runtime runs in a DEMO trial period for 2 hours, after that a restart of the runtime is mandatory,'
• Any unlicensed IIoT SL library runs in a DEMO trial period for 30 minutes, after that period a re-download the runtime is mandatory.
• For tips and pricing, read this FAQ [questions:#9]
• This library is MIT licensed, you may exchange the licensed MQTT Client SL for any other MQTT client you see fit. This will be done by you. We can offcourse help by providing you with tips or hints or small assistance.
• Ignition Enterprise SCADA runs in a DEMO trial period for 2 hours or choose to opt-in for a FREE maker Edition.
• The Xperimental Codesys Based Primary Host makes it possible to test our Edge/Device without Ignition (or any other primary host) beware that is not feature complete.

Acknowledgements

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

Webdesign by Haico Hermsen / Ian Campbell

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