mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-05-03 09:38:59 +00:00
160 lines
6.3 KiB
Markdown
160 lines
6.3 KiB
Markdown
---
|
||
title: "MQTT Device trigger"
|
||
description: "Instructions on how to integrate MQTT device triggers within Home Assistant."
|
||
ha_category:
|
||
- Device automation
|
||
ha_release: 0.106
|
||
ha_iot_class: Configurable
|
||
ha_domain: mqtt
|
||
---
|
||
|
||
The `mqtt` device trigger platform uses an MQTT message payload to generate device trigger events.
|
||
|
||
An MQTT device trigger is a better option than a [binary sensor](/integrations/binary_sensor.mqtt/) for buttons, remote controls etc.
|
||
|
||
## Configuration
|
||
|
||
MQTT device triggers are only supported through [MQTT discovery](/integrations/mqtt/#mqtt-discovery), manual setup through {% term "`configuration.yaml`" %} is not supported.
|
||
The discovery topic needs to be: `<discovery_prefix>/device_automation/[<node_id>/]<object_id>/config`. Note that only one trigger may be defined per unique discovery topic. Also note that the combination of `type` and `subtype` should be unique for a device.
|
||
|
||
{% configuration %}
|
||
automation_type:
|
||
description: The type of automation, must be 'trigger'.
|
||
required: true
|
||
type: string
|
||
payload:
|
||
description: Optional payload to match the payload being sent over the topic.
|
||
required: false
|
||
type: string
|
||
platform:
|
||
description: Must be `device_automation`. Only allowed and required in [MQTT auto discovery device messages](/integrations/mqtt/#device-discovery-payload).
|
||
required: true
|
||
type: string
|
||
qos:
|
||
description: The maximum QoS level to be used when receiving and publishing messages.
|
||
required: false
|
||
type: integer
|
||
default: 0
|
||
topic:
|
||
description: The MQTT topic subscribed to receive trigger events.
|
||
required: true
|
||
type: string
|
||
type:
|
||
description: "The type of the trigger, e.g. `button_short_press`. Entries supported by the frontend: `button_short_press`, `button_short_release`, `button_long_press`, `button_long_release`, `button_double_press`, `button_triple_press`, `button_quadruple_press`, `button_quintuple_press`. If set to an unsupported value, will render as `subtype type`, e.g. `button_1 spammed` with `type` set to `spammed` and `subtype` set to `button_1`"
|
||
required: true
|
||
type: string
|
||
subtype:
|
||
description: "The subtype of the trigger, e.g. `button_1`. Entries supported by the frontend: `turn_on`, `turn_off`, `button_1`, `button_2`, `button_3`, `button_4`, `button_5`, `button_6`. If set to an unsupported value, will render as `subtype type`, e.g. `left_button pressed` with `type` set to `button_short_press` and `subtype` set to `left_button`"
|
||
required: true
|
||
type: string
|
||
device:
|
||
description: "Information about the device this device trigger is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). At least one of identifiers or connections must be present to identify the device."
|
||
required: true
|
||
type: map
|
||
keys:
|
||
configuration_url:
|
||
description: 'A link to the webpage that can manage the configuration of this device. Can be either an `http://`, `https://` or an internal `homeassistant://` URL.'
|
||
required: false
|
||
type: string
|
||
connections:
|
||
description: 'A list of connections of the device to the outside world as a list of tuples `[connection_type, connection_identifier]`. For example the MAC address of a network interface: `"connections": [["mac", "02:5b:26:a8:dc:12"]]`.'
|
||
required: false
|
||
type: list
|
||
identifiers:
|
||
description: A list of IDs that uniquely identify the device. For example a serial number.
|
||
required: false
|
||
type: [list, string]
|
||
manufacturer:
|
||
description: The manufacturer of the device.
|
||
required: false
|
||
type: string
|
||
model:
|
||
description: The model of the device.
|
||
required: false
|
||
type: string
|
||
model_id:
|
||
description: The model identifier of the device.
|
||
required: false
|
||
type: string
|
||
name:
|
||
description: The name of the device.
|
||
required: false
|
||
type: string
|
||
serial_number:
|
||
description: "The serial number of the device."
|
||
required: false
|
||
type: string
|
||
suggested_area:
|
||
description: 'Suggest an area if the device isn’t in one yet.'
|
||
required: false
|
||
type: string
|
||
sw_version:
|
||
description: The firmware version of the device.
|
||
required: false
|
||
type: string
|
||
via_device:
|
||
description: 'Identifier of a device that routes messages between this device and Home Assistant. Examples of such devices are hubs, or parent devices of a sub-device. This is used to show device topology in Home Assistant.'
|
||
required: false
|
||
type: string
|
||
value_template:
|
||
description: "Defines a [template](/docs/configuration/templating/#using-value-templates-with-mqtt) to extract the value."
|
||
required: false
|
||
type: template
|
||
{% endconfiguration %}
|
||
|
||
### Example
|
||
|
||
This shows a complete example of defining a remote control type device with two triggers: "left arrow click" and "right arrow click".
|
||
|
||
Note that it is not necessary to provide the full device information in each message, but the identifying information, `identifier` in the example, must be the same.
|
||
|
||
#### Left arrow click configuration
|
||
|
||
- Discovery topic: `homeassistant/device_automation/0x90fd9ffffedf1266/action_arrow_left_click/config`
|
||
- Discovery payload:
|
||
|
||
```json
|
||
{
|
||
"automation_type": "trigger",
|
||
"type": "action",
|
||
"subtype": "arrow_left_click",
|
||
"payload": "arrow_left_click",
|
||
"topic": "zigbee2mqtt/0x90fd9ffffedf1266/action",
|
||
"device": {
|
||
"identifiers": [
|
||
"zigbee2mqtt_0x90fd9ffffedf1266"
|
||
],
|
||
"name": "0x90fd9ffffedf1266",
|
||
"sw_version": "Zigbee2MQTT 1.14.0",
|
||
"model": "TRADFRI remote control (E1524/E1810)",
|
||
"manufacturer": "IKEA"
|
||
}
|
||
}
|
||
```
|
||
|
||
- Trigger topic: `zigbee2mqtt/0x90fd9ffffedf1266/action`
|
||
- Trigger payload: `arrow_left_click`
|
||
|
||
#### Right arrow click configuration
|
||
|
||
- Discovery topic: `homeassistant/device_automation/0x90fd9ffffedf1266/action_arrow_right_click/config`
|
||
- Discovery payload:
|
||
|
||
```json
|
||
{
|
||
"automation_type": "trigger",
|
||
"type": "action",
|
||
"subtype": "arrow_right_click",
|
||
"payload": "arrow_right_click",
|
||
"topic": "zigbee2mqtt/0x90fd9ffffedf1266/action",
|
||
"device": {
|
||
"identifiers": [
|
||
"zigbee2mqtt_0x90fd9ffffedf1266"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
- Trigger topic: `zigbee2mqtt/0x90fd9ffffedf1266/action`
|
||
- Trigger payload: `arrow_right_click`
|