Persistent sessions (clean_session = false) across ungraceful reconnects

This document shows how to configure a ClearBlade system so that if an MQTT client disconnects ungracefully (e.g., because of a catastrophic power cycle), the system stores messages sent to the disconnected device and delivers them when the device reconnects.

Prerequisites

1. The environment is running ClearBlade Platform Version >= 9.33.4.

2. The ClearBlade console is available for viewing/editing systems (for ClearBlade IoT Core users: behind a registry, there is a system):

3. Devices have connected with persistent sessions, which are typically enforced by setting a clean or clean_session flag to FALSE when connecting with the MQTT library of your choice (e.g., paho.mqtt.python).

4. Devices have subscribed to the topics for which they want messages stored in case of a catastrophic disconnect with QoS (Quality of Service) 1 or 2.

Steps

1. Go to the Messages page on the console and then choose the History Storage tab:

Note to ClearBlade IoT Core users: There will be an existing item in History Storage for topic /devices/+/state. Do not edit or delete that item.

2. Click Add Topic and configure the History Storage item:

3. Enter the topic for which message history should be stored. Use wildcards + and # as appropriate for MQTT topics. e.g. /devices/+/commands/#.

4. Check the Platform (e.g., cloud) and Edge checkboxes as appropriate. Both can be checked if only one is used. For most customers, messages only need to be stored on the Platform.

5. Set a value for Max Rows. We highly recommend not setting this to Infinite. Set this to a maximum number of messages to store, beyond which the benefit of storing messages diminishes.

6. Set a value for Max Time. We highly recommend not setting this to Forever. Set this to a maximum time beyond which a reconnecting device should be treated as a newly connecting device.ing.

Messages containing binary payloads will be hex encoded when saved to Message History.