GPIO 二进制传感器

GPIO 二进制传感器平台允许你将设备上任何输入引脚用作二进制传感器。默认情况下，它使用硬件中断进行高效的状态变更检测，CPU 使用率极低。

# 示例配置条目
binary_sensor:
  - platform: gpio
    pin: D2
    name: "Living Room Window"
    device_class: window

# 包含中断配置的示例
binary_sensor:
  - platform: gpio
    pin: GPIO13
    name: "Motion Sensor"
    # use_interrupt: true  # 默认 - 使用中断
    interrupt_type: RISING  # 仅检测低到高的转换

# 轮询模式示例（旧行为）
binary_sensor:
  - platform: gpio
    pin: GPIO14
    name: "Legacy Sensor"
    use_interrupt: false  # 使用轮询而非中断

# 共享引脚示例（自动轮询模式）
binary_sensor:
  - platform: gpio
    pin:
      number: GPIO15
      allow_other_uses: true  # 引脚与其他组件共享
    name: "Pump Status"
    # 中断将自动禁用以保证兼容性

配置变量

pin（必选，Pin Schema）：要监控的引脚。
use_interrupt（可选，boolean）：使用硬件中断而非轮询，以获得更好的性能和更低的 CPU 使用率。大多数平台默认为 true，但由于硬件限制，基于 LibreTiny 的平台（BK72xx、RTL87xx、LN882x）默认为 false。仅支持内部 GPIO 引脚。
interrupt_type（可选，string）：要使用的中断类型。可选值之一：
- ANY (默认): 在任何边沿变化时触发（高到低或低到高）
- RISING: 仅在上升沿（低到高）触发
- FALLING: 仅在下降沿（高到低）触发
来自 Binary Sensor 的所有其他选项。

中断模式与轮询模式

GPIO 二进制传感器支持两种工作模式：

中断模式（默认，use_interrupt: true ）：

使用硬件中断检测引脚状态变更
极其高效——CPU 使用率最多降低 98%
更新在每个循环周期中处理一次（与轮询模式相同）
短于循环间隔的转换会被忽略，以保持与轮询模式的向后兼容
仅在引脚实际改变状态时处理
推荐用于大多数用例

轮询模式（use_interrupt: false ）：

在主循环中持续读取引脚状态
CPU 使用率较高，但实现更简单
短于循环间隔的转换会被忽略
仅在不支持中断或为了兼容性时使用

NOTE

中断模式仅适用于内部 GPIO 引脚。外部 GPIO 扩展器（如 PCF8574）会自动回退到轮询模式。

基于 LibreTiny 的平台（BK72xx、RTL87xx、LN882x）由于边沿中断的硬件限制，默认使用轮询模式。如有需要，你可以明确启用中断模式，但它在所有引脚上可能无法可靠工作。

NOTE

当引脚配置为 allow_other_uses: true（用于与其他组件共享）时，会自动禁用中断以防止冲突。这确保了与需要监控引脚状态变更的组件（如 duty_cycle 传感器）的兼容性。传感器将改用轮询模式。

激活内部上拉

如果你连接了一个没有外部上拉的按钮，或者在日志输出中始终看到大量 ON/OFF 事件，这通常意味着 GPIO 引脚处于浮空状态。

对于这种情况，你需要手动启用 ESP 上的上拉（或下拉）电阻，你可以通过 Pin Schema 来完成。

binary_sensor:
  - platform: gpio
    pin:
      number: D2
      mode:
        input: true
        pullup: true
    name: ...

反转值

使用 Pin Schema 的 inverted 属性来反转二进制传感器：

# 示例配置条目
binary_sensor:
  - platform: gpio
    pin:
      number: D2
      inverted: true
    name: ...

消抖

一些二进制传感器稍不稳定，在按下时会在 ON 和 OFF 状态之间快速转换。为了解决此问题并对信号进行消抖，请使用二进制传感器过滤器：

# 示例配置条目
binary_sensor:
  - platform: gpio
    pin: D2
    name: ...
    filters:
      - delayed_on: 10ms

上面的示例仅在按钮保持高电平超过 10ms 时才会使信号变高。或者，下面的配置会使二进制传感器立即发布 ON 值，但会等待 10ms 再发布 OFF 值：

# 示例配置条目
binary_sensor:
  - platform: gpio
    pin: D2
    name: ...
    filters:
      - delayed_off: 10ms

GPIO 二进制传感器

配置变量

中断模式与轮询模式

激活内部上拉

反转值

消抖

参见