Un trozo de papel aluminio pegado bajo la cubierta de un escritorio, un cable y un ESP32 bastan para tener un botón sin piezas móviles, que no se gasta y que funciona a través de plástico delgado o vidrio. Esa es la promesa de los pines táctiles capacitivos, y en esta guía vas a usarlos con ESP IDF, el framework oficial de Espressif, en lugar del Arduino Core.
Al terminar vas a saber qué pines táctiles tiene tu placa, cómo funciona por dentro la medición, por qué con ESP IDF hay que calibrar el canal antes de usarlo y cómo encender un LED con un toque usando callbacks del driver touch_sens. El mismo código compila sin cambios para el ESP32 original, el ESP32-S2/S3 y el ESP32-P4.
Cómo detecta un toque el ESP32
Un pin táctil es, en el fondo, un capacitor con una de sus placas en el aire. El periférico carga y descarga ese pin una y otra vez entre dos voltajes de referencia y cuenta cuánto se demora. Cuando acercas el dedo, tu cuerpo suma capacitancia (unos pocos picofaradios) y el ciclo de carga cambia. El driver no ve "un toque": ve un número que se mueve respecto de su valor en reposo.
De ahí sale la diferencia clave entre generaciones:
- En el ESP32 original (sensor versión 1), el valor baja al tocar. Por eso el umbral se pone en un 98 % del valor en reposo (
ACTIVE_THRESH_RATIO 0.98). - En el ESP32-S2/S3 y P4 (versiones 2 y 3), el valor sube al tocar, y el umbral se define como un 2 % por sobre la referencia (
ACTIVE_THRESH_RATIO 0.02).
Si alguna vez portaste código táctil del ESP32 al S3 y dejó de funcionar, esta inversión suele ser la causa.
¿Qué pines puedes usar?
El ESP32 original trae 10 GPIO táctiles; el ESP32-S3, 14. Los ESP32-C2, C3, C6 y H2 no tienen pines táctiles, así que si tu placa es una de esas, este tutorial no aplica.

En la DevKit del ESP32 original los pines táctiles van de Touch 0 a Touch 9. En la ESP32-S3 DevKitC están marcados en naranjo:

Ojo con la numeración: el canal táctil no siempre coincide con el número de GPIO. En el ESP32-S3, TOUCH8 es el GPIO 8; en el ESP32 original, TOUCH8 es el GPIO 33. El código de esta guía trabaja con el número de canal.
Por qué ESP IDF pide más pasos que Arduino
En Arduino basta un touchRead(). ESP IDF te da el periférico completo, así que el flujo tiene cinco pasos:
- Crear el controlador táctil y el canal.
- Calibrar: medir el pin sin tocar y fijar el umbral real.
- Registrar los callbacks
on_activeyon_inactive. - Dentro de cada callback, solo cambiar una bandera (nada de esperas).
- Iniciar el escaneo y revisar la bandera en el bucle principal.
A cambio obtienes filtrado de ruido por hardware, detección por interrupción en vez de sondeo y la posibilidad de usar el mismo canal para despertar el chip desde deep sleep.
Prepara el proyecto en VS Code
Necesitas VS Code con la extensión ESP IDF instalada. Si no la tienes, Random Nerd Tutorials tiene una guía de instalación (enlace en Recursos).
- Abre la extensión ESP IDF, despliega Advanced y elige New Project Wizard.
- Selecciona Use ESP IDF v6.X como versión del framework.

- Completa los campos: nombre del proyecto, carpeta de destino (no uses una carpeta sincronizada con Google Drive, OneDrive o Dropbox: la compilación crea miles de archivos y se vuelve lentísima), chip objetivo (por ejemplo
esp32s3), configuración de la placa (para el S3 con USB nativo, ESP32-S3 chip (via builtin USB JTAG)) y puerto serie. - Presiona el botón azul Choose Template.

- Elige ESP IDF Templates y presiona Create project using template sample project.

Cuando aparezca el aviso, haz clic en Open Project. Si no lo ves, usa File > Open Folder… y elige la carpeta del proyecto. Todo el trabajo se hace en main/main.c:

Circuito
Con un ESP32-S3, conecta un cable suelto al GPIO 8 (será tu "botón") y un LED con su resistencia en serie al GPIO 2.

Un detalle práctico: un cable pelado funciona, pero un cuadrado de papel aluminio o cobre de unos 2 cm al final del cable da una lectura mucho más estable, porque aumenta el área que acopla con tu dedo.
El código completo
Copia esto en main.c:
/*
Rui Santos & Sara Santos - Random Nerd Tutorials
https://RandomNerdTutorials.com/esp-idf-esp32-touch-sensor-pins/
*/
#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "driver/gpio.h"
#include "driver/touch_sens.h"
static const char *TAG = "touch_led";
#define TOUCH_CH 8
#define LED_PIN 2
// Touch sensor configuration
#if SOC_TOUCH_SENSOR_VERSION == 1 // ESP32
#define SAMPLE_CONFIG TOUCH_SENSOR_V1_DEFAULT_SAMPLE_CONFIG(5.0, TOUCH_VOLT_LIM_L_0V5, TOUCH_VOLT_LIM_H_1V7)
#define ACTIVE_THRESH_RATIO 0.98
#define CHAN_CFG_DEFAULT() { \
.abs_active_thresh = {1000}, \
.charge_speed = TOUCH_CHARGE_SPEED_7, \
.init_charge_volt = TOUCH_INIT_CHARGE_VOLT_DEFAULT, \
.group = TOUCH_CHAN_TRIG_GROUP_BOTH, \
}
#elif SOC_TOUCH_SENSOR_VERSION == 2 // ESP32-S2 / S3
#define SAMPLE_CONFIG TOUCH_SENSOR_V2_DEFAULT_SAMPLE_CONFIG(500, TOUCH_VOLT_LIM_L_0V5, TOUCH_VOLT_LIM_H_2V2)
#define ACTIVE_THRESH_RATIO 0.02
#define CHAN_CFG_DEFAULT() { \
.active_thresh = {2000}, \
.charge_speed = TOUCH_CHARGE_SPEED_7, \
.init_charge_volt = TOUCH_INIT_CHARGE_VOLT_DEFAULT, \
}
#elif SOC_TOUCH_SENSOR_VERSION == 3 // ESP32-P4
#define SAMPLE_CONFIG TOUCH_SENSOR_V3_DEFAULT_SAMPLE_CONFIG2(3, 29, 8, 3), \
TOUCH_SENSOR_V3_DEFAULT_SAMPLE_CONFIG2(2, 88, 31, 7), \
TOUCH_SENSOR_V3_DEFAULT_SAMPLE_CONFIG2(3, 10, 31, 7)
#define ACTIVE_THRESH_RATIO 0.02
#define CHAN_CFG_DEFAULT() { \
.active_thresh = {1000, 2500, 5000}, \
}
#else
#error "Board target not supported"
#endif
// Calibrate touch sensor: take a benchmark reading and set the active threshold
static void calibrate_touch(touch_sensor_handle_t sens, touch_channel_handle_t chan)
{
ESP_ERROR_CHECK(touch_sensor_enable(sens));
for (int i = 0; i < 3; i++) {
ESP_ERROR_CHECK(touch_sensor_trigger_oneshot_scanning(sens, 2000));
}
ESP_ERROR_CHECK(touch_sensor_disable(sens));
uint32_t benchmark = 0;
#if SOC_TOUCH_SUPPORT_BENCHMARK
touch_channel_read_data(chan, TOUCH_CHAN_DATA_TYPE_BENCHMARK, &benchmark);
#else
touch_channel_read_data(chan, TOUCH_CHAN_DATA_TYPE_SMOOTH, &benchmark);
#endif
touch_channel_config_t chan_cfg = CHAN_CFG_DEFAULT();
#if SOC_TOUCH_SENSOR_VERSION == 1
chan_cfg.abs_active_thresh[0] = (uint32_t)(benchmark * ACTIVE_THRESH_RATIO);
#else
chan_cfg.active_thresh[0] = (uint32_t)(benchmark * ACTIVE_THRESH_RATIO);
#endif
ESP_ERROR_CHECK(touch_sensor_reconfig_channel(chan, &chan_cfg));
ESP_LOGI(TAG, "Benchmark: %lu - threshold set", benchmark);
}
// Set by the touch driver's event callbacks, read by the main task loop
static volatile bool touch_active = false;
// Called from the touch driver when the channel becomes active (touch dectected)
static bool IRAM_ATTR on_touch_active(touch_sensor_handle_t sens_handle, const touch_active_event_data_t *event, void *user_ctx)
{
touch_active = true;
return false;
}
// Called from the touch driver when the channel becomes inactive (touch released)
static bool IRAM_ATTR on_touch_inactive(touch_sensor_handle_t sens_handle, const touch_inactive_event_data_t *event, void *user_ctx)
{
touch_active = false;
return false;
}
void app_main(void)
{
// Configure LED GPIO as output
gpio_config_t led_cfg = {
.pin_bit_mask = 1ULL << LED_PIN,
.mode = GPIO_MODE_OUTPUT,
};
gpio_config(&led_cfg);
gpio_set_level(LED_PIN, 0);
touch_sensor_handle_t sens = NULL;
touch_channel_handle_t chan = NULL;
// Touch sensor controller
touch_sensor_sample_config_t sample_cfg[TOUCH_SAMPLE_CFG_NUM] = { SAMPLE_CONFIG };
touch_sensor_config_t sens_cfg = TOUCH_SENSOR_DEFAULT_BASIC_CONFIG(TOUCH_SAMPLE_CFG_NUM, sample_cfg);
ESP_ERROR_CHECK(touch_sensor_new_controller(&sens_cfg, &sens));
// Configure touch sensor channel
touch_channel_config_t chan_cfg = CHAN_CFG_DEFAULT();
ESP_ERROR_CHECK(touch_sensor_new_channel(sens, TOUCH_CH, &chan_cfg, &chan));
// Filter
touch_sensor_filter_config_t filter_cfg = TOUCH_SENSOR_DEFAULT_FILTER_CONFIG();
ESP_ERROR_CHECK(touch_sensor_config_filter(sens, &filter_cfg));
// Calibrate touch sensor
calibrate_touch(sens, chan);
// Register touch active/inactive event callbacks
touch_event_callbacks_t callbacks = {
.on_active = on_touch_active,
.on_inactive = on_touch_inactive,
};
ESP_ERROR_CHECK(touch_sensor_register_callbacks(sens, &callbacks, NULL));
// Start continuous touch sensor scanning
ESP_ERROR_CHECK(touch_sensor_enable(sens));
ESP_ERROR_CHECK(touch_sensor_start_continuous_scanning(sens));
ESP_LOGI(TAG, "Touch GPIO %d to turn on LED on GPIO %d", TOUCH_CH, LED_PIN);
// Flag to hold current LED state
bool led_on = false;
while (1) {
// Read the touch_active flag set by the touch driver's callbacks
bool touched = touch_active;
if (touched && !led_on) {
// Turn on LED when touch is detected
gpio_set_level(LED_PIN, 1);
led_on = true;
ESP_LOGI(TAG, "Touch detected, LED ON");
} else if (!touched && led_on) {
// Turn off LED when touch is released
gpio_set_level(LED_PIN, 0);
led_on = false;
ESP_LOGI(TAG, "Touch released, LED OFF");
}
vTaskDelay(pdMS_TO_TICKS(20));
}
}
Qué hace cada parte
Canal y LED. TOUCH_CH 8 es el canal táctil (GPIO 8 en el S3) y LED_PIN 2 el pin del LED. Si usas un ESP32 original, el canal 8 corresponde al GPIO 33.
Configuración por chip. El bloque #if SOC_TOUCH_SENSOR_VERSION elige automáticamente los parámetros de muestreo, los límites de voltaje y la razón del umbral según el chip que compilas. No hace falta tocarlo.
Calibración. calibrate_touch() habilita el sensor, hace tres mediciones de una sola pasada, lee el valor de referencia del pin sin tocar y recalcula el umbral. Por eso no debes tocar el cable al encender la placa: si lo haces, la referencia queda mal y el toque nunca supera el umbral.
static void calibrate_touch(touch_sensor_handle_t sens, touch_channel_handle_t chan)
{
ESP_ERROR_CHECK(touch_sensor_enable(sens));
for (int i = 0; i < 3; i++) {
ESP_ERROR_CHECK(touch_sensor_trigger_oneshot_scanning(sens, 2000));
}
ESP_ERROR_CHECK(touch_sensor_disable(sens));
uint32_t benchmark = 0;
#if SOC_TOUCH_SUPPORT_BENCHMARK
touch_channel_read_data(chan, TOUCH_CHAN_DATA_TYPE_BENCHMARK, &benchmark);
#else
touch_channel_read_data(chan, TOUCH_CHAN_DATA_TYPE_SMOOTH, &benchmark);
#endif
touch_channel_config_t chan_cfg = CHAN_CFG_DEFAULT();
#if SOC_TOUCH_SENSOR_VERSION == 1
chan_cfg.abs_active_thresh[0] = (uint32_t)(benchmark * ACTIVE_THRESH_RATIO);
#else
chan_cfg.active_thresh[0] = (uint32_t)(benchmark * ACTIVE_THRESH_RATIO);
#endif
ESP_ERROR_CHECK(touch_sensor_reconfig_channel(chan, &chan_cfg));
ESP_LOGI(TAG, "Benchmark: %lu - threshold set", benchmark);
}
Callbacks en IRAM. on_touch_active() y on_touch_inactive() se ejecutan en contexto de interrupción, por eso llevan IRAM_ATTR y solo cambian la bandera touch_active. Esa variable es volatile porque la escribe la interrupción y la lee otra tarea: sin esa palabra, el compilador podría guardar su valor en un registro y el bucle nunca vería el cambio.
static bool IRAM_ATTR on_touch_active(touch_sensor_handle_t sens_handle,
const touch_active_event_data_t *event, void *user_ctx)
{
touch_active = true;
return false;
}
Filtro. TOUCH_SENSOR_DEFAULT_FILTER_CONFIG() activa un filtro de ruido por hardware que evita disparos falsos cuando hay motores, fuentes conmutadas o cables largos cerca.
Bucle principal. Cada 20 ms compara la bandera con el estado del LED y solo actúa cuando cambia, así el log no se llena de mensajes repetidos.
bool led_on = false;
while (1) {
bool touched = touch_active;
if (touched && !led_on) {
gpio_set_level(LED_PIN, 1);
led_on = true;
ESP_LOGI(TAG, "Touch detected, LED ON");
} else if (!touched && led_on) {
gpio_set_level(LED_PIN, 0);
led_on = false;
ESP_LOGI(TAG, "Touch released, LED OFF");
}
vTaskDelay(pdMS_TO_TICKS(20));
}
Compila y graba
En la barra inferior de VS Code revisa cuatro cosas: método de grabación UART (ícono de estrella), puerto COM correcto (ícono de enchufe), chip objetivo (ícono de chip) y, para placas con USB nativo, la configuración via builtin USB JTAG.



Presiona el ícono de llave inglesa (Build Project). La primera compilación se demora más; al terminar verás el mensaje de éxito en la terminal.


Luego presiona el ícono del rayo (Flash Device). Algunas placas necesitan que mantengas apretado el botón BOOT para entrar en modo de grabación.

Prueba
Abre la terminal y toca el cable del GPIO 8: el LED del GPIO 2 se enciende mientras mantienes el dedo y se apaga al soltar.

Cada cambio queda registrado en el log:

Si algo no funciona
- El LED nunca enciende: revisa en el log el valor de
Benchmark. Si tocaste el cable al arrancar, reinicia la placa sin tocarlo. - El LED parpadea solo: el cable es muy largo o pasa cerca de una fuente de ruido. Acórtalo o aléjalo; también puedes subir la razón del umbral (por ejemplo 0.04 en el S3).
- Error "Board target not supported": tu chip no tiene sensor táctil (C3, C6, H2) o el objetivo seleccionado no es el correcto.
- Funciona con la mano pero no a través de la cubierta: aumenta el tamaño del electrodo de aluminio; el acoplamiento depende del área.
Variantes y mejoras
- Teclado táctil de cuatro botones: crea cuatro canales con
touch_sensor_new_channel()y recorta cuatro cuadrados de papel aluminio pegados bajo una lámina de acrílico. Identifica qué canal disparó con el campochan_idde los datos del evento en el callback. - Despertar desde deep sleep: configura el mismo canal como fuente de despertar y deja la placa durmiendo. Un toque la despierta, hace su trabajo y vuelve a dormir; ideal para un control alimentado con batería.
- Interruptor de luz con relé: cambia el LED por un módulo relé y convierte el bucle en un conmutador (un toque enciende, el siguiente apaga) para controlar una lámpara de velador.
- Detector de nivel de agua: un electrodo pegado por fuera de un bidón plástico cambia su lectura cuando el agua sube a esa altura, sin contacto con el líquido.
Personalización para Chile
En Chile consigues todo lo necesario en MechatronicStore:
- Seeed Studio XIAO ESP32 S3 (SKU GS1-3): placa con chip ESP32-S3, igual al del tutorial. En la XIAO, el GPIO 8 es el pin D9 y el GPIO 2 es el D1, así que el código funciona sin cambios.
- ESP32 con Wifi y Bluetooth ESP 32 ESP WROOM-32 ESP32S Tipo C (SKU X2-10V2): si prefieres el ESP32 original. El código lo reconoce solo (sensor versión 1); conecta el cable táctil al GPIO 33, que es el canal 8 en este chip.
- LED 5mm rojo (SKU GA1-5): el indicador del toque.
- Resistencias 1/4W 1 unidad 220Ω (SKU GK1-18): limita la corriente del LED.
- Breadboard / Protoboard 830 puntos MB102 (SKU C-302): para montar el circuito sin soldar.
- Cables macho macho 40 piezas 20cm (SKU C-411): para el electrodo táctil y las conexiones.
- Cable USB Tipo C a USB Tipo A 1mt (SKU B-101): para grabar la placa desde el computador.
Si el tutorial original usa una ESP32-S3 DevKitC, la XIAO ESP32 S3 cumple la misma función con el mismo chip, en un formato más pequeño.
Recursos
- Tutorial original (inglés): ESP IDF: ESP32 Capacitive Touch Sensor Pins, de Random Nerd Tutorials.
- Código fuente: touch.pins.c en el repositorio de Random Nerd Tutorials.
- Documentación adicional: guía del sensor táctil capacitivo en ESP IDF de Espressif.
Versión chilena basada en el tutorial original, con componentes en stock local en MechatronicStore.










