diff --git a/docs/device_automation_action.md b/docs/device_automation_action.md index 5165096a..11b8fd60 100644 --- a/docs/device_automation_action.md +++ b/docs/device_automation_action.md @@ -16,12 +16,24 @@ The template will create a new file `device_action.py` in your integration folde #### `ACTION_SCHEMA` -This is the schema for actions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_ACTION_BASE_SCHEMA`. +This is the schema for actions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_ACTION_BASE_SCHEMA`. Do not apply the schema manually. The core will apply the schema if the action schema is defined as a constant in the `device_action.py` module of the integration. -#### `async def async_get_actions(hass, device_id)` +#### `async_get_actions` + +```py +async def async_get_actions(hass: HomeAssistant, device_id: str) -> list[dict]: + """List device actions for devices.""" +``` Return a list of actions that this device supports. -#### `async def async_call_action_from_config(hass, config, variables, context)` +#### `async_call_action_from_config` + +```py +async def async_call_action_from_config( + hass: HomeAssistant, config: dict, variables: dict, context: Context | None +) -> None: + """Execute a device action.""" +``` Execute the passed in action. diff --git a/docs/device_automation_condition.md b/docs/device_automation_condition.md index f51e39ed..10f12f17 100644 --- a/docs/device_automation_condition.md +++ b/docs/device_automation_condition.md @@ -18,10 +18,27 @@ The template will create a new file `device_condition.py` in your integration fo This is the schema for conditions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_CONDITION_BASE_SCHEMA`. -#### `async def async_get_conditions(hass, device_id)` +#### `async_get_conditions` + +```py +async def async_get_conditions( + hass: HomeAssistant, device_id: str +) -> list[dict[str, str]]: + """List device conditions for devices.""" +``` Return a list of conditions that this device supports. -#### `async def async_condition_from_config(config, config_validation)` +#### `async_condition_from_config` + +```py +@callback +def async_condition_from_config( + config: ConfigType, config_validation: bool +) -> condition.ConditionCheckerType: + """Create a function to test a device condition.""" +``` Create a condition function from a function. The condition functions should be an async-friendly callback that evaluates the condition and returns a `bool`. + +The `config_validation` parameter will be used by the core to apply config validation conditionally with the defined `CONDITION_SCHEMA`. diff --git a/docs/device_automation_trigger.md b/docs/device_automation_trigger.md index 26f3e4ff..1e33b993 100644 --- a/docs/device_automation_trigger.md +++ b/docs/device_automation_trigger.md @@ -12,7 +12,16 @@ To add support for Device Triggers, an integration needs to have a `device_trigg - *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. -- *Add text and translations*: Give each trigger a human readable name. +- *Add text and translations*: Give each trigger a human readable name. + +Do not apply the static schema manually. The core will apply the schema if the trigger schema is defined as a constant in the `device_trigger.py` module of the integration. + +If the trigger requires dynamic validation that the static `TRIGGER_SCHEMA` can't provide, it's possible to implement an `async_validate_trigger_config` function. + +```py +async def async_validate_trigger_config(hass: HomeAssistant, config: ConfigType) -> ConfigType: + """Validate config.""" +``` 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`. @@ -85,7 +94,6 @@ For example, you might attach the trigger and action to [Events fired](integrati ```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",