Mqtt device trigger (home-assistant#12200)

source/_docs/mqtt/discovery.markdown

@@ -12,6 +12,7 @@ Supported by MQTT discovery:
 - [Binary sensors](/integrations/binary_sensor.mqtt/)
 - [Cameras](/integrations/camera.mqtt/)
 - [Covers](/integrations/cover.mqtt/)
+- [Device Triggers](/integrations/device_trigger.mqtt/)
 - [Fans](/integrations/fan.mqtt/)
 - [HVACs](/integrations/climate.mqtt/)
 - [Lights](/integrations/light.mqtt/)

source/_integrations/binary_sensor.mqtt.markdown

@@ -14,6 +14,8 @@ The binary sensor state will be updated only after a new message is published on
 the binary sensor will receive an instant state update after subscription and Home Assistant will display the correct state on startup.
 Otherwise, the initial state displayed in Home Assistant will be `unknown`.
 
+Stateless devices such as buttons, remote controls etc are better represented by [MQTT device triggers](/integrations/device_trigger.mqtt/) than by binary sensors.
+
 ## Configuration
 
 The `mqtt` binary sensor platform optionally supports an `availability_topic` to receive online and offline messages (birth and LWT messages) from the MQTT device. During normal operation, if the MQTT sensor device goes offline (i.e., publishes `payload_not_available` to `availability_topic`), Home Assistant will display the binary sensor as `unavailable`. If these messages are published with the `retain` flag set, the binary sensor will receive an instant update after subscription and Home Assistant will display the correct availability state of the binary sensor when Home Assistant starts up. If the `retain` flag is not set, Home Assistant will display the binary sensor as `unavailable` when Home Assistant starts up. If no `availability_topic`

source/_integrations/device_trigger.mqtt.markdown

@@ -0,0 +1,75 @@
+---
+title: "MQTT Device Trigger"
+description: "Instructions on how to integrate MQTT device triggers within Home Assistant."
+logo: mqtt.png
+ha_category:
+  - Device Automation
+ha_release: 0.106
+ha_iot_class: Configurable
+---
+
+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](/docs/mqtt/discovery/), manual setup through `configuration.yaml` is not supported.
+The discovery topic needs to be: `<discovery_prefix>/device_automation/[<node_id>/]<object_id>/config`.
+
+{% configuration %}
+automation_type:
+  description: The type of automation, must be 'device_trigger'.
+  required: true
+  type: string
+payload:
+  description: Optional payload to match the payload being sent over the topic.
+  required: false
+  type: string
+qos:
+  description: The maximum QoS level to be used when receiving 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. `First button 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)."
+  required: true
+  type: map
+  keys:
+    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, map]
+    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
+    name:
+      description: The name of the device.
+      required: false
+      type: string
+    sw_version:
+      description: The firmware version of the device.
+      required: false
+      type: string
+{% endconfiguration %}