MQTT API Reference
A list of API calls and information specific to the MQTT plugin.
App Creation
To create apps based on just the MQTT API, use some code like the following:
import mqttapi as mqtt
class MyApp(mqtt.Mqtt):
def initialize(self):
Making Calls to MQTT
The MQTT Plugin uses the inherited call_service()
helper function the AppDaemon API,
to carry out service calls from within an AppDaemon app. See the documentation of this
function here
for a detailed description.
The function call_service()
allows the app to carry out one of the following services:
mqtt/publish
mqtt/subscribe
mqtt/unsubscribe
By simply specifying 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. See the section on namespaces
for a detailed description.
Examples
# if wanting to publish data to a broker
self.call_service("mqtt/publish", topic = "homeassistant/bedroom/light", payload = "ON")
# if wanting to unsubscribe a topic from a broker in a different namespace
self.call_service("mqtt/unsubscribe", topic = "homeassistant/bedroom/light", namespace = "mqtt2")
The MQTT API also provides 3 convenience functions to make calling of specific functions easier and more readable. These are documented in the following section.
Reference
Services
- appdaemon.plugins.mqtt.mqttapi.Mqtt.mqtt_subscribe(self, topic: str | list, **kwargs: Any | None) None
Subscribes to a MQTT topic.
This 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.- Parameters:
- Keyword Arguments:
namespace (str, 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.
- Returns:
None.
Examples
>>> self.mqtt_subscribe("homeassistant/bedroom/light") >>> self.mqtt_subscribe(["homeassistant/bedroom/light", "zigbee2mqtt/Living Room Light"])
- appdaemon.plugins.mqtt.mqttapi.Mqtt.mqtt_unsubscribe(self, topic: str | list, **kwargs: Any | None) None
Unsubscribes from a MQTT topic.
A helper function used to unsubscribe 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.- Parameters:
- Keyword Arguments:
namespace (str, 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.
- Returns:
None.
Examples
>>> self.mqtt_unsubscribe("homeassistant/bedroom/light")
- appdaemon.plugins.mqtt.mqttapi.Mqtt.mqtt_publish(self, topic: str, payload: Any = None, **kwargs: Any | None) None
Publishes a message to a MQTT broker.
This 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.- Parameters:
topic (str) – topic the payload is to be sent to on the broker (e.g.,
homeassistant/bedroom/light
).payload – data that is to be sent to on the broker (e.g.,
'ON'
).**kwargs (optional) – Zero or more keyword arguments.
- Keyword Arguments:
qos (int, optional) – The Quality of Service (QOS) that is to be used when sending the data to the broker. This is has to be an integer (Default value:
0
).retain (bool, optional) – This flag is used to specify if the broker is to retain the payload or not (Default value:
False
).namespace (str, 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.
- Returns:
None.
Examples:
Send data to the default HA broker.
>>> self.mqtt_publish("homeassistant/bedroom/light", "ON")
Send data to a different broker.
>>> self.mqtt_publish("homeassistant/living_room/light", "ON", qos = 0, retain = True, namespace = "mqtt2")
- appdaemon.plugins.mqtt.mqttapi.Mqtt.is_client_connected(self, **kwargs: Any | None) bool
Returns
TRUE
if the MQTT plugin is connected to its broker,FALSE
otherwise.This a helper function used to check or confirm within an app if the plugin is connected to its broker. This can be useful, if it is necessary to be certain the client is connected, so if not the app can internally store the data in a queue, and wait for connection before sending the data.
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.- Parameters:
**kwargs (optional) – Zero or more keyword arguments.
- Keyword Arguments:
namespace (str, 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.
- Returns:
Boolean.
Examples
Check if client is connected, and send data. >>> if self.clientConnected(): >>> self.mqtt_publish(topic, payload)
Check if client is connected in mqtt2 namespace, and send data.
>>> if self.clientConnected(namespace = 'mqtt2'): >>> self.mqtt_publish(topic, payload, namespace = 'mqtt2')
Events
- appdaemon.plugins.mqtt.mqttapi.Mqtt.listen_event(self, callback: Callable, event: str = None, **kwargs: Any | None) str
Listens for changes within the MQTT plugin.
Unlike other plugins, MQTT does not keep state. All MQTT messages will have an event which is set to
MQTT_MESSAGE
by default. This can be changed to whatever that is required in the plugin configuration.- Parameters:
callback – Function to be invoked when the requested event 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.**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 or wildcard 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 we want to listen to a specific topic or wildcard,
topic
orwildcard
can be passed in, and used to filter the callback by supplying them as keyword arguments. If you include keyword values, the values supplied to thelisten_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. If using
wildcard
, only those used to subscribe to the broker can be used as wildcards. The plugin supports the use both single and multi-level wildcards.
- Keyword Arguments:
namespace (str, 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.
binary (bool, optional) – If wanting the payload to be returned as binary, this should be specified. If not given, AD will return the payload as decoded data. It should be noted that it is not possible to have different apps receieve both binary and non-binary data on the same topic
- Returns:
A handle that can be used to cancel the callback.
Examples
Listen all events.
>>> self.listen_event(self.mqtt_message_received_event, "MQTT_MESSAGE")
Listen events for a specific subscribed topic.
>>> self.listen_event(self.mqtt_message_received_event, "MQTT_MESSAGE", topic='homeassistant/bedroom/light')
Listen events for a specific subscribed high level topic.
>>> self.listen_event(self.mqtt_message_received_event, "MQTT_MESSAGE", wildcard='homeassistant/#')
>>> self.listen_event(self.mqtt_message_received_event, "MQTT_MESSAGE", wildcard='homeassistant/+/motion')
Listen events for binary payload
>>> self.listen_event(self.mqtt_message_received_event, "MQTT_MESSAGE", topic='hermes/audioServer/#', binary=True)
Listen plugin’s disconnected events from the broker.
>>> self.listen_event(self.mqtt_message_received_event, "MQTT_MESSAGE", state='Disconnected', topic=None)
Listen plugin’s’ connected events from the broker.
>>> self.listen_event(self.mqtt_message_received_event, "MQTT_MESSAGE", state='Connected', topic=None)
Notes
At this point, it is not possible to use single level wildcard like using
homeassistant/+/light
instead ofhomeassistant/bedroom/light
. This could be added later, if need be.
MQTT Config
Developers can get the MQTT configuration data (i.e., client_id or username) using the
helper function get_plugin_config()
inherited from the AppDaemon API. See the
documentation of this function here
for a detailed description.
See More
Read the AppDaemon API Reference to learn other inherited helper functions that can be used by Hass applications.