ha-device-triggers

Home Assistant Device Triggers

Device triggers allow automations to be triggered by device-specific events, like button presses or motion detection.

Note: Device triggers/conditions/actions are optional UX features, not Integration Quality Scale (IQS) rules — unlike diagnostics and repairs, they are not among the 52 IQS rules. Don't implement them to advance an IQS tier; only add them when the device genuinely benefits from device-based automation.

When to Use Device Triggers

Use device triggers when:

• Device has physical buttons or inputs
• Device generates events (motion, doorbell press)
• Hardware state changes need automation triggers
• Standard entity triggers aren't sufficient

File Structure

custom_components/{domain}/
├── device_trigger.py    # Trigger implementation
├── device_condition.py  # See ha-device-conditions-actions
├── device_action.py     # See ha-device-conditions-actions
└── strings.json         # Trigger labels

device_trigger.py Template

"""Device triggers for {Name}."""
from __future__ import annotations

from typing import Any

import voluptuous as vol

from homeassistant.components.device_automation import DEVICE_TRIGGER_BASE_SCHEMA
from homeassistant.components.homeassistant.triggers import event as event_trigger
from homeassistant.const import CONF_DEVICE_ID, CONF_DOMAIN, CONF_PLATFORM, CONF_TYPE
from homeassistant.core import CALLBACK_TYPE, HomeAssistant
from homeassistant.helpers import device_registry as dr
from homeassistant.helpers.trigger import TriggerActionType, TriggerInfo
from homeassistant.helpers.typing import ConfigType

from .const import DOMAIN

# Define trigger types your device supports
TRIGGER_TYPES = {"button_press", "button_long_press", "motion_detected"}

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


async def async_get_triggers(
    hass: HomeAssistant, device_id: str
) -> list[dict[str, Any]]:
    """Return a list of triggers for this device."""
    device_registry = dr.async_get(hass)
    device = device_registry.async_get(device_id)

    if device is None:
        return []

    # Check if this device belongs to our integration
    if DOMAIN not in [id[0] for id in device.identifiers]:
        return []

    triggers = []

    # Add triggers based on device capabilities
    # In a real integration, check device.model or stored capabilities
    for trigger_type in TRIGGER_TYPES:
        triggers.append(
            {
                CONF_PLATFORM: "device",
                CONF_DEVICE_ID: device_id,
                CONF_DOMAIN: DOMAIN,
                CONF_TYPE: trigger_type,
            }
        )

    return triggers


async def async_attach_trigger(
    hass: HomeAssistant,
    config: ConfigType,
    action: TriggerActionType,
    trigger_info: TriggerInfo,
) -> CALLBACK_TYPE:
    """Attach a trigger."""
    event_config = event_trigger.TRIGGER_SCHEMA(
        {
            event_trigger.CONF_PLATFORM: "event",
            event_trigger.CONF_EVENT_TYPE: f"{DOMAIN}_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, trigger_info, platform_type="device"
    )