class WLAN – Steuerung der integrierten WiFi-Schnittstellen¶

Die Klasse WLAN steuert die integrierten WiFi-Funkmodule moderner OpenMV Cams. Dieselbe Klasse kapselt je nach WiFi-MCU des Boards zwei unterschiedliche zugrunde liegende Treiber:

CYW43 (Infineon CYW43xxx Murata WiFi-Modul). Verwendet von der OpenMV Cam N6, OpenMV Cam RT1062, Arduino Portenta H7, Arduino Nicla Vision und Arduino Giga R1 WiFi.
NINA W10 (u-blox NINA-W10 / ESP32-WROOM). Verwendet vom Arduino Nano RP2040 Connect.

Die beiden Treiber stellen dieselben Methodennamen bereit, unterscheiden sich jedoch in einigen Argumenten und in der Menge der akzeptierten config()-Schlüssel. Unterschiede sind unten gekennzeichnet.

Die OpenMV-Kameras mit einem älteren WINC1500 WiFi-Shield (M4 / M7 / H7 / H7 Plus / Pure Thermal) verwenden stattdessen WINC.

Anwendungsbeispiel:

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

Konstruktoren¶

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

Erzeugt ein WLAN-Schnittstellenobjekt.

interface_id wählt aus, auf welcher Schnittstelle gearbeitet werden soll:

WLAN.IF_STA – Station-/Client-Modus. Verbindet sich mit connect() mit einem übergeordneten Access Point. Dies ist die Standardeinstellung.

WLAN.IF_AP – Access-Point-Modus. Konfiguriert den AP mit config() und akzeptiert Client-Verbindungen.

Dasselbe physische Funkmodul versorgt beide Schnittstellen; das Erzeugen der einen schließt die andere nicht aus.

Methoden¶

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

Schaltet das WiFi-Funkmodul ein oder aus.

Ohne Argument wird der aktuelle Zustand zurückgegeben – True, solange das Funkmodul eingeschaltet ist, andernfalls False.

active(True) versorgt die WiFi-MCU mit Strom, lädt deren Firmware (CYW43 holt den Firmware-Blob aus dem Flash; NINA validiert die aktuell geflashte Firmware-Version) und bringt die lwIP-netif für diese Schnittstelle hoch. Alle anderen Methoden – connect(), scan(), ipconfig() und verwandte – erfordern, dass die Schnittstelle aktiv ist.

active(False) schaltet das Funkmodul wieder aus. Auf der STA-Schnittstelle wird dadurch außerdem die Verbindung zum aktuellen AP getrennt und die netif freigegeben.

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

Verbindet die STA-Schnittstelle mit dem angegebenen Access Point.

ssid – die Netzwerk-SSID (String oder bytes).

key – Passwort / Pre-Shared Key. Übergeben Sie None für ein offenes Netzwerk.

security (nur Schlüsselwort) – eine der SEC_*-Konstanten. -1 (Standard) wählt automatisch: SEC_OPEN, wenn key leer ist, andernfalls SEC_WPA_WPA2.

bssid (nur Schlüsselwort, nur CYW43) – beschränkt die Verbindung auf den AP mit dieser 6-Byte-MAC-Adresse. Wird vom NINA-Treiber ignoriert.

channel (nur Schlüsselwort) – bevorzugter Funkkanal. Standard ist „den Treiber wählen lassen“.

disconnect() → None¶: Trennt im STA-Modus die Verbindung zum aktuell verbundenen Access Point. Die Schnittstelle bleibt aktiv; rufen Sie connect() erneut auf, um sich wieder zu verbinden, oder active() (False), um das Funkmodul vollständig auszuschalten. Wird ignoriert, wenn derzeit keine Verbindung besteht.

isconnected() → bool¶

Gibt im STA-Modus True zurück, wenn eine Verbindung mit einem Access Point besteht und eine IPv4-Adresse per DHCP bezogen (oder über ipconfig() statisch zugewiesen) wurde. Gibt False zurück, solange sich die Verbindung noch in der Authentifizierungs-/Verbindungs-/DHCP-Phase befindet.

Gibt im AP-Modus True zurück, wenn mindestens eine Station beigetreten ist.

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

Sucht nach nahegelegenen Access Points und gibt eine Liste von 6-Tupeln zurück:

[0] SSID (bytes; leer bei versteckten Netzwerken).

[1] BSSID (6-Byte-MAC, bytes). Mit binascii.hexlify() umwandeln.

[2] Kanalnummer.

[3] RSSI in dBm.

[4] Sicherheitsmodus (eine der SEC_*-Konstanten).

[5] Reserviert (immer 1).

Alle Schlüsselwortargumente sind nur für CYW43:

passive – wenn True, wird ein passiver Scan anstelle des standardmäßigen aktiven Probe-Request-Scans verwendet.

ssid – beschränkt den Scan auf eine SSID.

bssid – beschränkt den Scan auf eine BSSID.

Das Scannen ist nur auf einer STA-Schnittstelle sinnvoll.

status() → int¶

status(param: str) → Any

Fragt den Verbindungsstatus ab.

Ohne Argument wird der Verbindungsstatus als kleine Ganzzahl zurückgegeben (treiberspezifische Kodierung – ein Wahrheitswert bedeutet „verbunden“).

Mit einem String-Argument:

"rssi" – gibt im STA-Modus den aktuellen RSSI in dBm zurück.

"stations" – gibt im AP-Modus eine Liste der verbundenen Stationen zurück. CYW43 gibt [(mac_bytes,), ...] zurück; NINA gibt [ip_string, ...] zurück.

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

Liest oder setzt IPv4-Schnittstellenparameter als 4-Tupel von (ip, subnet, gateway, dns) als Strings im Dotted-Quad-Format.

Bemerkung

Bevorzugen Sie ipconfig() für neuen Code:

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: Liest oder setzt IPv4-/IPv6-Schnittstellenparameter. Der CYW43-Treiber delegiert an die Standard-lwIP-Implementierung und unterstützt den vollständigen Satz der unter AbstractNIC.ipconfig() dokumentierten Schlüssel. Der NINA-Treiber implementiert eine kleinere Teilmenge pro Schnittstelle – dhcp4 und has_dhcp4 (schreibgeschützt) sowie addr4 und gw4 zum Lesen / Setzen.

config(param: str) → Any¶

config(**kwargs: Any) → None

Liest oder setzt WiFi-spezifische Schnittstellenparameter.

Mit einem einzelnen positionellen String-Argument wird der Wert dieses Parameters zurückgegeben. Mit Schlüsselwortargumenten werden ein oder mehrere Parameter auf einmal gesetzt – Änderungen, die einen laufenden AP betreffen, führen dazu, dass der AP automatisch herunter- und wieder hochgefahren wird.

Beispiel:

# 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-Treiber – auslesbare Parameter:

"antenna" – Antennenauswahl (int).

"channel" – aktueller Kanal.

"ssid" / "essid" – die aktuelle SSID (String).

"security" – der Authentifizierungsmodus des AP (einer von SEC_*).

"mac" – MAC-Adresse der Schnittstelle (6 bytes).

"pm" – Energieverwaltungswert.

"txpower" – Sendeleistung in dBm.

"hostname" – DHCP-/mDNS-Hostname. Veraltet; verwenden Sie stattdessen network.hostname().

CYW43-Treiber – setzbare Parameter:

antenna=<int> – Antennenauswahl.

channel=<int> – AP-Kanal.

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

key=<str> / password=<str> – Pre-Shared Key des AP.

security=<int> – Authentifizierungsmodus des AP (einer von SEC_*).

pm=<int> – Energieverwaltungsmodus (einer von PM_NONE, PM_PERFORMANCE, PM_POWERSAVE).

monitor=<int> – aktiviert den Monitor-/All-Multicast-Modus.

txpower=<int> – Sendeleistung in dBm.

trace=<int> – interne Treiber-Trace-Bitmaske.

hostname=<str> – DHCP-/mDNS-Hostname. Veraltet; verwenden Sie stattdessen network.hostname().

NINA-Treiber – auslesbare Parameter:

"ssid" – die aktuelle SSID (String).

"security" – der Authentifizierungsmodus des AP.

"mac" / "bssid" – MAC-Adresse der Schnittstelle (6 bytes).

"fw_version" – ein 3-Tupel (major, minor, patch).

NINA-Treiber – setzbare Parameter: der Aufruf wird an connect() weitergeleitet und akzeptiert dieselben Schlüsselwortargumente (ssid, key, security, channel). Nur auf der AP-Schnittstelle gültig.

deinit() → None¶: Schaltet die WiFi-MCU aus und wieder ein und gibt jede vom Treiber gehaltene Ressource frei (Firmware-Puffer, lwIP-netif, SPI-/SDIO-Bus). Nach dem Aufruf muss das WLAN-Objekt vor der Verwendung neu erzeugt werden. Verwenden Sie dies anstelle von active() (False), wenn Sie einen vollständigen Reset benötigen (zum Beispiel vor dem Neuflashen der Firmware des Funkmoduls oder zur Wiederherstellung aus einem festgefahrenen Treiberzustand). Nur CYW43.

send_ethernet(buf: bytes) → None¶: Injiziert das rohe Ethernet-Einzelbild buf direkt in den Sendepfad des Treibers und umgeht dabei den IP-Stack. Gedacht für reine L2-Konsumenten – Bridging, benutzerdefinierte EtherType-Protokolle und Ähnliches. Das Einzelbild muss Ziel-/Quell-MAC und EtherType enthalten (keine FCS – die Hardware hängt sie an). Nur CYW43.

ioctl(cmd: int, buf: bytearray) → None¶: Sendet einen treiberspezifischen Steuerbefehl. cmd ist der numerische ioctl-Code, der von der zugrunde liegenden Funk-Firmware definiert wird, und buf ist ein veränderbarer Puffer, der sowohl für die Befehlsdaten als auch für die Antwort verwendet wird. Die Menge der gültigen cmd-Werte ist treiberspezifisch und zwischen CYW43 und NINA nicht portierbar. Wird hauptsächlich von Low-Level-Testskripten und Chip-Inbetriebnahme-Code verwendet.

Konstanten¶

IF_STA: int¶: Kennung der Station-/Client-Schnittstelle. An den Konstruktor übergeben, um den STA-Modus auszuwählen.

IF_AP: int¶: Kennung der Access-Point-Schnittstelle. An den Konstruktor übergeben, um den AP-Modus auszuwählen.

SEC_OPEN: int¶: Sicherheitswert für ein unverschlüsseltes Netzwerk. Auf beiden Treibern verfügbar.

SEC_WPA_WPA2: int¶: Sicherheitswert für WPA / WPA2 mit einem Pre-Shared Key. Der Standard, wenn connect() ein Schlüssel übergeben wird. Auf beiden Treibern verfügbar.

SEC_WPA3: int¶: Sicherheitswert für WPA3 (SAE) mit einem Pre-Shared Key. Nur CYW43.

SEC_WPA2_WPA3: int¶: Sicherheitswert für den WPA2-/WPA3-Übergangsmodus. Nur CYW43.

SEC_WEP: int¶: Sicherheitswert für WEP (Wired Equivalent Privacy). Wird zur Kompatibilität mit älteren Access Points bereitgestellt – WEP ist kryptografisch gebrochen und sollte bei neuen Installationen nicht verwendet werden. Nur NINA.

OPEN: int¶: Abwärtskompatibler Alias für SEC_OPEN. Neuer Code sollte SEC_OPEN verwenden. Nur NINA.

WEP: int¶: Abwärtskompatibler Alias für SEC_WEP. Neuer Code sollte SEC_WEP verwenden. Nur NINA.

WPA_PSK: int¶: Abwärtskompatibler Alias für SEC_WPA_WPA2. Neuer Code sollte SEC_WPA_WPA2 verwenden. Nur NINA.

PM_NONE: int¶: An config(pm=...) übergeben, um die WiFi-Energieverwaltung zu deaktivieren. Nur CYW43.

PM_PERFORMANCE: int¶: An config(pm=...) übergeben, um die auf Leistung abgestimmte WiFi-Energieverwaltung zu aktivieren. Nur CYW43.

PM_POWERSAVE: int¶: An config(pm=...) übergeben, um die auf maximale Akkulaufzeit abgestimmte WiFi-Energieverwaltung zu aktivieren. Nur CYW43.