class WINC – driver dello shield WiFi

La classe WINC pilota il modulo WiFi Atmel WINC1500 802.11 b/g/n sull’OpenMV WiFi Shield. Disponibile su OpenMV Cam M4, M7, H7, H7 Plus e Pure Thermal (le schede STM32 per cui è stato progettato lo shield WiFi). Per le schede con WiFi integrato (OpenMV Cam N6, OpenMV Cam RT1062, Arduino Giga) usa invece WLAN.

Esempio – connettersi a un access point e stampare l’indirizzo:

import network

wlan = network.WINC()
wlan.connect("SSID", "KEY", security=network.WINC.WPA_PSK)

print("status:    ", "connected" if wlan.isconnected() else "off")
print("rssi:      ", wlan.rssi(), "dBm")
print("interface: ", wlan.ifconfig())
print("netinfo:   ", wlan.netinfo())

Esempio – attivare un access point aperto e attendere un client:

import network

wlan = network.WINC(mode=network.WINC.MODE_AP)
wlan.start_ap("OpenMV-Cam", security=network.WINC.OPEN, channel=6)

print("waiting for a station to associate...")
print(wlan.wait_for_sta(timeout=None))

Costruttori

class network.WINC(mode: int = WINC.MODE_STA) → None

Crea un oggetto driver WINC e attiva lo shield WiFi.

mode seleziona la modalità operativa in cui il modulo si avvia:

Nota

In modalità AP il WINC1500 ha dei limiti hardware:

  • Può connettersi un solo client alla volta.

  • Sono supportate solo le sicurezze OPEN o WEP.

  • Un bug nel firmware del modulo WiFi fa sì che qualsiasi socket associato smetta di funzionare quando il client si disconnette. Imposta un timeout sul socket del server in modo che sollevi un’eccezione che puoi usare per riaprirlo.

Metodi

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

Attiva o disattiva lo shield WiFi.

Senza argomenti, restituisce lo stato attuale – True mentre lo shield è inizializzato e la radio è attiva, False altrimenti.

active(True) esegue l’handshake del firmware del WINC1500 su SPI e attiva la radio nella mode configurata. È un no-op se l’interfaccia è già attiva. connect() lo richiama automaticamente se non è ancora stato chiamato; per qualsiasi altro metodo (scan(), rssi(), netinfo(), …) devi prima chiamare active(True).

active(False) spegne nuovamente la radio (il WINC torna alla modalità solo BSP) e rilascia i pin SPI.

connect(ssid: str, key: str | None = None, *, security: int = WINC.WPA_PSK, channel: int = 1) → None

Si associa alla rete WiFi ssid usando la password key, la modalità di sicurezza security (una tra OPEN, WPA_PSK o la costante 802.1X) sul canale radio channel. security e channel sono solo keyword.

Dopo la connessione usa il modulo socket per aprire porte TCP/UDP.

Questo metodo si blocca finché l’associazione non si completa o fallisce.

config(ssid: str, key: str | None = None, *, security: int = WINC.WPA_PSK, channel: int = 1) → None

Alias di connect(). Fornito per compatibilità con il codice che chiama config su altre interfacce network.

start_ap(ssid: str, key: str | None = None, *, security: int = WINC.OPEN, channel: int = 1) → None

Alias di connect() usato dopo aver costruito l’oggetto con mode=MODE_AP per configurare e avviare l’access point. L’AP supporta solo le sicurezze OPEN o WEP; se viene usata WEP è richiesto key.

disconnect() → None

In modalità STA, si dissocia dall’access point attualmente associato. Lo shield rimane attivo; chiama connect() per riassociarti. No-op quando non si è attualmente associati.

isconnected() → bool

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

connected_sta() → List[str]

In modalità AP, restituisce una lista contenente l’indirizzo IP del client attualmente connesso (o una lista vuota se nessun client è connesso).

wait_for_sta(timeout: int | None) → List[str]

In modalità AP, si blocca finché un client non si connette e restituisce una lista contenente l’indirizzo IP del client. timeout è l’attesa massima in millisecondi; passa None per attendere indefinitamente.

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

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

Chiamato senza argomenti: restituisce la configurazione attuale.

Chiamato con una tupla di 4 elementi: imposta una configurazione IP statica al posto di quella acquisita tramite DHCP.

Esempio – fissare un IP statico prima di connettersi:

wlan = network.WINC()
wlan.ifconfig(("192.168.1.100", "255.255.255.0",
               "192.168.1.1", "192.168.1.1"))
wlan.connect(SSID, key=KEY, security=network.WINC.WPA_PSK)

Nota

WINC non implementa la moderna API AbstractNIC.ipconfig(); usa ifconfig() qui.

netinfo() → Tuple[int, int, str, str, str]

Restituisce una tupla di 5 elementi che descrive l’associazione attuale:

  • [0] RSSI come int (dBm).

  • [1] Modalità di sicurezza – una delle costanti di sicurezza.

  • [2] Stringa SSID.

  • [3] BSSID come stringa MAC "XX:XX:XX:XX:XX:XX".

  • [4] Indirizzo IPv4 come stringa in notazione puntata.

scan() → List[Tuple[str, str, int, int, int, int]]

Esegue la scansione degli access point nelle vicinanze. Restituisce una lista di tuple di 6 elementi:

  • [0] Stringa SSID.

  • [1] BSSID come stringa MAC "XX:XX:XX:XX:XX:XX".

  • [2] Numero del canale.

  • [3] RSSI in dBm.

  • [4] Modalità di sicurezza – una delle costanti di sicurezza.

  • [5] Riservato (sempre 1).

Può essere chiamato senza prima associarsi a una rete.

rssi() → int

Restituisce l’RSSI in dBm dell’access point attualmente associato. Approssimativamente: -30 è eccellente, -67 è OK per lo streaming, -80 è marginale, -90 e inferiore è inutilizzabile. Significativo solo in modalità STA mentre isconnected() è True.

fw_version() → Tuple[int, int, int, int, int, int, int]

Restituisce una tupla di 7 elementi che descrive le versioni del firmware e del driver del WINC1500:

  • [0] Major del firmware.

  • [1] Minor del firmware.

  • [2] Patch del firmware.

  • [3] Major del driver.

  • [4] Minor del driver.

  • [5] Patch del driver.

  • [6] Revisione hardware del chip.

fw_dump(path: str) → None

Legge la flash interna del WINC1500 e scrive l’immagine firmware risultante nel file in path sul filesystem dell’OpenMV. Usalo per eseguire il backup dell’immagine attualmente installata prima di chiamare fw_update().

Richiede che il modulo sia stato costruito con mode=MODE_FIRMWARE.

fw_update(path: str) → None

Cancella la flash interna del WINC1500 e la programma con l’immagine binaria in path. L’immagine deve corrispondere al layout previsto dal firmware OpenMV (tipicamente fornita da Atmel / Microchip con il WINC SDK).

La chiamata si blocca per diversi secondi mentre la flash viene programmata e verificata. Spegni e riaccendi l’OpenMV Cam dopo il ritorno della chiamata in modo che il WINC1500 si avvii dalla nuova immagine.

Richiede che il modulo sia stato costruito con mode=MODE_FIRMWARE.

Costanti

OPEN: int

Valore di sicurezza per una rete non crittografata. Passa all’argomento security di connect() / start_ap().

WPA_PSK: int

Valore di sicurezza per WPA/WPA2 con chiave pre-condivisa. Il valore predefinito per connect().

Nota

Esiste anche un valore di sicurezza WPA/WPA2 Enterprise (802.1X). Il firmware lo espone con il nome 802_1X, che non è un identificatore Python valido – accedivi tramite getattr(network.WINC, "802_1X").

MODE_STA: int

Modalità stazione – connettersi a un access point come client. La modalità predefinita del costruttore.

MODE_AP: int

Modalità access point – il WINC diventa l’AP a cui i client si associano.

MODE_P2P: int

Modalità WiFi-Direct (peer-to-peer).

MODE_BSP: int

Inizializza solo il board-support package del WINC – la radio non viene attivata. Usata dal flusso di aggiornamento firmware.

MODE_FIRMWARE: int

Modalità di aggiornamento firmware. Richiesta da fw_dump() e fw_update().