ESP32 触摸按键

在 ESP32、ESP32-S2、ESP32-S3 和 ESP32-P4 处理器上可以使用电容式触摸检测。 在 ESPHome 中，它的配置分为两部分：

• 组件/中心
• 二进制传感器

组件/中心

esp32_touch 组件创建一个全局中心，使 GPIO 引脚 支持 ESP32、ESP32-S2、ESP32-S3 和 ESP32-P4 处理器]的（电容式）触摸检测成为可能。启用后， 二进制传感器 就可以配置为允许触摸检测。

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

配置变量

• setup_mode（可选，boolean）：是否在日志中显示带有触摸按键值的调试消息。 对于找出二进制传感器的合适阈值很有用，但 会淹没日志。更多信息参见设置触摸按键。 默认为 false。

• id（可选，ID）：手动指定用于代码生成的 ID。

高级选项

这些变量可以添加到中心组件的配置（上方）中，对于微调以及/或者 传感器行为不符合预期时很有用。

所有处理器

• sleep_duration（可选，Time）：设置一个时间段 表示触摸外设应在两次测量之间休眠的时间量。这可以降低 功耗，但会使传感器变慢。默认值约为 27 毫秒。

• measurement_duration（可选，Time）：设置所有触摸按键的转换 时间。更长的转换时间意味着可以对触摸按键执行更多的充放电周期，因此提高精度。默认值约为 8ms，即最大量。

仅限 ESP32、ESP32-S2 和 ESP32-S3

• 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（可选，仅限 ESP32）：充放电周期要使用的电压衰减。可选 1.5V、1V、 0.5V、0V 之一。默认为 0V。

有关上述参数的更详细解释，请参见 ESP-IDF 文档。

仅限 ESP32

• iir_filter（可选，Time）：可选地为所有触摸按键设置一个 无限脉冲响应 过滤器。这可以大大提高触摸按键的精度，但更高的值 会降低响应时间。一个好的初始值为 10ms。默认情况下，IIR 过滤器处于非活动状态。

仅限 ESP32-S2、ESP32-S3 和 ESP32-P4

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

过滤器配置：

• filter_mode（可选）：设置过滤器模式。必须是 IIR_4、IIR_8、IIR_16、 IIR_32、IIR_64、IIR_128、IIR_256（仅限 S2/S3）或 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 文档。

降噪配置（仅限 ESP32-S2 和 ESP32-S3，ESP32-P4 不可用）：

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

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

有关降噪配置的更详细解释，请参见 ESP-IDF 文档。

防水配置：

• waterproof_guard_ring（可选，Pin）：设置保护垫要使用的触摸通道。保护 垫用于检测覆盖触摸面板的大面积水体。

• 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 Touch Pad"
    pin: GPIOXX
    threshold: 1000

配置变量

• pin（必选，Pin）：要检测触摸 事件的引脚。

• threshold（必选，int ）：用于检测触摸事件的阈值。 参见下面的确定阈值以获取确定此值的帮助。

• wakeup_threshold（可选，int ）：用于检测从深度睡眠唤醒的触摸事件的阈值。 参见下面的确定阈值以获取确定此值的帮助。应从深度睡眠 中唤醒的触摸按键传感器必须指定此值。还必须配置 Deep Sleep Component 以启用 从触摸事件中唤醒。请注意，在深度睡眠期间没有任何过滤器处于活动状态。

• 来自 Binary Sensor 的所有其他选项。

原始值

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

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

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

sensor:
  - platform: template
    name: "Raw touch value"
    lambda: |-
        return id(esp32_touch_pad).get_value();
    update_interval: 3s

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

触摸按键引脚

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

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

确定阈值

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

传感器硬件报告的确切值会根据处理器、PCB 布局甚至可能的 环境因素而有所不同。

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

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

binary_sensor:
  - platform: esp32_touch
    name: "ESP32 Touch Pad GPIO27"
    pin: GPIO27
    threshold: 1000

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

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

最后，不要忘记通过将 setup_mode 选项重新设为 false 来禁用它 ；保持启用状态将 降低 ESP 的整体性能。

S2、S3 和 P4 变体

NOTE

ESP32-S2、ESP32-S3 和 ESP32-P4 触摸配置

默认的 measurement_duration 和 sleep_duration 值是针对原始 ESP32 进行优化的， 在 S2/S3/P4 变体上可能完全无法工作。这些变体具有不同的触摸硬件，需要不同的时序设置。

关键区别：

• 触摸值会增大（与减小的 ESP32 相反）
• 返回的原始值更高，相比原始 ESP32
• 需要更短的测量持续时间 - 默认的 8ms 对 S2/S3/P4 来说通常过高

S2/S3/P4 的示例设置：

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

binary_sensor:
  - platform: esp32_touch
    name: "Touch Sensor"
    pin: GPIOXX
    threshold: 1000  # 根据你的硬件进行调整

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

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

• 在 S2、S3 和 P4 变体上，与触摸传感器接触会导致原始传感器值增大；而 在原始 ESP32 上，接触会导致该值减小。

这些行为差异是由硬件和软件（ESP-IDF）接口的更改造成的，因此应 被预期——如果你要将配置从原始 ESP32 迁移到 S2、S3 或 P4 变体，请预期你需要 对配置进行一些调整以适应这种行为。

最重要的是，默认的 8ms measurement_duration（针对原始 ESP32 优化）对 S2/S3/P4 变体来说通常过高，并且可能导致触摸检测完全无法工作。使用像 0.25ms 这样低得多的值已被 发现在许多 S2/S3 设备上有效，尽管具体的参数可能仍需要根据硬件实现进行调整。

参见

• 二进制传感器组件
• esp-idf Touch Sensor API
• API 参考：esp32_touch.h