From 37521cad71fa7937745392436ce819357de8e00f Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Tue, 24 Sep 2019 14:34:32 -0700 Subject: [PATCH 1/8] Initial draft device automations docs --- docs/device_automation_action.md | 22 ++++++++++++++++++++++ docs/device_automation_condition.md | 22 ++++++++++++++++++++++ docs/device_automation_index.md | 10 ++++++++++ docs/device_automation_trigger.md | 22 ++++++++++++++++++++++ website/i18n/en.json | 17 +++++++++++++++++ website/sidebars.json | 6 ++++++ 6 files changed, 99 insertions(+) create mode 100644 docs/device_automation_action.md create mode 100644 docs/device_automation_condition.md create mode 100644 docs/device_automation_index.md create mode 100644 docs/device_automation_trigger.md diff --git a/docs/device_automation_action.md b/docs/device_automation_action.md new file mode 100644 index 00000000000..b66bee1c6d2 --- /dev/null +++ b/docs/device_automation_action.md @@ -0,0 +1,22 @@ +--- +title: "Device Actions" +sidebar_label: Actions +--- + +Device actions allow a user to have a device to something. Examples are to turn a light on or open the 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 checks the condition. + +To get started with device actions, create a new file `device_action.py`. The file will need to contain 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_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. diff --git a/docs/device_automation_condition.md b/docs/device_automation_condition.md new file mode 100644 index 00000000000..75fe89ea2ad --- /dev/null +++ b/docs/device_automation_condition.md @@ -0,0 +1,22 @@ +--- +title: "Device Conditions" +sidebar_label: Conditions +--- + +Device conditions allow a user to check if a certain device 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 createa a function that checks the condition. + +To get started with device conditions, create a new file `device_condition.py`. The file will need to contain 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_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 diff --git a/docs/device_automation_index.md b/docs/device_automation_index.md new file mode 100644 index 00000000000..bf37416d933 --- /dev/null +++ b/docs/device_automation_index.md @@ -0,0 +1,10 @@ +--- +title: "Device Automations" +sidebar_label: Introduction +--- + +Device Automations provides 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 in 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 automatoins are using events, state and service helpers under the hood. diff --git a/docs/device_automation_trigger.md b/docs/device_automation_trigger.md new file mode 100644 index 00000000000..732faff0ed2 --- /dev/null +++ b/docs/device_automation_trigger.md @@ -0,0 +1,22 @@ +--- +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. + +To get started with device automation triggers, create a new file `device_trigger.py`. The file will need to contain 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_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. diff --git a/website/i18n/en.json b/website/i18n/en.json index a529e9119b8..854569ef330 100644 --- a/website/i18n/en.json +++ b/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", diff --git a/website/sidebars.json b/website/sidebars.json index 6f98fd3195f..c335a7ea9cc 100644 --- a/website/sidebars.json +++ b/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": { From 73208dc6c284b295e6797edf3963160caf716557 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Tue, 24 Sep 2019 14:54:35 -0700 Subject: [PATCH 2/8] Fix code block --- docs/device_automation_action.md | 4 ++-- docs/device_automation_condition.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/device_automation_action.md b/docs/device_automation_action.md index b66bee1c6d2..983bbdedd92 100644 --- a/docs/device_automation_action.md +++ b/docs/device_automation_action.md @@ -11,9 +11,9 @@ To get started with device actions, create a new file `device_action.py`. The fi ## `ACTION_SCHEMA` -This is the schema for actions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_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) +## `async async async_get_actions(hass, device_id)` Return a list of actions that this device supports. diff --git a/docs/device_automation_condition.md b/docs/device_automation_condition.md index 75fe89ea2ad..904bff1eab7 100644 --- a/docs/device_automation_condition.md +++ b/docs/device_automation_condition.md @@ -11,9 +11,9 @@ To get started with device conditions, create a new file `device_condition.py`. ## `CONDITION_SCHEMA` -This is the schema for conditions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_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) +## `async async_get_conditions(hass, device_id)` Return a list of conditions that this device supports. From f38474ce27007acd926f0196eecd40e62c753ca4 Mon Sep 17 00:00:00 2001 From: Paulus Schoutsen Date: Tue, 24 Sep 2019 16:52:06 -0700 Subject: [PATCH 3/8] Add notes about scaffolding --- docs/device_automation_action.md | 4 +++- docs/device_automation_condition.md | 4 +++- docs/device_automation_trigger.md | 6 ++++-- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/device_automation_action.md b/docs/device_automation_action.md index 983bbdedd92..d19d9881abe 100644 --- a/docs/device_automation_action.md +++ b/docs/device_automation_action.md @@ -7,7 +7,9 @@ Device actions allow a user to have a device to something. Examples are to turn Device actions are defined as dictionaries. These dictionaries are created by your integration and are passed to your integration to create a function that checks the condition. -To get started with device actions, create a new file `device_action.py`. The file will need to contain the following functions and constants: +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` diff --git a/docs/device_automation_condition.md b/docs/device_automation_condition.md index 904bff1eab7..31990d05232 100644 --- a/docs/device_automation_condition.md +++ b/docs/device_automation_condition.md @@ -7,7 +7,9 @@ Device conditions allow a user to check if a certain device condition is met. Ex Device conditions are defined as dictionaries. These dictionaries are created by your integration and are passed to your integration to createa a function that checks the condition. -To get started with device conditions, create a new file `device_condition.py`. The file will need to contain the following functions and constants: +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` diff --git a/docs/device_automation_trigger.md b/docs/device_automation_trigger.md index 732faff0ed2..92cafb837ec 100644 --- a/docs/device_automation_trigger.md +++ b/docs/device_automation_trigger.md @@ -7,11 +7,13 @@ Device triggers are automation triggers that are tied to a specific device. Exam Device triggers are defined as dictionaries. These dictionaries are created by your integration and are consumed by your integration to attach the trigger. -To get started with device automation triggers, create a new file `device_trigger.py`. The file will need to contain the following functions and constants: +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_SCHEMA from `device_automation/__init__.py`. +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)` From 63c440a6c280959f2a4e9d6098c69ff0c2317993 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Wed, 25 Sep 2019 18:52:13 +0200 Subject: [PATCH 4/8] Update device_automation_action.md --- docs/device_automation_action.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/device_automation_action.md b/docs/device_automation_action.md index d19d9881abe..808c1fa9cab 100644 --- a/docs/device_automation_action.md +++ b/docs/device_automation_action.md @@ -3,9 +3,12 @@ title: "Device Actions" sidebar_label: Actions --- -Device actions allow a user to have a device to something. Examples are to turn a light on or open the door. +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 checks the condition. +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`. From ceeed8631d0fba798233109cfab9cce944fafc11 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Wed, 25 Sep 2019 18:55:44 +0200 Subject: [PATCH 5/8] Update device_automation_condition.md --- docs/device_automation_condition.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/device_automation_condition.md b/docs/device_automation_condition.md index 31990d05232..92e511a8279 100644 --- a/docs/device_automation_condition.md +++ b/docs/device_automation_condition.md @@ -3,9 +3,12 @@ title: "Device Conditions" sidebar_label: Conditions --- -Device conditions allow a user to check if a certain device condition is met. Examples are is a light on or is the floor wet. +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 createa a function that checks the condition. +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`. From c4e073078f7fb18504dfeea25e59436b93f360af Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Wed, 25 Sep 2019 18:57:01 +0200 Subject: [PATCH 6/8] Update device_automation_condition.md --- docs/device_automation_condition.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/device_automation_condition.md b/docs/device_automation_condition.md index 92e511a8279..9af6d72fd7f 100644 --- a/docs/device_automation_condition.md +++ b/docs/device_automation_condition.md @@ -24,4 +24,4 @@ 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 +Create a condition function from a function. The condition functions should be an async-friendly callback that evaluates the condition and returns a `bool`. From 09736747309ed3aa4451fa81c7fe76bfd86e511e Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Wed, 25 Sep 2019 18:58:48 +0200 Subject: [PATCH 7/8] Update device_automation_index.md --- docs/device_automation_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/device_automation_index.md b/docs/device_automation_index.md index bf37416d933..ea15ec6c9e9 100644 --- a/docs/device_automation_index.md +++ b/docs/device_automation_index.md @@ -3,8 +3,8 @@ title: "Device Automations" sidebar_label: Introduction --- -Device Automations provides 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. +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 in 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. +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 automatoins are using events, state and service helpers under the hood. +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. From 95f4c14b07c349600e735dbfc7dbfd791c5ae3cc Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Wed, 25 Sep 2019 19:01:04 +0200 Subject: [PATCH 8/8] Update device_automation_trigger.md --- docs/device_automation_trigger.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/device_automation_trigger.md b/docs/device_automation_trigger.md index 92cafb837ec..29ff4f4e578 100644 --- a/docs/device_automation_trigger.md +++ b/docs/device_automation_trigger.md @@ -7,6 +7,9 @@ Device triggers are automation triggers that are tied to a specific device. Exam 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: