Motivation

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)
  • getLimitedBroadcastAddress() und getDirectedBroadcastAddress() hinzugefügt
  • Meldungen in deutsch
1.3 (2018-03-05)

Diese Anpassungen waren notwendig, weil es gelegentlich vorkam, das nach einem Verbindungsfehler der hostname nicht mehr gesetzt werden konnte.

  • Die Einstellung des Modus wird der Methode WiFi.begin() überlassen
  • Lokale IP-Adresse kann eingestellt werden
  •  Kein Abbruch, wenn der Hostname nicht gesetzt werden kann
  • Returncode geändert
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.

In­halts­ver­zeich­nis

Verwendung

Methode connectStation()

Methoden handleReconnectStation() und setRetryInterval()

Broadcast-Adressen

Download


Verwendung

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.

Methode connectStation()

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

Broadcast-Adressen

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.

Download

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