ESP32 captive portal non si apre? Come sistemare il popup

Perché il popup del captive portal dell'ESP32 non si apre su Android, iPhone o Windows: DNS, URL di probe, redirect 302 e i controlli che lo sistemano.

Pubblicato
Tempo di lettura
8 min
Un maker con gli occhiali indica un telefono che mostra un elenco Wi-Fi con la rete Gizmo-Setup e un popup vuoto, accanto a una scheda ESP32 sulla scrivania.

In breve

Un captive portal su ESP32 ha bisogno di due cose: un DNS che risponde a ogni nome con l'IP della scheda e un redirect HTTP per l'URL di probe. Se il popup non si apre, controlla prima queste due.

Un captive portal su ESP32 non si apre quando il controllo di connettività del telefono riceve una risposta dall'aspetto normale invece di un redirect. La scheda ha bisogno di un server DNS che risponde a ogni nome con il proprio IP e di un web server che reindirizza la richiesta di probe alla pagina di setup. Senza entrambi, Android, iOS e Windows credono che la rete sia a posto e non mostrano niente.

Questa guida segue quello che la libreria gizmo-common fa davvero, perché ogni dispositivo OpenGizmo (il Gizmo Ticker, il Gizmo Reolink Switch e la Gizmo Camera) apre così il suo primo setup Wi-Fi. Ho letto il suo codice sorgente e le fonti di Android, Apple, Microsoft e Arduino-ESP32 linkate qui sotto, e segnalo quello che non ho potuto verificare. Proprio ora la tua scheda non ne vuole sapere di mostrare il popup? Salta alla checklist più in basso e torna qui per il perché.

Come funziona un captive portal su ESP32?

Un captive portal è una pagina web che il telefono apre da solo quando si unisce a una rete Wi-Fi che non ha accesso a Internet finché non fai il login. Succede negli hotel. Un ESP32 può fare lo stesso trucco per la sua pagina di setup, senza nessun cloud di mezzo. La sequenza è breve:

  1. L'ESP32 avvia un access point (un hotspot) e un server DNS sulla porta 53.
  2. Il telefono si unisce all'hotspot e invia un probe: una richiesta DNS e poi una richiesta HTTP verso un indirizzo noto.
  3. Il server DNS risponde con l'IP dell'ESP32, qualunque nome sia stato chiesto.
  4. Il web server risponde al probe con un redirect alla pagina di setup.
  5. Il telefono vede che la risposta non è quella che si aspetta e apre una finestra di accesso sulla pagina di setup.

Un telefono e un ESP32 che si scambiano una richiesta DNS, un probe HTTP e un redirect a /ap-setup, passo per passo

Il popup è una decisione del telefono, non tua. Non puoi spingergli una pagina: puoi solo dare al probe una risposta che faccia dire al telefono "serve un accesso". Per gli altri modi di dare il Wi-Fi a una scheda, vedi Provisioning Wi-Fi su ESP32: captive portal, BLE, Improv.

Quali URL richiedono Android, iPhone e Windows?

Ogni sistema operativo ha il suo probe, e ognuno considera "online" una risposta diversa. Tutto il resto, per loro, è un captive portal.

SORichiesta di probe (default)Risposta che significa onlineFonte
Androidhttp://connectivitycheck.gstatic.com/generate_204HTTP 204Configurazione AOSP NetworkStack
Windows 10 1607 e successivi, 11http://www.msftconnecttest.com/connecttest.txt200 con Microsoft Connect TestMicrosoft Learn, FAQ su NCSI
iOS e macOShttp://captive.apple.com/hotspot-detect.htmlUna pagina con SuccessHost nella documentazione Apple, percorso e pagina da segnalazioni della community

I default di Android sono nel file di risorse AOSP NetworkStack: il probe HTTP è http://connectivitycheck.gstatic.com/generate_204, con uno HTTPS su https://www.google.com/generate_204 e due di riserva. Nel NetworkMonitor.java dello stesso progetto, una risposta 200 con un body di 4 byte o meno non viene volutamente trattata come portal, e una risposta da portal senza header Location fa usare ad Android 12 e successivi l'URL del probe come pagina di accesso (il codice controlla SdkLevel.isAtLeastS()). I produttori di telefoni possono sostituire questi URL, quindi considera la tabella il comportamento di serie.

Microsoft documenta la sua parte nelle FAQ su NCSI: da Windows 10 build 14393 il probe è www.msftconnecttest.com/connecttest.txt, e un 200 il cui body non contiene il testo atteso, oppure un 302 o un 304, viene segnalato come hotspot che richiede un accesso.

Per Apple, l'unica fonte primaria che ho trovato è l'elenco di host di Apple Support per le reti aziendali, che indica captive.apple.com come usato per la "Internet connectivity validation for networks that use captive portals". Il percorso /hotspot-detect.html e la pagina Success vengono da articoli della community, quindi consideralo un dato ampiamente riportato, non una specifica Apple. Un ingegnere Apple conferma anche, in una risposta sul forum sviluppatori, che macOS tiene una rete captive fuori dalla route predefinita finché non pensa che il portal sia stato gestito.

Cosa risponde gizmo-common?

La libreria è abbastanza piccola da poterla leggere. Quando non c'è nessuna rete salvata, o un tentativo di connessione fallisce, avvia un hotspot aperto e un server DNS in startAccessPoint() di wifi_setup.cpp:

wifi_setup.cpp
wifi_setup.cpp
accessPointEnabled = WiFi.softAP(setupOptions.accessPointName);
// Answer every DNS name with the hotspot address, so phones open the setup page
dnsServer->start(DNS_PORT, "*", WiFi.softAPIP());
Riga 3, col. 1UTF-8cpp

DNS_PORT è 53 e "*" significa "ogni nome". Nel sorgente di DNSServer di Arduino-ESP32, un dominio vuoto o jolly corrisponde a tutto, le query A e ANY ricevono l'IP, e gli altri tipi come AAAA ricevono una risposta vuota. Quello è il branch master attuale: non ho controllato il core più vecchio che PlatformIO blocca con espressif32 @ 8.0.0.

La metà HTTP è handleCaptivePortalRequest(), chiamata per prima nel gestore not-found del web server. Tocca solo le richieste GET e HEAD che arrivano dall'hotspot, mai la pagina di setup, /api/ o i file della web app, e manda tutto il resto alla pagina di setup:

wifi_setup.cpp
wifi_setup.cpp
// Send everything else to the setup page
request->redirect(setupOptions.setupPagePath);
Riga 2, col. 1UTF-8cpp

La pagina di setup è /ap-setup in tutti e tre i progetti. In ESPAsyncWebServer 3.12.1, la versione che il ticker blocca nel suo platformio.ini, redirect() usa di default lo status 302. Quindi il probe della tabella qui sopra riceve un 302 e un header Location. Android vede un portal invece di un 204, Windows vede un 302 invece del suo file di testo, e il controllo di Apple non dovrebbe trovare nessuna pagina Success. Questo è tutto il trucco: nessuna route speciale /generate_204, un solo catch-all.

Una tabella dei probe di Android, Apple e Windows, della risposta che ognuno si aspetta e del singolo redirect 302 che l'ESP32 invia a tutti e tre

Due dettagli che aiutano più avanti. Le richieste dalla normale rete Wi-Fi non vengono mai reindirizzate, perché il controllo confronta l'IP locale del client con quello dell'hotspot. E attraverso l'hotspot rispondono solo quattro percorsi API (/api/networks, /api/connect, /api/check-connection, /api/device): il setup del Wi-Fi e i dettagli del dispositivo, nient'altro, perché chiunque sia nei paraggi può unirsi all'hotspot aperto. Per l'intero flusso in un dispositivo finito, vedi come è costruito il Reolink Switch e la panoramica di OpenGizmo.

Checklist: il popup non compare

Cambia una cosa alla volta e prova dopo ogni passo.

Un maker tiene un telefono con la rete Wi-Fi Gizmo-Ticker evidenziata e indica una scheda XIAO collegata a una matrice LED

1. L'hotspot c'è davvero?

L'hotspot si apre solo quando non c'è nessuna rete salvata, o quella salvata non riesce a connettersi (il tentativo di connessione scade a 12,5 secondi, secondo WIFI_CONNECT_TIMEOUT). Finché una rete salvata funziona, non ci sono né hotspot né portal. Compila l'ambiente debug (pio run -e debug -t upload, poi pio device monitor) e cerca Access point ready on http://.... Il firmware di release non stampa log.

Se hai flashato la scheda dal browser, ESP Web Tools: flashare un ESP32 dal browser spiega le build di release.

2. Il telefono si è unito davvero all'hotspot?

Molti telefoni preferiscono i dati mobili quando una rete Wi-Fi non ha Internet, e alcuni chiedono se restare connessi. Resta connesso, oppure spegni i dati mobili per il test. Su alcuni telefoni la richiesta di accesso può arrivare come notifica invece che come finestra, quindi guarda nella tendina delle notifiche prima di pensare che non sia successo niente. Non ho trovato una fonte primaria su come ogni produttore la formuli o la posizioni.

3. Apri a mano un indirizzo http://

Il README di gizmo-common dà lo stesso consiglio: mentre sei connesso all'hotspot, apri nel browser un qualsiasi indirizzo http:// e verrai reindirizzato. Se questo funziona ma il popup no, DNS e redirect vanno bene e di mezzo c'è solo la logica di probe del telefono. Usa HTTP semplice: il web server del firmware ascolta solo sulla porta 80 (AsyncWebServer server(80) in ogni progetto), quindi un indirizzo https:// non può essere reindirizzato.

4. Elimina ciò che intercetta la richiesta DNS

Una VPN o un'app che forza il proprio resolver DNS, oppure l'impostazione di DNS sicuro di un browser, possono far passare la richiesta lontano dal tuo server DNS jolly, e il telefono non raggiunge mai la scheda. Non ho trovato una fonte primaria sulla modalità DNS privato di Android, quindi la indico come causa probabile, non misurata. Spegni la VPN e il DNS privato per il setup, poi riaccendili.

5. Controlla lo status code del probe

Da un laptop collegato all'hotspot, nslookup example.com dovrebbe restituire l'IP dell'hotspot, e curl -i http://connectivitycheck.gstatic.com/generate_204 dovrebbe stampare un 302 con Location: /ap-setup (l'ho ricavato dal codice e non l'ho provato su hardware). Un IP sbagliato indica il lato DNS. Un 204 significa che il tuo firmware, o qualcos'altro lungo il percorso, risponde da solo al probe, e il telefono penserà di essere online.

6. Se scrivi il tuo portal

Vale la regola di prima: il DNS risponde a ogni nome, e un percorso sconosciuto reindirizza alla tua pagina. Non inviare un 204 o la pagina Success attesa dalle tue route, o il telefono penserà di essere online e nasconderà il popup.

E la DHCP option 114 e la Captive Portal API?

La RFC 8910 definisce un modo per informare i client del portal, con la DHCPv4 option 114 e con un'opzione IPv6 Router Advertisement (tipo 37), che trasportano un URI. L'URI punta a un'API descritta nella RFC 8908, che risponde con application/captive+json su HTTPS con un flag captive e un user-portal-url facoltativo. Il NetworkMonitor di Android contiene già codice per quel content type, ma gizmo-common non invia la option 114, quindi i tre dispositivi OpenGizmo si affidano al redirect del probe. Non ho provato quella option su un ESP32.

Quanto resta acceso l'hotspot, e come lo riporti?

Quando la pagina di setup interroga /api/check-connection e riceve lo stato Connected, il firmware spegne l'hotspot. Se la rete salvata torna da sola, l'hotspot resta acceso per 120 secondi (ACCESS_POINT_SHUTDOWN_DELAY) e poi si spegne. Le nuove credenziali vengono provate per prime e salvate solo quando si connettono, quindi un errore di battitura non può sostituire una rete funzionante. La rete salvata sta in NVS, l'archivio chiave-valore nella memoria flash dell'ESP32.

Per far tornare il portal, tieni premuto il pulsante BOOT della XIAO ESP32-S3 per 10 secondi mentre il firmware gira (cancella anche le impostazioni del progetto), oppure premi Forget network nella web app. La ESP32-CAM non ha il reset con BOOT: il suo GPIO0 è anche il clock della camera, quindi usa la web app. Se raggiungi la scheda per nome dopo esserti unito al Wi-Fi, il problema successivo può essere mDNS, di cui parla ESP32 .local non funziona su Android.

Cosa è stato verificato, e i limiti

Il DNS jolly, il redirect 302, il timeout di 12,5 secondi e il ritardo di 120 secondi dell'hotspot sono letti direttamente da gizmo-common v2.5.1 (bloccata dal ticker e dal Reolink Switch; la camera blocca la v2.4.0, che non ho letto per questa guida) e da ESPAsyncWebServer 3.12.1; per questa guida non ho catturato pacchetti da un telefono vero. I probe di Android e Windows vengono dalla documentazione AOSP e Microsoft, l'host di Apple da Apple Support e il suo percorso solo da fonti della community, e i produttori di telefoni o le versioni dei sistemi operativi possono cambiare qualsiasi cosa. Se la checklist non ha sistemato il tuo popup, prova prima il passo 3: ti dice se il problema è la scheda o il telefono. Per un confronto con BLE e Improv, la guida ai metodi di provisioning è la tappa successiva.

Domande frequenti

Trova risposte rapide alle domande più comuni su questo argomento.

Il telefono apre la pagina di accesso solo se il controllo di connettività riceve una risposta diversa da quella attesa. Se il DNS dell'ESP32 non risponde a ogni nome con il proprio IP, o il web server risponde all'URL di probe con 204 o con la pagina sbagliata, il telefono pensa che la rete vada bene e non mostra nulla.

Pubblicato

Pronto 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.

Leggi anche

Esplora le categorie