class WINC – controlador do shield WiFi¶

A classe WINC controla o módulo WiFi Atmel WINC1500 802.11 b/g/n no OpenMV WiFi Shield. Disponível no OpenMV Cam M4, M7, H7, H7 Plus e Pure Thermal (as placas STM32 para as quais o shield WiFi foi concebido). Para placas com WiFi integrado (OpenMV Cam N6, OpenMV Cam RT1062, Arduino Giga) utilize WLAN em alternativa.

Exemplo – ligar a um ponto de acesso e imprimir o endereço:

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

Exemplo – criar um ponto de acesso aberto e aguardar por um 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))

Construtores¶

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

Cria um objeto controlador WINC e ativa o shield WiFi.

mode seleciona o modo de funcionamento em que o módulo arranca:

WINC.MODE_STA – estação / cliente. Liga-se a um ponto de acesso com connect(). Este é o modo padrão.

WINC.MODE_AP – ponto de acesso. Configure o AP com start_ap(), depois aceite ligações de clientes.

WINC.MODE_P2P – WiFi Direct.

WINC.MODE_BSP – ativa apenas o BSP (sem rádio).

WINC.MODE_FIRMWARE – modo de atualização de firmware; necessário para fw_dump() e fw_update().

Nota

No modo AP, o WINC1500 tem limitações de hardware:

Apenas um cliente pode ligar-se de cada vez.
Apenas a segurança OPEN ou WEP é suportada.
Um bug no firmware do módulo WiFi faz com que qualquer socket ligado deixe de funcionar quando o cliente se desliga. Defina um timeout no socket do servidor para que seja lançada uma exceção que pode usar para o reabrir.

Métodos¶

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

Liga ou desliga o shield WiFi.

Sem argumento, devolve o estado atual – True enquanto o shield estiver inicializado e o rádio estiver ativo, False caso contrário.

active(True) realiza o handshake do firmware WINC1500 via SPI e ativa o rádio no mode configurado. É uma operação sem efeito se a interface já estiver ativa. connect() chama-o automaticamente se ainda não tiver sido chamado; para qualquer outro método (scan(), rssi(), netinfo(), …) deve chamar active(True) primeiro.

active(False) desliga o rádio (o WINC passa para o modo apenas BSP) e liberta os pinos SPI.

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

Associa-se à rede WiFi ssid usando a palavra-passe key, o modo de segurança security (um de OPEN, WPA_PSK ou a constante 802.1X) no canal de rádio channel. security e channel são exclusivamente por palavra-chave.

Após a ligação, use o módulo socket para abrir portas TCP/UDP.

Este método bloqueia até que a associação seja concluída ou falhe.

config(ssid: str, key: str | None = None, *, security: int = WINC.WPA_PSK, channel: int = 1) → None¶: Alias de connect(). Fornecido para compatibilidade com código que chama config noutras interfaces network.

start_ap(ssid: str, key: str | None = None, *, security: int = WINC.OPEN, channel: int = 1) → None¶: Alias de connect() utilizado após construir o objeto com mode=MODE_AP para configurar e iniciar o ponto de acesso. O AP suporta apenas a segurança OPEN ou WEP; se WEP for usado, key é obrigatório.

disconnect() → None¶: No modo STA, desassocia-se do ponto de acesso atualmente associado. O shield permanece ativo; chame connect() para reassociar. Sem efeito quando não está associado.

isconnected() → bool¶: No modo STA, devolve True quando está associado a um ponto de acesso e foi obtido um endereço IPv4 (via DHCP ou ifconfig()). Devolve False durante a fase de autenticação / associação / DHCP.

connected_sta() → List[str]¶: No modo AP, devolve uma lista contendo o endereço IP do cliente atualmente ligado (ou uma lista vazia se nenhum cliente estiver ligado).

wait_for_sta(timeout: int | None) → List[str]¶: No modo AP, bloqueia até que um cliente se ligue e devolve uma lista contendo o endereço IP do cliente. timeout é o tempo máximo de espera em milissegundos; passe None para aguardar indefinidamente.

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

Obtém ou define os parâmetros IPv4 da interface. O tuplo de 4 elementos contém (ip, subnet, gateway, dns) como strings em notação decimal pontuada.

Chamado sem argumento: devolve a configuração atual.

Chamado com um tuplo de 4 elementos: define uma configuração IP estática em substituição da obtida por DHCP.

Exemplo – definir um IP estático antes de ligar:

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 não implementa a API moderna AbstractNIC.ipconfig(); use ifconfig() aqui.

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

Devolve um tuplo de 5 elementos que descreve a associação atual:

[0] RSSI como inteiro (dBm).

[1] Modo de segurança – uma das constantes de segurança.

[2] String SSID.

[3] BSSID como string MAC no formato "XX:XX:XX:XX:XX:XX".

[4] Endereço IPv4 como string em notação decimal pontuada.

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

Procura pontos de acesso próximos. Devolve uma lista de tuplos de 6 elementos:

[0] String SSID.

[1] BSSID como string MAC no formato "XX:XX:XX:XX:XX:XX".

[2] Número do canal.

[3] RSSI em dBm.

[4] Modo de segurança – uma das constantes de segurança.

[5] Reservado (sempre 1).

Pode ser chamado sem estar previamente associado a uma rede.

rssi() → int¶: Devolve o RSSI em dBm do ponto de acesso atualmente associado. Aproximadamente: -30 é excelente, -67 é aceitável para streaming, -80 é marginal, -90 e abaixo é inutilizável. Apenas significativo no modo STA enquanto isconnected() for True.

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

Devolve um tuplo de 7 elementos que descreve as versões do firmware e do controlador do WINC1500:

[0] Major do firmware.

[1] Minor do firmware.

[2] Patch do firmware.

[3] Major do controlador.

[4] Minor do controlador.

[5] Patch do controlador.

[6] Revisão de hardware do chip.

fw_dump(path: str) → None¶

Lê a flash interna do WINC1500 e escreve a imagem de firmware resultante no ficheiro em path no sistema de ficheiros do OpenMV. Use isto para criar uma cópia de segurança da imagem atualmente instalada antes de chamar fw_update().

Requer que o módulo tenha sido construído com mode=MODE_FIRMWARE.

fw_update(path: str) → None¶

Apaga a flash interna do WINC1500 e programa-a com a imagem binária em path. A imagem deve corresponder ao layout esperado pelo firmware do OpenMV (normalmente fornecida pela Atmel / Microchip com o WINC SDK).

A chamada bloqueia durante vários segundos enquanto a flash é programada e verificada. Faça um ciclo de alimentação no OpenMV Cam após o retorno da chamada para que o WINC1500 arranque com a nova imagem.

Requer que o módulo tenha sido construído com mode=MODE_FIRMWARE.

Constantes¶

OPEN: int¶: Valor de segurança para uma rede não encriptada. Passe ao argumento security de connect() / start_ap().

WPA_PSK: int¶: Valor de segurança para WPA/WPA2 com chave pré-partilhada. O valor padrão para connect().

Nota

Existe também um valor de segurança WPA/WPA2 Enterprise (802.1X). O firmware expõe-o com o nome 802_1X, que não é um identificador Python válido – aceda-lhe via getattr(network.WINC, "802_1X").

MODE_STA: int¶: Modo de estação – liga-se a um ponto de acesso como cliente. O modo padrão do construtor.

MODE_AP: int¶: Modo de ponto de acesso – o WINC torna-se o AP ao qual os clientes se associam.

MODE_P2P: int¶: Modo WiFi-Direct (ponto-a-ponto).

MODE_BSP: int¶: Inicializa apenas o pacote de suporte de placa WINC – o rádio não é ativado. Utilizado pelo fluxo de atualização de firmware.

MODE_FIRMWARE: int¶: Modo de atualização de firmware. Necessário para fw_dump() e fw_update().