FreeRTOS su ESP32 con Arduino: task, code, semafori e mutex
Perché loop() è un task sul core 1, come creare task sui due core, vTaskDelayUntil, code tra produttore e consumatore, semafori da interrupt, mutex per la seriale e task watchdog.

Chi passa da Arduino UNO all’ESP32 scopre presto che lo sketch non è più l’unico programma in esecuzione. Sotto setup() e loop() lavora FreeRTOS, un sistema operativo in tempo reale che gestisce il Wi-Fi, i timer di sistema e, su un chip a due core, decide istante per istante quale codice far girare. Ignorarlo funziona finché il progetto è piccolo; quando però bisogna leggere un sensore a intervalli regolari, rispondere subito a un pulsante e intanto mantenere una connessione di rete, il classico loop() pieno di millis() diventa difficile da leggere e da far funzionare bene.
Questa guida prosegue la guida introduttiva all’ESP32 e riusa lo stesso circuito: LED su GPIO25, pulsante su GPIO27 e potenziometro su GPIO34. Si vedrà perché il core Arduino per ESP32 è costruito sopra FreeRTOS, come si crea un task e lo si assegna a un core, la differenza tra vTaskDelay(), delay() e vTaskDelayUntil(), come si passano dati tra task con una coda, come un interrupt sveglia un task con un semaforo binario e come un mutex protegge una risorsa condivisa come la seriale. Chiudono la guida il dimensionamento dello stack, il task watchdog e gli errori più comuni. Tutti i programmi sono stati compilati ed eseguiti nell’emulatore QEMU di Espressif: i log della simulazione compaiono nel testo e nei grafici.
Perché sull’ESP32 c’è FreeRTOS
Il core arduino-esp32 non è un firmware scritto da zero: è un componente di ESP-IDF, il framework ufficiale di Espressif, e ESP-IDF è costruito su una versione di FreeRTOS modificata per il multiprocessore simmetrico (SMP). La versione 3.3.12 del core usa ESP-IDF 5.5, il cui kernel deriva da FreeRTOS 10.5.1. Lo scheduler parte da solo prima dello sketch: la funzione app_main() del core inizializza l’hardware e crea un task chiamato loopTask, che esegue setup() una volta e poi loop() all’infinito. Nel core 3.3.12 questo task ha 8192 byte di stack, priorità 1 ed è assegnato al core 1.
Nel frattempo girano altri task creati dal sistema. La documentazione di ESP-IDF elenca un task idle per ciascun core (priorità 0), un task ipc per core (priorità 24), il task esp_timer (priorità 22, core 0) e, se si usano le API dei timer software, il task Tmr Svc. Il Wi-Fi e il Bluetooth, quando vengono attivati, aggiungono i propri task, anch’essi sul core 0. È per questo che lo sketch Arduino gira di norma sul core 1: il core 0 resta disponibile per la radio.
| Parametro (core 3.3.12, ESP32 classico) | Valore | Conseguenza pratica |
|---|---|---|
Frequenza del tick (configTICK_RATE_HZ) |
1000 Hz | 1 tick = 1 ms, pdMS_TO_TICKS(100) = 100 |
Priorità disponibili (configMAX_PRIORITIES) |
25 (da 0 a 24) | numero più alto = più importante |
loopTask (setup() e loop()) |
8192 byte, priorità 1, core 1 | loop() è un task come gli altri |
| Task watchdog | 5 s, sorveglia IDLE0, poi panic e riavvio | un task che monopolizza il core 0 fa ripartire la scheda |
| Controllo dello stack overflow | metodo canary | messaggio ***ERROR*** A stack overflow in task ... |
Lo scheduler è preemptive a priorità fissa: tra i task pronti, ogni core esegue quello con priorità più alta, e un task che diventa pronto con priorità maggiore interrompe subito quello in corso. A parità di priorità i task si alternano a ogni tick (time slicing), ma la documentazione di ESP-IDF avverte che su due core l’alternanza è solo “best effort” e consiglia di assegnare allo stesso core i task con la stessa priorità. Il punto chiave è che un task bloccato non consuma CPU: mentre aspetta, la CPU esegue gli altri task o il task idle.
Creare un task con xTaskCreatePinnedToCore
Un task è una funzione C con un ciclo infinito, che riceve un puntatore generico e non deve mai terminare con return: se il lavoro è finito, il task si cancella con vTaskDelete(NULL). Sull’ESP32 si crea di solito con xTaskCreatePinnedToCore(), che aggiunge alla funzione standard di FreeRTOS la scelta del core.
BaseType_t xTaskCreatePinnedToCore(
TaskFunction_t funzione, // void funzione(void *param)
const char *nome, // nome per il debug (max 15 caratteri)
uint32_t stack, // dimensione dello stack in BYTE (ESP-IDF)
void *param, // puntatore passato alla funzione
UBaseType_t priorita, // 0 ... 24
TaskHandle_t *handle, // dove salvare l'handle (o NULL)
BaseType_t core); // 0, 1 oppure tskNO_AFFINITY
Attenzione al terzo parametro: in FreeRTOS “standard” lo stack si esprime in word (4 byte su un processore a 32 bit), mentre in ESP-IDF si esprime in byte, come precisa la documentazione Espressif. Un esempio trovato in rete per un altro microcontrollore che passa 1024 alloca 4 KB su un ARM, ma solo 1 KB sull’ESP32: troppo poco per un task che usa printf(). Con tskNO_AFFINITY il task può girare su entrambi i core; con 0 o 1 resta vincolato a quello indicato. La funzione restituisce pdPASS se il task è stato creato; un errore indica in genere memoria insufficiente.
Il primo programma crea due task con la stessa struttura: un’elaborazione di durata variabile (20, 30 o 40 ms, simulata con un’attesa attiva) seguita da un ritardo di 100 ms. Il primo usa vTaskDelay() ed è vincolato al core 0, il secondo usa vTaskDelayUntil() e comanda il LED sul core 1. Entrambi misurano il proprio periodo con esp_timer_get_time(), che conta i microsecondi dall’avvio, e dopo 20 cicli stampano un riepilogo. loop() ogni 5 s stampa lo stack rimasto libero.
// FreeRTOS su ESP32: due task su core diversi, vTaskDelay e vTaskDelayUntil
// Core arduino-esp32 3.x - ESP32 classico (DevKitC), LED su GPIO25
const int LED_PIN = 25;
const uint32_t PERIODO_MS = 100; // periodo desiderato per entrambi i task
const uint32_t CICLI = 20; // cicli registrati prima del riepilogo
TaskHandle_t hRelativo = NULL;
TaskHandle_t hAssoluto = NULL;
// Simula un'elaborazione di durata variabile (20, 30, 40 ms) che occupa la CPU
static void lavoro(uint32_t n) {
int64_t durata_us = (20 + (n % 3) * 10) * 1000LL;
int64_t t0 = esp_timer_get_time();
while (esp_timer_get_time() - t0 < durata_us) {
// attesa attiva: tiene occupato il core (vedi paragrafo sul watchdog)
}
}
// Stampa periodo medio, minimo e massimo misurati
static void riepilogo(const char *nome, const uint32_t *p, uint32_t n) {
uint32_t mn = p[0], mx = p[0], somma = 0;
for (uint32_t i = 0; i < n; i++) {
somma += p[i];
if (p[i] < mn) mn = p[i];
if (p[i] > mx) mx = p[i];
}
Serial.printf("%s: periodo medio %.1f ms (min %lu, max %lu)\n", nome,
(float)somma / n, (unsigned long)mn, (unsigned long)mx);
}
// Task 1: lavoro + vTaskDelay -> il ritardo si somma alla durata del lavoro
void taskRelativo(void *param) {
uint32_t periodi[CICLI];
int64_t prec = esp_timer_get_time();
Serial.printf("taskRelativo avviato sul core %d\n", xPortGetCoreID());
for (uint32_t n = 0; ; n++) {
lavoro(n);
vTaskDelay(pdMS_TO_TICKS(PERIODO_MS));
int64_t ora = esp_timer_get_time();
if (n < CICLI) {
periodi[n] = (uint32_t)((ora - prec + 500) / 1000);
Serial.printf("R;%lu;%lu\n", (unsigned long)n, (unsigned long)periodi[n]);
} else if (n == CICLI) {
riepilogo("vTaskDelay", periodi, CICLI);
}
prec = ora;
}
}
// Task 2: lavoro + vTaskDelayUntil -> periodo fisso, indipendente dal lavoro
void taskAssoluto(void *param) {
uint32_t periodi[CICLI];
bool led = false;
int64_t prec = esp_timer_get_time();
TickType_t ultimoRisveglio = xTaskGetTickCount();
Serial.printf("taskAssoluto avviato sul core %d\n", xPortGetCoreID());
for (uint32_t n = 0; ; n++) {
lavoro(n);
led = !led;
digitalWrite(LED_PIN, led);
vTaskDelayUntil(&ultimoRisveglio, pdMS_TO_TICKS(PERIODO_MS));
int64_t ora = esp_timer_get_time();
if (n < CICLI) {
periodi[n] = (uint32_t)((ora - prec + 500) / 1000);
Serial.printf("A;%lu;%lu\n", (unsigned long)n, (unsigned long)periodi[n]);
} else if (n == CICLI) {
riepilogo("vTaskDelayUntil", periodi, CICLI);
}
prec = ora;
}
}
void setup() {
Serial.begin(115200);
delay(100);
pinMode(LED_PIN, OUTPUT);
Serial.printf("setup() sul core %d, priorita' %u, tick %d Hz\n",
xPortGetCoreID(), (unsigned)uxTaskPriorityGet(NULL), configTICK_RATE_HZ);
// funzione, nome, stack in BYTE, parametro, priorita', handle, core
xTaskCreatePinnedToCore(taskRelativo, "relativo", 4096, NULL, 1, &hRelativo, 0);
xTaskCreatePinnedToCore(taskAssoluto, "assoluto", 4096, NULL, 1, &hAssoluto, 1);
}
void loop() {
// loop() e' anch'esso un task (loopTask, priorita' 1, core 1)
vTaskDelay(pdMS_TO_TICKS(5000));
Serial.printf("Stack libero minimo: relativo %u, assoluto %u, loopTask %u byte\n",
(unsigned)uxTaskGetStackHighWaterMark(hRelativo),
(unsigned)uxTaskGetStackHighWaterMark(hAssoluto),
(unsigned)uxTaskGetStackHighWaterMark(NULL));
}
Nella simulazione l’ordine dei messaggi conferma la struttura descritta: setup() gira sul core 1 con priorità 1 e tick a 1000 Hz, taskRelativo parte sul core 0 e taskAssoluto sul core 1. Il riepilogo finale è il seguente:
setup() sul core 1, priorita' 1, tick 1000 Hz taskAssoluto avviato sul core 1 taskRelativo avviato sul core 0 ... vTaskDelayUntil: periodo medio 99.6 ms (min 91, max 104) vTaskDelay: periodo medio 130.4 ms (min 117, max 141) Stack libero minimo: relativo 1984, assoluto 1820, loopTask 6544 byte
vTaskDelay, delay e vTaskDelayUntil
vTaskDelay(n) blocca il task per n tick a partire dal momento della chiamata: il ritardo si somma al tempo speso nell’elaborazione. Nel core Arduino per ESP32 anche delay(ms) è implementata come vTaskDelay(ms / portTICK_PERIOD_MS), quindi non è un’attesa attiva come sulla UNO: durante un delay() la CPU passa agli altri task. vTaskDelayUntil(&ultimo, n) invece calcola il risveglio in tempo assoluto, come ultimo + n, e aggiorna da sola la variabile ultimo: il periodo resta costante qualunque sia la durata del lavoro, purché questa sia inferiore al periodo. ESP-IDF documenta la variante xTaskDelayUntil(), che restituisce pdFALSE se il risveglio previsto era già passato, cioè se il task ha “perso” una scadenza; vTaskDelayUntil() è la stessa funzione senza valore di ritorno.
Il grafico, ottenuto dal log della simulazione, mostra la differenza: con vTaskDelay() il periodo oscilla tra 120 e 140 ms seguendo la durata del lavoro (media 130 ms), con vTaskDelayUntil() resta a 100 ms. Le piccole deviazioni di qualche millisecondo sono dovute all’emulatore, che in questa modalità segue l’orologio del computer che lo esegue e non i tempi della CPU reale: ripetendo la simulazione con il tempo virtuale deterministico di QEMU (opzione -icount) i periodi risultano esattamente 100 ms con vTaskDelayUntil() e 120, 130, 140 ms con vTaskDelay(), ed è ciò che ci si aspetta su una scheda vera. La regola pratica è semplice: per campionare un sensore, aggiornare un regolatore o generare un evento periodico si usa vTaskDelayUntil(); vTaskDelay() o delay() vanno bene per pause il cui valore esatto non conta.
Esempio di calcolo: periodo dei due task (dati dello sketch)
vTaskDelay: T = t_lavoro + 100 ms
t_lavoro = 20, 30, 40 ms -> T = 120, 130, 140 ms
media = (120 + 130 + 140) / 3 = 130 ms
vTaskDelayUntil: T = 100 ms (finché t_lavoro < 100 ms)
Risoluzione: 1 tick = 1/1000 Hz = 1 ms. Ritardi più brevi del tick
non si ottengono con vTaskDelay(): servono un timer hardware o esp_timer.
Code: passare dati tra task
Due task che si scambiano dati attraverso una variabile globale rischiano di leggere un valore scritto a metà, di perdere aggiornamenti o di dover controllare continuamente se c’è un dato nuovo. La coda (queue) di FreeRTOS risolve tutti e tre i problemi: è un buffer FIFO di elementi a dimensione fissa, protetto dal kernel, in cui un task scrive con xQueueSend() e un altro legge con xQueueReceive(). Gli elementi vengono copiati per valore (il commento nel sorgente di FreeRTOS dice “items are queued by copy, not by reference”): si può quindi inviare una struttura locale senza preoccuparsi della sua durata.
QueueHandle_t coda = xQueueCreate(10, sizeof(Campione)); // 10 elementi
// produttore: attesa massima 0 tick (se la coda è piena, il dato si perde)
if (xQueueSend(coda, &c, 0) != pdPASS) campioniPersi++;
// consumatore: dorme fino all'arrivo di un dato, al massimo 500 ms
if (xQueueReceive(coda, &c, pdMS_TO_TICKS(500)) == pdPASS) { /* elabora c */ }
L’ultimo parametro è il tempo massimo di attesa in tick. Con 0 la funzione ritorna subito; con portMAX_DELAY il task resta bloccato finché l’operazione non è possibile. Per il consumatore il blocco è la scelta naturale: non consuma CPU e si sveglia appena arriva un dato, senza ritardi di polling. Per il produttore la scelta dipende dall’applicazione: un task che campiona a periodo fisso non deve bloccarsi, perché ritarderebbe il campione successivo, quindi conviene usare 0 e contare i dati persi. La funzione uxQueueMessagesWaiting() restituisce il numero di elementi presenti ed è utile per la diagnostica.
Semafori binari dagli interrupt
Una routine di interrupt (ISR) deve durare il meno possibile: finché è in esecuzione, gli interrupt di priorità uguale o inferiore e lo scheduler su quel core sono fermi. Non può chiamare funzioni bloccanti né usare Serial. Lo schema corretto è rinviare il lavoro a un task: la ISR registra l’evento e “dà” un semaforo binario, il task resta bloccato su xSemaphoreTake() e si sveglia appena il semaforo diventa disponibile. Il semaforo binario creato con xSemaphoreCreateBinary() nasce vuoto, quindi il primo Take blocca finché la ISR non esegue il primo Give.
void ARDUINO_ISR_ATTR isrPulsante() {
BaseType_t svegliaTask = pdFALSE;
xSemaphoreGiveFromISR(semPulsante, &svegliaTask);
portYIELD_FROM_ISR(svegliaTask);
}
Dentro una ISR si usano solo le funzioni con suffisso FromISR. Il secondo argomento viene impostato a pdTRUE se il Give ha reso pronto un task con priorità più alta di quello interrotto: in quel caso portYIELD_FROM_ISR() chiede allo scheduler di passare a quel task all’uscita dall’interrupt, invece di aspettare il tick successivo. ARDUINO_ISR_ATTR è la macro del core per le ISR: diventa IRAM_ATTR (funzione nella RAM interna, eseguibile anche mentre la cache della flash è disabilitata) solo se il core è compilato con l’opzione CONFIG_ARDUINO_ISR_IRAM. Nel core 3.3.12 distribuito per l’IDE questa opzione è disattivata, quindi la macro è vuota e l’interrupt GPIO viene registrato senza il flag IRAM: durante una scrittura in flash viene semplicemente rinviato. Conviene comunque usarla, perché rende lo sketch corretto anche con un core configurato diversamente. Va ricordato che l’interrupt GPIO viene allocato sul core che chiama attachInterrupt(), qui il core 1 di setup(): se il task svegliato è vincolato al core 0, è il kernel SMP a segnalare l’altro core.
Un semaforo binario non conta gli eventi: se la ISR esegue tre Give prima che il task faccia Take, il task si sveglia una volta sola. Per un pulsante è un vantaggio, perché i rimbalzi del contatto vengono assorbiti. Se invece ogni evento conta, per esempio gli impulsi di un contatore, servono un semaforo contatore (xSemaphoreCreateCounting()) o una coda.
Mutex per la seriale condivisa
Quando più task stampano sulla stessa seriale, le righe rischiano di mescolarsi. Nel core 3.x ogni singola scrittura sulla UART è già protetta da un lock interno, quindi una sola chiamata a Serial.printf() esce intera; il problema nasce quando una riga è composta da più chiamate, come un’intestazione con il tempo seguita dal messaggio, perché tra l’una e l’altra può inserirsi un altro task. La soluzione è un mutex: chi lo prende con xSemaphoreTake() ha l’uso esclusivo della risorsa fino al xSemaphoreGive().
Il mutex sembra un semaforo binario, ma ha due differenze importanti. Va restituito dallo stesso task che lo ha preso, e implementa l’ereditarietà della priorità: se un task a bassa priorità lo detiene e uno ad alta priorità lo richiede, il primo viene temporaneamente innalzato, così non resta bloccato da task di priorità intermedia (il fenomeno noto come priority inversion). Proprio per questo il sorgente di FreeRTOS precisa che i mutex non si possono usare nelle ISR. Nell’esempio completo il mutex è incapsulato in una funzione logf(): il testo viene preparato con vsnprintf() in un buffer locale fuori dalla sezione protetta, e il mutex viene tenuto solo per il tempo della stampa.
Esempio completo: produttore, consumatore e pulsante
Il progetto d’esempio mette insieme gli elementi visti finora. Tre task, una coda, un semaforo binario e due mutex si dividono il lavoro: taskSensore (priorità 2, core 1) legge il potenziometro ogni 100 ms con vTaskDelayUntil() e mette il campione in coda; taskElabora (priorità 1, core 1) riceve i campioni, ne calcola la media su 10 e regola la luminosità del LED in PWM; taskPulsante (priorità 3, core 0) attende il semaforo dato dall’interrupt del pulsante, filtra i rimbalzi e accende o spegne il LED. loop() ogni 2 s stampa l’occupazione della coda, i campioni persi e lo stack libero di ogni task. La funzione aggiornaLed() è chiamata da due task che girano su core diversi: un secondo mutex, mutexLed, impedisce che un duty calcolato con il vecchio stato del LED sovrascriva quello appena impostato dall’altro task.
Il circuito è identico a quello della guida introduttiva. Il LED (rosso, tensione diretta di circa 2 V) con 330 Ω assorbe circa 3,9 mA alla massima luminosità; il pulsante collega GPIO27 a massa e usa il pull-up interno; il potenziometro forma un partitore tra 3V3 e GND con il cursore su GPIO34, ingresso dell’ADC1, e il condensatore da 100 nF riduce il rumore della lettura. Lo schema seguente mostra come i task si distribuiscono sui due core e quali oggetti di FreeRTOS li collegano.
Lo sketch contiene due opzioni di compilazione. SORGENTE_TEST, normalmente 0, sostituisce pulsante e potenziometro con una sorgente interna deterministica: un timer hardware ogni 10 ms genera una “pressione” al secondo con due rimbalzi e un rilascio con un rimbalzo, e i campioni seguono un’onda triangolare tra 0 e 3000 mV. Serve per provare il programma senza circuito e per la simulazione, dove gli ingressi non sono disponibili. RITARDO_ELABORA_MS rallenta artificialmente il consumatore per osservare la coda che si riempie. Entrambe si impostano senza modificare il file, con una proprietà di compilazione di arduino-cli (vedi più avanti); la proprietà usata, compiler.cpp.extra_flags, è vuota nella configurazione del core, quindi aggiunge solo le due definizioni e non toglie nulla alla compilazione normale.
// FreeRTOS su ESP32: coda produttore/consumatore, semaforo da ISR, mutex per Serial
// Core arduino-esp32 3.x - ESP32 classico (DevKitC)
// LED su GPIO25 (PWM), pulsante su GPIO27 verso GND, potenziometro su GPIO34 (ADC1)
#include <stdarg.h>
#ifndef SORGENTE_TEST
#define SORGENTE_TEST 0 // 1 = pulsante e potenziometro simulati da un timer
#endif
#ifndef RITARDO_ELABORA_MS
#define RITARDO_ELABORA_MS 0 // > 100 per vedere la coda riempirsi
#endif
const int LED_PIN = 25;
const int BUTTON_PIN = 27;
const int POT_PIN = 34;
const uint32_t PERIODO_CAMPIONI_MS = 100;
const int LUNGHEZZA_CODA = 10;
struct Campione { // elemento della coda: copiato per valore
uint32_t n; // numero progressivo
uint32_t tick; // istante di acquisizione (tick = ms)
uint16_t mV; // tensione letta
};
QueueHandle_t codaCampioni;
SemaphoreHandle_t semPulsante; // semaforo binario: ISR -> taskPulsante
SemaphoreHandle_t mutexSerial; // mutex: un solo task alla volta su Serial
SemaphoreHandle_t mutexLed; // mutex: aggiornaLed() e' chiamata da due task
TaskHandle_t hSensore, hElabora, hPulsante;
volatile uint32_t eventiIsr = 0;
uint32_t campioniPersi = 0; // scritto solo da taskSensore
volatile bool ledAcceso = false;
volatile uint16_t ultimaMedia = 0;
// ---------- log thread-safe ----------
void logf(const char *fmt, ...) {
char buf[120];
va_list ap;
va_start(ap, fmt);
vsnprintf(buf, sizeof(buf), fmt, ap);
va_end(ap);
xSemaphoreTake(mutexSerial, portMAX_DELAY);
Serial.printf("[%6lu] c%d ", (unsigned long)millis(), xPortGetCoreID());
Serial.println(buf);
xSemaphoreGive(mutexSerial);
}
// ---------- interrupt del pulsante: lavoro minimo, poi sveglia il task ----------
void ARDUINO_ISR_ATTR isrPulsante() {
BaseType_t svegliaTask = pdFALSE;
eventiIsr = eventiIsr + 1; // (++ su volatile e' deprecato in C++20)
xSemaphoreGiveFromISR(semPulsante, &svegliaTask);
portYIELD_FROM_ISR(svegliaTask); // se il task svegliato ha priorita' maggiore
}
#if SORGENTE_TEST
// Sorgente interna deterministica: timer hardware ogni 10 ms.
// Ogni secondo simula una pressione con 2 rimbalzi e un rilascio con 1 rimbalzo.
hw_timer_t *timerTest = NULL;
volatile bool testPremuto = false;
void ARDUINO_ISR_ATTR isrTimerTest() {
static uint32_t k = 0;
uint32_t fase = k++ % 100;
if (fase <= 2) { testPremuto = true; isrPulsante(); } // 0, 10, 20 ms
if (fase == 40 || fase == 41) { testPremuto = false; isrPulsante(); }
}
uint16_t leggiMilliVolt(uint32_t n) { // onda triangolare 0..3000 mV
uint32_t p = n % 40;
return (p < 20 ? p : 40 - p) * 150;
}
bool pulsantePremuto() { return testPremuto; }
#else
uint16_t leggiMilliVolt(uint32_t n) { return analogReadMilliVolts(POT_PIN); }
bool pulsantePremuto() { return digitalRead(BUTTON_PIN) == LOW; }
#endif
void aggiornaLed() {
// luminosita' proporzionale alla media (0..3000 mV -> 0..1023), se acceso.
// Chiamata da taskElabora (core 1) e taskPulsante (core 0): il mutex impedisce
// che un duty calcolato con il vecchio stato sovrascriva quello nuovo.
xSemaphoreTake(mutexLed, portMAX_DELAY);
uint32_t duty = ledAcceso ? (uint32_t)ultimaMedia * 1023 / 3000 : 0;
ledcWrite(LED_PIN, duty > 1023 ? 1023 : duty);
xSemaphoreGive(mutexLed);
}
// ---------- produttore: un campione ogni 100 ms, periodo fisso ----------
void taskSensore(void *param) {
TickType_t ultimo = xTaskGetTickCount();
logf("taskSensore avviato");
for (uint32_t n = 0; ; n++) {
Campione c = { n, xTaskGetTickCount(), leggiMilliVolt(n) };
if (xQueueSend(codaCampioni, &c, 0) != pdPASS) { // non attende: coda piena
campioniPersi++;
}
vTaskDelayUntil(&ultimo, pdMS_TO_TICKS(PERIODO_CAMPIONI_MS));
}
}
// ---------- consumatore: media su 10 campioni ----------
void taskElabora(void *param) {
Campione c;
uint32_t somma = 0, primo = 0;
int k = 0;
logf("taskElabora avviato");
for (;;) {
if (xQueueReceive(codaCampioni, &c, pdMS_TO_TICKS(500)) != pdPASS) {
logf("Timeout: nessun campione da 500 ms");
continue;
}
if (k == 0) primo = c.n;
somma += c.mV;
if (++k == 10) {
ultimaMedia = somma / 10;
aggiornaLed();
logf("Media campioni %lu-%lu: %u mV", (unsigned long)primo,
(unsigned long)c.n, ultimaMedia);
somma = 0;
k = 0;
}
if (RITARDO_ELABORA_MS) vTaskDelay(pdMS_TO_TICKS(RITARDO_ELABORA_MS));
}
}
// ---------- pulsante: attende il semaforo, filtra i rimbalzi ----------
void taskPulsante(void *param) {
uint32_t pressioni = 0, ignorati = 0;
logf("taskPulsante avviato");
for (;;) {
xSemaphoreTake(semPulsante, portMAX_DELAY); // dorme fino all'interrupt
vTaskDelay(pdMS_TO_TICKS(30)); // lascia finire i rimbalzi
xSemaphoreTake(semPulsante, 0); // scarta i fronti arrivati nel frattempo
if (!pulsantePremuto()) { // rilascio o disturbo
ignorati++;
continue;
}
pressioni++;
ledAcceso = !ledAcceso;
aggiornaLed(); // l'ultima scrittura usa lo stato nuovo
logf("Pulsante n.%lu: LED %s (interrupt %lu, risvegli ignorati %lu)",
(unsigned long)pressioni, ledAcceso ? "ACCESO" : "SPENTO",
(unsigned long)eventiIsr, (unsigned long)ignorati);
}
}
void setup() {
Serial.begin(115200);
delay(100);
ledcAttach(LED_PIN, 5000, 10); // PWM 5 kHz, 10 bit
pinMode(BUTTON_PIN, INPUT_PULLUP);
codaCampioni = xQueueCreate(LUNGHEZZA_CODA, sizeof(Campione));
semPulsante = xSemaphoreCreateBinary();
mutexSerial = xSemaphoreCreateMutex();
mutexLed = xSemaphoreCreateMutex();
if (!codaCampioni || !semPulsante || !mutexSerial || !mutexLed) {
Serial.println("Memoria insufficiente per gli oggetti FreeRTOS");
while (true) delay(1000);
}
// funzione, nome, stack (byte), parametro, priorita', handle, core
xTaskCreatePinnedToCore(taskPulsante, "pulsante", 3072, NULL, 3, &hPulsante, 0);
xTaskCreatePinnedToCore(taskSensore, "sensore", 3072, NULL, 2, &hSensore, 1);
xTaskCreatePinnedToCore(taskElabora, "elabora", 3072, NULL, 1, &hElabora, 1);
#if SORGENTE_TEST
timerTest = timerBegin(1000000); // 1 MHz
timerAttachInterrupt(timerTest, isrTimerTest);
timerAlarm(timerTest, 10000, true, 0); // ogni 10 ms
logf("Sorgente di test attiva");
#else
attachInterrupt(digitalPinToInterrupt(BUTTON_PIN), isrPulsante, FALLING);
#endif
}
void loop() {
vTaskDelay(pdMS_TO_TICKS(2000));
logf("Coda %u/%d, persi %lu | stack libero: sensore %u, elabora %u, pulsante %u, loop %u",
(unsigned)uxQueueMessagesWaiting(codaCampioni), LUNGHEZZA_CODA,
(unsigned long)campioniPersi,
(unsigned)uxTaskGetStackHighWaterMark(hSensore),
(unsigned)uxTaskGetStackHighWaterMark(hElabora),
(unsigned)uxTaskGetStackHighWaterMark(hPulsante),
(unsigned)uxTaskGetStackHighWaterMark(NULL));
}
Il task del pulsante applica un filtro antirimbalzo in tre passi. Al primo interrupt il task si sveglia e attende 30 ms con vTaskDelay(), il tempo in cui i rimbalzi si esauriscono; poi esegue un xSemaphoreTake() con attesa nulla, che scarta il Give eventualmente arrivato nel frattempo; infine rilegge il pin. Se il pulsante risulta ancora premuto la pressione è valida, altrimenti si trattava del rilascio, che con l’interrupt sul fronte di discesa produce anch’esso fronti spuri, o di un disturbo. Per approfondire il fenomeno dei rimbalzi si veda la guida ai circuiti di debouncing.
Compilazione, simulazione e risultato
Per la scheda reale si compila normalmente, dall’IDE o da riga di comando. Per la simulazione in QEMU, che non supporta la modalità QIO della flash, si compila una seconda volta in modalità DIO a 40 MHz e si attiva la sorgente di test; il file .merged.bin prodotto contiene bootloader, tabella delle partizioni e applicazione.
# scheda reale (ESP32 Dev Module) arduino-cli compile --fqbn esp32:esp32:esp32 rtos_coda_semaforo # simulazione: flash DIO 40 MHz e sorgente di test interna arduino-cli compile --fqbn esp32:esp32:esp32:FlashMode=dio,FlashFreq=40 \ --build-property "compiler.cpp.extra_flags=-DSORGENTE_TEST=1" \ --output-dir buildsim rtos_coda_semaforo # esperimento con consumatore lento (150 ms per campione) --build-property "compiler.cpp.extra_flags=-DSORGENTE_TEST=1 -DRITARDO_ELABORA_MS=150"
Inizio del log seriale in QEMU (tra parentesi quadre millis(), poi il core che ha stampato la riga):
[ 919] c1 taskSensore avviato [ 923] c0 taskPulsante avviato [ 927] c1 taskElabora avviato [ 929] c1 Sorgente di test attiva [ 974] c0 Pulsante n.1: LED ACCESO (interrupt 3, risvegli ignorati 0) [ 1818] c1 Media campioni 0-9: 675 mV [ 1975] c0 Pulsante n.2: LED SPENTO (interrupt 8, risvegli ignorati 1) [ 2818] c1 Media campioni 10-19: 2175 mV [ 2930] c1 Coda 0/10, persi 0 | stack libero: sensore 1392, elabora 1404, pulsante 1268, loop 6480 [ 2980] c0 Pulsante n.3: LED ACCESO (interrupt 13, risvegli ignorati 2) [ 3821] c1 Media campioni 20-29: 2325 mV
Uno script di verifica confronta il log con i valori attesi e segnala PASS per ogni controllo. I task girano sui core previsti. Le medie coincidono con quelle calcolate dall’onda triangolare: per i campioni da 0 a 9 i valori sono 0, 150, …, 1350 mV, la cui media è 675 mV. I blocchi di dieci campioni sono consecutivi, quindi nessun dato è stato perso o duplicato. Per ogni secondo arrivano esattamente 5 interrupt (3 alla pressione e 2 al rilascio), ma il LED commuta una volta sola e il risveglio dovuto al rilascio viene ignorato. Il task del pulsante ha la priorità più alta: la sua riga compare circa 30 ms dopo il primo interrupt, cioè dopo il solo tempo del filtro, qualunque cosa stiano facendo gli altri task.
Con il consumatore rallentato a 150 ms per campione l’uscita dalla coda scende a 6,67 campioni al secondo contro i 10 in ingresso: la coda si riempie e, da quel momento, il produttore perde i campioni in eccesso senza bloccarsi. Il grafico confronta il log con il calcolo.
Esempio di calcolo: coda da 10 elementi, consumatore lento ingresso = 1 / 0,100 s = 10 campioni/s uscita = 1 / 0,150 s = 6,67 campioni/s accumulo = 10 - 6,67 = 3,33 campioni/s coda piena dopo 10 / 3,33 = 3 s poi persi = 3,33 campioni/s -> circa 6,7 ogni 2 s log QEMU: (7/10, 0) a 2 s, poi coda 10/10 e persi 4, 11, 17, 24
Una coda più lunga rimanda soltanto il momento in cui si riempie: se il consumatore è strutturalmente più lento, bisogna campionare meno spesso, accelerare l’elaborazione o decidere quali dati perdere (con xQueueOverwrite() su una coda da un elemento si conserva sempre l’ultimo valore).
Dimensionare lo stack con uxTaskGetStackHighWaterMark
Ogni task ha il suo stack, allocato nella RAM al momento della creazione: troppo piccolo provoca un crash, troppo grande spreca memoria. FreeRTOS riempie lo stack di un valore noto alla creazione del task e uxTaskGetStackHighWaterMark(handle) restituisce la quantità minima di stack rimasta libera da allora; con NULL si interroga il task corrente. Anche in questo caso ESP-IDF esprime il risultato in byte e non in word.
Esempio di calcolo: stack dei task (minimo su 15 esecuzioni in simulazione) task stack libero min. usato sensore 3072 B 1200 B 1872 B elabora 3072 B 1180 B 1892 B pulsante 3072 B 1236 B 1836 B loopTask 8192 B 6480 B 1712 B Regola pratica: tenere libero almeno il 25-30 % dopo aver esercitato tutti i percorsi del codice (errori, stampe, casi limite). Qui il margine è almeno il 38 % (1180 / 3072): 3072 B vanno bene, 2048 B no.
Il valore va letto dopo che il task ha percorso tutti i suoi rami, comprese le stampe di errore, che di solito sono le funzioni più “affamate”: printf() e vsnprintf() usano da sole parecchie centinaia di byte, e la versione con i numeri in virgola mobile ancora di più (nel primo esempio il task che stampa il riepilogo con %.1f ha usato più di 2 KB). Anche le variabili locali grandi, come il buffer di logf() o l’array dei periodi, finiscono nello stack. Se lo stack si esaurisce, il controllo canary attivo nel core ferma il programma con il messaggio ***ERROR*** A stack overflow in task sensore has been detected. seguito dal riavvio: è il segnale che lo stack di quel task va aumentato.
Il task watchdog: cosa lo fa scattare
Il task watchdog (TWDT) di ESP-IDF rileva i task che girano a lungo senza cedere la CPU. Nella configurazione del core Arduino è attivo con un timeout di 5 s, sorveglia il task idle del core 0 e, allo scadere, provoca un panic e il riavvio della scheda. Il meccanismo è indiretto: il task idle “accarezza” il watchdog quando gira, e gira solo se nessun altro task è pronto su quel core. Un task con priorità 1 o superiore che esegue un ciclo di calcolo senza mai bloccarsi affama quindi il task idle, e dopo 5 s il watchdog interviene.
// Task watchdog su ESP32: un task che non cede mai la CPU sul core 0
// Core arduino-esp32 3.x - ESP32 classico (DevKitC)
#include <esp_system.h>
#ifndef CEDI_CPU
#define CEDI_CPU 0 // 1 = il task chiama vTaskDelay(1) a ogni giro
#endif
void taskCalcolo(void *param) {
uint32_t giri = 0;
for (;;) {
for (uint32_t i = 0; i < 100000; i++) {
__asm__ __volatile__("nop"); // calcolo fittizio: mai una funzione bloccante
}
giri++;
if (giri % 100 == 0) {
Serial.printf("taskCalcolo: %lu giri, t = %lu ms\n",
(unsigned long)giri, (unsigned long)millis());
}
#if CEDI_CPU
vTaskDelay(1); // 1 tick: anche l'IDLE task del core 0 puo' girare
#endif
}
}
const char *nomeReset(esp_reset_reason_t r) {
switch (r) {
case ESP_RST_POWERON: return "accensione";
case ESP_RST_SW: return "esp_restart()";
case ESP_RST_PANIC: return "panic";
case ESP_RST_INT_WDT: return "interrupt watchdog";
case ESP_RST_TASK_WDT: return "task watchdog";
case ESP_RST_BROWNOUT: return "brownout";
default: return "altro";
}
}
void setup() {
Serial.begin(115200);
delay(100);
esp_reset_reason_t r = esp_reset_reason();
Serial.printf("Avvio, ultimo reset: %d (%s)\n", (int)r, nomeReset(r));
xTaskCreatePinnedToCore(taskCalcolo, "calcolo", 3072, NULL, 1, NULL, 0);
}
void loop() {
delay(1000);
Serial.printf("loop() attivo sul core %d, t = %lu ms\n",
xPortGetCoreID(), (unsigned long)millis());
}
Su una scheda reale questo sketch dovrebbe produrre, circa 5 s dopo l’avvio, messaggi come i seguenti (testo e ordine sono quelli del sorgente task_wdt.c di ESP-IDF 5.5; i tempi tra parentesi variano e sul core 1 compare il task in esecuzione in quel momento, di solito IDLE1 perché loop() passa quasi tutto il tempo in delay()), seguiti dal dump del panic e dal riavvio. Al successivo avvio la ROM stampa rst:0xc (SW_CPU_RESET), perché il riavvio dopo il panic è un reset software, ma esp_reset_reason() restituisce ESP_RST_TASK_WDT (valore 6): prima di fermarsi, il gestore del watchdog registra la causa in un registro che sopravvive al reset.
E (5xxx) task_wdt: Task watchdog got triggered. The following tasks/users
did not reset the watchdog in time:
E (5xxx) task_wdt: - IDLE0 (CPU 0)
E (5xxx) task_wdt: Tasks currently running:
E (5xxx) task_wdt: CPU 0: calcolo
E (5xxx) task_wdt: CPU 1: IDLE1
E (5xxx) task_wdt: Aborting.
E (5xxx) task_wdt: Print CPU 0 (current core) backtrace
...
Questa è l’unica parte della guida che non si può riprodurre in simulazione: per far avviare il firmware, l’emulatore disattiva il watchdog dei timer hardware, e quindi il TWDT non scatta. In QEMU lo sketch mostra comunque il comportamento dei due core: taskCalcolo occupa il core 0 senza pause, mentre loop() continua a stampare dal core 1 ogni secondo, perché ogni core ha il proprio scheduler. La prova del reset va fatta al banco con la checklist allegata.
Le soluzioni corrette, in ordine di preferenza, sono: strutturare il task in modo che si blocchi (su una coda, un semaforo o un vTaskDelay()); spezzare un calcolo lungo inserendo ogni tanto vTaskDelay(1), come nella variante CEDI_CPU=1; per un task che deve restare attivo, iscriverlo esplicitamente al watchdog con esp_task_wdt_add(NULL) e chiamare esp_task_wdt_reset() a ogni ciclo. taskYIELD() non basta, perché cede la CPU solo a task di pari priorità e non al task idle, che ha priorità 0. Il task idle del core 1 non è sorvegliato nella configurazione del core Arduino, quindi un loop() senza pause non fa scattare il watchdog; con enableLoopWDT() si può iscrivere anche loopTask. Disattivare il watchdog con disableCore0WDT() nasconde il problema e lascia senza CPU il task idle, che tra l’altro libera la memoria dei task cancellati.
Errori comuni
Stack espresso in word. Copiare un xTaskCreate(..., 1024, ...) da un esempio per STM32 assegna 1024 byte, non 4096. Il sintomo è un crash con il messaggio di stack overflow o, peggio, un riavvio apparentemente casuale. Si parte da 3–4 KB e si regola con uxTaskGetStackHighWaterMark().
Funzioni bloccanti o Serial nelle ISR. Serial.print(), delay(), xQueueSend() senza FromISR o un mutex dentro una ISR provocano un crash o un blocco. La ISR deve solo registrare l’evento e svegliare un task.
Variabili condivise senza protezione. Un contatore incrementato da due task può perdere incrementi; una struttura scritta da un task e letta da un altro può risultare incoerente. Si usano code, mutex o, per interi a 32 bit scritti da un solo task, almeno volatile. Nel C++ del core 3.x l’operatore ++ su una variabile volatile genera un avviso di deprecazione: nell’esempio si scrive x = x + 1.
Task che termina con return. Una funzione di task che esce dal ciclo e ritorna provoca un errore del kernel. Il task deve restare nel ciclo infinito o chiamare vTaskDelete(NULL).
Priorità troppo alte. Assegnare 20 o più a un task applicativo lo mette al di sopra di molti task di sistema, per esempio dello stack TCP/IP (priorità 18 nel core 3.3.12), e a ridosso del task del Wi-Fi (23): se non si blocca spesso, provoca ritardi di rete e possibili disconnessioni. Per i task dello sketch bastano valori bassi, da 1 a 5, scelti in base all’urgenza.
Attese attive. Un while (!flag) {} per aspettare un evento consuma il 100 % del core e affama i task a priorità più bassa. Al suo posto si usano un semaforo, una coda o una notifica.
Checklist per un progetto multi-task su ESP32 1. Un task per ogni attività con tempi propri (campionamento, rete, interfaccia). 2. Stack in byte; misurare con uxTaskGetStackHighWaterMark e tenere il 25-30 % libero. 3. Priorità basse (1-5); la più alta all'attività con la scadenza più stretta. 4. Task periodici con vTaskDelayUntil; nessuna attesa attiva. 5. Dati tra task con code (copia per valore); decidere se il produttore attende o scarta. 6. ISR brevi, con ARDUINO_ISR_ATTR, solo funzioni FromISR + portYIELD_FROM_ISR. 7. Risorse condivise (Serial, I2C, SPI) protette da un mutex, mai usato nelle ISR. 8. Nessun task deve impedire a IDLE0 di girare per 5 s (task watchdog). 9. Stessa priorità -> stesso core; lasciare il core 0 al Wi-Fi quando possibile. 10. Provare i casi limite: coda piena, timeout, rimbalzi, perdita di eventi.
Fonti e verifiche
Il codice di questo articolo è stato compilato con arduino-cli 1.3.1 e il core esp32:esp32 3.3.12 (ESP-IDF 5.5) ed eseguito in simulazione (QEMU di Espressif, ESP32 a due core); la prova su hardware reale va eseguita con la checklist fornita. I parametri del sistema (tick, stack e priorità di loopTask, configurazione del watchdog) sono stati letti nei sorgenti e nella configurazione del core installato.
- Espressif, ESP-IDF: FreeRTOS (IDF) (stack in byte, affinità ai core, scheduling,
xTaskDelayUntil) e FreeRTOS Overview (task di sistema) - Espressif, ESP-IDF: Watchdogs (task watchdog e interrupt watchdog)
- FreeRTOS, xSemaphoreGiveFromISR e i commenti dei file
queue.hesemphr.hdi FreeRTOS-Kernel 10.5.1 inclusi nel core - Espressif, Arduino-ESP32: API ADC (
analogReadMilliVolts())
Articoli collegati
- ESP32: guida introduttiva, scelta della scheda e primo progetto Wi-Fi con Arduino IDE
- ESP32 e MQTT con Home Assistant
- ESP-NOW tra due ESP32 senza router
- Circuiti di debouncing: installazione, funzionamento e dimensionamento
- Semplice orologio con la funzione millis()
- Come gestire ingressi analogici e uscite PWM con Arduino









