Using The Sparkplug Viewer

About

AUTOSOL provides Sparkplug Viewer as a utility application to provide a window into Sparkplug or plaintext data on your broker.

Sparkplug Viewer is not a replacement for an HMI, though it does understand the Sparkplug specification.

The application is passive by design. For example, if the application has not observed a DBIRTH or NBIRTH message for a DDATA, a REBIRTH request will NOT be sent unless the user manually instigates that through the menu.

Sparkplug Viewer V4B is currently an open beta.

Installing

There is no installer. The application is one file. Download the application wherever you wish and double click on it to execute.

64-bit Windows is required.

Key Features

Make a Broker Connection.

Metric View for visualizing your data.

Data View where you can inspect messages.

Publish Sparkplug Node Rebirth messages and Plaintext MQTT messages.

Ability to Write to Metric.

If the connection to your broker is lost, the application will retry that connection according to your KeepAlive value until you click Disconnect.

The application supports connecting to:

Unsecured brokers
Secured brokers via TLS 1.2 or 1.3 (app defaults to highest available).
MQTT v3.1, MQTT v3.1.1, MQTT v5
Brokers that require password authentication

The TLS authentication modes supported are:

Anonymous
Server Authentication
Client Authentication

Broker Connection

Click Client > Connect > New Connection. You may also save and re-open your connection from file later if desired.

When you ‘Save Connection to File’, there is an option to save credentials in the file or omit them. Keys and certificates in the file are referred to by path, they are not saved in the file.

If the connection to your broker is lost, the application will retry that connection according to your Keep Alive value until you click Disconnect.

Broker Address
Configure an IP or hostname to connect to.

Broker Port
Configure a TCP port to connect to.

Subscribe To
Configure one or more topics to subscribe to. The most commonly used topics at time of writing are defaults. You may left click a topic and press the delete key to delete it if desired. To add a topic, type the topic name in the bottom row of the grid. You may choose a QoS between 0 and 2 for each topic.

Some brokers are very sensitive to which topics they will permit clients to connect and subscribe to. Choosing a topic space or QoS level that is not appropriate for your broker configuration may result in an MQTT authentication error and disconnect.

Client ID
Provide a specific Client Id or accept a random Client Id (click button to generate a unique Id).

Keep Alive
Keep alive value in seconds. Also tells the application on what interval to attempt reconnection to the broker when it drops.

Protocol Version
Select MQTT version to use.

Clean Session
Opt into a clean session or not, with regard to MQTT.

Message Limit

The message limit is the maximum number of topics and payloads that will display at a time in the message list on the right side of the window. When the limit is reached, the oldest message will be cycled out of the display.

Use Username/Password
If checked, the application will present the specified username and password to broker when connecting.

Enable TLS
Use the highest version of TLS available on the system to connect to the broker.

Verify Broker Cert
Validate the server certificate presented by the broker before establishing a connection.
CA certificates in the Windows certificate store will be considered.
The CA certificates(s) in the CA Certificate box on this page will be considered if specified.

Suppress Hostname/IP Check

If checked, Sparkplug Viewer will still allow the TLS handshake to continue even though the broker’s certificate may be inauthentic for one of these reasons:

No CN (Common Name) in the Subject field that matches either the hostname or IP that Sparkplug Viewer is connecting to the broker at. Not required if there is a SAN (see next bullet point).
No SAN (Subject Alternate Name) extension that matches either the hostname or IP that Sparkplug Viewer is connecting to the broker at. Not required if there is a CN in the subject that has the IP or hostname (see previous bullet point).
The IP or hostname provided in either the CN or SAN does not match the IP or hostname that the Broker Address provided to Sparkplug Viewer. NOTE: This may not necessarily be the broker itself if there is some kind of TCP port forwarding in place, in which case you will need to suppress the error to connect.

Suppress Certificate Chain Check

If checked, Sparkplug Viewer will still allow the TLS handshake to continue even though the broker’s certificate chain may contain errors.

Client Certificate/Client Key
If the broker expects client authentication and you are using an X509 Certificate + Private Key file to authenticate, reference the file here. For the private key, PKCS8 format is expected. Both encrypted (specify a password in the box) or unencrypted keys (omit the password in the box) are supported.

Example of how to create a key file with OpenSSL:
openssl genrsa -aes256 -out client.key 2048

Example of how to create a certificate:
openssl req -out client.csr -key client.key -new -subj "/C=US/ST=Texas/O=THIS_COMPANY INC/CN=MyEACM/emailAddress=name@company.com" --outform PEM
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out client.pem -days 3650 --outform PEM

Client PFX
If you prefer to do client authentication with a password protected PFX file instead of a Client Certificate/Key in separate files you may do so here. A PFX (PKCS12) file retains both the client certificate and private key in the same file. Enter the password in the box.

Example of how to create a PFX file with OpenSSL:

openssl pkcs12 -export -out client-eacm/client-eacm.pfx -inkey client-eacm/client-eacm.key -in client-eacm/client-eacm.pem -certfile ca/ca.crt --passin pass:john --passout pass:john

Metric View

In the pane on the left side of the screen there is a Metric view for visualizing your data.

Metrics are in the order:

Group Name
Node Name
Device Name
Metric Name
Metric Attributes

If no BIRTH message has been observed by a given metric, it is referred to by the syntax <NO NAME-n> where n is the alias number provided in DDATA.

Once a BIRTH message has be observed while the application is running, <NO NAME-n> will be replaced with the name of the metric.

Data View

In the pane on the right side of screen there is a Data view where you can inspect messages.

Left click the desired message to select it:

Left click and drag the bottom right pane to the desired position so you can view the data:

Sparkplug Node Rebirth

In the menu on the top left of the screen you can publish Sparkplug Node Rebirth messages.

Sparkplug Viewer is designed to be passive and let your HMI be your HMI. It will not automatically issue a REBIRTH message if it does not fully understand metric data. You may choose to send a REBIRTH by clicking Client > Write > Node Rebirth.

Enter the name of the Group and Edge Node and a click Send NCMD Rebirth. Example:

Plaintext MQTT

In the menu on the top left of the screen you can also publish Plaintext MQTT messages.

Sometimes publishing a plaintext MQTT message is useful for debugging a node i.e. faking a STATE message.

Click Client > Write > MQTT and provide the Topic and UTF8 payload contents in order to publish a plaintext payload. You may set Retain and QoS if desired.

Write to Metric

Inside of the Metric View you can right click on a Metric’s name (first column) and choose to write to a metric. Frequently it is useful to write to either a Device Metric (under EoN Devices) or an Edge Node Metric (under EoN Metrics). Right click the desired metric in the view and select the Write to Metric button. Fill in the desired value and choose Write.

Writing to a device metric will instigate an MQTT publish to topic spBv1.0/{GROUPID}/DCMD/{NODEID}/{DEVICENAME} i.e.

spBv1.0/TX/DCMD/GALV/G5

With a binary payload expressed in structured text similar to:

{
  "timestamp": "1740082321586",
  "metrics": [
    {
      "alias": "7",
      "timestamp": "1740082321586",
      "datatype": 9,
      "floatValue": 1
    }
  ]
}

If you check the box Force Write by Name, the name of the metric will be used in place of the alias integer. Example payload rendered in structured text:

{
  "timestamp": "1740082601750",
  "metrics": [
    {
      "name": "DPLOWLIMIT",
      "timestamp": "1740082601750",
      "datatype": 9,
      "floatValue": 1.1
    }
  ]
}

Disconnect

You may click Client > Disconnect to disconnect or just close the application when finished.

ACM User Guide