Bei jedem neuen ESP8266- oder ESP32-Projekt muss ich wieder heraussuchen, wie der Verbindungsaufbau zum WLAN funktioniert. Deshalb hier als Bibliotheksfunktion hinterlegt.
| Version | Anpassungen |
|---|---|
| 1.0 (2017-01-11) | Basis-Version |
| 1.1 (2017-05-30) |
Zweite Version von begin() mit Strings als Parameter |
| 1.2 (2018-01-29) |
|
| 1.3 (2018-03-05) |
Diese Anpassungen waren notwendig, weil es gelegentlich vorkam, das nach einem Verbindungsfehler der hostname nicht mehr gesetzt werden konnte.
|
| 1.4 (2018-03-08) | Probleme beim setzen des hostname. Der disassemblierte Quellcode von wifi_station_set_hostname
zeigt eine Abfrage auf wifi_get_opmode. Es scheint, dass
WiFi.hostname(char *) nur dann funktioniert, wenn der Station-Modus aktiv
ist.WiFi.enableSTA(true); eingefügt. |
| 1.5 (2018-03-12) | handleReconnectStation() und setRetryInterval() hinzugefügt. |
| 1.6 (2018-03-15) | getModeString() und getStatusString() hinzugefügt |
| 1.7 (2018-04-09) | handleReconnectStation() und setRetryInterval() wieder entfernt. Seit der Core-Version klappt autoreconnect (wieder?). |
| 1.8. (2018-07-11) | Timeout (einstellbar) und Fehlermeldungen für connectStation überarbeitet. |
| 1.9 (2024-01-24) | Für ESP32 ergänzt. |
Inhaltsverzeichnis
Die Arduino-Klasse UrsWiFi besitzt folgende statische Methoden:
| Methode | Verwendung |
|---|---|
| connectStation() | Verbindung zum WLAN herstellen. |
| setTimeOut() | Legt die Zeitbeschränkung für den Verbindungsaufbau fest. 0 bedeutet endlos. Die Voreinstellung ist 30 Sekunden. |
| getLimitedBroadcastAddress() | Liefert die IP-Adresse 255.255.255.255. |
| getDirectedBroadcastAddress() | Liefert die Direct-Broadcast-Adresse für das aktuelle WLAN. |
| getModeString() | Liefert den Text, z.B. "WIFI_OFF" (s. WiFiMode_t), zum angegebenen Modus. Ist der Parameter -1, wird der aktuelle Modus per WiFi.getMode() abgerufen. Entspricht der Parameter keinem gültigen Modus, wird "WIFI_UNKNOWN" zurück gegeben. |
| getStatusString() | Liefert den Text, z.B. "WL_CONNECTED" (s. wl_status_t), zum angegebenen Status. Ist der Parameter -1, wird der aktuelle Status per WiFi.status() abgerufen. Entspricht der Parameter keinem gültigen Status, wird "WL_UNKNOWN" zurück gegeben. |
Die statische Methode connectStation() stellt eine WiFi-Verbindung zum angegebenen WLAN her:
static UrsCodes::ConnectCode connectStation(const char* ssid, const char* password,
const char* hostname = NULL, IPAddress localIP = (uint32_t) 0, Print& outDevice = Serial);
static UrsCodes::ConnectCode
connectStation(const String ssid, const String password,
const
String hostname = "", IPAddress localIP = (uint32_t)0, Print& outDevice = Serial);
String ssid = "MyWLAN";
String password = "Geheim";
String hostname = "ESP8266";
...
UrsWiFi.connectStation(ssid, password, hostname);Die Ausgabe erfolgt dann standardmäßig auf Serial:
Mit WiFi MyWLAN verbinden als ESP8266 .......
Verbunden mit MyWLAN, IP-Adresse: 192.168.334.22
... oder eine entsprechende Fehlermeldung.
| Parameter | Funktion | Standard |
|---|---|---|
| ssid | Bezeichnung des WLANs, an dem die Anmeldung erfolgen soll. | - |
| password | Passwort zur Anmeldung am WLAN. | - |
| hostname | Name, unter dem der ESP8266 erscheinen soll (optinal). | NULL Es wird der interne Name genutzt: "ESP_XXXXXX", XXXXXX= ChipID in Hex, z.B. "ESP_D43948" |
| localIP | IP-Adresse, die das Gerät erhalten soll. Die IP-Adresse kann erst nach erfolgreicher Anmeldung am Access-Point eingestellt werden. Gateway-IP, SubnetMask und DNS-IP werden aus diesen Anmelde-Informationen ermittelt. |
0.0.0.0 Es wird eine IP vom Access-Point bezogen. |
| OutDevice | Gerät, auf die Protokoll- und Fehlermeldungen ausgegeben werden sollen, z.B. Serial, UrsWiFiSerial, UrsDummyPrint. | Serial |
Der Verbindungsaufbau hat ein Timeout von ca. 5 Sekunden.
Die Methode meldet den Versuch zum Verbindungsaufbau mit
Mit WiFi '<ssid>' verbinden als '<hostname>' ....
War der Verbindungsaufbau erfolgreich wird gemeldet:
Verbunden mit '<ssid>' als '<hostname>', IP-Adresse: <IP>
Für den Rückgabewert der Methode steht die Enumeration ConnectCode zur Verfügung. Dieser Typ wurde in einem eigenen Namensraum gekapselt, um die versehentliche Nutzung zu verhindern. Der Typ wird als Flag-Typ organisiert, kann also Kombinationen von Werten enthalten:
namespace UrsCodes {
enum ConnectCode : uint8_t {
noError = 0,
notConnected = 1,
hostnameFail = 2,
localIPFail = 4,
timeout = 8
};
}Diese Methode ConnectCode liefert den Rückgabe-Wert 0, wenn die Verbindung wie gewünscht hergestellt werden konnte, ansonsten einen Fehlercode:
| Flag | Bedeutung | Meldung |
|---|---|---|
| notConnected | Verbindung konnte nicht hergestellt werden (s. WiFi.begin()). | ***** Fehler: WiFi-Verbindung fehlgeschlagen: <status> |
| hostNameFail | Der Host-Name konnte nicht eingestellt werden (s. WiFi.hostname()). | ***** Fehler: hostname: 'xxx' konnte nicht eingestellt werden! |
| localIPFail | Die gewünschte IP-Adresse konnte nicht eingestellt werden (s. WiFi.config()). | ***** Fehler: Lokale IP konnte nicht eingestellt werden! |
| timeout | Timeout beim Verbinden mit dem WLAN | ***** Fehler: WiFi-Verbindung fehlgeschlagen: Timeout |
Gelegentlich kam es vor, dass der Hostname nicht gesetzt werden konnte. Dieses Problem trat besonders dann auf, wenn eine vorhergehende Verbindung fehlgeschlagen ist. Hier bietet sich ggf. eine zweiter Versuch an:
// mit WLAN verbinden
// -------------------------------------------------------------------------
auto conStatus = UrsWiFi.connectStation(SSID, Password, Name, LocalIP);
if (!(conStatus & UrsCodes::ConnectCode::notConnected)) { // Verbunden
if (conStatus != UrsCodes::ConnectCode::noError) {// aber Probleme: 2. Versuch
Serial.println(F("=== 2. Versuch"));
UrsWiFi.connectStation(SSID, Password, Name, LocalIP);
}
}Hinweis: Um volle Kontrolle über den Anmeldevorgang zu erlangen, empfiehlt es sich zu Beginn von setup() folgende Anweisungen auszuführen:
ESP.eraseConfig();
WiFi.setAutoConnect(false);
WiFi.setAutoReconnect(false);Hinweis für FRITZ!Box-Nutzer: Der Router übernimmt den Host-Name nicht direkt, sondern fügt ein ".fritz.box" an. Aus "UrsESP" wird "UrsESP.fritz.box".
Die Funktion und der Aufbau von Broadcast-Adressen ist gut im Wikipedia-Artikel Broadcast erklärt. Die Methode getLimitedBroadcastAddress() liefert die Limited-Broadcast-IP-Adresse 255.255.255.255.
Die Methode getDirectedBroadcastAddress() liefert die Direct-Broadcast-Adresse für das aktuelle WLAN. Dazu werden alle in der subnetMask (s. ESP8266 Arduino core documentation: Station Class) mit 255 hinterlegten Bytes durch die der lokalen IP ersetzt, die anderen durch 255 (s. auch Wikipedia: Netzmaske). z.B:
Subnet-Maske: 255.255.255.0, lokale IP: 192.168.7.41 -> Directed-Broadcast-Adresse: 192.168.7.255.
Das ZIP-Archiv für Bibliothek UrsWiFi zum Download. Die entpackten Dateien ins Verzeichnis <user>\Documents\Arduino\libraries kopieren (siehe Installing Additional Arduino Libraries).
Das Archiv enthält die Bibliotheksdateien