Commands

Table of Contents

• Decoding and Processing the Message Payload
• Writing the Individual JSON Values
• Accessing Commands
• JSONPath Queries
  • Examples

See also

Xentara Elements in the Xentara user manual

Commands are Xentara elements that allow you to receive commands from by an MQTT client element by subscribing to an MQTT topic. Command elements must always be children of client elements.

Each command element has the following properties:

1. The topic the command should subscribe to, as described in chapter 3.3.2.1 Topic Name in the MQTT specification.
2. A list of Xentara data points to write to when a message is received from the broker, together with information about how to extract the relevant value from the message payload.

The MQTT client requires the payload of all messages received on the command topic to be formattes as a JSON text compliant with RFC 8259. When a message on the subscribed topic is received from the broker, the MQTT client will attempt to parse the payload and write the resulting values to writable Xentara data points.

Decoding and Processing the Message Payload

The configuration of the command contains a list of data points to write whenever a message is received on the subscribed topic. Each of the data points entries has the following properties:

1. The actual data point to write to. This must be a writable data point, like an output data point, or a Xentara register data point. Registers can be useful to store the received value for subsequent processing.
2. A JSONPath query specifying where within the received message the value for this particular data point can be found. The supported JSONPath queries are described in the chapter JSONPath Queries below.
3. An option named “as JSON text”, specifying whether the JSON value found by the path should be decoded, or whether the original JSON text should be written to the data point as a string (see below).

For each data point the corresponding JSON value is located with the received message payload, and the corresponsing value is written to the data point. The process of decoding the values is described in the next chapter.

Writing the Individual JSON Values

See also

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

Normally, the JSON value found is decoded, and the resulting value is written to the data point using the appropriate data type:

• If the JSON document contains a JSON number, like 25.3 or jsonnumber{6}, then the corresponding numeric values is written to the data point as number.
• If the JSON document contains a JSON Boolean value, (true or jsonkeyword{false}), then the corresponsing Boolean value is written to the data point as a Boolean.
• If the JSON document contains a JSON string, like “"error"} or “"ARMED"}, then the string is decoded by removing the quotes and expanding escape sequences, and is written to the data point as a string. The JSON string encoding is describen in Section 7 of RFC 8259.

Other JSON types (objects, array, and NULL values) are not supported and will result in a type mismatch error.

Sometimes, however, it can be more useful to write the original JSON text to the data point as a string, and then decode the value using a purpose-written microservice. This can be accomplished using the Xentara C++ Control skill, for example. This allowes you to do more sophisticated parsing of the JSON value, including parsing JSON objects and JSON arrays. To use a microservice to decode the JSON value proceed as follows:

1. Create a Xentara register data point with data type “string” to hold the JSON text.
2. Add the register as a data point in the MQTT command object, and enable the option “as JSON text” for it.
3. Write a decoder microservice (for example, using the Xentara C++ Control skill) that reads the value from the reister, decodes it using a JSON parser, and takes the appropriate action. For example, you can write the decoded values to another set of registers.
4. Attach the decoder code to the “written” event of the register using a Xentara execution pipeline. For a C++ Control, this entails placing its “step” task in the pipeline.

Accessing Commands

See also

Accessing Xentara Elements in the Xentara user manual MQTT topics have the following members:

Attributes

key	The command’s primary key.
name	The command’s name. The name is the last component of the primary key.
UUID	The unique UUID of the command.
type	The command’s element type. For MQTT commands, this is always “MQTT Command”.
category	The command’s category. For MQTT commands, this is always “transaction”.
brokerAddress	The host name or network address of the broker the command’s client connects to.
portNumber	The port number of the broker the command’s client connects to.
clientID	The MQTT client identifier the command’s client advertises to the broker on connection.
topic	The MQTT topic the command subscribes to.
state	A Boolean value denoting whether the topic was subscribed to successfully. This attribute will be true if the topic is was subscribed to successfully, or false if there was a problem.
subscribeTime	The time the topic was subscribed to, or the time the subscribe error occurred if the subscription failed.
subscribeError	This attribute contains an error message denoting the error if the “state” attribute is false.
receiveTime	The time a message was received.
QoS	The numeric value of the MQTT QoS (quality of service) of the last received message. MQTT defines the following three QoS values: QoS Meaning 0 At most once 1 At least once 2 Exactly once
retained	Whether the last received message was a message that will be retained by the broker. This will cause the message to be received again if the connection to the broken is lost and reestablished. The retained flag is set by the publisher of the message.
receiveErrorSummary	This attribute contains a text summarizal any errors that occurred decoding the last message payload, or writing the data to the data points.

Events

received

This event is raised whenever a message has been received on the subscribed topic.

JSONPath Queries

See also

RFC 9535: JSONPath: Query Expressions for JSON

JSONPath is a language that allows you to specify a “path” to a specific value within a JSON document. The Xentara MQTT client only supports a subset of the JSONPath specification. The following selectors are supported:

• The root identifier,
• name selectors, and
• array selectors.

Examples

Consider the following payload:

{
  "temperatures": {
    "intake": 27.4,
    "exhaust": 1384.6
  },
  "pressures": [
    1.023,
    22.5
  ],
  "status": [
    {
      "class": "nominal",
      "confidence": 0.94
    },
    {
      "class": "elevated",
      "confidence": 0.70
    }
  ]
}

You can extract the individual values from this payload using the following JSONPath queries:

Value	JSONPath Query
intake temperature	$.temperatures.intake
exhaust temperature	$.temperatures.exhaust
pressure #1	$.pressures[0]
pressure #2	$.pressures[1]
class of status #1	$.status[0].class
confidence of status #1	$.status[0].confidence
class of status #2	$.status[1].class
confidence of status #2	$.status[1].confidence

You can also extract the entire “status” array using the query “$.status”, or the entire “temperatures” block using the query “$.temperatures”. This is only useful, however, if you selected the option “as JSON text” for the data point, because the normal decoding of JSON values only supports strings, numbers, and Boolean values.

To extract the whole JSON message, use just the query “$”.