Add support for MQTT LWT

savfaire · savfaire · commit c37319e814b5 · 2024-03-06T17:21:01.000-06:00
diff --git a/README.md b/README.md
@@ -331,7 +331,7 @@ If you don't specify a client_id, the SDK will use a random hex string.
 > Definition: `System.Messaging(user, port=1883, keepalive=30, url="", client_id="")`   
 > Returns: MQTT messaging object.
 
-There are a slew of callback functions you may assign. 
+There are a number of callback functions you may assign. 
 Typically, you want to set these callbacks before you connect to the broker. 
 This is a list of the function names and their expected parameters. 
 For more information about the individual callbacks, see the [paho-mqtt](https://github.com/eclipse/paho.mqtt.python#callbacks) documentation.   
@@ -343,6 +343,7 @@ For more information about the individual callbacks, see the [paho-mqtt](https:/
 - `on_message(client, userdata, mid)`   
 - `on_log(client, userdata, level, buf)`   
 
+#### Connecting and Disconnecting
 Before publishing or subscribing, you must connect your client to the broker. 
 After you're finished, it's good practice to disconnect from the broker before quitting your program. 
 These are both simple functions that take no parameters.
@@ -352,13 +353,31 @@ These are both simple functions that take no parameters.
 > Definition: `Messaging.disconnect()`   
 > Returns: Nothing.   
 
+#### Last Will and Testament (LWT)
+MWTT brokers support the concept of a last will and testament. The last will and testament is a set of parameters that allow the MQTT broker 
+publish a specified message to a specific topic in the event of an abnormal disconnection. Setting the last will and testament can be accomplished
+by invoking the `set_will` function. The last will and testament can also be removed from a MQTT client by invoking `clear_will`.
+
+**Note: set_will() and clear_will() must be invoked prior to invoking Messaging.connect()**
+
+- `set_will(topic, payload, qos, retain)`   
+- `clear_will()`   
+
+> Definition: `Messaging.set_will()`   
+> Returns: Nothing.   
+> Definition: `Messaging.clear_will()`   
+> Returns: Nothing. 
+
+
+#### Subscribing to topics
 You can subscribe to as many topics as you like and unsubscribe from them using the following two commands. 
 
 > Definition: `Messaging.subscribe(topic)`   
 > Returns: Nothing.   
 > Definition: `Messaging.unsubscribe(topic)`   
 > Returns: Nothing.
 
+#### Publishing to topics
 Publishing takes the topic to publish to and the message to publish as arguments. The type of message can be string or bytes.
 
 > Definition: `Messaging.publish(topic, message)`   
diff --git a/clearblade/Messaging.py b/clearblade/Messaging.py
@@ -113,7 +113,31 @@ def __log_cb(self, client, userdata, level, buf):
         if self.on_log:
             self.on_log(client, userdata, level, buf)
 
-    def connect(self):
+    def set_will(self, topic, payload, qos = 0, retain = False):
+        """
+        Set a Will to be sent by the broker in case the client disconnects unexpectedly.
+        This must be called before connect() to have any effect.
+
+        :param str topic: The topic that the will message should be published on.
+        :param payload: The message to send as a will. If not given, or set to None a
+            zero length message will be used as the will. Passing an int or float
+            will result in the payload being converted to a string representing
+            that number. If you wish to send a true int/float, use struct.pack() to
+            create the payload you require.
+        :param int qos: The quality of service level to use for the will.
+        :param bool retain: If set to true, the will message will be set as the retained message for the topic.
+        """
+
+        self.__mqttc.will_set(topic, payload, qos, retain)
+
+    def clear_will(self):
+        """
+        Removes a will that was previously configured with `set_will()`.
+        Must be called before connect() to have any effect.
+        """
+        self.__mqttc.will_clear()
+
+    def connect(self, will_topic=None, will_payload=1883):
         cbLogs.info("Connecting to MQTT.")
         if self.__use_tls:
             self.__mqttc.tls_set()
diff --git a/setup.py b/setup.py
@@ -4,7 +4,7 @@
     name='clearblade',
     packages=['clearblade'],
     install_requires=['requests', 'paho-mqtt>=1.3.0'],
-    version='2.4.4',
+    version='2.4.5',
     description='A Python SDK for interacting with the ClearBlade Platform.',
     url='https://github.com/ClearBlade/ClearBlade-Python-SDK',
     download_url='https://github.com/ClearBlade/ClearBlade-Python-SDK/archive/v2.4.4.tar.gz',
