Abstract

This page describes how Cloud Injector Agent configurations interact with Ignition tag trees to push messages and tag change events to the cloud service. It explains how tags get identified to be pushed as well as what specific 'topics' will be included with the messages. It also goes over some example configurations to show how the system will behave in different scenarios.

Sparkplug Overview

Cloud Injectors utilize concepts of the Sparkplug Specification for MQTT. The Cloud Injector modules are designed to pick up tags in Ignition or Ignition Edge and publish those tags, parts of their configuration, and tag change events to an MQTT Server. These tags are push to the Cloud Service based on a combination of a 'Agent' configuration as well as the arrangement of tags in the Ignition tag tree.

It is important to note that the configuration of the 'agents' in conjunction with the tag tree determines some of the data used in pushing the messages to the cloud service. The 'topics' are meant to be used as the addresses of the different components in the distributed system. It is important to note with the various cloud services that these topics are not really MQTT topics. Instead, they are included in the message as part of the JSON document. But, they are conceptually used in the same way as they are in the Sparkplug Specification. For the remainder of this document, the 'topic' will refer to a portion of the JSON document that is pushed to the cloud service and not an actually MQTT topic. Note this really only applies to the Cloud Injector modules and not the MQTT modules such as MQTT Transmission and MQTT Engine. In the topics per the Sparkplug specification, there are three important identifiers to note. These are shown below.

Sparkplug Identifiers
  • The 'Group ID' is meant to represent a logical grouping of Edge Nodes. This can be a region, a facility name, or any meaningful grouping of Edge Nodes within your application.
  • The 'Edge Node ID' is the ID of the logical Edge Node. This is often the name that represents the component which is aggregating data from various Sparkplug Devices.
  • The 'Device ID' is the ID of a device attached to the Ignition instance. This can be a PLC or logical grouping of tags the represent a physical or logical device connected to Ignition.

These identifiers then become components of the MQTT topics. There is also a 'verb' in Sparkplug messages which denotes whether the message is a birth certificate, death certificate, data message, command message, etc. Sparkplug topics are of the following form using all of these different parameters.

  • spBv1.0/GROUP_ID/VERB/EDGE_NODE_ID/DEVICE_ID

It is also important to note that the combination of any GROUP_ID and EDGE_NODE_ID must be unique within the distributed system. Because these are used as 'addresses' in the system you should never have two that conflict with each other. It is a bit like having two houses with the same postal address. It isn't possible for other MQTT clients in the system to tell where messages are coming from and when sending messages to them they will both receive the messages. This is why the combination of these two identifiers must be unique. For example, you can have two or more Edge Nodes with the same GROUP_ID as long as each EDGE_NODE_ID is unique.

Tag Agents and Tag Trees

Tag Agents define what tags will be picked up in the Ignition tag tree and pushed to the defined cloud service. Tag Agents are very similar to MQTT Transmission 'Transmitters' in terms of how they interact with the Ignition Tag Tree. The 'Tag Provider' and 'Tag Path' configuration options define where in the Ignition Tag Tree the Agent will look for tags. There are also configuration options for the Sparkplug Group, Edge Node, and Device ID.

The Agent scans or discovers folders based on the different combinations of potential Sparkplug Settings.

  • If all three IDs are left blank the Agent will assume the following folder structures follow the Tag Path:
    • <groupFolder>/<edgeNodeFolder>/<deviceFolder>/<tags>
    • <groupFolder>/<edgeNodeFolder>/<tags>
  • If only the Group ID is specified the Agent will assume the following folder structure follows the Tag Path:
    • <edgeNodeFolder>/<deviceFolder>/<tags>
    • <edgeNodeFolder>/<tags>
  • If the Group ID and the Edge Node ID are specified the Agent will assume the following folder structure follows the Tag Path:
    • <deviceFolder>/<tags>
    • <tags>
  • If the Group ID, Edge Node ID, and the Device ID are specified the Agent will assume the following folder structure follows the Tag Path:
    • <tags>

Consider the following Custom Transmitter configuration.



With this Tag Agent configuration and tag tree we end up with the following Sparkplug IDs.

  • Group ID=G1 and Edge Node ID=E1 with two Devices with Device ID=D1 and Device ID=D2

Note because there was no Device ID specified in the Tag Agent configuration so the Device IDs get picked up from the tag tree.

Consider another example:

Now consider this tag tree:

With this Tag Agent configuration and tag tree we end up with the following Sparkplug IDs (which are the same from the previous example).

  • Group ID=G1 and Edge Node ID=E1 with two Devices with Device ID=D1 and Device ID=D2

As shown here, if the Sparkplug IDs are not specified in the Tag Agent configuration, the first level folders in the tag tree will become the Sparkplug IDs.



Additional Resources

  • No labels

New to MQTT? Start Here!