Skip to content

[esp32_touch] Add ESP32-P4 support, document voltage_attenuation as ESP32-only #6104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
swoboda1337 wants to merge 2 commits into
base: next
Choose a base branch
from
Draft

[esp32_touch] Add ESP32-P4 support, document voltage_attenuation as ESP32-only #6104

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cf95c19
[esp32_touch] Add ESP32-P4 support, deprecate voltage_attenuation
swoboda1337 Feb 17, 2026
860fd34
[esp32_touch] Restore voltage_attenuation documentation
swoboda1337 Feb 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 22 additions & 20 deletions src/content/docs/components/binary_sensor/esp32_touch.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import esp32TouchUiImg from './images/esp32_touch-ui.png';
import esp32TouchFindingThresholdsImg from './images/esp32_touch-finding_thresholds.png';
import APIRef from '@components/APIRef.astro';

Capacitive touch detection is possible on ESP32, ESP32-S2 or ESP32-S3 processors.
Capacitive touch detection is possible on ESP32, ESP32-S2, ESP32-S3 and ESP32-P4 processors.
In ESPHome, it is configured in two parts:

- [Component/Hub](#esp32-touch-component)
Expand All @@ -19,7 +19,7 @@ In ESPHome, it is configured in two parts:
## Component/Hub

The `esp32_touch` component creates a global hub enabling (capacitive) touch detection on GPIO pins
[supported by ESP32, ESP32-S2 or ESP32-S3 processors](#esp32-touch-pad-pins). With this enabled,
[supported by ESP32, ESP32-S2, ESP32-S3 and ESP32-P4 processors](#esp32-touch-pad-pins). With this enabled,
[binary sensors](#esp32-touch-binary-sensor) may then be configured to permit touch detection.

```yaml
Expand Down Expand Up @@ -52,13 +52,15 @@ the sensors aren't behaving as expected.
time for all touch pads. A longer conversion time means that more charge/discharge cycles of the touch pad
can be performed, therefore increasing accuracy. Default is about 8ms, the maximum amount.

#### ESP32, ESP32-S2 and ESP32-S3 only

- **low_voltage_reference** (*Optional*): The low voltage reference to use for the charge cycles. One of `0.5V`,
`0.6V`, `0.7V`, `0.8V`. Default is `0.5V`.

- **high_voltage_reference** (*Optional*): The high voltage reference to use for the charge cycles. One of `2.4V`,
`2.5V`, `2.6V`, `2.7V`. Default is `2.7V`.

- **voltage_attenuation** (*Optional*): The voltage attenuation to use for the charge cycles. One of `1.5V`, `1V`,
- **voltage_attenuation** (*Optional*, ESP32 only): The voltage attenuation to use for the charge cycles. One of `1.5V`, `1V`,
`0.5V`, `0V`. Default is `0V`.

For a more detailed explanation of the parameters above, please see the
Expand All @@ -71,15 +73,15 @@ For a more detailed explanation of the parameters above, please see the
filter should be applied to all touch pads. This can increase the accuracy of the touch pads a lot, but higher values
decrease the response time. A good value to start with is `10ms`. By default, the IIR filter is inactive.

#### ESP32-S2 and ESP32-S3 only
#### ESP32-S2, ESP32-S3 and ESP32-P4 only

**For each configuration category below, if one option is specified, all options must be specified.** The configuration
options below do not have any default values; in other words, they are inactive by default.

Filter configuration:

- **filter_mode** (*Optional*): Sets the filter mode. Must be one of `IIR_4`, `IIR_8`, `IIR_16`,
`IIR_32`, `IIR_64`, `IIR_128`, `IIR_256` or `JITTER`.
`IIR_32`, `IIR_64`, `IIR_128`, `IIR_256` (S2/S3 only) or `JITTER`.

- **debounce_count** (*Optional*, `int` range 0-7): Sets the debounce count; if the measured values continue to
exceed the threshold for `n + 1` times, the touch sensor state changes.
Expand All @@ -94,7 +96,7 @@ Filter configuration:
For a more detailed explanation of the filter configuration, please see the
[ESP-IDF documentation.](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/touch_pad.html#_CPPv419touch_filter_config)

Denoise configuration:
Denoise configuration (ESP32-S2 and ESP32-S3 only, not available on ESP32-P4):

- **denoise_grade** (*Optional*): Sets the denoise range of the denoise channel. Determined by measuring the noise
amplitude of the denoise channel. Must be one of `BIT12`, `BIT10`, `BIT8` or `BIT4`.
Expand Down Expand Up @@ -188,12 +190,12 @@ under a flexible object like a plastic mat, add the raw values, and apply a thre

## Touch Pad Pins

Various pins on the ESP32, ESP32-S2 and ESP32-S3 can be used to detect touches. They are as follows (using the default
Various pins on the ESP32, ESP32-S2, ESP32-S3 and ESP32-P4 can be used to detect touches. They are as follows (using the default
"raw" pin names/numbers):

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

<span id="esp32-finding-thresholds"></span>

Expand Down Expand Up @@ -239,21 +241,21 @@ reduce the ESP's overall performance.

<span id="esp32-note-about-variants"></span>

## S2 and S3 Variants
## S2, S3 and P4 Variants

> [!NOTE]
> **ESP32-S2 and ESP32-S3 Touch Configuration**
> **ESP32-S2, ESP32-S3 and ESP32-P4 Touch Configuration**
>
> The default `measurement_duration` and `sleep_duration` values are optimized for the original ESP32 and
> **may not work at all on S2/S3 variants**. The S2/S3 touch hardware requires different timing settings.
> **may not work at all on S2/S3/P4 variants**. These variants have different touch hardware requiring different timing settings.
>
> Key differences:
>
> - **Touch values increase** when touched (opposite of ESP32 which decreases)
> - **Higher raw values** are returned compared to original ESP32
> - **Lower measurement duration required** - the default 8ms is often too high for S2/S3
> - **Lower measurement duration required** - the default 8ms is often too high for S2/S3/P4
>
> **Example settings for S2/S3:**
> **Example settings for S2/S3/P4:**
>
> ```yaml
> esp32_touch:
Expand All @@ -268,21 +270,21 @@ reduce the ESP's overall performance.
> threshold: 1000 # Adjust based on your hardware
> ```

If you're familiar with the ESP32 hardware and pick up an S2 or S3 variant, you're likely to notice some behavioral
If you're familiar with the ESP32 hardware and pick up an S2, S3 or P4 variant, you're likely to notice some behavioral
differences between them. In particular:

- Raw touch sensor readings on the S2 and S3 variants will generally return larger numeric values than the original
- Raw touch sensor readings on the S2, S3 and P4 variants will generally return larger numeric values than the original
ESP32 hardware.

- Contact with the touch sensor on the S2 and S3 variants will result in the raw sensor value reading *increasing*; on
- Contact with the touch sensor on the S2, S3 and P4 variants will result in the raw sensor value reading *increasing*; on
the original ESP32, contact would cause this value to *decrease*.

These behavioral differences are due to changes in the hardware and software (ESP-IDF) interfaces and should be
expected -- if you are moving your configuration from an original ESP32 to an S2 or S3 variant, expect that you'll need
expected -- if you are moving your configuration from an original ESP32 to an S2, S3 or P4 variant, expect that you'll need
to make some adjustments to your configuration to accommodate this behavior.

Most importantly, the default `measurement_duration` of 8ms (optimized for original ESP32) is often too high for
S2/S3 variants and can prevent touch detection from working entirely. Using a much lower value like 0.25ms has been
S2/S3/P4 variants and can prevent touch detection from working entirely. Using a much lower value like 0.25ms has been
found to work across many S2/S3 devices, though specific parameters may still need tuning per hardware implementation.

## See Also
Expand Down
Loading