ArduinoEmbedded & IoT

ESP-NOW tra due ESP32 senza router: guida con Arduino core 3.x

Caratteristiche di ESP-NOW, MAC e peer, callback del core 3.3, pacchetti con numero di sequenza e CRC, invio con conferma, vincolo del canale con il Wi-Fi, portata e consumi.

Non sempre c’è un router a portata di antenna: un telecomando per il cancello, un sensore in fondo al giardino o due schede che devono scambiarsi un comando in pochi millisecondi non hanno bisogno di indirizzi IP, server o connessioni da mantenere. ESP-NOW è il protocollo di Espressif che permette a due o più ESP32 di comunicare direttamente, usando la stessa radio del Wi-Fi ma senza access point e senza lo stack TCP/IP: un pacchetto parte appena chiamata la funzione di invio, e il trasmettitore sa subito se il destinatario lo ha ricevuto.

Questa guida, che prosegue la guida introduttiva all’ESP32, descrive le caratteristiche di ESP-NOW verificate sulla documentazione di ESP-IDF, le API disponibili nel core Arduino 3.x e il cambiamento delle funzioni di callback che rende incompatibili molti esempi in rete. Si costruisce poi un progetto completo con due schede: un trasmettitore con pulsante e potenziometro e un ricevitore che regola un LED in PWM e stampa RSSI e statistiche di collegamento. I pacchetti hanno un formato definito, con numero di sequenza e CRC, verificato con un test su PC; si discutono infine la coesistenza con il Wi-Fi, il vincolo del canale, la portata e i consumi.

Che cos’è ESP-NOW

ESP-NOW trasmette i dati dentro frame di gestione 802.11 di tipo “action”, specifici del produttore (categoria 127, con l’identificativo OUI di Espressif). Non c’è associazione a una rete, autenticazione Wi-Fi né assegnazione di indirizzi: ogni scheda è identificata dal suo indirizzo MAC, e per inviare dati a un’altra basta averla registrata come peer. Il frame unicast viene confermato dal destinatario con un ACK a livello MAC, gestito dall’hardware, e il driver ritrasmette automaticamente se la conferma non arriva. La velocità predefinita è di 1 Mbps, la più robusta tra quelle del 802.11b.

Caratteristica Valore (documentazione ESP-IDF 5.5)
Dati per pacchetto 250 byte con ESP-NOW v1.0 (ESP_NOW_MAX_DATA_LEN); 1470 byte con v2.0
Compatibilità un dispositivo v1.0 riceve da un v2.0 solo pacchetti fino a 250 byte
Peer registrabili al massimo 20, di cui cifrati al massimo 17 (7 nella configurazione predefinita, anche nel core Arduino: opzione CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM; la costante ESP_NOW_MAX_ENCRYPT_PEER_NUM dell’header vale ancora 6 e non va presa come limite)
Cifratura CCMP; chiave primaria PMK e chiave locale LMK da 16 byte per peer; niente cifratura per broadcast e multicast
Canale da 0 a 14; 0 = canale corrente, altrimenti deve coincidere con quello della radio
Interfaccia Station o SoftAP
Velocità predefinita 1 Mbps (modificabile per peer con esp_now_set_peer_rate_config())
Callback eseguite nel task del Wi-Fi ad alta priorità: vanno tenute brevi

Il numero di versione dipende dal firmware: le versioni recenti di ESP-IDF supportano ESP-NOW v2.0 con pacchetti più lunghi, ma un pacchetto oltre 250 byte non arriva a una scheda con firmware v1.0, per esempio compilato con un core Arduino più vecchio. Gli sketch di questa guida stampano la versione all’avvio con esp_now_get_version() e usano un pacchetto di 14 byte, valido in ogni caso. ESP-NOW è adatto a messaggi brevi e frequenti; per trasferire file o flussi continui di dati conviene il Wi-Fi tradizionale.

Leggere il MAC e scegliere l’API

Il trasmettitore deve conoscere il MAC del ricevitore. Il modo più semplice è leggerlo dal ricevitore stesso: entrambi gli sketch lo stampano all’avvio con WiFi.macAddress(), che restituisce il MAC dell’interfaccia Station dopo che la radio è stata avviata in modalità WIFI_STA. È importante usare il MAC dell’interfaccia con cui si registra il peer: quello della SoftAP è diverso (sull’ESP32 differisce nell’ultimo byte). Il MAC stampato, per esempio 24:6F:28:12:34:56, va copiato nell’array MAC_RICEVITORE del trasmettitore come { 0x24, 0x6F, 0x28, 0x12, 0x34, 0x56 }.

Nel core arduino-esp32 3.x ci sono due modi di usare ESP-NOW. La libreria ESP_NOW, inclusa nel core, offre le classi C++ ESP_NOW_Class (oggetto globale ESP_NOW) e ESP_NOW_Peer, da cui si deriva una classe con i metodi onReceive() e onSent(); gli esempi del core mostrano broadcast, reti di più nodi e una porta seriale virtuale. In alternativa si chiamano direttamente le API di ESP-IDF: esp_now_init(), esp_now_add_peer(), esp_now_send() e la registrazione delle callback. In questa guida si usano le API di ESP-IDF: sono documentate in dettaglio, sono le stesse di un progetto ESP-IDF e mostrano esattamente cosa succede.

Le callback sono cambiate

Molti sketch ESP-NOW che si trovano in rete non compilano con il core attuale perché la firma delle callback è cambiata due volte. Con ESP-IDF 5.0, e quindi a partire dal core 3.0 (basato su ESP-IDF 5.1), la callback di ricezione riceve una struttura esp_now_recv_info_t, con indirizzo sorgente, destinazione e informazioni radio come l’RSSI, al posto del solo MAC. Con ESP-IDF 5.5 (core 3.3) è cambiata anche la callback di invio, che riceve una struttura esp_now_send_info_t invece del MAC del destinatario.

Core Arduino (ESP-IDF) Callback di invio Callback di ricezione
2.x (4.4) (const uint8_t *mac, esp_now_send_status_t) (const uint8_t *mac, const uint8_t *dati, int len)
3.0–3.2 (5.1–5.4) (const uint8_t *mac, esp_now_send_status_t) (const esp_now_recv_info_t *info, const uint8_t *dati, int len)
3.3.x (5.5) (const esp_now_send_info_t *info, esp_now_send_status_t) (const esp_now_recv_info_t *info, const uint8_t *dati, int len)

Compilando con il core 3.3.12 uno sketch scritto per il 2.x si ottengono errori di conversione come questi:

error: invalid conversion from 'void (*)(const uint8_t*, esp_now_send_status_t)'
       to 'esp_now_send_cb_t' {aka 'void (*)(const wifi_tx_info_t*, esp_now_send_status_t)'}
error: invalid conversion from 'void (*)(const uint8_t*, const uint8_t*, int)'
       to 'esp_now_recv_cb_t' {aka 'void (*)(const esp_now_recv_info*, const unsigned char*, int)'}

Il trasmettitore di questa guida risolve il problema con il controllo #if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 5, 0), che sceglie la firma giusta in fase di compilazione: è la stessa tecnica usata dalla libreria ESP_NOW del core. Il MAC del destinatario, se serve, si trova nel campo des_addr della nuova struttura.

Il progetto: trasmettitore e ricevitore

Il trasmettitore legge un pulsante su GPIO27 e un potenziometro su GPIO34 e invia un pacchetto ogni 100 ms, oppure subito quando cambia lo stato del pulsante. Il ricevitore regola la luminosità di un LED su GPIO25 in base alla tensione del potenziometro, lo accende o lo spegne a ogni pressione del pulsante, lo spegne se per un secondo non arrivano pacchetti e ogni 2 s stampa ricevuti, persi, duplicati, scartati, RSSI medio e minimo. I collegamenti sono quelli della guida introduttiva, divisi tra le due schede.

Schema a blocchi di trasmettitore e ricevitore ESP-NOW e struttura del pacchetto da 14 byte con magic, versione, numero di sequenza, millivolt, pulsante, pressioni, uptime e CRC

Schema di collegamento: ESP32 trasmettitore con pulsante su GPIO27 e potenziometro da 10 kilohm con condensatore da 100 nF su GPIO34; ESP32 ricevitore con LED e resistenza da 330 ohm su GPIO25

Una struttura dati condivisa

Le due schede devono interpretare i byte allo stesso modo. Il formato è definito in un file pacchetto.h, identico nelle cartelle dei due sketch, che contiene la struttura, il calcolo del CRC, la validazione e le statistiche. La struttura è dichiarata __attribute__((packed)): senza questo attributo il compilatore potrebbe inserire byte di riempimento tra i campi per allinearli, e la dimensione dipenderebbe dal compilatore. Un static_assert ferma la compilazione se la dimensione non è di 14 byte. I campi a più byte viaggiano nell’ordine della memoria dell’ESP32, cioè little-endian; due ESP32 e un PC x86 usano lo stesso ordine, ma per comunicare con un microcontrollore diverso andrebbe fissato esplicitamente.

// pacchetto.h - formato dei dati ESP-NOW condiviso da trasmettitore e ricevitore.
// Lo stesso file va copiato in entrambe le cartelle degli sketch.
// Non usa funzioni Arduino: si compila anche su PC per i test.
#pragma once
#include <stdint.h>
#include <stddef.h>
#include <string.h>

const uint8_t PKT_MAGIC = 0xA5;     // riconosce i nostri pacchetti
const uint8_t PKT_VERSIONE = 1;     // da incrementare se cambia la struttura

struct __attribute__((packed)) Pacchetto {
  uint8_t magic;        // PKT_MAGIC
  uint8_t versione;     // PKT_VERSIONE
  uint16_t seq;         // numero di sequenza, riparte da 0 dopo 65535
  uint16_t mV;          // tensione del potenziometro in millivolt
  uint8_t pulsante;     // 1 = premuto in questo istante
  uint8_t pressioni;    // pressioni contate dal trasmettitore (modulo 256)
  uint32_t uptime_ms;   // millis() del trasmettitore: rivela i riavvii
  uint16_t crc;         // CRC-16/CCITT-FALSE di tutti i byte precedenti
};
static_assert(sizeof(Pacchetto) == 14, "Pacchetto deve occupare 14 byte");

// CRC-16/CCITT-FALSE: polinomio 0x1021, valore iniziale 0xFFFF
inline uint16_t crc16(const uint8_t *d, size_t n) {
  uint16_t crc = 0xFFFF;
  while (n--) {
    crc ^= (uint16_t)(*d++) << 8;
    for (int i = 0; i < 8; i++)
      crc = (crc & 0x8000) ? (uint16_t)((crc << 1) ^ 0x1021) : (uint16_t)(crc << 1);
  }
  return crc;
}

inline void preparaPacchetto(Pacchetto &p, uint16_t seq, uint16_t mV, bool pulsante,
                             uint8_t pressioni, uint32_t uptime_ms) {
  p.magic = PKT_MAGIC;
  p.versione = PKT_VERSIONE;
  p.seq = seq;
  p.mV = mV;
  p.pulsante = pulsante ? 1 : 0;
  p.pressioni = pressioni;
  p.uptime_ms = uptime_ms;
  p.crc = crc16((const uint8_t *)&p, offsetof(Pacchetto, crc));
}

enum EsitoPacchetto { PKT_OK, PKT_LUNGHEZZA, PKT_ESTRANEO, PKT_VERSIONE_ERR, PKT_CRC_ERR };

// Controlla un buffer ricevuto e, se valido, lo copia in out
inline EsitoPacchetto validaPacchetto(const uint8_t *dati, int len, Pacchetto &out) {
  if (len != (int)sizeof(Pacchetto)) return PKT_LUNGHEZZA;
  memcpy(&out, dati, sizeof(Pacchetto));           // copia: nessun problema di allineamento
  if (out.magic != PKT_MAGIC) return PKT_ESTRANEO;
  if (out.versione != PKT_VERSIONE) return PKT_VERSIONE_ERR;
  if (crc16(dati, offsetof(Pacchetto, crc)) != out.crc) return PKT_CRC_ERR;
  return PKT_OK;
}

// Statistiche di collegamento dai numeri di sequenza
struct Statistiche {
  uint32_t ricevuti = 0, persi = 0, duplicati = 0, riavvii = 0;
  uint16_t ultimoSeq = 0;
  uint32_t ultimoUptime = 0;
  bool primo = true;

  // Restituisce false per un duplicato o un pacchetto vecchio fuori ordine: va ignorato
  bool aggiorna(uint16_t seq, uint32_t uptime_ms) {
    ricevuti++;
    // Trasmettitore ripartito: il suo tempo torna indietro di oltre 1 s (un duplicato o
    // un pacchetto fuori ordine e' piu' vecchio al massimo di qualche centinaio di ms)
    if (!primo && uptime_ms + 1000 < ultimoUptime) {
      riavvii++;
      primo = true;
    }
    if (!primo) {
      uint16_t salto = (uint16_t)(seq - ultimoSeq);  // aritmetica modulo 65536
      if (salto == 0) { duplicati++; return false; }
      if (salto < 32768) persi += salto - 1;        // pacchetti mancanti in mezzo
      else { duplicati++; return false; }           // pacchetto vecchio o fuori ordine
    }
    primo = false;
    ultimoSeq = seq;
    ultimoUptime = uptime_ms;
    return true;
  }
};

Il numero di sequenza permette al ricevitore di contare i pacchetti persi: se dopo il 41 arriva il 44, ne mancano due. Il calcolo usa l’aritmetica a 16 bit senza segno, quindi funziona anche quando il contatore riparte da 0 dopo 65535; un salto “all’indietro” indica un pacchetto vecchio o duplicato, e in quel caso aggiorna() restituisce false: il ricevitore lo conta e lo scarta senza elaborarlo, altrimenti un pacchetto arrivato fuori ordine con un contatore delle pressioni già superato invertirebbe il LED. Il campo uptime_ms riconosce il riavvio del trasmettitore: se il tempo torna indietro di oltre un secondo (un duplicato o un pacchetto fuori ordine è più vecchio al massimo di qualche centinaio di millisecondi), la sequenza riparte senza contare perdite fittizie.

Il CRC-16 merita una precisazione onesta. Ogni frame 802.11 ha già un controllo CRC a 32 bit (FCS) verificato dall’hardware, e un frame corrotto viene scartato prima di arrivare allo sketch. Il CRC applicativo serve soprattutto a riconoscere pacchetti con un formato diverso, per esempio inviati da un’altra versione del firmware o da un altro progetto sullo stesso canale, insieme ai campi magic e versione. Diventa indispensabile se lo stesso pacchetto viene poi inoltrato su una seriale o salvato in memoria.

Esempio di calcolo: verifica del formato (test su PC, test_pacchetto.cpp)

  CRC-16/CCITT-FALSE("123456789") = 0x29B1   (valore di riferimento: OK)
  Pacchetto(seq 0x1234, 1650 mV, premuto, 7 pressioni, 123456 ms):
    A5 01 34 12 72 06 01 07 40 E2 01 00 20 2C
    1650 = 0x0672 -> byte 72 06;  123456 = 0x0001E240 -> byte 40 E2 01 00
  Errori su un solo bit:      112/112 rilevati
  Errori casuali su 2 byte:   0 non rilevati su 100000 prove
  Sequenza 65530, 65531, 65533, 65533, 65535, 0, 1, 5:
    ricevuti 8, persi 5 (65532, 65534, 2, 3, 4), duplicati 1 (scartato)
  Seq 10, 11, 10 (fuori ordine), 12 con pressioni 3, 4, 3, 4:
    il pacchetto vecchio è scartato, il LED si inverte una volta sola
  Canale simulato con 10 % di perdite su 20000 pacchetti: 1969 persi stimati = reali

Il trasmettitore

// ESP-NOW trasmettitore: pulsante su GPIO27 e potenziometro su GPIO34
// Core arduino-esp32 3.x (ESP-IDF 5.x) - ESP32 classico (DevKitC)

#include <WiFi.h>
#include <esp_now.h>
#include <esp_idf_version.h>
#include "pacchetto.h"

// MAC del ricevitore (letto dal suo monitor seriale all'avvio): DA SOSTITUIRE
uint8_t MAC_RICEVITORE[6] = { 0x24, 0x6F, 0x28, 0x00, 0x00, 0x00 };
const uint8_t CANALE = 1;               // stesso canale sul ricevitore
const int BUTTON_PIN = 27;              // verso GND, pull-up interno
const int POT_PIN = 34;                 // ADC1
const uint32_t PERIODO_MS = 100;        // invio periodico (10 pacchetti/s)

volatile bool invioInCorso = false;
volatile uint32_t inviOk = 0, inviFalliti = 0;
uint16_t seq = 0;
uint8_t pressioni = 0;

// Callback di invio: la firma dipende dalla versione di ESP-IDF del core
#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 5, 0)
void suInviato(const esp_now_send_info_t *info, esp_now_send_status_t stato) {   // core 3.3.x
#else
void suInviato(const uint8_t *mac, esp_now_send_status_t stato) {                // core 2.x - 3.2.x
#endif
  // gira nel task Wi-Fi: solo operazioni brevi
  if (stato == ESP_NOW_SEND_SUCCESS) inviOk = inviOk + 1;
  else inviFalliti = inviFalliti + 1;
  invioInCorso = false;
}

bool leggiPulsante() {                  // pulsante con filtro antirimbalzo da 30 ms
  static bool stabile = false, ultimo = false;
  static uint32_t tCambio = 0;
  bool letto = digitalRead(BUTTON_PIN) == LOW;
  if (letto != ultimo) { ultimo = letto; tCambio = millis(); }
  if (millis() - tCambio >= 30 && stabile != letto) {
    stabile = letto;
    if (stabile) pressioni++;           // conta solo le pressioni
  }
  return stabile;
}

void invia(bool pulsante) {
  if (invioInCorso) return;             // attende la conferma del pacchetto precedente
  Pacchetto p;
  preparaPacchetto(p, seq, analogReadMilliVolts(POT_PIN), pulsante, pressioni, millis());
  invioInCorso = true;
  esp_err_t e = esp_now_send(MAC_RICEVITORE, (const uint8_t *)&p, sizeof(p));
  if (e != ESP_OK) {
    invioInCorso = false;
    inviFalliti = inviFalliti + 1;
    Serial.printf("esp_now_send: errore %s\n", esp_err_to_name(e));
  }
  seq++;
}

void setup() {
  Serial.begin(115200);
  pinMode(BUTTON_PIN, INPUT_PULLUP);
  analogSetPinAttenuation(POT_PIN, ADC_11db);

  WiFi.mode(WIFI_STA);                  // la radio deve essere avviata prima di ESP-NOW
  WiFi.setChannel(CANALE);
  while (!WiFi.STA.started()) delay(10);
  Serial.printf("\nTrasmettitore, MAC %s, canale %u\n", WiFi.macAddress().c_str(), CANALE);

  if (esp_now_init() != ESP_OK) {
    Serial.println("esp_now_init fallita");
    while (true) delay(1000);
  }
  esp_now_register_send_cb(suInviato);
  uint32_t versione = 0;
  esp_now_get_version(&versione);       // 1 = v1.0 (max 250 byte), 2 = v2.0
  Serial.printf("ESP-NOW versione %lu\n", (unsigned long)versione);

  esp_now_peer_info_t peer = {};
  memcpy(peer.peer_addr, MAC_RICEVITORE, 6);
  peer.channel = CANALE;                // 0 = canale corrente
  peer.ifidx = WIFI_IF_STA;
  peer.encrypt = false;
  if (esp_now_add_peer(&peer) != ESP_OK) {
    Serial.println("esp_now_add_peer fallita");
    while (true) delay(1000);
  }
  Serial.printf("Pacchetto da %u byte\n", (unsigned)sizeof(Pacchetto));
}

void loop() {
  static uint32_t tInvio = 0, tStat = 0;
  static bool pulsantePrec = false;
  static uint8_t pressioniPrec = 0;
  bool pulsante = leggiPulsante();

  // invio periodico, oppure subito quando cambia il pulsante
  if (millis() - tInvio >= PERIODO_MS || pulsante != pulsantePrec || pressioni != pressioniPrec) {
    invia(pulsante);
    tInvio = millis();
    pulsantePrec = pulsante;
    pressioniPrec = pressioni;
  }
  if (millis() - tStat >= 5000) {
    tStat = millis();
    uint32_t ok = inviOk, ko = inviFalliti;
    Serial.printf("Inviati: %lu confermati, %lu falliti (%.1f %% ok), pressioni %u\n",
                  (unsigned long)ok, (unsigned long)ko,
                  ok + ko ? 100.0 * ok / (ok + ko) : 0.0, pressioni);
  }
  delay(2);
}

L’ordine delle operazioni in setup() segue la documentazione: prima si avvia la radio in modalità Station e si imposta il canale, poi si inizializza ESP-NOW, si registra la callback e infine si aggiunge il peer con il suo MAC, il canale e l’interfaccia. esp_now_send() non attende la trasmissione: mette il pacchetto in coda e ritorna subito. L’esito arriva più tardi nella callback suInviato(), eseguita nel task del Wi-Fi. La documentazione avverte che inviare pacchetti a intervalli troppo brevi può alterare l’ordine delle callback e consiglia di inviare il successivo dopo la conferma del precedente: per questo la variabile invioInCorso blocca un nuovo invio finché la callback non è arrivata.

Il pulsante ha un filtro antirimbalzo software di 30 ms e il trasmettitore non invia l’evento “pressione”, ma il contatore delle pressioni. È una scelta deliberata: se un pacchetto va perso, il successivo porta comunque il contatore aggiornato e il ricevitore non perde il comando. Un messaggio “premuto ora” perso, invece, sarebbe perso per sempre.

Il ricevitore

// ESP-NOW ricevitore: LED in PWM su GPIO25, statistiche e RSSI sul monitor seriale
// Core arduino-esp32 3.x (ESP-IDF 5.x) - ESP32 classico (DevKitC)

#include <WiFi.h>
#include <esp_now.h>
#include "pacchetto.h"

const uint8_t CANALE = 1;               // stesso canale del trasmettitore
const int LED_PIN = 25;
const uint32_t TIMEOUT_MS = 1000;       // senza pacchetti per 1 s: LED spento

struct Ricevuto {                       // elemento della coda callback -> loop()
  Pacchetto p;
  int8_t rssi;
};

QueueHandle_t coda;
volatile uint32_t scartati = 0;         // pacchetti non validi (contati nella callback)
Statistiche collegamento;

// Callback di ricezione (firma ESP-IDF 5.x, core 3.x): gira nel task Wi-Fi
void suRicevuto(const esp_now_recv_info_t *info, const uint8_t *dati, int len) {
  Ricevuto r;
  if (validaPacchetto(dati, len, r.p) != PKT_OK) {
    scartati = scartati + 1;
    return;
  }
  r.rssi = info->rx_ctrl->rssi;         // dBm del pacchetto appena ricevuto
  xQueueSend(coda, &r, 0);              // mai bloccare il task Wi-Fi
}

void setup() {
  Serial.begin(115200);
  ledcAttach(LED_PIN, 5000, 12);        // PWM 5 kHz, 12 bit
  coda = xQueueCreate(16, sizeof(Ricevuto));

  WiFi.mode(WIFI_STA);
  WiFi.setChannel(CANALE);
  while (!WiFi.STA.started()) delay(10);
  Serial.printf("\nRicevitore, MAC %s, canale %u\n", WiFi.macAddress().c_str(), CANALE);

  if (esp_now_init() != ESP_OK) {
    Serial.println("esp_now_init fallita");
    while (true) delay(1000);
  }
  esp_now_register_recv_cb(suRicevuto);
  uint32_t versione = 0;
  esp_now_get_version(&versione);       // 1 = v1.0 (max 250 byte), 2 = v2.0
  Serial.printf("ESP-NOW versione %lu\n", (unsigned long)versione);
}

void loop() {
  static uint32_t tUltimo = 0, tStat = 0;
  static bool abilitato = true, collegato = false;
  static uint8_t pressioniPrec = 0;
  static uint16_t mV = 0;
  static int32_t sommaRssi = 0;
  static int8_t rssiMin = 0;
  static uint32_t nRssi = 0;
  Ricevuto r;

  while (xQueueReceive(coda, &r, 0) == pdPASS) {
    if (!collegamento.aggiorna(r.p.seq, r.p.uptime_ms)) continue;   // duplicato o vecchio: ignorato
    if (!collegato) {                   // primo pacchetto: allinea il contatore
      collegato = true;
      pressioniPrec = r.p.pressioni;
      Serial.println("Collegamento attivo");
    } else if (r.p.pressioni != pressioniPrec) {
      pressioniPrec = r.p.pressioni;   // ogni nuova pressione inverte lo stato
      abilitato = !abilitato;
    }
    mV = r.p.mV;
    sommaRssi += r.rssi;
    if (nRssi == 0 || r.rssi < rssiMin) rssiMin = r.rssi;
    nRssi++;
    tUltimo = millis();
    uint32_t duty = abilitato ? (uint32_t)mV * 4095 / 3000 : 0;
    ledcWrite(LED_PIN, duty > 4095 ? 4095 : duty);
  }

  if (collegato && millis() - tUltimo > TIMEOUT_MS) {   // failsafe
    collegato = false;
    ledcWrite(LED_PIN, 0);
    Serial.println("Collegamento perso: LED spento");
  }

  if (millis() - tStat >= 2000) {
    tStat = millis();
    uint32_t tot = collegamento.ricevuti + collegamento.persi;
    Serial.printf("Ricevuti %lu, persi %lu (%.1f %%), duplicati %lu, scartati %lu, riavvii TX %lu | "
                  "RSSI medio %d dBm, min %d dBm | %u mV, LED %s\n",
                  (unsigned long)collegamento.ricevuti, (unsigned long)collegamento.persi,
                  tot ? 100.0 * collegamento.persi / tot : 0.0, (unsigned long)collegamento.duplicati,
                  (unsigned long)scartati, (unsigned long)collegamento.riavvii,
                  nRssi ? (int)(sommaRssi / (int32_t)nRssi) : 0, rssiMin, mV,
                  abilitato ? "abilitato" : "spento");
    sommaRssi = 0;
    nRssi = 0;
  }
  delay(2);
}

La callback di ricezione gira nel task del Wi-Fi, ad alta priorità: se si attardasse in stampe o calcoli rallenterebbe tutta la radio. Per questo fa solo tre cose: valida il pacchetto, legge l’RSSI dal campo rx_ctrl della struttura esp_now_recv_info_t e copia il risultato in una coda FreeRTOS senza attendere. Tutto il resto, cioè statistiche, LED e stampe, avviene nel loop(). È lo schema produttore-consumatore descritto nella guida a FreeRTOS su ESP32, dove la coda separa un contesto che non deve bloccarsi da uno che può prendersi il suo tempo.

I duplicati e i pacchetti fuori ordine vengono scartati subito, prima di toccare il LED. Al primo pacchetto il ricevitore allinea il proprio contatore delle pressioni a quello ricevuto, senza commutare il LED; poi ogni variazione del contatore inverte lo stato. Il failsafe spegne il LED se per un secondo non arriva nulla: è il comportamento prudente per un comando a distanza, perché un attuatore non deve restare acceso se il comando si interrompe. Ogni 2 s il monitor seriale mostra una riga con questo formato:

Ricevuti <n>, persi <n> (<%>), duplicati <n>, scartati <n>, riavvii TX <n> | RSSI medio <dBm>, min <dBm> | <mV> mV, LED abilitato|spento

Invio con conferma: cosa garantisce

Lo stato ESP_NOW_SEND_SUCCESS significa, secondo la documentazione, che il pacchetto è stato ricevuto correttamente a livello MAC: la radio del destinatario lo ha accettato e ha inviato l’ACK. Non garantisce che l’applicazione lo abbia elaborato: la coda del ricevitore potrebbe essere piena o lo sketch potrebbe scartarlo. Se serve una conferma applicativa, per esempio per un comando che deve essere eseguito una volta sola, il ricevitore deve rispondere con un proprio pacchetto, e il trasmettitore deve ritentare finché non lo riceve. Lo stato ESP_NOW_SEND_FAIL arriva quando, dopo le ritrasmissioni, l’ACK non è arrivato: ricevitore spento o fuori portata, MAC sbagliato o canale diverso.

Diagramma di sequenza: esp_now_send nel loop del trasmettitore, frame radio, ACK MAC, callback di invio con esito positivo, callback di ricezione e coda verso il loop del ricevitore; in caso di ACK mancante ritrasmissioni e callback con esito negativo

Per i pacchetti broadcast, inviati all’indirizzo FF:FF:FF:FF:FF:FF, nessun ricevitore invia l’ACK: la callback non dice nulla sulla ricezione, e il broadcast va usato solo per messaggi che possono andare persi, come un annuncio periodico. Il peer broadcast va comunque aggiunto con esp_now_add_peer() prima di inviare.

Coesistenza con il Wi-Fi e vincolo del canale

L’ESP32 ha una sola radio, che in ogni istante lavora su un solo canale. Finché le schede usano solo ESP-NOW, il canale si sceglie liberamente con WiFi.setChannel(), uguale su tutte. Se però una scheda è anche collegata a un router in modalità Station, per esempio il ricevitore che inoltra i dati a Home Assistant come descritto nella guida su ESP32, MQTT e Home Assistant, il canale lo decide il router, e tutti i peer ESP-NOW devono usare quello. La documentazione lo dice in modo esplicito: il canale del peer deve coincidere con quello su cui si trova la radio, oppure valere 0 (“canale corrente”).

Schema del vincolo del canale: senza router entrambe le schede sul canale 1; con il ricevitore collegato al router sul canale 6 anche il trasmettitore deve usare il canale 6

Il problema pratico è che molti router scelgono il canale automaticamente e possono cambiarlo, per esempio dopo un riavvio. Le soluzioni sono due: fissare il canale nelle impostazioni del router, oppure far cercare al trasmettitore il canale della rete con una scansione (WiFi.scanNetworks() e WiFi.channel(i) sulla rete con il SSID noto) e impostarlo prima di aggiungere il peer. C’è poi il risparmio energetico: una scheda collegata al router usa per impostazione predefinita il modem sleep, che spegne il ricevitore radio tra un beacon e l’altro, e in quegli intervalli i pacchetti ESP-NOW possono andare persi; sul ricevitore conviene disattivarlo con WiFi.setSleep(false), a costo di un consumo maggiore.

Portata e consumi

La portata dipende dalla potenza trasmessa, dalla sensibilità del ricevitore, dalle antenne e soprattutto dagli ostacoli. Il datasheet dell’ESP32 indica in modalità 802.11b una potenza di uscita tipica di 20 dBm (fino a +20,5 dBm) e una sensibilità tipica di −98 dBm a 1 Mbps. La differenza, 118 dB, è il budget di collegamento disponibile; in spazio libero l’attenuazione di tratta si calcola con la formula derivata dall’equazione di Friis:

\(L_{fs}\,[\text{dB}] = 20\log_{10} d_{\text{km}} + 20\log_{10} f_{\text{MHz}} + 32{,}44\)

Esempio di calcolo: portata teorica sul canale 1 (2412 MHz)

  Budget: P_tx - S = 20 dBm - (-98 dBm) = 118 dB  (antenne 0 dBi)
  Margine di 30 dB (ostacoli, fading, antenne reali): L_fs = 88 dB
    20 log d = 88 - 20 log 2412 - 32,44 = 88 - 67,65 - 32,44 = -12,09
    d = 10^(-12,09/20) km = 0,249 km  ~ 250 m
  Margine di 20 dB:  L_fs = 98 dB  ->  d ~ 790 m
  Sono limiti superiori in vista diretta: in casa ogni parete toglie
  da pochi dB a oltre 10 dB e la portata scende a qualche decina di metri.

Grafico teorico della potenza ricevuta in funzione della distanza in spazio libero e con 20 dB di attenuazioni, con la sensibilità di meno 98 dBm e la soglia con 30 dB di margine

Il calcolo non considera la zona di Fresnel, le riflessioni sul terreno né il guadagno reale dell’antenna stampata del modulo, quindi va preso come ordine di grandezza. Il dato utile al banco è l’RSSI stampato dal ricevitore: valori tra −40 e −70 dBm indicano un collegamento solido, avvicinandosi a −90 dBm iniziano le perdite. Per distanze maggiori Espressif offre una modalità Long Range a bitrate ridotto, da valutare caso per caso.

Per i consumi, il datasheet indica circa 240 mA durante la trasmissione 802.11b a 19,5 dBm e da 95 a 100 mA in ricezione. Il ricevitore di questo progetto tiene la radio sempre in ascolto, quindi assorbe un centinaio di milliampere in continuo: va alimentato da rete. Il trasmettitore, invece, trasmette per tempi brevissimi.

Esempio di calcolo: durata di un pacchetto in aria a 1 Mbps

  frame = intestazione MAC 24 + categoria 1 + OUI 3 + casuale 4
        + elemento del produttore 7 + dati 14 + FCS 4 = 57 byte = 456 bit
  t = 456 µs + preambolo e intestazione PLCP lunghi 192 µs ~ 0,65 ms
  A 10 pacchetti/s la radio trasmette per circa 6,5 ms al secondo (0,65 %).

In un trasmettitore a batteria il consumo è dominato dal resto: CPU accesa, avvio della radio e attese. Lo schema tipico è risvegliarsi dal deep sleep, avviare il Wi-Fi in Station, inizializzare ESP-NOW, inviare un pacchetto, attendere la callback e tornare a dormire, con una scheda progettata per il basso consumo come spiegato nella guida introduttiva.

Cifratura

Per cifrare i pacchetti unicast si imposta una chiave primaria comune con esp_now_set_pmk() (16 byte) e, per ogni peer, una chiave locale nel campo lmk con encrypt = true. Entrambe le schede devono registrare l’altra come peer cifrato con la stessa chiave locale. La cifratura limita il numero di peer cifrati (7 nella configurazione del core) e non si applica ai broadcast. Per un telecomando di un cancello è il minimo indispensabile. Il numero di sequenza del pacchetto scarta già duplicati e pacchetti fuori ordine, ma non basta contro chi registra i pacchetti e li ritrasmette più tardi: un tempo che torna indietro viene interpretato come riavvio del trasmettitore. Per un comando critico servono la cifratura e un contatore che non riparte da zero a ogni accensione, per esempio salvato nella memoria non volatile.

Prove e limiti della verifica

Con il core 3.3.12 il trasmettitore occupa circa 895 KB di flash e il ricevitore circa 889 KB (68 e 67 % della partizione predefinita), con circa 46 KB di RAM statica, senza avvisi di compilazione. Il file pacchetto.h è stato compilato con g++ ed eseguito su PC con il test riportato sopra. Gli sketch sono stati avviati anche nell’emulatore QEMU, che però si ferma all’inizializzazione della radio: ESP-NOW non si può emulare. Lo scambio reale, l’RSSI, le perdite in funzione della distanza e il comportamento con il router vanno verificati al banco con due schede, seguendo la checklist allegata.

Errori comuni

Errori di compilazione sulle callback. Esempi scritti per il core 2.x o 3.0–3.2: va adattata la firma come nella tabella. Non si risolve con un cast forzato, che farebbe interpretare un puntatore a struttura come un MAC.

Tutti gli invii falliscono. MAC del ricevitore copiato male o preso dall’interfaccia sbagliata, ricevitore su un altro canale (per esempio perché collegato al router), oppure ricevitore non ancora avviato. Il primo controllo è confrontare MAC e canale stampati all’avvio dalle due schede.

esp_now_init() o esp_now_add_peer() falliscono. La radio non è stata avviata prima con WiFi.mode(WIFI_STA), oppure il peer ha un canale diverso da quello corrente. esp_err_to_name() stampa il codice di errore in chiaro.

Il ricevitore si blocca o si riavvia. Stampe, delay() o elaborazioni lunghe dentro la callback di ricezione, che gira nel task del Wi-Fi. La callback deve solo copiare i dati in una coda.

Valori senza senso nel ricevitore. Struttura diversa tra le due schede (un campo aggiunto da una sola parte) o struttura non packed. Il controllo di lunghezza, magic, versione e CRC di validaPacchetto() scarta questi pacchetti e li conta come “scartati”.

Perdite con il ricevitore collegato al router. Modem sleep attivo o router che ha cambiato canale: WiFi.setSleep(false) e canale fisso o scansione.

Checklist per un collegamento ESP-NOW

 1. Stesso core su tutte le schede, oppure firme delle callback adattate (#if ESP_IDF_VERSION).
 2. WiFi.mode(WIFI_STA) prima di esp_now_init(); MAC letto con WiFi.macAddress().
 3. Stesso canale su tutte le schede; con il router, il canale del router.
 4. Struttura packed, static_assert sulla dimensione, campo versione, CRC.
 5. Numero di sequenza per contare perdite e duplicati; contatori invece di eventi.
 6. Callback brevi: validazione, RSSI e coda; il resto nel loop() o in un task.
 7. Nuovo invio solo dopo la callback del precedente.
 8. Failsafe sul ricevitore: uscite in stato sicuro se i pacchetti si interrompono.
 9. Pacchetti al massimo di 250 byte se qualche scheda usa ESP-NOW v1.0.
10. Cifratura (PMK + LMK) per i comandi che non devono essere falsificati.

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); il formato dei pacchetti è stato verificato con un test su PC (g++) e gli sketch sono stati avviati nell’emulatore QEMU, che non emula la radio. La prova su hardware reale va eseguita con la checklist fornita. Le firme delle callback e i limiti sono stati controllati anche negli header esp_now.h del core installato.

Articoli collegati

Admin | MST-Tutorial

Appassionato di elettronica, elettrotecnica e programmazione. Fondatore di MST-Tutorial, condivido con entusiasmo conoscenze, esperienze e progetti legati all’innovazione tecnologica, con l’obiettivo di rendere accessibili concetti tecnici complessi attraverso tutorial chiari e pratici.

Articoli Correlati

Pulsante per tornare all'inizio