设备自动化

介绍

Device automation在HA的核心概念之上为用户提供了一个以设备为中心的层。在创建自动化时，用户不再需要处理像状态和事件这样的核心概念。相反，他们将能够选择一个设备，然后从一个预定义的触发器、条件和操作列表中选择。

集成可以通过公开函数来生成预定义的触发器、条件和操作，并拥有能够侦听触发器、检查条件和执行操作的函数来与这个系统挂钩。

设备自动化并没有暴露额外的功能，而是为用户提供了一种不必学习新概念的方式。设备自动化在底层使用事件、状态和服务帮助器。

触发器

设备触发器是绑定到特定设备和事件或状态更改的自动化触发器。例如“灯亮了”或“检测到水”。

设备触发器可以由提供设备的集成(如ZHA, deCONZ)或设备具有实体的实体集成(如灯，开关)提供。前者的例子是不绑定于实体的事件，如远程控制或触摸面板上的按键，而后者的例子则是灯亮了。

要添加对设备触发器的支持，集成需要有device_trigger.py和

• 定义一个TRIGGER_SCHEMA:一个表示触发器的字典，比如一个设备和一个事件类型
• 创建触发器:创建包含设备或实体和支持的事件或状态更改的字典，如模式所定义的。
• 附加触发器:将触发器配置与事件或状态更改相关联，例如在事件总线上触发的消息。
• 添加文本和翻译:给每个触发器一个可读的名称。

不要手动应用静态模式。如果触发器模式被定义为集成的device_trigger.py模块中的常量，则Core将应用该模式。

如果触发器需要静态TRIGGER_SCHEMA不能提供的动态验证，则可以实现一个async_validate_trigger_config函数。

async def async_validate_trigger_config(hass: HomeAssistant, config: ConfigType) -> ConfigType:
    """Validate config."""

包括一个用于开始使用设备触发器的模板。首先，在一个开发环境运行python3 -m script.scaffold device_trigger

模板将在集成文件夹中创建一个新文件device_trigger.py和一个匹配的测试文件。该文件包含以下函数和常量:

定义一个TRIGGER_SCHEMA

设备触发器被定义为字典。这些字典由集成创建，并由集成使用以附加触发器。

这是一种复杂的模式，它验证特定的触发器字典是否代表集成可以处理的配置。这应该是device_automation/__init__.py中的TRIGGER_BASE_SCHEMA的扩展。

from homeassistant.const import (
    CONF_ENTITY_ID,
    CONF_TYPE,
)

TRIGGER_TYPES = {"water_detected", "noise_detected"}

TRIGGER_SCHEMA = TRIGGER_BASE_SCHEMA.extend(
    {
        vol.Required(CONF_TYPE): vol.In(TRIGGER_TYPES),
    }
)

此示例只有一个type字段，指示支持的事件类型

创建触发器

async_get_triggers方法返回设备或任何相关实体支持的触发器列表。这些是向用户公开的用于创建自动化的触发器。

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

绑定触发器

要将其连接起来:给定一个TRIGGER_SCHEMA配置，确保在触发触发器时调用该action。

例如，您可以将触发器和操作附加到由您的集成在事件总线上 Events fired 。

async def async_attach_trigger(hass, config, action, automation_info):
    """Attach a trigger."""
    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"
    )

返回值是一个解绑触发器的函数。

增加文本和翻译

自动化用户界面将在映射到事件类型的设备自动化中显示人类可读的字符串。使用您支持的触发器类型和子类型更新string.json:

{
   "device_automation": {
    "trigger_type": {
      "water_detected": "Water detected",
      "noise_detected": "Noise detected"
    }
}

为了在开发过程中测试你的翻译，python3 -m script.translations develop

条件

设备条件允许用户检查是否满足某个条件。例如是灯亮着还是地板湿了。

设备条件被定义为字典。这些字典是由集成创建的，并传递给集成来创建一个检查条件的函数。

设备条件可以由提供设备的集成(如ZHA、deCONZ)或设备具有实体的实体集成(如光、湿度传感器)提供。后者的一个例子可能是检查灯是否开着或地板是湿的。

如果条件需要静态CONDITION_SCHEMA不能提供的动态验证，则可以实现async_validate_condition_config函数。

async def async_validate_condition_config(hass: HomeAssistant, config: ConfigType) -> ConfigType:
    """Validate config."""

HA包括一个用于开始设备条件的模板,执行python3 -m script.scaffold device_condition

模板将在集成文件夹中创建一个新文件device_condition.py和一个匹配的测试文件。该文件包含以下函数和常量:

CONDITION_SCHEMA

这是条件的模式。基本模式应该从homeassistant.helpers.config_validation.DEVICE_CONDITION_BASE_SCHEMA扩展。

async_get_conditions

async def async_get_conditions(
    hass: HomeAssistant, device_id: str
) -> list[dict[str, str]]:
    """List device conditions for devices."""

返回此设备支持的条件列表。

async_condition_from_config

@callback
def async_condition_from_config(
    config: ConfigType, config_validation: bool
) -> condition.ConditionCheckerType:
    """Create a function to test a device condition."""

从函数中创建条件函数。条件函数应该是一个对异步友好（即很好的支持异步）的回调函数，它计算条件并返回bool值。

config_validation参数将被核心用来有条件地对已定义的CONDITION_SCHEMA应用配置验证。

动作、行为（Actions）

设备动作允许用户让设备做一些事情。例如开灯或开门。

设备动作被定义为字典。这些字典由集成创建，并传递给集成以创建执行操作的函数。

设备动作可以由提供设备的集成(如ZHA, deCONZ)或设备具有实体的实体集成(如灯，开关)提供。前者的一个例子是重启设备，而后者的一个例子是打开灯。

如果动作需要静态ACTION_SCHEMA不能提供的动态验证，则可以实现一个async_validate_action_config函数。

async def async_validate_action_config(hass: HomeAssistant, config: ConfigType) -> ConfigType:
    """Validate config."""

HA包括一个用于开始设备操作的模板,运行python3 -m script.scaffold device_action

模板将在集成文件夹中创建一个新文件device_action.py和一个匹配的测试文件。该文件包含以下函数和常量:

ACTION_SCHEMA

这是操作的模式。基本模式应该从homeassistant.helpers.config_validation.DEVICE_ACTION_BASE_SCHEMA扩展。

不要手动应用模式。如果操作模式在集成的device_action.py模块中定义为常量，则核心将应用该模式。

async_get_actions

async def async_get_actions(hass: HomeAssistant, device_id: str) -> list[dict]:
    """List device actions for devices."""

返回此设备支持的操作列表。

async_call_action_from_config

async def async_call_action_from_config(
    hass: HomeAssistant, config: dict, variables: dict, context: Context | None
) -> None:
    """Execute a device action."""

执行传入的动作。