UNS Basics

Review the Inductive Automation article UNS: Unified Namespace for a comprehensive overview of what a UNS is and how it works.

Sparkplug Basics

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:

{         
  "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:

{         
  "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
} 

UNS Architecture

MQTT Engine

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.

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: 

• SparkplugGroupId
• SparkplugEdgeNodeId
• SparkplugDeviceId

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.

Managing UDTs

Colliding Tag Paths

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 will at Error level when parsing a tag name that is already associated with a different Sparkplug Descriptor. 

MQTT Transmission UNS Transmitter

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.

ADD IMAGE OF UNS TRANSMITTER

There are two types of messages published - UNS Data and UNS Properties 

• UNS Data Message
  • Published when QualifiedValue of the tag changes 
  • Topic
    • Ignition tag path starting at the Tag Path defined in the transmitter
    • Example: Vancouver/Area1/Line1/Zone1/Asset1/T1

• • Payload
    • JSON formatted payload containing tag name, dataType, value, timestamp and qualityCode
    • Example: {"name":"Vancouver/Area1/Line1/Zone1/Asset1/T1","dataType":"Int32","value":120,"timestamp":1727215043878,"qualityCode":192}

• UNS Properties Message
  • Published on initial client connection
  • Topic
    • Ignition tag path starting at the Tag Path defined in the transmitter extended by .props
    • Example: Vancouver/Area1/Line1/Zone1/Asset1/T1.props
  • Payload
    • JSON formatted payload containing property values, such as engHigh, engLow, if hey have been changed from the Ignition default or if they are custom properties. 
    • Example: {"SparkplugEdgeNodeId":{"type":"String","value":"E1"},"SparkplugGroupId":{"type":"String","value":"G1"},"enabled":{"type":"Boolean","value":true},"SparkplugDeviceId":{"type":"String","value":"D1"}}

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","dataType":"Int32","value":5,"timestamp":1727217522441,"qualityCode":192}

CONVERT UDTS = FALSE

Topic: Vancouver/Area1/Line1/Zone1/Asset1/Instance1.props

Payload: {"SparkplugEdgeNodeId":{"type":"String","value":"E1"},"SparkplugGroupId":{"type":"String","value":"G1"},"SparkplugDeviceId":{"type":"String","value":"D1"}}

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}