Determines whether a clean session is used once connected.
def get_clean_session() -> bool: ... def set_clean_session(value: bool) -> None: ...
clean_session = property(get_clean_session, set_clean_session)
This property determines whether or not the class should instruct the server to use a clean session when it connects. (Note that this property must be set to the desired value before calling connect.)
By default, clean_session is true, so the server will discard any state data previously associated with the current client_id once the class has connected successfully. In addition, the server will not save any state data when the class disconnects.
Setting clean_session to False before connecting will cause the server to re-associate any previously stored state data for the current client_id. The server will also save any state data that exists when the class is disconnected.
The server-side session state consists of:
- whether a session is present (see SessionPresent),
- 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
When setting clean_session to False, it is important that the restore_session method be used to load any previously saved (client-side) session data from a previous session before calling connect. (Successful calls to restore_session will automatically set clean_session to False.)
Similarly, once disconnected, save the string returned by save_session for later use. The saved session information may be used when connecting with clean_session set to False at a later time.
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 class should instruct the server to discard any previously stored session data associated with the current client_id and start a new clean session.
For more information on session expiration in MQTT 5, see the SessionExpInterval config. Setting clean_session to True in v3.1.1 is equivalent to setting clean_session 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 clean_session, and to manage its preservation depending on SessionExpInterval.