Guias · 14 min de leitura

ESP32 FreeRTOS: dual-core, tarefas, filas e semáforos

ESP32 FreeRTOS: xTaskCreatePinnedToCore, prioridades, delay e vTaskDelay, filas, semáforos, pilha e watchdog; execute LED, sensor e servidor web ao mesmo tempo.

ESP32 FreeRTOS é o sistema operacional de tempo real que já funciona dentro do ESP32 e permite fazer várias coisas ao mesmo tempo. Todo sketch para ESP32 que você escreve no Arduino IDE, na verdade, roda sobre o FreeRTOS: suas funções setup() e loop() são executadas dentro de uma tarefa chamada loopTask em um dos dois núcleos do ESP32. Ao criar suas próprias tarefas, você pode piscar um LED enquanto lê um sensor e responde às solicitações de um servidor web ao mesmo tempo, sem que uma atividade atrase as outras. A estrutura de “vários trabalhos ao mesmo tempo” que você tenta montar com millis() no Arduino Uno fica muito mais organizada no ESP32.

Neste guia, você vai aprender como os dois núcleos do ESP32 são compartilhados e em qual núcleo o Wi-Fi funciona. Depois, vamos criar tarefas com xTaskCreatePinnedToCore, fixá-las em um núcleo específico, definir prioridades e ver a diferença entre delay() e vTaskDelay(). Vamos usar uma fila para compartilhar dados com segurança entre tarefas, um semáforo para despertar uma tarefa a partir da interrupção de um botão e um mutex para proteger o Monitor Serial compartilhado. Depois de abordar o tamanho da pilha e os erros de watchdog, vamos montar um exemplo completo que executa LED, sensor e servidor web ao mesmo tempo. No final, há uma breve comparação com os dois núcleos do Raspberry Pi Pico.

Placa de desenvolvimento ESP32
O ESP32 clássico tem dois núcleos Xtensa LX6 e pode executar tarefas separadas em cada um com o FreeRTOS.

O que é o ESP32 FreeRTOS e como os dois núcleos funcionam?

No FreeRTOS, cada trabalho é uma tarefa. Uma tarefa é uma função C comum com sua própria memória de pilha e prioridade, geralmente contendo um laço infinito. Em cada núcleo, o escalonador do FreeRTOS escolhe a tarefa de maior prioridade entre as que estão prontas para executar. Quando uma tarefa espera com vTaskDelay(), aguarda dados de uma fila ou espera por um semáforo, o núcleo é entregue imediatamente a outra tarefa. Tarefas com a mesma prioridade se alternam a cada tick. No core do Arduino para ESP32, um tick dura 1 ms (1.000 ticks por segundo), então vTaskDelay(100) espera cerca de 100 ms. O ESP32 clássico tem dois núcleos: núcleo 0 (PRO_CPU) e núcleo 1 (APP_CPU). A Espressif coloca a comunicação sem fio no núcleo 0 e seu código no núcleo 1, para que as atividades do Wi-Fi não interrompam seu laço. Com as configurações padrão do Arduino, estas são as tarefas executadas nos núcleos:

TarefaNúcleoPrioridadeFunção
loopTask (setup e loop)11Seu código Arduino, pilha de 8.192 bytes
Driver de Wi-Fi023Rádio e protocolo Wi-Fi
lwIP (tcpip)018Pilha TCP/IP, pacotes web e MQTT
Bluetooth (BT/BLE)0AltaControlador Bluetooth e Bluedroid
esp_timer022Temporizadores de software
IDLE0 e IDLE10 e 10Tarefas ociosas; alimentam o watchdog e liberam a memória das tarefas excluídas

Esta tabela traz duas lições importantes. Primeiro, as tarefas de Wi-Fi e TCP/IP têm prioridade muito alta; se você colocar uma tarefa pesada sua no núcleo 0, elas a interromperão sempre que houver tráfego de rede, e, se sua tarefa as mantiver ocupadas por muito tempo, o Wi-Fi será prejudicado. Segundo, loopTask tem prioridade de apenas 1; se você colocar no núcleo 1 uma tarefa com prioridade maior que nunca espera, loop() nunca será executada. O ESP32-S3 também é dual-core. O ESP32-S2, o ESP32-C3 e o ESP32-C6 têm um único núcleo; você ainda pode criar tarefas nessas placas, mas todas compartilham o mesmo núcleo.

Esquema de ligação

Para os exemplos deste artigo, você precisa de um ESP32 DevKit, dois LEDs, um potenciômetro e um botão de pressão. O LED azul da placa está no GPIO 2; conecte o segundo LED ao GPIO 4 por meio de um resistor de 220 Ω. Conectamos o potenciômetro ao GPIO 34, um canal ADC1, porque os pinos ADC2 não podem ser lidos enquanto o Wi-Fi está ligado.

ComponentePino do ESP32Observação
LED integradoGPIO 2Integrado à placa na maioria dos DevKits
Segundo LEDGPIO 4Resistor de 220 Ω em série, terminal curto no GND
Terminal central do potenciômetroGPIO 34Somente entrada, ADC1; terminais externos em 3V3 e GND
BotãoGPIO 27Outro terminal no GND, usado com INPUT_PULLUP
Conecte o terminal externo do potenciômetro a 3V3, não a 5V. Os pinos do ESP32 funcionam com 3,3 V e não toleram 5 V. Em projetos com Wi-Fi, conecte os sensores analógicos aos pinos ADC1 GPIO 32–39; os pinos ADC2 (GPIO 0, 2, 4, 12–15, 25–27) não podem ser lidos com analogRead() enquanto o Wi-Fi está ligado. Você pode conferir a escolha do pino na ferramenta Pinagem.

Primeiras tarefas com xTaskCreatePinnedToCore

No primeiro exemplo, piscamos dois LEDs com duas tarefas separadas, em velocidades e núcleos diferentes. Toda função de tarefa tem o formato void function(void *parameter) e contém um laço infinito. xTaskCreatePinnedToCore(), que inicia a tarefa, também informa em qual núcleo ela deve executar. Observe que usamos a mesma função de tarefa duas vezes e passamos uma estrutura de configuração diferente a cada vez; graças ao parâmetro, uma única função controla dois LEDs de forma independente.

C++ (Arduino IDE)
1// İki LED, iki görev, iki çekirdek / two LEDs, two tasks, two cores
2struct LedAyari {
3  int pin;          // LED pini / LED pin
4  int beklemeMs;    // yarım periyot / half period
5};
6
7LedAyari led1 = {2, 250};   // dahili LED, hızlı / onboard LED, fast
8LedAyari led2 = {4, 700};   // harici LED, yavaş / external LED, slow
9
10void ledGorevi(void *parametre) {
11  LedAyari *ayar = (LedAyari *)parametre;
12  pinMode(ayar->pin, OUTPUT);
13  for (;;) {                                         // görev asla bitmez / a task never returns
14    digitalWrite(ayar->pin, !digitalRead(ayar->pin));
15    vTaskDelay(pdMS_TO_TICKS(ayar->beklemeMs));      // çekirdeği bırak / give the core away
16  }
17}
18
19void setup() {
20  Serial.begin(115200);
21  // fonksiyon, ad, yığın (bayt), parametre, öncelik, tutamaç, çekirdek
22  // function, name, stack (bytes), parameter, priority, handle, core
23  xTaskCreatePinnedToCore(ledGorevi, "LED1", 2048, &led1, 1, NULL, 0);
24  xTaskCreatePinnedToCore(ledGorevi, "LED2", 2048, &led2, 1, NULL, 1);
25}
26
27void loop() {
28  Serial.printf("loop() cekirdek / core: %d\n", xPortGetCoreID());
29  delay(1000);                                       // ESP32'de delay de çekirdeği bırakır / delay yields on ESP32 too
30}

Quando você carrega o código, os dois LEDs piscam de forma independente, e o Monitor Serial mostra que loop() é executada no núcleo 1. Estes são os parâmetros da função:

ParâmetroValor no exemploSignificado
pvTaskCodeledGoreviA função que a tarefa executa
pcName"LED1"Nome exibido durante a depuração, com até 16 caracteres
usStackDepth2048Tamanho da pilha; no ESP32, é expresso em bytes
pvParameters&led1Ponteiro passado à tarefa; deve apontar para uma variável global ou static
uxPriority1Prioridade, de 0 (a mais baixa) a 24
pvCreatedTaskNULLIdentificador para interromper ou monitorar a tarefa depois
xCoreID0 ou 1Núcleo de execução; com tskNO_AFFINITY, executa no núcleo que estiver livre
Uma função de tarefa nunca deve terminar com return; se isso acontecer, o ESP32 informa um erro e reinicia. Se uma tarefa terminou seu trabalho, exclua-a chamando vTaskDelete(NULL) na última linha. Também não passe o endereço de uma variável local de setup() como parâmetro da tarefa: quando setup() termina, essa variável deixa de existir e a tarefa lê um endereço inválido. No ESP32-C3, S2 e C6, que têm um único núcleo, só é possível usar 0 ou tskNO_AFFINITY como número do núcleo; a opção mais portável é xTaskCreate(), que não escolhe um núcleo.

Comparação entre delay(), vTaskDelay() e vTaskDelayUntil()

No Arduino Uno, delay() mantém o processador totalmente ocupado; nada mais é executado durante a espera. No ESP32, é diferente: delay() no core do Arduino, na verdade, chama vTaskDelay(). Assim, quando você escreve delay(100), sua tarefa dorme por 100 ms e o núcleo fica disponível para outras tarefas nesse intervalo. É por isso que usar delay() dentro das tarefas também funciona; ainda assim, escrever vTaskDelay(pdMS_TO_TICKS(100)) no código FreeRTOS deixa sua intenção mais clara. A diferença real está nos métodos que esperam mantendo o processador ocupado: delayMicroseconds() e laços vazios como while (millis() - t < 500) {} nunca liberam o núcleo. Abordamos em detalhes o uso de millis() no Arduino em millis() e delay().

MétodoLibera o núcleo?Quando usar
delay(ms)Sim (chama vTaskDelay no ESP32)Esperas simples, dentro de loop()
vTaskDelay(pdMS_TO_TICKS(ms))SimEspera em tarefas; o atraso é somado ao tempo de trabalho
vTaskDelayUntil(&last, period)SimAmostragem com frequência fixa; período exato, independentemente do tempo de trabalho
delayMicroseconds(us)NãoEsperas de microssegundos em protocolos de sensores
while (millis() - t < ms) {}NãoNão use em tarefas FreeRTOS; impede a execução das outras tarefas

Se um laço usa vTaskDelay(100) e o trabalho leva 15 ms, ele se repete a cada 115 ms e o erro se acumula com o tempo. Se você quer ler um sensor exatamente a cada 100 ms, use vTaskDelayUntil(): a função acompanha o instante do despertar anterior e desperta a tarefa exatamente um período depois a cada vez. A tarefa do sensor na próxima seção usa esse método.

Prioridades das tarefas: qual executa primeiro?

Se várias tarefas de um núcleo estão prontas para executar, a de maior prioridade sempre é executada. Uma tarefa de prioridade menor só recebe o núcleo quando as de prioridade maior estão esperando. Isso se chama escalonamento preemptivo por prioridade: assim que chegam os dados que uma tarefa de alta prioridade espera, a tarefa de prioridade menor é interrompida. Isso permite dar alta prioridade a trabalhos que exigem resposta rápida, mas há uma armadilha: se uma tarefa de alta prioridade nunca espera, as de prioridade menor nunca executam. Na prática, o esquema a seguir funciona bem:

  • Prioridade 1: Trabalhos sem urgência, como atualizar um display, escrever no Monitor Serial ou executar um servidor web. loop() também está neste nível.
  • Prioridade 2–3: Trabalhos que precisam acontecer no momento certo, como leituras regulares de sensores, malhas de controle e tratamento de botões.
  • Prioridade 4–5: Tarefas curtas despertadas por uma interrupção que precisam responder imediatamente.
  • Evite: Não dê prioridade 18 ou maior às suas tarefas; esses níveis pertencem ao Wi-Fi, ao TCP/IP e aos temporizadores do sistema.

Compartilhar dados com segurança entre tarefas usando uma fila

A primeira ideia para transferir dados entre tarefas é usar uma variável global, mas duas tarefas podem acessar a mesma variável ao mesmo tempo. Se uma tarefa lê uma estrutura de vários bytes enquanto outra a escreve, recebe um valor com uma parte antiga e outra nova; como esses erros aparecem raramente e de forma aleatória, são muito difíceis de localizar. A solução do FreeRTOS é a fila. Uma fila é uma sequência de itens de tamanho fixo que transfere dados por cópia: a tarefa que envia deixa uma cópia com xQueueSend(), e a tarefa que recebe retira essa cópia com xQueueReceive(). Se a fila está vazia, a tarefa receptora dorme e não consome tempo de CPU; ela desperta assim que chegam dados. No exemplo abaixo, uma tarefa lê o potenciômetro exatamente a cada 100 ms e coloca a leitura na fila junto com uma marcação de tempo; uma segunda tarefa processa cada leitura que sai da fila.

C++ (Arduino IDE)
1// Sensör görevi -> kuyruk -> işleyici görev / sensor task -> queue -> consumer task
2const int POT_PIN = 34;                 // ADC1 pini / ADC1 pin
3
4struct Olcum {
5  uint16_t ham;                         // 0-4095 ham değer / raw value
6  float volt;                           // gerilim / voltage
7  uint32_t zaman;                       // ms cinsinden zaman / timestamp in ms
8};
9
10QueueHandle_t olcumKuyrugu;
11
12void sensorGorevi(void *parametre) {
13  TickType_t sonUyanma = xTaskGetTickCount();
14  for (;;) {
15    Olcum o;
16    o.ham = analogRead(POT_PIN);
17    o.volt = analogReadMilliVolts(POT_PIN) / 1000.0f;
18    o.zaman = millis();
19    if (xQueueSend(olcumKuyrugu, &o, 0) != pdPASS) {   // kuyruk doluysa bekleme / don't wait if full
20      Serial.println("Kuyruk dolu / Queue full");
21    }
22    vTaskDelayUntil(&sonUyanma, pdMS_TO_TICKS(100));   // tam 100 ms periyot / exact 100 ms period
23  }
24}
25
26void isleyiciGorev(void *parametre) {
27  Olcum o;
28  for (;;) {
29    // veri gelene kadar uyu / sleep until data arrives
30    if (xQueueReceive(olcumKuyrugu, &o, portMAX_DELAY) == pdPASS) {
31      Serial.printf("%lu ms  ham/raw: %4u  %.2f V  bekleyen/waiting: %u\n",
32                    (unsigned long)o.zaman, o.ham, o.volt,
33                    (unsigned)uxQueueMessagesWaiting(olcumKuyrugu));
34    }
35  }
36}
37
38void setup() {
39  Serial.begin(115200);
40  olcumKuyrugu = xQueueCreate(10, sizeof(Olcum));      // 10 ölçümlük kuyruk / queue of 10 readings
41  if (olcumKuyrugu == NULL) {
42    Serial.println("Kuyruk olusturulamadi / Queue creation failed");
43    return;
44  }
45  xTaskCreatePinnedToCore(sensorGorevi, "Sensor", 3072, NULL, 2, NULL, 1);
46  xTaskCreatePinnedToCore(isleyiciGorev, "Isleyici", 3072, NULL, 1, NULL, 1);
47}
48
49void loop() {
50  vTaskDelay(pdMS_TO_TICKS(1000));     // loop'un burada işi yok / loop has nothing to do here
51}

Como a prioridade da tarefa do sensor (2) é maior que a da consumidora (1), as leituras sempre são feitas no momento certo. Mesmo que a consumidora fique lenta por um instante, por exemplo ao escrever em um cartão SD, nenhuma leitura é perdida; elas aguardam sua vez na fila de 10 itens. Se a fila enche, xQueueSend() retorna um erro sem esperar, permitindo que você perceba isso. Se você só precisa do valor mais recente, por exemplo para mostrar a temperatura atual em um display, pode criar uma fila de um único item, escrever nela com xQueueOverwrite() e ler o valor sem removê-lo usando xQueuePeek(). Vamos usar esse método no exemplo final.

Semáforos e mutexes: despertar uma tarefa a partir de uma interrupção e proteger um recurso compartilhado

Um semáforo binário é como uma sinalização que permite a uma tarefa esperar por um evento. Seu uso mais comum é com interrupções: a rotina de interrupção (ISR) de um botão deve ser muito curta, por isso ela não faz o trabalho propriamente dito, apenas libera o semáforo; a tarefa que espera por ele desperta e faz o trabalho. Explicamos os fundamentos das interrupções no artigo Interrupções no Arduino. Um mutex garante que apenas uma tarefa por vez use um recurso compartilhado, como a porta serial, o barramento I2C ou um display. Se duas tarefas chamam Serial.printf() no mesmo instante, suas linhas podem se misturar; com um mutex, cada tarefa obtém o bloqueio antes de escrever e o libera ao terminar. No código abaixo, cada pressão no botão alterna o estado do segundo LED, e duas tarefas escrevem no mesmo Monitor Serial sem misturar suas saídas.

C++ (Arduino IDE)
1const int BUTON_PIN = 27;              // butonun diğer ucu GND / other leg to GND
2const int LED_PIN   = 4;
3
4SemaphoreHandle_t butonSemaforu;       // kesme -> görev sinyali / ISR -> task signal
5SemaphoreHandle_t seriKilit;           // Serial için mutex / mutex for Serial
6
7void IRAM_ATTR butonKesmesi() {
8  BaseType_t uyandir = pdFALSE;
9  xSemaphoreGiveFromISR(butonSemaforu, &uyandir);   // ISR'de FromISR sürümü / FromISR version in ISR
10  if (uyandir == pdTRUE) {
11    portYIELD_FROM_ISR();              // bekleyen görevi hemen çalıştır / run the waiting task now
12  }
13}
14
15void guvenliYaz(const char *metin) {
16  if (xSemaphoreTake(seriKilit, pdMS_TO_TICKS(100)) == pdTRUE) {
17    Serial.println(metin);
18    xSemaphoreGive(seriKilit);         // kilidi mutlaka bırak / always release the lock
19  }
20}
21
22void butonGorevi(void *parametre) {
23  uint32_t sonBasma = 0;
24  for (;;) {
25    xSemaphoreTake(butonSemaforu, portMAX_DELAY);    // basılana kadar uyu / sleep until pressed
26    if (millis() - sonBasma > 200) {                 // 200 ms ark önleme / 200 ms debounce
27      sonBasma = millis();
28      digitalWrite(LED_PIN, !digitalRead(LED_PIN));
29      guvenliYaz("Butona basildi / Button pressed");
30    }
31  }
32}
33
34void raporGorevi(void *parametre) {
35  char satir[64];
36  for (;;) {
37    snprintf(satir, sizeof(satir), "Calisma suresi / Uptime: %lu s", (unsigned long)(millis() / 1000));
38    guvenliYaz(satir);
39    vTaskDelay(pdMS_TO_TICKS(2000));
40  }
41}
42
43void setup() {
44  Serial.begin(115200);
45  pinMode(LED_PIN, OUTPUT);
46  pinMode(BUTON_PIN, INPUT_PULLUP);
47  butonSemaforu = xSemaphoreCreateBinary();
48  seriKilit = xSemaphoreCreateMutex();
49  xTaskCreatePinnedToCore(butonGorevi, "Buton", 2048, NULL, 3, NULL, 1);
50  xTaskCreatePinnedToCore(raporGorevi, "Rapor", 2048, NULL, 1, NULL, 1);
51  attachInterrupt(digitalPinToInterrupt(BUTON_PIN), butonKesmesi, FALLING);
52}
53
54void loop() {
55  vTaskDelay(pdMS_TO_TICKS(1000));
56}
Dentro de uma rotina de interrupção, use somente funções FreeRTOS cujos nomes terminam em FromISR (como xSemaphoreGiveFromISR e xQueueSendFromISR). Chamar Serial.print(), delay() ou qualquer função que espere dentro de uma interrupção trava o ESP32. Coloque IRAM_ATTR antes da função de interrupção; isso coloca a função na RAM rápida em vez da memória flash. Depois de obter um mutex, sempre o devolva em todos os caminhos de execução: se você esquecer xSemaphoreGive() em um ramo de erro, todas as tarefas que esperam por esse recurso ficarão bloqueadas para sempre.

Em qual núcleo o Wi-Fi funciona e onde colocar suas tarefas?

No core do Arduino, o driver de Wi-Fi, a pilha TCP/IP e o Bluetooth ficam fixados no núcleo 0; loop() e os eventos do Arduino são executados no núcleo 1. Por padrão, o watchdog de tarefas do ESP32 também monitora a tarefa ociosa do núcleo 0 (IDLE0). Se você colocar no núcleo 0 uma tarefa que tenha prioridade e nunca espere, IDLE0 não conseguirá executar por 5 segundos, o Monitor Serial mostrará Task watchdog got triggered e a placa reiniciará. Essa mesma tarefa também atrasa o processamento dos pacotes de rede. Uma regra simples facilita as coisas:

TrabalhoNúcleo sugeridoPor quê?
Controle rápido e regular, amostragem de sensores, controle de motores1As interrupções do Wi-Fi não prejudicam a temporização
Servidor web, MQTT, solicitações HTTP0 ou 1, prioridade baixaA pilha de rede já está no núcleo 0; sua tarefa deve esperar com frequência
Atualizações do display, registro de dados1, prioridade 1Sem urgência, usa o tempo disponível
Cálculos longos (FFT, criptografia)1, ou 0 com prioridade baixa, intercalando vTaskDelay(1)Para não impedir a execução do watchdog e das outras tarefas

Tamanho da pilha e erros de watchdog

Cada tarefa tem sua própria memória de pilha; variáveis locais, chamadas de funções e funções de biblioteca como printf usam esse espaço. No ESP32, o tamanho da pilha é expresso em bytes; a unidade “word” mencionada na documentação padrão do FreeRTOS não se aplica ao ESP32. 2.048 bytes são suficientes para uma tarefa simples de LED. Reserve 3.072–4.096 bytes para tarefas que usam Serial.printf(), operações com String e impressão de números de ponto flutuante. Tarefas que lidam com HTTPClient, TLS (HTTPS) ou JSON podem precisar de 8.192 bytes ou mais. Se ocorrer um estouro de pilha, o ESP32 informa Stack canary watchpoint triggered ou A stack overflow in task ... has been detected e reinicia. Você pode descobrir a menor quantidade de pilha que permaneceu livre em uma tarefa até o momento com uxTaskGetStackHighWaterMark(); o valor é em bytes e, se cair abaixo de 500 bytes, você deve aumentar a pilha. Explicamos como ler as mensagens de erro por trás de reinicializações inesperadas em Brownout e Guru Meditation no ESP32.

Mensagem de erroSignificadoSolução
Task watchdog got triggered ... IDLE (CPU 0) (mensagem de erro: watchdog de tarefa acionado no núcleo 0)Uma tarefa no núcleo 0 não esperou por 5 sAdicione vTaskDelay(1) ao laço, reduza a prioridade ou mova a tarefa para o núcleo 1
Stack canary watchpoint triggered (task name) (mensagem de erro: estouro de pilha da tarefa)A pilha da tarefa indicada estourouAumente o valor da pilha em xTaskCreatePinnedToCore
Guru Meditation Error: LoadProhibitedFoi lido um endereço inválidoConfira se o ponteiro passado à tarefa aponta para uma variável local
Interrupt wdt timeout on CPU1Uma rotina de interrupção demorou demais ou as interrupções permaneceram desativadasEncurte a ISR e transfira o trabalho para uma tarefa usando um semáforo
FreeRTOS Task "Gorev" should not return, Aborting now! (mensagem de erro: a função da tarefa não deve retornar)A função da tarefa terminou com returnUse um laço infinito ou chame vTaskDelete(NULL) no final

Projeto: LED, sensor e servidor web ao mesmo tempo

Agora vamos reunir o que aprendemos em um projeto. Haverá três tarefas: a tarefa do sensor lê o potenciômetro a cada 200 ms e escreve a média das últimas 8 leituras em uma fila de um único item; a tarefa do LED pisca o LED integrado em uma velocidade definida pela página web; e a tarefa web mostra o valor atual do sensor em uma página aberta no celular e oferece links que alteram a velocidade do LED. As tarefas compartilham dados usando xQueueOverwrite() e xQueuePeek(), sem recorrer a variáveis globais. loop() imprime a pilha livre de cada tarefa e a RAM livre a cada 10 segundos, para que você veja, durante o funcionamento real, se as pilhas são grandes o suficiente. Substitua o nome da rede Wi-Fi e a senha pelos seus.

C++ (Arduino IDE)
1#include <WiFi.h>
2#include <WebServer.h>
3
4const char* WIFI_ADI   = "EvAgi_2G";       // Wi-Fi adı / network name
5const char* WIFI_SIFRE = "sifre1234";      // Wi-Fi şifresi / Wi-Fi password
6
7const int LED_PIN = 2;                     // dahili LED / onboard LED
8const int POT_PIN = 34;                    // ADC1, Wi-Fi ile çalışır / ADC1, works with Wi-Fi
9
10WebServer sunucu(80);
11QueueHandle_t sensorKutusu;                // tek öğe: son ortalama / one item: latest average
12QueueHandle_t hizKutusu;                   // tek öğe: LED yarım periyodu / one item: LED half period
13TaskHandle_t ledTutamac, sensorTutamac, webTutamac;
14
15void sensorGorevi(void *p) {
16  uint16_t son[8] = {0};
17  uint8_t sira = 0;
18  TickType_t sonUyanma = xTaskGetTickCount();
19  for (;;) {
20    son[sira] = analogRead(POT_PIN);
21    sira = (sira + 1) % 8;
22    uint32_t toplam = 0;
23    for (int i = 0; i < 8; i++) toplam += son[i];
24    uint16_t ortalama = toplam / 8;
25    xQueueOverwrite(sensorKutusu, &ortalama);       // eskisinin üzerine yaz / overwrite the old one
26    vTaskDelayUntil(&sonUyanma, pdMS_TO_TICKS(200));
27  }
28}
29
30void ledGorevi(void *p) {
31  pinMode(LED_PIN, OUTPUT);
32  uint32_t beklemeMs = 500;
33  for (;;) {
34    xQueuePeek(hizKutusu, &beklemeMs, 0);           // yeni hız varsa al / take a new speed if any
35    digitalWrite(LED_PIN, !digitalRead(LED_PIN));
36    vTaskDelay(pdMS_TO_TICKS(beklemeMs));
37  }
38}
39
40void anaSayfa() {
41  uint16_t deger = 0;
42  uint32_t hiz = 0;
43  xQueuePeek(sensorKutusu, &deger, 0);              // okur ama silmez / reads without removing
44  xQueuePeek(hizKutusu, &hiz, 0);
45  String html = "<!DOCTYPE html><html><head><meta charset='utf-8'>"
46                "<meta http-equiv='refresh' content='2'>"
47                "<meta name='viewport' content='width=device-width'></head><body>"
48                "<h2>ESP32 FreeRTOS</h2>";
49  html += "<p>Sensor: " + String(deger) + " / 4095</p>";
50  html += "<p>LED: " + String(hiz) + " ms</p>";
51  html += "<p><a href='/hiz?ms=100'>100 ms</a> | <a href='/hiz?ms=500'>500 ms</a> | "
52          "<a href='/hiz?ms=1000'>1000 ms</a></p></body></html>";
53  sunucu.send(200, "text/html", html);
54}
55
56void hizAyarla() {
57  uint32_t ms = sunucu.arg("ms").toInt();
58  if (ms >= 50 && ms <= 5000) {
59    xQueueOverwrite(hizKutusu, &ms);
60  }
61  sunucu.sendHeader("Location", "/");
62  sunucu.send(303);
63}
64
65void webGorevi(void *p) {
66  WiFi.mode(WIFI_STA);
67  WiFi.begin(WIFI_ADI, WIFI_SIFRE);
68  while (WiFi.status() != WL_CONNECTED) {
69    vTaskDelay(pdMS_TO_TICKS(500));                 // beklerken çekirdeği bırak / yield while waiting
70  }
71  Serial.print("Adres / Address: http://");
72  Serial.println(WiFi.localIP());
73  sunucu.on("/", anaSayfa);
74  sunucu.on("/hiz", hizAyarla);
75  sunucu.begin();
76  for (;;) {
77    sunucu.handleClient();
78    vTaskDelay(pdMS_TO_TICKS(2));                   // IDLE görevine nefes aldır / let the idle task run
79  }
80}
81
82void setup() {
83  Serial.begin(115200);
84  sensorKutusu = xQueueCreate(1, sizeof(uint16_t));
85  hizKutusu = xQueueCreate(1, sizeof(uint32_t));
86  uint32_t ilkHiz = 500;
87  xQueueOverwrite(hizKutusu, &ilkHiz);
88
89  xTaskCreatePinnedToCore(sensorGorevi, "Sensor", 2048, NULL, 2, &sensorTutamac, 1);
90  xTaskCreatePinnedToCore(ledGorevi, "LED", 2048, NULL, 1, &ledTutamac, 1);
91  xTaskCreatePinnedToCore(webGorevi, "Web", 6144, NULL, 1, &webTutamac, 0);
92}
93
94void loop() {
95  // boş yığın (bayt) ve boş RAM / free stack (bytes) and free heap
96  Serial.printf("Bos yigin / Free stack  Sensor: %u  LED: %u  Web: %u  |  Heap: %u\n",
97                (unsigned)uxTaskGetStackHighWaterMark(sensorTutamac),
98                (unsigned)uxTaskGetStackHighWaterMark(ledTutamac),
99                (unsigned)uxTaskGetStackHighWaterMark(webTutamac),
100                (unsigned)ESP.getFreeHeap());
101  vTaskDelay(pdMS_TO_TICKS(10000));
102}

Após carregar o código, abra no celular o endereço mostrado no Monitor Serial. A página é atualizada a cada 2 segundos e o valor muda conforme você gira o potenciômetro. Ao tocar nos links, a velocidade do LED muda imediatamente, mas o ritmo de leitura do sensor nunca é afetado, porque cada trabalho é executado em sua própria tarefa e em seu próprio ritmo. A tarefa web fica no núcleo 0, junto da pilha de rede, com prioridade baixa; como espera 2 ms a cada repetição, a tarefa IDLE0 consegue executar e o watchdog não é acionado. As tarefas do LED e do sensor ficam no núcleo 1 e não são afetadas pelo tráfego Wi-Fi. É fácil expandir essa estrutura: para atualizar os valores instantaneamente sem recarregar a página, adicione o método WebSocket do artigo Servidor web e WebSocket no ESP32 e, para suavizar valores de sensores com ruído, substitua a média na tarefa do sensor por um filtro de mediana ou exponencial.

Comparação com o Raspberry Pi Pico: dois núcleos no MicroPython

O RP2040 do Raspberry Pi Pico também é dual-core, mas não há sistema operacional: no MicroPython, você inicia o segundo núcleo com o módulo _thread, e apenas duas threads são executadas nos dois núcleos. No Arduino, o core arduino-pico oferece as funções setup1() e loop1() para o segundo núcleo. O código MicroPython abaixo pisca o LED no segundo núcleo enquanto lê o potenciômetro no primeiro; o contador compartilhado é protegido por um lock, assim como o mutex no ESP32. Há mais informações sobre os núcleos e as unidades PIO do Pico no artigo PIO e dois núcleos do Pico.

MicroPython
1import _thread, time
2from machine import Pin, ADC
3
4led = Pin(25, Pin.OUT)          # Pico dahili LED (Pico W'da Pin("LED")) / onboard LED (Pin("LED") on Pico W)
5pot = ADC(26)                   # GP26 = ADC0
6kilit = _thread.allocate_lock() # ortak veri kilidi / lock for shared data
7yanma_sayisi = 0
8
9def ikinci_cekirdek():
10    global yanma_sayisi
11    while True:
12        led.toggle()
13        with kilit:             # sayaç güvenle artar / counter updated safely
14            yanma_sayisi += 1
15        time.sleep_ms(300)
16
17_thread.start_new_thread(ikinci_cekirdek, ())   # çekirdek 1'de çalışır / runs on core 1
18
19while True:
20    deger = pot.read_u16()      # 0-65535
21    with kilit:
22        sayac = yanma_sayisi
23    print("Pot:", deger, "LED degisimi / toggles:", sayac)
24    time.sleep(1)

No Pico, esse método funciona bem para dois trabalhos, mas recursos como quantidade de tarefas, prioridades, filas e escalonador não são tão completos quanto no FreeRTOS do ESP32. Para projetos com muitos trabalhos simultâneos, conexões de rede e temporização precisa, o ESP32 e o FreeRTOS oferecem uma base mais prática. Se você quer criar projetos Wi-Fi com o Pico, confira o artigo Servidor web Wi-Fi com Pico W.

Erros comuns e soluções

SintomaCausa provávelSolução
A placa reinicia assim que uma tarefa é criadaA função da tarefa termina com return ou a pilha é pequena demaisAdicione um laço infinito e aumente a pilha para 4.096 bytes
loop() nunca é executadaUma tarefa de prioridade maior no núcleo 1 nunca esperaAdicione vTaskDelay() a essa tarefa ou reduza sua prioridade para 1
Erro de watchdog quando o Wi-Fi está ligadoUma tarefa no núcleo 0 impede a execução de IDLE0Use vTaskDelay(1) no laço ou mova a tarefa para o núcleo 1
Os valores às vezes não fazem sentidoDuas tarefas leem e escrevem na mesma estrutura global ao mesmo tempoTransfira os dados com uma fila ou proteja o acesso com um mutex
As linhas no Monitor Serial ficam misturadasDuas tarefas escrevem em Serial ao mesmo tempoObtenha um mutex antes de escrever e libere-o depois
A placa trava quando o botão é pressionadoSerial.print ou uma função FreeRTOS normal na rotina de interrupçãoUse apenas funções FromISR na ISR e transfira o trabalho para uma tarefa
analogRead() retorna 4095 ou 0 enquanto o Wi-Fi está ligadoO sensor está em um pino ADC2Use um dos pinos ADC1 GPIO 32–39
O código compila no ESP32-C3, mas não executaFoi solicitado o núcleo 1 em uma placa de núcleo únicoUse o núcleo 0 ou tskNO_AFFINITY, ou use xTaskCreate()
Ao migrar para o FreeRTOS, não divida tudo em tarefas de uma vez. Primeiro, mova o trabalho mais sensível ao tempo do seu código que já funciona, como a amostragem de sensores, para uma tarefa própria e deixe o restante em loop(). Confira a pilha com uxTaskGetStackHighWaterMark() após cada nova tarefa. Se você trocar todos os dados entre tarefas por filas e acessar cada recurso de hardware compartilhado por meio de um mutex, evitará desde o início a maioria dos erros do tipo “às vezes dá problema”.

Os dois núcleos do ESP32 e o FreeRTOS transformam funções loop() complicadas, cheias de cálculos com millis(), em tarefas pequenas e legíveis, cada uma dedicada a um trabalho. Agora que você sabe criar tarefas, definir prioridades, transferir dados com filas, tratar interrupções com semáforos e medir a pilha, seus projetos Wi-Fi vão funcionar sem travar. Se você está começando com o ESP32, encontrará os fundamentos em O que é o ESP32?. No app BlueGrays, você também pode explorar projetos com ESP32, como servidor web assíncrono, WebSocket, relógio NTP, registrador de temperatura e iluminação inteligente, todos com esquemas do circuito passo a passo e códigos prontos para usar.

Perguntas frequentes

O que é o FreeRTOS no ESP32?

FreeRTOS é um sistema operacional de tempo real que funciona dentro do ESP32, e seu código Arduino roda sobre ele. Ele permite dividir vários trabalhos em tarefas separadas, definir prioridades e distribuí-las pelos dois núcleos. Não é necessária uma instalação separada; funções como xTaskCreate já estão prontas para usar no core do Arduino para ESP32.

Em qual núcleo loop() é executada no ESP32?

No core do Arduino, setup() e loop() são executadas dentro de uma tarefa chamada loopTask no núcleo 1, com prioridade 1. Wi-Fi, TCP/IP e Bluetooth ficam no núcleo 0. Você pode conferir isso imprimindo xPortGetCoreID().

Qual é a diferença entre delay() e vTaskDelay() no ESP32?

No core do Arduino para ESP32, delay() na verdade chama vTaskDelay(), então ambas liberam o núcleo para outras tarefas durante a espera. A espera ocupada que você conhece do Arduino Uno ocorre no ESP32 com delayMicroseconds() e laços while vazios. Para trabalhos com frequência fixa, vTaskDelayUntil() é mais precisa.

Qual deve ser o tamanho da pilha em xTaskCreatePinnedToCore?

No ESP32, o tamanho da pilha é expresso em bytes. 2.048 bytes são um bom ponto de partida para tarefas simples de LED, 3.072–4.096 para tarefas que usam Serial.printf e String, e 8.192 para trabalhos pesados como HTTPS e JSON. Meça a necessidade real com uxTaskGetStackHighWaterMark() e ajuste.

Como corrigir o erro “Task watchdog got triggered” no ESP32?

Esse erro significa que a tarefa ociosa do núcleo 0 não conseguiu executar por 5 segundos; geralmente, uma tarefa está em um laço sem nunca esperar. Adicione vTaskDelay(1) dentro do laço, reduza a prioridade da tarefa ou mova-a para o núcleo 1. Dividir cálculos longos em partes menores também ajuda.

Como compartilhar dados entre tarefas no ESP32?

A forma mais segura é usar filas do FreeRTOS: os dados são enviados com xQueueSend() e recebidos com xQueueReceive() e, como são copiados, não ocorrem leituras parciais de valores. Se só precisar do valor mais recente, use uma fila de um único item com xQueueOverwrite() e xQueuePeek(). Se você compartilhar hardware ou uma estrutura global, proteja o acesso com um mutex.

Ver todos os projetos
Servidor web assíncrono com ESP32 (IP no LCD)
ES-27Avançado

Servidor web assíncrono com ESP32 (IP no LCD)

Neste projeto, transformamos o ESP32 em um servidor web assíncrono que você pode controlar pelo celular ou computador na mesma rede Wi-Fi. Com a biblioteca ESPAsyncWebServer, o servidor processa várias requisições ao mesmo tempo (ao contrário do WebServer.h tradicional, que bloqueia a execução ao processar uma requisição). Você poderá abrir o endereço IP do ESP32 no navegador e clicar nos botões ON/OFF (as rotas /on e /off) para ligar e desligar o LED conectado ao GPIO 5.

4.8(16)
26
Contador WebSocket com ESP32 (2 botões + LCD + web em tempo real)
ES-28Avançado
Premium

Contador WebSocket com ESP32 (2 botões + LCD + web em tempo real)

Neste projeto, dois botões conectados ao ESP32 (GPIO 5 aumenta, GPIO 4 diminui) alteram um contador. O valor é atualizado instantaneamente no LCD I2C 16x2 e, com o suporte a WebSocket do ESPAsyncWebServer, em todos os navegadores conectados, sem recarregar a página. Em vez de consultas periódicas por HTTP, usamos uma única conexão persistente, e o ESP32 envia o novo valor a todos com ws.textAll().

4.5(14)
23
Conexão Wi-Fi STA com ESP32 e display LCD
ES-25Avançado

Conexão Wi-Fi STA com ESP32 e display LCD

Neste projeto, conectamos o ESP32 à rede Wi-Fi de casa no modo estação (STA), de forma segura e tolerante a falhas. Guardamos o SSID e a senha em um arquivo secrets.h separado para evitar que sejam expostos no Git, configuramos um mecanismo de reconexão automática e exibimos o nível de sinal RSSI e o endereço IP em um display LCD I2C. O LED integrado funciona como indicador de status. É um gerenciador de conexão pronto para uso em produção.

4.4(21)
38
Brilho do LED com potenciômetro no ESP32 (analógico → PWM)
ES-13Intermediário
Premium

Brilho do LED com potenciômetro no ESP32 (analógico → PWM)

Neste projeto, controlamos o brilho de um LED de forma analógica com um potenciômetro. O pino ADC do ESP32 lê a tensão de 0-3,3V do potenciômetro e converte esse valor em um sinal PWM (modulação por largura de pulso), enviado ao LED. Assim, ao girar o potenciômetro, o brilho do LED aumenta e diminui gradualmente. Com Arduino Core 3.0+, você pode usar analogWrite() diretamente; no ESP32-S2/S3, a resolução do ADC é fixada em 12 bits.

4.5(19)
32
Controle de fita WS2812B NeoPixel com ESP32
ES-24Intermediário
Premium

Controle de fita WS2812B NeoPixel com ESP32

Os LEDs endereçáveis WS2812B (NeoPixel) são LEDs RGB inteligentes que podem ser controlados em cadeia por um único pino de dados. Neste projeto, vamos controlar uma fita WS2812B de 8 LEDs com a biblioteca Adafruit_NeoPixel para criar uma animação suave de arco-íris. Embora o nível lógico de 3,3V do ESP32 funcione sem problemas na maioria dos lotes de WS2812B, vamos mostrar uma solução com um resistor de 470Ω em série e um capacitor de 1.000µF para casos de instabilidade.

4.9(19)
30
ESP32 em sono profundo — Economia de bateria (OLED + contador na RAM RTC)
ES-33Avançado
Premium

ESP32 em sono profundo — Economia de bateria (OLED + contador na RAM RTC)

O modo de sono profundo do ESP32 reduz o consumo de corrente para ~10 µA ao desligar a CPU e a maioria dos periféricos, sendo essencial para dispositivos IoT alimentados por bateria. Neste projeto, usamos três fontes de despertar: um temporizador (15 segundos), um pino externo (EXT0 — botão no GPIO 33) e toque (T0/GPIO 4). As variáveis marcadas com RTC_DATA_ATTR são preservadas durante o sono profundo, mantendo os contadores de inicializações e de despertares por temporizador e botão.

4.3(10)
16
Registrador de temperatura com ESP32 (DHT22 + DS1307 RTC + microSD + OLED)
ES-40Avançado
Premium

Registrador de temperatura com ESP32 (DHT22 + DS1307 RTC + microSD + OLED)

Monte um registrador de temperatura com data e hora usando ESP32. O DHT22 mede a temperatura e a umidade a cada minuto, o DS1307 RTC fornece a hora real e cada leitura é gravada em CSV no cartão microSD. O OLED mostra em letras grandes a temperatura atual, além da umidade, da data e hora e do total de registros. Abra o arquivo /temp_log.csv no Excel, no Google Sheets ou com pandas para acompanhar uma estufa ou a temperatura de casa.

4.7(7)
12
Iluminação inteligente com ESP32 (PIR + LDR + relé + OLED)
ES-37Avançado
Premium

Iluminação inteligente com ESP32 (PIR + LDR + relé + OLED)

Transforme a iluminação do corredor, banheiro ou despensa em iluminação inteligente com ESP32! Com um sensor de movimento PIR, um sensor de luz LDR e um módulo relé, montamos o cenário clássico de "acender a luz ao detectar movimento no escuro" — se o ambiente já estiver claro, o movimento NÃO aciona a luz, economizando energia durante o dia. A luz fica acesa por 30 segundos; se o movimento continuar, o temporizador reinicia e a luz permanece acesa por mais tempo.

4.3(6)
11