GPIO 二进制传感器

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

# 示例配置条目
binary_sensor:
  - platform: gpio
    pin: D2
    name: "客厅窗户"
    device_class: window

# 带中断配置的示例
binary_sensor:
  - platform: gpio
    pin: GPIO13
    name: "运动传感器"
    # use_interrupt: true  # 默认 - 使用中断
    interrupt_type: RISING  # 仅检测低到高的转换

# 使用轮询模式的示例（传统行为）
binary_sensor:
  - platform: gpio
    pin: GPIO14
    name: "传统传感器"
    use_interrupt: false  # 使用轮询而不是中断

# 共享引脚的示例（自动轮询模式）
binary_sensor:
  - platform: gpio
    pin:
      number: GPIO15
      allow_other_uses: true  # 引脚与其他组件共享
    name: "水泵状态"
    # 为兼容性将自动禁用中断

配置变量

• pin (必需, 引脚模式): 要监控的引脚。

• use_interrupt (可选, 布尔值): 使用硬件中断而不是轮询以获得更好的性能和更低的 CPU 占用。大多数平台默认为 true，但由于硬件限制，基于 LibreTiny 的平台（BK72xx、RTL87xx、LN882x）默认为 false。仅支持内部 GPIO 引脚。

• interrupt_type (可选, 字符串): 要使用的中断类型。可选值：

  • ANY (默认): 在任何边沿变化时触发（高到低或低到高）
  • RISING: 仅在上升沿触发（低到高）
  • FALLING: 仅在下降沿触发（高到低）

• 所有其他选项来自 二进制传感器。

中断模式 vs 轮询模式

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 上手动启用上拉（或下拉）电阻，您可以使用 引脚模式 来实现。

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

反转值

使用 引脚模式 的 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 值，但在发布 OFF 值之前等待 10ms：

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

另见

• 二进制传感器组件
• 引脚模式
• API Reference: gpio_binary_sensor.h