Provisioning Wi-Fi ESP32: captive portal, BLE, Improv
Provisioning Wi-Fi ESP32 a confronto: password nel codice, captive portal, BLE e SoftAP Espressif, Improv ed ESP-Touch, per sicurezza e setup da telefono.
- Autore
Mauro Brambilla- Pubblicato
- Tempo di lettura
- 9 min
- Categoria
- Confronti

In breve
Per una scheda che un estraneo configura dal telefono, il captive portal non richiede app ma manda la password in chiaro. La Security 1 o 2 di Espressif la cifra, e Improv va bene per una scheda su USB.
Il provisioning Wi-Fi dell'ESP32 è il modo in cui una scheda impara nome e password della tua rete senza che siano compilati nel firmware. I metodi più diffusi sono le credenziali nel codice, il captive portal, il provisioning BLE o SoftAP di Espressif, Improv ed ESP-Touch. Per una scheda che qualcuno configura dal telefono io sceglierei il captive portal, a meno che la password non vada cifrata.
In questo articolo li confronto per fatica di setup, sicurezza, memoria e recupero. La parte sul portal viene dal sorgente di gizmo-common, che gira in ogni dispositivo OpenGizmo, il resto dalla documentazione di Espressif, Improv e WiFiManager linkata qui sotto. BLE, Improv ed ESP-Touch non li ho provati su hardware per questo articolo, quindi quelle sezioni descrivono documenti, non test.
Cos'è il provisioning Wi-Fi, e perché non scrivere la password nel codice?
Provisioning significa far arrivare le credenziali a una scheda che non ne ha. Scriverle nel codice è la versione a fatica zero: metti WiFi.begin("name", "password") nel sorgente e fai il flash. Va bene per una scheda che userai solo tu, su una sola rete, e smette di funzionare appena il router cambia. In più lascia la password nel file sorgente e nel binario del firmware, quindi non puoi pubblicare né condividere nessuno dei due così com'è.
Questo secondo punto è il motivo per cui ogni progetto condiviso ha bisogno di una risposta migliore. Il firmware precompilato, come le immagini che installa il flasher da browser, deve essere identico per tutti, quindi le credenziali devono arrivare dopo il flash.

Quali sono le opzioni per il provisioning Wi-Fi dell'ESP32?
| Metodo | Come arrivano le credenziali | Cosa serve all'utente | Protezione in transito |
|---|---|---|---|
| Nel codice | Compilate nel firmware | Codice sorgente, toolchain | Non vengono inviate; stanno nel binario |
| Captive portal | Modulo web servito dalla scheda sul proprio hotspot | Qualsiasi telefono o portatile con un browser | Nessuna se l'hotspot è aperto; WPA2 se imposti una password per l'hotspot |
| Provisioning unificato Espressif | BLE (GATT) o SoftAP con un server HTTP | L'app di esempio di Espressif, o una tua | Security 0: nessuna. Security 1: AES-256-CTR. Security 2: AES-256-GCM |
| Improv Serial o BLE | Pacchetti binari su seriale USB o Bluetooth LE | Chrome o Edge (non su iOS) per le demo web, oppure un'app | Non descritta nella specifica |
| ESP-Touch (SmartConfig) | Un'app per telefono trasmette le credenziali in broadcast, la scheda ascolta | App per telefono (Espressif ne pubblica una per Android) | AES facoltativo in ESP-Touch v2 |
Ecco cosa c'è dietro ogni riga.
Captive portal (e WiFiManager)
La scheda apre un suo hotspot e serve una pagina di setup. WiFiManager fa la stessa cosa quando la scheda non riesce a entrare in una rete salvata: passa in modalità access point e avvia un server DNS e un web server, e il repository chiama il risultato captive portal. Il README dice che la documentazione è obsoleta, e copre sia ESP8266 sia ESP32. gizmo-common è la versione OpenGizmo della stessa idea, scritta per le web app dei nostri progetti. Come si apre il popup e perché a volte non succede è spiegato in Captive portal ESP32 che non si apre? Come sistemare il popup Wi-Fi.
Il provisioning unificato di Espressif
L'Unified Provisioning di ESP-IDF è un framework, non una pagina: trasporta le credenziali, ed eventualmente altre impostazioni, via BLE (GATT) oppure SoftAP più HTTP. Espressif elenca app di provisioning per Android e iOS con il codice sorgente, e uno strumento Python, esp_prov, per il debug. La pagina attuale della documentazione rimanda al componente network_provisioning per il codice della libreria e gli esempi. Il trasporto BLE occupa circa 110 KB di RAM a runtime, secondo la stessa pagina, e buona parte si può recuperare se poi smetti di usare il BLE. Il core Arduino-ESP32 lo avvolge in WiFiProv, con uno schema SoftAP e uno BLE.
Improv
Improv Wi-Fi è uno standard aperto con due trasporti, Serial e Bluetooth LE, e dice che entrambi si possono usare da un browser. La specifica seriale definisce pacchetti che iniziano con IMPROV e comandi come l'invio delle impostazioni Wi-Fi e la scansione delle reti. ESPHome lo include come componente improv_serial, e ESP Web Tools è nell'elenco di chi lo adotta sul sito di Improv. L'SDK C++ ha licenza Apache-2.0, e il suo README mette la documentazione del codice tra le cose da fare.
ESP-Touch
ESP-Touch, chiamato anche SmartConfig, funziona al contrario: l'app sul telefono conosce già la rete e la manda alla scheda. Nella libreria Android di Espressif all'app vengono dati SSID, BSSID e password dell'access point, e il task può usare pacchetti broadcast o multicast. ESP-Touch v2 non è compatibile con l'originale. La pagina SmartConfig di ESP-IDF dice che la v2 supporta la cifratura AES con una chiave da 16 byte. Dice anche di fermare il task al termine per liberare memoria.
Qual è il metodo più semplice per l'utente?
Il più semplice è quello che non chiede nulla che l'utente non abbia già. Per un captive portal basta il browser del telefono. Collegarsi a un hotspot è un gesto che la gente conosce da hotel e bar, e su questo punta tutto il meccanismo. Ha un punto debole: è il telefono a decidere se aprire la pagina di accesso, e certi telefoni non lo fanno.
Il provisioning BLE è più fluido in un punto. Espressif fa notare che sia su Android sia su iOS l'app può trovare la scheda e connettersi senza uscire dall'app, mentre con il provisioning SoftAP gli utenti iOS vengono mandati nelle Impostazioni di sistema per collegarsi alla rete della scheda. Il prezzo è l'app: qualcuno deve realizzarla, pubblicarla e mantenerla, oppure l'utente installa quella generica di Espressif.
Improv Serial è il più comodo quando la scheda è già collegata al computer, perché una pagina come quella di ESP Web Tools può mostrare il dispositivo e mandare le impostazioni Wi-Fi sullo stesso cavo. Non serve a niente per una scheda dimenticata in un cassetto dall'altra parte della casa. Il sito di Improv dice che le sue demo web richiedono Chrome o Edge e non girano su iOS.
ESP-Touch non ha bisogno di un hotspot, ma all'utente serve comunque un'app che fornisca nome e password della rete. Non ho trovato una fonte primaria sul suo comportamento con le reti a 5 GHz, quindi non so dire come fallisca in quel caso.

Quanto è sicuro ciascun metodo?
Qui sicurezza significa una cosa sola: qualcuno vicino alla scheda può leggere o sostituire le credenziali mentre viaggiano? La documentazione di Espressif è la più esplicita. Ci sono tre schemi:
- Security 0: "No security (No encryption)."
- Security 1: scambio di chiavi Curve25519 con cifratura AES-256-CTR. Ha una modalità autorizzata che usa una stringa proof of possession (PoP), un segreto per dispositivo che l'utente inserisce nell'app, e una modalità senza.
- Security 2: derivazione delle chiavi SRP6a con AES-256-GCM, basata su un nome utente e una password che dai tu all'app del telefono in qualche modo, per esempio con l'adesivo di un codice QR.
Per il SoftAP, Espressif suggerisce anche WPA2 con una passphrase univoca per ogni dispositivo. Un dettaglio da controllare nel core Arduino: la funzione beginProvision nell'header WiFiProv.h usa come proof of possession predefinita "abcd1234", quindi impostane una tua prima di distribuire la scheda.
Improv è più scarno. Nella specifica BLE la password viaggia come byte in chiaro nella characteristic dei comandi RPC, e la pagina non descrive né pairing né cifratura, quindi l'eventuale protezione dipende dal tuo stack BLE. Aggiunge un passaggio di autorizzazione facoltativo: un dispositivo può aspettare un'interazione fisica prima di accettare le credenziali, e l'autorizzazione scade dopo un timeout che la specifica suggerisce di un minuto. Il checksum intercetta solo gli errori accidentali.

Un captive portal aperto non ha nessuna protezione, e preferisco dirlo piuttosto che nasconderlo. L'hotspot di gizmo-common parte con WiFi.softAP(setupOptions.accessPointName), senza password, quindi le credenziali viaggiano in HTTP semplice. Questo significa che chiunque sia nel raggio radio della scheda durante il setup potrebbe, in linea di principio, leggerle. L'ho ricavato dal codice e non ho provato a catturare il traffico. Due cose limitano l'esposizione: l'hotspot si apre solo quando non c'è una rete funzionante (il firmware lo tiene attivo per due minuti dopo il ritorno del Wi-Fi, così il telefono può vedere il risultato), e finché è attivo rispondono solo quattro percorsi API (/api/networks, /api/connect, /api/check-connection e /api/device), come mostra il codice di guardRequest. Per WiFiManager l'access point si può e si deve proteggere con una password ("can and should"); con una password nota il traffico è almeno cifrato WPA2 via radio.
Come si salvano le credenziali e come si rimedia a una password sbagliata?
Salvare è la metà facile. La metà difficile è un errore di battitura: se la scheda sovrascrive una rete funzionante con una password sbagliata, resta offline e non ha modo di dirlo.
gizmo-common lo gestisce in wifi_setup.cpp. Le nuove credenziali restano in RAM e si provano per prime. Vengono scritte in NVS (l'archivio chiave-valore della flash dell'ESP32, namespace gizmo-wifi, chiavi ssid e password) solo quando la connessione funziona. Se il tentativo fallisce dopo 12,5 secondi, la scheda le scarta, torna alla rete salvata e riapre l'hotspot. Nel codice che ho letto non ho trovato nessuna cifratura di NVS, quindi la password salvata sta nella flash come testo semplice.
Per un reset voluto, l'utente può tenere premuto il pulsante BOOT della XIAO ESP32-S3 per 10 secondi, oppure premere Forget network nella web app, come descrivono il README di gizmo-common e la guida per sistemare il captive portal. Qualunque metodo scelga, fagli sempre la stessa domanda: cosa succede quando la password è sbagliata, e l'utente può rimediare senza un computer? Improv ha nella specifica un errore dedicato "unable to connect", e ESP-Touch si arrende dopo un timeout che la pagina SmartConfig indica tra 15 e 255 secondi.
I 5 GHz rompono qualcuno di questi metodi?
L'ESP32-S3 della scheda XIAO non ha una radio a 5 GHz, come spiegato nella guida all'acquisto degli ESP32, dove solo l'ESP32-C5 è dual band. Un metodo che fa la scansione dalla scheda, come il portal o la scansione di Improv, elenca solo ciò che la scheda riesce a sentire. La pagina Wi-Fi della web app ha proprio questo stato per una scansione vuota: "No networks found yet", con un pulsante Scan again (vedi docs/screenshot-wifi.png nel repository di Gizmo Ticker). Se il router unisce le due bande sotto un solo nome, la scheda di solito riesce comunque a entrare sulla parte a 2,4 GHz. Se le chiama in modo diverso, scegli il nome a 2,4 GHz.
Quale metodo ha scelto OpenGizmo, e perché?
Tutti e tre i progetti OpenGizmo, il Gizmo Ticker, il Gizmo Reolink Switch e la Gizmo Camera, usano il captive portal. Nei tre repository del firmware non ho trovato codice Improv, provisioning BLE o ESP-Touch. Queste sono le ragioni che posso indicare nel codice:

- La web app esiste già. Ogni scheda serve la propria web app, e la pagina di setup
/ap-setupne fa parte, quindi il portal non costa un nuovo front end. - Nessuna app da pubblicare. Il setup si fa con qualsiasi cosa abbia un browser, su qualsiasi telefono o portatile.
- Tentativi sicuri. Le credenziali si salvano solo dopo che si connettono, e un hotspot che si riapre in caso di errore è la via di recupero.
- Reset a mano. Il pulsante BOOT, o Forget network nella web app, riporta il portal.
I costi sono quelli visti sopra: un hotspot aperto, HTTP semplice e un telefono che potrebbe non aprire il popup. Li ho accettati perché l'hotspot si apre solo mentre la scheda non ha rete e l'unica cosa che viaggia è la password del Wi-Fi. Se spedissi qualcosa che gestisce un segreto di più valore della password del Wi-Fi di casa, passerei alla Security 2 di Espressif su BLE.
Quindi quale metodo usare?
Usa le credenziali nel codice per una scheda di prova usa e getta. Usa un captive portal quando chiunque abbia un telefono deve poter configurare la scheda e un hotspot aperto è accettabile. Usa il provisioning unificato di Espressif con Security 1 o 2 quando controlli l'app e vuoi la cifratura. Usa Improv Serial quando la scheda è comunque su USB. ESP-Touch ha senso solo se distribuisci già la sua app.
Il limite di questo confronto è che ho letto le specifiche e il codice, e non ho misurato tempi di setup, consumo della batteria o dimensione della flash di nessuno di questi metodi. Se il tuo captive portal non si apre su un telefono, vai alla guida per sistemare il captive portal, e se la scheda è configurata ma il suo nome .local non si risolve, il problema successivo è mDNS su Android. Per vedere tutto il flusso del dispositivo, leggi la panoramica di OpenGizmo.
Domande frequenti
Trova risposte rapide alle domande più comuni su questo argomento.
Il provisioning Wi-Fi è il passaggio in cui un ESP32 impara nome e password della tua rete Wi-Fi senza che siano scritti nel firmware. L'utente invia le credenziali da un telefono o da un computer, e la scheda le salva nella memoria flash e si connette. I metodi più comuni sono captive portal, Bluetooth LE, Improv ed ESP-Touch.
Autore
Mauro BrambillaPronto a costruire il tuo gizmo?
Scegli un progetto ESP32 open source e segui la sua guida passo passo, dalla lista dei componenti e dai collegamenti fino al firmware e al primo avvio.





