Versions Compared

Old Version 1

changes.mady.by.user Gill Houghton

Saved on

compared with

New Version 2

changes.mady.by.user Gill Houghton

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

MQTT Engine is designed to consume Sparkplug messages and create Ignition tags in the MQTT Engine tag provider.

The topic and payload of the Sparkplug message are parsed in different ways to create the Default Tag or UNS Tag folder hierarchy in the MQTT Engine tag provider.

Quick overview of Sparkplug message format

A Cirrus Link Sparkplug message comprises two parts: the topic and the payload.

Topic

The topic is published in the format:

  • spBv1.0/[GroupID]/[Verb]/[EdgeNodeID]/[DeviceID]

Payload

Payload in the format:

  • timestamp
  • metrics
    • name - the tag folder hierarchy not used in the topic namespace
    • alias - numeric value representing the metric when aliasing is used
    • timestamp - timestamp associated with the last metric change event
    • dataType - DataType associated with the metric
    • isHistorical - set to True to denote the metric represents a historical value
    • isTransient - set to null
    • metaData - used for file transfers and custom decoding information for the metric
    • properties - used for Ignition tag properties. See the Ignition Tag Properties reference for all available properties
    • value - value associated with the metric
    • isNull - flag denoting the metric has a null value
    • seq The message sequence number used to ensure that messages are processed in the correct order


    Default Tags

    When configured to create Default Tags, MQTT Engine will parse the topic and payload to create tags under the 'Edge Nodes' folder in the MQTT Engine tag provider.

    The metric name in the payload is used for the tag name prefixed by the Sparkplug Descriptors from the message topic resulting in a tag path of:

    • [MQTT Engine]Edge Nodes/GroupID/EdgeNodeID/DeviceID/MetricName

    For example the message below:

    • Topic: spBv1.0/Site 1/DDATA/Area 1/Line 1
    • Payload: {"timestamp":1643823757750,"metrics":[{"name":"Conveyer/Batch/Quantity","timestamp":1643823756467,"dataType":"Double","value":33.02}],"seq":23}

    creates an MQTT Engine tag:

    • [MQTT Engine]Edge Nodes/Site 1/Area 1/Line 1/Conveyer/Batch/Quantity


    Note

    If using MQTT Transmission to publish the message and have configured the Transmitter to dynamically pickup the Sparkplug Descriptors, the metric names used in the payload will be the remainder of the tag folder hierarchy not used in the topic namespace.

    Prefixing the Sparkplug Descriptors in the topic to the metric name in the payload results in unique tag folder hierarchy's at MQTT Engine  


    UNS Tags

    When configured to create UNS Tags, MQTT Engine will obfuscate the Sparkplug Descriptors used in the topic and only parse the metric name included in the payload to create the tag structure under the configured UNS Folder prefix

    . 

    .

    It is a requirement of a UNS is that each tag can only be referenced from a single source ie. the same tag path cannot be published from two edge nodes.

    For example the message below:

    • Topic: spBv1.0/Site 1/DDATA/Area 1/Line 1
    • Payload: {"timestamp":1643823757750,"metrics":[{"name":"Conveyer/Batch/Quantity","timestamp":1643823756467,"dataType":"Double","value":33.02}],"seq":23}

    creates an MQTT Engine tag:

    • [MQTT Engine]UNS/Conveyer/Batch/Quantity
      • Custom with custom properties of
        • SparkplugDeviceId - Line1
        • SparkplugEdgeNodeId - Area 1
        • SparkplugGroupId - Site 1


    Warning

    If MQTT Engine receives a second message payload with a metric name it has already created, it will not create the UNS tag. 

    For example:

    • Topic: spBv1.0/Site 2/DDATA/Area 2/Line 2
    • Payload: {"timestamp":1643823756250,"metrics":[{"name":"Conveyer/Batch/Quantity","timestamp":1643823732145,"dataType":"Double","value":65.40}],"seq":72}

    will not create an MQTT Engine tag as the tag [MQTT Engine]UNS/Conveyer/Batch/Quantity already exists.

    Note

    A requirement of a UNS is that each tag can only be referenced from a single source ie. the same tag path cannot be published from two edge nodes.

    In order to identify the source for the tag, the Sparkplug Descriptors in the topic are used to create three custom tag properties which identify the Sparkplug Descriptor associated with this tag: SparkplugGroupId, SparkplugEdgeNodeId and SparkplugDeviceId


    If using MQTT Transmission to publish the message

    , you may need to utilize the Sparkplug IDs configurable for each Transmitter to correctly build your UNS tag path rather than allow the Transmitter

    and the Transmitter are configured to dynamically pickup the Sparkplug Descriptors

    from the tag folder hierarchy.

    , the metric names used in the payload will be the remainder of the tag folder hierarchy not used in the topic namespace.

    This can result in collisions at MQTT Engine with duplicate metric names from different edge nodes.

    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.
    NoteIf MQTT Engine is configured for both Default Tags and UNS Tags, this approach will result in some duplication of the folder structure under the Edge Nodes but will ensure that the UNS view is correctly laid out 


    In the example below we have

    four

    three tag providers simulating

    four Edges

    edges - Site 1A, Site 1B

    , Site 1C

    and Site 2. 

    For each Transmitter configuration we have set the Sparkplug IDs to use the the message topic allowing the tag folder hierarchy at the Edge to form the metric name. 

    Allowing the Transmitters to create the Sparkplug Descriptors dynamically would result in duplicate metric names in messages published to MQTT Engine.

    For example:

    Site 1 A publishing with topic "Enterprise/Site 1/Area 1" would contain a payload metric of "BMS/Rooftop"

    Site 1 B publishing with topic "Enterprise/Site 1/Area 2" would contain a payload metric of "BMS/Rooftop"

    Site 2 publishing with topic "Enterprise/Site 2/Area 1" would contain a payload metric of "BMS/Rooftop"Image Removed



    Image Removed

    The recommended approach to create unique metric names is to configure the Sparkplug Descriptors used by each Transmitter which allows the full tag folder hierarchy to be used for the metric name.

    In the example below we have set the Sparkplug IDs for each Transmitter: 

    Image Added

    such that 

    Site 1 A publishing with topic "Enterprise/Site 1 A/UNS" would contain a payload metric of "

    Messages published from the each edge node will now contain metric names which are the full folder hierarchy at the Edge

    For example:

    Site 1A Edge node metric name of

    Enterprise/Site 1/Area 1/BMS/Rooftop

    / ........Site 1B Edge node metric name of

    "

    Site 1 B publishing with topic "Enterprise/Site 1 B/UNS" would contain a payload metric of "Enterprise/Site 1/Area 2/BMS/Rooftop

    / ........Site 1C Edge node metric name of

    "

    Site 2 publishing with topic "Enterprise/Site

    1/Area 2/Line 2/DO1_EMU/........Site 2 Edge node metric name of

    2/UNS" would contain a payload metric of "Enterprise/Site 2/Area 1/BMS/Rooftop

    / ........

    "


    Note

    If MQTT Engine is configured for both Default Tags and UNS Tags, this approach will result in some duplication of the folder structure under the Edge Nodes but will ensure that the UNS view is correctly laid out 


    At Engine, these tags published from Edge Nodes Site 1 A, Site 1 B and Site 1 C are then concatenated under the single UNS tag path of UNS> UNS > Enterprise > Site 1