MQTT

Generated data can be exported via the MQTT protocol.

 

 

Log files cannot be exported via MQTT.

 

Set up a connection to the MQTT broker using settings in the 'Export Setting's group at the device level as shown below.

 

 

Two broker connections can be configured. Broker 1 is always enabled when MQTT is enabled. If the connection to Broker 1 fails and Broker 2 is enabled, then a connection to Broker 2 will be attempted.

 

The value of the 'Mqtt Group Name' parameter is equivalent to the 'group_id' element in the Sparkplug B specification. The 'edge_node_id' in Sparkplug B comes from the 'Device Name' or 'Device Export Name' parameter. The 'device_id' element comes from the 'User Configured Name' parameter or the 'App Export Name' parameter.

 

SparkplugbB nodes are equivalent to PLC Shift devices, and Sparkplug B devices are equivalent to PLC Shift apps. Tags at the device level have a topic that starts with this:

 

 

Tags at the app level have a topic that starts with this:

 

 

Every metric (value) that is sent using Sparkplug B has a 64 bit alias. The alias is very important because tag names are only sent in NBIRTH or DBIRTH messages. At run time, only the alias is sent for published messages.

 

This alias must be unique at the node level, which means that the alias for any given PLC Shift tag must be unique across all the apps that belong to any single device. The alias should also be persistent, so that when apps are restarted, each tag that was previously exported is exported with the same alias.

 

To accomplish this, the alias for each tag is formed from an app specific identifier and the tag's parameter ID. The parameter ID is not unique because all apps of the same type have the same tags with the same parameter IDs.

 

When an app is created at runtime, it is assigned a persistent GUID (Globally Unique IDentifier, aka UUID). The top 64 bits of the tag alias come from a 32 bit hash code of the GUID, and the bottom 32 bits come from the parameter ID. Parameter IDs for each tag can be found in each app's reference material in this manual. The app alias prefix can be found in the MQTT log. The value is published in the log when an app is created, as shown below.

 

 

As of version 1.21 release (December 2023), each app publishes a 'MQTT Alias Prefix' status parameter. This makes is easier to find a given app's alias prefix compared to digging through the log file.

 

As an example, to calculate the alias of the 'Methane' tag in a Gas Flow app, you would start by finding the tag's parameter ID. In this case, the parameter ID for methane is 1245184, or 0x0013 0000 in hexadecimal. If the app's MQTT alias prefix is 1817164652, or 0x6C4F BB6C hex, the alias can be calculated by putting the app's alias prefix in the top 32 bits and the parameter ID in the bottom 32 bits, which results in a 64 bit alias of 0x6C4F BB6C 0013 0000, or 7 804 662 751 788 466 176 decimal.

 

You can use this alias to decode messages on the app's topic that only have an alias and no tag name, or you can use the alias to publish new values that the app has subscribed to.

 

To enable publishing streaming values via MQTT:

 

 

Values are published in the Sparkplug B format. A Sparkplug B aware broker and clients are required to use data in this format. The screen grab below shows tags automatically generated in Inductive Automation's Ignition SCADA when using Sparkplug B and a Cirrus Link MQTT broker.

 

 

Streaming data values are published to the broker once per second. It is suitable for real time data.

 

Tabular data can be published using MQTT, but this mechanism uses features that are not officially part of the MQTT or Sparkplug B protocol. To publish tabular data using MQTT, use a Cirrus Link broker and Inductive Automation Ignition SCADA.

 

Tabular data is exported periodically using its own broker connection. A connection is opened, tabular data is exported, and then the connection is closed.

 

By using its own connection, publishing and subscribing streaming data once per second is not impacted. Because a different connection is used, NBIRTH/NDEATH and DBIRTH/DDEATH messages are required. We do this using the normal device and application export names, but with _RECORDS appended to the name, as shown below.

 

 

The MQTT connection used for records will connect to whichever broker is active for streaming data. This allows all MQTT connections to be kept in sync.

 

 

For streaming values where publishing is enabled, subscribing is also allowed. Subscribing to a value allows for the value to be changed directly via MQTT via SCADA or other systems, without requiring the value to be mapped through the PLC.

 

Sparkplug B requires that device level changes from the host to the edge are published on a topic that includes 'DCMD' in the topic. See the Sparkplug B specification for more details on how topics are generated.

 

Normally, updates would be published with the tag alias in the payload, which is how the PLC Shift runtime knows how to match incoming requests to a specific tag. However, if the alias is 0, then the PLC Shift runtime will attempt to match by name, which is slower, but requires no knowledge of the alias. If the tag alias is 0, then the Sparkplug B metric payload must contain the tag name.

 

When publishing values that an app has subscribed to, take care to make sure that new value's type matches the type of the parameter in PLC Shift. When writing to user defined parameters, match the tag value type instead of parameter value type, because the parameter value type is always 'string' for user defined parameters.