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."
Check the required versions of the JDK, yarn and node
Use the following commands to verify JDK, yarn, and node versions:
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
Build the TCK with Gradle
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:
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
After building with yarn build,the web console will start for production with
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
cd hivemq-sparkplug-aware-extension ./gradlew buildAfter successful build the extension artifact is located at _build/hivemq-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.
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