Állomás (Station) osztály

Az ESP8266 által biztosított funkciók száma állomás módban sokkal kiterjedtebb, mint az eredeti Arduino WiFi könyvtárban. Ezért az eredeti dokumentáció kiegészítése helyett úgy döntöttünk, hogy a vázlatból újat írunk.

Az állomásosztály leírása négy részre oszlik. Először a hozzáférési ponttal való kapcsolat létrehozásának módszereit tárgyalja. A második olyan módszereket biztosít a kapcsolat kezelésére, mint pl. a reconnect vagy az isConnected. A harmadik a kapcsolatokra vonatkozó információk beszerzésére szolgáló tulajdonságokra vonatkozik, például MAC- vagy IP-címre. Végül a negyedik szakasz alternatív módszereket kínál a csatlakozáshoz, mint pl. Wi-Fi Protected Setup (WPS).

Tartalomjegyzék

Az alábbi pontok leírást és kódrészleteket tartalmaznak az egyes módszerek használatáról.

További kódmintákért tekintse meg a külön szakaszt, amely kifejezetten az állomásosztályra vonatkozó példákat tartalmaz.

Itt kezdődik

A modul állomás módba kapcsolása a begin funkcióval történik. A begin-nek tipikusan átadott paraméterek közé tartozik az SSID és a jelszó, így a modul egy adott hozzáférési ponthoz tud csatlakozni.


WiFi.begin(ssid, password)

Alapértelmezés szerint az ESP megpróbál újra csatlakozni a Wi-Fi hálózathoz, amikor megszakad. Ezt nem kell külön kóddal kezelni. A kapcsolat megszakadásának szimulálására jó módszer a hozzáférési pont visszaállítása. Az ESP jelenti a kapcsolat megszakadását, majd megpróbál automatikusan újracsatlakozni.

begin

A begin függvénynek számos változata létezik (a C++-ban a függvény többarcúságnak nevezik). Az egyik közvetlenül fent volt: WiFi.begin(ssid, password). A többarcúságnak rugalmasságot biztosítanak az elfogadott paraméterek számában vagy típusában.

A begin legegyszerűbb többarcúsága a következő:


WiFi.begin()

Meghívása engedélyezi az állomás módot, és csatlakozik az utoljára használt hozzáférési ponthoz a flash memóriába mentett konfiguráció alapján.

Megjegyzés:

Az alábbiakban a begin egy másik többarcúságának szintaxisa látható az összes lehetséges paraméterrel:


WiFi.begin(ssid, password, channel, bssid, connect)

A paraméterek jelentése a következő:

config

Tiltsa le a DHCP klienst (Dynamic Host Configuration Protocol), és állítsa be az állomás interfész IP-konfigurációját a felhasználó által megadott tetszőleges értékekre. Az interfész statikus IP-konfiguráció lesz a DHCP által biztosított értékek helyett.


WiFi.config(local_ip, gateway, subnet, dns1, dns2)

A függvény true-t ad vissza, ha a konfigurációmódosítás sikeresen végrehajtva. Ha a konfiguráció nem alkalmazható, mert pl. a modul nem állomás vagy állomás + soft access point módban van, akkor false értéket ad vissza.

A következő IP-konfiguráció gondoskodik:

Példakód:


#include <ESP8266WiFi.h>

const char* ssid = "********";
const char* password = "********";

IPAddress staticIP(192,168,1,22);
IPAddress gateway(192,168,1,9);
IPAddress subnet(255,255,255,0);

void setup(void)
{
  Serial.begin(115200);
  Serial.println();

  Serial.printf("Connecting to %s\n", ssid);
  WiFi.config(staticIP, gateway, subnet);
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED)
  {
    delay(500);
    Serial.print(".");
  }
  Serial.println();
  Serial.print("Connected, IP address: ");
  Serial.println(WiFi.localIP());
}

void loop() {}

A példa kimenete:


Connecting to sensor-net
.
Connected, IP address: 192.168.1.22

Kérjük, vegye figyelembe, hogy a statikus IP-konfigurációjú állomás általában gyorsabban csatlakozik a hálózathoz. A fenti példában körülbelül 500 ms-ig tartott (egy pont . jelenik meg). Ennek az az oka, hogy az IP-konfiguráció DHCP-kliens általi megszerzése időt vesz igénybe, és ebben az esetben ez a lépés kimarad. Ha mindhárom paramétert 0.0.0.0-nak adja meg (local_ip, gateway és subnet), akkor újra engedélyezi a DHCP-t. Új IP-címek beszerzéséhez újra csatlakoztatnia kell az eszközt.

A kapcsolat kezelése

reconnect

Csatlakoztassa újra az állomást. Ez úgy történik, hogy megszakítja a csatlakozást a hozzáférési ponttól, majd újrakezdi a kapcsolatot ugyanahhoz az AP-hoz.


WiFi.reconnect()

Megjegyzések: 1. Az állomásnak már csatlakoznia kell egy hozzáférési ponthoz. Ha nem ez a helyzet, akkor a függvény false értéket ad vissza, és nem hajt végre semmilyen műveletet. 2. Ha true értéket ad vissza, az azt jelenti, hogy a kapcsolódási folyamat sikeresen elindult. A felhasználónak továbbra is ellenőriznie kell a kapcsolat állapotát, és meg kell várnia a WL_CONNECTED jelentését:


WiFi.reconnect();
while (WiFi.status() != WL_CONNECTED)
{
  delay(500);
  Serial.print(".");
}

disconnect

Az aktuálisan konfigurált SSID-t és jelszót null értékre állítja, és leválasztja az állomást egy hozzáférési pontról.


WiFi.disconnect(wifioff)

A wifioff egy opcionális boolean paraméter. Ha true, akkor az állomás mód kikapcsol.

isConnected

true értéket ad vissza, ha az állomás csatlakozik egy hozzáférési ponthoz, vagy false értéket, ha nem.


WiFi.isConnected()

setAutoConnect

Konfigurálja a modult úgy, hogy a bekapcsoláskor automatikusan csatlakozzon az utoljára használt hozzáférési ponthoz.


WiFi.setAutoConnect(autoConnect)

Az autoConnect opcionális paraméter. Ha false értékre van állítva, az automatikus csatlakozási funkció le lesz tiltva. Ha kihagyja vagy true-ra állítja, akkor az automatikus csatlakozás engedélyezve lesz.

getAutoConnect

Ez "társ" funkció a setAutoConnect()-hez. true értéket ad vissza, ha a modul úgy van beállítva, hogy bekapcsoláskor automatikusan csatlakozzon az utoljára használt hozzáférési ponthoz.


WiFi.setAutoConnect(autoConnect)

Ha az automatikus csatlakozás funkció le van tiltva, akkor a függvény false értéket ad vissza.

setAutoReconnect

Beállítja, hogy a modul megkíséreljen-e újracsatlakozni egy hozzáférési ponthoz, ha megszakad.


WiFi.setAutoReconnect(autoReconnect)

Ha az autoReconnect paraméter truera van állítva, akkor a modul megpróbálja visszaállítani a megszakadt kapcsolatot az AP-vel. Ha false értékre van állítva, akkor a modul leválasztva marad.

Megjegyzés: A setAutoReconnect(true) futtatásakor, ha a modul már le van választva, nem csatlakozik újra a hozzáférési ponthoz. Ehelyett a reconnect()-et kell használni.

waitForConnectResult

Várja meg, amíg a modul csatlakozik a hozzáférési ponthoz. Ez a funkció az állomás vagy állomás + soft hozzáférési pont módban konfigurált modulokhoz használható.


WiFi.waitForConnectResult()

A függvény a következő kapcsolati állapotok egyikét adja vissza:

Konfiguráció

macAddress

Beszerezi az ESP állomás interfészének MAC-címét.


WiFi.macAddress(mac)

A függvény a mac-kel, amely egy memóriahelyre mutató pointer (6 elemből álló uint8_t tömb) biztosítja a helyet a mac-cím mentéséhez. Ugyanezt a mutatóértéket adja vissza maga a függvény.

Példakód:


if (WiFi.status() == WL_CONNECTED)
{
  uint8_t macAddr[6];
  WiFi.macAddress(macAddr);
  Serial.printf("Connected, mac address: %02x:%02x:%02x:%02x:%02x:%02x\n", macAddr[0], macAddr[1], macAddr[2],
    macAddr[3], macAddr[4], macAddr[5]);
}

A példa kimenete:


Mac address: 5C:CF:7F:08:11:17

Ha nem érzi jól magát a mutatókkal, akkor ennek a funkciónak opcionális verziója is elérhető. A mutató helyett egy formázott karakterláncot ad vissza, amely ugyanazt a mac-címet tartalmazza.


WiFi.macAddress()

Példakód:


if (WiFi.status() == WL_CONNECTED)
{
  Serial.printf("Connected, mac address: %s\n", WiFi.macAddress().c_str());
}

localIP

Az ESP állomás interfészének IP-címének megszerzésére használt funkció.


WiFi.localIP()

A visszaadott érték típusa: IPAddress. Néhány módszer áll rendelkezésre az ilyen típusú adatok megjelenítésére. Az alábbi példák jól bemutatják az IPAddress-t visszaadó subnetMask, gatewayIP és dnsIP leírását.

Példakód:


if (WiFi.status() == WL_CONNECTED)
{
  Serial.print("Connected, IP address: ");
  Serial.println(WiFi.localIP());
}

A példa kimenete:


Connected, IP address: 192.168.1.10

subnetMask

Beszerezi az állomás interfészének alhálózati maszkját.


WiFi.subnetMask()

Az alhálózati maszk beszerzéséhez a modult a hozzáférési ponthoz kell csatlakoztatni.

Példakód:


Serial.print("Subnet mask: ");
Serial.println(WiFi.subnetMask());

A példa kimenete:


Subnet mask: 255.255.255.0

gatewayIP

Beszerezi az átjáró IP-címét.


WiFi.gatewayIP()

Példakód:


Serial.printf("Gataway IP: %s\n", WiFi.gatewayIP().toString().c_str());

A példa kimenete:


Gataway IP: 192.168.1.9

dnsIP

Beszerezi a Domain Name Servers (DNS) IP-címeit.


WiFi.dnsIP(dns_no)

A dns_no bemeneti paraméterrel megadhatjuk, hogy melyik Domain Name Server IP-jére van szükségünk. Ez a paraméter nulla alapú, és az engedélyezett értékek semmi, 0 vagy 1. Ha nincs megadva paraméter, akkor a DNS #1 IP-címe kerül visszaadásra.

Példakód:


Serial.print("DNS #1, #2 IP: ");
WiFi.dnsIP().printTo(Serial);
Serial.print(", ");
WiFi.dnsIP(1).printTo(Serial);
Serial.println();

A példa kimenete:


DNS #1, #2 IP: 62.179.1.60, 62.179.1.61

hostname

Beszerezi az ESP-állomáshoz rendelt DHCP-állomásnevet.


WiFi.hostname()

A függvény String típust ad vissza. Az alapértelmezett gazdagépnév ESP_24xMAC formátumban van, ahol a 24xMAC a modul MAC-címének utolsó 24 bitje.

A gazdagépnév a következő funkcióval módosítható:


WiFi.hostname(aHostname)

Az aHostname bemeneti paraméter lehet char*, const char* vagy String. A hozzárendelt gazdagépnév maximális hossza 32 karakter. A függvény az eredménytől függően true vagy false értéket ad vissza. Például, ha túllépi a 32 karakteres korlátot, a függvény false értéket ad vissza az új gazdagépnév hozzárendelése nélkül.

Példakód:


Serial.printf("Default hostname: %s\n", WiFi.hostname().c_str());
WiFi.hostname("Station_Tester_02");
Serial.printf("New hostname: %s\n", WiFi.hostname().c_str());

A példa kimenete:


Default hostname: ESP_081117
New hostname: Station_Tester_02

status

A Wi-Fi kapcsolat állapotát adja vissza.


WiFi.status()

A függvény a következő kapcsolati állapotok egyikét adja vissza:

A visszaadott érték típusa wl_status_t, amely a wl_definitions.h fájlban van definiálva

Példakód:


#include <ESP8266WiFi.h>

const char* ssid = "********";
const char* password = "********";

void setup(void)
{
  Serial.begin(115200);
  Serial.printf("Connection status: %d\n", WiFi.status());
  Serial.printf("Connecting to %s\n", ssid);
  WiFi.begin(ssid, password);
  Serial.printf("Connection status: %d\n", WiFi.status());
  while (WiFi.status() != WL_CONNECTED)
  {
    delay(500);
    Serial.print(".");
  }
  Serial.printf("\nConnection status: %d\n", WiFi.status());
  Serial.print("Connected, IP address: ");
  Serial.println(WiFi.localIP());
}

void loop() {}

A példa kimenete:


Connection status: 7
Connecting to sensor-net
Connection status: 7
......
Connection status: 3
Connected, IP address: 192.168.1.10

A 7-es és 3-as kapcsolati állapotok a következőképpen nézhetők meg a wl_definitions.h fájlban:


3 - WL_CONNECTED
7 - WL_DISCONNECTED

E példa alapján a fenti kód futtatásakor a modul kezdetben nem csatlakozik a hálózathoz, és a 7 - WL_DISCONNECTED kapcsolati állapotot adja vissza. A WiFi.begin(ssid, password) futtatása után azonnal szintén nincs kapcsolat. Ezután körülbelül 3 másodperc elteltével (az 500 ms-onként megjelenő pontok száma alapján) végül csatlakozik, és a 3 – WL_CONNECTED állapotot adja vissza.

SSID

Visszaadja a Wi-Fi hálózat nevét, amelyet hivatalosan Service Set Identification (SSID)-nek hívnak.


WiFi.SSID()

A visszaadott érték String típusú.

Példakód:


Serial.printf("SSID: %s\n", WiFi.SSID().c_str());

A példa kimenete:


SSID: sensor-net

psk

Visszaadja a Wi-Fi hálózathoz társított jelenlegi, előre megosztott kulcsot (jelszót).


WiFi.psk()

A visszaadott érték String típusú.

BSSID

Visszaadja annak a hozzáférési pontnak a mac-címét, amelyhez az ESP-modult a csatlakozáshoz irányították. Ezt a címet hivatalosan Basic Service Set Identification (BSSID)-nek hívják. A visszaadott mutató az, amit a felhasználó beállított a begin() bssid argumentummal történő meghívásakor. Ez nem feltétlenül tükrözi annak a hozzáférési pontnak a mac-címét, amelyhez az ESP modul állomás interfésze jelenleg csatlakozik.


WiFi.BSSID()

A BSSID() függvény egy mutatót ad vissza arra a memóriahelyre (egy uint8_t tömbre, amely 6 elemből áll), ahová a BSSID mentve van.

Az alábbiakban hasonló függvény látható, a BSSID-t adja vissza, de String típusként. 


WiFi.BSSIDstr()

Példakód:


Serial.printf("BSSID: %s\n", WiFi.BSSIDstr().c_str());

A példa kimenete:


BSSID: 00:1A:70:DE:C1:68

RSSI

Visszaadja a Wi-Fi hálózat jelerősségét, amelyet hivatalosan Received Signal Strength Indication (RSSI)-nek hívnak.


WiFi.RSSI()

A jelerősség értéke dBm-ben van megadva. A visszaadott érték típusa int32_t.

Példakód:


Serial.printf("RSSI: %d dBm\n", WiFi.RSSI());

A példa kimenete:


RSSI: -68 dBm

Csatlakozás másként

Az ESP8266 SDK alternatív módszereket kínál az ESP-állomás hozzáférési ponthoz való csatlakoztatására. Közülük az esp8266 / Arduino mag a WPS-t és a Smart Config-ot valósítja meg, amint azt az alábbiakban részletesen ismertetjük.

WPS

A következő beginWPSConfig funkció lehetővé teszi a hálózathoz való csatlakozást a Wi-Fi Protected Setup (WPS) használatával. Jelenleg csak a nyomógombos konfiguráció (WPS_TYPE_PBC mód) támogatott (SDK 1.5.4).


WiFi.beginWPSConfig()

A kapcsolat eredményétől függően a függvény true vagy false értéket ad vissza (boolean típusú).

Példakód:


#include <ESP8266WiFi.h>

void setup(void)
{
  Serial.begin(115200);
  Serial.println();

  Serial.printf("Wi-Fi mode set to WIFI_STA %s\n", WiFi.mode(WIFI_STA) ? "" : "Failed!");
  Serial.print("Begin WPS (press WPS button on your router) ... ");
  Serial.println(WiFi.beginWPSConfig() ? "Success" : "Failed");

  while (WiFi.status() != WL_CONNECTED)
  {
    delay(500);
    Serial.print(".");
  }
  Serial.println();
  Serial.print("Connected, IP address: ");
  Serial.println(WiFi.localIP());
}

void loop() {}

A példa kimenete:


Wi-Fi mode set to WIFI_STA
Begin WPS (press WPS button on your router) ... Success
.........
Connected, IP address: 192.168.1.102

Smart Config

Az ESP modul és a hozzáférési pont Smart Config kapcsolata speciális csomagok lekérdezésével történik, amelyek tartalmazzák a kívánt AP SSID-jét és jelszavát. Ehhez a mobileszköznek vagy számítógépnek rendelkeznie kell a kódolt SSID és jelszó sugárzásának funkciójával.

A következő három funkció érhető el a Smart Config megvalósításához.

Indítsa el az intelligens konfigurációs módot a kívánt hozzáférési pont SSID azonosítóját és jelszavát tartalmazó speciális csomagok megkeresésével. Az eredménytől függően true vagy false értéket ad vissza.


beginSmartConfig()

A Smart Config állapotának lekérdezése annak eldöntéséhez, hogy mikor kell leállítani a konfigurációt. A függvény boolean típusú true vagy false értéket ad vissza.


smartConfigDone()

Leállítja a Smart Config, felszabadítja a beginSmartConfig() által lefoglalt puffert. Az eredmény függvényében a függvény true vagy false, boolean típusú értéket ad vissza.


stopSmartConfig()

A Smart Config funkcióval kapcsolatos további részletekért tekintse meg az ESP8266 API felhasználói kézikönyvét.

© Copyright 2017, Ivan Grokhotkov Revision 02c1a502. Fordította: Maczák András