.. module:: mqtt ************************ Lightweight MQTT Library ************************ This module contains an implementation of an MQTT client based on the `paho-project `_ `embedded c client `_. It aims to be less memory consuming than the pure Python one. The Client allows to connect to a broker (both via insecure and TLS channels) and start publishing messages/subscribing to topics with a simple interface. Python callbacks can be easily set to handle incoming messages. Reconnection can be manually handled by the user by means of several callbacks and methods (:meth:`reconnect`, :meth:`connected`, ``loop_failure``) ============ Client class ============ .. class:: Client(client_id, clean_session=True, cycle_timeout=500, command_timeout=60000) :param client_id: unique ID of the MQTT Client (multiple clients connecting to the same broken with the same ID are not allowed), can be an empty string with :samp:`clean_session` set to true. :param clean_session: when ``True`` requests the broker to assign a clean state to connecting client without remembering previous subscriptions or other configurations. :param cycle_timeout: maximum time to wait for received messages on every loop cycle (in milliseconds) :param command_timeout: maximum time to wait for protocol commands to be acknowledged (in milliseconds) Instantiates the MQTT Client. .. method:: connect(host, keepalive, port=1883, ssl_ctx=None, breconnect_cb=None, aconnect_cb=None, loop_failure=None, start_loop=True) :param host: hostname or IP address of the remote broker. :param port: network port of the server host to connect to, defaults to 1883. :param keepalive: maximum period in seconds between communications with the broker. If no other messages are being exchanged, this controls the rate at which the client will send ping messages to the broker. :param ssl_ctx: optional ssl context (:ref:`Zerynth SSL module `) for secure mqtt channels. :param breconnect_cb: optional callback with actions to be performed when :meth:`reconnect` is called. The callback function will be called passing mqtt client instance. :param aconnect_cb: optional callback with actions to be performed after the client successfully connects. The callback function will be called passing mqtt client instance. :param loop_failure: optional callback with actions to be performed on failures happening during the MQTT read cycle. The user should try to implement client reconnection logic here. By default, or if ``loop_failure`` callback returns ``mqtt.BREAK_LOOP``, the read loop is terminated on failures. ``loop_failure`` callback must return ``mqtt.RECOVERED`` to keep the MQTT read cycle alive. :param start_loop: if ``True`` starts the MQTT read cycle after connection. Connects to a remote broker and start the MQTT reception thread. .. method:: get_return_code() Get the return code of the last connection attempt. .. method:: reconnect() Tries to connect again with previously set connection parameters. If ``breconnect_cb`` was passed to :meth:`connect`, ``breconnect_cb`` is executed first. Return the return code of the connection .. method:: connected() Returns ``True`` if client is connected, ``False`` otherwise. .. method:: loop() Starts MQTT background loop to handle incoming packets. Already called by :meth:`connect` if ``start_loop`` is ``True``. .. method:: set_username_pw(username, password='') :param username: connection username. :param password: connection password. Sets connection username and password. .. method:: set_will(topic, payload, qos=0, retain=True) :param topic: last will topic. :param payload: last will payload. :param qos: last will qos value. :param retain: last will retain flag. Set client last will and testament. .. method:: publish(topic, payload='', qos=0, retain=False) :param topic: topic the message should be published on. :param payload: actual message to send. If not given a zero length message will be used. :param qos: is the quality of service level to use. :param retain: if set to true, the message will be set as the "last known good"/retained message for the topic. Publishes a message on a topic. This causes a message to be sent to the broker and subsequently from the broker to any clients subscribing to matching topics. .. method:: subscribe(topic, function, qos=0) :param topic: topic to subscribe to. :param function: callback to be executed when a message published on chosen topic is received. :param qos: quality of service for the subscription. Subscribes to a topic and set a callback for processing messages published on it. The callback function is called passing three parameters: the MQTT client object, the payload of received message and the actual topic:: def my_callback(mqtt_client, payload, topic): # do something with client, payload and topic ... .. method:: unsubscribe(topic) Unsubscribes the client from one topic. :param topic: is the string representing the subscribed topic to unsubscribe from. .. method:: disconnect(timeout=None) Sends a disconnect message, optionally waiting for the loop to exit. :param timeout: is the maximum time to wait (in milliseconds).