Contents
Cirrus Link Resources
Cirrus Link Website
Contact Us (Sales/Support)
Forum
Cirrus Link Modules Docs for Ignition 7.9.x
Inductive Resources
Ignition User Manual
Knowledge Base Articles
Inductive University
Forum
Warning |
---|
The UNS Transmitter is available in the nightly module build. The nightly module versions are always based on the last official release plus all features and bug fixes that have been made on top of the last official release but do not undergo the full suite of testing and should generally not be used in production environments. There are known issues with the UNS Transmitter and it is a work in progress until official release |
Table of Contents |
---|
Review the Inductive Automation article UNS: Unified Namespace for a comprehensive overview of what a UNS is and how it works.
Sparkplug defines a standard format for MQTT message topic paths of:
spBv1.0/group_id/Message Type/edge_node_id/device_id
Sparkplug defines a standard format for MQTT message payloads of:
Code Block |
---|
{ "timestamp": <timestamp>, "metrics": [{ "name": <metric_name>, "alias": <alias>, "timestamp": <timestamp>, "dataType": <datatype>, "value": <value> }], "seq": <sequence_number> } |
where the ‘name’ of a metric can be hierarchical to build out proper folder structures for applications consuming the metric values.
For example, a simple Sparkplug™ B payload with a two metrics can be represented in JSON as follows:
Code Block |
---|
{ "timestamp": 1486144502122, "metrics": [{ "name": "Metric1", "alias": 1, "timestamp": 1479123452194, "dataType": "String", "value": "Test" }, { "name": "Metric Level 1/Metric Level 2/Metric2", "alias": 2, "timestamp": 1479123452056, "dataType": "String", "value": "Test" }], "seq": 2 } |
Tip | ||
---|---|---|
| ||
Using the hierarchical functionality of the metric name, in conjunction with the group_id, edge_node_id and device_id already defined in the Topic Namespace, allows consuming Sparkplug applications to organize metrics in the same hierarchical fashion to construct the Unified NameSpace whilst taking advantage of the benefits afforded by using Sparkplug. |
Note |
---|
The directional arrows in the image represent data flow. Data can be published from the UNS Transmitter to Enterprise Consuming Clients but the UNS Transmitter MQTT Client has will have no subscriptions |
From release 4.0.23, MQTT Engine now has the option to consume incoming Sparkplug messages and organize metrics in the same hierarchical fashion to construct the Unified NameSpace.
Configuration is set in the Sparkplug B namespace under MQTT Engine > Namespaces > Sparkplug B > Default > General as shown below:
Let's take a look at a an example of how a UNS can be created at MQTT Engine from Edge Node tags published by MQTT Transmission.
Tip | ||
---|---|---|
| ||
Review the MQTT Transmission Transmitters and Tag Trees to gain an understanding of how MQTT Transmission Transmitter configurations interact with Ignition tag trees to publish Sparkplug messages and the immense flexibility that can be realized. |
We have configured an MQTT Transmission Transmitter to use the Ignition tag tree in the default tag provider at the Edge to construct the Sparkplug Device Descriptor (group_id, edge_id and device_id) starting at the folder level below Edge Nodes.
For the Ignition tag tree below, the topic and payload for a change to tag T1 will be:
Topic: spBv1.0/G1/DDATA/E1/D1
SparkplugBPayload: [timestamp=1726851053618, metrics=[Metric [name=Vancouver/Area1/Line1/Zone1/Asset1/T1, alias=null, timestamp=1726851052615, dataType=Int32, isHistorical=null, isTransient=null, metaData=null, properties=PropertySet [propertyMap={}], value=10, isNull=false]], seq=3, uuid=null, body=null]
At MQTT Engine, the metric name is parsed and the tag structure created under the configured UNS folder name.
The tag has three additional properties which identify the Sparkplug Descriptor associated with this tag:
Edge
MQTT Engine
MQTT Engine
Tip |
---|
The Sparkplug Descriptor properties, SparkplugDeviceId, SparkplugEdgeNodeId and SparkplugGroupID, for UDT Instance tags are inherited from the parent UDT Instance and can be viewed in the tag editor for the UDT Instance: |
Warning |
---|
Currently it is possible to manually edit the Sparkplug Descriptor properties for a UNS tag at MQTT Engine. The edits will hold until a BIRTH message is received from the Edge Node. These tags are not used internally by MQTT Engine and the tag will remain associated with the original Sparkplug Descriptor. For example if the SparkplugDeviceId associated with Vancouver/Area1/Line1/Zone1/Asset1/T1 is changed to D17, new data coming in from spBv1.0/G1/DDATA/E1/D1 for metric Vancouver/Area1/Line1/Zone1/Asset1/T1 will still be written to the tag. However, these tag properties are used by UNS Transmitter to create the .props message associated with the tag. Any refresh of the edge node at the UNS Transmitter will result in a .props message being published with the edited Sparkplug Descriptor properties. |
In addition to creating the UNS folder, 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. See the Engine Tags documentation for details on each of these tags.
Under the Device Control and Node Control folders there is a "Delete UNS Tags" tag. This tag makes it simple to delete the tags for the respective Edge Node or Device without having to parse through the UNS tag tree to find the associated tags.
Note |
---|
The security on this tag is set to Read Only = True and will need to be updated to Read Only = False before the boolean can be written to. |
MQTT Engine
A requirement of a UNS is that each tag can only be reference from a single source ie. the same tag path cannot be published from two edge nodes.
To help identify colliding UNS tag, the SparkplugNPayloadHandler SparkplugBPayloadHandler will at Error level when parsing a tag name that is already associated with a different Sparkplug Descriptor.
Anchor | ||||
---|---|---|---|---|
|
Warning |
---|
The UNS Transmitter is available in the nightly module build. The nightly module versions are always based on the last official release plus all features and bug fixes that have been made on top of the last official release but do not undergo the full suite of testing and should generally not be used in production environments. There are known issues with the UNS Transmitter and it is a work in progress until official release |
Once the UNS structure has been created at MQTT Engine, a UNS Transmitter can be configured to publish tag changes over MQTT to any Enterprise consuming clients.
Note |
---|
The UNS Transmitter MQTT Client has no subscriptions |
The UNS Transmitter comprises similar properties as the Sparkplug Transmitter with the addition of Publish Settings:
and the removal of the following properties:
Device level UDTs as Devices
Publish UDT Definitions
Optimize UDTs
In-Order History
Include Sparkplug DataTypes
There are two types of messages published - UNS Data and UNS Properties
FORMAT OF UDT MESSAGE
COVERT UDTS = TRUE
Topic: Vancouver/Area1/Line1/Zone1/Asset1/Instance1/TestTag1.props
Payload: {Topic: Vancouver/Area1/Line1/Zone1/Asset1/Instance1/TestTag1
Payload: {"name":"Vancouver/Area1/Line1/Zone1/Asset1/Instance1/TestTag1"CONVERT UDTS = FALSE
Topic: Vancouver/Area1/Line1/Zone1/Asset1/Instance1.props
Payload: {"SparkplugEdgeNodeId":{"type":"String","value":"E1"},"SparkplugGroupId":{"type":"String","value":"G1"},"Topic: Vancouver/Area1/Line1/Zone1/Asset1/Instance1
On initial connection:
Payload: {"name":"Vancouver/Area1/Line1/Zone1/Asset1/Instance1","dataType":"Template","value":{"reference":"MyTestUDT","isDefinition":false,"metrics":[{"name":"TestTag2","timestamp":1727217701946,"dataType":"Int32","isHistorical":false,"isTransient":false,"metaData":{},"value":2},{"name":"TestTag1","timestamp":1727217701946,"dataType":"Int32","isHistorical":false,"isTransient":false,"metaData":{},"value":5}],"parameters":[{"name":"Parameter 1","type":"Int64","value":5},{"name":"Parameter 2","type":"String","value":"Testing"},{"name":"Parameter 3","type":"Double","value":0.01}]},"timestamp":1727217740028,"qualityCode":192}
On UDT tag change:
Payload: {"name":"Vancouver/Area1/Line1/Zone1/Asset1/Instance1","dataType":"Template","value":{"reference":"MyTestUDT","isDefinition":false,"metrics":[{"name":"TestTag1","timestamp":1727217819069,"dataType":"Int32","value":6}]},"timestamp":1727217819069,"qualityCode":192