WLAN osztály – beépített WiFi interfészek vezérlése¶

A WLAN osztály a modern OpenMV Cam eszközök beépített WiFi rádióit vezérli. Ugyanez az osztály kétféle különböző alapdrivert burkol be a kártya WiFi MCU-jától függően:

CYW43 (Infineon CYW43xxx Murata WiFi modul). Az OpenMV Cam N6, OpenMV Cam RT1062, Arduino Portenta H7, Arduino Nicla Vision és Arduino Giga R1 WiFi használja.
NINA W10 (u-blox NINA-W10 / ESP32-WROOM). Az Arduino Nano RP2040 Connect használja.

A két driver ugyanazokat a metódusneveket teszi elérhetővé, de néhány argumentumban és az elfogadott config() kulcsok halmazában eltérnek. Az eltéréseket alább jelöljük.

A régebbi WINC1500 WiFi shielddel ellátott OpenMV kamerák (M4 / M7 / H7 / H7 Plus / Pure Thermal) helyette a WINC osztályt használják.

Példa a használatra:

import network

# Enable the station interface and connect to a WiFi AP.
nic = network.WLAN(network.WLAN.IF_STA)
nic.active(True)
nic.connect("your-ssid", "your-key")
while not nic.isconnected():
    pass

print(nic.ipconfig("addr4"))

Konstruktorok¶

class network.WLAN(interface_id: int = WLAN.IF_STA) → None¶

Létrehoz egy WLAN interfész objektumot.

Az interface_id választja ki, hogy melyik interfészen kell működni:

WLAN.IF_STA – állomás / kliens mód. Csatlakozás egy felsőbb szintű hozzáférési ponthoz a connect() segítségével. Ez az alapértelmezett.

WLAN.IF_AP – hozzáférési pont mód. Konfigurálja az AP-t a config() segítségével, és fogadja a kliens kapcsolatokat.

Ugyanaz a fizikai rádió szolgálja ki mindkét interfészt; az egyik létrehozása nem zárja ki a másikat.

Metódusok¶

active(is_active: bool | None = None) → bool¶

Bekapcsolja vagy kikapcsolja a WiFi rádiót.

Argumentum nélkül visszaadja az aktuális állapotot – True, amíg a rádió be van kapcsolva, egyébként False.

Az active(True) bekapcsolja a WiFi MCU-t, betölti a firmware-ét (a CYW43 a firmware blobot a flash memóriából tölti be; a NINA az éppen flashelt firmware verziót ellenőrzi), és felépíti az ehhez az interfészhez tartozó lwIP netifet. Az összes többi metódus – connect(), scan(), ipconfig() és társaik – megköveteli, hogy az interfész aktív legyen.

Az active(False) visszakapcsolja a rádiót. A STA interfészen ez egyúttal leválasztja az aktuális AP-ról és felszabadítja a netifet.

connect(ssid: str, key: str | None = None, *, security: int = -1, bssid: bytes | None = None, channel: int = -1) → None¶

Társítja a STA interfészt a megadott hozzáférési ponttal.

ssid – a hálózat SSID-je (sztring vagy bytes).

key – jelszó / előre megosztott kulcs. Nyílt hálózathoz adjon át None értéket.

security (csak kulcsszóként) – a SEC_* konstansok egyike. A -1 (az alapértelmezett) automatikusan választ: SEC_OPEN, ha a key üres, egyébként SEC_WPA_WPA2.

bssid (csak kulcsszóként, csak CYW43) – a társítást az ezzel a 6 bájtos MAC-címmel rendelkező AP-ra korlátozza. A NINA driver figyelmen kívül hagyja.

channel (csak kulcsszóként) – a kívánt rádiócsatorna. Az alapértelmezett, hogy „a driver válasszon”.

disconnect() → None¶: STA módban leválasztja az éppen társított hozzáférési pontról. Az interfész aktív marad; hívja meg újra a connect() metódust az újratársításhoz, vagy az active() (False) metódust a rádió teljes kikapcsolásához. Ha jelenleg nincs társítva, a hívásnak nincs hatása.

isconnected() → bool¶

STA módban True értéket ad vissza, ha egy hozzáférési ponttal társítva van és egy IPv4-cím megszerzésre került DHCP-n keresztül (vagy statikusan hozzá lett rendelve az ipconfig() segítségével). False értéket ad vissza, amíg a kapcsolat még a hitelesítési/társítási/DHCP fázisban van.

AP módban True értéket ad vissza, ha legalább egy állomás csatlakozott.

scan(*, passive: bool = False, ssid: bytes | None = None, bssid: bytes | None = None) → List[Tuple[bytes, bytes, int, int, int, int]]¶

Megkeresi a közeli hozzáférési pontokat, és egy 6 elemű tuple-ökből álló listát ad vissza:

[0] SSID (bytes; rejtett hálózatoknál üres).

[1] BSSID (6 bájtos MAC, bytes). A binascii.hexlify() segítségével alakítható át.

[2] Csatornaszám.

[3] RSSI dBm-ben.

[4] Biztonsági mód (a SEC_* konstansok egyike).

[5] Fenntartva (mindig 1).

Az összes kulcsszavas argumentum csak CYW43-as:

passive – ha True, passzív keresést használ az alapértelmezett aktív, probe-request alapú keresés helyett.

ssid – a keresést egyetlen SSID-re korlátozza.

bssid – a keresést egyetlen BSSID-re korlátozza.

A keresés csak STA interfészen értelmes.

status() → int¶

status(param: str) → Any

Lekérdezi a kapcsolat állapotát.

Argumentum nélkül a kapcsolat állapotát egy kis egész számként adja vissza (driver-specifikus kódolás – az igaz érték „társítva” jelentésű).

Sztring argumentummal:

"rssi" – STA módban visszaadja az aktuális RSSI értéket dBm-ben.

"stations" – AP módban visszaadja a csatlakozott állomások listáját. A CYW43 [(mac_bytes,), ...] formátumot ad vissza; a NINA [ip_string, ...] formátumot.

ifconfig(config: Tuple[str, str, str, str] | None = None) → Tuple[str, str, str, str] | None¶

Lekérdezi vagy beállítja az IPv4 interfész paramétereit egy (ip, subnet, gateway, dns) négyelemű, pontozott-quad sztringekből álló tuple-ként.

Megjegyzés

Új kódhoz inkább az ipconfig() használata javasolt:

nic.ipconfig(addr4="192.168.0.4/24", gw4="192.168.0.1")
network.ipconfig(dns="8.8.8.8")

ipconfig(param: str) → Any¶
ipconfig(**kwargs: Any) → None: Lekérdezi vagy beállítja az IPv4 / IPv6 interfész paramétereit. A CYW43 driver a szabványos lwIP implementációra delegál, és támogatja az AbstractNIC.ipconfig() metódusnál dokumentált teljes kulcskészletet. A NINA driver egy kisebb, interfészenkénti részhalmazt valósít meg – dhcp4 és has_dhcp4 (csak olvasható), valamint addr4 és gw4 a lekérdezéshez / beállításhoz.

config(param: str) → Any¶

config(**kwargs: Any) → None

Lekérdezi vagy beállítja a WiFi-specifikus interfész paramétereket.

Egyetlen pozicionális sztring argumentummal visszaadja az adott paraméter értékét. Kulcsszavas argumentumokkal egy vagy több paramétert állít be egyszerre – a futó AP-t érintő változtatások hatására az AP automatikusan le, majd újra felépül.

Példa:

# Set up the access-point name and channel.
ap.config(ssid="My AP", channel=11)
# Query params one at a time.
print(ap.config("ssid"))
print(ap.config("mac"))

CYW43 driver – lekérdezhető paraméterek:

"antenna" – antennaválasztó (int).

"channel" – aktuális csatorna.

"ssid" / "essid" – az aktuális SSID (sztring).

"security" – az AP hitelesítési módja (a SEC_* egyike).

"mac" – az interfész MAC-címe (6 bytes).

"pm" – energiakezelési érték.

"txpower" – adóteljesítmény dBm-ben.

"hostname" – DHCP/mDNS hosztnév. Elavult; helyette használja a network.hostname() függvényt.

CYW43 driver – beállítható paraméterek:

antenna=<int> – antennaválasztó.

channel=<int> – AP csatorna.

ssid=<str> / essid=<str> – AP SSID.

key=<str> / password=<str> – AP előre megosztott kulcs.

security=<int> – AP hitelesítési mód (a SEC_* egyike).

pm=<int> – energiakezelési mód (a PM_NONE, PM_PERFORMANCE, PM_POWERSAVE egyike).

monitor=<int> – monitor / all-multicast mód engedélyezése.

txpower=<int> – adóteljesítmény dBm-ben.

trace=<int> – belső driver trace bitmaszk.

hostname=<str> – DHCP/mDNS hosztnév. Elavult; helyette használja a network.hostname() függvényt.

NINA driver – lekérdezhető paraméterek:

"ssid" – az aktuális SSID (sztring).

"security" – az AP hitelesítési módja.

"mac" / "bssid" – az interfész MAC-címe (6 bytes).

"fw_version" – egy 3 elemű (major, minor, patch) tuple.

NINA driver – beállítható paraméterek: a hívás a connect() metódusra továbbít, és ugyanazokat a kulcsszavas argumentumokat fogadja el (ssid, key, security, channel). Csak az AP interfészen érvényes.

deinit() → None¶: Teljesen ki- és bekapcsolja a WiFi MCU-t, és felszabadít minden erőforrást, amelyet a driver tart (firmware pufferek, lwIP netif, SPI/SDIO busz). Ennek meghívása után a WLAN objektumot újra kell létrehozni a használat előtt. Akkor használja ezt az active() (False) helyett, amikor teljes visszaállításra van szükség (például a rádió firmware-ének újraflashelése előtt, vagy egy beragadt driver állapotból való helyreállításhoz). Csak CYW43.

send_ethernet(buf: bytes) → None¶: A nyers Ethernet képkockát (buf) közvetlenül a driver adási útvonalába injektálja, megkerülve az IP veremet. L2-only fogyasztóknak szánták – bridgeléshez, egyedi EtherType protokollokhoz és hasonlókhoz. A képkockának tartalmaznia kell a cél/forrás MAC-et és az EtherType-ot (FCS nélkül – azt a hardver fűzi hozzá). Csak CYW43.

ioctl(cmd: int, buf: bytearray) → None¶: Driver-specifikus vezérlőparancsot ad ki. A cmd az alapul szolgáló rádió firmware által definiált numerikus ioctl kód, a buf pedig egy módosítható puffer, amelyet mind a parancs hasznos terhe, mind a válasz használ. Az érvényes cmd értékek halmaza driver-specifikus, és nem hordozható a CYW43 és a NINA között. Leginkább alacsony szintű tesztszkriptek és chip-bekapcsolási kódok használják.

Konstansok¶

IF_STA: int¶: Állomás / kliens interfész azonosító. Adja át a konstruktornak a STA mód kiválasztásához.

IF_AP: int¶: Hozzáférési pont interfész azonosító. Adja át a konstruktornak az AP mód kiválasztásához.

SEC_OPEN: int¶: Biztonsági érték titkosítatlan hálózathoz. Mindkét driveren elérhető.

SEC_WPA_WPA2: int¶: Biztonsági érték WPA / WPA2 esetén előre megosztott kulccsal. Ez az alapértelmezett, ha kulcsot adnak át a connect() metódusnak. Mindkét driveren elérhető.

SEC_WPA3: int¶: Biztonsági érték WPA3 (SAE) esetén előre megosztott kulccsal. Csak CYW43.

SEC_WPA2_WPA3: int¶: Biztonsági érték a WPA2 / WPA3 átmeneti módhoz. Csak CYW43.

SEC_WEP: int¶: Biztonsági érték WEP-hez (Wired Equivalent Privacy). A régebbi hozzáférési pontokkal való kompatibilitás miatt biztosított – a WEP kriptográfiailag feltört, és új telepítéseknél nem szabad használni. Csak NINA.

OPEN: int¶: Visszafelé kompatibilis alias a SEC_OPEN konstanshoz. Az új kódnak a SEC_OPEN konstanst kell használnia. Csak NINA.

WEP: int¶: Visszafelé kompatibilis alias a SEC_WEP konstanshoz. Az új kódnak a SEC_WEP konstanst kell használnia. Csak NINA.

WPA_PSK: int¶: Visszafelé kompatibilis alias a SEC_WPA_WPA2 konstanshoz. Az új kódnak a SEC_WPA_WPA2 konstanst kell használnia. Csak NINA.

PM_NONE: int¶: Adja át a config(pm=...) hívásnak a WiFi energiakezelés letiltásához. Csak CYW43.

PM_PERFORMANCE: int¶: Adja át a config(pm=...) hívásnak a teljesítményre hangolt WiFi energiakezelés engedélyezéséhez. Csak CYW43.

PM_POWERSAVE: int¶: Adja át a config(pm=...) hívásnak a maximális akkumulátor-élettartamra hangolt WiFi energiakezelés engedélyezéséhez. Csak CYW43.