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.

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.