Pinos de toque do ESP32: touchRead, limiar, interrupção e slider

Os pinos de toque do ESP32 são GPIOs especiais ligados a sensores de toque capacitivos integrados ao chip. O ESP32 clássico tem 10 deles (T0–T9), e eles detectam o toque em um fio, num pedaço de papel-alumínio ou em fita de cobre sem nenhum módulo extra. Uma única função faz o trabalho: touchRead(). Quando seu dedo se aproxima do pad, ele adiciona uma pequena capacitância ao circuito, e o ESP32 entrega essa variação para você como um número. Com isso dá para fazer um interruptor de toque, um dimmer de luz, um slider ou um botão de abertura escondido sem botão mecânico.

Neste guia, primeiro vamos ver qual GPIO está ligado a qual canal de toque e de quais é melhor ficar longe. Depois vamos ler os valores do touchRead, escolher o limiar certo e escrever um botão de toque robusto, com autocalibração e histerese. Você também vai aprender a fazer pads com papel-alumínio e fita de cobre, ajustar o brilho de um LED com um slider de três pads, usar interrupções com touchAttachInterrupt e acordar o ESP32 do deep sleep com um toque. As seções finais tratam de problemas com umidade e ruído, das diferenças do ESP32-S3 e de um exemplo curto em MicroPython.

Como funcionam os pinos de toque do ESP32?

Cada pino de toque está ligado a um circuito de medição dentro do chip. Esse circuito fica carregando e descarregando o pino e conta quantos ciclos de carga e descarga se completam em um tempo fixo. O fio e o pad no pino se comportam como um pequeno capacitor. Quando você aproxima o dedo, seu corpo acrescenta alguns picofarads a esse capacitor, a carga e a descarga ficam mais lentas e menos ciclos se completam no mesmo tempo. Por isso, no ESP32 clássico, o valor do touchRead cai quando você toca. Com um fio curto, normalmente você vê 40–80 em repouso; ao tocar com o dedo, o valor cai para algo em torno de 10–25. Esses números dependem do comprimento do fio, do tamanho do pad, da placa e do ambiente, então nunca escreva um limiar de cabeça no código: meça na sua própria montagem.

Tabela dos pinos de toque do ESP32 (T0–T9)

Os canais de toque estão ligados apenas a GPIOs específicos; se você usar o touchRead em qualquer outro pino, não vai obter um valor com sentido. O core do Arduino define constantes prontas como T0 e T1 para esses canais, então escrever touchRead(T0) no código é o mesmo que touchRead(4). Alguns desses pinos são pinos de strapping, que decidem como a placa inicia no boot; eles funcionam como pinos de toque, mas não devem ser sua primeira opção.

Fazendo pads: fio, papel-alumínio e fita de cobre

Qualquer superfície condutora funciona como pad de toque. O mais simples é a ponta desencapada de um jumper espetado no pino. Para uma superfície mais confortável, você pode usar um pedaço de papel-alumínio de 2×2 cm ou fita de cobre autoadesiva; a fita de cobre também aceita solda, então é melhor para projetos permanentes. Dá para colar o pad em papelão, no lado de dentro de uma caixa plástica ou atrás de um pedaço de madeira. O toque também é detectado através de 1–3 mm de plástico, acrílico ou vidro; só que a queda do valor fica menor, então é preciso medir o limiar de novo. Mantenha curto o fio do pad até o ESP32: fios com mais de 20–30 cm viram antenas, e tocar no próprio fio também dispara.

Lendo os valores do touchRead e definindo um limiar

O primeiro passo é ver os números reais na sua montagem. O sketch abaixo lê o GPIO 4 (T0) e o GPIO 27 (T7) oito vezes cada um e mostra a média. Se você abrir o Plotter Serial no menu Ferramentas da Arduino IDE, pode acompanhar as duas linhas ao vivo e ver como os valores caem quando você toca.

1// ESP32 dokunmatik değer okuma / ESP32 touch value reading
2// GPIO 4 = T0, GPIO 27 = T7
3
4void setup() {
5  Serial.begin(115200);
6  delay(500);
7}
8
9void loop() {
10  uint32_t t0 = 0, t7 = 0;
11  for (int i = 0; i < 8; i++) {      // 8 ölçümün ortalaması / average of 8 readings
12    t0 += touchRead(T0);
13    t7 += touchRead(T7);
14  }
15  Serial.print("T0:");
16  Serial.print(t0 / 8);
17  Serial.print(" T7:");
18  Serial.println(t7 / 8);            // Seri Çizici için / for the Serial Plotter
19  delay(100);
20}

Enquanto observa os valores, anote três situações: o pad em repouso, o dedo sobre o pad e o dedo a 1–2 cm acima do pad. Por exemplo, se você lê 62 em repouso, 14 ao tocar e 45 ao aproximar, um limiar seguro fica em cerca de 60 por cento do valor em repouso, ou seja, por volta de 37. Coloque o limiar muito perto do valor em repouso e ele dispara só com o dedo se aproximando; coloque baixo demais e você vai perder toques leves.

Botão de toque com autocalibração

Em vez de escrever um limiar fixo no código, é bem mais confiável medir o valor em repouso do pad quando a placa liga e calcular o limiar a partir dele. O sketch abaixo faz a média de 50 leituras na inicialização, considera uma queda de 40 por cento como toque e alterna o LED. Ele considera o pad solto quando o valor volta a ficar acima de 80 por cento do valor em repouso. Usar dois limiares separados se chama histerese; isso evita disparos repetidos quando o valor fica oscilando bem no limite. Se você tem curiosidade sobre o lado mecânico dos botões, veja o artigo como ligar um botão.

1// Otomatik kalibrasyonlu dokunmatik buton / self-calibrating touch button
2// GPIO 4 (T0) dokunma pedi, GPIO 2 kart üstü LED
3// GPIO 4 (T0) touch pad, GPIO 2 onboard LED
4
5const uint8_t DOKUNMA_PIN = T0;   // GPIO 4
6const uint8_t LED_PIN = 2;
7
8uint32_t bosDeger = 0;            // dokunulmamış değer / untouched value
9uint32_t basEsik, birakEsik;      // histerezisli eşikler / thresholds with hysteresis
10bool basili = false;
11bool ledDurum = false;
12
13uint32_t ortalamaOku(uint8_t pin, int adet) {
14  uint32_t toplam = 0;
15  for (int i = 0; i < adet; i++) {
16    toplam += touchRead(pin);
17    delay(2);
18  }
19  return toplam / adet;
20}
21
22void setup() {
23  Serial.begin(115200);
24  pinMode(LED_PIN, OUTPUT);
25  delay(300);                                  // açılışta pede dokunma / do not touch at boot
26  bosDeger = ortalamaOku(DOKUNMA_PIN, 50);
27  basEsik = bosDeger * 60 / 100;               // %40 düşüş = dokunma / 40% drop = touch
28  birakEsik = bosDeger * 80 / 100;             // %20 altına dönünce bırakıldı / released
29  Serial.printf("Bos: %u  Bas: %u  Birak: %u\n", bosDeger, basEsik, birakEsik);
30}
31
32void loop() {
33  uint32_t deger = ortalamaOku(DOKUNMA_PIN, 4);
34
35  if (!basili && deger < basEsik) {            // yeni dokunma / new touch
36    basili = true;
37    ledDurum = !ledDurum;
38    digitalWrite(LED_PIN, ledDurum);
39    Serial.println("Dokunuldu / touched");
40  } else if (basili && deger > birakEsik) {    // parmak çekildi / finger lifted
41    basili = false;
42  }
43  delay(20);
44}

Interrupções de toque com touchAttachInterrupt

Em vez de chamar touchRead o tempo todo, você pode deixar o hardware de toque medir em segundo plano e chamar uma função quando o valor cair abaixo de um limiar. É isso que touchAttachInterrupt(pino, função, limiar) faz. No ESP32 clássico, a interrupção dispara quando o valor medido fica abaixo do limiar e continua disparando a cada ciclo de medição enquanto o dedo estiver no pad. Por isso, a função de interrupção deve só levantar uma flag, e o trabalho de verdade deve acontecer no loop(), com uma verificação de tempo. Falamos das regras gerais de interrupções no artigo interrupções no Arduino.

1// touchAttachInterrupt ile dokunma kesmesi / touch interrupt
2// GPIO 27 (T7) pedi; eşik touchRead ile ölçülerek seçilmeli
3// GPIO 27 (T7) pad; pick the threshold from your touchRead values
4
5const uint8_t PED = T7;            // GPIO 27
6const uint16_t ESIK = 40;          // ESP32: değer bunun ALTINA inince tetikler / fires below this
7volatile bool dokunuldu = false;
8
9void IRAM_ATTR dokunmaKesmesi() {
10  dokunuldu = true;                // kesmede yalnız bayrak / only set a flag in the ISR
11}
12
13void setup() {
14  Serial.begin(115200);
15  touchAttachInterrupt(PED, dokunmaKesmesi, ESIK);
16}
17
18void loop() {
19  static unsigned long sonDokunma = 0;
20  if (dokunuldu) {
21    dokunuldu = false;
22    // Parmak durdukça kesme tekrar tekrar gelir; 300 ms'de bir say
23    // The ISR repeats while the finger stays; count once per 300 ms
24    if (millis() - sonDokunma > 300) {
25      sonDokunma = millis();
26      Serial.printf("Dokunma! deger: %u\n", touchRead(PED));
27    }
28  }
29}

Neste exemplo o limiar é 40; ele serve para um pad que lê por volta de 60 em repouso; caso contrário, ajuste de acordo com os números do sketch de leitura anterior. O atributo IRAM_ATTR na função de interrupção a coloca na memória rápida; isso é recomendado para funções de interrupção no ESP32. Para desligar a interrupção, chame touchDetachInterrupt(pino). No ESP32 clássico, você também pode chamar touchInterruptSetThresholdDirection(false) para que a interrupção dispare quando o valor subir acima do limiar; isso é útil para capturar o momento em que o dedo sai.

Slider de toque com três pads

Três pads em fila bastam para descobrir onde está o seu dedo. Quando o dedo fica entre dois pads, os dois valores caem; olhando quanto cada pad caiu, você calcula a posição com uma média ponderada. Se você cortar os pads em formatos de zigue-zague ou de ponta de flecha que se encaixam, em vez de quadrados simples, o dedo toca pelo menos dois pads em qualquer posição e o slider fica bem mais suave. Três tiras de fita de cobre de 1,5 cm de largura, com 1–2 mm de espaço entre elas, são um bom começo.

1// Üç pedli dokunmatik kaydırıcı ile LED parlaklığı / 3-pad touch slider dims an LED
2// Pedler: GPIO 13 (T4), GPIO 14 (T6), GPIO 33 (T8); LED: GPIO 26
3// Pads: GPIO 13 (T4), GPIO 14 (T6), GPIO 33 (T8); LED: GPIO 26
4
5const uint8_t pedler[3] = {T4, T6, T8};
6const uint8_t LED_PIN = 26;
7uint32_t bos[3];                   // her pedin boştaki değeri / idle value of each pad
8int parlaklik = 0;
9
10uint32_t oku(uint8_t pin) {
11  uint32_t t = 0;
12  for (int i = 0; i < 4; i++) t += touchRead(pin);
13  return t / 4;
14}
15
16void setup() {
17  Serial.begin(115200);
18  delay(300);
19  for (int p = 0; p < 3; p++) {
20    uint32_t t = 0;
21    for (int i = 0; i < 32; i++) t += touchRead(pedler[p]);
22    bos[p] = t / 32;
23  }
24}
25
26void loop() {
27  long fark[3];
28  long toplam = 0;
29  for (int p = 0; p < 3; p++) {
30    fark[p] = (long)bos[p] - (long)oku(pedler[p]);   // dokununca değer düşer / value drops on touch
31    if (fark[p] < 0) fark[p] = 0;
32    toplam += fark[p];
33  }
34
35  // Toplam düşüş boştaki değerin %25'ini geçerse parmak var
36  // A finger is present if the total drop exceeds 25% of an idle value
37  if (toplam > (long)bos[1] / 4) {
38    // Ağırlıklı ortalama: ped A = 0, ped B = 500, ped C = 1000
39    // Weighted average: pad A = 0, pad B = 500, pad C = 1000
40    long konum = (fark[1] * 500L + fark[2] * 1000L) / toplam;
41    parlaklik = map(konum, 0, 1000, 0, 255);
42    analogWrite(LED_PIN, parlaklik);
43    Serial.printf("Konum: %ld  Parlaklik: %d\n", konum, parlaklik);
44  }
45  delay(30);
46}

Na inicialização, o sketch salva o valor em repouso de cada pad e, a cada ciclo, calcula as quedas. Se a queda total for grande o bastante, há um dedo no slider e a posição é calculada entre 0 e 1000. Convertemos esse valor para 0–255 com map() e o enviamos ao LED com analogWrite(). O analogWrite() funciona tanto na versão 2.x quanto na 3.x do core Arduino do ESP32. Você encontra como o PWM funciona no artigo o que é PWM.

Acordando do deep sleep com um toque

Em um projeto a bateria, você pode colocar o ESP32 em deep sleep e acordá-lo só quando alguém tocar no pad. Nesse modo os núcleos ficam desligados, mas o circuito de medição de toque continua funcionando com baixo consumo. A função touchSleepWakeUpEnable(pino, limiar) define o limiar e ativa o despertar por toque de uma vez só. No ESP32 clássico você pode usar vários pads como fonte de despertar; no ESP32-S2 e no S3, só um pad é permitido. Depois de acordar, esp_sleep_get_touchpad_wakeup_status() informa qual pad acordou a placa. Falamos dos detalhes do deep sleep e dos valores de corrente no artigo ESP32 deep sleep.

1// Dokunarak deep sleep'ten uyanma / wake from deep sleep by touch
2// GPIO 27 (T7) pedi / GPIO 27 (T7) pad
3
4#if CONFIG_IDF_TARGET_ESP32
5  #define ESIK 40      // ESP32: değer bunun altına inerse uyanır / wakes below this value
6#else
7  #define ESIK 5000    // ESP32-S2/S3: boştaki değere göre artış / rise above the baseline
8#endif
9
10RTC_DATA_ATTR int uyanmaSayisi = 0;   // uykuda korunur / kept during deep sleep
11
12void setup() {
13  Serial.begin(115200);
14  delay(500);
15  uyanmaSayisi++;
16
17  if (esp_sleep_get_wakeup_cause() == ESP_SLEEP_WAKEUP_TOUCHPAD) {
18    Serial.printf("Dokunmayla uyandi, ped: %d\n", (int)esp_sleep_get_touchpad_wakeup_status());
19  } else {
20    Serial.println("Ilk acilis ya da baska neden / first boot or other cause");
21  }
22  Serial.printf("Uyanma sayisi: %d\n", uyanmaSayisi);
23
24  // Burada ölçüm yap, veri gönder... / take readings, send data here...
25  delay(2000);
26
27  touchSleepWakeUpEnable(T7, ESIK);   // T7 pedini uyandırma kaynağı yap / enable T7 as wake source
28  Serial.println("Uyuyorum / going to sleep");
29  Serial.flush();
30  esp_deep_sleep_start();
31}
32
33void loop() {
34}

Depois de acordar, o código começa de novo pelo setup(), porque a RAM é apagada no deep sleep. Para manter a contagem de despertares, colocamos RTC_DATA_ATTR na frente da variável; essas variáveis ficam na pequena memória RTC, que é preservada durante o sono. Como a medição de toque continua durante o sono, a corrente em deep sleep fica um pouco maior do que com despertar por timer; leve isso em conta ao estimar a autonomia da bateria. O bloco #if no código permite que o mesmo programa compile com o limiar certo também no ESP32-S2 e no S3.

Pinos de toque do ESP32 com MicroPython

Se você gravou o MicroPython no seu ESP32, faz a mesma coisa com a classe TouchPad do módulo machine. O método read() retorna o mesmo valor que o touchRead() no Arduino; no ESP32 clássico, ele também cai ao tocar. Para despertar, usa-se esp32.wake_on_touch(True) e o método config(limiar) do pad.

1# ESP32 MicroPython dokunmatik pin / ESP32 MicroPython touch pin
2from machine import Pin, TouchPad
3import time
4
5ped = TouchPad(Pin(4))       # GPIO 4 = T0
6led = Pin(2, Pin.OUT)        # kart üstü LED / onboard LED
7
8bos = sum(ped.read() for _ in range(20)) // 20   # dokunulmamış değer / idle value
9esik = bos * 6 // 10
10basili = False
11
12while True:
13    deger = ped.read()
14    if not basili and deger < esik:
15        basili = True
16        led.value(not led.value())   # her dokunuşta LED'i değiştir / toggle on every touch
17        print("dokunuldu", deger)
18    elif basili and deger > bos * 8 // 10:
19        basili = False
20    time.sleep_ms(30)

O Raspberry Pi Pico não tem sensor de toque capacitivo integrado. Se você quer um botão de toque com um Pico ou um Arduino Uno, a solução mais fácil é um módulo TTP223 pronto; ele detecta o toque sozinho e entrega um sinal digital comum.

Problemas com umidade, água e ruído

A detecção capacitiva detecta água além de dedos. Uma gota de água ou muita umidade sobre o pad aumenta a capacitância, o valor cai e o botão pode disparar sozinho. Em projetos para banheiro, cozinha ou área externa, coloque o pad atrás de uma superfície que não retenha água, escolha um limiar um pouco mais baixo e exija que o toque dure pelo menos 50–100 ms. Fios longos, relés e motores por perto e uma fonte USB ruim também fazem os valores oscilarem. A tabela abaixo resume os problemas mais comuns e suas soluções.

Pinos de toque no ESP32-S3 e em outros modelos

O ESP32-S2 e o ESP32-S3 usam hardware de toque de segunda geração e diferem do ESP32 clássico em três pontos importantes. Primeiro, os canais ficam nos GPIO 1–14 e são 14; T1 é o GPIO 1 e T14 é o GPIO 14. Segundo, os valores são bem maiores e sobem ao tocar; um pad que lê cerca de 20.000 em repouso pode passar de 40.000 ao ser tocado. Terceiro, o limiar em touchAttachInterrupt e touchSleepWakeUpEnable não é um valor absoluto, mas um aumento em relação ao valor em repouso. No S3 você também pode usar touchInterruptGetLastStatus(pino) para saber se o pad ainda está pressionado. O ESP32-C3 e o ESP32-C6 não têm sensor de toque. Se você escreve código para mais de um modelo, separe-os com CONFIG_IDF_TARGET_ESP32, como no exemplo de despertar.

Ideias de projetos com pinos de toque

• Luminária de mesa: um interruptor liga/desliga invisível feito de fita de cobre colada atrás de uma tampa de madeira, com toque longo para ajustar o brilho.
• Dimmer com slider: mude o brilho e a cor de uma fita de LED WS2812B com um slider de três pads.
• Campainha ou dispositivo de recados a bateria: o ESP32 espera em deep sleep, acorda quando o pad é tocado e envia uma notificação por Wi-Fi.
• Piano de frutas: um brinquedo com fios ligados a bananas e maçãs que toca uma nota diferente para cada fruta; um buzzer pode fazer o som.
• Painel de senha escondido: uma fechadura que abre quando quatro pads escondidos dentro de uma caixa são tocados na ordem certa.

Os pinos de toque do ESP32 dão ao seu projeto uma interface de toque com alguns centímetros de papel-alumínio e poucas linhas de código. No app BlueGrays você encontra projetos como LED piscando com ESP32, controle de LED com botão, brilho de LED com PWM e deep sleep, cada um com esquema do circuito e código passo a passo; troque os botões pelos pads de toque deste guia e monte a sua própria versão.