Abstract

The MQTT Sparkplug™ B specification defines a way for subscribing clients (such as MQTT Engine) to notify publishing clients (such as MQTT Transmission) via a STATE message when they are online or offline.

When the subscribing client connects to a server, it can publish its connection state on a topic that contains an ID identifying it as a Sparkplug Primary Host Application.

In the event that the subscribing client becomes disconnected from the server, the server will publish a Last Will and Testament (LWT) message on the same topic setting the state to offline. Any connecting client that subscribes on the state topic will then be notified of Primary Host Application state and can key off this to do different things when that subscriber status changes. 

STATE message formats

Prior to the v3.0.0 release of the specification, the STATE message included a UTF-8 string payload that was either ONLINE or OFFLINE. Sparkplug™ B payloads are not used for encoding in this payload and this allowed Host/backend application(s) to work across Sparkplug™ payload types.

  • Topic:
    • STATE/primary_host_id
  • Payload:
    • ONLINE
    • OFFLINE

In the v3.0.0 release of the specification, both the topic namespace and payload for the STATE message have been updated. The topic now includes a "namespace" element and the payload is a JSON data format comprising two name/value pairs of "online" and "timestamp".

  • Topic:
    • spBv1.0/STATE/primary_host_id
  • Payload:
    • { "online" : true,  "timestamp" : 1668114759262}
    • { "online" : false, "timestamp" : 1668114759262}


MQTT Engine compliance

From release 4.0.14 MQTT Engine will support the new STATE message format and be in compliance with MQTT Sparkplug™ B specification v3.0.0.

However as there will still be many existing clients which are only compatible with the MQTT Sparkplug™ B specification v2.2, we have made changes to MQTT Engine to establish a MQTT client whose only function is to publish the STATE message in its legacy format.

This is a configurable option and will be disabled as default on a new installation of MQTT Engine.

How does this change in MQTT Engine affect me?

For most customers this change will be seamless and no additional configuration is required.

If you are updating from a previous version of MQTT Engine to v4.0.14, the configuration of the Legacy State template will be completed as part of the upgrade process and the Legacy Client enabled.

MQTT Engine will always attempt to publish/subscribe using the new STATE message format even when the Legacy Client is enabled and there is no means to disable this.

If you have restrictive Access Controls Lists configured at your broker you will need to allow access to the spBv1.0/STATE/ topic

If using MQTT Distributor you will see that the tag [MQTT Distributor]Distributor Info/Connected Clients has increased by one. If you have scripting or an application using this tag value, then you will likely need to make the appropriate changes to accommodate this increase in the connected client count. 

When viewing Ignition logs, you will also notice a new MQTT Engine client which starts with ME-LS for example: 

TahuClient    10Nov2022 17:13:31    ME-LS-6a6595d1-d44b-4: MQTT Client connected to tcp://localhost:1883 on thread Thread-2043
TahuClient    10Nov2022 17:13:31    ME-6ME-88477f61-7893-49b1: MQTT Client connected to tcp://localhost:1883 on thread Thread-2040

How do I configure the legacy state message?

The additional legacy STATE client is configured under the Advanced section for each of the configured MQTT servers in the MQTT Engine module configuration. The Legacy State template will be automatically populated with the variables from the server configuration Main and TLS sections if you are updating from a previous version of MQTT Engine to v4.0.14.

For some MQTT servers, the Username/Password for each client connection must be unique and so these parameters for the second legacy client will need to be edited.

To disable, you simply deselect the Enable Legacy STATE messages option. To fully remove the retained legacy STATE message at the server, you will need to restart any connected server.

Which clients will be created?

With Primary Host Disabled and Legacy Host Disabled

  • ME client created, connects and subscribes [[a/#][0], [spBv1.0/#][0]]

With Primary Host Enabled and Legacy Host Disabled

  • ME client created, connects and subscribes [[a/#][0], [spBv1.0/#][0], [spBv1.0/STATE/MyPrimaryHost][1]]

With Primary Host Disabled and Legacy Host Enabled

  • ME client created, connects and subscribes [[a/#][0], [spBv1.0/#][0]]
  • ME-LS client created but no connection made

With Primary Host Enabled and Legacy Host Enabled

  • ME client created, connects and subscribes [[a/#][0], [spBv1.0/#][0], [spBv1.0/STATE/MyPrimaryHost][1]]
  • ME-LS client created, connects and subscribes [[STATE/MyPrimaryHost][1]]


Additional Resources

  • No labels

New to MQTT? Start Here!