klasa WLAN – sterowanie wbudowanymi interfejsami WiFi¶

Klasa WLAN obsługuje wbudowane moduły radiowe WiFi w nowoczesnych kamerach OpenMV Cam. Ta sama klasa opakowuje dwa różne sterowniki niskiego poziomu, w zależności od układu MCU WiFi danej płytki:

CYW43 (moduł WiFi Infineon CYW43xxx firmy Murata). Używany przez OpenMV Cam N6, OpenMV Cam RT1062, Arduino Portenta H7, Arduino Nicla Vision oraz Arduino Giga R1 WiFi.
NINA W10 (u-blox NINA-W10 / ESP32-WROOM). Używany przez Arduino Nano RP2040 Connect.

Oba sterowniki udostępniają te same nazwy metod, lecz różnią się kilkoma argumentami oraz zestawem akceptowanych kluczy config(). Różnice są zaznaczone poniżej.

Kamery OpenMV ze starszą nakładką WiFi WINC1500 (M4 / M7 / H7 / H7 Plus / Pure Thermal) używają zamiast tego klasy WINC.

Przykład użycia:

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

Konstruktory¶

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

Tworzy obiekt interfejsu WLAN.

interface_id wybiera interfejs, na którym ma działać:

WLAN.IF_STA – tryb stacji / klienta. Połącz się z nadrzędnym punktem dostępowym za pomocą connect(). To jest wartość domyślna.

WLAN.IF_AP – tryb punktu dostępowego. Skonfiguruj AP za pomocą config() i przyjmuj połączenia klientów.

Oba interfejsy obsługuje to samo fizyczne radio; utworzenie jednego nie wyklucza drugiego.

Metody¶

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

Włącza lub wyłącza radio WiFi.

Bez argumentu zwraca bieżący stan – True, gdy radio jest włączone, False w przeciwnym razie.

active(True) włącza zasilanie układu MCU WiFi, ładuje jego oprogramowanie układowe (CYW43 pobiera blob oprogramowania układowego z pamięci flash; NINA weryfikuje aktualnie wgraną wersję oprogramowania układowego) i uruchamia interfejs lwIP netif dla tego interfejsu. Wszystkie pozostałe metody – connect(), scan(), ipconfig() i pokrewne – wymagają, aby interfejs był aktywny.

active(False) ponownie wyłącza zasilanie radia. Na interfejsie STA powoduje to także odłączenie od bieżącego AP i zwolnienie netif.

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

Łączy interfejs STA z podanym punktem dostępowym.

ssid – SSID sieci (ciąg znaków lub bajty).

key – hasło / klucz współdzielony. Przekaż None dla sieci otwartej.

security (tylko jako słowo kluczowe) – jedna ze stałych SEC_*. -1 (wartość domyślna) wybiera automatycznie: SEC_OPEN, gdy key jest puste, a w przeciwnym razie SEC_WPA_WPA2.

bssid (tylko jako słowo kluczowe, tylko CYW43) – ogranicza połączenie do AP o tym 6-bajtowym adresie MAC. Ignorowane przez sterownik NINA.

channel (tylko jako słowo kluczowe) – preferowany kanał radiowy. Domyślnie „pozwól sterownikowi wybrać”.

disconnect() → None¶: W trybie STA odłącza od aktualnie połączonego punktu dostępowego. Interfejs pozostaje aktywny; wywołaj ponownie connect(), aby połączyć się ponownie, lub active() (False), aby całkowicie wyłączyć zasilanie radia. Brak efektu, gdy nie ma aktualnego połączenia.

isconnected() → bool¶

W trybie STA zwraca True, gdy istnieje połączenie z punktem dostępowym oraz uzyskano adres IPv4 z DHCP (lub przypisano go statycznie za pomocą ipconfig()). Zwraca False w trakcie fazy uwierzytelniania/łączenia/DHCP.

W trybie AP zwraca True, gdy dołączyła co najmniej jedna stacja.

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

Skanuje pobliskie punkty dostępowe i zwraca listę 6-elementowych krotek:

[0] SSID (bajty; puste dla sieci ukrytych).

[1] BSSID (6-bajtowy MAC, bytes). Przekształć za pomocą binascii.hexlify().

[2] Numer kanału.

[3] RSSI w dBm.

[4] Tryb zabezpieczeń (jedna ze stałych SEC_*).

[5] Zarezerwowane (zawsze 1).

Wszystkie argumenty słów kluczowych dotyczą tylko CYW43:

passive – jeśli True, używa skanowania pasywnego zamiast domyślnego aktywnego skanowania z żądaniami sondującymi.

ssid – ogranicza skanowanie do jednego SSID.

bssid – ogranicza skanowanie do jednego BSSID.

Skanowanie ma sens tylko na interfejsie STA.

status() → int¶

status(param: str) → Any

Sprawdza stan połączenia.

Bez argumentu zwraca stan łącza jako małą liczbę całkowitą (kodowanie zależne od sterownika – wartość prawdziwa oznacza „połączono”).

Z argumentem będącym ciągiem znaków:

"rssi" – w trybie STA zwraca bieżące RSSI w dBm.

"stations" – w trybie AP zwraca listę połączonych stacji. CYW43 zwraca [(mac_bytes,), ...]; NINA zwraca [ip_string, ...].

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

Pobiera lub ustawia parametry IPv4 interfejsu jako 4-elementową krotkę ciągów (ip, subnet, gateway, dns) w notacji kropkowej.

Informacja

W nowym kodzie preferuj ipconfig()

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: Pobiera lub ustawia parametry interfejsu IPv4 / IPv6. Sterownik CYW43 deleguje to do standardowej implementacji lwIP i obsługuje pełny zestaw kluczy udokumentowanych w AbstractNIC.ipconfig(). Sterownik NINA implementuje mniejszy podzbiór dla danego interfejsu – dhcp4 i has_dhcp4 (tylko do odczytu) oraz addr4 i gw4 do pobierania / ustawiania.

config(param: str) → Any¶

config(**kwargs: Any) → None

Pobiera lub ustawia parametry interfejsu specyficzne dla WiFi.

Z pojedynczym pozycyjnym argumentem będącym ciągiem znaków zwraca wartość tego parametru. Z argumentami słów kluczowych ustawia jeden lub więcej parametrów naraz – zmiany dotyczące działającego AP powodują automatyczne wyłączenie i ponowne włączenie AP.

Przykład:

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

Sterownik CYW43 – parametry możliwe do odczytania:

"antenna" – selektor anteny (int).

"channel" – bieżący kanał.

"ssid" / "essid" – bieżący SSID (ciąg znaków).

"security" – tryb uwierzytelniania AP (jeden z SEC_*).

"mac" – adres MAC interfejsu (6 bytes).

"pm" – wartość zarządzania energią.

"txpower" – moc nadawania w dBm.

"hostname" – nazwa hosta DHCP/mDNS. Przestarzałe; zamiast tego użyj network.hostname().

Sterownik CYW43 – parametry możliwe do ustawienia:

antenna=<int> – selektor anteny.

channel=<int> – kanał AP.

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

key=<str> / password=<str> – klucz współdzielony AP.

security=<int> – tryb uwierzytelniania AP (jeden z SEC_*).

pm=<int> – tryb zarządzania energią (jeden z PM_NONE, PM_PERFORMANCE, PM_POWERSAVE).

monitor=<int> – włącza tryb monitorowania / odbioru wszystkich pakietów multicast.

txpower=<int> – moc nadawania w dBm.

trace=<int> – wewnętrzna maska bitowa śledzenia sterownika.

hostname=<str> – nazwa hosta DHCP/mDNS. Przestarzałe; zamiast tego użyj network.hostname().

Sterownik NINA – parametry możliwe do odczytania:

"ssid" – bieżący SSID (ciąg znaków).

"security" – tryb uwierzytelniania AP.

"mac" / "bssid" – adres MAC interfejsu (6 bytes).

"fw_version" – 3-elementowa krotka (major, minor, patch).

Sterownik NINA – parametry możliwe do ustawienia: wywołanie jest przekazywane do connect() i przyjmuje te same argumenty słów kluczowych (ssid, key, security, channel). Ważne tylko na interfejsie AP.

deinit() → None¶: Resetuje przez wyłączenie zasilania układ MCU WiFi i zwalnia wszystkie zasoby utrzymywane przez sterownik (bufory oprogramowania układowego, lwIP netif, magistralę SPI/SDIO). Po wywołaniu tej metody obiekt WLAN musi zostać ponownie utworzony przed użyciem. Używaj jej zamiast active() (False), gdy potrzebujesz pełnego resetu (na przykład przed ponownym wgraniem oprogramowania układowego radia lub w celu odzyskania sterownika z zablokowanego stanu). Tylko CYW43.

send_ethernet(buf: bytes) → None¶: Wstrzykuje surową ramkę Ethernet buf bezpośrednio do ścieżki nadawania sterownika, pomijając stos IP. Przeznaczone dla odbiorców działających tylko na warstwie L2 – mostkowanie, niestandardowe protokoły EtherType i podobne. Ramka musi zawierać docelowy/źródłowy MAC oraz EtherType (bez FCS – sprzęt dołącza je samodzielnie). Tylko CYW43.

ioctl(cmd: int, buf: bytearray) → None¶: Wydaje polecenie sterujące specyficzne dla sterownika. cmd to liczbowy kod ioctl zdefiniowany przez oprogramowanie układowe radia niskiego poziomu, a buf to modyfikowalny bufor używany zarówno dla ładunku polecenia, jak i odpowiedzi. Zestaw poprawnych wartości cmd jest specyficzny dla sterownika i nieprzenośny pomiędzy CYW43 a NINA. Używane głównie przez niskopoziomowe skrypty testowe i kod uruchamiania układów.

Stałe¶

IF_STA: int¶: Identyfikator interfejsu stacji / klienta. Przekaż do konstruktora, aby wybrać tryb STA.

IF_AP: int¶: Identyfikator interfejsu punktu dostępowego. Przekaż do konstruktora, aby wybrać tryb AP.

SEC_OPEN: int¶: Wartość zabezpieczeń dla sieci nieszyfrowanej. Dostępna w obu sterownikach.

SEC_WPA_WPA2: int¶: Wartość zabezpieczeń dla WPA / WPA2 z kluczem współdzielonym. Domyślna, gdy do connect() przekazano klucz. Dostępna w obu sterownikach.

SEC_WPA3: int¶: Wartość zabezpieczeń dla WPA3 (SAE) z kluczem współdzielonym. Tylko CYW43.

SEC_WPA2_WPA3: int¶: Wartość zabezpieczeń dla trybu przejściowego WPA2 / WPA3. Tylko CYW43.

SEC_WEP: int¶: Wartość zabezpieczeń dla WEP (Wired Equivalent Privacy). Udostępniona w celu zgodności ze starszymi punktami dostępowymi – WEP jest kryptograficznie złamany i nie powinien być używany w nowych wdrożeniach. Tylko NINA.

OPEN: int¶: Alias zachowujący zgodność wsteczną dla SEC_OPEN. Nowy kod powinien używać SEC_OPEN. Tylko NINA.

WEP: int¶: Alias zachowujący zgodność wsteczną dla SEC_WEP. Nowy kod powinien używać SEC_WEP. Tylko NINA.

WPA_PSK: int¶: Alias zachowujący zgodność wsteczną dla SEC_WPA_WPA2. Nowy kod powinien używać SEC_WPA_WPA2. Tylko NINA.

PM_NONE: int¶: Przekaż do config(pm=...), aby wyłączyć zarządzanie energią WiFi. Tylko CYW43.

PM_PERFORMANCE: int¶: Przekaż do config(pm=...), aby włączyć zarządzanie energią WiFi dostrojone pod kątem wydajności. Tylko CYW43.

PM_POWERSAVE: int¶: Przekaż do config(pm=...), aby włączyć zarządzanie energią WiFi dostrojone pod kątem maksymalnej żywotności baterii. Tylko CYW43.