Details on the MQTT driver

Retain

The Retain flag is only relevant for publishing. For subscription addresses it is ignored. If the Retain flag is set, the broker stores the last published value for that topic. If a client subscribes this topic, it immediately receives this value. The use case of the Retain flag is to provide a "last" value of a topic to the clients without the need to publish a value.

Quality of Service

There are 3 levels of QoS (0,1,2).

  • The value 0 means "fire and forget". This means that a message published with QoS 0 is not acknowledged or retransmitted.
  • The value 1 means "transmission of message at least once". A message with QoS 1 is acknowledged by the receiver.

If the acknowledgement does not reach the sender, the message is repeated. However, this might also lead to duplicate messages.

The value 2 means "exactly once". In this case the receiver acknowledges the messages, the sender acknowledges the acknowledgement and the receiver finally sends a transaction complete.

This allows the receiver to filter out duplicate messages. The price of the higher reliability of higher QoS values is a higher resource consumption in the broker and the client, higher network load and also higher transmission latency time.

The QoS of a message from Broker to a subscribing client is determined by the QoS of the original publish and the QoS of the subscription. This can be seen in the table below where the QoS of the subscription is horizontal and the QoS of the original publish is vertical.

P\S 0 1 2
0 0 0 0
1 0 1 1

2 0 1 2

Persistent Session

A persistent session stores the subscriptions and QoS 1 and 2 messages if the client is not connected. This might lead to a lot buffered values, which are sent to the client if the client reconnects and resumes the session.

This is why persistent sessions must be used with care since they might lead to a high resource consumption of the broker.

The use case of persistent session is to bright the gap where a subscribing client is not available and no messages shall be lost.

Debug flags

Following debug flags can be used to detect possible error causes during driver runtime:

Debug level Description
25 Internal data handling of MQTT messages

Error messages

Error code Error message
0 Unknown error
1 SocketConnectionRefusedError
2 SocketRemoteHostClosedError
3 SocketHostNotFoundError
4 SocketAccessError
5 SocketResourceError
6 SocketTimeoutError
7 SocketDatagramTooLargeError
8 SocketNetworkError
9 SocketAddressInUseError
10 SocketAddressNotAvailableError
11 SocketUnsupportedSocketOperationError
12 SocketUnfinishedSocketOperationError
13 SocketProxyAuthenticationRequiredError
14 SocketSslHandshakeFailedError
15 SocketProxyConnectionRefusedError
16 SocketProxyConnectionClosedError
17 SocketProxyConnectionTimeoutError
18 SocketProxyNotFoundError
19 SocketProxyProtocolError
20 SocketOperationError
21 SocketSslInternalError
22 SocketSslInvalidUserDataError
23 SocketTemporaryError
65536 MqttUnacceptableProtocolVersionError
65537 MqttIdentifierRejectedError
65538 MqttServerUnavailableError
65539 MqttBadUserNameOrPasswordError
65540 MqttNotAuthorizedError
65541 MqttNoPingResponse