ArduinoEmbedded & IoT

ESP32 e MQTT con Home Assistant: discovery, last will e riconnessione

Protocollo MQTT, broker Mosquitto in Home Assistant con utente dedicato, PubSubClient e buffer, MQTT Discovery con ArduinoJson 7, LWT online/offline e riconnessione non bloccante.

Un ESP32 che legge una temperatura e accende un LED diventa davvero utile quando entra nel sistema domotico di casa: la misura compare in un grafico, il LED si comanda dall’app sullo smartphone e un’automazione può reagire ai valori. Il modo più diffuso per collegare un dispositivo fatto in casa a Home Assistant è MQTT, un protocollo di messaggistica leggero nato proprio per sensori e attuatori su reti poco affidabili. Rispetto al web server visto nella guida introduttiva all’ESP32, qui non è il browser a interrogare la scheda: è la scheda a pubblicare i dati verso un server centrale, il broker, che li distribuisce a chi li ha richiesti.

In questa guida si vedono i concetti di MQTT che servono davvero (topic, QoS, messaggi retained, last will e keepalive), la configurazione del broker Mosquitto in Home Assistant con un utente dedicato, la libreria PubSubClient con il limite del buffer da 256 byte e la MQTT Discovery, che fa comparire il dispositivo in Home Assistant senza scrivere una riga di YAML. Il progetto finale pubblica la temperatura di un sensore TMP36, espone il LED come interruttore, segnala se è online o offline e si riconnette da solo senza mai bloccare il programma. Il codice è stato compilato per l’ESP32; poiché la rete non si può emulare, la generazione dei messaggi e la logica di riconnessione sono state verificate con un test su PC, e la prova completa è affidata a una checklist di banco.

MQTT in breve: broker, topic e messaggi

In MQTT i dispositivi non si parlano direttamente. Ogni partecipante è un client che apre una connessione TCP verso il broker (porta 1883 senza cifratura, 8883 con TLS) e la mantiene aperta. Un client pubblica messaggi su un topic, una stringa gerarchica con livelli separati da / come mst/esp32-a1b2c3/temperatura, e il broker li inoltra a tutti i client che si sono sottoscritti a quel topic. Nelle sottoscrizioni si possono usare due caratteri jolly: + sostituisce un solo livello (mst/+/temperatura), # tutti i livelli successivi e va messo in fondo (mst/#). Il contenuto del messaggio, il payload, è una sequenza di byte qualsiasi: un numero in formato testo, una parola come ON o un documento JSON.

Questo schema disaccoppia chi produce i dati da chi li usa. L’ESP32 non sa se a leggere la temperatura sarà Home Assistant, uno script su un PC o entrambi, e non deve conoscerne l’indirizzo: gli basta raggiungere il broker. Anche i comandi seguono la stessa strada al contrario: Home Assistant pubblica ON su un topic di comando a cui l’ESP32 è sottoscritto.

QoS, retain, last will e keepalive

La qualità del servizio (QoS) stabilisce le garanzie di consegna tra un client e il broker. Con QoS 0 il messaggio è inviato una volta senza conferma (“al più una volta”): se la connessione cade in quell’istante, va perso. Con QoS 1 il destinatario conferma la ricezione e il mittente ritrasmette finché non riceve la conferma (“almeno una volta”), con possibili duplicati. Il QoS 2 (“esattamente una volta”) usa uno scambio di quattro pacchetti ed è raramente necessario in domotica. Per una temperatura inviata ogni 30 secondi, perdere un valore non è un problema e QoS 0 basta.

Un messaggio pubblicato con il flag retain viene memorizzato dal broker, che conserva l’ultimo per ciascun topic e lo consegna subito a ogni nuovo sottoscrittore. È il modo per far conoscere lo stato attuale a chi si collega dopo: se Home Assistant si riavvia, ritrova la configurazione del dispositivo e l’ultimo stato del LED senza aspettare il messaggio successivo. Un messaggio retained con payload vuoto cancella quello memorizzato.

Il last will (LWT, last will and testament) è un messaggio che il client consegna al broker al momento della connessione e che il broker pubblica al suo posto se la connessione si interrompe senza una disconnessione regolare: alimentazione staccata, Wi-Fi caduto, firmware bloccato. Il broker si accorge della caduta grazie al keepalive: il client dichiara un intervallo, e se in quel tempo non ha altro da trasmettere invia un PINGREQ. Secondo la specifica MQTT 3.1.1, se il broker non riceve nulla per una volta e mezza l’intervallo di keepalive chiude la connessione e pubblica il last will. Con un keepalive di 30 s, lo stato offline compare entro circa 45 s dallo spegnimento.

Diagramma di sequenza MQTT: connessione con last will, pubblicazione di online e della discovery, temperatura, comando del LED da Home Assistant, ping, ripubblicazione dopo il riavvio di Home Assistant e pubblicazione di offline da parte del broker

Il broker Mosquitto in Home Assistant

Home Assistant OS e le installazioni Supervised offrono il broker Mosquitto come app ufficiale. Dalla versione 2026.2 quelle che prima si chiamavano add-on si chiamano app, e il relativo menu delle impostazioni ha cambiato nome di conseguenza; nelle guide più vecchie si troverà quindi “add-on Mosquitto broker”. Con le installazioni Container o Core il broker va installato a parte, per esempio dal gestore pacchetti della distribuzione o con l’immagine Docker ufficiale di Eclipse Mosquitto.

Configurazione del broker in Home Assistant OS (procedura indicativa)

 1. Impostazioni > App (ex Componenti aggiuntivi) > Store: installare
    "Mosquitto broker", avviarlo e attivare "Avvia all'accensione".
 2. Creare un utente dedicato all'ESP32: Impostazioni > Persone > Utenti
    (scheda visibile con la modalità avanzata attiva nel profilo),
    per esempio "esp32-mqtt" con una password robusta.
    I nomi "homeassistant" e "addons" sono riservati dal broker.
    In alternativa: opzione "logins" nella configurazione dell'app.
 3. Impostazioni > Dispositivi e servizi: Home Assistant propone
    l'integrazione MQTT già rilevata; confermarla.
 4. Nelle opzioni dell'integrazione verificare che la discovery sia
    attiva (prefisso predefinito "homeassistant").
 5. Annotare l'indirizzo IP del server: sarà MQTT_HOST nello sketch.

Un utente separato per ogni dispositivo, o almeno per i dispositivi fai-da-te, permette di revocarne l’accesso senza toccare il resto. La porta 1883 trasmette credenziali e dati in chiaro: va bene all’interno della rete di casa, ma non deve essere esposta su Internet. Per l’accesso da fuori si usano una VPN o il TLS sulla porta 8883, che sull’ESP32 richiede NetworkClientSecure e più memoria.

La libreria PubSubClient e il buffer da 256 byte

PubSubClient di Nick O’Leary (versione 2.8) è la libreria MQTT più usata con Arduino: è piccola, funziona con qualunque oggetto Client (qui WiFiClient) e implementa MQTT 3.1.1. Ha però alcuni limiti da conoscere. Pubblica solo con QoS 0, mentre le sottoscrizioni possono chiedere QoS 0 o 1; il last will può invece avere QoS 1 ed essere retained. Il keepalive predefinito è di 15 s e il timeout del socket di 15 s; entrambi si cambiano con setKeepAlive() e setSocketTimeout().

Il limite che causa più problemi è il buffer interno da 256 byte (MQTT_MAX_PACKET_SIZE). Il buffer contiene l’intero pacchetto, non solo il payload: intestazione fissa (fino a 5 byte), 2 byte di lunghezza del topic, il topic e il payload. Se il pacchetto non ci sta, publish() restituisce false e il messaggio non parte, senza altri avvisi. I payload di discovery di Home Assistant superano facilmente i 256 byte, quindi va chiamato setBufferSize() prima della connessione.

\(N_{pacchetto} = 5 + 2 + L_{topic} + L_{payload}\)

Esempio di calcolo: dimensione dei pacchetti di discovery (valori del test su PC)

  sensore: topic "homeassistant/sensor/esp32-a1b2c3/temperatura/config"
           L_topic = 52 byte, L_payload = 448 byte
           N = 5 + 2 + 52 + 448 = 507 byte   > 256  -> serve setBufferSize()
  switch:  L_topic = 44 byte, L_payload = 394 byte
           N = 5 + 2 + 44 + 394 = 445 byte
  Scelta:  setBufferSize(1024), margine per nomi più lunghi.
           Il buffer è allocato nell'heap: 1 KB, una frazione minima della RAM.

MQTT Discovery: Home Assistant crea il dispositivo da solo

Con la MQTT Discovery il dispositivo descrive se stesso. Per ogni entità pubblica un messaggio di configurazione su un topic con la forma documentata da Home Assistant:

<discovery_prefix>/<component>/[<node_id>/]<object_id>/config

homeassistant/sensor/esp32-a1b2c3/temperatura/config
homeassistant/switch/esp32-a1b2c3/led/config

Il prefisso predefinito è homeassistant; component è il tipo di entità (sensor, switch, binary_sensor, light…); node_id è facoltativo e Home Assistant non lo usa: serve solo a tenere ordinati sul broker i topic di un dispositivo, e qui coincide con l’identificativo della scheda ricavato dal MAC (sono ammessi solo lettere, cifre, _ e -); object_id distingue le entità. Il payload è un documento JSON con le stesse opzioni della configurazione YAML dell’entità. Le opzioni usate nel progetto, verificate sulla documentazione delle integrazioni MQTT Sensor e MQTT Switch, sono queste:

Chiave Significato Valore nel progetto
unique_id identificativo univoco dell’entità, indispensabile per modificarla dall’interfaccia e per collegarla a un dispositivo esp32-a1b2c3_temperatura
device raggruppa le entità in un dispositivo; richiede identifiers o connections identificativo, nome, produttore, modello, versione
state_topic topic da cui leggere lo stato mst/<id>/temperatura
availability_topic topic di disponibilità; valori predefiniti online e offline mst/<id>/stato
device_class, state_class tipo di grandezza (icona, conversioni) e tipo di misura (statistiche a lungo termine) temperature, measurement
unit_of_measurement unità del valore °C
command_topic, payload_on/payload_off solo per lo switch: topic dei comandi e valori (predefiniti ON e OFF) mst/<id>/led/set

Il messaggio di configurazione può essere pubblicato con il flag retain, così il broker lo riconsegna a Home Assistant a ogni avvio. La documentazione indica però come approccio migliore un altro meccanismo: Home Assistant pubblica online sul topic homeassistant/status quando parte (il cosiddetto birth message), e il dispositivo, sottoscritto a quel topic, ripubblica configurazione e stati. Il progetto fa entrambe le cose; il prezzo del retain, segnalato dalla stessa documentazione, è che una configurazione rimasta sul broker fa ricomparire l’entità anche dopo aver dismesso la scheda, finché non la si cancella (vedi gli errori comuni). È inoltre raccomandato il blocco origin, che indica quale software ha generato la discovery ed è obbligatorio nella device discovery descritta più avanti. Per eliminare un’entità basta pubblicare un payload vuoto sul suo topic di configurazione.

Esistono due varianti di discovery. Quella usata qui, con un messaggio per ogni entità (single component discovery), è la più semplice da capire e da correggere. Per dispositivi con molte entità la documentazione consiglia la device discovery, con un unico messaggio sul topic homeassistant/device/<id>/config che elenca tutti i componenti: riduce il traffico, ma produce un JSON più lungo, da dimensionare con la stessa formula. La documentazione ammette anche nomi abbreviati delle chiavi (stat_t per state_topic, dev per device, ~ come base dei topic), utili quando la memoria è scarsa; qui si preferiscono i nomi completi per leggibilità.

Schema a blocchi: ESP32 con PubSubClient collegato via Wi-Fi al broker Mosquitto in Home Assistant, integrazione MQTT, dispositivo e client di prova mosquitto_sub, con l'elenco dei topic usati

Hardware: TMP36 e LED

Come sensore si usa il TMP36 di Analog Devices, un sensore di temperatura analogico che funziona da 2,7 a 5,5 V e quindi si alimenta direttamente dai 3,3 V della scheda. Secondo il datasheet l’uscita vale 750 mV a 25 °C con un coefficiente di 10 mV/°C, cioè 500 mV a 0 °C; l’accuratezza tipica è di ±1 °C a 25 °C e ±2 °C nell’intervallo di funzionamento, con una corrente di riposo inferiore a 50 µA, che rende trascurabile l’autoriscaldamento. Il datasheet raccomanda un condensatore ceramico da 100 nF tra alimentazione e massa, vicino al pin.

\(T = \frac{V_{out} – 500\ \text{mV}}{10\ \text{mV/°C}}\)

L’uscita va su GPIO34, un ingresso dell’ADC1: con il Wi-Fi attivo i pin dell’ADC2 non sono utilizzabili, come spiegato nella guida introduttiva. Con l’attenuazione di 11 dB la documentazione del core Arduino indica un intervallo da circa 150 a 3100 mV, mentre ESP-IDF raccomanda per l’ESP32 di restare tra 150 e 2450 mV, dove l’errore è minore: per il TMP36 (500–1000 mV tra 0 e 50 °C) il problema non si pone, e il limite inferiore corrisponde a circa −35 °C. La lettura usa analogReadMilliVolts(), che applica la calibrazione memorizzata nel chip, ed è la media di 16 campioni. Restano un’incertezza dell’ADC di qualche decina di millivolt, cioè alcuni gradi, e l’accuratezza del sensore: per misure più precise conviene un sensore digitale come quelli descritti nella guida ai sensori di temperatura. Chi non ha il TMP36 può collegare al suo posto il potenziometro della guida introduttiva: il valore pubblicato sarà una “temperatura simulata” da circa −35 a +260 °C, comunque utile per provare il sistema. Il LED con 330 Ω su GPIO25 resta quello già visto.

Schema di collegamento: TMP36 alimentato a 3,3 V con condensatore da 100 nF e uscita su GPIO34, LED con resistenza da 330 ohm su GPIO25

Il codice: logica separata dall’hardware

Il progetto è diviso in due file nella stessa cartella dello sketch. ha_mqtt.h contiene tutto ciò che non dipende dall’hardware: la costruzione dei topic, i payload JSON di discovery generati con ArduinoJson 7, la conversione del TMP36 e la macchina a stati della connessione. Non usa funzioni Arduino e si compila anche su un PC, il che ha permesso di provarlo senza scheda. Lo sketch mqtt_ha_sensore.ino collega quella logica a Wi-Fi, PubSubClient e pin.

In ArduinoJson 7 il documento è un semplice JsonDocument che si dimensiona da solo nell’heap; measureJson() calcola in anticipo la lunghezza del testo, così le funzioni rifiutano un buffer troppo piccolo invece di produrre un JSON troncato. Le stringhe passate come const char* vengono copiate nel documento, quindi i buffer locali dei topic possono essere riutilizzati senza rischi.

// ha_mqtt.h - logica indipendente dall'hardware per ESP32 + MQTT + Home Assistant:
// topic, payload di MQTT Discovery (ArduinoJson 7) e macchina a stati di riconnessione.
// Non usa funzioni Arduino: si compila anche su PC con g++ per i test.
#pragma once
#include <ArduinoJson.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>

struct Dispositivo {
  const char *id;        // identificativo univoco, es. "esp32-a1b2c3" (dal MAC)
  const char *nome;      // nome del dispositivo in Home Assistant
  const char *versione;  // versione del firmware
};

// Topic del dispositivo: mst/<id>/<suffisso>
inline void creaTopic(char *out, size_t n, const char *id, const char *suffisso) {
  snprintf(out, n, "mst/%s/%s", id, suffisso);
}

// Topic di discovery: homeassistant/<component>/<node_id>/<object_id>/config
inline void topicDiscovery(char *out, size_t n, const char *componente,
                           const char *id, const char *oggetto) {
  snprintf(out, n, "homeassistant/%s/%s/%s/config", componente, id, oggetto);
}

// Blocchi comuni: device (raggruppa le entita') e origin (chi genera la discovery)
inline void aggiungiDevice(JsonDocument &doc, const Dispositivo &d) {
  JsonObject dev = doc["device"].to<JsonObject>();
  dev["identifiers"].to<JsonArray>().add(d.id);
  dev["name"] = d.nome;
  dev["manufacturer"] = "MST-Tutorial";
  dev["model"] = "ESP32-DevKitC";
  dev["sw_version"] = d.versione;
  doc["origin"]["name"] = "mst-esp32-mqtt";
}

// Sensore di temperatura: restituisce la lunghezza del JSON (0 se il buffer non basta)
inline size_t payloadTemperatura(char *out, size_t n, const Dispositivo &d) {
  JsonDocument doc;
  char uid[48], stato[64], disp[64];
  snprintf(uid, sizeof(uid), "%s_temperatura", d.id);
  creaTopic(stato, sizeof(stato), d.id, "temperatura");
  creaTopic(disp, sizeof(disp), d.id, "stato");
  doc["name"] = "Temperatura";
  doc["unique_id"] = uid;
  doc["device_class"] = "temperature";
  doc["state_class"] = "measurement";
  doc["unit_of_measurement"] = "°C";
  doc["suggested_display_precision"] = 1;
  doc["state_topic"] = stato;
  doc["availability_topic"] = disp;
  aggiungiDevice(doc, d);
  if (measureJson(doc) >= n) return 0;
  return serializeJson(doc, out, n);
}

// Interruttore per il LED: comando su .../led/set, stato su .../led/stato
inline size_t payloadLed(char *out, size_t n, const Dispositivo &d) {
  JsonDocument doc;
  char uid[48], cmd[64], stato[64], disp[64];
  snprintf(uid, sizeof(uid), "%s_led", d.id);
  creaTopic(cmd, sizeof(cmd), d.id, "led/set");
  creaTopic(stato, sizeof(stato), d.id, "led/stato");
  creaTopic(disp, sizeof(disp), d.id, "stato");
  doc["name"] = "LED";
  doc["unique_id"] = uid;
  doc["command_topic"] = cmd;
  doc["state_topic"] = stato;
  doc["payload_on"] = "ON";
  doc["payload_off"] = "OFF";
  doc["availability_topic"] = disp;
  aggiungiDevice(doc, d);
  if (measureJson(doc) >= n) return 0;
  return serializeJson(doc, out, n);
}

// Dimensione del pacchetto MQTT PUBLISH (QoS 0) che PubSubClient deve contenere nel buffer:
// header fisso (fino a 5 byte) + 2 byte di lunghezza del topic + topic + payload
inline size_t dimensionePacchetto(size_t lunghezzaTopic, size_t lunghezzaPayload) {
  return 5 + 2 + lunghezzaTopic + lunghezzaPayload;
}

// TMP36: 500 mV a 0 gradi C, 10 mV per grado
inline float temperaturaDaMilliVolt(uint32_t mV) {
  return ((float)mV - 500.0f) / 10.0f;
}

// Comando del LED: 1 = ON, 0 = OFF, -1 = non valido
inline int interpretaComando(const char *s) {
  if (strcmp(s, "ON") == 0) return 1;
  if (strcmp(s, "OFF") == 0) return 0;
  return -1;
}

// ---------- macchina a stati della connessione (non bloccante) ----------
enum class StatoRete : uint8_t { AVVIO, ATTESA_WIFI, ATTESA_MQTT, OPERATIVO };
enum class Azione : uint8_t { NESSUNA, AVVIA_WIFI, RICONNETTI_WIFI, CONNETTI_MQTT };

inline const char *nomeStato(StatoRete s) {
  switch (s) {
    case StatoRete::AVVIO:       return "AVVIO";
    case StatoRete::ATTESA_WIFI: return "ATTESA_WIFI";
    case StatoRete::ATTESA_MQTT: return "ATTESA_MQTT";
    case StatoRete::OPERATIVO:   return "OPERATIVO";
  }
  return "?";
}

struct Riconnessione {
  static const uint32_t TIMEOUT_WIFI_MS = 30000;   // poi WiFi.reconnect()
  static const uint32_t RITARDO_MIN_MS = 1000;     // primo tentativo MQTT
  static const uint32_t RITARDO_MAX_MS = 32000;    // tetto del backoff
  StatoRete stato = StatoRete::AVVIO;
  uint32_t t0 = 0;                                 // inizio dell'attesa corrente
  uint32_t ritardoMqtt = RITARDO_MIN_MS;

  // Da chiamare a ogni loop(): decide cosa fare senza mai attendere.
  // Le differenze (ora - t0) tra unsigned funzionano anche al riavvolgimento di millis().
  Azione passo(uint32_t ora, bool wifiOk, bool mqttOk) {
    switch (stato) {
      case StatoRete::AVVIO:
        stato = StatoRete::ATTESA_WIFI; t0 = ora;
        return Azione::AVVIA_WIFI;
      case StatoRete::ATTESA_WIFI:
        if (wifiOk) {                               // primo tentativo MQTT subito
          stato = StatoRete::ATTESA_MQTT; t0 = ora - ritardoMqtt;
          return Azione::NESSUNA;
        }
        if (ora - t0 >= TIMEOUT_WIFI_MS) { t0 = ora; return Azione::RICONNETTI_WIFI; }
        return Azione::NESSUNA;
      case StatoRete::ATTESA_MQTT:
        if (!wifiOk) { stato = StatoRete::ATTESA_WIFI; t0 = ora; return Azione::NESSUNA; }
        if (ora - t0 >= ritardoMqtt) return Azione::CONNETTI_MQTT;
        return Azione::NESSUNA;
      case StatoRete::OPERATIVO:
        if (!wifiOk) { stato = StatoRete::ATTESA_WIFI; t0 = ora; return Azione::NESSUNA; }
        if (!mqttOk) { stato = StatoRete::ATTESA_MQTT; t0 = ora; return Azione::NESSUNA; }
        return Azione::NESSUNA;
    }
    return Azione::NESSUNA;
  }

  // Esito del tentativo MQTT: successo -> OPERATIVO, errore -> attesa raddoppiata
  void esitoMqtt(bool ok, uint32_t ora) {
    t0 = ora;
    if (ok) {
      stato = StatoRete::OPERATIVO;
      ritardoMqtt = RITARDO_MIN_MS;
    } else {
      ritardoMqtt = (ritardoMqtt * 2 > RITARDO_MAX_MS) ? RITARDO_MAX_MS : ritardoMqtt * 2;
    }
  }
};
// ESP32 + MQTT + Home Assistant (MQTT Discovery) - core arduino-esp32 3.x
// Librerie: PubSubClient 2.8, ArduinoJson 7.x
// TMP36 su GPIO34 (ADC1), LED con 330 ohm su GPIO25

#include <WiFi.h>
#include <PubSubClient.h>
#include <ArduinoJson.h>
#include "ha_mqtt.h"

// ---- da personalizzare ----
const char *WIFI_SSID = "NOME_RETE";
const char *WIFI_PASS = "PASSWORD_RETE";
const char *MQTT_HOST = "192.168.1.10";      // indirizzo IP di Home Assistant
const uint16_t MQTT_PORT = 1883;
const char *MQTT_USER = "esp32-mqtt";        // utente dedicato per il broker
const char *MQTT_PASS = "PASSWORD_MQTT";
// ---------------------------

const char *VERSIONE = "1.0.0";
const int LED_PIN = 25;
const int TMP36_PIN = 34;
const uint32_t PERIODO_TEMPERATURA_MS = 30000;
const char *TOPIC_HA_STATUS = "homeassistant/status";   // birth message di HA

WiFiClient rete;
PubSubClient mqtt(rete);
Riconnessione rc;

char idDispositivo[16];                  // "esp32-xxxxxx"
char tStato[48], tTemperatura[48], tLedSet[48], tLedStato[48];
bool ledAcceso = false;
uint32_t ultimaTemperatura = 0;

float leggiTemperatura() {
  uint32_t somma = 0;
  for (int i = 0; i < 16; i++) somma += analogReadMilliVolts(TMP36_PIN);
  return temperaturaDaMilliVolt(somma / 16);
}

void pubblicaTemperatura() {
  char s[12];
  snprintf(s, sizeof(s), "%.1f", leggiTemperatura());
  mqtt.publish(tTemperatura, s);                       // QoS 0, non retained
  Serial.printf("-> %s = %s\n", tTemperatura, s);
}

void pubblicaLed() {
  mqtt.publish(tLedStato, ledAcceso ? "ON" : "OFF", true);   // retained
}

void pubblicaDiscovery() {
  static char payload[768];
  char topic[96];
  Dispositivo d = { idDispositivo, "ESP32 sensore MST", VERSIONE };

  topicDiscovery(topic, sizeof(topic), "sensor", idDispositivo, "temperatura");
  size_t n = payloadTemperatura(payload, sizeof(payload), d);
  bool ok1 = n > 0 && mqtt.publish(topic, (const uint8_t *)payload, n, true);

  topicDiscovery(topic, sizeof(topic), "switch", idDispositivo, "led");
  n = payloadLed(payload, sizeof(payload), d);
  bool ok2 = n > 0 && mqtt.publish(topic, (const uint8_t *)payload, n, true);
  Serial.printf("Discovery: sensore %s, LED %s\n", ok1 ? "ok" : "ERRORE", ok2 ? "ok" : "ERRORE");
}

void suMessaggio(char *topic, uint8_t *payload, unsigned int len) {
  char msg[16];
  len = len < sizeof(msg) - 1 ? len : sizeof(msg) - 1;
  memcpy(msg, payload, len);
  msg[len] = '\0';
  Serial.printf("<- %s = %s\n", topic, msg);

  if (strcmp(topic, tLedSet) == 0) {
    int c = interpretaComando(msg);
    if (c < 0) return;                                 // comando sconosciuto
    ledAcceso = (c == 1);
    digitalWrite(LED_PIN, ledAcceso ? HIGH : LOW);
    pubblicaLed();                                     // conferma dello stato
  } else if (strcmp(topic, TOPIC_HA_STATUS) == 0 && strcmp(msg, "online") == 0) {
    pubblicaDiscovery();                               // HA riavviato: ripubblica
    pubblicaLed();
    pubblicaTemperatura();
  }
}

bool connettiMqtt() {
  Serial.printf("MQTT: connessione a %s:%u... ", MQTT_HOST, MQTT_PORT);
  // id, utente, password, topic LWT, QoS LWT, retain LWT, messaggio LWT
  if (!mqtt.connect(idDispositivo, MQTT_USER, MQTT_PASS, tStato, 1, true, "offline")) {
    Serial.printf("fallita (stato %d)\n", mqtt.state());
    return false;
  }
  Serial.println("ok");
  mqtt.publish(tStato, "online", true);              // disponibilita' (retained)
  mqtt.subscribe(tLedSet, 1);
  mqtt.subscribe(TOPIC_HA_STATUS, 1);
  pubblicaDiscovery();
  pubblicaLed();
  pubblicaTemperatura();
  ultimaTemperatura = millis();
  return true;
}

void gestisciRete() {
  bool wifiOk = WiFi.status() == WL_CONNECTED;
  switch (rc.passo(millis(), wifiOk, mqtt.connected())) {
    case Azione::AVVIA_WIFI:
      WiFi.mode(WIFI_STA);
      WiFi.setAutoReconnect(true);
      WiFi.begin(WIFI_SSID, WIFI_PASS);
      Serial.printf("Wi-Fi: connessione a %s\n", WIFI_SSID);
      break;
    case Azione::RICONNETTI_WIFI:
      Serial.println("Wi-Fi: nessuna connessione da 30 s, nuovo tentativo");
      WiFi.reconnect();
      break;
    case Azione::CONNETTI_MQTT:
      rc.esitoMqtt(connettiMqtt(), millis());
      break;
    case Azione::NESSUNA:
      break;
  }
}

void setup() {
  Serial.begin(115200);
  pinMode(LED_PIN, OUTPUT);
  digitalWrite(LED_PIN, LOW);
  analogSetPinAttenuation(TMP36_PIN, ADC_11db);

  uint64_t mac = ESP.getEfuseMac();                    // MAC di fabbrica
  snprintf(idDispositivo, sizeof(idDispositivo), "esp32-%02x%02x%02x",
           (uint8_t)(mac >> 24), (uint8_t)(mac >> 32), (uint8_t)(mac >> 40));
  creaTopic(tStato, sizeof(tStato), idDispositivo, "stato");
  creaTopic(tTemperatura, sizeof(tTemperatura), idDispositivo, "temperatura");
  creaTopic(tLedSet, sizeof(tLedSet), idDispositivo, "led/set");
  creaTopic(tLedStato, sizeof(tLedStato), idDispositivo, "led/stato");
  Serial.printf("\nDispositivo %s, firmware %s\n", idDispositivo, VERSIONE);

  mqtt.setServer(MQTT_HOST, MQTT_PORT);
  mqtt.setCallback(suMessaggio);
  mqtt.setBufferSize(1024);        // i payload di discovery superano i 256 byte predefiniti
  mqtt.setKeepAlive(30);           // secondi
  mqtt.setSocketTimeout(5);        // secondi di attesa massima delle risposte
}

void loop() {
  static StatoRete precedente = StatoRete::AVVIO;
  gestisciRete();
  if (rc.stato != precedente) {
    Serial.printf("[%lu ms] stato rete: %s -> %s\n", (unsigned long)millis(),
                  nomeStato(precedente), nomeStato(rc.stato));
    precedente = rc.stato;
  }
  if (rc.stato == StatoRete::OPERATIVO) {
    mqtt.loop();                   // riceve i messaggi e gestisce il keepalive
    if (millis() - ultimaTemperatura >= PERIODO_TEMPERATURA_MS) {
      ultimaTemperatura = millis();
      pubblicaTemperatura();
    }
  }
  // qui il resto del programma: nessuna attesa bloccante
  delay(10);
}

Alcuni dettagli meritano attenzione. L’identificativo esp32-xxxxxx deriva dagli ultimi tre byte del MAC di fabbrica, quindi è diverso per ogni scheda: lo stesso sketch caricato su due ESP32 crea due dispositivi distinti. Il client ID MQTT coincide con l’identificativo; due client con lo stesso ID si scollegherebbero a vicenda di continuo. La connessione dichiara il last will offline retained con QoS 1 e, subito dopo, pubblica online retained sullo stesso topic: Home Assistant mostra così lo stato corretto in ogni momento. Lo stato del LED è retained, la temperatura no, perché un valore vecchio di ore presentato come attuale sarebbe fuorviante. Infine, il callback suMessaggio() copia il payload in un buffer terminato da zero prima di confrontarlo: PubSubClient fornisce un puntatore e una lunghezza, non una stringa C.

Ecco il payload di discovery del sensore prodotto dalla funzione payloadTemperatura() nel test su PC, qui formattato su più righe per leggibilità (nel messaggio reale è su una riga e occupa 448 byte):

{
  "name": "Temperatura",
  "unique_id": "esp32-a1b2c3_temperatura",
  "device_class": "temperature",
  "state_class": "measurement",
  "unit_of_measurement": "°C",
  "suggested_display_precision": 1,
  "state_topic": "mst/esp32-a1b2c3/temperatura",
  "availability_topic": "mst/esp32-a1b2c3/stato",
  "device": {
    "identifiers": ["esp32-a1b2c3"],
    "name": "ESP32 sensore MST",
    "manufacturer": "MST-Tutorial",
    "model": "ESP32-DevKitC",
    "sw_version": "1.0.0"
  },
  "origin": { "name": "mst-esp32-mqtt" }
}

Riconnessione non bloccante

Molti esempi in rete si collegano al Wi-Fi e al broker con cicli while (!connected()) { delay(500); }, in setup() o in una funzione reconnect() chiamata dal loop(). Funzionano al primo avvio, ma se il router si riavvia o il broker resta spento per qualche minuto il programma si ferma dentro quel ciclo: niente misure, pulsanti ignorati, LED congelati. Il progetto usa invece una macchina a stati: a ogni passaggio del loop() la funzione passo() guarda lo stato del Wi-Fi e di MQTT, decide se è il momento di agire e restituisce subito un’azione.

Diagramma degli stati AVVIO, ATTESA_WIFI, ATTESA_MQTT e OPERATIVO con le transizioni per Wi-Fi connesso o perso, connessione MQTT riuscita o fallita e attesa raddoppiata fino a 32 secondi

Il Wi-Fi viene avviato una volta sola: il driver dell’ESP32, con setAutoReconnect(true), ritenta già da solo, e lo sketch interviene con WiFi.reconnect() solo se la rete manca da 30 s. Con il Wi-Fi presente si tenta la connessione MQTT; se fallisce, l’attesa prima del tentativo successivo raddoppia a ogni errore, da 2 a 32 s (backoff esponenziale), per non martellare un broker in difficoltà. Una connessione riuscita azzera l’attesa. Tutti i confronti di tempo usano la differenza ora - t0 tra interi senza segno, che resta corretta anche quando millis() si riavvolge dopo circa 49,7 giorni. L’unica operazione che può bloccare è mqtt.connect(): se il broker non risponde, la connessione TCP attende fino al timeout del client di rete, 3 s nel core 3.x, e la risposta del broker fino al timeout del socket impostato a 5 s.

La macchina a stati è stata provata su PC con uno scenario di guasti simulato a passi di 10 ms: Wi-Fi disponibile dopo 4 s, broker irraggiungibile fino a 30 s, riavvio del broker a 100 s, Wi-Fi assente tra 130 e 150 s. Lo stesso scenario è stato ripetuto partendo a 60 s dal riavvolgimento di millis(), con risultati identici.

Grafico della simulazione su PC: stato della connessione nel tempo con tentativi MQTT falliti a 4, 6, 10 e 18 secondi e riusciti a 34, 101 e 150 secondi

Esempio di calcolo: tentativi MQTT nello scenario simulato

  Wi-Fi pronto a 4 s       -> primo tentativo subito:  4 s (fallisce)
  attese 2, 4, 8, 16 s     -> tentativi a 6, 10, 18 s (falliscono), 34 s (riesce:
                              il broker è tornato a 30 s)
  broker perso a 100 s     -> attesa minima 1 s:      101 s (riesce)
  Wi-Fi perso 130-150 s    -> al ritorno, subito:      150 s (riesce)
  WiFi.begin() chiamato 1 volta; nessun WiFi.reconnect() (interruzioni < 30 s)

Compilazione, prova e osservazione dei messaggi

Lo sketch richiede le librerie PubSubClient e ArduinoJson, installabili dal gestore librerie dell’IDE. Con il core 3.3.12, PubSubClient 2.8 e ArduinoJson 7.4.2 la compilazione per “ESP32 Dev Module” non produce avvisi e occupa circa 915 KB di flash (il 69 % della partizione predefinita da 1,25 MB) e 48 KB di RAM statica: la parte più grande è lo stack Wi-Fi. Prima di caricare si personalizzano le credenziali della rete e del broker. Le credenziali scritte nel codice non vanno pubblicate insieme allo sketch.

Lo strumento più utile per la messa a punto è mosquitto_sub, il client a riga di comando di Mosquitto (pacchetto mosquitto-clients su Debian e Ubuntu), che mostra tutti i messaggi in transito. Con l’opzione -F si può stampare anche il flag retain (%r).

# tutti i messaggi del dispositivo e della discovery, con il flag retain
mosquitto_sub -h 192.168.1.10 -u esp32-mqtt -P 'PASSWORD_MQTT' \
  -t 'mst/#' -t 'homeassistant/#' -F '%r %t %p'

# comando manuale del LED, senza passare da Home Assistant
mosquitto_pub -h 192.168.1.10 -u esp32-mqtt -P 'PASSWORD_MQTT' \
  -t 'mst/esp32-a1b2c3/led/set' -m 'ON'

# eliminare un'entità creata per errore (payload vuoto, retained)
mosquitto_pub -h 192.168.1.10 -u esp32-mqtt -P 'PASSWORD_MQTT' \
  -t 'homeassistant/sensor/esp32-a1b2c3/temperatura/config' -r -n

Il test su PC (test_host.cpp, compilato con g++ e la stessa ArduinoJson) ha verificato i topic, la validità dei due JSON e la presenza di tutte le chiavi, la dimensione dei pacchetti rispetto al buffer, il rifiuto di un buffer troppo piccolo, la conversione del TMP36 (750 mV = 25,0 °C), l’interpretazione dei comandi e la sequenza di riconnessione. Lo sketch completo è stato anche avviato nell’emulatore QEMU: parte, genera l’identificativo e i topic, ma si ferma all’inizializzazione della radio, che l’emulatore non riproduce. La verifica dei messaggi reali, della comparsa del dispositivo in Home Assistant e del last will va quindi fatta al banco, con la checklist allegata.

Errori comuni

Il dispositivo non compare in Home Assistant. Nella maggior parte dei casi il messaggio di discovery non è mai partito perché supera il buffer di PubSubClient: publish() restituisce false senza altri segnali. Lo sketch stampa “Discovery: … ERRORE” proprio per questo. Altre cause: JSON non valido (un payload troncato a mano), prefisso di discovery diverso da homeassistant, unique_id mancante quando c’è il blocco device.

Connessione rifiutata con stato 4 o 5. I codici restituiti da mqtt.state() seguono la specifica: 4 indica nome utente o password errati, 5 un client non autorizzato. Va controllato l’utente creato per il broker. Lo stato −2 indica invece che la connessione TCP non è riuscita: indirizzo sbagliato, broker spento o porta bloccata.

Disconnessioni ogni pochi secondi. Due schede con lo stesso client ID si scacciano a vicenda; oppure il loop() contiene attese lunghe e mqtt.loop() non viene chiamato per più di 1,5 volte il keepalive, così il broker chiude la connessione.

Entità “non disponibili” anche se la scheda funziona. Il topic di availability_topic nella discovery non coincide con quello su cui si pubblica online, oppure online non è retained e Home Assistant, riavviato, non lo ha mai visto.

Letture di temperatura assurde. Sensore collegato a un pin dell’ADC2 (inutilizzabile con il Wi-Fi), TMP36 montato al contrario (si scalda e può danneggiarsi: staccare subito l’alimentazione) o condensatore di disaccoppiamento assente con cavi lunghi.

Entità duplicate dopo una modifica. Cambiando unique_id o object_id resta la vecchia configurazione retained sul broker: va cancellata pubblicando un payload vuoto retained sul vecchio topic.

Checklist per un dispositivo MQTT con Home Assistant

 1. Broker raggiungibile in rete locale; utente dedicato; porta 1883 non esposta su Internet.
 2. Client ID unico per scheda (derivato dal MAC).
 3. setBufferSize() >= 5 + 2 + topic + payload del messaggio più grande.
 4. Discovery retained, con unique_id, device e availability_topic.
 5. Sottoscrizione a homeassistant/status: ripubblicare discovery e stati su "online".
 6. LWT "offline" retained; "online" retained subito dopo la connessione.
 7. Stati degli attuatori retained, misure non retained.
 8. Nessun ciclo di attesa: riconnessione a stati con backoff, mqtt.loop() sempre chiamato.
 9. Sensori analogici su ADC1 (GPIO32-39) con il Wi-Fi attivo.
10. Prova con mosquitto_sub prima di cercare il problema in Home Assistant.

Fonti e verifiche

Il codice di questo articolo è stato compilato con arduino-cli 1.3.1, il core esp32:esp32 3.3.12, PubSubClient 2.8 e ArduinoJson 7.4.2; la logica dei messaggi e della riconnessione è stata eseguita in un test su PC (g++) e lo sketch è stato avviato nell’emulatore QEMU, che non emula la rete. La prova su hardware reale va eseguita con la checklist fornita. I limiti di PubSubClient sono stati letti nel sorgente della libreria.

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