CleanSession Property

Determines whether a clean session is used once connected.

Data Type

Default Value

Remarks

This property determines whether or not the adapter should instruct the server to use a clean session when it connects.

By default, CleanSession is true, so the server will discard any state data previously associated with the current ClientId once the adapter has connected successfully. In addition, the server will not save any state data when the adapter disconnects.

Setting CleanSession to False before connecting will cause the server to re-associate any previously stored state data for the current ClientId. The server will also save any state data that exists when the adapter is disconnected.

The server-side session state consists of:

• whether a session is present,
• client subscriptions (including subscription identifiers in MQTT 5),
• QoS 1 and 2 messages sent to the client pending transmission or completed acknowledgment (and optionally pending QoS 0 messages),
• QoS 2 messages received from the client but not completely acknowledged, and
• the SessionExpInterval (in MQTT 5).

Note that retained messages are not deleted as a result of a session ending, but are not part of the session state.

Client-Side Session State

The client-side session state consists of:

• QoS 1 and QoS 2 messages which have been sent to the Server, but have not been completely acknowledged, and
• QoS 2 messages which have been received from the Server, but have not been completely acknowledged.

MQTT 5 Notes

In MQTT 5, the "Clean Session" flag from v3.1.1 is split into a "Clean Start" flag indicating that the server should discard previously saved session data from this connection, and a SessionExpInterval controlling the length of time the server should preserve the session data after disconnection.

In MQTT 5, this property acts only as the "Clean Start" flag. It determines whether or not the adapter should instruct the server to discard any previously stored session data associated with the current ClientId and start a new clean session.

For more information on session expiration in MQTT 5, see the SessionExpInterval config. Setting CleanSession to True in v3.1.1 is equivalent to setting CleanSession to True AND setting SessionExpInterval to 0 in MQTT 5.

As with MQTT 3.1.1, it is important for the client to save and restore its own session data on connection and disconnection depending on the value of CleanSession, and to manage its preservation depending on SessionExpInterval.