Initial draft device automations docs (#321)

* Initial draft device automations docs

* Fix code block

* Add notes about scaffolding

* Update device_automation_action.md

* Update device_automation_condition.md

* Update device_automation_condition.md

* Update device_automation_index.md

* Update device_automation_trigger.md

docs/device_automation_action.md

@@ -0,0 +1,27 @@
+---
+title: "Device Actions"
+sidebar_label: Actions
+---
+
+Device actions allow a user to have a device do something. Examples are to turn a light on or open a door.
+
+Device actions are defined as dictionaries. These dictionaries are created by your integration and are passed to your integration to create a function that performs the action.
+
+Device actions 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 could be to reboot the device, while an example of the latter could be to turn a light on.
+
+Home Assistant includes a template to get started with device actions. To get started, run inside a development environment `python3 -m script.scaffold device_action`.
+
+The template will create a new file `device_action.py` in your integration folder and a matching test file. The file contains the following functions and constants:
+
+## `ACTION_SCHEMA`
+
+This is the schema for actions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_ACTION_BASE_SCHEMA`.
+
+## `async async async_get_actions(hass, device_id)`
+
+Return a list of actions that this device supports.
+
+## `async async_call_action_from_config(hass, config, variables, context)`
+
+Execute the passed in action.

docs/device_automation_condition.md

@@ -0,0 +1,27 @@
+---
+title: "Device Conditions"
+sidebar_label: Conditions
+---
+
+Device conditions allow a user to check if a certain condition is met. Examples are is a light on or is the floor wet.
+
+Device conditions are defined as dictionaries. These dictionaries are created by your integration and are passed to your integration to create a a function that checks the condition.
+
+Device conditions 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, humidity sensor).
+An example of the latter could be to check if a light is on or the floor is wet.
+
+Home Assistant includes a template to get started with device conditions. To get started, run inside a development environment `python3 -m script.scaffold device_condition`.
+
+The template will create a new file `device_condition.py` in your integration folder and a matching test file. The file contains the following functions and constants:
+
+## `CONDITION_SCHEMA`
+
+This is the schema for conditions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_CONDITION_BASE_SCHEMA`.
+
+## `async async_get_conditions(hass, device_id)`
+
+Return a list of conditions that this device supports.
+
+## `async async_condition_from_config(config, config_validation)`
+
+Create a condition function from a function. The condition functions should be an async-friendly callback that evaluates the condition and returns a `bool`.

docs/device_automation_index.md

@@ -0,0 +1,10 @@
+---
+title: "Device Automations"
+sidebar_label: Introduction
+---
+
+Device Automations provide users with a device-centric layer on top of the core concepts of Home Assistant. When creating automations, users no longer have to deal with core concepts like states and events. Instead, they will be able to pick a device and then pick from a list of pre-defined triggers, conditions and actions.
+
+Integrations can hook into this system by exposing functions to generate the pre-defined triggers, conditions, actions and having functions that can listen for the triggers, check the condition and execute the action.
+
+Device automations are not exposing extra functionality but are a way for users to not have to learn new concepts. Device automations are using events, state and service helpers under the hood.

docs/device_automation_trigger.md

@@ -0,0 +1,27 @@
+---
+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 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.
+
+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`.
+
+## `async async_get_triggers(hass, device_id)`
+
+Return a list of triggers.
+
+## `async async_attach_trigger(hass, config, action, automation_info)`
+
+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.

website/i18n/en.json

@@ -179,6 +179,22 @@
       "development_validation": {
         "title": "Validate the input"
       },
+      "device_automation_action": {
+        "title": "Device Actions",
+        "sidebar_label": "Actions"
+      },
+      "device_automation_condition": {
+        "title": "Device Conditions",
+        "sidebar_label": "Conditions"
+      },
+      "device_automation_index": {
+        "title": "Device Automations",
+        "sidebar_label": "Introduction"
+      },
+      "device_automation_trigger": {
+        "title": "Device Triggers",
+        "sidebar_label": "Triggers"
+      },
       "device_registry_index": {
         "title": "Device Registry",
         "sidebar_label": "Introduction"
@@ -1657,6 +1673,7 @@
       "Building Integrations": "Building Integrations",
       "Development Checklist": "Development Checklist",
       "Home Assistant Core 101": "Home Assistant Core 101",
+      "Device Automations": "Device Automations",
       "Misc": "Misc",
       "Introduction": "Introduction",
       "External API": "External API",

website/sidebars.json

@@ -86,6 +86,12 @@
       "dev_101_states",
       "dev_101_config"
     ],
+    "Device Automations": [
+      "device_automation_index",
+      "device_automation_trigger",
+      "device_automation_condition",
+      "device_automation_action"
+    ],
     "Misc": ["development_validation", "development_typing"]
   },
   "Misc": {