Abstract

Injector Tag Agents have three parameters related to managing UDTs:

  1. Convert UDTs which converts UDT members to normal tags when enabled
  2. Optimize UDTs which optimizes UDT Payloads sizes in NDATA and DDATA payloads when enabled
  3. Publish UDT Definitions which publishes the UDT definition in the NBIRTH payload when enabled
If you have selected Convert UDTs to be true, then the Optimize UDTs and Publish UDT Definitions parameters will not be used
UDTs instances must be created at the Edge Node level or lower. Review Cloud Injector Tag Agents and Tag Trees to understand how the Sparkplug Identifiers are determined.

This document will show the effect on the message payload that these parameters have using the UDT example below:

Example 1

Convert UDTs: True

In this scenario, the UDT tags are converted to normal tags in the DBIRTH, NBIRTH, DDATA or NDATA messages with the name comprising the UDT instance and the UDT tag, for example name: "Test_UDT/Int001", and associated dataType


{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","type":"NDEATH"},"payload":{"timestamp":1652121534156,"metrics":[{"name":"bdSeq","timestamp":1652121534156,"dataType":"Int64","value":0}],"seq":-1}}

{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","type":"NBIRTH"},"payload":{"timestamp":1652121535168,"metrics":[{"name":"bdSeq","timestamp":1652121535167,"dataType":"Int64","value":0}],"seq":0}}


{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","deviceId":"Tutorial_Device","type":"DBIRTH"},"payload":{"timestamp":1652121535168,"metrics":[{"name":"Test_UDT/Int001","timestamp":1652121535168,"dataType":"Int32","metaData":{},"properties":{"Quality":{"type":"Int32","value":192}},"value":10},{"name":"Test_UDT/Int003","timestamp":1652121535168,"dataType":"Int32","metaData":{},"properties":{"Quality":{"type":"Int32","value":192}},"value":30},{"name":"Test_UDT/Int002","timestamp":1652121535168,"dataType":"Int32","metaData":{},"properties":{"Quality":{"type":"Int32","value":192}},"value":20}],"seq":1}}


{"topic":"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","deviceId":"Tutorial_Device","type":"DDATA"},"payload":{"timestamp":1652121670904,"metrics":[{"name":"Test_UDT/Int001","timestamp":1652121669893,"dataType":"Int32","value":100}],"seq":2}}


{"topic":"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","deviceId":"Tutorial_Device","type":"DDATA"},"payload":{"timestamp":1652121707709,"metrics":[{"name":"Test_UDT/Int002","timestamp":1652121706702,"dataType":"Int32","value":200}],"seq":3}}


Example 2

Convert UDTs: False

Optimize UDTs: False

Publish UDT Definition: True

In this scenario, the UDT tags are included in the DDATA or NDATA payloads with a dataType of Template and the tag name contained in the metaData


{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","type":"NDEATH"},"payload":{"timestamp":1652122108771,"metrics":[{"name":"bdSeq","timestamp":1652122108771,"dataType":"Int64","value":0}],"seq":-1}}


{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","type":"NBIRTH"},"payload":{"timestamp":1652122109797,"metrics":[{"name":"UDT001","timestamp":1652122109790,"dataType":"Template","value":{"isDefinition":true,"metrics":[{"name":"Int001","timestamp":1652121236868,"dataType":"Int32","metaData":{},"value":10},{"name":"Int002","timestamp":1652121244677,"dataType":"Int32","metaData":{},"value":20},{"name":"Int003","timestamp":1652121249789,"dataType":"Int32","metaData":{},"value":30}]}},{"name":"bdSeq","timestamp":1652122109795,"dataType":"Int64","value":0}],"seq":0}}


{"topic":"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","deviceId":"Tutorial_Device","type":"DBIRTH"},"payload":{"timestamp":1652122109797,"metrics":[{"name":"Test_UDT","timestamp":1652122109809,"dataType":"Template","metaData":{},"value":{"reference":"UDT001","isDefinition":false,"metrics":[{"name":"Int001","timestamp":1652122109797,"dataType":"Int32","metaData":{},"value":100},{"name":"Int002","timestamp":1652122109797,"dataType":"Int32","metaData":{},"value":400200},{"name":"Int003","timestamp":1652122109797,"dataType":"Int32","metaData":{},"value":300}]}}],"seq":1}}


{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","deviceId":"Tutorial_Device","type":"DDATA"},"payload":{"timestamp":1652122230548,"metrics":[{"name":"Test_UDT","timestamp":1652122229536,"dataType":"Template","metaData":{},"value":{"reference":"UDT001","isDefinition":false,"metrics":[{"name":"Int001","timestamp":1652122229536,"dataType":"Int32","metaData":{},"value":1000}]}}],"seq":2}}


{"topic":"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","deviceId":"Tutorial_Device","type":"DDATA"},"payload":{"timestamp":1652122234323,"metrics":[{"name":"Test_UDT","timestamp":1652122233319,"dataType":"Template","metaData":{},"value":{"reference":"UDT001","isDefinition":false,"metrics":[{"name":"Int002","timestamp":1652122233319,"dataType":"Int32","metaData":{},"value":2000}]}}],"seq":3}}


Example 3 

Convert UDTs: False

Optimize UDTs: True

Publish UDT Definition: True

In this scenario, UDT tags are included in the DDATA or NDATA payloads as normal tags with the name comprising the UDT instance and the UDT tag for example name: "Test_UDT/Int001" and associated dataType.

It will be the responsibility of the client subscribing to this data to reconstruct as UDTs if required

{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","type":"NDEATH"},"payload":{"timestamp":1652122380765,"metrics":[{"name":"bdSeq","timestamp":1652122380765,"dataType":"Int64","value":0}],"seq":-1}}


{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","type":"NBIRTH"},"payload":{"timestamp":1652122381786,"metrics":[{"name":"UDT001","timestamp":1652122381778,"dataType":"Template","value":{"isDefinition":true,"metrics":[{"name":"Int001","timestamp":1652121236868,"dataType":"Int32","metaData":{},"value":10},{"name":"Int002","timestamp":1652121244677,"dataType":"Int32","metaData":{},"value":20},{"name":"Int003","timestamp":1652121249789,"dataType":"Int32","metaData":{},"value":30}]}},{"name":"bdSeq","timestamp":1652122381785,"dataType":"Int64","value":0}],"seq":0}}


{"topic":"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","deviceId":"Tutorial_Device","type":"DBIRTH"},"payload":{"timestamp":1652122381786,"metrics":[{"name":"Test_UDT","timestamp":1652122381790,"dataType":"Template","metaData":{},"value":{"reference":"UDT001","isDefinition":false,"metrics":[{"name":"Int001","timestamp":1652122381786,"dataType":"Int32","metaData":{},"value":1000},{"name":"Int002","timestamp":1652122381786,"dataType":"Int32","metaData":{},"value":2000},{"name":"Int003","timestamp":1652122381786,"dataType":"Int32","metaData":{},"value":300}]}}],"seq":1}}


{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","deviceId":"Tutorial_Device","type":"DDATA"},"payload":{"timestamp":1652122454226,"metrics":[{"name":"Test_UDT/Int003","timestamp":1652122453164,"dataType":"Int32","value":3000}],"seq":2}}


{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","deviceId":"Tutorial_Device","type":"DDATA"},"payload":{"timestamp":1652122457602,"metrics":[{"name":"Test_UDT/Int001","timestamp":1652122456594,"dataType":"Int32","value":100}],"seq":3}}


{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","deviceId":"Tutorial_Device","type":"DDATA"},"payload":{"timestamp":1652122558395,"metrics":[{"name":"Test_UDT/Int001","timestamp":1652122557388,"dataType":"Int32","value":1000}],"seq":4}}

Example 4 - NBIRTH message

Publish UDT Definition: True

{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","type":"NBIRTH"},"payload":{"timestamp":1652122381786,"metrics":[{"name":"UDT001","timestamp":1652122381778,"dataType":"Template","value":{"isDefinition":true,"metrics":[{"name":"Int001","timestamp":1652121236868,"dataType":"Int32","metaData":{},"value":10},{"name":"Int002","timestamp":1652121244677,"dataType":"Int32","metaData":{},"value":20},{"name":"Int003","timestamp":1652121249789,"dataType":"Int32","metaData":{},"value":30}]}},{"name":"bdSeq","timestamp":1652122381785,"dataType":"Int64","value":0}],"seq":0}}


Publish UDT Definition: False

{"topic":{"namespace":"spBv1.0","edgeNodeDescriptor":"Tutorial_Group/Tutorial_Edge_Node","groupId":"Tutorial_Group","edgeNodeId":"Tutorial_Edge_Node","type":"NBIRTH"},"payload":{"timestamp":1652123286421,"metrics":[{"name":"bdSeq","timestamp":1652123286417,"dataType":"Int64","value":0}],"seq":0}}

This functionality is useful if your UDT definitions do not frequently change and you can avoid the data overhead of including the UDT definition in the NBIRTH payload 



  • No labels

New to MQTT? Start Here!