Data Formats for TANI MQTT Implementation

Binary

The Binary format is used when higher performance or shorter network frames are needed.

For MQTT 5: The Payload Format Indicator is always 0 (Binary), except if the PLC data type is "String", for which it is 1 (String). The Content Type is a textual representation of the PLC data type, optionally followed by a comma separated list of PLC data type flags.

For MQTT 3.1/3.1.1: The data type can not be transferred using this protocol. Either configure the type on all systems equal or use one of the other protocol options.

Encoding

Boolean - These are encoded as a single bit. Arrays are packed, so that a byte contains up to 8 array elements. The last byte is padded with 0.
Integer - These are encoded as 1, 2, 4 or 8 byte values, signed or unsigned depending on the type selected by the item syntax. Byte order is also selected by the item syntax.
Floating point - These are encoded as 4 or 8 byte IEEE float numbers. Size and byte order is selected by the item syntax.
String - A character string is encoded as a UInt32 length, followed by the string data (without any terminator character). Byte order is selected by the item syntax.
Multilanguage String - A multilanguage string (or Localized Text) is encoded as a UInt16 translation count, then that many String pairs (locale and text). Byte order is selected by the item syntax.
Structure - Structured data are encoded field by field as given in the structure definition.
Enumeration - Enumerations are encoded as UInt32
Array - Arrays are encoded by encoding their elements one by one. The array length is implicitly set by the length of the encoded data.

Examples

Note: all examples are given as hexdump.

Numeric value (42)

2A 00

Bit-Array (1, 0, 1, 0)

0A

Structure (First: int = 1, Second: String = "String Value")

01 00 00 00 04 00 00 00 53 74 72 69 6E 67 20 56 61 6C 75 65

JSON

The JSON data format is used to transfer data to/from systems that have difficulties with binary data. It consists of a JSON objects with the following properties.

For MQTT 5: The Payload Format Indicator is always 1 (String), the Content Type is "application/json"

Properties

Value - Contains the data value as a boolean, number, string, object (for structured data), or an array of one of these. Depends on the PLC data type.
Type - The PLC data type of the value.
StructureName - The structure name, if "Type" = "Structure".
EnumerationName - The enumeration name, if "Type" = "Enumeration".

Examples

Numeric value 42

{

  "Type": "Uint16",

  "Value": (42)

}

Bit-Array (1, 0, 1, 0)

{

  "Type": "Boolean",

  "Value": [

    true,

    false,

    true,

    false

  ]

}

Structure (First: int = 1, Second: String = "String Value")

{

  "Type": "Structure",

  "StructureName": "MyValues",

  "Value": {

    "First": 1,

    "Second": "String Value",

  }

}

XML

The XML data format is used to transfer data to/from systems that can't handle binary or JSON data. It recreates the JSON data described above as XML.

For MQTT 5: The Payload Format Indicator is always 1 (String), the Content Type is "text/xml"

JSON to XML mapping

Null - null → <n/>
Null values are represented by "n".
Boolean - true → <t/>
false → <f/>
Booleans are represented by "t" and "f" tags, for "true" and "false" values, respectively.
Number - 42 → 42
4.2 → <d>4.2</d>
Numbers are represented by "i" or "d" tags, used for integers and floating point ("double") values, respectively.
String - "a" → <s>a</s>
Strings are represented by "s" tags.
Object - { "a": "b", "c": 42 } → <o><s n="a">b</s>42</o>
Objects are represented by "o" tags. All properties are inserted as sub tags, with "n" attribute for the name.
Array - [ "a", 42 ] → <a><s>a</s>42</a>
Arrays are represented by "a" tags. All array elements are inserted as sub tags.

Properties

See the JSON data described above.

Examples

Numeric value (42)

<o>

  <s n="Type">Uint16</s>

  <i n="Value">42</i>

</o>

Bit-Array (1, 0, 1, 0)

<o>

  <s n="Type">Boolean</s>

  <a n="Value">

    <t/>

    <f/>

    <t/>

    <f/>

  </a>

</o>

Structure (First: int = 1, Second: String = "String Value")

<o>

  <s n="Type">Structure</s>

  <s n="StructureName">MyValues</s>

  <o n=Value>

    <i n="First">1</i>

    <s n="Second">String Value</s>

  </o>

</o>

Data Types

Data Type list

Name	Meaning
Boolean	Binary value (true or false)
SByte, Int16, Int32, Int64	Signed integers of 1, 2, 4 or 8 bytes length
Byte, UInt16, UInt32, UInt64	Unsigned integers of 1, 2, 4 or 8 bytes length
Float, Double	Floating point values of 4 or 8 bytes length
String	Character String
DateTime	Timestamp with date and time
Structure	Structured data
Enumeration	Enumerated data
LocalizedText	String with multiple possible translations

Data Type flags

Flag	Meaning
BigEndian	Data is in big endian (most-significant byte first) order
LittleEndian	Data is in little endian (least-significant byte first) order. Note: only one of LittleEndian and BigEndian should be specified.
BitArrayLen1, BitArrayLen2, ... BitArrayLen7	Indicate the number of valid bits in the last byte of a bit array. Not specifying one of these makes all 8 bits valid.