Library gpio.touch | Standard libraries

Library touch

To use this library in your code:

import gpio.touch

Touch sensor support.

This library provides ways to use some GPIO pins as capacitive touch pads.

Raw readings and detection polarity

The value returned by Touch.read is a count derived from the charge and discharge cycles of the touch pad. A finger on the pad increases the pad's capacitance, but the direction in which that changes the raw reading depends on the chip family:

On the original ESP32 the sensor counts charge/discharge cycles within a
fixed time window. Extra capacitance slows those cycles, so the raw reading
*decreases* on touch. The hardware threshold is an absolute cutoff, and the
pad is considered touched when the raw reading falls *below* the threshold.
On the ESP32-S2 and ESP32-S3 the sensor instead counts clock ticks for a
fixed number of charge/discharge cycles. Extra capacitance makes each cycle
longer, so the raw reading *increases* on touch. The hardware threshold is
a delta added to an auto-calibrated benchmark (which tracks the untouched
reading), and the pad is considered touched when the raw reading exceeds
benchmark + threshold.

Note that the raw ranges also differ widely between chips: an untouched ESP32 pad typically reads in the low hundreds, while an untouched ESP32-S3 pad reads in the tens of thousands and rises to several hundred thousand on touch. A threshold calibrated on one chip is not meaningful on another.

Calibration

Call Touch.calibrate on a freshly constructed, untouched pad. It samples the raw reading, picks a threshold that triggers on a roughly one-third change, and stores the observed baseline so that Touch.get can report presses correctly on both polarities.

For applications that need a custom calibration strategy, Touch.threshold and Touch.baseline= can be set directly. Keep in mind the per-chip meaning of the threshold described above.

ESP32

Pins 0, 2, 4, 12-15, 27, 32, 33 can be used as touch pads.

ESP32-C3

The ESP32-C3 does not have touch support.

ESP32-C6

The ESP32-C6 does not have touch support.

ESP32-S2

Pins 1-14 can be used as touch pads.

ESP32-S3

Pins 1-14 can be used as touch pads.

Examples


import gpio.touch show Touch

main:
  // Pin 32 is a touch pad on the original ESP32. See the per-chip sections
  // above for which pins are available on other chips.
  touch := Touch 32
  touch.calibrate
  while not touch.get: sleep --ms=10
  print "touched"
  touch.close

A touch pad can be used to wake the device from deep sleep. See the 'esp32' library.

Classes

Touch

Touch sensor.

Libraries