Lightweight MQTT Library¶
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 (
class Client(client_id, clean_session=True, cycle_timeout=500, command_timeout=60000)
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
clean_sessionset to true.
- clean_session – when
Truerequests the broker to assign a clean state to connecting client without remembering previous subscriptions or other configurations.
- cycle_timeout – maximum time to wait for received messages on every loop cycle (in milliseconds)
- command_timeout – maximum time to wait for protocol commands to be acknowledged (in milliseconds)
Instantiates the MQTT Client.
connect(host, keepalive, port=1883, ssl_ctx=None, breconnect_cb=None, aconnect_cb=None, loop_failure=None, start_loop=True)
- host – hostname or IP address of the remote broker.
- port – network port of the server host to connect to, defaults to 1883.
- 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.
- ssl_ctx – optional ssl context (Zerynth SSL module) for secure mqtt channels.
- breconnect_cb – optional callback with actions to be performed when
reconnect()is called. The callback function will be called passing mqtt client instance.
- aconnect_cb – optional callback with actions to be performed after the client successfully connects. The callback function will be called passing mqtt client instance.
- 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
mqtt.BREAK_LOOP, the read loop is terminated on failures.
loop_failurecallback must return
mqtt.RECOVEREDto keep the MQTT read cycle alive.
- start_loop – if
Truestarts the MQTT read cycle after connection.
Connects to a remote broker and start the MQTT reception thread.
Get the return code of the last connection attempt.
Tries to connect again with previously set connection parameters.
breconnect_cb was passed to
breconnect_cb is executed first.
Return the return code of the connection.
True if client is connected,
Starts MQTT background loop to handle incoming packets.
Already called by
- username – connection username.
- password – connection password.
Sets connection username and password.
publish(topic, payload='', qos=0, retain=False)
- topic – topic the message should be published on.
- payload – actual message to send. If not given a zero length message will be used.
- qos – is the quality of service level to use.
- 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.
subscribe(topic, function, qos=0)`*
- topic – topic to subscribe to.
- function – callback to be executed when a message published on chosen topic is received.
- 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 ...
Unsubscribes the client from one topic.
Arguments: topic – is the string representing the subscribed topic to unsubscribe from.
Sends a disconnect message, optionally waiting for the loop to exit.
Arguments: timeout – is the maximum time to wait (in milliseconds).