classe WLAN – controle das interfaces WiFi integradas¶

A classe WLAN controla os rádios WiFi embarcados nas OpenMV Cams modernas. A mesma classe encapsula dois drivers subjacentes diferentes, dependendo do MCU WiFi da placa:

CYW43 (módulo WiFi Infineon CYW43xxx Murata). Usado pela 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). Usado pela Arduino Nano RP2040 Connect.

Os dois drivers expõem os mesmos nomes de métodos, mas diferem em alguns argumentos e no conjunto de chaves config() aceitas. As diferenças são indicadas abaixo.

As câmeras OpenMV com um shield WiFi WINC1500 legado (M4 / M7 / H7 / H7 Plus / Pure Thermal) usam WINC em vez disso.

Exemplo de uso:

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

Construtores¶

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

Cria um objeto de interface WLAN.

interface_id seleciona em qual interface operar:

WLAN.IF_STA – modo estação / cliente. Conecta-se a um ponto de acesso upstream com connect(). Este é o padrão.

WLAN.IF_AP – modo ponto de acesso. Configure o AP com config() e aceite conexões de clientes.

O mesmo rádio físico atende ambas as interfaces; construir uma não impede a outra.

Métodos¶

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

Liga ou desliga o rádio WiFi.

Sem argumento, retorna o estado atual – True enquanto o rádio está ligado, False caso contrário.

active(True) energiza o MCU WiFi, carrega seu firmware (o CYW43 busca o blob de firmware da flash; o NINA valida a versão de firmware atualmente gravada) e ativa a netif lwIP para esta interface. Todos os demais métodos – connect(), scan(), ipconfig() e afins – exigem que a interface esteja ativa.

active(False) desliga o rádio novamente. Na interface STA isso também desassocia do AP atual e libera a netif.

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

Associa a interface STA ao ponto de acesso informado.

ssid – o SSID da rede (string ou bytes).

key – senha / chave pré-compartilhada. Passe None para uma rede aberta.

security (somente por palavra-chave) – uma das constantes SEC_*. -1 (o padrão) seleciona automaticamente: SEC_OPEN quando key está vazia, SEC_WPA_WPA2 caso contrário.

bssid (somente por palavra-chave, apenas CYW43) – restringe a associação ao AP com este endereço MAC de 6 bytes. Ignorado pelo driver NINA.

channel (somente por palavra-chave) – canal de rádio preferido. O padrão é “deixar o driver escolher”.

disconnect() → None¶: No modo STA, desassocia do ponto de acesso atualmente associado. A interface permanece ativa; chame connect() novamente para reassociar, ou active() (False) para desligar o rádio completamente. Não faz nada quando não há associação atual.

isconnected() → bool¶

No modo STA, retorna True quando associado a um ponto de acesso e um endereço IPv4 foi obtido via DHCP (ou atribuído estaticamente por ipconfig()). Retorna False enquanto o enlace ainda está na fase de autenticação/associação/DHCP.

No modo AP, retorna True quando pelo menos uma estação se conectou.

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

Procura pontos de acesso próximos e retorna uma lista de 6-tuplas:

[0] SSID (bytes; vazio para redes ocultas).

[1] BSSID (MAC de 6 bytes, bytes). Converta com binascii.hexlify().

[2] Número do canal.

[3] RSSI em dBm.

[4] Modo de segurança (uma das constantes SEC_*).

[5] Reservado (sempre 1).

Todos os argumentos por palavra-chave são exclusivos do CYW43:

passive – se True, usa uma varredura passiva em vez da varredura ativa por probe-request padrão.

ssid – restringe a varredura a um SSID.

bssid – restringe a varredura a um BSSID.

A varredura só faz sentido em uma interface STA.

status() → int¶

status(param: str) → Any

Consulta o status da conexão.

Sem argumento, retorna o status do enlace como um pequeno inteiro (codificação específica do driver – verdadeiro significa “associado”).

Com um argumento string:

"rssi" – no modo STA, retorna o RSSI atual em dBm.

"stations" – no modo AP, retorna uma lista das estações conectadas. O CYW43 retorna [(mac_bytes,), ...]; o NINA retorna [ip_string, ...].

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

Obtém ou define os parâmetros IPv4 da interface como uma 4-tupla de strings (ip, subnet, gateway, dns) no formato quad pontuado.

Nota

Prefira ipconfig() para código novo:

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: Obtém ou define os parâmetros IPv4 / IPv6 da interface. O driver CYW43 delega à implementação lwIP padrão e suporta o conjunto completo de chaves documentadas em AbstractNIC.ipconfig(). O driver NINA implementa um subconjunto menor por interface – dhcp4 e has_dhcp4 (somente leitura), além de addr4 e gw4 para obtenção / definição.

config(param: str) → Any¶

config(**kwargs: Any) → None

Obtém ou define parâmetros específicos da interface WiFi.

Com um único argumento posicional do tipo string, retorna o valor desse parâmetro. Com argumentos por palavra-chave, define um ou mais parâmetros de uma vez – alterações que afetam um AP em execução fazem o AP ser desativado e reativado automaticamente.

Exemplo:

# 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 – parâmetros consultáveis:

"antenna" – seletor de antena (int).

"channel" – canal atual.

"ssid" / "essid" – o SSID atual (string).

"security" – o modo de autenticação do AP (um de SEC_*).

"mac" – endereço MAC da interface (6 bytes).

"pm" – valor de gerenciamento de energia.

"txpower" – potência de transmissão em dBm.

"hostname" – hostname DHCP/mDNS. Obsoleto; use network.hostname() em vez disso.

Driver CYW43 – parâmetros definíveis:

antenna=<int> – seletor de antena.

channel=<int> – canal do AP.

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

key=<str> / password=<str> – chave pré-compartilhada do AP.

security=<int> – modo de autenticação do AP (um de SEC_*).

pm=<int> – modo de gerenciamento de energia (um de PM_NONE, PM_PERFORMANCE, PM_POWERSAVE).

monitor=<int> – habilita o modo monitor / all-multicast.

txpower=<int> – potência de transmissão em dBm.

trace=<int> – máscara de bits de rastreamento interno do driver.

hostname=<str> – hostname DHCP/mDNS. Obsoleto; use network.hostname() em vez disso.

Driver NINA – parâmetros consultáveis:

"ssid" – o SSID atual (string).

"security" – o modo de autenticação do AP.

"mac" / "bssid" – endereço MAC da interface (6 bytes).

"fw_version" – uma 3-tupla (major, minor, patch).

Driver NINA – parâmetros definíveis: a chamada é encaminhada a connect() e aceita os mesmos argumentos por palavra-chave (ssid, key, security, channel). Válido apenas na interface AP.

deinit() → None¶: Reinicia a alimentação do MCU WiFi e libera todos os recursos retidos pelo driver (buffers de firmware, netif lwIP, barramento SPI/SDIO). Após chamar isto, o objeto WLAN deve ser reconstruído antes de ser usado. Use isto em vez de active() (False) quando precisar de um reset completo (por exemplo, antes de regravar o firmware do rádio ou para recuperar de um estado travado do driver). Apenas CYW43.

send_ethernet(buf: bytes) → None¶: Injeta o quadro Ethernet bruto buf diretamente no caminho de transmissão do driver, contornando a pilha IP. Destinado a consumidores exclusivamente de camada 2 – bridging, protocolos EtherType personalizados e similares. O quadro deve incluir os MACs de destino/origem e o EtherType (sem FCS – o hardware o anexa). Apenas CYW43.

ioctl(cmd: int, buf: bytearray) → None¶: Emite um comando de controle específico do driver. cmd é o código numérico de ioctl definido pelo firmware do rádio subjacente e buf é um buffer mutável usado tanto para a carga útil do comando quanto para a resposta. O conjunto de valores cmd válidos é específico do driver e não é portável entre CYW43 e NINA. Usado principalmente por scripts de teste de baixo nível e código de bring-up de chip.

Constantes¶

IF_STA: int¶: Identificador da interface estação / cliente. Passe ao construtor para selecionar o modo STA.

IF_AP: int¶: Identificador da interface ponto de acesso. Passe ao construtor para selecionar o modo AP.

SEC_OPEN: int¶: Valor de segurança para uma rede não criptografada. Disponível em ambos os drivers.

SEC_WPA_WPA2: int¶: Valor de segurança para WPA / WPA2 com chave pré-compartilhada. O padrão quando uma chave é fornecida a connect(). Disponível em ambos os drivers.

SEC_WPA3: int¶: Valor de segurança para WPA3 (SAE) com chave pré-compartilhada. Apenas CYW43.

SEC_WPA2_WPA3: int¶: Valor de segurança para o modo de transição WPA2 / WPA3. Apenas CYW43.

SEC_WEP: int¶: Valor de segurança para WEP (Wired Equivalent Privacy). Fornecido para compatibilidade com pontos de acesso legados – o WEP é criptograficamente quebrado e não deve ser usado em novas implantações. Apenas NINA.

OPEN: int¶: Alias de compatibilidade retroativa para SEC_OPEN. Código novo deve usar SEC_OPEN. Apenas NINA.

WEP: int¶: Alias de compatibilidade retroativa para SEC_WEP. Código novo deve usar SEC_WEP. Apenas NINA.

WPA_PSK: int¶: Alias de compatibilidade retroativa para SEC_WPA_WPA2. Código novo deve usar SEC_WPA_WPA2. Apenas NINA.

PM_NONE: int¶: Passe a config(pm=...) para desabilitar o gerenciamento de energia WiFi. Apenas CYW43.

PM_PERFORMANCE: int¶: Passe a config(pm=...) para habilitar o gerenciamento de energia WiFi ajustado para desempenho. Apenas CYW43.

PM_POWERSAVE: int¶: Passe a config(pm=...) para habilitar o gerenciamento de energia WiFi ajustado para máxima duração da bateria. Apenas CYW43.