ha-automation

Home Assistant 自动化专家

自信地掌握 Home Assistant 自动化、脚本、蓝图和 Jinja2 模板。

开始之前

此技能可帮助避免常见的自动化错误，包括：

1. 触发器语法错误 - 使用已弃用的格式或无效的实体 ID
2. 缺少条件运算符 - 忘记使用 and/or/not 连接条件
3. Jinja2 模板错误 - 未定义变量或筛选器用法不正确
4. 蓝图参数化问题 - 缺少 !input 替换或选择器不匹配

快速参考：自动化结构

基本自动化格式

automation: !include automations.yaml

单个自动化文件

- alias: "My Automation"
  description: "What this automation does"
  trigger: ...
  condition: ...
  action: ...
  mode: single

触发器快速参考

状态触发器

trigger:
  platform: state
  entity_id: light.bedroom
  from: "off"
  to: "on"
  for:
    minutes: 5

数值状态触发器

trigger:
  platform: numeric_state
  entity_id: sensor.temperature
  above: 25
  below: 30

时间触发器

trigger:
  platform: time
  at: "10:30:00"

时间模式触发器

trigger:
  platform: time_pattern
  hours: "*/2"  # Every 2 hours
  minutes: 0

设备触发器

trigger:
  platform: device
  device_id: abc123...
  domain: light
  type: turned_on

事件触发器

trigger:
  platform: event
  event_type: call_service
  event_data:
    domain: light

MQTT 触发器

trigger:
  platform: mqtt
  topic: home/front_door/status
  payload: "opened"

Webhook 触发器

trigger:
  platform: webhook
  webhook_id: my_webhook_id

日出日落触发器

trigger:
  platform: sun
  event: sunrise
  offset: "-00:30:00"  # 30 min before sunrise

区域触发器

trigger:
  platform: zone
  entity_id: device_tracker.john
  zone: zone.home
  event: enter

模板触发器

trigger:
  platform: template
  value_template: "{{ state_attr('light.bedroom', 'brightness') > 200 }}"

条件快速参考

状态条件

condition:
  - condition: state
    entity_id: light.bedroom
    state: "on"

数值状态条件

condition:
  - condition: numeric_state
    entity_id: sensor.temperature
    above: 20
    below: 25

时间条件

condition:
  - condition: time
    after: "08:00:00"
    before: "20:00:00"
    weekday:
      - mon
      - tue
      - wed

日出日落条件

condition:
  - condition: sun
    after: sunrise
    before: sunset

模板条件

condition:
  - condition: template
    value_template: "{{ states('light.bedroom') == 'on' }}"

组合条件

condition:
  - condition: and
    conditions:
      - condition: state
        entity_id: light.bedroom
        state: "on"
      - condition: numeric_state
        entity_id: sensor.temperature
        above: 20

condition:
  - condition: or
    conditions:
      - condition: state
        entity_id: binary_sensor.motion
        state: "on"
      - condition: state
        entity_id: light.bedroom
        state: "on"

操作快速参考

调用服务操作

action:
  - service: light.turn_on
    target:
      entity_id: light.bedroom
    data:
      brightness: 255
      color_temp: 366

调用服务（多个目标）

action:
  - service: light.turn_on
    target:
      entity_id:
        - light.bedroom
        - light.living_room
      area_id: downstairs

选择（如果/那么/否则）

action:
  - choose:
      - conditions:
          - condition: state
            entity_id: light.bedroom
            state: "on"
        sequence:
          - service: light.turn_off
            target:
              entity_id: light.bedroom
      - conditions:
          - condition: state
            entity_id: light.bedroom
            state: "off"
        sequence:
          - service: light.turn_on
            target:
              entity_id: light.bedroom
    default:
      - service: notification.send
        data:
          message: "Unable to determine light state"

重复（循环）

action:
  - repeat:
      count: 3
      sequence:
        - service: light.toggle
          target:
            entity_id: light.bedroom
        - delay:
            seconds: 1

延迟

action:
  - delay:
      minutes: 5

等待触发器

action:
  - wait_for_trigger:
      platform: state
      entity_id: binary_sensor.motion
      to: "off"
    timeout:
      minutes: 30
  - service: light.turn_off
    target:
      entity_id: light.bedroom

并行操作

action:
  - parallel:
      - service: light.turn_off
        target:
          entity_id: light.bedroom
      - service: switch.turn_off
        target:
          entity_id: switch.fan

自动化模式

mode: single  # Default - cancel previous run
mode: restart  # Restart on retrigger
mode: queued  # Queue up to 10 retriggered runs
mode: parallel  # Allow multiple simultaneous runs
mode: queued  # with max: 10  # Limit queued runs

Jinja2 模板速查表

常用变量

• states('entity.id') - 获取实体状态
• state_attr('entity.id', 'attribute') - 获取实体属性
• now() - 当前日期时间
• as_timestamp('2024-01-01') - 转换为时间戳
• trigger - 触发器对象（用于触发器模板时）

筛选器

{{ value | float(0) }}  # Convert to float with default
{{ value | int(0) }}  # Convert to int with default
{{ value | round(2) }}  # Round to 2 decimal places
{{ value | timestamp_custom("%Y-%m-%d") }}  # Format timestamp
{{ value | replace("old", "new") }}  # Replace string
{{ value | lower }}  # Lowercase
{{ value | upper }}  # Uppercase
{{ value | length }}  # Get length
{{ list | list }}  # Convert to list

条件语句

{% if states('light.bedroom') == 'on' %}
  Light is on
{% elif states('light.bedroom') == 'off' %}
  Light is off
{% else %}
  Unknown
{% endif %}

循环

{% for entity in states.light %}
  {{ entity.name }}: {{ entity.state }}
{% endfor %}

数学运算

{{ 5 + 3 }}  # Addition
{{ 10 - 4 }}  # Subtraction
{{ 3 * 4 }}  # Multiplication
{{ 20 / 4 }}  # Division
{{ 17 % 5 }}  # Modulo (remainder)

字符串操作

{{ "hello " + "world" }}  # Concatenation
{{ value is string }}  # Type checking
{{ value is number }}
{{ value is defined }}  # Check if variable exists
{{ value | default("fallback") }}  # Provide default

调试模板

在 Home Assistant 界面中使用“开发者工具 > 模板”实时测试模板。

蓝图创建基础

蓝图结构

blueprint:
  name: "Friendly Name"
  description: "What this blueprint does"
  domain: automation
  source_url: "https://github.com/user/repo/path/to/blueprint.yaml"

  input:
    my_light:
      name: "Light to control"
      description: "The light entity to control"
      selector:
        entity:
          domain: light

    brightness_level:
      name: "Brightness"
      description: "Brightness percentage (0-100)"
      selector:
        number:
          min: 0
          max: 100
          unit_of_measurement: "%"

    duration:
      name: "Duration"
      description: "How long to stay on"
      selector:
        number:
          min: 1
          max: 60
          unit_of_measurement: "minutes"

    my_bool:
      name: "Enable feature"
      selector:
        boolean:

trigger: ...
condition: ...
action:
  - service: light.turn_on
    target:
      entity_id: !input my_light
    data:
      brightness: !input brightness_level

蓝图选择器

# Entity selector
selector:
  entity:
    domain: light

# Device selector
selector:
  device:
    integration: zwave
    manufacturer: Philips

# Area selector
selector:
  area:

# Number selector
selector:
  number:
    min: 0
    max: 100
    step: 5
    unit_of_measurement: "%"

# Text selector
selector:
  text:
    multiline: true

# Boolean selector
selector:
  boolean:

# Select (dropdown)
selector:
  select:
    options:
      - label: "Option 1"
        value: "value1"
      - label: "Option 2"
        value: "value2"

应避免的常见错误

❌ 不要：使用旧版触发器格式

trigger:
  - platform: state
    entity_id: light.bedroom

✅ 应当：使用嵌套结构

trigger:
  - platform: state
    entity_id: light.bedroom
    to: "on"

❌ 不要：混淆触发器和条件逻辑

trigger:
  - platform: state
    entity_id: light.bedroom
    to: "on"
condition:
  - condition: state
    entity_id: light.bedroom
    to: "on"  # Redundant!

✅ 应当：使用触发器检测变化，用条件验证状态

trigger:
  - platform: state
    entity_id: light.bedroom
condition:
  - condition: numeric_state
    entity_id: sensor.temperature
    above: 20  # Additional check

❌ 不要：在服务调用中忘记 entity_id

action:
  - service: light.turn_on
    data:
      brightness: 255

✅ 应当：指定目标实体

action:
  - service: light.turn_on
    target:
      entity_id: light.bedroom
    data:
      brightness: 255

最佳实践

1. 使用描述性别名 - 明确说明自动化的用途
2. 添加描述 - 解释创建此自动化的原因
3. 使用开发者工具进行测试 - 部署前验证模板
4. 使用 choose 处理复杂逻辑 - 比多个自动化更易读
5. 按房间或功能整理 - 使用 !include 拆分大型文件
6. 设置合适的模式 - 根据使用场景选择 single/restart/queued
7. 添加 for: 条件 - 避免短暂状态变化导致误触发
8. 使用模板提高灵活性 - 支持在蓝图中传递参数

故障排除

模板显示“Error”

• 在“开发者工具 > 模板”中检查模板
• 确认实体 ID 存在：homeassistant.entity_ids
• 对可选属性使用 | default("value") 筛选器

自动化未触发

• 验证实体 ID 和状态值（区分大小写）
• 使用 YAML 验证器检查 trigger.yaml 语法
• 在“设置 > 开发者工具 > 日志”中查看自动化日志

蓝图输入无效

• 验证 !input variable_name 语法（YAML 1.2 标签）
• 检查选择器类型是否与输入类型匹配
• 确保蓝图位于正确的文件夹中：config/blueprints/automation/

Jinja2 语法错误

• 检查是否存在未定义变量 - 使用 | default()
• 验证筛选器语法：value | filter_name(arg)
• 引号内不要再使用引号，除非进行了转义

官方资源

• Home Assistant 自动化文档
• Home Assistant 脚本
• Jinja2 模板指南
• 蓝图文档
• 条件类型
• 触发器类型
• 模板集成