MQTT Client Addressing

An address assist dialog is provided but it may not be possible to query your broker for the published topics. You may need to obtain the topic names and structure from your MQTT broker.

MQTT Address Assist dialog - manual mode

  • For protocols other than Sparkplug, enter the Topic (required) and the Metric (optional unless in Sparkplug protocol).
  • If your driver is configured for Custom protocol, enter the name of the custom encoder/decoder module (required).
  • The MQTT addressing scheme allows the use of simple array indexing with the built-in JSON in order to read JSON array payloads.
    It will also allow custom decoders to return either structures or arrays of structures.
  • If the pass-through decoder is used, do not use any indexing trail
  • An XML reading address with top-level array indexing will cause an addressing error, because decoded XML always starts with the root and cannot start with an array. With XML an indexing trail can never start with a top level array indexing, therefore an indexing trail in the form, [0].A.B will fail because it starts with a top level array indexing.

Indexing Trails

(aka "metric". Specifies the address of nested or array data)

You will get a "Tag Address" error in the following situations:

  • You use the built-in pass-through decoder with any indexing trail.
  • You use the built-in XML decoder with an indexing trail that starts with array indexing such as [2][0].temperature

 

It is possible to have an indexing trail that begins with array indexing if the data returned from the decoder is an array of structures instead of just a structure. As examples:

  • A custom decoder could return a VTScada structure or an array of VTScada structures.
  • The built-in JSON decoder can also return a structure or an array of structures.
  • The built-in XML decoder can return only a structure.
  • The built-in pass-through decoder cannot return either. It returns the MQTT payload as a stream.

MQTT Address Assist dialog - Sparkplug B mode

When in Sparkplug B mode, you can Import Tags from PLCs rather than create and configure them one at a time.

  • When the driver is in Sparkplug B mode, Topic, Metric and Custom Decoder will not be shown. Instead, the dialog will display a tree of addresses. This information is obtained from the BIRTH certificate.
    If needed, the address assist can be made to switch back to the generic address entry mode using the "Manual" button, at the bottom left of the dialog when in Sparkplug B mode. (And, back to tree mode using the "Tree" button.)

Reading Data

The general form of an address is 

TopicName+Decoder+Metric

Note that it is optional to specify an encoder or decoder, therefore the most common form of an address is

TopicName++Metric

Where

  • Plus signs (+) are separators between the three components as shown.
    VTScada does not support the use of wildcards.
  • TopicName is required and is a unique name describing the information. Examples include:
building/floor-1/sensors/temperature

The temperature sensor on the first floor.

building/+/sensors/temperature

Temperature sensors on all floors.

building/floor-1/sensors/#

All sensors on the first floor.

  • Decoder (/ Encoder) Tells VTScada how the information is stored so that it can be interpreted correctly. In practice, most data will be encoded as either JSON or XML. In most cases you need only specify the decoder if you are deviating from the protocol you specified in the driver.
    The following decoders are provided. It is also possible for experienced VTScada programmers to write their own. (Write a Custom MQTT Decoder)
    An Encoder / Decoder is always required for Custom and must not be specified for PassThrough. Other requirements may exist for various encoders.

JSONDec

The default decoder. If left blank, this will be used.

XMLDec

An XML decoder.

MQTTPassThruParser

Data stored in the topic is passed through without parsing.

SPBDec

Sparkplug B decoder

SPBEnc

Sparkplug B encoder

If the driver is configured to use the Sparkplug B protocol, there is no need to specify these strings in the address.

  • Metric (formerly "Indexing Trail") Specifies the address of nested or array data.

For example, given data stored in the topic, Building/Floor1/sensors using JSON as follows, where the desired information (highlighted in green) is the first element of the array in "K1_1_3":

{"V1":51.5,
 "K1":{"K1_1":{"K1_1_1":53,
               "K1_1_2":"v1_2_794",
               "K1_1_3":[13.713,26.138,39.804]
              }
      },
 "K2":11.11,
 "Timestamp":1555622869.8499205
}

The address is:

Building/floor1/sensors++K1.K1_1.K1_1_3[0].

Note that in this example, the decoder is not specified (++), meaning that the default JSONDec decoder is to be used.

For Sparkplug B, the "DataSet" data type is not supported.

The keys used within a Metric's properties array to extract extra tag information are as follows:

Units - SparkplugBEngUnitsProperty

RangeMin - SparkplugBRangeMinProperty

RangeMax - SparkplugBRangeMaxProperty

No action is required if your SparkplugB device publishes units, and ranges under the following names : engUnit, engHigh, engLow. If your device publishes units under a different name (for example, "MotorUnits") then you must change the matching SparkplugB property as shown in the following example:

SparkplugBRangeMinProperty = MotorUnits

The following is an example of a Python script implementing an MQTT device that references those variables:

#
metric.properties.keys.extend(["engUnit"])
propertyValue = metric.properties.values.add()
propertyValue.type = ParameterDataType.String
propertyValue.string_value = "Deg Celcius"
#
metric.properties.keys.extend(["engHigh"])
propertyValue = metric.properties.values.add()
propertyValue.type = ParameterDataType.Float
propertyValue.float_value = 50.0
#
metric.properties.keys.extend(["engLow"])
propertyValue = metric.properties.values.add()
propertyValue.type = ParameterDataType.Float
propertyValue.float_value = 10.0

In each block you can see the reference to engunit, enghigh and englow. Those MQTT properties get translated to the SparkPlugB properties in VTScada. If your MQTT device uses different variable names, you can change them in the VTScada properties.

VTScada then takes those three variables and when the MQTT tags are automatically built, it uses them to populate the engineering units and the Display Range Min and Max of the IO tag.

Writing data

Write addresses follow a similar scheme as the Read addresses with the following changes:

  • The only encoders supported by default are the JSONEncoder (JSONEnc) and the MQTTPassThruParser. The default is the JSON encoder.
  • Custom encoders are supported and if used are passed in the tag value as parameter 1. The TrailingIndex, if used, is specified as parameter 2. The encoder must be a subroutine that returns the full payload for the message (very similar to the custom decoders).
  • Write addresses contain 2 additional optional components in their delimiters - the QoS of the message, and if the message should be retained. e.g. MyTopic+MyEncoder+TrailingIndex+QoS+Retain. The QoS will default to that of the driver if not specified, and the retain will default to FALSE if not specified.

 

Read example, using the HiveMQ® public broker: