二进制传感器组件

ESPHome 支持多种类型的二进制传感器。它们会自动出现在 Home Assistant 前端的界面中，并提供多项配置选项。

基础二进制传感器配置

所有二进制传感器都有一个平台和一个可选的设备类。默认情况下，二进制传感器会自动选择合适的设备类，但你也可以随时覆盖它。

binary_sensor:
  - platform: ...
    device_class: motion

配置变量：

id（可选，string）：手动指定用于代码生成的 ID。必须指定 id 和 name 中的至少一个。
name（可选，string）：二进制传感器的名称。必须指定 id 和 name 中的至少一个。

NOTE

如果你的设备设置了 friendly_name，并且你希望二进制传感器使用该名称，可以设置 name: None。

device_class（可选，string）：传感器的设备类。可选项列表见 https://www.home-assistant.io/integrations/binary_sensor/#device-class。
icon（可选，icon）：手动设置二进制传感器在前端界面中使用的图标。
filters（可选，list）：应用于二进制传感器值的一组过滤器，例如信号反转。参见二进制传感器过滤器。

自动化：

on_press（可选，Automation）：按钮按下时要执行的自动化。参见on_press。
on_release（可选，Automation）：按钮释放时要执行的自动化。参见on_release。
on_state（可选，Automation）：状态变更发布时要执行的自动化。参见on_state。
on_click（可选，Automation）：按钮按住指定时间段时要执行的自动化。参见on_click。
on_double_click（可选，Automation）：按钮按两次且符合指定时间间隔时要执行的自动化。参见on_double_click。
on_multi_click（可选，Automation）：按钮按特定序列时要执行的自动化。参见on_multi_click。

高级选项：

internal（可选，boolean）：将该组件标记为内部组件。内部组件将不暴露给前端（如 Home Assistant）。只指定 id 而不指定 name 将隐式将此值设为 true。
disabled_by_default（可选，boolean）：如果为 true，则此实体不应被添加到任何客户端的前端中，（通常为 Home Assistant），除非用户手动启用它（通过 Home Assistant UI）。默认为 false。
trigger_on_initial_state（可选，boolean）：如果为 true，则当二进制传感器状态从 unknown 变为有效状态时，任何适用的触发器都将被触发。这适用于设置第一个有效状态的情况，以及在执行 binary_sensor.invalidate_state 动作后设置的任何有效状态。默认为 false。
entity_category（可选，string）：实体的类别。可选项列表见 https://developers.home-assistant.io/docs/core/entity/#generic-properties。设为 "" 以移除默认的实体类别。
如果启用了 MQTT，还包含 MQTT 组件的所有其他选项。
如果启用了 Webserver 并选择了版本 3，则包含 Webserver 组件的所有其他选项。参见 Webserver 版本 3。

动作

`binary_sensor.invalidate_state` 动作

此动作将使传感器的当前状态失效。它与 Template 二进制传感器搭配使用时最为有用。状态失效后，将向 Home Assistant 报告为 unknown。示例：

on_...:
  binary_sensor.invalidate_state: my_binary_sensor_id

状态也可以通过 lambda 中的 API 调用失效——参见下方链接的 API 引用。

二进制传感器过滤器

通过二进制传感器过滤器，你可以进一步自定义 ESPHome 处理二进制传感器值的方式。它们与传感器过滤器类似。所有过滤器在管线中被处理。这意味着所有二进制传感器过滤器会按配置中给出的顺序进行处理（因此这些条目的顺序很重要！）

binary_sensor:
  - platform: ...
    # ...
    filters:
      - invert:
      - delayed_on: 100ms
      - delayed_off: 100ms
      # 模板化，仅当干簧管处于活动状态时延迟 1 秒（1000ms）
      - delayed_on_off: !lambda "if (id(reed_switch).state) return 1000; else return 0;"
      - delayed_on_off:
          time_on: 10s
          time_off: !lambda "if (id(reed_switch).state) return 1000; else return 0;"
      - autorepeat:
        - delay: 1s
          time_off: 100ms
          time_on: 900ms
        - delay: 5s
          time_off: 100ms
          time_on: 400ms
      - lambda: |-
          if (id(other_binary_sensor).state) {
            return x;
          } else {
            return {};
          }

`invert`

一个简单的过滤器，仅反转二进制传感器的每个值。

`delayed_on`

（必选，time，templatable）：当收到 ON 信号时，等待指定的时间段后再发布 ON 状态。如果在等待期间收到 OFF 值，则丢弃 ON 动作。换句话说：只有当二进制传感器至少保持 ON 状态达到指定时间段时才发送 ON 值。使用 lambda 调用时，应返回以毫秒为单位的延迟值。 用于对按钮进行消抖。

`delayed_off`

（必选，time，templatable）：当收到 OFF 信号时，等待指定的时间段后再发布 OFF 状态。如果在等待期间收到 ON 值，则丢弃 OFF 动作。换句话说：只有当二进制传感器至少保持 OFF 状态达到指定时间段时才发送 OFF 值。使用 lambda 调用时，应返回以毫秒为单位的延迟值。 用于对按钮进行消抖。

`delayed_on_off`

仅当二进制传感器至少保持在同一状态达到指定时间段时才发送 ON 或 OFF 值。

此过滤器使用两个时间延迟：on 和 off。

如果延迟相等，可以通过传递时间参数以简写形式配置过滤器：

binary_sensor:
  - platform: ...
    # ...
    filters:
      - delayed_on_off: 1s

（必选，time，templatable）：ON 和 OFF 延迟。使用 lambda 调用时，应返回以毫秒为单位的延迟值。 用于对二进制开关进行消抖。

如果延迟不同，则需要像下面示例中那样分别传递它们：

binary_sensor:
  - platform: ...
    # ...
    filters:
      - delayed_on_off:
          time_on: 10s
          time_off: 20s

配置变量：

time_on（必选，time，templatable）：ON 延迟。
time_off（必选，time，templatable）：OFF 延迟。

使用 lambda 调用时，应返回以毫秒为单位的延迟值。

`autorepeat`

实现自动重复行为的过滤器。该过滤器以一组时序描述作为参数。收到 ON 信号后，它被传递到输出，并开始第一个 delay。当该间隔到期时，输出变为 OFF，并使用 time_off 和 time_on 的时长分别对应 OFF 和 ON 状态进行切换。同时启动第二个时序描述的 delay，并重复该过程直到列表耗尽，此时最后一个时序描述的时序保持使用。收到 OFF 信号会停止整个过程并立即输出 OFF。

因此在示例中，输出保持 ON 状态等待一秒，然后以每秒一次的频率切换五秒，接着以每秒两次的频率切换，直到收到 OFF。

不带任何时序描述的 autorepeat 过滤器等效于一个所有参数均设为默认值的时序。

配置变量：

delay（可选，Time）：进入下一个时序的延迟。默认为 1s。
time_off（可选，Time）：将输出保持在 OFF 状态的间隔。默认为 100ms。
time_on（可选，Time）：将输出保持在 ON 状态的间隔。默认为 900ms。

`lambda`

指定任意 lambda 以实现更复杂的过滤器。来自二进制传感器的输入值为 x，你可以返回 true 表示 ON，返回 false 表示 OFF，返回 {} 则停止过滤器链。

`settle`

（必选，time，templatable）：收到信号时，发布状态，但在发布任何额外状态变更之前，等待接收到的状态在指定时间段内保持不变。此过滤器对 delayed_on_off 过滤器起到补充作用，但在延迟期开始时即发布值变更。使用 lambda 调用时，应返回以毫秒为单位的延迟值。 用于对二进制开关进行消抖。

`timeout`

（必选，time，templatable）：如果在指定时间段内没有发布值，则使状态失效。

二进制传感器自动化

ESPHome 中二进制传感器的触发器使用了计算机鼠标的术语。例如，press 在鼠标按钮首次按下时触发。

你可以在 lambda 中通过 id(binary_sensor_id).state 访问二进制传感器的当前状态。

`on_press`

当按钮首次按下，或者换句话说在信号的上升沿时，将触发此自动化。

binary_sensor:
  - platform: gpio
    # ...
    on_press:
      then:
        - switch.turn_on: relay_1

配置变量：参见 Automation。

`on_release`

当按钮按压结束，或者换句话说在信号的下降沿时，将触发此自动化。

binary_sensor:
  - platform: gpio
    # ...
    on_release:
      then:
        - switch.turn_off: relay_1

配置变量：参见 Automation。

`on_state`

当收到新状态时将触发此自动化（因此将 on_press 和 on_release 合并为一个触发器）。新状态将作为变量 x 以布尔值的形式给出，并可在 lambda 中使用。当状态失效时不会被调用；仅当 trigger_on_initial_state 为 true 时，状态最初变为有效时才会被调用。

binary_sensor:
  - platform: gpio
    # ...
    on_state:
      then:
        - switch.turn_off: relay_1

配置变量：参见 Automation。

`on_state_change`

on_state 的替代方案，当二进制传感器状态失效时也会被触发。它传入两个参数，x 与 on_change 相同为新值，x_previous 为变更前的紧接值。这两个参数的类型均为 optional<bool>，因此也能指示值是否有效。请注意，这会在所有状态变更时调用，包括初始状态。

binary_sensor:
  - platform: gpio
    # ...
    on_state_change:
      then:
      - logger.log:
          format: "Old state was %s"
          args: ['x_previous.has_value() ? ONOFF(x_previous.value()) : "Unknown"']
      - logger.log:
          format: "New state is %s"
          args: ['x.has_value() ? ONOFF(x.value()) : "Unknown"']

配置变量：参见 Automation。

`on_click`

当按钮按下持续一段时长在 min_length 到 max_length 之间的时间段时，将触发此自动化。任何比这更长或更短的点击都不会触发自动化。因此该自动化在信号的下降沿触发。

binary_sensor:
  - platform: gpio
    # ...
    on_click:
      min_length: 50ms
      max_length: 350ms
      then:
        - switch.turn_off: relay_1

配置变量：

min_length（可选，Time）：点击应持续的最短时长。默认为 50ms。
max_length（可选，Time）：点击应持续的最长时长。默认为 350ms。
参见 Automation。

NOTE

可以像这样定义多个 on_click 条目（更复杂的匹配参见 on_multi_click）：

binary_sensor:
  - platform: gpio
    # ...
    on_click:
    - min_length: 50ms
      max_length: 350ms
      then:
        - switch.turn_off: relay_1
    - min_length: 500ms
      max_length: 1000ms
      then:
        - switch.turn_on: relay_1

条目独立评估，因此所有匹配的自动化都会触发。

`on_double_click`

当按钮被按下两次时将触发此自动化，其中第一次点击的持续时间在 min_length 和 max_length 之间。当第二次上升沿在 min_length 和 max_length 内发生时，将触发自动化。

binary_sensor:
  - platform: gpio
    # ...
    on_double_click:
      min_length: 50ms
      max_length: 350ms
      then:
        - switch.turn_off: relay_1

配置变量：

min_length（可选，Time）：点击应持续的最短时长。默认为 50ms。
max_length（可选，Time）：点击应持续的最长时长。默认为 350ms。
参见 Automation。

`on_multi_click`

当按钮以用户指定的序列按下时，将触发此自动化。

IMPORTANT

使用物理按钮配合 on_multi_click 时，请给二进制传感器添加一个消抖过滤器。机械开关在按下和释放时会抖动，产生额外的 ON/OFF 转换处于时序窗口内。在序列最终窗口内到达的抖动边沿将取消待处理的触发器，因此类似双击的（以及依赖最终转换稳定的类似模式）将会被错过。

delayed_on_off: 20ms 过滤器是大多数微动开关的良好起点，只需多一行：

binary_sensor:
  - platform: gpio
    pin: GPIOXX
    name: "My Button"
    filters:
      - delayed_on_off: 20ms
    on_multi_click:
      - timing:
          - ON for at most 1s
          - OFF for at most 1s
          - ON for at most 1s
          - OFF for at least 0.2s
        then:
          - logger.log: "Double Clicked"

binary_sensor:
  - platform: gpio
    # ...
    on_multi_click:
    - timing:
        - ON for at most 1s
        - OFF for at most 1s
        - ON for 0.5s to 1s
        - OFF for at least 0.2s
      then:
        - logger.log: "Double-Clicked"

配置变量：

timing（必选）：多点点击的时序。它使用基于语言的语法，采用以下风格：
- <ON/OFF> for <TIME> to <TIME>
- <ON/OFF> for at least <TIME>
- <ON/OFF> for at most <TIME>
invalid_cooldown（可选，Time）：如果开始了多点点击，但 timing 中设置的时序不匹配，将激活一段“冷却”期，在此期间不会匹配任何时序。默认为 1s。
参见 Automation。

NOTE

针对你的用例正确设置时序有时会比较困难。如果将全局日志级别设置为 VERBOSE，多点点击触发器会显示有关是什么阻止了触发器发生的日志。

你可以在时序序列末尾使用 OFF 时序来区分不同类型的按压。例如下面的配置会区分双击、长按和短按。

on_multi_click:
- timing:
    - ON for at most 1s
    - OFF for at most 1s
    - ON for at most 1s
    - OFF for at least 0.2s
  then:
    - logger.log: "Double Clicked"
- timing:
    - ON for 1s to 2s
    - OFF for at least 0.5s
  then:
    - logger.log: "Single Long Clicked"
- timing:
    - ON for at most 1s
    - OFF for at least 0.5s
  then:
    - logger.log: "Single Short Clicked"

虽然 on_click 仅在信号的下降沿触发，而 on_double_click 仅在第二个上升沿触发，但 on_multi_click 的自动化可以在任何时间触发。例如，一个没有 OFF 的 ON for at least 时序不需要等待下降沿。这支持实现持续长按，并可选地为同一传感器处理点击：

binary_sensor:
  - platform: gpio
    id: button_1
    # ...
    on_multi_click:
    # 也可以使用 `on_click` 替换此部分
    - timing:
        - ON for at most 0.7s
      then:
        - light.turn_on:
            id: light_1
            brightness: 10%
    - timing:
        - ON for at least 1s
      then:
        - while:
            condition:
              # 自我引用此传感器
              binary_sensor.is_on: button_1
            then:
              - light.dim_relative:
                  id: light_1
                  relative_brightness: 5%
                  transition_length: 0.1s
              - delay: 0.1s

`binary_sensor.is_on` / `binary_sensor.is_off` 条件

此 Condition 检查给定的二进制传感器是否处于 ON（或 OFF）状态。

# 在某个触发器中：
on_...:
  if:
    condition:
      # is_off 使用相同的语法
      binary_sensor.is_on: my_binary_sensor

lambda 调用

从 lambda 中，你可以调用所有二进制传感器上的多个方法来执行一些高级操作。

publish_state() : 手动使二进制传感器在程序的任意位置发布并保存状态。

    // 在 lambda 中，发布 OFF 状态。
    id(my_binary_sensor).publish_state(false);

    // 在 lambda 中，发布 ON 状态。
    id(my_binary_sensor).publish_state(true);

.state : 获取二进制传感器的当前状态。

    // 在 lambda 中，获取二进制传感器状态并按条件执行某些操作
    if (id(my_binary_sensor).state) {
      // 二进制传感器处于 ON 状态，在这里执行某操作
    } else {
      // 二进制传感器处于 OFF 状态，在这里执行其他操作
    }

参见

API 参考：binary_sensor.h

二进制传感器组件

基础二进制传感器配置

动作

binary_sensor.invalidate_state 动作

二进制传感器过滤器

invert

delayed_on

delayed_off

delayed_on_off

autorepeat

lambda

settle

timeout

二进制传感器自动化

on_press

on_release

on_state

on_state_change

on_click

on_double_click

on_multi_click

binary_sensor.is_on / binary_sensor.is_off 条件

lambda 调用

参见

`binary_sensor.invalidate_state` 动作

`invert`

`delayed_on`

`delayed_off`

`delayed_on_off`

`autorepeat`

`lambda`

`settle`

`timeout`

`on_press`

`on_release`

`on_state`

`on_state_change`

`on_click`

`on_double_click`

`on_multi_click`

`binary_sensor.is_on` / `binary_sensor.is_off` 条件