You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 28 Next »

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



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
} 
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.

UNS Architecture


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 will have no subscriptions

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.

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: 

  • SparkplugGroupId
  • SparkplugEdgeNodeId
  • SparkplugDeviceId


Edge

MQTT Engine

MQTT Engine


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:


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.

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






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. 



MQTT Transmission UNS Transmitter


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.

The UNS Transmitter will use the namespace unsAv1.0

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:

  • Convert UDTs
  • Device level UDTs as Devices

  • Publish UDT Definitions

  • Optimize UDTs

  • In-Order History

    • This will always be true for the UNS Transmitter
  • Include Sparkplug DataTypes

    • This will always be true for the 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: 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
    • 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"}}




  • No labels