Reference Python Implementation API

Install using:

$ pip install qth

A reference implementation of the Qth home-automation oriented conventions for MQTT.

class qth.Client(client_id, description=None, loop=None, make_client_id_unique=True, host=None, port=None, keepalive=10)

Connect to an MQTT server.

Parameters:

client_id : str

A unique identifier for this client. (Required) Will be prepended with a randomly generated suffix to avoid collisions when several instances of the same client are created. Set make_client_id_unique to False to disable this behaviour.

description : str

A human-readable description of the client. Defaults to being empty.

loop : asyncio.AbstractEventLoop

The asyncio event loop to run in. If omitted or None, uses the default loop.

make_client_id_unique : bool

If set to False, don’t add a unique, random suffix to the client_id.

host : str

The hostname of the MQTT server. (Defaults to the value of the QTH_HOST environment variable, or if that is not set, localhost).

port : int

The port number of the MQTT server. (Defaults to the value of the QTH_PORT environment variable, or if that is not set, 1883).

keepalive : float

Number of seconds between pings to the MQTT server.

register(path, behaviour, description, on_unregister=_NOT_GIVEN, delete_on_unregister=False)

Coroutine. Register a path with the Qth registration system.

Parameters:

path : string

The topic path for the endpoint being registered.

behaviour : string

The qth behaviour name which describes how this endpoint will be used.

description : string

A human-readable string describing the purpose or higher-level behaviour of the endpoint.

on_unsubscribe : JSON-serialisable value

If given the on disconnection (either clean or dirty), sets the value of the registered proprety/sends the registered event with the given value.

delete_on_unregister : bool

If true, deletes the registered property. If set to True for an event, behaviour is undefined. If set at the same time as on_subscribe, behaviour is undefined.

unregister(path)

Coroutine. Unregister a path with the Qth registration system.

Parameters:

path : string

The path to unregister.

send_event(topic, value=None)

Coroutine. Sends a Qth event.

Parameters:

topic : str

The topic of the event.

value : JSON-serialiseable

(Optional) JSON-serialiseable value to send with the event.

watch_event(topic, callback)

Coroutine. Calls a callback whenever a Qth event occurs.

Parameters:

topic : str

The topic of the event.

callback : function or coroutine

This function or coroutine is called with the event topic and deserialised value of the event when the event occurs.

unwatch_event(topic, callback)

Coroutine. Stop watching a particular Qth event.

set_property(topic, value)

Coroutine which sets the value of a Qth property.

Parameters:

topic : str

The topic of the property.

value : JSON-serialiseable

JSON-serialiseable value to set the property to.

get_property(topic)

Coroutine which returns a PropertyWatcher object.

Blocks until the property value is known.

Parameters:

topic : str

The topic of the property. Must not be a wildcard!

Returns:

PropertyWatcher

An interface to the current property value. The value field will be updated with the most recent value of the property. Setting the value will cause the property to be written

When you’re finished with it either call PropertyWatcher.close or Client.unwatch_property(topic, p) where topic is the topic of the property and p is the PropertyWatcher.

watch_property(topic, callback)

Coroutine which calls a callback whenever a Qth property is set.

Parameters:

topic : str

The topic of the property. Must not be a wildcard!

callback : function or coroutine

This function or coroutine is called with the topic and deserialised value of the property when the property value is set.

unwatch_property(topic, callback)

Coroutine. Stop watching a particular Qth property.

delete_property(topic)

Coroutine which deletes a Qth property. Watchers will receive a final value of qth.Empty.

Parameters:

topic : str

The topic of the property to delete.

publish_registration(force=False)

Coroutine. For advanced users only. Publish the Qth client registration message, if connected.

This method is called automatically upon (re)connection and when the registration is changed. It is unlikely you’ll need to call this by hand.

Parameters:

force : bool

If true, force the registration to be sent, even if it hasn’t changed.

subscribe(topic, callback, retain_all=False)

For advanced users only. Coroutine which subscribes to a MQTT topic (with QoS 2) and registers a callback for message arrival on that topic. Returns once the subscription has been confirmed.

If the client reconnects, the subscription will be automatically renewed.

Many callbacks may be associated with the same topic pattern. See the description of the retain_all flag.

Parameters:

topic : str

The topic to subscribe to.

callback : function or coroutine

A callback function or coroutine to call when a message matching this subscription is received. The function will be called with a two arguments: the topic and the deserialised payload.

retain_all : bool

If True, treat all received messages on this topic as retained. Future subscriptions to the same topic will always immediately receive a copy of the most recent message matching the subscription.

If False, only the first subscription to a given topic will receive the server-retained message, if any. Future subscriptions to the same topic will only receive subsequent messages.

This option is a work-around for MQTT not exposing when a received message was sent with the retain flag.

All subscribers to a particular topic must set this argument to the same value.

unsubscribe(topic, callback)

Coroutine. For advanced users only. Unsubscribe from a topic.

Parameters:

topic : str

The topic pattern used when subscribing.

callback : function or coroutine

The callback or coroutine used when subscribing.

publish(topic, payload, retain=False)

Coroutine. For advanced users only. Publish a message with QoS 2, waiting until connected and the publication has been acknowledged.

Parameters:

topic : str

The topic to publish to

payload : JSON-serialiseable value or qth.Empty

The payload of the message. Will be sent seriallised as JSON or if qth.Empty is passed, will be a completely empty MQTT message.

retain : bool

Should the message be retained by the MQTT server?

ensure_connected()

For advanced users only (most commands call this internally). Coroutine. Block until the client has connected to the MQTT server and all registration and subscription commands have completed.

close()

Coroutine. Permanently close the connection to the MQTT server.

client_id

This client’s Qth client ID.

qth.Empty = Empty

Payload value to send to generate a genuinely empty MQTT message.

qth.EVENT_ONE_TO_MANY = 'EVENT-1:N'

Behaviour name for One-to-Many Events.

qth.EVENT_MANY_TO_ONE = 'EVENT-N:1'

Behaviour name for Many-to-One Events.

qth.PROPERTY_ONE_TO_MANY = 'PROPERTY-1:N'

Behaviour name for One-to-Many Properties.

qth.PROPERTY_MANY_TO_ONE = 'PROPERTY-N:1'

Behaviour name for Many-to-One Properties.

qth.DIRECTORY = 'DIRECTORY'

Behaviour used for directory entries in a Qth registry’s directory listing. Not to be used by regular clients.

exception qth.MQTTError(code)

Thrown when an MQTT-related error occurs. Has a ‘code’ member variable indicating the Paho-MQTT error code.

class qth.PropertyWatcher(client, topic)

Using the supplied client, watch the supplied property.

value

The most recently received property value. If no value has yet been received, this value will be qth.Empty.

Calling PropertyWatcher.wait will wait until this property has a valid value.

wait()

Wait until the value of the property is known.

close()

Permanently stop watching the property, invalidating the value of this object.