classe WLAN – controllo delle interfacce WiFi integrate¶

La classe WLAN pilota le radio WiFi integrate nelle moderne OpenMV Cam. La stessa classe incapsula due driver sottostanti diversi a seconda dell’MCU WiFi della scheda:

CYW43 (modulo WiFi Infineon CYW43xxx Murata). Utilizzato da OpenMV Cam N6, OpenMV Cam RT1062, Arduino Portenta H7, Arduino Nicla Vision e Arduino Giga R1 WiFi.
NINA W10 (u-blox NINA-W10 / ESP32-WROOM). Utilizzato dall’Arduino Nano RP2040 Connect.

I due driver espongono gli stessi nomi di metodo ma differiscono per alcuni argomenti e per l’insieme delle chiavi config() accettate. Le differenze sono segnalate di seguito.

Le camere OpenMV con uno shield WiFi WINC1500 legacy (M4 / M7 / H7 / H7 Plus / Pure Thermal) utilizzano invece WINC.

Esempio di utilizzo:

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

Costruttori¶

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

Crea un oggetto interfaccia WLAN.

interface_id seleziona su quale interfaccia operare:

WLAN.IF_STA – modalità station / client. Connettiti a un access point a monte con connect(). Questa è la modalità predefinita.

WLAN.IF_AP – modalità access-point. Configura l’AP con config() e accetta le connessioni dei client.

La stessa radio fisica supporta entrambe le interfacce; costruirne una non preclude l’altra.

Metodi¶

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

Attiva o disattiva la radio WiFi.

Senza argomenti, restituisce lo stato corrente – True quando la radio è attiva, False altrimenti.

active(True) alimenta l’MCU WiFi, ne carica il firmware (CYW43 recupera il blob del firmware dalla flash; NINA convalida la versione del firmware attualmente programmata) e attiva il netif lwIP per questa interfaccia. Tutti gli altri metodi – connect(), scan(), ipconfig() e affini – richiedono che l’interfaccia sia attiva.

active(False) rimette in standby la radio. Sull’interfaccia STA questo provoca anche la disassociazione dall’AP corrente e il rilascio del netif.

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

Associa l’interfaccia STA all’access point indicato.

ssid – l’SSID della rete (stringa o bytes).

key – password / chiave precondivisa. Passa None per una rete aperta.

security (solo keyword) – una delle costanti SEC_*. -1 (il valore predefinito) effettua una selezione automatica: SEC_OPEN quando key è vuota, SEC_WPA_WPA2 altrimenti.

bssid (solo keyword, solo CYW43) – limita l’associazione all’AP con questo indirizzo MAC a 6 byte. Ignorato dal driver NINA.

channel (solo keyword) – canale radio preferito. Il valore predefinito è «lascia scegliere al driver».

disconnect() → None¶: In modalità STA, disassocia dall’access point attualmente associato. L’interfaccia rimane attiva; richiama connect() per riassociarti, oppure active() (False) per mettere completamente in standby la radio. Non ha effetto quando non si è associati.

isconnected() → bool¶

In modalità STA restituisce True quando si è associati a un access point e è stato ottenuto un indirizzo IPv4 tramite DHCP (o assegnato staticamente tramite ipconfig()). Restituisce False mentre il collegamento è ancora nella fase di autenticazione/associazione/DHCP.

In modalità AP restituisce True quando almeno una station si è unita.

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

Cerca gli access point nelle vicinanze e restituisce un elenco di tuple di 6 elementi:

[0] SSID (bytes; vuoto per le reti nascoste).

[1] BSSID (MAC a 6 byte, bytes). Converti con binascii.hexlify().

[2] Numero del canale.

[3] RSSI in dBm.

[4] Modalità di sicurezza (una delle costanti SEC_*).

[5] Riservato (sempre 1).

Tutti gli argomenti keyword sono esclusivi di CYW43:

passive – se True, utilizza una scansione passiva anziché la scansione attiva predefinita basata su probe-request.

ssid – limita la scansione a un solo SSID.

bssid – limita la scansione a un solo BSSID.

La scansione ha senso solo su un’interfaccia STA.

status() → int¶

status(param: str) → Any

Interroga lo stato della connessione.

Senza argomenti, restituisce lo stato del collegamento come piccolo intero (codifica specifica del driver – un valore truthy significa «associato»).

Con un argomento stringa:

"rssi" – in modalità STA, restituisce l’RSSI corrente in dBm.

"stations" – in modalità AP, restituisce un elenco delle station connesse. CYW43 restituisce [(mac_bytes,), ...]; NINA restituisce [ip_string, ...].

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

Ottiene o imposta i parametri IPv4 dell’interfaccia come tupla di 4 elementi di stringhe in notazione puntata (ip, subnet, gateway, dns).

Nota

Per il nuovo codice preferisci 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: Ottiene o imposta i parametri IPv4 / IPv6 dell’interfaccia. Il driver CYW43 delega all’implementazione standard lwIP e supporta l’intero insieme di chiavi documentate in AbstractNIC.ipconfig(). Il driver NINA implementa un sottoinsieme per-interfaccia più ridotto – dhcp4 e has_dhcp4 (sola lettura), oltre a addr4 e gw4 per get / set.

config(param: str) → Any¶

config(**kwargs: Any) → None

Ottiene o imposta i parametri dell’interfaccia specifici del WiFi.

Con un singolo argomento posizionale stringa, restituisce il valore di quel parametro. Con argomenti keyword, imposta uno o più parametri contemporaneamente – le modifiche che interessano un AP in funzione fanno sì che l’AP venga arrestato e riavviato automaticamente.

Esempio:

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

Driver CYW43 – parametri leggibili:

"antenna" – selettore di antenna (int).

"channel" – canale corrente.

"ssid" / "essid" – l’SSID corrente (stringa).

"security" – la modalità di autenticazione dell’AP (una delle SEC_*).

"mac" – indirizzo MAC dell’interfaccia (6 bytes).

"pm" – valore di gestione dell’alimentazione.

"txpower" – potenza di trasmissione in dBm.

"hostname" – hostname DHCP/mDNS. Deprecato; usa invece network.hostname().

Driver CYW43 – parametri impostabili:

antenna=<int> – selettore di antenna.

channel=<int> – canale dell’AP.

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

key=<str> / password=<str> – chiave precondivisa dell’AP.

security=<int> – modalità di autenticazione dell’AP (una delle SEC_*).

pm=<int> – modalità di gestione dell’alimentazione (una tra PM_NONE, PM_PERFORMANCE, PM_POWERSAVE).

monitor=<int> – abilita la modalità monitor / all-multicast.

txpower=<int> – potenza di trasmissione in dBm.

trace=<int> – bitmask di trace interna del driver.

hostname=<str> – hostname DHCP/mDNS. Deprecato; usa invece network.hostname().

Driver NINA – parametri leggibili:

"ssid" – l’SSID corrente (stringa).

"security" – la modalità di autenticazione dell’AP.

"mac" / "bssid" – indirizzo MAC dell’interfaccia (6 bytes).

"fw_version" – una tupla di 3 elementi (major, minor, patch).

Driver NINA – parametri impostabili: la chiamata viene inoltrata a connect() e accetta gli stessi argomenti keyword (ssid, key, security, channel). Valida solo sull’interfaccia AP.

deinit() → None¶: Riavvia l’MCU WiFi (power-cycle) e rilascia tutte le risorse trattenute dal driver (buffer del firmware, netif lwIP, bus SPI/SDIO). Dopo questa chiamata l’oggetto WLAN deve essere ricostruito prima dell’uso. Usa questo metodo anziché active() (False) quando hai bisogno di un reset completo (per esempio, prima di riprogrammare il firmware della radio o per recuperare da uno stato bloccato del driver). Solo CYW43.

send_ethernet(buf: bytes) → None¶: Inietta il frame Ethernet grezzo buf direttamente nel percorso di trasmissione del driver, bypassando lo stack IP. Pensato per consumatori di solo L2 – bridging, protocolli EtherType personalizzati e simili. Il frame deve includere MAC di destinazione/sorgente e EtherType (nessun FCS – l’hardware lo aggiunge). Solo CYW43.

ioctl(cmd: int, buf: bytearray) → None¶: Emette un comando di controllo specifico del driver. cmd è il codice ioctl numerico definito dal firmware della radio sottostante e buf è un buffer mutabile utilizzato sia per il payload del comando sia per la risposta. L’insieme dei valori cmd validi è specifico del driver e non è portabile tra CYW43 e NINA. Utilizzato principalmente da script di test di basso livello e codice di bring-up del chip.

Costanti¶

IF_STA: int¶: Identificatore dell’interfaccia station / client. Passalo al costruttore per selezionare la modalità STA.

IF_AP: int¶: Identificatore dell’interfaccia access-point. Passalo al costruttore per selezionare la modalità AP.

SEC_OPEN: int¶: Valore di sicurezza per una rete non cifrata. Disponibile su entrambi i driver.

SEC_WPA_WPA2: int¶: Valore di sicurezza per WPA / WPA2 con chiave precondivisa. Il valore predefinito quando viene fornita una chiave a connect(). Disponibile su entrambi i driver.

SEC_WPA3: int¶: Valore di sicurezza per WPA3 (SAE) con chiave precondivisa. Solo CYW43.

SEC_WPA2_WPA3: int¶: Valore di sicurezza per la modalità di transizione WPA2 / WPA3. Solo CYW43.

SEC_WEP: int¶: Valore di sicurezza per WEP (Wired Equivalent Privacy). Fornito per compatibilità con gli access point legacy – WEP è crittograficamente compromesso e non dovrebbe essere usato nelle nuove installazioni. Solo NINA.

OPEN: int¶: Alias retrocompatibile di SEC_OPEN. Il nuovo codice dovrebbe usare SEC_OPEN. Solo NINA.

WEP: int¶: Alias retrocompatibile di SEC_WEP. Il nuovo codice dovrebbe usare SEC_WEP. Solo NINA.

WPA_PSK: int¶: Alias retrocompatibile di SEC_WPA_WPA2. Il nuovo codice dovrebbe usare SEC_WPA_WPA2. Solo NINA.

PM_NONE: int¶: Passa a config(pm=...) per disabilitare la gestione dell’alimentazione WiFi. Solo CYW43.

PM_PERFORMANCE: int¶: Passa a config(pm=...) per abilitare la gestione dell’alimentazione WiFi ottimizzata per le prestazioni. Solo CYW43.

PM_POWERSAVE: int¶: Passa a config(pm=...) per abilitare la gestione dell’alimentazione WiFi ottimizzata per la massima durata della batteria. Solo CYW43.