A Step-by-Step Guide to Obtaining Sparkplug 3.0 Certification

The Sparkplug Compatibility Program allows you to prove compatibility and certify your product for Eclipse Sparkplug and MQTT-based IoT infrastructure.

By getting listed in the compatibility program, you will gain the confidence that your products meet stringent quality and interoperability requirements. Your compatible products will get visible for current and future adopters of Sparkplug and, in turn, this will build your brand and expand your market reach.

To become certified, you must pass multiple open-source tests that confirm conformance to Sparkplug Technology Compatibility Kit (TCK). If a product passes the compatibility tests, the Sparkplug Working Group will add it to its official list of compatible products. Once licensed, you can market the compatibility to the outside world using the Sparkplug Compatible logo.

Here’s a detailed step-by-step guide on how to get certified using Sparkplug Technology Compatibility Kit (TCK). If you want to learn more about the Sparkplug TCK program, check out this article to learn what’s new in Sparkplug 3.0.

Before we dive into the first step, here is an overview of the full certification protocol:

• Step 1: Ensure all prerequisites are met.
• Step 2: Build and install the HiveMQ Sparkplug-TCK Extension.
• Step 3: Run HiveMQ with Sparkplug-TCK Extension.
• Step 4: Run HiveMQ.
• Step 5: Build and run the Sparkplug TCK Web console.
• Step 6: Access the TCK web console.
• Step 7: Build and install the “HiveMQ Sparkplug Aware Extension."

Preconditions

Check the required versions of the JDK, yarn and node

Use the following commands to verify JDK, yarn, and node versions:

JDK 11

yarn

Node.js

Build and Install the HiveMQ Sparkplug-TCK Extension

Now that JDK, yarn, and node versions are verified, you can build and install the HiveMQ Sparkplug-TCK extension. Use the following steps:

Checkout the Eclipse Sparkplug repository

gh repo clone eclipse-sparkplug/sparkplug

Change location to TCK folder

cd sparkplug/tck

Build the TCK with Gradle

./gradlew build

This will result in an extension artifact for the HiveMQ MQTT broker located in the ./build/hivemq-extension directory:

Run HiveMQ with Sparkplug-TCK Extension

Now, it is time to run HiveMQ with the Sparkplug-TCK Extension.

Download HiveMQ Community Edition

Get the latest HiveMQ Community Edition, which is open source and freely available.

Extract the package and change to the HiveMQ extensions folder

Copy the extension distribution file

Now copy the former build TCK Extension (tck/build/hivemq-extension/sparkplug-tck-3.0.0-rc1.zip) to the HiveMQ Extension directory and

Unzip the sparkplug-tck-3.0.0-rc1.zip in the extension folder

Verify the Sparkplug TCK extension has been successfully installed

Add a websocket listener to HiveMQ

The TCK console application relies on a websocket MQTT communication. So, a websocket listener has to be established on the HiveMQ broker. The HiveMQ configuration file is located in the config/config.xml folder and has to be extended like this:

Run HiveMQ

Now, HiveMQ is ready to be started via ./bin/run.sh. and the terminal

Verify the TCK extension is loaded

Verify a websocket listener is started on port 8000

Build and run the Sparkplug TCK Web console

The TCK is controlled by a web console application, which is located in the Sparkplug project in the folder sparkplug/tck/webconsole. The project, including all dependencies, can be installed with

yarn install

After building with yarn build,the web console will start for production with

yarn start:

Access the TCK Web Console

After successful start of the application, the TCK web console can be opened in a web browser at: http://localhost:300

Connect the TCK to the local HiveMQ Broker

The easiest way to connect to the local HiveMQ broker is to the set default values by clicking on the Set Default Values button and then Connect:

The TCK is now ready to go.

Available Sparkplug conformance profiles

Now Sparkplug conformance profiles for Host Applications, Edge Nodes and MQTT Brokers are available:

The Host Application profile contains tests for testing:

• Session Establishment
• Session Termination
• Send Command
• Edge Session Termination
• Message Ordering
• Multiple MQTT Server (Broker)

Edge Node Tests profiles are:

• Session Establishment
• Session Termination,
• Send Data, Send Complex Data
• Receive Command
• Primary Host and Multiple MQTT Server (Broker)

With the Broker test profile a MQTT broker can be tested for general Sparkplug Compliance and also the Sparkplug Aware functionality.

Build and Install the “HiveMQ Sparkplug Aware Extension”

The Sparkplug Aware Extension turns the HiveMQ broker into a Sparkplug Aware Broker providing all optional features of the Sparkplug 3.0 specification.

The “HiveMQ Sparkplug Aware Extension” is an open source project. Its project repository is located here: https://github.com/hivemq/hivemq-sparkplug-aware-extension The repository contains the source code for a custom build, also a release artifact.

Clone the repository

gh repo clone hivemq/hivemq-sparkplug-aware-extension

Build the extension

This build artifact, or alternatively the downloaded release file, can now be unzipped into HiveMQ CE’s extensions folder:

After restarting HiveMQ, the Sparkplug Aware Extension should be ready:

Give the Sparkplug TCK a Try

Now that the TCK is running with a Sparkplug Aware HiveMQ broker, the Broker conformance profile can be tested:

Sparkplug Compliant Broker Test

To execute the Compliant Test for the broker, no further preconditions are required. With click on Start Test, the local HiveMQ broker is successfully tested:

Sparkplug Aware Broker Test

The Aware Broker test requires a Sparkplug Edge Node for testing the state management. Here, use the soon-to-be-released version of MQTT.fx (a beta version for Windows and MacOS). MQTT.fx is an easy-to-use graphical desktop tool for MQTT-related testing. It also provides Sparkplug tracing and device simulation capabilities.

During the Aware Test run, it is required to connect and disconnect the device matching the given Group Id and EdgeNode Id. So after the Aware Test starts the EoN Device in MQTT.fx can be connected to the local HiveMQ broker:

The “Subscribe” tab of MQTT.fx shows the message flow, including the new $sparkplug/certificates/# topic:

After disconnecting the MQTT.fx Sparkplug device, the test ends. You will see the results in the TCK web console as a proof that the HiveMQ broker earned the Sparkplug Aware conformity:

Now the setup is complete.

What’s Next?

With the TCK application and the Sparkplug Aware HiveMQ broker, all the required tools for further Host Application and Edge Node tests are ready to continue with the Sparkplug 3.0 Certification of Hardware and Software.

Check out the video below that provides the summary of this blog

About Jens Deters

Jens Deters has held various roles in IT and telecommunications over the past 22 years: software developer, IT trainer, project manager, product manager, consultant and branch manager. Today Jens leads the Professional Services Team at HiveMQ. As a long-time expert in MQTT and IIoT and developer of the popular GUI tool MQTT.fx, he and his team support HiveMQ customers every day in implementing the world’s most exciting (I)IoT UseCases at leading brands and enterprises.

Contact Jens