ESP32 触摸板

电容式触摸检测在 ESP32、ESP32-S2 或 ESP32-S3 处理器上可行。在 ESPHome 中，它分为两部分配置：

• 组件/集线器
• 二进制传感器

组件/集线器

esp32_touch 组件创建一个全局集线器，在 ESP32、ESP32-S2 或 ESP32-S3 处理器支持的 GPIO 引脚 上启用（电容式）触摸检测。启用此功能后，可以配置 二进制传感器 以允许触摸检测。

# 示例配置条目
esp32_touch:
  setup_mode: false

配置变量

• setup_mode (可选, 布尔值): 是否在日志中显示触摸板值的调试消息。对于找出二进制传感器的合适阈值很有用，但会使日志过多。请参阅 设置触摸板 了解更多信息。默认为 false。

• id (可选, ID): 手动指定用于代码生成的 ID。

高级选项

这些变量可以添加到集线器组件的配置（上方），对于微调和/或传感器行为异常时很有用。

所有处理器

• sleep_duration (可选, 时间): 设置表示触摸外设在测量之间应休眠的时间段。这可以降低功耗但使传感器变慢。默认约为 27 毫秒。

• measurement_duration (可选, 时间): 设置所有触摸板的转换时间。较长的转换时间意味着可以对触摸板执行更多的充电/放电循环，从而提高准确性。默认约为 8ms，最大值。

• low_voltage_reference (可选): 用于充电周期的低电压参考。可选 0.5V、0.6V、0.7V、0.8V。默认为 0.5V。

• high_voltage_reference (可选): 用于充电周期的高电压参考。可选 2.4V、2.5V、2.6V、2.7V。默认为 2.7V。

• voltage_attenuation (可选): 用于充电周期的电压衰减。可选 1.5V、1V、0.5V、0V。默认为 0V。

有关上述参数的更详细说明，请参阅 ESP-IDF 文档。

仅 ESP32

• iir_filter (可选, 时间): 可选择对所有触摸板应用 无限脉冲响应 滤波器。这可以大大提高触摸板的准确性，但较高的值会降低响应时间。一个好的起始值是 10ms。默认情况下，IIR 滤波器处于非活动状态。

仅 ESP32-S2 和 ESP32-S3

对于下面的每个配置类别，如果指定了一个选项，则必须指定所有选项。 下面的配置选项没有任何默认值；换句话说，它们默认处于非活动状态。

滤波器配置：

• filter_mode (可选): 设置滤波器模式。必须是 IIR_4、IIR_8、IIR_16、IIR_32、IIR_64、IIR_128、IIR_256 或 JITTER 之一。

• debounce_count (可选, int 范围 0-7): 设置去抖计数；如果测量值持续超过阈值 n + 1 次，触摸传感器状态将更改。

• noise_threshold (可选, int 范围 0-3): 噪声阈值系数。越高 = 抗噪性越强。实际噪声应小于（噪声系数 * 触摸阈值）。系数为 0: 4/8; 1: 3/8; 2: 2/8; 3: 1。

• jitter_step (可选, int 范围 0-15): 设置抖动滤波器步长。

• smooth_mode (可选): 对原始数据应用的滤波级别，以对抗大噪声干扰。必须是 OFF、IIR_2、IIR_4 或 IIR_8 之一。

有关滤波器配置的更详细说明，请参阅 ESP-IDF 文档。

降噪配置：

• denoise_grade (可选): 设置降噪通道的降噪范围。通过测量降噪通道的噪声幅度确定。必须是 BIT12、BIT10、BIT8 或 BIT4 之一。

• denoise_cap_level (可选): 选择降噪通道的内部参考电容。必须是 L0、L1、L2、L3、L4、L5、L6 或 L7 之一。

有关降噪配置的更详细说明，请参阅 ESP-IDF 文档。

防水配置：

• waterproof_guard_ring (可选, 引脚): 设置用于保护垫的触摸通道。保护垫用于检测覆盖触摸面板的大面积水。

• waterproof_shield_driver (可选): 屏蔽通道驱动能力配置；屏蔽通道上的寄生电容越大，需要设置的驱动能力越高。必须是 L0、L1、L2、L3、L4、L5、L6 或 L7 之一。

有关防水配置的更详细说明，请参阅 ESP-IDF 文档。

二进制传感器

esp32_touch 二进制传感器平台允许您使用 ESP32 的触摸外设来检测某个引脚是否正在被”触摸”。

首先，您需要设置 全局触摸集线器。然后您可以将单独的触摸板添加为二进制传感器。当在这些引脚上检测到触摸时，二进制传感器将报告 ON 状态。当然，如果没有检测到触摸，二进制传感器将报告 OFF 状态。

# 示例配置条目
esp32_touch:

binary_sensor:
  - platform: esp32_touch
    name: "ESP32 触摸板"
    pin: GPIOXX
    threshold: 1000

配置变量

• pin (*必需, 引脚): 用于检测触摸事件的引脚。

• threshold (*必需, int): 用于检测触摸事件的阈值。请参阅下面的 查找阈值 以帮助确定此值。

• wakeup_threshold (可选, int): 用于检测触摸事件以从深度睡眠唤醒的阈值。请参阅下面的 查找阈值 以帮助确定此值。应该触发从深度睡眠唤醒的触摸板传感器必须指定此值。还必须配置 深度睡眠组件 以启用从触摸事件唤醒。请注意，在深度睡眠期间没有任何滤波器处于活动状态。

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

原始值

如果需要访问原始值，可以创建一个模板传感器来轮询它们：

# 访问原始值的示例配置条目
esp32_touch:
  id: esp32_touch_1

binary_sensor:
  - platform: esp32_touch
    id: esp32_touch_pad
    pin: GPIOXX
    threshold: 0

sensor:
  - platform: template
    name: "原始触摸值"
    lambda: |-
        return id(esp32_touch_pad).get_value();
    update_interval: 3s

一个使用示例是在一个区域内集成多个较小传感器的宽区域压力传感器。制作两条夹着纸的铝箔条，将一根导线连接到触摸引脚，另一根连接到地。在柔性物体（如塑料垫）下设置多个传感器，添加原始值，并应用阈值。

触摸板引脚

ESP32、ESP32-S2 和 ESP32-S3 上的各种引脚可用于检测触摸。如下所示（使用默认的”原始”引脚名称/编号）：

ESP32	ESP32-S2	ESP32-S3
GPIO4, GPIO0, GPIO2, GPIO15, GPIO13, GPIO12, GPIO14, GPIO27, GPIO33, GPIO32	GPIO1 - GPIO14	GPIO1 - GPIO14

查找阈值

对于要监控的每个触摸板，您需要先找到一个阈值。此阈值用于使用从处理器内部传感器硬件读取的原始值来确定触摸板是否被触摸。当传感器没有接触时，值通常在某个范围内波动；当触摸传感器的触摸板时，值将显著变化，从而可以检测到触摸。

传感器硬件报告的确切值将因处理器、PCB 布局甚至环境因素而异。

要找到合适的阈值，首先配置 ESP32 触摸集线器 使用 setup_mode: 配置选项记录测量值。接下来，为要观察的触摸板添加一些二进制传感器。您还需要在配置中放入一些（临时的）阈值（如下所示）以使验证器满意；一旦我们确定合适的值，我们稍后会替换这些值。

# 用于查找阈值值的示例配置条目
esp32_touch:
  setup_mode: true

binary_sensor:
  - platform: esp32_touch
    name: "ESP32 触摸板 GPIO27"
    pin: GPIO27
    threshold: 1000

上传程序/配置并观察设备的日志；您将看到集线器组件记录的值。触摸传感器的引脚/触摸板应该导致记录的值发生（显著）变化。尝试对触摸板施加不同大小的力；应该会出现一个模式，揭示一个介于”已触摸”和”未触摸”之间的值，二进制传感器随后将使用该值来区分这两种状态。

一旦您确定了适当的值，更新配置中的阈值参数并测试更新后的配置。您可能需要重复此过程几次来微调行为并使其恰到好处。

最后，不要忘记通过将 setup_mode 设置回 false 来禁用它；保持启用会降低 ESP 的整体性能。

S2 和 S3 变体

NOTE

ESP32-S2 和 ESP32-S3 触摸配置

默认的 measurement_duration 和 sleep_duration 值针对原始 ESP32 进行了优化，可能根本无法在 S2/S3 变体上工作。S2/S3 触摸硬件需要不同的时序设置。

关键差异：

• 触摸时触摸值增加（与 ESP32 相反，后者减少）
• 与原始 ESP32 相比返回更高的原始值
• 需要较低的测量持续时间 - 默认的 8ms 对 S2/S3 来说通常太高

S2/S3 的示例设置：

esp32_touch:
  setup_mode: false
  measurement_duration: 0.25ms  # 比默认的 8ms 低得多
  sleep_duration: 0.5ms

binary_sensor:
  - platform: esp32_touch
    name: "触摸传感器"
    pin: GPIO1
    threshold: 1000  # 根据您的硬件调整

如果您熟悉 ESP32 硬件并拿起 S2 或 S3 变体，您很可能会注意到它们之间的一些行为差异。特别是：

• S2 和 S3 变体上的原始触摸传感器读数通常返回比原始 ESP32 硬件更大的数值。

• S2 和 S3 变体上与触摸传感器接触会导致原始传感器读数增加；在原始 ESP32 上，接触会导致此值减少。

这些行为差异是由于硬件和软件 (ESP-IDF) 接口的变化，应该被预期——如果您正在将配置从原始 ESP32 移动到 S2 或 S3 变体，预期您需要调整配置以适应此行为。

最重要的是，默认的 measurement_duration 为 8ms（针对原始 ESP32 优化）对于 S2/S3 变体来说通常太高，可能完全阻止触摸检测工作。使用像 0.25ms 这样的较低值已被发现适用于许多 S2/S3 设备，尽管特定参数可能仍需要根据硬件实现进行调整。

另见

• 二进制传感器组件
• esp-idf 触摸传感器 API
• API Reference: esp32_touch.h