MQTT¶

Capabilities¶

Capabilities	Support for version 3	Comment
Client MQTT
Broker MQTT		It’s possible to add a broker inside the OSP stack but the configuration is not handled natively
Authentication - Basic		See authentication
Authentication - Enhanced authentication (new feature of MQTT 5.0)	N.A.	This feature is currently not supported. In case of interest please contact us at info@swissdotnet.ch
TLS support
MQTT 5 - Header		This feature is currently not supported. In case of interest please contact us at info@swissdotnet.ch
MQTT 5 - reason code		This feature is currently not supported. In case of interest please contact us at info@swissdotnet.ch
Broker connectivity monitoring		See broker connectivity monitoring.
Publish		See mqtt-publish
Subscribe		See mqtt-subscribe
Topic		Wildcards are not supported.
MQTT 5 - Data type		Payload Format Description and Content Type
Quality of service		See quality of services

Concept¶

OnSphere acts as an MQTT client and can connect to one or multiples MQTT broker. The system currently supports MQTT V3 and V5.

Warning

Every message is interpreted as an UTF-8 string.

Authentication¶

The authentication can be done with :

certificate
user / password

The authentication method to use is defined in broker.mqtt.

Note

The public and ca certificates need to be placed in certs/external. The private certificate need to be placed in certs/keys.

Broker connectivity monitoring¶

OnSphere publishes values whose content reflect the connectivity on configured Brokers: True when the connection with the broker is established, False otherwise.

Publish¶

Warning

Every message is published as an UTF-8 string.

Upon a Value change, a message can be published. This message can be the actual value content or a generated json payload.

Usage¶

Trigger a message on a broker when an action is triggered
Sending periodic state to a broker

Subscription¶

The subscription on a topic generates a Value. The Value definition allows to convert the received message either automatically or via a parser.

MQTT QOS¶

OnSphere supports the QoS :

QoS 0 - At most once
QoS 1 - At least once
QoS 2 - Exactly once

This configuration is done in the owner.mqtt file

Parser¶

The parser allows conversion of the received payload to the wanted type as defined by the Value. This configuration is done in owner.mqtt.

STANDARD¶

This is the default parser. It will try to convert the payload to the desired type and generate an error if it cannot. After that the value will be published.

STANDARD_WITH_TOPIC¶

This parser will modify the payload to include the topic on which it was received. For example, the payload 10 will become {"topic": "the/topic", "payload": 10}.

It will try to convert the payload to the desired type and generate an error if it cannot. After that the value will be published.

JSON¶

This parser can read a field of a json object to set the value. It needs a filter in order to find the targeted value. The filter is a dot separated string with the format:

{field}.{field}.{field}

It can handle an array by adding [index] to the field name. The index can have the following value:

empty: first element of the array
number: element at index (with a 0 based index)
negative number: element from the end starting at -1

A optional timestampLocation filter is available. It can be used to override the value timestamp with the one in the payload. This timestamp by default is in milliseconds.

It can be changed by setting timestampUnit with one of the following:

NANOSECONDS
MICROSECONDS
MILLISECONDS
SECONDS
MINUTES
HOURS
DAYS

Example¶

With the following payload:

{
    "array": [
        1,
        2,
        3,
        4
    ],
    "object": {
        "boolean": true
    },
    "complex_object": {
        "type": "OBJECT",
        "list": [
            {
                "object": {
                    "boolean": true
                }
            },
            {
                "object": {
                    "boolean": false
                }
            }
        ]
    }
}

The filter array[0] or array[] will return 1.
The filter array[-1] will return 4.
The filter array[1] or array[-3] will return 2.
The filter object.boolean will return true.
The filter complex_object.list[0].object.boolean will return true.
The filter complex_object.list[1].object.boolean will return false.