Add additional trigger documentation (#733)

docs/device_automation_trigger.md

@@ -3,25 +3,99 @@ title: "Device Triggers"
 sidebar_label: Triggers
 ---
 
-Device triggers are automation triggers that are tied to a specific device. Examples are "light turned on" or "water detected".
+Device triggers are automation triggers that are tied to a specific device and an event or state change. Examples are "light turned on" or "water detected".
 
-Device triggers are defined as dictionaries. These dictionaries are created by your integration and are consumed by your integration to attach the trigger.
+Device triggers can be provided by the integration that provides the device (e.g. ZHA, deCONZ) or the entity integrations that the device has entities with (e.g. light, switch).  An example of the former is events not tied to an entity e.g. key press on a remote control or touch panel, while an example of the latter could be that a light has been turned on.
 
-Device triggers can be provided by the integration that provides the device (e.g. ZHA, deCONZ) or the entity integrations that the device has entities with (e.g. light, switch).
-An example of the former is events not tied to an entity e.g. key press on a remote control or touch panel, while an example of the latter could be that a light has been turned on.
+To add support for Device Triggers, an integration needs to have a `device_trigger.py` and:
+
+- *Define a `TRIGGER_SCHEMA`*: A dictionary that represents a trigger, such as a device and an event type
+- *Create triggers*: Create dictionaries containing the device or entity and supported events or state changes as defined by the schema.
+- *Attach triggers*: Associate a trigger config with an event or state change, e.g. a message fired on the event bus.
 
 Home Assistant includes a template to get started with device triggers. To get started, run inside a development environment `python3 -m script.scaffold device_trigger`.
 
 The template will create a new file `device_trigger.py` in your integration folder and a matching test file. The file contains the following functions and constants:
 
-#### `TRIGGER_SCHEMA`
 
-This is a voluptuous schema that verifies that a specific dictionary represents a config that your integration can handle. This should extend the TRIGGER_BASE_SCHEMA from `device_automation/__init__.py`.
+#### Define a `TRIGGER_SCHEMA`
 
-#### `async def async_get_triggers(hass, device_id)`
+Device triggers are defined as dictionaries. These dictionaries are created by your integration and are consumed by your integration to attach the trigger.
 
-Return a list of triggers.
+This is a voluptuous schema that verifies that a specific trigger dictionary represents a config that your integration can handle. This should extend the TRIGGER_BASE_SCHEMA from `device_automation/__init__.py`.
 
-#### `async def async_attach_trigger(hass, config, action, automation_info)`
+```python
+from homeassistant.const import (
+    CONF_ENTITY_ID,
+    CONF_TYPE,
+)
 
-Given one of your own trigger configs, make it so the `action` is called whenever the trigger is triggered. Return value is a function that detaches the trigger.
+TRIGGER_TYPES = {"water_detected", "noise_detected"}
+
+TRIGGER_SCHEMA = TRIGGER_BASE_SCHEMA.extend(
+    {
+        vol.Required(CONF_TYPE): vol.In(TRIGGER_TYPES),
+    }
+)
+```
+
+This example has a single `type` field indicating the type of events supported.
+
+#### Create triggers
+
+The `async_get_triggers` method returns a list of triggers supported by the device or any associated entities. These are the triggers exposed to the user for creating automations.
+
+```python
+from homeassistant.const import (
+    CONF_DEVICE_ID,
+    CONF_DOMAIN,
+    CONF_PLATFORM,
+    CONF_TYPE,
+)
+
+async def async_get_triggers(hass, device_id):
+    """Return a list of triggers."""
+
+    device_registry = await hass.helpers.device_registry.async_get_registry()
+    device = device_registry.async_get(device_id)
+
+    triggers = []
+
+    # Determine which triggers are supported by this device_id ...
+
+    triggers.append({
+        # Required fields of TRIGGER_BASE_SCHEMA
+        CONF_PLATFORM: "device",
+        CONF_DOMAIN: "mydomain",
+        CONF_DEVICE_ID: device_id,
+        # Required fields of TRIGGER_SCHEMA
+        CONF_TYPE: "water_detected",
+    })
+
+    return triggers
+```
+
+#### Attach triggers
+
+The last step is to wire everything up: Given a `TRIGGER_SCHEMA` config, make sure the `action` is called when the trigger is triggered.
+
+For example, you might attach the trigger and action to [Events fired](integration_events.md) on the event bus by your integration.
+
+```python
+async def async_attach_trigger(hass, config, action, automation_info):
+    """Attach a trigger."""
+    config = TRIGGER_SCHEMA(config)
+    event_config = event_trigger.TRIGGER_SCHEMA({
+        event_trigger.CONF_PLATFORM: "event",
+        event_trigger.CONF_EVENT_TYPE: "mydomain_event",
+        event_trigger.CONF_EVENT_DATA: {
+            CONF_DEVICE_ID: config[CONF_DEVICE_ID],
+            CONF_TYPE: config[CONF_TYPE],
+        },
+    }
+    return await event_trigger.async_attach_trigger(
+        hass, event_config, action, automation_info, platform_type="device"
+    )
+```
+
+The return value is a function that detaches the trigger.

docs/integration_events.md

@@ -2,17 +2,25 @@
 title: "Firing events"
 ---
 
-Some integration represents a device or service that has events, like when motion is detected or a momentary button is pushed. An integration can make these available to users by firing them as events in Home Assistant.
+Some integrations represent devices or services that have events, like when motion is detected or a momentary button is pushed. An integration can make these available to users by firing them as events in Home Assistant.
 
 Your integration should fire events of type `<domain>_event`. For example, the ZHA integration fires `zha_event` events.
 
 If the event is related to a specific device/service, it should be correctly attributed. Do this by adding a `device_id` attribute to the event data that contains the device identifier from the device registry.
 
+```
+event_data = {
+    "device_id": "my-device-id",
+    "type": "motion_detected",
+}
+hass.bus.async_fire("mydomain_event", event_data)
+```
+
 If a device or service only fires events, you need to [manually register it in the device registry](device_registry_index.md#manual-registration).
 
 ## Making events accessible to users
 
-[Device triggers](device_automation_trigger.md) should be used to make events accessible to users. With a device trigger a user will be able to see all available events for the device and use it in their automations.
+A [Device trigger](device_automation_trigger.md) can be attached to a specific event based on the payload, and will make the event accessible to users. With a device trigger a user will be able to see all available events for the device and use it in their automations.
 
 ## What not to do