class WLAN – controlo das interfaces WiFi integradas¶

A classe WLAN controla os rádios WiFi incorporados nas câmaras OpenMV modernas. A mesma classe encapsula dois controladores subjacentes distintos, dependendo do MCU WiFi da placa:

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

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

As câmaras OpenMV com o shield WiFi legado WINC1500 (M4 / M7 / H7 / H7 Plus / Pure Thermal) utilizam WINC em alternativa.

Exemplo de utilização:

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 a interface a operar:

WLAN.IF_STA – modo estação / cliente. Liga a um ponto de acesso externo com connect(). Este é o modo predefinido.

WLAN.IF_AP – modo ponto de acesso. Configura o AP com config() e aceita ligações de clientes.

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

Métodos¶

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

Ativa ou desativa o rádio WiFi.

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

active(True) liga o MCU WiFi, carrega o seu firmware (o CYW43 obtém o blob de firmware da flash; o NINA valida a versão do firmware atualmente gravado) e ativa a netif lwIP para esta interface. Todos os outros métodos – connect(), scan(), ipconfig() e semelhantes – requerem que a interface esteja ativa.

active(False) desativa o rádio. Na interface STA, isto também desassocia do AP atual e liberta 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 indicado.

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

key – palavra-passe / chave pré-partilhada. Passe None para uma rede aberta.

security (apenas por palavra-chave) – uma das constantes SEC_*. -1 (o valor predefinido) seleciona automaticamente: SEC_OPEN quando key está vazio, SEC_WPA_WPA2 caso contrário.

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

channel (apenas por palavra-chave) – canal de rádio preferido. Por defeito é «deixar o controlador escolher».

disconnect() → None¶: Em 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 tem efeito quando não está atualmente associado.

isconnected() → bool¶

Em modo STA, devolve True quando associado a um ponto de acesso e um endereço IPv4 foi obtido via DHCP (ou atribuído estaticamente através de ipconfig()). Devolve False enquanto a ligação ainda está na fase de autenticação/associação/DHCP.

Em modo AP, devolve True quando pelo menos uma estação se associou.

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

Pesquisa pontos de acesso próximos e devolve uma lista de tuplos de 6 elementos:

[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 de palavra-chave são exclusivos do CYW43:

passive – se True, utiliza uma pesquisa passiva em vez da pesquisa ativa por probe-request predefinida.

ssid – restringe a pesquisa a um SSID.

bssid – restringe a pesquisa a um BSSID.

A pesquisa só é relevante numa interface STA.

status() → int¶

status(param: str) → Any

Consulta o estado da ligação.

Sem argumento, devolve o estado da ligação como um pequeno inteiro (codificação específica do controlador – um valor verdadeiro significa «associado»).

Com um argumento de string:

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

"stations" – em modo AP, devolve uma lista de estações ligadas. O CYW43 devolve [(mac_bytes,), ...]; o NINA devolve [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 um tuplo de 4 elementos de strings no formato decimal pontuado (ip, subnet, gateway, dns).

Nota

Prefira ipconfig() para novo código:

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 parâmetros de interface IPv4 / IPv6. O controlador CYW43 delega para a implementação padrão lwIP e suporta o conjunto completo de chaves documentado em AbstractNIC.ipconfig(). O controlador NINA implementa um subconjunto por interface mais reduzido – dhcp4 e has_dhcp4 (só de leitura), mais addr4 e gw4 para obter / definir.

config(param: str) → Any¶

config(**kwargs: Any) → None

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

Com um único argumento posicional de string, devolve o valor desse parâmetro. Com argumentos de palavra-chave, define um ou mais parâmetros de uma só vez – as alterações que afetam um AP em funcionamento fazem com que o AP seja reiniciado 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"))

Controlador CYW43 – parâmetros legíveis:

"antenna" – seletor de antena (int).

"channel" – canal atual.

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

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

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

"pm" – valor de gestão de energia.

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

"hostname" – nome de anfitrião DHCP/mDNS. Obsoleto; utilize network.hostname() em alternativa.

Controlador 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é-partilhada do AP.

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

pm=<int> – modo de gestão de energia (uma de PM_NONE, PM_PERFORMANCE, PM_POWERSAVE).

monitor=<int> – ativa o modo monitor / multicast-total.

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

trace=<int> – máscara de bits de rastreio interno do controlador.

hostname=<str> – nome de anfitrião DHCP/mDNS. Obsoleto; utilize network.hostname() em alternativa.

Controlador NINA – parâmetros legíveis:

"ssid" – o SSID atual (string).

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

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

"fw_version" – um tuplo de 3 elementos (major, minor, patch).

Controlador NINA – parâmetros definíveis: a chamada é encaminhada para connect() e aceita os mesmos argumentos de palavra-chave (ssid, key, security, channel). Apenas válido na interface AP.

deinit() → None¶: Reinicia o MCU WiFi e liberta todos os recursos que o controlador detém (buffers de firmware, netif lwIP, barramento SPI/SDIO). Após chamar este método, o objeto WLAN tem de ser reconstruído antes de ser utilizado. Utilize este método em vez de active() (False) quando precisar de um reinício completo (por exemplo, antes de regravar o firmware do rádio ou para recuperar de um estado de controlador bloqueado). Exclusivo do CYW43.

send_ethernet(buf: bytes) → None¶: Injeta o fotograma Ethernet em bruto buf diretamente no caminho de transmissão do controlador, contornando a pilha IP. Destinado a consumidores apenas de nível L2 – bridging, protocolos EtherType personalizados e semelhantes. O fotograma deve incluir MAC de destino/origem e EtherType (sem FCS – o hardware acrescenta-o). Exclusivo do CYW43.

ioctl(cmd: int, buf: bytearray) → None¶: Emite um comando de controlo específico do controlador. cmd é o código ioctl numérico definido pelo firmware do rádio subjacente e buf é um buffer mutável utilizado tanto para o payload do comando como para a resposta. O conjunto de valores cmd válidos é específico do controlador e não é portável entre CYW43 e NINA. Utilizado principalmente por scripts de teste de baixo nível e código de inicialização de chips.

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 encriptada. Disponível em ambos os controladores.

SEC_WPA_WPA2: int¶: Valor de segurança para WPA / WPA2 com chave pré-partilhada. O valor predefinido quando uma chave é fornecida a connect(). Disponível em ambos os controladores.

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

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

SEC_WEP: int¶: Valor de segurança para WEP (Wired Equivalent Privacy). Fornecido para compatibilidade com pontos de acesso legados – o WEP é criptograficamente comprometido e não deve ser utilizado em novos sistemas. Exclusivo do NINA.

OPEN: int¶: Alias de compatibilidade retroativa para SEC_OPEN. O novo código deve utilizar SEC_OPEN. Exclusivo do NINA.

WEP: int¶: Alias de compatibilidade retroativa para SEC_WEP. O novo código deve utilizar SEC_WEP. Exclusivo do NINA.

WPA_PSK: int¶: Alias de compatibilidade retroativa para SEC_WPA_WPA2. O novo código deve utilizar SEC_WPA_WPA2. Exclusivo do NINA.

PM_NONE: int¶: Passe a config(pm=...) para desativar a gestão de energia WiFi. Exclusivo do CYW43.

PM_PERFORMANCE: int¶: Passe a config(pm=...) para ativar a gestão de energia WiFi otimizada para desempenho. Exclusivo do CYW43.

PM_POWERSAVE: int¶: Passe a config(pm=...) para ativar a gestão de energia WiFi otimizada para máxima autonomia da bateria. Exclusivo do CYW43.