API Documentation

Flask-MQTT Package.

author:Stefan Lehmann <stlm@posteo.de>
license:MIT, see license file or https://opensource.org/licenses/MIT
class flask_mqtt.Mqtt(app: flask.app.Flask = None, connect_async: bool = False, mqtt_logging: bool = False)[source]

Bases: object

Main Mqtt class.

Parameters:
  • app – flask application object
  • connect_async – if True then connect_aync will be used to connect to MQTT broker
  • mqtt_logging – if True then messages from MQTT client will be logged
init_app(app: flask.app.Flask) → None[source]

Init the Flask-MQTT addon.

on_connect() → Callable[source]

Decorator.

Decorator to handle the event when the broker responds to a connection request. Only the last decorated function will be called.

on_disconnect() → Callable[source]

Decorator.

Decorator to handle the event when client disconnects from broker. Only the last decorated function will be called.

on_log() → Callable[source]

Decorate a callback function to handle MQTT logging.

Example Usage:

@mqtt.on_log()
def handle_logging(client, userdata, level, buf):
    print(client, userdata, level, buf)
on_message() → Callable[source]

Decorator.

Decorator to handle all messages that have been subscribed and that are not handled via the on_message decorator.

Note: Unlike as written in the paho mqtt documentation this callback will not be called if there exists an topic-specific callback added by the on_topic decorator.

Example Usage::

@mqtt.on_message()
def handle_messages(client, userdata, message):
    print('Received message on topic {}: {}'
          .format(message.topic, message.payload.decode()))
on_publish() → Callable[source]

Decorator.

Decorator to handle all messages that have been published by the client.

Example Usage::

@mqtt.on_publish()
def handle_publish(client, userdata, mid):
    print('Published message with mid {}.'
          .format(mid))
on_subscribe() → Callable[source]

Decorate a callback function to handle subscritions.

Usage::

@mqtt.on_subscribe()
def handle_subscribe(client, userdata, mid, granted_qos):
    print('Subscription id {} granted with qos {}.'
          .format(mid, granted_qos))
on_topic(topic: str) → Callable[source]

Decorator.

Decorator to add a callback function that is called when a certain topic has been published. The callback function is expected to have the following form: handle_topic(client, userdata, message)

Parameters:topic – a string specifying the subscription topic to subscribe to

The topic still needs to be subscribed via mqtt.subscribe() before the callback function can be used to handle a certain topic. This way it is possible to subscribe and unsubscribe during runtime.

Example usage::

app = Flask(__name__)
mqtt = Mqtt(app)
mqtt.subscribe('home/mytopic')

@mqtt.on_topic('home/mytopic')
def handle_mytopic(client, userdata, message):
    print('Received message on topic {}: {}'
          .format(message.topic, message.payload.decode()))
on_unsubscribe() → Callable[source]

Decorate a callback funtion to handle unsubscribtions.

Usage::

@mqtt.unsubscribe()
def handle_unsubscribe(client, userdata, mid)
    print('Unsubscribed from topic (id: {})'
          .format(mid)')
publish(topic: str, payload: Optional[bytes] = None, qos: int = 0, retain: bool = False) → Tuple[int, int][source]

Send a message to the broker.

Parameters:
  • topic – the topic that the message should be published on
  • payload – the actual message to send. If not given, or set to None a zero length message will be used. 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.
  • qos – 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
Returns:

Returns a tuple (result, mid), where result is MQTT_ERR_SUCCESS to indicate success or MQTT_ERR_NO_CONN if the client is not currently connected. mid is the message ID for the publish request.

subscribe(topic: str, qos: int = 0) → Tuple[int, int][source]

Subscribe to a certain topic.

Parameters:
  • topic – a string specifying the subscription topic to subscribe to.
  • qos – the desired quality of service level for the subscription. Defaults to 0.
Return type:

(int, int)

Result:

(result, mid)

A topic is a UTF-8 string, which is used by the broker to filter messages for each connected client. A topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator).

The function returns a tuple (result, mid), where result is MQTT_ERR_SUCCESS to indicate success or (MQTT_ERR_NO_CONN, None) if the client is not currently connected. mid is the message ID for the subscribe request. The mid value can be used to track the subscribe request by checking against the mid argument in the on_subscribe() callback if it is defined.

Topic example: myhome/groundfloor/livingroom/temperature

unsubscribe(topic: str) → Optional[Tuple[int, int]][source]

Unsubscribe from a single topic.

Parameters:topic – a single string that is the subscription topic to unsubscribe from
Return type:(int, int)
Result:(result, mid)

Returns a tuple (result, mid), where result is MQTT_ERR_SUCCESS to indicate success or (MQTT_ERR_NO_CONN, None) if the client is not currently connected. mid is the message ID for the unsubscribe request. The mid value can be used to track the unsubscribe request by checking against the mid argument in the on_unsubscribe() callback if it is defined.

unsubscribe_all() → None[source]

Unsubscribe from all topics.

class flask_mqtt.TopicQos(topic, qos)

Bases: tuple

Container for topic + qos

qos

Alias for field number 1

topic

Alias for field number 0