Skip to content

Provisioning (BLE & WLAN)

Als Provisioning wird die Erst-Einrichtung eines Geräts bezeichnet. Ein frisch geflashter ESP32 besitzt noch keine WLAN-Zugangsdaten und kann das Backend daher nicht erreichen. Beim Provisioning erhält er die SSID und das Passwort des Netzwerks, verbindet sich damit und meldet sich anschließend beim Backend an.

Für die Übergabe der Zugangsdaten gibt es zwei Wege. Im Normalfall überträgt die App sie direkt über Bluetooth Low Energy. Ist keine App zur Hand, öffnet das Gerät einen eigenen Access Point mit einer Weboberfläche, über die sich die Zugangsdaten eintragen lassen. Beide Wege führen zum selben Ergebnis: gespeicherte Zugangsdaten und eine aktive Verbindung zum Backend.

Ablauf

Die Einrichtung wird von der ActionConnect Library gesteuert. Beim Start versetzt connectHubInit() das WLAN in den kombinierten Modus (WIFI_AP_STA), startet das BLE-Advertising und lädt eventuell gespeicherte Zugangsdaten aus dem nichtflüchtigen Speicher.

Sind bereits Zugangsdaten hinterlegt, verbindet sich das Gerät direkt und geht in den Normalbetrieb über. Fehlen sie oder schlägt die Verbindung fehl, wird das Gerät für das Provisioning empfänglich: Es bleibt über BLE erreichbar und öffnet – sofern kein BLE-Client verbunden ist – seinen Access Point. Zusätzlich prüft connectHubProcessTransport() im laufenden Betrieb, ob das Gerät nach fünf Minuten weiterhin ohne WLAN, ohne aktiven Access Point und ohne BLE-Verbindung ist, und startet in diesem Fall den Access Point als Rückfall.

Sobald gültige Zugangsdaten eintreffen – über BLE oder die Weboberfläche –, speichert das Gerät sie, verbindet sich mit dem WLAN, hinterlegt seine MAC-Adresse, beendet den Access Point und baut die MQTT-Verbindung auf. Mit der ersten Verbindung sendet es seine Registrierung samt Thing Model an das Backend.

flowchart TD
    Start["connectHubInit()"] --> Load{"Zugangsdaten<br/>gespeichert?"}
    Load -->|ja| Conn{"Verbindung<br/>erfolgreich?"}
    Load -->|nein| Prov
    Conn -->|ja| Run["Normalbetrieb:<br/>MQTT + Registrierung"]
    Conn -->|nein| Prov["Provisioning:<br/>BLE aktiv, Access Point offen"]
    Prov --> Recv["SSID + Passwort empfangen<br/>(BLE oder Weboberfläche)"]
    Recv --> Save["speichern, verbinden,<br/>Access Point beenden"]
    Save --> Run

BLE-Konfiguration

Über BLE schreibt die App die Zugangsdaten in die RX-Characteristic des Geräts (die Charakteristiken sind unter BLE-Kommunikation beschrieben). Das Gerät akzeptiert dabei zwei Formate – ein JSON-Objekt oder eine einfache Textzeile:

{ "type": "wifi", "ssid": "MeinNetz", "password": "geheim" }

WIFI:MeinNetz:geheim

Bereits hinterlegte Zugangsdaten lassen sich wieder entfernen, wodurch das Gerät erneut in das Provisioning zurückfällt. Auch dafür genügt eine kurze Nachricht, als Text WIFI:CLEAR oder als JSON { "type": "wifi_clear" }.

Das Gerät prüft die empfangenen Daten und meldet das Ergebnis über die TX-Characteristic zurück an die App. Die Antwort ist ein JSON-Objekt mit dem Feld provision:

Antwort Bedeutung
{"provision":"ok","ip":"192.168.1.42"} Verbindung hergestellt; enthält die zugewiesene IP-Adresse.
{"provision":"err","error":"missing_ssid"} Es wurde keine SSID übergeben.
{"provision":"err","error":"wifi_connect_failed"} Verbindung mit den Daten nicht möglich.
{"provision":"cleared"} Gespeicherte Zugangsdaten wurden entfernt.

Nach einer erfolgreichen Verbindung beendet das Gerät seinen Access Point, baut die MQTT-Verbindung auf und sendet seine Registrierung.

WLAN-Zugangsdaten

Steht keine App zur Verfügung, dient der Access Point als zweiter Weg. Öffnet das Gerät diesen, erscheint ein WLAN mit dem in der Firmware gesetzten Namen. Nach dem Verbinden ruft man die Weboberfläche des Geräts im Browser auf. Sie zeigt den Pairing-Code des Geräts an und bietet ein Formular für SSID und Passwort.

Mit dem Absenden speichert das Gerät die Eingaben und versucht sofort, die Verbindung herzustellen. Gelingt dies, beendet es den Access Point und bestätigt den Erfolg im Browser; andernfalls weist es auf die fehlgeschlagene Verbindung hin, sodass die Eingabe wiederholt werden kann.

Pairing-Code

Der auf der Weboberfläche angezeigte Code besteht aus den letzten vier Stellen der MAC-Adresse und wird für das erste Einbinden des Geräts im Dashboard benötigt (siehe Getting Started).

Der Access-Point-Name ist in der Firmware zunächst ein Platzhalter und sollte je Gerät angepasst werden (Setup & Build).

Persistenz (Device ID & UUID)

Damit das Provisioning ein einmaliger Schritt bleibt, legt die Firmware die relevanten Werte im nichtflüchtigen Speicher (Preferences/NVS) ab. Sie überstehen einen Neustart und ein erneutes Flashen, sodass sich das Gerät danach ohne weitere Eingabe verbindet und seine Identität behält.

Namespace Inhalt Zweck
storage WLAN-SSID, Passwort und MAC-Adresse Automatische Verbindung nach dem Neustart
ble Service-, TX- und RX-UUID Stabile BLE-Identität, an der die App das Gerät wiedererkennt
device Sechsstellige Geräte-ID Eindeutige Kennung des Geräts

Die BLE-UUIDs und die Geräte-ID werden je Gerät einmalig erzeugt und danach unverändert weiterverwendet; die Erzeugung ist unter BLE-Kommunikation beschrieben. Das Löschen der Zugangsdaten (WIFI:CLEAR) betrifft nur den WLAN-Teil im Namespace storage – die BLE-Identität und die Geräte-ID bleiben erhalten.

Siehe auch