ESP32 WLAN-Provisioning: Captive Portal, BLE, Improv
ESP32 WLAN-Provisioning im Vergleich: Passwort im Code, Captive Portal, BLE und SoftAP von Espressif, Improv, ESP-Touch, nach Sicherheit und Komfort.
- Autor
Mauro Brambilla- Veroffentlicht
- Lesezeit
- 8 Min.
- Kategorie
- Vergleiche

Kurz gesagt
Bei einem Board, das ein Fremder per Handy einrichtet, braucht das Captive Portal keine App, schickt das Passwort aber unverschlüsselt. Espressifs Security 1 oder 2 verschlüsselt es, Improv passt zu einem Board am USB-Kabel.
ESP32-WLAN-Provisioning heißt: Ein Board erfährt Namen und Passwort deines Netzes, ohne dass beides in die Firmware einkompiliert ist. Die gängigen Methoden sind fest im Code hinterlegte Zugangsdaten, ein Captive Portal, Espressifs BLE- oder SoftAP-Provisioning, Improv und ESP-Touch. Für ein Board, das jemand per Handy einrichtet, würde ich das Captive Portal nehmen, außer das Passwort muss verschlüsselt werden.
In diesem Beitrag vergleiche ich sie nach Aufwand bei der Einrichtung, Sicherheit, Speicher und Wiederherstellung. Der Teil zum Portal stammt aus dem Quellcode von gizmo-common, der in jedem OpenGizmo-Gerät läuft, der Rest aus der Espressif-, Improv- und WiFiManager-Dokumentation, die unten verlinkt ist. BLE, Improv und ESP-Touch habe ich für diesen Beitrag nicht auf Hardware ausprobiert, diese Abschnitte beschreiben also Dokumente, keine Tests.
Was ist WLAN-Provisioning, und warum nicht einfach das Passwort im Code lassen?
Provisioning heißt, die Zugangsdaten auf ein Board zu bringen, das noch keine hat. Fest im Code ist die Variante ohne Aufwand: Du schreibst WiFi.begin("name", "password") in den Quellcode und flashst. Das reicht für ein Board, das nur du in einem einzigen Netz benutzt, und es bricht, sobald sich der Router ändert. Außerdem steht dein Passwort danach in der Quelldatei und im Firmware-Binary, du kannst also keins von beiden so wie es ist veröffentlichen oder teilen.
Dieser zweite Punkt ist der Grund, warum jedes geteilte Projekt eine bessere Antwort braucht. Vorgefertigte Firmware, etwa die Images, die der Flasher im Browser installiert, muss für alle identisch sein, die Zugangsdaten müssen also nach dem Flashen ankommen.

Welche Optionen gibt es für das ESP32-WLAN-Provisioning?
| Methode | Wie die Zugangsdaten ankommen | Was der Nutzer braucht | Schutz bei der Übertragung |
|---|---|---|---|
| Fest im Code | In die Firmware einkompiliert | Quellcode, Toolchain | Wird nicht gesendet; steht im Binary |
| Captive Portal | Webformular, das das Board über seinen eigenen Hotspot ausliefert | Jedes Handy oder jeder Laptop mit Browser | Keiner bei offenem Hotspot; WPA2, wenn du ein Hotspot-Passwort setzt |
| Vereinheitlichtes Provisioning von Espressif | BLE (GATT) oder SoftAP mit einem HTTP-Server | Espressifs Beispiel-App oder deine eigene | Security 0: keiner. Security 1: AES-256-CTR. Security 2: AES-256-GCM |
| Improv Serial oder BLE | Binäre Pakete über USB-Seriell oder Bluetooth LE | Chrome oder Edge (nicht auf iOS) für die Web-Demos, oder eine App | In der Spezifikation nicht beschrieben |
| ESP-Touch (SmartConfig) | Eine Handy-App sendet die Zugangsdaten per Broadcast, das Board hört mit | Handy-App (Espressif veröffentlicht eine für Android) | Optional AES in ESP-Touch v2 |
Das steckt hinter den einzelnen Zeilen.
Captive Portal (und WiFiManager)
Das Board öffnet seinen eigenen Hotspot und liefert eine Einrichtungsseite aus. WiFiManager macht dasselbe, wenn das Board kein gespeichertes Netz erreicht: Es wechselt in den Access-Point-Modus und startet einen DNS- und einen Webserver, und das Repository nennt das Ergebnis ein Captive Portal. Die README sagt, die Dokumentation sei veraltet, und sie deckt ESP8266 und ESP32 ab. gizmo-common ist die OpenGizmo-Version derselben Idee, geschrieben für die Web-Apps unserer eigenen Projekte. Wie das Popup aufgeht und warum es manchmal ausbleibt, steht in ESP32 Captive Portal funktioniert nicht? So behebst du das WLAN-Popup.
Espressifs vereinheitlichtes Provisioning
Das Unified Provisioning von ESP-IDF ist ein Framework, keine Seite: Es transportiert die Zugangsdaten und optional weitere Einstellungen über BLE (GATT) oder SoftAP plus HTTP. Espressif listet Provisioning-Apps für Android und iOS mit Quellcode auf und ein Python-Tool, esp_prov, zum Debuggen. Die aktuelle Doku-Seite verweist für den Bibliothekscode und die Beispiele auf die Komponente network_provisioning. Der BLE-Transport braucht laut derselben Seite zur Laufzeit etwa 110 KB RAM, und das meiste davon lässt sich zurückholen, wenn du BLE danach nicht mehr nutzt. Der Arduino-ESP32-Core verpackt es als WiFiProv mit einem SoftAP- und einem BLE-Schema.
Improv
Improv Wi-Fi ist ein offener Standard mit zwei Transporten, Serial und Bluetooth LE, und laut Improv lassen sich beide aus einem Browser nutzen. Die Serial-Spezifikation definiert Pakete, die mit IMPROV beginnen, und Befehle wie WLAN-Einstellungen senden und Netze scannen. ESPHome liefert es als Komponente improv_serial mit, und ESP Web Tools steht auf Improvs Liste der Anwender. Das C++-SDK steht unter der Apache-2.0-Lizenz, und seine README führt die Code-Dokumentation als offenes To-do auf.
ESP-Touch
ESP-Touch, auch SmartConfig genannt, arbeitet andersherum: Die Handy-App kennt das Netz schon und schickt es an das Board. In Espressifs Android-Bibliothek bekommt die App SSID, BSSID und Passwort des Access Points, und die Task kann Broadcast- oder Multicast-Pakete verwenden. ESP-Touch v2 ist nicht mit dem Original kompatibel. Die SmartConfig-Seite von ESP-IDF sagt, dass v2 AES-Verschlüsselung mit einem 16-Byte-Schlüssel unterstützt. Sie sagt außerdem, dass du die Task danach stoppen sollst, um Speicher freizugeben.
Welche Methode ist für den Nutzer am einfachsten?
Am einfachsten ist die, die nichts verlangt, was der Nutzer nicht schon hat. Ein Captive Portal braucht nur den Browser des Handys. Sich mit einem Hotspot zu verbinden, kennen die Leute aus Hotels und Cafés, und darauf baut die ganze Idee auf. Einen Haken gibt es: Das Handy entscheidet, ob es die Anmeldeseite öffnet, und manche tun es nicht.
BLE-Provisioning läuft an einer Stelle runder. Espressif weist darauf hin, dass die App das Board sowohl auf Android als auch auf iOS finden und sich verbinden kann, ohne die App zu verlassen, während SoftAP-Provisioning iOS-Nutzer in die Systemeinstellungen schickt, damit sie dem Netz des Boards beitreten. Der Preis ist die App: Jemand muss sie bauen, veröffentlichen und pflegen, oder der Nutzer installiert Espressifs generische.
Improv Serial ist am bequemsten, wenn das Board schon am Computer hängt, weil eine Seite wie die von ESP Web Tools das Gerät anzeigen und die WLAN-Einstellungen über dasselbe Kabel schicken kann. Für ein Board, das in einer Schublade am anderen Ende der Wohnung liegt, nützt es nichts. Die Improv-Seite sagt, dass ihre Web-Demos Chrome oder Edge brauchen und auf iOS nicht laufen.
ESP-Touch braucht keinen Hotspot, aber der Nutzer braucht trotzdem eine App, die Namen und Passwort des Netzes liefert. Zu seinem Verhalten mit 5-GHz-Netzen habe ich keine Primärquelle gefunden, deshalb kann ich nicht sagen, wie es dort scheitert.

Wie sicher ist jede Methode?
Sicherheit meint hier nur eins: Kann jemand in der Nähe des Boards die Zugangsdaten mitlesen oder austauschen, während sie unterwegs sind? Espressifs Doku ist am deutlichsten. Es gibt drei Stufen:
- Security 0: "No security (No encryption)."
- Security 1: Curve25519-Schlüsselaustausch mit AES-256-CTR-Verschlüsselung. Es gibt einen autorisierten Modus, der einen Proof-of-Possession-String (PoP) nutzt, ein Geheimnis pro Gerät, das der Nutzer in der App eingibt, und einen Modus ohne.
- Security 2: SRP6a-Schlüsselableitung mit AES-256-GCM, auf Basis von Benutzername und Passwort, die du der Handy-App irgendwie mitgibst, zum Beispiel über einen QR-Code-Aufkleber.
Für SoftAP empfiehlt Espressif außerdem WPA2 mit einer eindeutigen Passphrase pro Gerät. Ein Detail, das du im Arduino-Core prüfen solltest: Die Funktion beginProvision im Header WiFiProv.h setzt als Proof of Possession standardmäßig "abcd1234", setz also deinen eigenen, bevor du auslieferst.
Improv ist knapper gehalten. In der BLE-Spezifikation wandert das Passwort als Klartext-Bytes durch die RPC-Command-Characteristic, und die Seite beschreibt weder Pairing noch Verschlüsselung, jeder Schutz hängt also von deinem BLE-Stack ab. Dazu kommt ein optionaler Autorisierungsschritt: Ein Gerät kann auf eine physische Interaktion warten, bevor es Zugangsdaten annimmt, und die Autorisierung läuft nach einem Timeout ab, den die Spezifikation mit einer Minute vorschlägt. Die Prüfsumme fängt nur zufällige Fehler ab.

Ein offenes Captive Portal hat gar keinen Schutz, und das sage ich lieber, als es zu verstecken. Der Hotspot von gizmo-common wird mit WiFi.softAP(setupOptions.accessPointName) gestartet, ohne Passwort, die Zugangsdaten gehen also über unverschlüsseltes HTTP. Das heißt, jeder in Funkreichweite des Boards könnte sie während der Einrichtung im Prinzip mitlesen. Das habe ich aus dem Code abgeleitet und keinen Mitschnitt getestet. Zwei Dinge begrenzen die Angriffsfläche: Der Hotspot öffnet sich nur, solange kein funktionierendes Netz da ist (die Firmware hält ihn nach der Rückkehr des WLANs noch zwei Minuten offen, damit das Handy das Ergebnis sehen kann), und solange er läuft, antworten nur vier API-Pfade (/api/networks, /api/connect, /api/check-connection und /api/device), wie der Code von guardRequest zeigt. WiFiManager sagt, du "can and should" seinen Access Point mit einem Passwort schützen; bei bekanntem Passwort ist der Verkehr über die Luft wenigstens WPA2-verschlüsselt.
Wie speicherst du die Zugangsdaten und erholst dich von einem falschen Passwort?
Das Speichern ist die leichte Hälfte. Die schwere Hälfte ist ein Tippfehler: Wenn das Board ein funktionierendes Netz mit einem falschen Passwort überschreibt, ist es offline und hat keine Möglichkeit, das zu melden.
gizmo-common löst das in wifi_setup.cpp. Neue Zugangsdaten bleiben im RAM und werden zuerst ausprobiert. In den NVS (den Schlüssel-Wert-Speicher im Flash des ESP32, Namespace gizmo-wifi, Schlüssel ssid und password) werden sie erst geschrieben, wenn die Verbindung klappt. Scheitert der Versuch nach 12,5 Sekunden, verwirft das Board sie, kehrt zum gespeicherten Netz zurück und öffnet den Hotspot erneut. Im Code, den ich gelesen habe, habe ich keine NVS-Verschlüsselung gefunden, das gespeicherte Passwort liegt also als Klartext im Flash.
Für ein gewolltes Zurücksetzen kann der Nutzer die BOOT-Taste des XIAO ESP32-S3 10 Sekunden lang halten oder in der Web-App Forget network drücken, wie es die gizmo-common-README beschreibt und die Anleitung zum Captive Portal erklärt. Egal, welche Methode du wählst, stell ihr dieselbe Frage: Was passiert bei einem falschen Passwort, und kann der Nutzer es ohne Computer beheben? Improv hat in seiner Spezifikation einen eigenen Fehler "unable to connect", und ESP-Touch gibt nach einem Timeout auf, der laut SmartConfig-Seite zwischen 15 und 255 Sekunden liegt.
Bricht 5 GHz eine dieser Methoden?
Der ESP32-S3 auf dem XIAO-Board hat kein 5-GHz-Funkmodul, wie im ESP32-Kaufratgeber steht, wo nur der ESP32-C5 Dualband ist. Eine Methode, die vom Board aus scannt, etwa das Portal oder ein Improv-Scan, listet nur auf, was das Board hören kann. Die WLAN-Seite der Web-App hat für einen leeren Scan genau diesen Zustand: "No networks found yet", mit einem Button Scan again (siehe docs/screenshot-wifi.png im Gizmo-Ticker-Repository). Wenn dein Router beide Bänder unter einem Namen zusammenfasst, kann das Board meist trotzdem auf der 2,4-GHz-Seite beitreten. Benennt er sie getrennt, wähle den 2,4-GHz-Namen.
Welche Methode hat OpenGizmo gewählt, und warum?
Alle drei OpenGizmo-Projekte, der Gizmo Ticker, der Gizmo Reolink Switch und die Gizmo Camera, nutzen das Captive Portal. In den drei Firmware-Repositories habe ich keinen Code für Improv, BLE-Provisioning oder ESP-Touch gefunden. Das sind die Gründe, die ich im Code nennen kann:

- Die Web-App gibt es schon. Jedes Board liefert seine eigene Web-App aus, und die Einrichtungsseite
/ap-setupgehört dazu, das Portal kostet also kein neues Frontend. - Keine App zu veröffentlichen. Alles mit einem Browser kann die Einrichtung übernehmen, auf jedem Handy oder Laptop.
- Sichere Wiederholungen. Zugangsdaten werden erst gespeichert, nachdem sie verbunden haben, und ein Hotspot, der sich bei einem Fehler wieder öffnet, ist der Weg zurück.
- Zurücksetzen von Hand. Die BOOT-Taste oder Forget network in der Web-App bringt das Portal zurück.
Die Nachteile sind die oben genannten: ein offener Hotspot, unverschlüsseltes HTTP und ein Handy, das das Popup vielleicht nicht öffnet. Ich habe sie in Kauf genommen, weil sich der Hotspot nur öffnet, solange das Board kein Netz hat, und das WLAN-Passwort das Einzige ist, was gesendet wird. Würde ich etwas ausliefern, das ein wertvolleres Geheimnis als ein WLAN-Passwort für zu Hause verarbeitet, würde ich auf Espressifs Security 2 über BLE umsteigen.
Welche Methode solltest du also nehmen?
Nimm fest hinterlegte Zugangsdaten für ein Wegwerf-Testboard. Nimm ein Captive Portal, wenn jeder mit einem Handy das Board einrichten können soll und ein offener Hotspot akzeptabel ist. Nimm Espressifs vereinheitlichtes Provisioning mit Security 1 oder 2, wenn du die App kontrollierst und Verschlüsselung willst. Nimm Improv Serial, wenn das Board sowieso am USB-Kabel hängt. ESP-Touch lohnt sich nur, wenn du seine App ohnehin ausliefern willst.
Die Grenze dieses Vergleichs: Ich habe die Spezifikationen und den Code gelesen und bei keiner Methode Einrichtungszeit, Akkuverbrauch oder Flash-Größe gemessen. Wenn sich dein Captive Portal auf einem Handy nicht öffnet, geh zur Anleitung zum Captive Portal, und wenn das Board eingerichtet ist, sein .local-Name aber nicht aufgelöst wird, ist das nächste Problem mDNS auf Android. Den ganzen Ablauf des Geräts siehst du in der OpenGizmo-Übersicht.
Haufig gestellte Fragen
Finden Sie schnelle Antworten auf die haufigsten Fragen zu diesem Thema.
WLAN-Provisioning ist der Schritt, in dem ein ESP32 Namen und Passwort deines WLANs erfährt, ohne dass sie in seiner Firmware stehen. Der Nutzer schickt die Zugangsdaten von einem Handy oder Computer, und das Board speichert sie im Flash und verbindet sich. Übliche Methoden sind Captive Portal, Bluetooth LE, Improv und ESP-Touch.
Autor
Mauro BrambillaLust, 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.





