Eclipse-Sparkplug-TCK

Eclipse-Sparkplug-TCK.md

Getting started with the Sparkplug TCK

This document pulls instructions from various sources into one place. Assumes the dev is working within a Windows environment.

1. GET LISTED | sparkplug.eclipse.org

   This page has a link to download binaries (.zip file) that you need to get started. While looking at the GitHub page, it was not obvious (to me, anyway) this .zip is being referenced. The download link is not super visible, look for the following:

   You can download the current TCK binaries from here.

2. sparkplug/tck | github.com/eclipse-sparkplug

   The official GitHub page for the Sparkplug project inludes a folder at the root level for the TCK. There you'll find a UesrGuide which is the primary source for this gist. Note that at the time of writing, the readme in the TCK folder makes reference to the zipped binaries but the link provided is broken.

3. HiveMQ Community Edition | github.com/hivemq

   The TCK is built assuming a HiveMQ broker is available for testing. There is a free version available on GitHub.

4. User Guide - Install HiveMQ | docs.hivemq.com

   Docs for installing HiveMQ are really good, but be aware, there is extra setup required to make HiveMQ work with the TCK. Details to follow.

Download

• HiveMQ Community Edition | github.com/hivemq
• WindowsService Installer | hivemq.com
• Eclipse-Sparkplug-TCK-3.0.0.zip | download.eclipse.org

Install & Configure HiveMQ

Following instructions at docs.hivemq.com, create C:\hivemq which will be referred to as the HiveMQ 'home' directory. Content of the zip files will land here.

Copy sparkplug-tck extension (from zip) folder into HiveMQ home folder

• from ~\Downloads\Eclipse-Sparkplug-TCK-3.0.0\SparkplugTCK\hivemq-extension\sparkplug-tck-3.0.0
• to C:\hivemq\extensions

Copy windows-service folder into HiveMQ home folder

• from ~\Downloads\hivemq-windows-service\hivemq-windows-service\hivemq-windows-service
• to C:\hivemq

-- Results --

C:\HIVEMQ
|   README.txt
|   
+---bin
+---conf
+---data
+---extensions
|   +---hivemq-allow-all-extension
|   |       hivemq-allow-all-extension-1.0.0.jar
|   |       hivemq-extension.xml
|   |       LICENSE
|   |       README.html
|   |       README.txt
|   |       
|   \---sparkplug-tck
|       |   hivemq-extension.xml
|       |   sparkplug-tck-3.0.0.jar
|       |
|       +---coverage
|       \---third-party-licenses
|               license-dependency.html
|               
+---log
+---third-party-licenses
\---windows-service
    |   installService.bat
    |   LICENSE.txt
    |   README.txt
    |   uninstallService.bat
    |   wrapper.jar
    |   wrapperApp.jar
    |   
    +---bat
    +---conf
    +---lib
    +---log
    +---tmp

Next, run C:\hivemq\windows-service\installService.bat. After the service installs, run services.msc, find the HiveMQ service, and set its startup behavior to manual then restart the system.

Need to modify C:\hivemq\conf\config.xml to include a websocket listener. The exact configuration is detailed in sparkplug/tck/UserGuide.adoc, copied below for reference:

<hivemq>
  <listeners>

    <!-- Default listener -->
    <tcp-listener>
      <port>1883</port>
      <bind-address>0.0.0.0</bind-address>
    </tcp-listener>

    <!-- Add for Sparkplug TCK -->
    <websocket-listener>
      <port>8000</port>
      <bind-address>0.0.0.0</bind-address>
      <path>/mqtt</path>
      <name>my-websocket-listener</name>
      <subprotocols>
        <subprotocol>mqttv3.1</subprotocol>
        <subprotocol>mqtt</subprotocol>
      </subprotocols>
      <allow-extensions>true</allow-extensions>
    </websocket-listener>
    
  </listeners>
  <anonymous-usage-statistics>
    <enabled>true</enabled>
  </anonymous-usage-statistics>
</hivemq>

Start the HiveMQ broker by runnnig C:\hivemq\bin\run.bat (may need to run as Administrator).

Run the web console

The user-facing part of TCK is an interactive web page or web console. The backend runs on NodeJS, the project uese the yarn package manager.

1. Run corepack enable from an Administrator shell (cmd or PowerShell). This assumes the corepack component was installed along with NodeJS.

2. Run npm install -g yarn to install the package manager globally (not ideal to install globally for every application, but for this it's fine).

3. Run $env:NODE_OPTIONS = "--openssl-legacy-provider" to set an environment variable that will modify NodeJS runtime.

4. yarn install, yarn build, then yarn start

5. Open a browser and go to http://localhost:3000.