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

Anchor
unstransmitter unstransmitter

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.

The UNS Transmitter will use the namespace unsAv1.0

The UNS Transmitter is an agent within MQTT Transmission that monitor tags, converts them to MQTT messages, and publish them to an MQTT Server. Each transmitter is configured with a server Set and will attempt to maintain an MQTT client connection with one server in that Set at all times.

The configuration sections available are Tag Settings, Publish Settings, History Settings and Advanced Settings.

Anchor
unstagsettings unstagsettings

UNS Transmitters - Tag Settings

• Name
  • Unique name for the UNS Transmitter
• Enabled
  • Checkbox to enable/disable the UNS Transmitter. Selected by default.
• Tag Provider
  
  • The name of the tag provider that Transmission will monitor.
• Tag Path
  • Optional path to the root folder where the tag tree starts.
  • Transmitters also support a multi-tag path configuration. Reference the Transmitters with Multi-Tag Paths tutorial for configuration assistance.
• Set
  • The Set that the UNS Transmitter client will connect to.
• Discovery Delay
  • An optional startup delay, in milliseconds, to wait before scanning for Tags to monitor. This is useful when Tags are dynamically created on initial startup, as is the case when using the MQTT Engine module.

Anchor
unspublishsettings unspublishsettings

UNS Transmitters - Publish Settings

• Properties QoS
  • The MQTT Quality of Service to use for 'properties' messages
• Properties Retain
  • Whether or not to set the MQTT retain flag to true for 'properties' messages
• Data QoS
  • The MQTT Quality of Service to use for 'data' messages
• Data Retain
  • Whether or not to set the MQTT retain flag to true for 'data' messages

Anchor
unshistorysettings unshistorysettings

UNS Transmitters - History Settings

• History Store
  • The MQTT Transmission History Store to use with the UNS Transmitter.
• Enable History Storage by Default
  • Checkbox to enable/disable store and forward for all tags. Selected by default. 
  • Store and forward controls whether or not a tag is stored in the configured History Store when Transmission is offline. To override the global setting, individual tags will require a custom tag property 'StoreAndForward' (type: boolean) to be created and set to the reverse state of the global setting.

Anchor
unsadvancedsettings unsadvancedsettings

UNS Transmitters - Advanced Settings

• Filtered Properties
  • A semicolon delimited list of Tag properties to filter/block from being published

  • By default the filtered properties list contains: 

    accessRights;clampMode;deadband;deadbandMode;formatString;historicalDeadband;historicalDeadbandMode;historicalDeadbandStyle;historyEnabled;historyMaxAge;historyMaxAgeUnits;historyProvider;historySampleRate;historySampleRateUnits;historyTagGroup;historyTimeDeadband;historyTimeDeadbandUnits;opcItemPath;opcServer;permissionModel;rawHigh;rawLow;sampleMode;scaleFactor;scaleMode;scaledHigh;scaledLow;tagGroup;valueSource;expression;expressionType;ConfiguredTagPath;eventScripts;readPermissions;writePermissions;eventScripts;parentEnabled;sourceTagPath

    
    

  • Tag properties are only published if different from the default Ignition tag property settings.

UNS Messages

UNS Data Message

A UNS Data Message is published when QualifiedValue of the tag changes 

• Topic
  • Ignition tag path starting at the Tag Path defined in the transmitterExample: unsAv1.0/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

A UNS Properties Message is published on initial client connection and on a refresh of the UNS Transmitter Edge Node

• Topic
  • Ignition tag path starting at the Tag Path defined in the transmitter extended by .props
  • Example: unsAv1.0/Vancouver/Area1/Line1/Zone1/Asset1/T1.props
• Payload
  • JSON formatted payload containing non default or custom property values 
  • Example: {"SparkplugEdgeNodeId":{"type":"String","value":"E1"},"SparkplugGroupId":{"type":"String","value":"G1"},"enabled":{"type":"Boolean","value":true},"SparkplugDeviceId":{"type":"String","value":"D1"}}

UNS Custom Messages

bdSeq

A bdSeq data and property message is published on initial client connection and on a refresh of the UNS Transmitter Edge Node. The 'value' metric in the data message is incremented on each connection

• Data message
  • Topic
    • unsAv1.0/bdSeq
  • Payload

    • Example: {"name": "bdSeq","dataType": "Int64","value": 207,"timestamp": 1730404992994,"qualityCode": 192}

• Property message
  • Topic
    • unsAv1.0/bdSeq.prop
  • Payload
    • null