二进制传感器组件

在 ESPHome 中，您可以使用不同类型的二进制传感器。它们会自动出现在 Home Assistant 前端界面中，并具有多个配置选项。

基础二进制传感器配置

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

binary_sensor:
  - platform: ...
    device_class: motion

配置变量：

id (可选, 字符串): 手动指定用于代码生成的 ID。id 和 name 必须至少指定一个。
name (可选, 字符串): 二进制传感器的名称。id 和 name 必须至少指定一个。

NOTE

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

device_class (可选, 字符串): 传感器的设备类别。请参阅 https://www.home-assistant.io/integrations/binary_sensor/#device-class 获取可用选项列表。
icon (可选, 图标): 手动设置前端界面中二进制传感器使用的图标。
filters (可选, 列表): 应用于二进制传感器值的过滤器列表，例如反转信号。请参阅二进制传感器过滤器。

自动化：

on_press (可选, 自动化): 当按钮被按下时执行的自动化。请参阅 on_press。
on_release (可选, 自动化): 当按钮被释放时执行的自动化。请参阅 on_release。
on_state (可选, 自动化): 当发布新状态时执行的自动化。请参阅 on_state。
on_click (可选, 自动化): 当按钮被按住指定时间段时执行的自动化。请参阅 on_click。
on_double_click (可选, 自动化): 当按钮在指定时间段内被按下两次时执行的自动化。请参阅 on_double_click。
on_multi_click (可选, 自动化): 当按钮以特定顺序被按下时执行的自动化。请参阅 on_multi_click。

高级选项：

internal (可选, 布尔值): 将此组件标记为内部。内部组件不会暴露给前端界面（如 Home Assistant）。仅指定 id 而不指定 name 会隐式将其设置为 true。
disabled_by_default (可选, 布尔值): 如果为 true，则此实体不应添加到任何客户端的前端界面（通常是 Home Assistant），除非用户手动启用（通过 Home Assistant UI）。默认为 false。
trigger_on_initial_state (可选, 布尔值): 如果为 true，当二进制传感器状态从 unknown 变为有效状态时，将触发任何适用的触发器。这适用于第一个有效状态的设置，以及在执行 binary_sensor.invalidate_state 操作后设置的任何有效状态。默认为 false。
entity_category (可选, 字符串): 实体的类别。请参阅 https://developers.home-assistant.io/docs/core/entity/#generic-properties 获取可用选项列表。设置为 "" 可移除默认实体类别。
如果启用了 MQTT，则适用 MQTT 组件的所有其他选项。
如果启用了 Webserver 并选择了版本 3，则适用 Webserver 组件的所有其他选项。请参阅 Webserver 版本 3。

操作

`binary_sensor.invalidate_state` 操作

此操作将使传感器的当前状态失效。它与模板二进制传感器配合使用最有用。状态失效后，将向 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
      # 模板化，仅当干簧开关闭合时延迟 1s (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`

(必需, 时间, 可模板化): 当收到 ON 信号时，等待指定的时间段后再发布 ON 状态。如果在等待期间收到 OFF 值，则 ON 操作将被丢弃。换句话说：只有当二进制传感器保持 ON 状态至少指定的时间段时，才发送 ON 值。使用 lambda 调用时，您应该返回以毫秒为单位的延迟值。对按钮去抖动非常有用。

`delayed_off`

(*必需, 时间, 可模板化): 当收到 OFF 信号时，等待指定的时间段后再发布 OFF 状态。如果在等待期间收到 ON 值，则 OFF 操作将被丢弃。换句话说：只有当二进制传感器保持 OFF 状态至少指定的时间段时，才发送 OFF 值。使用 lambda 调用时，您应该返回以毫秒为单位的延迟值。对按钮去抖动非常有用。

`delayed_on_off`

只有当二进制传感器在相同状态下保持至少指定的时间段时，才发送 ON 或 OFF 值。

此过滤器使用两个时间延迟：开启和关闭。

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

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

(*必需, 时间, 可模板化): ON 和 OFF 延迟。使用 lambda 调用时，您应该返回以毫秒为单位的延迟值。对二进制开关去抖动非常有用。

如果延迟不同，则需要按照以下示例传递：

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

配置变量：

time_on (必需, 时间, 可模板化): ON 延迟。
time_off (必需, 时间, 可模板化): OFF 延迟。

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

`autorepeat`

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

因此，该示例等待一秒钟输出为 ON，每秒切换一次持续五秒钟，然后每秒切换两次直到收到 OFF。

没有时序描述的 autorepeat 过滤器等效于一个所有参数都设置为默认值的时序。

配置变量：

delay (可选, 时间): 进入下一个时序的延迟。默认为 1s。
time_off (可选, 时间): 输出保持 OFF 的间隔。默认为 100ms。
time_on (可选, 时间): 输出保持 ON 的间隔。默认为 900ms。

`lambda`

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

`settle`

(*必需, 时间, 可模板化): 当收到信号时，发布状态但等待接收到的状态在指定时间段内保持不变后再发布任何其他状态更改。此过滤器补充了 delayed_on_off 过滤器，但在延迟期开始时发布值更改。使用 lambda 调用时，您应该返回以毫秒为单位的延迟值。对二进制开关去抖动非常有用。

`timeout`

(*必需, 时间, 可模板化): 如果在指定的时间段内没有发布值，则使状态失效。

二进制传感器自动化

ESPHome 中二进制传感器的触发器使用计算机鼠标的术语。例如，当鼠标按钮被按下时，press 在第一时间被触发。

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

`on_press`

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

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

配置变量：请参阅自动化。

`on_release`

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

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

配置变量：请参阅自动化。

`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

配置变量：请参阅自动化。

`on_state_change`

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

binary_sensor:
  - platform: gpio
    # ...
    on_state_change:
      then:
      - logger.log:
          format: "旧状态为 %s"
          args: ['x_previous.has_value() ? ONOFF(x_previous.value()) : "Unknown"']
      - logger.log:
          format: "新状态为 %s"
          args: ['x.has_value() ? ONOFF(x.value()) : "Unknown"']

配置变量：请参阅自动化。

`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 (可选, 时间): 点击应持续的最小时长。默认为 50ms。
max_length (可选, 时间): 点击应持续的最大时长。默认为 350ms。
请参阅自动化。

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 (可选, 时间): 点击应持续的最小时长。默认为 50ms。
max_length (可选, 时间): 点击应持续的最大时长。默认为 350ms。
请参阅自动化。

`on_multi_click`

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

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: "双击"

配置变量：

timing (必需): 多次点击的时序。这使用基于语法的语言：
- <ON/OFF> for <TIME> to <TIME>
- <ON/OFF> for at least <TIME>
- <ON/OFF> for at most <TIME>
invalid_cooldown (可选, 时间): 如果开始多次点击，但 timing 中设置的时序不匹配，将激活一个”冷却”期，在此期间不会匹配任何时序。默认为 1s。
请参阅自动化。

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: "双击"
- timing:
    - ON for 1s to 2s
    - OFF for at least 0.5s
  then:
    - logger.log: "单击长按"
- timing:
    - ON for at most 1s
    - OFF for at least 0.5s
  then:
    - logger.log: "单击短按"

虽然 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` 条件

此条件检查给定的二进制传感器是否为 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 Reference: 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` 条件