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.

Installing

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

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 right click a topic and choose to remove it if desired. To add a topic, type the name in the box and click the Add button.

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.

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 Certificate Chain
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.

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.

Disconnect

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