MQTT Subscriber item naming

The MQTT Subscriber can subscribe to data in:

• Sparkplug

• JSON-VTQ1

• JSON-VTQ2

• JSON-Generic

Sparkplug

A Sparkplug MQTT item reference is of the following format.

• For items in an Edge Gateway (EON), the item reference syntax is:

  spvB1.0/Group/EON.(Metric).value

• For items in the Device, the item reference syntax is:

  spvB1.0/Group/EON/Device.(Metric).value

where,

• Group: Group name defined in the MQTT publisher

• EON: Edge Gateway (EON) name published by the MQTT publisher

• Device: Device name published by the MQTT publisher

• Metric: Item name of the attribute published by the MQTT publisher

JSON-VTQ1 format

This JSON format is used in the:

• MQTT Publisher in Gateway Communication Driver, and

• MQTT Publisher in the MQTT Communication Driver

to publish MQTT data. In this format, a single item is published under its own MQTT topic.

The name of the MQTT topic is:

Group/ItemName

The format of the JSON string in each topic is:

{“d”: value, “dt”: datatype, “ts”: timestamp, “q”: quality }

where,

• Group: optional prefix as defined in the publisher of the Communication Driver. If this value is not blank, the / character is added automatically to the topic name between the Group name and Item name.

• ItemName: attribute name defined in the publisher of the Communication Driver.

• value: data value of item (in JSON convention).

• datatype: ordinal value of Microsoft’s VARENUM Variant data type. For example: 2 is VT_I2, 3 is VT_I4, 8 is VT_BSTR, 11 is VT_BOOL

• timestamp: timestamp of the data point in UTC expressed in ISO 8601 format. For example: 2021-06-17T22:46:07Z = June 17 2021, 10:46:07 pm UTC. The ISO 8601 timestamp string ends with Z.

• quality: OPC DA quality of the data point. For example: 192 = good; 0 = bad, 4 = Configuration error, 24 = Communication failure.

As the subscriber in the MQTT Communication Driver recognizes this format, it can interoperate and consume the data published from the MQTT Publisher in the Gateway Communication Driver or MQTT Communication Driver.

JSON-VTQ2

This format is used by the Publisher in the MQTT Communication Driver to publish MQTT data. If you select this option, multiple items are published under a single topic (up to 1000 items per topic).

To extract the values out to System Platform, OPC, SuiteLink or PCS clients transparently without adding any parsing logic, you need to use the MQTT Communication Driver subscriber.

For items in the Edge Gateway (EON), the topic is: Group/EON

For items in the Device, the topic is: Group/EON/Device

The format of the JSON string in each topic is an array of JSON string is:

{

"timestamp": timestamp_sent, "values": [

{ "id": itemName, "v": value, "dt": dataType, "t": timestamp_ds, "q": quality },

{ "id": itemName, "v": value, "dt": dataType, "t": timestamp_ds, "q": quality },

…

{ "id": itemName, "v": value, "dt": dataType, "t": timestamp_ds, "q": quality },

{ "id": itemName, "v": value, "dt": dataType, "t": timestamp_ds, "q": quality }

]

}

where,

• Group: optional prefix as defined in the publisher in MQTT Publisher configuration. If this value is not blank, the / character is added automatically to the publishing MQTT topic between the Group name and EON name.

• EON: Edge Gateway (EON) name published by the MQTT publisher.

• Device: Device name published by the MQTT publisher.

• timestamp_sent: timestamp when the message was sent from the MQTT publisher to the MQTT broker. The value is expressed in the number of milliseconds since Jan 1, 1970, UTC (Unix format).

• itemName: attribute name defined in the publisher of Gateway Communication Driver.

• value: data value of item (in JSON convention).

• dataType: ordinal value of Microsoft’s VARENUM Variant data type. For example: 2 is VT_I2, 3 is VT_I4, 8 is VT_BSTR, 11 is VT_BOOL

• timestamp_ds: timestamp of data value at the data source expressed in the number of milliseconds since Jan 1, 1970, UTC (Unix format).

• quality: OPC DA quality of the data point. The value can be in both the integer and string format. For example: 192 / good; 0 / bad, 4 / Configuration error, 24 / Communication failure.

Since the MQTT subscriber recognizes this format, the resulting VTQ (Value, Time, Quality) is readily available to any clients connecting to the MQTT subscriber with the following syntax:

• For items in the Edge Gateway (EON), the item reference syntax is: Group/EON.ItemName

• For items in the Device, the item reference syntax is: Group/EON/Device.ItemName

• If Group is blank, the item reference syntax for EON items is: EON.ItemName

• If Group is blank, the item reference syntax for Device items is: EON/Device.ItemName

  Note: You have to use MQTT Communication Driver to subscribe to this format. The subscriber in Gateway Communication Driver does not recognize this format.

JSON (Generic Format)

MQTT subscriber supports embedded JSON strings, as well as strings at multiple nested levels (objects and arrays). Refer to the following examples of possible JSON string forms and the referenced values.

Example1: If TagX receives a JSON string of form { “Value1”: 1, “Value2”:2}

Values in the JSON string are referenced as follows:

Example 2: If TagA receives a JSON string of form { “Value1”: 1, “Value2”:{ “value3”: 2, “value4”: 3 }, “Value5”: [ 5, 6] }

Values in the JSON string are referenced as follows:

Example 3: If TagA receives a JSON string of form [ “stringValue1”, “stringValue2”]

Values in the JSON string are referenced as follows: