TOUCH

About

Touch sensor is a peripheral, that has an internal oscillator circuit and it measures charge/discharge frequency over a fixed period of time on respective GPIO pins. Therefore these touch sensors are also known as capacitive sensors. For example, if you touch any of these pins, finger electrical charge will change this number of cycles, by changing the RC circuit attached to the touch sensor. The TouchRead() will return the number of cycles (charges/discharges) in a certain time (meas). The change of this count will be used to validate if a touch has happened or not. These pins can be easily integrated into capacitive pads, and replace mechanical buttons.

Note

Touch peripheral is not present in every SoC. Refer to datasheet of each chip for more info.

Arduino-ESP32 TOUCH API

TOUCH common API

touchRead

This function gets the touch sensor data. Each touch sensor has a counter to count the number of charge/discharge cycles. When the pad is ‘touched’, the value in the counter will change because of the larger equivalent capacitance. The change of the data determines if the pad has been touched or not.

touch_value_t touchRead(uint8_t pin);

pin GPIO pin to read TOUCH value

This function will return touch pad value as uint16_t (ESP32) or uint32_t (ESP32-S2/S3).

touchSetCycles

This function is used to set cycles that measurement operation takes. The result from touchRead, threshold and detection accuracy depend on these values. The defaults are setting touchRead to take ~0.5 ms.

void touchSetCycles(uint16_t measure, uint16_t sleep);

measure Sets the time that it takes to measure touch sensor value
sleep Sets waiting time before next measure cycle

touchAttachInterrupt

This function is used to attach interrupt to the touch pad. The function will be called if a touch sensor value falls below the given threshold for ESP32 or rises above the given threshold for ESP32-S2/S3. To determine a proper threshold value between touched and untouched state, use touchRead() function.

void touchAttachInterrupt(uint8_t pin, void (*userFunc)(void), touch_value_t threshold);

pin GPIO TOUCH pad pin
userFunc Function to be called when interrupt is triggered
threshold Sets the threshold when to call interrupt

touchAttachInterruptArg

This function is used to attach interrupt to the touch pad. In the function called by ISR you have the given arguments available.

void touchAttachInterruptArg(uint8_t pin, void (*userFunc)(void*), void *arg, touch_value_t threshold);

pin GPIO TOUCH pad pin
userFunc Function to be called when interrupt is triggered
arg Sets arguments to the interrupt
threshold Sets the threshold when to call interrupt

touchDetachInterrupt

This function is used to detach interrupt from the touch pad.

void touchDetachInterrupt(uint8_t pin);

pin GPIO TOUCH pad pin.

touchSleepWakeUpEnable

This function is used to setup touch pad as the wake up source from the deep sleep.

Note

ESP32-S2 and ESP32-S3 only support one sleep wake up touch pad.

void touchSleepWakeUpEnable(uint8_t pin, touch_value_t threshold);

pin GPIO TOUCH pad pin
threshold Sets the threshold when to wake up

TOUCH API specific for ESP32 chip (TOUCH_V1)

touchInterruptSetThresholdDirection

This function is used to tell the driver if it shall activate the interrupt if the sensor is lower or higher than the threshold value. Default is lower.

void touchInterruptSetThresholdDirection(bool mustbeLower);

TOUCH API specific for ESP32-S2 and ESP32-S3 chip (TOUCH_V2)

touchInterruptGetLastStatus

This function is used get the latest ISR status for the touch pad.

bool touchInterruptGetLastStatus(uint8_t pin);

This function returns true if the touch pad has been and continues pressed or false otherwise.

Example Applications

Example of reading the touch sensor.

// ESP32 Touch Test
// Just test touch pin - Touch0 is T0 which is on GPIO 4.

void setup() {
  Serial.begin(115200);
  delay(1000);  // give me time to bring up serial monitor
  Serial.println("ESP32 Touch Test");
}

void loop() {
  Serial.println(touchRead(T1));  // get value using T0
  delay(1000);
}

A usage example for the touch interrupts.

/*
This is an example how to use Touch Intrrerupts
The bigger the threshold, the more sensible is the touch
*/

int threshold = 40;
bool touch1detected = false;
bool touch2detected = false;

void gotTouch1() {
  touch1detected = true;
}

void gotTouch2() {
  touch2detected = true;
}

void setup() {
  Serial.begin(115200);
  delay(1000);  // give me time to bring up serial monitor
  Serial.println("ESP32 Touch Interrupt Test");
  touchAttachInterrupt(T2, gotTouch1, threshold);
  touchAttachInterrupt(T3, gotTouch2, threshold);
}

void loop() {
  if (touch1detected) {
    touch1detected = false;
    Serial.println("Touch 1 detected");
  }
  if (touch2detected) {
    touch2detected = false;
    Serial.println("Touch 2 detected");
  }
}

More examples can be found in our repository -> Touch examples.