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: An interface to the current property value. The
value
field will be updated with the most recent value of the property. Setting thevalue
will cause the property to be writtenWhen you’re finished with it either call PropertyWatcher.close or
Client.unwatch_property(topic, p)
wheretopic
is the topic of the property andp
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.
-