Tags Reference Tables
Overview
MQTT Engine automatically creates a known set folders containing tags for Engine Control and Engine Info. For each connected Edge Node, a Node Control and Node Info folder containing tags is created along with a Device Info folder for each connected device. The tables below describe these tags.
Node Control
The tags in each Node Control folder are created based on a supplied metric within the NBIRTH message from the Edge Node. These will only appear if the Edge Node implementation supports them. It is up to the Edge Node implementation (MQTT Transmission for example) to support any functionality it supplies via the NBIRTH. If the Edge Node does not support the specific control, it should not include it in the NBIRTH payload.
| Tag | Data Type | Description |
|---|---|---|
| Delete UNS Tags | Boolean | Writeable tag to delete all UNS namespace tags associated with this Sparkplug Edge Node. Tag is set to read-only by default |
| Next Server | Boolean | Writeable tag to request the Edge Node to walk to the next MQTT server |
| Rebirth | Boolean | Writeable tag to request the Edge Node to resend its cached NBIRTH and DBIRTH messages without disconnecting or sending DEATH messages first. This means a that the new BIRTH will only contain the same metrics/tags that were in the original BIRTH message. |
Node Info
General information tags with respect to Sparkplug Edge Nodes. These are created, managed and updated by Engine based on messages arriving from each given Edge Node.
| Tag | Data Type | Description |
|---|---|---|
| bdSeq | Long | The last bdSeq number sent by the Edge Node in an NBIRTH message |
| Birth Count | Long | The number of NBIRTH messages since the last time the info metrics were reset via the Node Info/Reset Info tag |
| Current Server | String | The current MQTT Server the Edge Node is connected to |
| Data Latency (ms) | Long | The time in milliseconds between MQTT Engine receiving of the last message and the payload's reported time. Note: For this to be very accurate the edge node's clock and the system clock running MQTT Engine should be synced |
| Death Count | Long | The number of NDEATH messages since the last time the info metrics were reset via the Node Info/Reset Info tag |
| Message Schema | String | The schema associated with the Edge Node (e.g. Sparkplug B) |
| Offline DateTime | DateTime | The time at which the last NDEATH message was received by MQTT Engine |
| Online | Boolean | Whether or not the Edge Node is online. This is determined by whether the last lifecycle message was an NBIRTH or NDEATH |
| Online DateTime | DateTime | The time at which the last NBIRTH message was received by MQTT Engine |
| Rebirth (Last) Cause | String | The reason for the last rebirth request to be issued for this Edge Node by MQTT Engine (added 4.0.22) |
| Rebirth (Last) DateTime | DateTime | The time at which the last rebirth was issued for this Edge Node by MQTT Engine (added 4.0.22) |
| Rebirth Count | Integer | The count of rebirth requests issued for this Edge Node by MQTT Engine (added 4.0.22) |
| Reset Info | Boolean | Writable tag to 'reset' the Node Info metrics |
| seq | Long | The last Sparkplug seq number received from the Edge Node |
| Total Bytes Recvd (bytes) | Long | The number of bytes received from the Edge Node since the last time the info metrics were reset via the Node Info/Reset Info tag |
| Total Bytes Xmit (bytes) | Long | The number of bytes sent to the Edge Node since the last time the info metrics were reset via the Node Info/Reset Info tag |
| Transmission Version | String | The version of MQTT Transmission installed at the Edge Node |
Device Control
Device Control tags are created from control metrics included in an Edge Node's DBIRTH message. These tags are only available if the Edge Node implementation (such as MQTT Transmission) supports the associated control functionality. If a control is not supported, the corresponding metric should not be included in the DBIRTH payload.
| Tag | Data Type | Description |
|---|---|---|
| Delete UNS Tags | Boolean | Writeable tag to delete all UNS namespace tags associated with this Sparkplug Device. Tag is set to read-only by default |
| Rebirth | Boolean | Writeable tag to request the Edge Node to resend its cached DBIRTH message for the specific Device without disconnecting or sending DEATH messages first. This means a that the new BIRTH will only contain the same metrics/tags that were in the original BIRTH message. |
Note: Block Device Commands must be disabled in order the DCMD to be published by Engine
Device Info
General information tags with respect to Sparkplug Devices. These are created, managed and updated by Engine based on messages arriving from each given device.
| Tag | Data Type | Description |
|---|---|---|
| Birth Count | Long | The number of DBIRTH messages since the last time the info metrics were reset via the Device Info/Reset Info tag |
| Data Message Count | Long | The number of DDATA messages since the last time the info metrics were reset via the Device Info/Reset Info tag |
| Death Count | Long | The number of DDEATH messages since the last time the info metrics were reset via the Device Info/Reset Info tag |
| Last Command Size (bytes) | Long | The size in bytes of the last DCMD that was sent from MQTT Engine |
| Last Data Message Size (bytes) | Long | The size in bytes of the last DDATA that was received from the Device |
| Offline DateTime | DateTime | The time at which the last DDEATH message was received by MQTT Engine |
| Online | Boolean | Whether or not the Device is online. This is determined by whether the last lifecycle message was an DBIRTH or NBIRTH |
| Online DateTime | DateTime | The time at which the last DBIRTH message was received by MQTT Engine |
| Reset Info | Boolean | Writable tag to 'reset' the Device Info metrics |
Engine Control
Primary Host Control
These tags give control over the configuration of the Primary Host ID for Engine.
| Tag | Data Type | Description |
|---|---|---|
| Enabled | Boolean | Writable tag to control whether or not the Primary Host is enabled for MQTT Engine |
| ID | String | Writable tag to set the Primary Host ID defined for MQTT Engine |
Processing Queue Control
These tags give control over the queued messages.
| Tag | Data Type | Description |
|---|---|---|
| Clear Queue | Boolean | Writable tag to control whether or not to clear the queue (added 4.0.31) |
| Edge Node Descriptor | String | Writable tag to set the Edge Node Descriptor for the queue to be cleared (added 4.0.31). Format is GroupId/EdgeNodeId as displayed in the Queued Messages dataset tag. |
| Smart Clear | Boolean | Writeable tag to determine method of clearing the queue when the Clear Queue tag is enabled. Set to True by default (added 4.0.31). If set to True, the last Birth message in the queue will be found and only messages in the queue that are before the Birth message will be cleared. If set to False, all messages in the queue will be cleared. |
Engine Info
These tags provide information about MQTT Engine, as well as its Devices, Edge Nodes, Latches, and the Client.
| Tag | Data Type | Description |
|---|---|---|
| Enable Tag Tracking | Boolean | Writable tag to control whether or not to update Tags Per Seconds (added 4.0.17) |
| Queued Messages | Dataset | A dataset showing the current message count for each message queue comprising: MQTT Server (String) - Sparkplug descriptors in the format GroupId/EdgeNodeId (String) - Queued Messages count (Integer) |
| Queued Messages Total | Integer | The count of all current queued messages |
| Rebirth (Last) Cause | String | The reason for the last rebirth request to be issued by MQTT Engine (added 4.0.22) |
| Rebirth (Last) DateTime | DateTime | The time at which the last rebirth was issued by MQTT Engine (added 4.0.22) |
| Rebirth (Last) Node | String | The Sparkplug EdgeNode ID for which the last rebirth was issued by MQTT Engine (added 4.0.22) |
| Rebirth Count | Integer | The count of rebirth requests issued by MQTT Engine (added 4.0.22) |
| Redundancy Role | String | The redundancy configuration of the Ignition system that MQTT engine is installed on. Options are Independent, Master and Backup |
| Redundancy State | String | The redundancy status of the Ignition system that MQTT engine is installed on. Options are Active or Cold |
| Reordered Mesg Count | Integer | The number of messages that have been reordered by MQTT Engine (added 4.0.22) |
| Reordered Mesg Reset | Boolean | Writable tag to reset the Reordered Mesg Count metric (added 4.0.22) |
| System-Wide Reset Info | Boolean | Writeable tag to 'reset' all Engine metrics |
| Tag Count | Long | The sum of tags included in the last NBIRTH and DBIRTH messages received from each Edge Node. When an LWT is received form the Edge Node, the tag count for that Edge Node is set to 0 and repopulated on connect when the next BIRTH messages are received (added 4.0.17) |
| Tags Per Second | Long | The number of tags changes received per second with the value updated every two seconds (added 4.0.17) |
| Total Bytes Recvd (bytes) | Integer | The number of bytes received by Engine since the last time the info metrics were reset via the System-Wide Reset Info tag |
| Total Bytes Xmit (bytes) | Integer | The number of bytes sent from Engine since the last time the info metrics were reset via the System-Wide Reset Info tag |
| Total Data Mesg Count | Integer | The number of messages received by Engine since the last time the info metrics were reset via the System-Wide Reset Info tag |
| Version | String | The version MQTT Engine currently installed |
Devices Folder
The Devices folder tags provide information on the connected devices.
| Tag | Data Type | Description |
|---|---|---|
| DeviceCount | Integer | The number of Sparkplug edge devices as determined by the received DBIRTH messages |
| DevicesOffline | Integer | The number of Sparkplug edge devices that are offline. This is determined by whether the last lifecycle message was an DBIRTH or DDEATH |
| DevicesOnline | Integer | The number of Sparkplug edge devices that are online. This is determined by whether the last lifecycle message was an DBIRTH or DDEATH |
Edge Nodes Folder
The Edge Nodes folder tags provide information on the connected Edge Nodes.
| Tag | Data Type | Description |
|---|---|---|
| Last Node to Connect | String | The Sparkplug ID of the last node to connect |
| Last Node To Disconnect | String | The Sparkplug ID of the last node to disconnect |
| NodesOffline | Integer | The number of Sparkplug Edge Nodes offline. This is determined by whether the last lifecycle message was an NBIRTH or NDEATH |
| NodesOnline | Integer | The number of Sparkplug Edge Nodes online. This is determined by whether the last lifecycle message was an NBIRTH or NDEATH |
| NodeUnitCount | Integer | The total number of Sparkplug Edge Nodes as determined by the received NBIRTH messages |
| Offline Nodes | Dataset | A dataset containing the Sparkplug ID and timestamp for all offline Sparkplug edge nodes |
| Online Nodes | Dataset | A dataset containing the Sparkplug ID and timestamp for all online Sparkplug edge nodes |
Latches Folder
The Latches folder tags provide a tag path to any configured tag latches in the MQTT Engine configuration.
| Tag | Data Type | Description |
|---|---|---|
| TagName as defined in the MQTT Engine configuration | Boolean | Writeable tag to 'reset' the tag latch |
For more information on tag latches, see the Tag Latches documentation.
MQTT Clients Folder
| Tag | Data Type | Description |
|---|---|---|
| Latency Check Period (ms) | Integer | Frequency in milliseconds that the message latency for each MQTT Client is checked if the Enable Latency Check is checked |
For each configured MQTT Engine Set, the following tags are available for each identified MQTT Client:**
| Name | Data Type | Description |
|---|---|---|
| Connected Nodes | Integer | Number of currently connected Sparkplug Edge Nodes to this MQTT Client |
| Enable Latency Check | Integer | Writable tag to enabled message latency checking for each MQTT Client |
| Message Processing Latency (ms) | Integer | The amount of time to process the last Sparkplug message |
| Messages Per Second | Integer | The number of MQTT messages received by Engine per second |
| MQTT Client ID | String | The Client ID for the MQTT Client |
| Offline DateTime | DateTime | The last time at which the MQTT Client successfully disconnected from the MQTT Server |
| Online | Boolean | A read-only tag showing the connection status of the MQTT Client |
| Online DateTime | DateTime | The last time at which the MQTT Client successfully connected to the MQTT Server |
| Server Latency (ms) | Integer | The amount of time that it takes for a test MQTT message to be sent and received back by MQTT Engine |
| Target Server URL | String | The URL of the target MQTT Server to connect to |
For each identified MQTT Client, the following folders and tags are available:
| Name | Description |
|---|---|
| Primary Host State/PrimaryHostName | Folder named as the Primary Host ID configured in MQTT Engine |
- Payload: String - Status of the Primary Host. Options are:
Primary Host Online: {"online":true,"timestamp":1681780081657}/Primary Host Offline: {"online":false,"timestamp":1681780081660}, where the timestamp is the time of the last status change in milliseconds - Retain: Boolean - Retain status of the LWT message for the Primary Host | | Legacy Primary Host State/PrimaryHostName | Folder named as the Primary Host ID configured in MQTT Engine if Enable Legacy State messages is True under the Severs > Legacy State configuration
- Payload: String - Status of the Legacy Primary Host. Options are
OFFLINEorONLINE - Retain: Boolean - Retain status of the LWT message for the Legacy Primary Host |