MQTT protocol support
MQTT protocol level supported is 3.1.1 (cf. MQTT Protocol Specification 3.1.1)
Live Objects acts as a standard MQTT message broker with some limitations:
-
the "will" functionality is not implemented, all "willXXX" flags and headers are not taken into account,
-
the "retain" functionality is not implemented,
-
the "duplicate" flag is not used,
-
the "clean session" flag is not used, the server always starts a new session.
Although Live Objects supports all control packets, QoS levels beyond the exchanges are not all fully guaranteed.
| QoS | definition | guaranteed | limitation |
|---|---|---|---|
0 |
at most once delivery |
yes |
no |
1 |
at least once delivery |
yes |
"duplicate" flag is not used, |
2 |
exactly once delivery |
no |
same as QoS1 |
Live Objects has several application behaviors depending on the connection mode (username) described in the following section. Currently Live objects supports 3 connection modes:
-
"device" mode used to communicate with a native MQTT device.
-
"external connector" mode is an API that allows communication with devices using other protocols not supported by Live Objects. To communicate with Live Objects, these devices are connected with a backend itself connected in "external connector" mode that can translate requests and responses (from / to) MQTT.
-
"application" mode with this mode, Live Objects provides an application mode to allow business applications to use the MQTT API.
MQTT Connect
The first packet exchanged must be a MQTT CONNECT packet, sent from the client to the MQTT endpoint.
This packet must contain:
-
clientId: usage depends on the "mode", usually the deviceId in "device" mode
-
username: used to select a mode and encoding: (case-sensitive)
-
json+device to use the "device" mode,
-
connector to use the "External connector" mode,
-
application to use the "application" mode,
-
-
password: an API Key with the mandatory roles depending on the connection mode
-
willRetain, willQoS, willFlag, willTopic, willMessage: ! Not taken into account !,
On reception, Live Objects validates the API key provided.
-
If the API key is valid, then Live Objects returns a MQTT CONNACK message with return code
0x00 Connection Accepted. -
If the API key is not valid, then Live Objects returns a MQTT CONNACK message with return code
0x04 Connection Refused: bad username or password, and closes the TCP connection.
MQTT keep alive interval and Ping Req/Res
Live Objects answers to MQTT PINGREQ packets with MQTT PINGRES packets: this is a way for the MQTT client to avoid connection timeouts.
| A Keep Alive value of zero (0) has the effect of turning off the keep alive mechanism. This means that, in this case, the Server is not required to disconnect the Client on the grounds of inactivity. Note that a Server is permitted to disconnect a Client that it determines to be inactive or non-responsive at any time, regardless of the Keep Alive value provided by that Client. |
MQTT Subscribe
Once connected, the client can at any time subscribe and unsubscribe to/from topics.
Live Objects answers with a MQTT SUBACK packet only once all subscriptions could be resolved:
MQTT specification enforce that a MQTT SUBACK is returned even if actual subscription is impossible / forbidden.
In Protocol 3.1 the MQTT client cannot be informed that it subscribed to a non-existing Topic.
In Protocol 3.1.1 the MQTT client will receive MQTT SUBACK with corresponding QoS of 0x80 (Failure).
|
Live Objects answers to MQTT UNSUBSCRIBE packet with a MQTT UNSUBACK packet only once existing subscriptions have been properly closed.