Message Payloads

Table of Contents

• Empty payloads
• Fixed payloads
• Constructed payloads

The payloads of messages sent to topic elements, birth messages of client elements, and will messages of client elements have the same format. The payload of each of these message can be configured to have one of three forms:

1. An empty payload
2. A fixed payload
3. A constructed payload, containing a JSON text compliant with RFC 8259.

Each topic, as well as the birth and will messages of each client have their own configuration, so that each can have their own format.

Constructed payloads for topic elements and birth messages can be dynamic, and can contain values of Xentara data points and/or individual Xentara attributes. Payloads of will messages are always static and cannot contain data point or attribute values.

Empty payloads

The payload of a message can be configured to be empty. Messages with empty payloads are never retained by the broker, but can be used to remove a retained message with the same topic. See chapter 3.3.1.3 RETAIN in the MQTT specification for details.

Fixed payloads

The payload of a message can be configured to be a fixed UTF-8 text string. Such topic payloads cannot include any dynamic data, like data point or attribute values.

Constructed payloads

See also

RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format

The payload of a message can be a dynamically constructed JSON text. This can be a JSON object, a JSON array, or another type of JSON value. Objects and arrays can be nested as desired. constructed payloads can contain values of Xentara data points and/or values of individual Xentara attributes.

Data point values are represented as JSON objects containing the value and quality of the data point:

{
  "value": 62.4,
  "quality": "good"
}

In actuality, message payloads always use a compact JSON representation, so the real payload will look like this:

{"value":62.4,"quality":"good"}

By default, the object only contains the value and quality of the data point. Optionally, additional attributes can be included by specifying them in the configuration of the topic or message:

{
  "value": 62.4,
  "quality": "good",
  "units": "°C",
  "changeTime": "2024-04-22T11:27:14.250000000Z",
  "error": ""
}

You can also combine more that one data point in a single payload:

{
  "temperature": {
    "value": 62.4,
    "quality": "good"
  },
  "pressure": {
    "value": 34,
    "quality": "good"
  }
}

You can also include arbitrary Xentara attributes of arbitrary Xentara elements in the payload:

{
  "address": "sensor.my-company.local",
  "deviceState": true,
  "connectionTime": "2024-04-22T11:27:14.342231400Z",
  "error": ""
}

Data points and arbitrary attributes can also be combined:

{
  "temperature": {
    "value": 62.4,
    "quality": "good"
  },
  "pressure": {
    "value": 34,
    "quality": "good"
  },
  "updateTime": "2024-04-22T11:27:14.250000000Z"
}

Fundamentally, the payload can be almost any arbitrary JSON text, containing nested objects, arrays, and any combination of data point values, attribute values, and fixed entries:

{
  "contents": "temperatures",
  "readings": [
    {
      "value": 62.4,
      "quality": "good"
    },
    {
      "value": 58.62,
      "quality": "good"
    }
  ],
  "updateTime": "2024-04-22T11:27:14.250000000Z",
  "comms": {
    "status": true,
    "error": "",
    "subdevices": [
      true,
      true,
      false
    ]
  }
}