Blog
Tutorial ESP32 WiFiManager per la configurazione del WiFi
Se hai mai spedito un progetto ESP32 con credenziali WiFi codificate, sai già cosa succede dopo. Funziona benissimo sul tuo banco di lavoro, connesso alla tua rete domestica e poi va al cliente, o in un edificio diverso, o in un paese diverso, e improvvisamente diventa un mattone finché qualcuno non lo riprogramma. Questo è uno dei mal di testa più comuni nello sviluppo di prodotti IoT, ed è anche uno dei più evitabili. Questo è esattamente il problema che WiFiManager è stato creato per risolvere.
Quindi, entriamo nel vivo: cos'è, come funziona realmente "sotto il cofano" e come puoi farlo funzionare nel tuo progetto ESP32, partendo da una rapida verifica dell'installazione fino ad arrivare al tipo di configurazione che vorresti effettivamente distribuire.
Perché le credenziali codificate in modo fisso non vanno bene
Abbiamo tutti scritto questa frase almeno una volta:
WiFi.begin("MyHomeNetwork", "password123");
E per trafficare sul banco, non c'è niente di male. Ma nel momento in cui il tuo progetto deve lasciare il banco, questo approccio inizia a causare veri problemi:
- Nessuna flessibilità per chi lo utilizza. Chiunque installi il dispositivo deve conoscere l'SSID e la password esatti prima ancora di flasharlo, altrimenti sarà necessario un accesso fisico in seguito solo per modificare un'impostazione.
- È un rischio per la sicurezza. Le credenziali incorporate nel firmware sono lì in chiaro, pronte per chiunque analizzi il binario.
- Non è scalabile. Hai dieci unità che vanno in dieci siti diversi? Sono dieci diverse compilazioni di firmware, o un sacco di riconfigurazioni manuali.
Quello che vogliamo veramente è che il dispositivo chieda semplicemente all'utente finale i dettagli del WiFi, li salvi e si riconnetta automaticamente ogni volta che si avvia senza che noi dobbiamo più toccare il codice. Questo è il gap che WiFiManager colma, e lo fa molto bene.
Cos'è WiFiManager
WiFiManager è una libreria open-source, originariamente scritta da tzapu e ora mantenuta da tablatronix, che offre al tuo progetto ESP32 (o ESP8266) un modo autonomo e basato sul web per configurare il WiFi. Invece di codificare le credenziali, il dispositivo si avvia in modalità Access Point, trasmette la propria piccola rete WiFi e mostra una semplice pagina web dove l'utente può scegliere la propria rete da un elenco scansionato e digitare la password.
Una volta che l'utente preme salva, WiFiManager scrive le credenziali nella memoria flash e tenta di connettersi. Da quel momento in poi, ogni volta che il dispositivo si avvia, prova prima quelle credenziali salvate e ritorna alla modalità di configurazione solo se la connessione fallisce. Questo intero schema è chiamato captive portal, e quasi certamente ci sei già incappato: è lo stesso trucco che fa apparire una pagina di login non appena ti connetti al WiFi di un hotel o di un aeroporto.
Come funziona il WiFiManager ESP32
La Fondazione: Modalità WiFi ESP32
La radio da 2.4 GHz dell'ESP32 può funzionare in tre diverse modalità:
- Modalità Stazione (STA): L'ESP32 funziona come un normale client WiFi, connettendosi al tuo router proprio come farebbe il tuo laptop o telefono.
- Modalità Access Point (AP): l'ESP32 crea la propria rete, quindi altri dispositivi possono connettersi direttamente ad essa.
- Modalità Dual (AP+STA): ed è qui che diventa intelligente: l'ESP32 può trasmettere la propria rete mentre contemporaneamente cerca o si connette a un altro router.
Quando il dispositivo si avvia in un luogo nuovo senza credenziali salvate, WiFiManager lo mette in modalità AP e inizia a trasmettere un SSID, qualcosa come ESP32-Setup. Questo dà al telefono un modo per entrare: un ponte diretto all'hardware prima ancora che venga toccato da Internet.
L'Intercettazione: Redirezione DNS
Okay, quindi il tuo telefono si è unito alla rete dell'ESP32. Come lo portiamo sulla pagina di configurazione senza far scrivere manualmente un indirizzo IP a qualcuno? Dirottiamo il DNS.
Normalmente, quando digiti un URL nel tuo browser, un server DNS lo traduce in un indirizzo IP dietro le quinte. Durante la modalità di configurazione, l'ESP32 esegue il suo piccolo server DNS, ma invece di rispondere correttamente, risponde a ogni singola richiesta con il proprio indirizzo, di solito 192.168.4.1. Non importa se il tuo telefono sta cercando google.com o qualsiasi altra cosa; la risposta è sempre “io”.”
La Trappola: Portali Captive
Quel trucco DNS è esattamente ciò che fa accadere la magia del portale captive. E l'hai già visto, probabilmente senza rendertene conto: quando ti connetti al WiFi di un aeroporto o di un hotel.
I telefoni e i laptop moderni controllano automaticamente, nel momento in cui si connettono a una nuova rete, se tale rete necessita di un accesso. I dispositivi Apple, ad esempio, contattano silenziosamente un indirizzo specifico in background per scoprirlo. Poiché il nostro ESP32 intercetta ogni richiesta DNS, cattura anche quel controllo in background. Invece della risposta prevista, restituisce la nostra pagina di configurazione HTML personalizzata. Il sistema operativo del telefono la vede e apre immediatamente una finestra del browser. Nessuno deve cercare un indirizzo IP; appare semplicemente.
Salvataggio per dopo: Archiviazione non volatile (NVS)
Una volta che qualcuno inserisce i dettagli del proprio WiFi e preme “Salva”, l'ESP32 ha bisogno di un modo per ricordarli, anche dopo che l'alimentazione è stata interrotta.
Le schede più vecchie si basavano sull'EEPROM per questo, ma l'ESP32 utilizza qualcosa di più recente chiamato NVS, o Non-Volatile Storage. Pensala come un semplice archivio chiave-valore, inserito nella sua partizione dedicata della memoria flash.
L'SSID e la password vengono scritti come valori stringa sotto chiavi specifiche. La prossima volta che il dispositivo si avvia, il firmware controlla prima la NVS e, se trova qualcosa di valido, salta tutta la procedura di Access Point e si connette silenziosamente in modalità Station. Nessun portale, nessun problema, solo un normale avvio.
Vincoli professionali: considerazioni sulla memoria
Ecco un utile paragone: è un po' come applicare le regole di Design for Manufacturing a un layout di PCB per risparmiare spazio sulla scheda. Devi gestire la memoria del tuo firmware nello stesso modo attento.
Eseguire contemporaneamente un Access Point, un server web e un server DNS consuma una buona parte della RAM dell'ESP32. Lasciare in esecuzione questi servizi dopo essersi già connessi sta privando la tua applicazione effettiva della memoria di cui potrebbe aver bisogno.
La mossa migliore per qualsiasi cosa in produzione è smantellare quei servizi di configurazione nel momento in cui si ottiene una connessione riuscita. Arresta i server web e DNS, libera le loro risorse una volta che autoConnect() ritorna, e recupererai quell'heap per le cose che contano davvero: campionare sensori, eseguire inferenze, gestire la gestione dell'alimentazione, qualunque cosa il tuo progetto debba fare.
Come installare WiFiManager su ESP32
Se stai usando l'Arduino IDE o PlatformIO, installarlo è indolore.
Arduino IDE: apri il Library Manager (Sketch > Includi Libreria > Gestisci Librerie), cerca “WiFiManager by tzapu” e installa l'ultima versione, attualmente la 2.0.17.
- Fai clic sul gestore della libreria
- Digita WiFiManager e installa WiFiManager di tzapu
Prima di iniziare a configurare parametri personalizzati e persistenza NVS, vale la pena verificare che funzioni innanzitutto il minimo indispensabile. La libreria include un esempio che fa proprio questo, cerca File > Examples > WiFiManager > Basic
Flashalo, e presumendo che non ci sia alcuna rete salvata, il tuo telefono dovrebbe offrirti immediatamente di connetterti a “ESP32-Setup” e la pagina di configurazione dovrebbe apparire subito. Una volta che hai confermato che funziona, sei pronto per costruire la versione completa.
Una cosa che vale la pena sapere: ci sono una manciata di fork di WiFiManager che circolano nell'ecosistema, alcune con correzioni aggiuntive specifiche per ESP32 integrate. Quindi, se riscontri problemi di compatibilità su un core ESP32 più recente, vale la pena ricontrollare esattamente quale fork hai effettivamente estratto.
Configurazione di ESP32 WiFiManager Pronta per la Produzione
Una chiamata autoConnect() "nuda" è ottima per dimostrare il concetto, ma una distribuzione reale di solito richiede qualcosa in più: campi personalizzati come l'indirizzo del server MQTT, un modo per cancellare le credenziali salvate senza dover riflashare e un timeout sensato in modo che il dispositivo non rimanga in modalità di configurazione per sempre, consumando la batteria.
Ecco uno schizzo completo che gestisce tutti e tre, costruito attorno a tre pezzi che lavorano insieme.
- Gestione della memoria. Anziché disperdere le letture e le scritture della memoria flash in tutta la setup(), le abbiamo nascoste nelle funzioni di supporto loadConfig() e saveConfig(). In questo modo, è immediatamente evidente, a colpo d'occhio, quali parti del codice stanno accedendo allo storage persistente:
- Il portello di fuga. Prima di toccare il WiFi in assoluto, controlliamo prima un pulsante di reset fisico. Questo è più importante di quanto possa sembrare: se lo stack WiFi si bloccasse da qualche parte in seguito, un utente senza altre vie d'uscita ha bisogno di un modo garantito per uscirne. Il controllo delle sovrascritture hardware prima di qualsiasi altra cosa significa che quel percorso non potrà mai essere bloccato da qualunque cosa venga dopo:
- Il flusso di configurazione. Il flusso in sé è bello e lineare: carica ciò che è salvato, passalo al portale come valori predefiniti, prova a connetterti, e questa parte è importante: scrivi di nuovo sulla memoria flash solo se l'utente ha effettivamente modificato qualcosa: non ha senso bruciare un ciclo di scrittura sulla memoria flash solo per rieseguire il salvataggio di ciò che era già lì:
Riunendo tutto, si ottiene un flusso di provisioning completo e autonomo: controlla un reset manuale, carica tutto ciò che è già stato salvato, permette all'utente di vederlo e sovrascriverlo tramite un portale captive, si connette e salva solo ciò che è effettivamente cambiato. Nessun servizio cloud, nessuna app companion e niente al di fuori del dispositivo stesso.
Errori comuni di WiFiManager ESP32
Alcune cose mettono spesso in difficoltà le persone con WiFiManager, tanto che vale la pena segnalarle prima che le incontri tu stesso:
- Il portale captive non compare sempre automaticamente. Alcune versioni di Android e i telefoni gestiti dall'azienda ritardano o disattivano quel rilevamento. Stampare sempre l'indirizzo IP del portale (192.168.4.1 per impostazione predefinita) sulla console seriale, in modo che qualcuno possa accedervi manualmente se il popup non compare mai.
- autoConnect() blocca di default. Mentre il dispositivo è in modalità AP, il resto del codice setup() non verrà eseguito. Se hai bisogno che altre cose accadano durante il provisioning, considera invece la modalità non bloccante di WiFiManager.
- NVS può corrompersi dopo un aggiornamento del core. L'aggiornamento del core Arduino ESP32 sposta occasionalmente la disposizione della partizione NVS e le vecchie credenziali iniziano a essere lette come spazzatura. Una cancellazione pulita di NVS o una chiamata difensiva a resetSettings() in caso di connessione fallita è più sicura che dare per scontato che i vecchi dati siano ancora validi.
- Proteggi con password il tuo AP. Per impostazione predefinita, quella rete di configurazione è spalancata. Chiunque si trovi nelle vicinanze può connettersi e visualizzare o modificare le impostazioni del tuo WiFi. Passa una password come secondo argomento a autoConnect() e quella porta si chiude.
WiFiManager è giusto per il tuo progetto ESP32
Per la maggior parte dei progetti consumer e dei prodotti commerciali a piccole tirature, WiFiManager offre un ottimo punto di equilibrio: zero dipendenze esterne, un flusso di configurazione che le persone già conoscono dal WiFi di hotel e aeroporti, e pochissimo codice da integrare.
Detto ciò, non è la soluzione giusta per tutto. Per implementazioni industriali headless, pensa a un dispositivo imbullonato a un muro senza schermo e senza facile accesso fisico, probabilmente è meglio usare una rete di fallback codificata in modo fisso più un percorso di provisioning remoto tramite BLE o un'API backend, piuttosto che contare su qualcuno che si avvicini e colleghi il proprio telefono all'AP del dispositivo. E se stai già utilizzando ESP-IDF invece di Arduino, vale la pena confrontarlo con il provisioning WiFi nativo di Espressif, che aggiunge il provisioning basato su BLE accanto al solito approccio SoftAP/captive-portal e tende a integrarsi più naturalmente in una codebase IDF esistente.
Ma per tutto ciò che sta nel mezzo tra i progetti dei maker, le piccole startup hardware, il problema “questa cosa deve funzionare nelle case di dieci clienti diversi senza dieci diverse build di firmware’, il WiFiManager è ancora uno dei modi più semplici e collaudati per risolvere il provisioning WiFi sull'ESP32.
Considerazioni finali
Questo è la fine di questo tutorial ESP32 WiFiManager. Una volta che l'impostazione di base funzionerà, le credenziali WiFi codificate non faranno più parte del tuo flusso di lavoro di distribuzione ESP32.
Se riscontri problemi durante la realizzazione di un prodotto IoT basato su ESP32, puoi sempre discutere il tuo progetto con PCBCool. Abbiamo anche lanciato di recente un sistema di preventivazione online, rendendone più facile sia per le aziende che per i creatori ottenere preventivi per progetti di PCB e PCBA. Se hai un progetto correlato, sentiti libero di metterlo alla prova.
Domande frequenti
Sì, ma il firmware di produzione dovrebbe aggiungere la protezione della password dell'AP e altri controlli di sicurezza di base.
Sì. L'utente si connette alla rete di configurazione dell'ESP32 e inserisce i dettagli del WiFi tramite un portale captive basato su browser.
No. L'ESP32 WiFi standard supporta solo la banda a 2.4GHz, quindi il router di destinazione deve fornire una rete a 2.4GHz.
A: Può essere utilizzato con reti nascoste, ma gli SSID nascosti sono meno pratici perché gli utenti potrebbero dover inserire manualmente il nome della rete.
A: Non di solito. Le credenziali sono archiviate nella flash, quindi i progetti con requisiti di sicurezza più stringenti dovrebbero considerare la crittografia flash, la crittografia NVS o un altro metodo di provisioning sicuro.
No. Si raccomanda un timeout in modo che il dispositivo non rimanga in modalità di configurazione indefinitamente, specialmente per i prodotti alimentati a batteria.
Senza una password AP, chiunque si trovi nelle vicinanze potrebbe connettersi al portale di configurazione e potenzialmente modificare la configurazione del dispositivo.
Sì. Può essere esteso con campi personalizzati come server MQTT, ID del dispositivo, endpoint API o impostazioni del prodotto definite dall'utente.
A: Non sempre. Per implementazioni su scala industriale o per flotte, il provisioning BLE, l'integrazione nel cloud o il provisioning controllato dal backend potrebbero essere più adatti.
A: Di solito no, a condizione che la partizione NVS non venga cancellata o modificata durante il processo di aggiornamento.
A: Un pulsante di reset è utile quando il dispositivo è installato sul campo e l'utente ha bisogno di un modo affidabile per cancellare le credenziali WiFi senza riflashare il firmware.
WiFiManager è utilizzato principalmente in progetti in stile Arduino per ESP32; per i progetti ESP-IDF, le opzioni di provisioning WiFi native di Espressif potrebbero essere più adatte.
Sì. L'AP, il server DNS e il server web utilizzano la RAM, quindi il firmware di produzione dovrebbe arrestare i servizi di configurazione dopo che la connessione WiFi è completa.
A: Può essere utilizzata, ma il portale di configurazione dovrebbe avere un timeout perché la modalità AP consuma più energia rispetto al normale funzionamento a basso consumo.
Sì, e il nostro team di ingegneria può fornire supporto se sorgono problemi di progettazione o assemblaggio che necessitano di essere risolti prima della produzione.
Sam K lavora su sistemi elettronici embedded, con un focus sulla progettazione hardware, sviluppo PCB, programmazione firmware e integrazione di sistemi. Supporta anche l'ottimizzazione delle prestazioni e aiuta a trasformare idee di prodotti elettronici in soluzioni affidabili nel mondo reale.
