network — configuração de rede

Este módulo fornece drivers de rede e configuração de roteamento. Para usar este módulo, é preciso ter instalado um build/variante do MicroPython com capacidades de rede. Os drivers de rede para hardware específico estão disponíveis dentro deste módulo e são usados para configurar a(s) interface(s) de rede do hardware. Os serviços de rede fornecidos pelas interfaces configuradas ficam então disponíveis para uso através do módulo socket.

Por exemplo:

import network
import socket
import time

nic = network.WLAN(network.WLAN.IF_STA)
nic.active(True)
nic.connect("your-ssid", "your-key")

print("Waiting for connection...")
while not nic.isconnected():
    time.sleep(1)
print(nic.ipconfig("addr4"))

# Open a TCP socket as usual.
addr = socket.getaddrinfo("micropython.org", 80)[0][-1]
s = socket.socket()
s.connect(addr)
s.send(b"GET / HTTP/1.1\r\nHost: micropython.org\r\n\r\n")
data = s.recv(1000)
s.close()

Substitua WLAN por WINC (shield WiFi legado) ou LAN (Ethernet integrado) conforme apropriado para a câmera. O padrão de alto nível construir -> ativar -> conectar -> usar sockets é o mesmo nos três casos.

Interface comum de adaptador de rede

Esta seção descreve uma classe base abstrata (implícita) para todas as classes de interface de rede implementadas pelos ports do MicroPython para diferentes hardwares. Isso significa que o MicroPython não fornece de fato uma classe AbstractNIC, mas qualquer classe NIC real, como descrito nas seções seguintes, implementa os métodos aqui descritos.

class network.AbstractNIC(id: int | None = None, *args: Any, **kwargs: Any) → None

Instancia um objeto de interface de rede. Os parâmetros dependem da interface de rede. Se houver mais de uma interface do mesmo tipo, o primeiro parâmetro deve ser id.

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

Liga ou desliga a interface de rede.

Sem argumento, retorna o estado atual – True enquanto a interface está ativa, False caso contrário.

Passe True para ativar a interface: liga / reinicia o controlador de rede subjacente, carrega o firmware quando aplicável e ativa a pilha IP nesta interface. Chamadas subsequentes que se comunicam com a rede (connect(), scan(), ipconfig(), …) exigem que a interface esteja ativa.

Passe False para desativar a interface: desativa a pilha IP e libera os recursos do driver. Em interfaces sem fio isso também desassocia de qualquer rede atualmente conectada.

O comportamento ao chamar outros métodos em uma interface inativa é indefinido.

connect(service_id: str | None = None, key: str | None = None, *, bssid: bytes | None = None, **kwargs: Any) → None

Conecta a interface a uma rede. Este método é opcional e disponível apenas para interfaces que não estão “sempre conectadas”. Se nenhum parâmetro for fornecido, conecta-se ao serviço padrão (ou ao único). Se um único parâmetro for fornecido, ele é o identificador primário de um serviço ao qual se conectar. Pode vir acompanhado de uma chave (senha) necessária para acessar tal serviço. Pode haver outros parâmetros arbitrários somente por palavra-chave, dependendo do tipo de meio de rede e/ou do dispositivo específico. Os parâmetros podem ser usados para: a) especificar tipos alternativos de identificador de serviço; b) fornecer parâmetros adicionais de conexão. Para os vários tipos de meio, há diferentes conjuntos de parâmetros predefinidos/recomendados, entre eles:

  • WiFi: palavra-chave bssid para conectar a um BSSID específico (endereço MAC)

disconnect() → None

Desconecta da rede.

isconnected() → bool

Retorna True se conectado à rede, caso contrário retorna False.

scan(**kwargs: Any) → List[Tuple]

Procura os serviços/conexões de rede disponíveis. Retorna uma lista de tuplas com os parâmetros dos serviços descobertos. Para os vários meios de rede, há diferentes variantes de formatos de tupla predefinidos/recomendados, entre eles:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Pode haver campos adicionais, específicos de um dispositivo em particular.

A função pode aceitar argumentos adicionais por palavra-chave para filtrar os resultados da varredura (por exemplo, procurar por um serviço específico, em um canal específico, por serviços de um conjunto específico, etc.) e para influenciar a duração da varredura e outros parâmetros. Sempre que possível, os nomes dos parâmetros devem corresponder aos de connect().

status(param: str | None = None) → Any

Consulta informações dinâmicas de status da interface. Quando chamada sem argumento, o valor de retorno descreve o status do enlace de rede. Caso contrário, param deve ser uma string que nomeie o parâmetro de status específico a ser obtido.

Os tipos e valores de retorno dependem do meio/tecnologia de rede. Alguns dos parâmetros que podem ser suportados são:

  • WiFi STA: use 'rssi' para obter o RSSI do sinal do AP

  • WiFi AP: use 'stations' para obter uma lista de todas as STAs conectadas ao AP. A lista contém tuplas no formato (MAC, RSSI).

ipconfig(param: str) → Any
ipconfig(**kwargs: Any) → None

Obtém ou define parâmetros de configuração IP específicos da interface. Os parâmetros suportados são os seguintes (a disponibilidade de um parâmetro específico depende do port e da interface de rede específica):

  • dhcp4 (True/False) obtém um endereço IPv4, gateway e servidor dns via DHCP. Este método não bloqueia nem aguarda a obtenção de um endereço. Para verificar se um endereço foi obtido, use a propriedade somente leitura has_dhcp4.

  • gw4 Obtém/define o gateway padrão IPv4.

  • dhcp6 (True/False) obtém um servidor DNS via DHCPv6 sem estado. A obtenção de endereços IP via DHCPv6 não está implementada atualmente.

  • autoconf6 (True/False) obtém um endereço IPv6 sem estado através do prefixo de rede compartilhado nos anúncios de roteador. Para verificar se um endereço sem estado foi obtido, use a propriedade somente leitura has_autoconf6.

  • addr4 (por exemplo, 192.168.0.4/24) obtém o endereço IPv4 atual e a máscara de rede como uma tupla (ip, subnet), independentemente de como esse endereço foi obtido. Este método pode ser usado para definir um endereço IPv4 estático, seja como uma tupla (ip, subnet) ou em notação CIDR.

  • addr6 (por exemplo, fe80::1234:5678) obtém uma lista dos endereços IPv6 atuais como uma tupla (ip, state, preferred_lifetime, valid_lifetime). Isso inclui endereços link-local, slaac e estáticos. preferred_lifetime e valid_lifetime representam, em segundos, o tempo de vida válido e preferido restante de cada endereço IPv6. state indica o estado atual do endereço:

    • 0x08 - 0x0f indica que o endereço é tentativo, contando o número de probes enviados.

    • 0x10 O endereço está obsoleto (mas ainda válido)

    • 0x30 O endereço é preferido (e válido)

    • 0x40 O endereço está duplicado e não pode ser usado.

    Este método pode ser usado para definir um endereço IPv6 estático, atribuindo a este parâmetro o endereço, como fe80::1234:5678.

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

Nota

Esta função está obsoleta, use ipconfig() em vez disso.

Obtém/define parâmetros de rede de nível IP da interface: endereço IP, máscara de sub-rede, gateway e servidor DNS. Quando chamado sem argumentos, este método retorna uma 4-tupla com as informações acima. Para definir os valores acima, passe uma 4-tupla com as informações necessárias. Por exemplo:

nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
config(param: str) → Any
config(**kwargs: Any) → None

Obtém ou define parâmetros gerais da interface de rede. Estes métodos permitem trabalhar com parâmetros adicionais além da configuração IP padrão (tratada por ipconfig()). Isso inclui parâmetros específicos da rede e do hardware. Para definir parâmetros, deve-se usar a sintaxe de argumentos por palavra-chave, e múltiplos parâmetros podem ser definidos de uma vez. Para consultar, o nome de um parâmetro deve ser passado entre aspas como string, e apenas um parâmetro pode ser consultado por vez:

# Set WiFi access point name (formally known as SSID) and WiFi channel
ap.config(ssid='My AP', channel=11)
# Query params one by one
print(ap.config('ssid'))
print(ap.config('channel'))

Implementações de classes de rede específicas

As seguintes classes concretas implementam a interface AbstractNIC e fornecem uma maneira de controlar interfaces de rede de vários tipos.

Funções de rede

As seguintes são funções disponíveis no módulo network.

network.country(code: str | None = None) → str | None

Obtém ou define o código de país ISO 3166-1 Alpha-2 de duas letras a ser usado para conformidade de rádio.

Se o parâmetro code for fornecido, o país será definido com este valor. Se a função for chamada sem parâmetros, ela retorna o país atual.

O código padrão "XX" representa a região “mundial”.

network.hostname(name: str | None = None) → str | None

Obtém ou define o hostname que identificará este dispositivo na rede. Ele será usado por todas as interfaces.

Este hostname é usado para:

  • Envio ao servidor DHCP na requisição do cliente. (Se usar DHCP)

  • Difusão via mDNS. (Se habilitado)

Se o parâmetro name for fornecido, o hostname será definido com este valor. Se a função for chamada sem parâmetros, ela retorna o hostname atual.

Uma mudança no hostname normalmente só é aplicada durante a conexão. Para o DHCP isso ocorre porque o hostname faz parte da requisição do cliente DHCP, e a implementação do mDNS na maioria dos ports só inicializa o hostname uma vez durante a conexão. Por esse motivo, você deve definir o hostname antes de ativar/conectar suas interfaces de rede.

O comprimento do hostname é limitado a 32 caracteres. Os ports do MicroPython podem optar por definir um limite menor por razões de memória. Se o nome fornecido não couber, um ValueError é levantado.

O hostname padrão é normalmente o nome da placa.

network.ipconfig(param: str) → Any
network.ipconfig(**kwargs: Any) → None

Obtém ou define parâmetros globais de configuração IP. Os parâmetros suportados são os seguintes (a disponibilidade de um parâmetro específico depende do port e da interface de rede específica):

  • dns Obtém/define o servidor DNS. Este método pode suportar tanto endereços IPv4 quanto IPv6.

  • prefer (4/6) Especifica qual tipo de endereço retornar, caso um nome de domínio tenha tanto registros A quanto AAAA. Observe que isso não limpa o cache DNS local, de modo que quaisquer endereços previamente obtidos podem não mudar.