class WINC – controlador del escudo WiFi

La clase WINC controla el módulo WiFi Atmel WINC1500 802.11 b/g/n del OpenMV WiFi Shield. Disponible en la OpenMV Cam M4, M7, H7, H7 Plus y Pure Thermal (las placas STM32 para las que se diseñó el escudo WiFi). Para placas con WiFi integrado (OpenMV Cam N6, OpenMV Cam RT1062, Arduino Giga) usa WLAN en su lugar.

Ejemplo – conectarse a un punto de acceso e imprimir la dirección:

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

Ejemplo – levantar un punto de acceso abierto y esperar a un cliente:

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

Constructores

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

Crea un objeto controlador WINC y levanta el escudo WiFi.

mode selecciona el modo de funcionamiento con el que arranca el módulo:

Nota

En modo AP el WINC1500 tiene límites de hardware:

  • Solo puede conectarse un cliente a la vez.

  • Solo se admite seguridad OPEN o WEP.

  • Un error en el firmware del módulo WiFi hace que cualquier socket vinculado deje de funcionar cuando el cliente se desconecta. Establece un tiempo de espera en el socket del servidor para que lance una excepción que puedas usar para reabrirlo.

Métodos

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

Activa o desactiva el escudo WiFi.

Sin argumentos, devuelve el estado actual – True mientras el escudo está inicializado y la radio activa, False en caso contrario.

active(True) realiza el protocolo de inicio del firmware del WINC1500 a través de SPI y levanta la radio en el mode configurado. No tiene efecto si la interfaz ya está activa. connect() lo llama automáticamente si aún no se ha llamado; para cualquier otro método (scan(), rssi(), netinfo(), …) debes llamar primero a active(True).

active(False) apaga de nuevo la radio (el WINC pasa al modo solo BSP) y libera los pines SPI.

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

Se asocia con la red WiFi ssid usando la contraseña key, el modo de seguridad security (uno de OPEN, WPA_PSK o la constante 802.1X) en el canal de radio channel. security y channel son de palabra clave únicamente.

Tras conectarte, usa el módulo socket para abrir puertos TCP/UDP.

Este método se bloquea hasta que la asociación se completa o falla.

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

Alias de connect(). Se proporciona por compatibilidad con código que llama a config en otras interfaces de network.

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

Alias de connect() que se usa tras construir el objeto con mode=MODE_AP para configurar e iniciar el punto de acceso. El AP solo admite seguridad OPEN o WEP; si se usa WEP, key es obligatorio.

disconnect() → None

En modo STA, se desasocia del punto de acceso actualmente asociado. El escudo permanece activo; llama a connect() para reasociarte. No tiene efecto cuando no hay ninguna asociación activa.

isconnected() → bool

En modo STA, devuelve True cuando está asociado con un punto de acceso y se ha obtenido una dirección IPv4 (mediante DHCP o ifconfig()). Devuelve False mientras sigue en la fase de autenticación / asociación / DHCP.

connected_sta() → List[str]

En modo AP, devuelve una lista que contiene la dirección IP del cliente actualmente conectado (o una lista vacía si no hay ningún cliente conectado).

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

En modo AP, se bloquea hasta que un cliente se conecta y devuelve una lista que contiene la dirección IP del cliente. timeout es la espera máxima en milisegundos; pasa None para esperar indefinidamente.

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

Obtiene o establece los parámetros de interfaz IPv4. La tupla de 4 elementos contiene (ip, subnet, gateway, dns) como cadenas en notación decimal con puntos.

Llamado sin argumentos: devuelve la configuración actual.

Llamado con una tupla de 4 elementos: establece una configuración IP estática en lugar de la obtenida por DHCP.

Ejemplo – fijar una IP estática antes de conectar:

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 no implementa la API moderna AbstractNIC.ipconfig(); usa aquí ifconfig().

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

Devuelve una tupla de 5 elementos que describe la asociación actual:

  • [0] RSSI como entero (dBm).

  • [1] Modo de seguridad – una de las constantes de seguridad.

  • [2] Cadena SSID.

  • [3] BSSID como cadena MAC "XX:XX:XX:XX:XX:XX".

  • [4] Dirección IPv4 como cadena en notación decimal con puntos.

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

Busca puntos de acceso cercanos. Devuelve una lista de tuplas de 6 elementos:

  • [0] Cadena SSID.

  • [1] BSSID como cadena MAC "XX:XX:XX:XX:XX:XX".

  • [2] Número de canal.

  • [3] RSSI en dBm.

  • [4] Modo de seguridad – una de las constantes de seguridad.

  • [5] Reservado (siempre 1).

Puede llamarse sin asociarse primero con una red.

rssi() → int

Devuelve el RSSI en dBm del punto de acceso actualmente asociado. Aproximadamente: -30 es excelente, -67 es aceptable para streaming, -80 es marginal, -90 y por debajo es inutilizable. Solo tiene sentido en modo STA mientras isconnected() sea True.

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

Devuelve una tupla de 7 elementos que describe las versiones de firmware y controlador del WINC1500:

  • [0] Versión mayor del firmware.

  • [1] Versión menor del firmware.

  • [2] Parche del firmware.

  • [3] Versión mayor del controlador.

  • [4] Versión menor del controlador.

  • [5] Parche del controlador.

  • [6] Revisión de hardware del chip.

fw_dump(path: str) → None

Lee la memoria flash interna del WINC1500 y escribe la imagen de firmware resultante en el archivo en path del sistema de archivos de la OpenMV. Usa esto para respaldar la imagen instalada actualmente antes de llamar a fw_update().

Requiere que el módulo se haya construido con mode=MODE_FIRMWARE.

fw_update(path: str) → None

Borra la memoria flash interna del WINC1500 y la programa con la imagen binaria en path. La imagen debe coincidir con la disposición que espera el firmware de OpenMV (normalmente suministrada por Atmel / Microchip con el WINC SDK).

La llamada se bloquea durante varios segundos mientras se programa y verifica la memoria flash. Apaga y enciende la OpenMV Cam después de que la llamada regrese para que el WINC1500 arranque desde la nueva imagen.

Requiere que el módulo se haya construido con mode=MODE_FIRMWARE.

Constantes

OPEN: int

Valor de seguridad para una red sin cifrar. Pasa al argumento security de connect() / start_ap().

WPA_PSK: int

Valor de seguridad para WPA/WPA2 con una clave precompartida. El valor predeterminado para connect().

Nota

También existe un valor de seguridad WPA/WPA2 Enterprise (802.1X). El firmware lo expone con el nombre 802_1X, que no es un identificador de Python válido – accede a él mediante getattr(network.WINC, "802_1X").

MODE_STA: int

Modo estación – conectarse a un punto de acceso como cliente. El modo predeterminado del constructor.

MODE_AP: int

Modo punto de acceso – el WINC se convierte en el AP con el que se asocian los clientes.

MODE_P2P: int

Modo WiFi-Direct (punto a punto).

MODE_BSP: int

Inicializa únicamente el paquete de soporte de placa (BSP) del WINC – la radio no se levanta. Lo usa el flujo de actualización de firmware.

MODE_FIRMWARE: int

Modo de actualización de firmware. Requerido por fw_dump() y fw_update().