MQTT

The MQTT configuration pages cover three levels: MQTT Clients, MQTT Devices, and MQTT Variables. Start by creating an MQTT client that defines the broker connection. Then create an MQTT device that groups variables under that client. Finally, create the MQTT variables that map publish and subscribe topics to named variables in the EnvisionSCADA namespace.

MQTT Clients handle the transport-level connection to the broker. MQTT Devices handle application-level grouping and topic structure. MQTT Variables define the individual payload mappings, data types, and historian behavior.

Keep client, device, and variable naming consistent with the broker topic structure so the overall MQTT layout remains easy to trace and maintain.

An MQTT device can also read a Sparkplug B edge node. With Protocol Sparkplug B, the device is one edge node of a Sparkplug B system, and its variables are the metrics of that edge node, without a topic per variable. The values, the data types, and the online state come from the birth and death certificates of the edge node. See Sparkplug B Devices.

Client Settings

Each MQTT client defines a connection to a single MQTT broker. Configure the broker endpoint, authentication, TLS options, and diagnostics.

Create a new client with the Add button in the toolbar. The Add dialog contains all client settings organized in the sections General, Connection, Sparkplug B, and Diagnostics, with default values already filled in. Enter at least the Name and Broker URL and press Create.

The client row shows Enable, Name, Broker URL, Port, Timeout, Retry, Username, Password, and Description directly and these values can be edited in place. Press the Settings icon on a client row to open the MQTT Client Settings dialog, which contains the same sections and all settings of the client. Press Save to apply the changes.

Device Settings

Each MQTT device groups variables under one MQTT client. MQTT devices do not have their own broker connection; they inherit it from the client they belong to.

Create a new device with the Add button in the toolbar. The Add device dialog contains all device settings in the General section, with default values already filled in. Enter at least the Name and press Create.

The device row shows Enable, Name, Protocol, Template, Timeout, and Description directly and these values can be edited in place. Press the Settings icon on a device row to open the Edit device dialog, which contains the same settings. Press Save to apply the changes. With Protocol Sparkplug B, the Sparkplug B section with Group ID and Edge Node ID is shown, and Template and Timeout are hidden.

Variable Settings

Each MQTT variable maps a publish or subscribe topic to a named variable in the EnvisionSCADA namespace.

Create a new variable with the Add button in the toolbar. The Add variable dialog organizes all variable settings in the tabs General, MQTT, Scaling, Historian, and Gateway, with default values already filled in. Enter at least the Name on the General tab and press Create. When the variable is created on a template device, it is also created on all instance devices that use the template. On a template device, start the Name with the {Device} replacer, so that each instance device gets its own variable. The Name must resolve to a different variable on each device; this is checked for every instance device before anything is saved, when a variable is created and when it is renamed.

The variable row shows Enable, Name, Asset, DataType, Publish Topic, Subscribe Topic, and Description directly and these values can be edited in place. Press the Settings icon on a variable row to open the Edit variable dialog, which contains the same tabs and all settings of the variable. Press Save to apply the changes. Changes made on a template device are also applied to the matching variable on all instance devices, while each instance keeps its own Modbus Address value. The Gateway tab settings Modbus Address, OPC UA, Writeable, MQTT Publisher, Kafka Device, Kafka Remap Device, and Kafka Remap Variable are also available as table columns, which are shown with Columns as described in the Configuration Tables article.

On a device with Protocol Sparkplug B, the dialog shows Sparkplug Device ID and Metric Name instead of Publish Topic and Subscribe Topic, the MQTT tab is hidden, and the table shows the columns Sparkplug Device ID and Metric Name instead of the topics. The Browse button lists the metrics of the edge node, see Browse Sparkplug Metrics.

Sparkplug B Devices

A device with Protocol Sparkplug B reads one edge node of a Sparkplug B system, as defined by the Eclipse Sparkplug 3.0 specification. The client subscribes to the Sparkplug namespace spBv1.0/# and acts as a Sparkplug host application for the edge nodes of its Sparkplug B devices. Messages of other edge nodes are ignored. The client handles the messages as follows:

• The birth certificates NBIRTH and DBIRTH define the metrics of a session, with name, alias, data type, and the first value. The variables receive their values from the birth certificate, and the device shows Online.
• NDATA and DDATA carry changed values, by alias or by name. Historical metrics (is_historical) do not change the live value.
• An NDEATH with the bdSeq of the current session, or the loss of the broker connection, sets every variable of the device to ConnectionLost and the device to Offline. An NDEATH of an older session is ignored. A DDEATH sets the variables of that Sparkplug device to ConnectionLost.
• After every connect, the client asks every enabled edge node for a Rebirth (NCMD Node Control/Rebirth). With Sparkplug Host ID set, it waits 2 seconds first, because edge nodes that use this client as primary host publish their birth certificates by themselves.
• A missing sequence number that stays open longer than Sparkplug Reorder Timeout, data from an edge node without a birth certificate in the current session, and an unknown alias each lead to a Rebirth request, at most one per edge node every 5 seconds.
• A Sparkplug template instance is read as its members, named <instance>/<member>. Arrays are shown as text in JSON array notation, and DateTime metrics as ISO 8601 text in UTC.
• A configured metric that is missing from the birth certificate sets its variable to ConnectionLost and is logged in the System Log.

Values are written to the variables with the time stamp of the metric, after the Scaling and the Converter of the variable. The data types of Sparkplug B are shown as follows; Browse sets the matching Data Type when it adds a variable:

The Quality property of a metric sets the status of the variable. A metric without the property is Good. A null value sets the status Unknown, or the status of its quality when that is not GOOD.

Writes. A write to a variable of a Sparkplug B device, from a page, an action, a script, or the API, is sent to the edge node as an NCMD command for an edge node metric or a DCMD command for a device metric, with the alias and the data type of the birth certificate. A write is refused and logged while the edge node or the Sparkplug device has no birth certificate in the current session. A metric that is not in the birth certificate, for example Device Control/Rebirth, is sent by name with the Data Type of the variable. Commands are not queued, so a write is never applied late.

Sparkplug Host ID. When Sparkplug Host ID is set on the client, the client is a Sparkplug Primary Host Application. Edge nodes that name it as their Primary Host ID publish their birth certificates when the client reports online, and end their session when the client stops. A change of the client, its devices, or its variables restarts the client, so these edge nodes publish their birth certificates again.

Redundancy. MQTT clients run on the primary node only. On a failover, the new primary node connects, publishes the STATE online when Sparkplug Host ID is set, and asks every edge node for a Rebirth. Both nodes need the same time base (NTP), because edge nodes compare the time stamps of the STATE messages.

Browse Sparkplug Metrics

On a device with Protocol Sparkplug B, the Browse button of the MQTT Variables page opens the Browse Sparkplug Metrics dialog. It shows the Group ID, the Edge Node ID, and whether the edge node is Online, and lists the metrics of the last birth certificates of the edge node with Device ID, Metric Name, Data Type, and Value. Metrics that are already configured on the device are marked Configured. Before the first birth certificate, the list is empty; press Request Rebirth to ask the edge node for its birth certificates. The list is loaded again after 1.5 seconds.

Select metrics and press Add Selected to create one variable per metric. The variable name is the metric name with every slash replaced by a dot and every other character that a variable name cannot contain replaced by an underscore. With Start names with {Device}. ticked, the name starts with the {Device} replacer. The Data Type follows the table in Sparkplug B Devices. Metrics whose name cannot be used are skipped, and the dialog shows how many variables were added and skipped.

Supported Data Types

The Data Type field determines how the MQTT payload value is interpreted.

Notes

The channel state indicator on each client and device row shows the current connection status. For a Sparkplug B device, the channel state is Online while the edge node has a birth certificate in the current session, and Offline after its death certificate or while the client is disconnected.

A variable can have a Publish Topic, a Subscribe Topic, or both. When a Subscribe Topic is set, the variable value is updated whenever a message arrives on that topic. When a Publish Topic is set, the variable value is sent to that topic whenever it changes.

When Identity In Message is enabled, the published JSON payload includes a device and variable identifier alongside the value. Use Timestamp Key and Value Key to control the exact JSON field names when the receiving system requires a specific message schema.

Variables are referenced at runtime using the format DeviceName.VariableName, for example Sensor1.Temperature.