The Xentara MQTT client v2.0
User Manual
JSON Format for Constructed Payloads

Constructed payloads are defined using a JSON object. The payload configuration for a constructed payload has the following format:

"payload": {
"@PayloadType": ...
}

"@PayloadType" is the type designation for the type of payload to use. Each type of payload has its own format, described in the chapters below.

The Xentara MQTT Client supports five types of payloads:

Type Designation Type
"@DataPoint" Data point value payload
"@Attribute" Attribute value payload
"@Object" JSON object payload
"@Array" JSON array payload
"@JSON" Fixed JSON value payload

JSON Format for Data Point Value Payloads

A data point value payload consists of a JSON object with individual members for the value and quality attributes of a Xentara data point.

A JSON object describing a data point value payload has the following syntax:

{
"@DataPoint": "Axis 1.Motor.Temperature"
}

Object Members
@DataPoint

The name of this member specifies that the payload is a data point value payload.

The value of the member (after the colon) defines the data point whose values should be contained in the payload. It must be a string value containing the primary key of a Xentara data point.

Note
Will message payloads are static and do not support data point value payloads. You can use a fixed JSON value payload to simulate a data point value inside of a a will message payload.

Example

The data point value payload above will produce a payload with the following structure:

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

Topic elements and birth messages can specify additional attributes to be included in the payload. A data point value payload with the additional attributes changeTime and error will have the following structure:

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

JSON Format for Attribute Value Payloads

An attribute value payload consists of a JSON value containing the value of a single Xentara attributes. Since the value is not wrapped inside of a JSON object, it may be difficult for consumers to parse. It is strongly recommended to place attribute value payloads inside of a JSON object by making it a member of a JSON object payload.

A JSON object describing an attribute value payload has the following syntax:

{
"@Attribute": "Devices.EtherCAT Bus.deviceState"
}

Object Members
@Attribute

The name of this member specifies that the payload is an attribute value payload.

The value of the member (after the colon) defines the attributes whose value should constitute in the payload. It must be a string value containing the primary key of a Xentara attribute.

Note
Will message payloads are static and do not support attribute value payloads. You can use a fixed JSON value payload to simulate a attribute value inside of a a will message payload.

Example

A JSON object payload containing three attribute values might look like this:

{
"Object": [
{
"key": "up",
"value": {
"@Attribute": "Devices.EtherCAT Bus.deviceState"
}
},
{
"key": "state",
"value": {
"@Attribute": "Devices.EtherCAT Bus.EtherCATState"
}
},
{
"key": "error",
"value": {
"@Attribute": "Devices.EtherCAT Bus.error"
}
}
]
}

This will produce a payload with the following structure:

{"up":true,"state":"Op",error:""}

JSON Format for JSON Object Payloads

A JSON object payload consists of a JSON object containing a arbitrary number of members. The key of each member can be freely chosen, and the value is another complete payload of any of the types described on this page.

A JSON object describing a JSON object payload has the following syntax:

{
"@Object": [
{
"key": "temperature",
"value": {
"@PayloadType": ...
}
},
{
"key": "rpm",
"value": {
"@PayloadType": ...
}
}
]
}

Object Members
@Object

The name of this member specifies that the payload is a JSON object payload.

The value of the member (after the colon) is an array of JSON objects, each describing a single member of the payload object. The format of the individual objects is described below.

Member Object Members
keyA string value specifying the key to use for this member. The key can be an arbitrary string, but must be unique within this JSON object payload.
valueA JSON object containing the value for the member. The object has the same format as the payload itself, and can contain any of the supported payload types, including another JSON object. The supported payload types are listed above.

Example

A complete JSON object payload containing two members might look like this:

"payload": {
"@Object": [
{
"key": "temperature",
"value": {
"@DataPoint": "Axis 1.Motor.Temperature"
}
},
{
"key": "rpm",
"value": {
"@DataPoint": "Axis 1.Motor.RPM"
}
}
]
}

This will produce a payload with the following structure:

{"temperature":{"value":58.7,"quality":"good"},"rpm":{"value":3403,"quality":"good"}}

JSON Format for JSON Array Payloads

A JSON array payload consists of a JSON array containing an arbitrary number of elements. The value of each element is another complete payload of any of the types described on this page.

A JSON object describing a JSON array payload has the following syntax:

{
"@Array": [
{
"@PayloadType": ...
},
{
"@PayloadType": ...
}
]
}

Object Members
@Array

The name of this member specifies that the payload is a JSON array payload.

The value of the member (after the colon) is an array of JSON objects, each describing a single element of the payload array. Each object has the same format as the payload itself, and can contain any of the supported payload types, including another JSON array. The supported payload types are listed above.

Example

A complete JSON array payload containing two elements might look like this:

"payload": {
"@Array": [
{
"@DataPoint": "Axis 1.Motor.Temperature"
},
{
"@DataPoint": "Axis 1.Motor.RPM"
}
]
}

This will produce a payload with the following structure:

[{"value":58.7,"quality":"good"},{"value":3403,"quality":"good"}]

JSON Format for Fixed JSON Payloads

A fixed JSON array consists of an arbitrary JSON text. The text can consist of any combination of JSON values, including objects, arrays, numbers, strings, Booleans, and null values. Objects and array can be arbitrarily nested.

A JSON object describing a fixed JSON payload has the following syntax:

{
"@JSON": ...
}

Object Members
@JSON

The name of this member specifies that the payload is a fixed JSON payload.

The value of the member (after the colon) is an arbitrary JSON object, array, string, number, Boolean, or null value that will be included as-is in the payload. The value will be reformatted to use the most compact JSON representation.

Example

A fixed JSON payload containing a JSON object with two members might look like this:

"payload": {
"@JSON": {
"alive": false,
"connectionTime": null
}
}

This will produce the following fixed payload:

{"alive":false,"connectionTime":null}