MQTT API Reference¶
A list of API calls and information specific to the MQTT plugin.
Service Calls¶
call_service()¶
call_service()
is used to carry out service calls from within an AppDaemon app. This allows the app to carry out one of the following services:Publish
Subscribe
Unsubscribe
By simply specifing within the function what is to be done. It uses configuration specified in the plugin configuration which simplifies the call within the app significantly. Different brokers can be accessed within an app, as long as they are all declared
when the plugins are configured, and using the namespace
parameter.
Synopsis¶
self.call_service(self, service, **kwargs)
Returns¶
None
Parameters¶
Service¶
The service to be carried out on the broker e.g. publish
.
Topic¶
The topic the service is targeted at on the broker e.g. homeassistant/bedroom/light
. This outside the service parameter is the most important keyword argument required.
Examples¶
mqtt_publish()¶
mqtt_publish()
is a helper function used for publishing a MQTT message to a broker, from within an AppDaemon app.
It uses configuration specified in the plugin configuration which simplifies the call within the app significantly. Different brokers can be accessed within an app, as long as they are all declared
when the plugins are configured, and using the namespace
parameter.
Synopsis¶
self.mqtt_publish(self, topic, payload, qos = 0, retain = False, **kwargs)
Returns¶
None
Parameters¶
Topic¶
The topic the payload is to be sent to on the broker e.g. homeassistant/bedroom/light
.
Payload¶
The data that is to be sent to on the broker e.g. 'ON'
.
QOS¶
The Quality of Service (QOS) that is to be used when sending the data to the broker. This is has to be an integer. This defaults to 0
Retain¶
This flag is used to specify if the broker is to retain the payload or not. This defaults to False
.
namespace = (optional)¶
Namespace to use for the service - see the section on namespaces for a detailed description. In most cases it is safe to ignore this parameter
**kwargs¶
Each service has different parameter requirements. This argument allows
you to specify a comma separated list of keyword value pairs, e.g.
qos = 0
or retain = True
.
Examples¶
self.mqtt_publish("homeassistant/bedroom/light", "ON")
# if wanting to send data to a different broker
self.mqtt_publish("homeassistant/living_room/light", "ON", qos = 0, retain = True, namepace = "mqtt2")
mqtt_subscribe()¶
mqtt_subscribe()
is a helper function used for subscribing to a topic on a broker, from within an AppDaemon app. This allows the
apps to now access events from that topic, in realtime. So outside the initial configuration at plugin config, this allows access to other topics while the apps runs. It should be noted that if Appdaemon was to reload, the topics subscribed via this function will not be available by default. On those declared at the plugin config will always be available.
It uses configuration specified in the plugin configuration which simplifies the call within the app significantly. Different brokers can be accessed within an app, as long as they are all declared
when the plugins are configured, and using the namespace
parameter.
Synopsis¶
self.mqtt_subscribe(self, topic, **kwargs)
Returns¶
None
mqtt_unsubscribe()¶
mqtt_unsubscribe()
is a helper function used for unsubscribing from a topic on a broker, from within an AppDaemon app. This denies the apps access events from that topic, in realtime. It is possible to unsubscribe from topics, even if they were part of the topics in the plugin config; but it is not possible to unsubscribe #
. It should also be noted that if Appdaemon was to reload, the topics unsubscribed via this function will be available if they were configured with the plugin by default.
It uses configuration specified in the plugin configuration which simplifies the call within the app significantly. Different brokers can be accessed within an app, as long as they are all declared
when the plugins are configured, and using the namespace
parameter.
Synopsis¶
self.mqtt_unsubscribe(self, topic, **kwargs)
Returns¶
None
Events¶
listen_event()¶
This is the primary way of listening for changes within the MQTT plugin - unlike other plugins, MQTT does not keep state. All MQTT messages will have an event type of MQTT_EVENT
Synopsis¶
handle = listen_event(callback, event = None, **kwargs):
Returns¶
A handle that can be used to cancel the callback.
Parameters¶
callback¶
Function to be invoked when the requested state change occurs. It must conform to the standard Event Callback format documented Here.
event¶
Name of the event to subscribe to. Can be the declared event_name
parameter as specified
in the plugin configuration. If no event is specified, listen_event()
will
subscribe to all MQTT events within the app’s functional namespace.
namespace = (optional)¶
Namespace to use for the call - see the section on namespaces for a detailed description. In most cases it is safe to ignore this parameter. The value global
for namespace has special significance, and means that the callback will lsiten to state updates from any plugin.
**kwargs (optional)¶
One or more keyword value pairs representing App specific parameters to supply to the callback. If the keywords match values within the event data, they will act as filters, meaning that if they don’t match the values, the callback will not fire.
As an example of this, a specific topic can be listened to, instead of listening to all topics subscribed to.
For example if data is sent to a subscribed topic, it will generate an event as specified in the config;
if wanting to listen to a specific topic, topic
can be passed in the filter the callback by supplying keyworded
arguments. If you include keyword values, the values supplied to the `listen_event()` call must match the values in the event or it
will not fire. If the keywords do not match any of the data in the event
they are simply ignored.
Filtering will work with any event type, but it will be necessary to figure out the data associated with the event to understand what values can be filtered on.
Examples¶
self.listen_event(self.mqtt_message_recieved_event, "MQTT_MESSAGE")
#Listen for when a specific subscribed topic gets some data:
self.listen_event(self.mqtt_message_recieved_event, "MQTT_MESSAGE", topic = 'homeassistant/bedroom/light')
MQTT Config¶
get_plugin_config()¶
Get the MQTT configuration data such as client_id or username. This can also be used to get the configuration of other plugins like if connected to a Home Assistant insteace, this can be used to access the Longitude and Latitude data of the Hass instance
Synopsis¶
get_plugin_config()
Returns¶
A dictionary containing all the configuration information available from the MQTT plugin.
Examples¶
config = self.get_plugin_config()
self.log("Current Client ID is {}".format(config["client_id"]))