ESP32 Captive Portal öffnet sich nicht? Popup reparieren

Warum sich das Captive-Portal-Popup des ESP32 auf Android, iPhone oder Windows nicht öffnet: DNS, Probe-URLs, 302-Weiterleitungen und wie du es behebst.

Veroffentlicht
Lesezeit
8 Min.
Ein Maker mit Brille zeigt auf ein Handy mit einer WLAN-Liste, dem Netzwerk Gizmo-Setup und einem leeren Popup, daneben ein ESP32-Board auf dem Schreibtisch.

Kurz gesagt

Ein Captive Portal auf dem ESP32 braucht zwei Dinge: ein DNS, das jeden Namen mit der Board-IP beantwortet, und eine HTTP-Weiterleitung für die Probe-URL. Öffnet sich das Popup nicht, prüfe zuerst diese beiden.

Ein ESP32 Captive Portal öffnet sich nicht, wenn der Verbindungstest des Handys eine normal aussehende Antwort statt einer Weiterleitung bekommt. Das Board braucht einen DNS-Server, der jeden Namen mit seiner eigenen IP beantwortet, und einen Webserver, der die Probe-Anfrage auf die Einrichtungsseite umleitet. Fehlt eines von beiden, halten Android, iOS und Windows das Netzwerk für in Ordnung und zeigen nichts an.

Diese Anleitung folgt dem, was die Bibliothek gizmo-common wirklich tut, denn jedes OpenGizmo-Gerät (der Gizmo Ticker, der Gizmo Reolink Switch und die Gizmo Camera) startet seine erste WLAN-Einrichtung auf diese Weise. Ich habe ihren Quellcode und die unten verlinkten Quellen von Android, Apple, Microsoft und Arduino-ESP32 gelesen, und ich sage dazu, was ich nicht prüfen konnte. Zeigt dein Board das Popup gerade jetzt nicht? Spring zur Checkliste weiter unten und komm für das Warum zurück.

Wie funktioniert ein Captive Portal auf dem ESP32?

Ein Captive Portal ist eine Webseite, die das Handy von selbst öffnet, wenn es sich mit einem WLAN verbindet, das erst nach einer Anmeldung Internet hat. Hotels machen das so. Ein ESP32 kann denselben Trick für seine eigene Einrichtungsseite nutzen, ganz ohne Cloud. Der Ablauf ist kurz:

  1. Der ESP32 startet einen Access Point (einen Hotspot) und einen DNS-Server auf Port 53.
  2. Das Handy verbindet sich mit dem Hotspot und sendet eine Probe: eine DNS-Abfrage und dann eine HTTP-Anfrage an eine bekannte Adresse.
  3. Der DNS-Server antwortet mit der IP des ESP32, egal welcher Name abgefragt wurde.
  4. Der Webserver beantwortet die Probe mit einer Weiterleitung auf die Einrichtungsseite.
  5. Das Handy merkt, dass die Antwort nicht die erwartete ist, und öffnet ein Anmeldefenster mit der Einrichtungsseite.

Ein Handy und ein ESP32 tauschen Schritt für Schritt eine DNS-Abfrage, eine HTTP-Probe und eine Weiterleitung auf /ap-setup aus

Das Popup ist die Entscheidung des Handys, nicht deine. Du kannst ihm keine Seite aufdrängen: Du kannst der Probe nur eine Antwort geben, bei der das Handy sagt "hier ist eine Anmeldung nötig". Für andere Wege, einem Board sein WLAN zu geben, siehe ESP32 WLAN-Provisioning: Captive Portal, BLE, Improv.

Welche URLs rufen Android, iPhone und Windows ab?

Jedes Betriebssystem hat seine eigene Probe, und jedes hält eine andere Antwort für "online". Alles andere ist für sie ein Captive Portal.

OSProbe-Anfrage (Standard)Antwort, die online bedeutetQuelle
Androidhttp://connectivitycheck.gstatic.com/generate_204HTTP 204AOSP-NetworkStack-Konfiguration
Windows 10 1607 und neuer, 11http://www.msftconnecttest.com/connecttest.txt200 mit Microsoft Connect TestMicrosoft Learn, NCSI-FAQ
iOS und macOShttp://captive.apple.com/hotspot-detect.htmlEine Seite mit SuccessHost in der Apple-Dokumentation, Pfad und Seite aus Community-Berichten

Die Standardwerte von Android stehen in der Ressourcendatei von AOSP NetworkStack: Die HTTP-Probe ist http://connectivitycheck.gstatic.com/generate_204, dazu kommen eine HTTPS-Probe auf https://www.google.com/generate_204 und zwei Ersatzprüfungen. In der NetworkMonitor.java desselben Projekts wird eine 200-Antwort mit einem Body von höchstens 4 Bytes bewusst nicht als Portal behandelt, und eine Portal-Antwort ohne Location-Header lässt Android 12 und neuer die Probe-URL als Anmeldeseite verwenden (der Code prüft SdkLevel.isAtLeastS()). Handyhersteller können diese URLs überschreiben, nimm die Tabelle also als Standardverhalten.

Microsoft dokumentiert seine Seite in der NCSI-FAQ: Seit Windows 10 Build 14393 ist die Probe www.msftconnecttest.com/connecttest.txt, und eine 200-Antwort, deren Body den erwarteten Text nicht enthält, oder eine 302 oder 304 wird als Hotspot gemeldet, der eine Anmeldung braucht.

Bei Apple ist die einzige Primärquelle, die ich gefunden habe, die Apple-Support-Liste der Hosts für Unternehmensnetzwerke. Sie nennt captive.apple.com als Host für die "Internet connectivity validation for networks that use captive portals". Der Pfad /hotspot-detect.html und die Seite Success stammen aus Community-Beiträgen, nimm sie also als weit verbreitete Angabe, nicht als Apple-Spezifikation. Ein Apple-Ingenieur bestätigt außerdem in einer Antwort im Entwicklerforum, dass macOS ein Captive-Netzwerk von der Standardroute fernhält, bis es das Portal für erledigt hält.

Was antwortet gizmo-common?

Die Bibliothek ist klein genug, um sie zu lesen. Gibt es kein gespeichertes Netzwerk oder schlägt ein Verbindungsversuch fehl, startet sie in startAccessPoint() in wifi_setup.cpp einen offenen Hotspot und einen DNS-Server:

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());
Zeile 3, Spalte 1UTF-8cpp

DNS_PORT ist 53, und "*" bedeutet "jeder Name". Im DNSServer-Quellcode von Arduino-ESP32 passt eine leere oder Platzhalter-Domain auf alles, A- und ANY-Abfragen bekommen die IP, und andere Typen wie AAAA bekommen eine leere Antwort. Das ist der aktuelle master-Branch: Den älteren Core, den PlatformIO mit espressif32 @ 8.0.0 festlegt, habe ich nicht geprüft.

Die HTTP-Hälfte ist handleCaptivePortalRequest(), das zuerst im Not-found-Handler des Webservers aufgerufen wird. Es betrifft nur GET- und HEAD-Anfragen, die über den Hotspot kommen, nie die Einrichtungsseite, /api/ oder die eigenen Dateien der Web-App, und schickt alles andere auf die Einrichtungsseite:

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

Die Einrichtungsseite ist in allen drei Projekten /ap-setup. In ESPAsyncWebServer 3.12.1, der Version, die der Ticker in seiner platformio.ini festlegt, nutzt redirect() standardmäßig den Status 302. Die Probe aus der Tabelle oben bekommt also eine 302 und einen Location-Header. Android sieht ein Portal statt einer 204, Windows sieht eine 302 statt seiner Textdatei, und Apples Prüfung sollte keine Success-Seite finden. Das ist der ganze Trick: keine spezielle Route /generate_204, ein einziger Catch-all.

Eine Tabelle mit den Probe-Anfragen von Android, Apple und Windows, der jeweils erwarteten Antwort und der einen 302-Weiterleitung, die der ESP32 für alle drei sendet

Zwei Details helfen später. Anfragen aus dem normalen WLAN werden nie umgeleitet, weil die Prüfung die lokale IP des Clients mit der des Hotspots vergleicht. Und über den Hotspot antworten nur vier API-Pfade (/api/networks, /api/connect, /api/check-connection, /api/device): die WLAN-Einrichtung und die Gerätedetails, sonst nichts, denn jeder in der Nähe kann dem offenen Hotspot beitreten. Den ganzen Ablauf in einem fertigen Gerät siehst du in Wie der Reolink Switch gebaut ist und im Überblick über OpenGizmo.

Checkliste: Das Popup erscheint nicht

Ändere immer nur eine Sache und teste nach jedem Schritt.

Ein Maker hält ein Handy mit hervorgehobenem WLAN Gizmo-Ticker und zeigt auf ein XIAO-Board, das mit einer LED-Matrix verkabelt ist

1. Gibt es den Hotspot überhaupt?

Der Hotspot öffnet sich nur, wenn kein Netzwerk gespeichert ist oder das gespeicherte sich nicht verbinden lässt (der Verbindungsversuch läuft nach 12,5 Sekunden ab, laut WIFI_CONNECT_TIMEOUT). Solange ein gespeichertes Netzwerk funktioniert, gibt es weder Hotspot noch Portal. Baue die Umgebung debug (pio run -e debug -t upload, dann pio device monitor) und such nach Access point ready on http://.... Die Release-Firmware schreibt keine Logs.

Hast du das Board aus dem Browser geflasht, erklärt ESP Web Tools: ESP32 aus dem Browser flashen die Release-Builds.

2. Hat sich das Handy wirklich mit dem Hotspot verbunden?

Viele Handys bevorzugen mobile Daten, wenn ein WLAN kein Internet hat, und manche fragen, ob sie verbunden bleiben sollen. Bleib verbunden oder schalte für den Test die mobilen Daten aus. Auf manchen Handys kommt die Anmeldeaufforderung als Benachrichtigung statt als Fenster, schau also in die Benachrichtigungsleiste, bevor du annimmst, es sei nichts passiert. Eine Primärquelle dazu, wie jeder Hersteller sie formuliert oder platziert, habe ich nicht gefunden.

3. Öffne von Hand eine http://-Adresse

Die README von gizmo-common gibt denselben Rat: Während du mit dem Hotspot verbunden bist, öffne im Browser irgendeine http://-Adresse, und du wirst weitergeleitet. Klappt das, aber das Popup nicht, sind DNS und Weiterleitung in Ordnung, und nur die Probe-Logik des Handys steht im Weg. Nimm einfaches HTTP: Der Webserver der Firmware lauscht nur auf Port 80 (AsyncWebServer server(80) in jedem Projekt), eine https://-Adresse lässt sich also nicht umleiten.

4. Entferne, was die DNS-Abfrage abfängt

Ein VPN oder eine App, die einen eigenen DNS-Resolver erzwingt, oder die Einstellung für sicheres DNS im Browser kann die Abfrage an deinem Platzhalter-DNS-Server vorbeileiten, sodass das Handy das Board nie erreicht. Zum privaten DNS-Modus von Android habe ich keine Primärquelle gefunden, daher nenne ich das eine wahrscheinliche Ursache, keine gemessene. Schalte VPN und privates DNS für die Einrichtung aus und danach wieder ein.

5. Prüfe den Statuscode der Probe

Von einem Laptop im Hotspot aus sollte nslookup example.com die IP des Hotspots liefern, und curl -i http://connectivitycheck.gstatic.com/generate_204 sollte eine 302 mit Location: /ap-setup ausgeben (das habe ich aus dem Code abgeleitet und nicht auf Hardware getestet). Eine falsche IP weist auf ein DNS-Problem hin. Eine 204 heißt, dass deine Firmware oder etwas anderes auf dem Weg die Probe selbst beantwortet, und das Handy glaubt, online zu sein.

6. Wenn du dein eigenes Portal schreibst

Behalte die Regel von oben bei: Das DNS beantwortet jeden Namen, und ein unbekannter Pfad leitet auf deine Seite um. Schick aus deinen eigenen Routen keine 204 und nicht die erwartete Success-Seite, sonst hält das Handy sich für online und blendet das Popup aus.

Und DHCP-Option 114 und die Captive-Portal-API?

RFC 8910 definiert einen Weg, Clients über das Portal zu informieren: in der DHCPv4-Option 114 und in einer IPv6-Router-Advertisement-Option (Typ 37), die einen URI tragen. Der URI zeigt auf eine in RFC 8908 beschriebene API, die über HTTPS application/captive+json mit einem captive-Flag und einer optionalen user-portal-url liefert. Der NetworkMonitor von Android enthält bereits Code für diesen Content-Type, aber gizmo-common sendet keine Option 114, daher verlassen sich die drei OpenGizmo-Geräte auf die Weiterleitung der Probe. Ich habe die Option nicht auf einem ESP32 getestet.

Wie lange bleibt der Hotspot an, und wie holst du ihn zurück?

Sobald die Einrichtungsseite /api/check-connection abfragt und den Status Connected bekommt, schaltet die Firmware den Hotspot ab. Kommt das gespeicherte Netzwerk von allein zurück, bleibt der Hotspot 120 Sekunden an (ACCESS_POINT_SHUTDOWN_DELAY) und schaltet sich dann ab. Neue Zugangsdaten werden zuerst ausprobiert und erst gespeichert, wenn sie sich verbinden, ein Tippfehler kann also kein funktionierendes Netzwerk ersetzen. Das gespeicherte Netzwerk liegt in NVS, dem Schlüssel-Wert-Speicher im Flash des ESP32.

Um das Portal zurückzuholen, halte die BOOT-Taste des XIAO ESP32-S3 10 Sekunden lang gedrückt, während die Firmware läuft (das löscht auch die eigenen Einstellungen des Projekts), oder drücke in der Web-App auf Forget network. Die ESP32-CAM hat keinen BOOT-Reset: Ihr GPIO0 ist zugleich der Kameratakt, nutze also die Web-App. Erreichst du das Board nach dem Verbinden mit dem WLAN über seinen Namen, kann mDNS das nächste Problem sein, das ESP32 .local funktioniert nicht auf Android behandelt.

Was geprüft wurde, und die Grenzen

Der DNS-Platzhalter, die 302-Weiterleitung, das Timeout von 12,5 Sekunden und die 120 Sekunden Hotspot-Verzögerung sind direkt aus gizmo-common v2.5.1 (vom Ticker und vom Reolink Switch festgelegt; die Kamera nutzt v2.4.0, die ich für diese Anleitung nicht gelesen habe) und aus ESPAsyncWebServer 3.12.1 gelesen; für diese Anleitung habe ich keine Pakete von einem echten Handy mitgeschnitten. Die Proben von Android und Windows stammen aus der Dokumentation von AOSP und Microsoft, der Apple-Host aus dem Apple-Support und sein Pfad nur aus Community-Quellen, und Handyhersteller oder OS-Versionen können jede davon ändern. Hat die Checkliste dein Popup nicht repariert, teste zuerst Schritt 3: Er zeigt, ob das Board oder das Handy schuld ist. Für einen Vergleich mit BLE und Improv ist die Übersicht der Provisioning-Methoden die nächste Station.

Haufig gestellte Fragen

Finden Sie schnelle Antworten auf die haufigsten Fragen zu diesem Thema.

Das Handy öffnet die Anmeldeseite nur, wenn sein Verbindungstest etwas anderes als die erwartete Antwort bekommt. Beantwortet der DNS-Server des ESP32 nicht jeden Namen mit der eigenen IP, oder antwortet der Webserver auf die Probe-URL mit 204 oder der falschen Seite, hält das Handy das Netzwerk für in Ordnung und zeigt nichts an.

Veroffentlicht

Lust, dein eigenes Gizmo zu bauen?

Such dir ein Open-Source-Projekt mit dem ESP32 aus und folge der Schritt-für-Schritt-Anleitung, von der Teileliste und der Verkabelung bis zur Firmware und zum ersten Start.

Lies auch

Kategorien entdecken