network — configuração de rede

Este módulo fornece controladores de rede e configuração de encaminhamento. Para utilizar este módulo, é necessário instalar uma variante/compilação do MicroPython com capacidades de rede. Os controladores de rede para hardware específico estão disponíveis neste módulo e são utilizados para configurar interface(s) de rede de hardware. Os serviços de rede fornecidos pelas interfaces configuradas ficam então disponíveis para utilização 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 integrada) conforme adequado para a câmara. O padrão de alto nível de construir -> ativar -> ligar -> usar sockets é o mesmo nos três casos.

Interface comum de adaptador de rede

Esta secção descreve uma classe base abstrata (implícita) para todas as classes de interface de rede implementadas pelos ports do MicroPython para hardware diferente. Isto significa que o MicroPython não fornece realmente a classe AbstractNIC, mas qualquer classe NIC concreta, conforme descrito nas secçõ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 existir mais do que uma interface do mesmo tipo, o primeiro parâmetro deve ser id.

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

Ativa ou desativa a interface de rede.

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

Passe True para ativar a interface: ligar / reiniciar o controlador de rede subjacente, carregar firmware quando aplicável, e ativar a pilha IP nesta interface. As chamadas subsequentes que comunicam com a rede (connect(), scan(), ipconfig(), …) requerem que a interface esteja ativa.

Passe False para desativar a interface: desligar a pilha IP e libertar os recursos do controlador. Nas interfaces sem fios, isto também desassocia de qualquer rede atualmente ligada.

O comportamento de chamar outros métodos numa interface inativa é indefinido.

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

Liga a interface a uma rede. Este método é opcional e está disponível apenas para interfaces que não estão «sempre ligadas». Se não forem dados parâmetros, liga ao serviço predefinido (ou único). Se for dado um único parâmetro, é o identificador principal do serviço ao qual se ligar. Pode ser acompanhado por uma chave (palavra-passe) necessária para aceder ao referido serviço. Podem existir outros parâmetros arbitrários apenas por palavra-chave, dependendo do tipo de suporte de rede e/ou dispositivo específico. Os parâmetros podem ser utilizados para: a) especificar tipos alternativos de identificador de serviço; b) fornecer parâmetros de ligação adicionais. Para vários tipos de suporte, existem diferentes conjuntos de parâmetros predefinidos/recomendados, entre eles:

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

disconnect() → None

Desliga da rede.

isconnected() → bool

Devolve True se estiver ligado à rede, caso contrário devolve False.

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

Pesquisa os serviços/ligações de rede disponíveis. Devolve uma lista de tuplos com os parâmetros dos serviços descobertos. Para vários tipos de suporte de rede, existem diferentes variantes de formatos de tuplo predefinidos/recomendados, entre eles:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Podem existir campos adicionais, específicos de um determinado dispositivo.

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

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

Consulta informações de estado dinâmico da interface. Quando chamado sem argumento, o valor de retorno descreve o estado da ligação de rede. Caso contrário, param deve ser uma string que indica o parâmetro de estado específico a obter.

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

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

  • WiFi AP: utilize 'stations' para obter uma lista de todos os STAs ligados ao AP. A lista contém tuplos na forma (MAC, RSSI).

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

Obtém ou define parâmetros de configuração IP 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 à espera de que um endereço seja obtido. Para verificar se um endereço foi obtido, utilize a propriedade só de leitura has_dhcp4.

  • gw4 Obtém/define o gateway IPv4 predefinido.

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

  • autoconf6 (True/False) obtém um endereço IPv6 sem estado através do prefixo de rede partilhado nos anúncios de router. Para verificar se um endereço sem estado foi obtido, utilize a propriedade só de 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 um tuplo (ip, subnet), independentemente de como este endereço foi obtido. Este método pode ser utilizado para definir um endereço IPv4 estático, quer como tuplo (ip, subnet) quer em notação CIDR.

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

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

    • 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 utilizado.

    Este método pode ser utilizado para definir um endereço IPv6 estático, definindo este parâmetro para 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, utilize ipconfig() em alternativa.

Obtém/define parâmetros de rede ao nível IP: endereço IP, máscara de sub-rede, gateway e servidor DNS. Quando chamado sem argumentos, este método devolve um tuplo de 4 elementos com as informações acima. Para definir os valores acima, passe um tuplo de 4 elementos 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 para além da configuração IP padrão (conforme tratado por ipconfig()). Incluem parâmetros específicos da rede e específicos do hardware. Para definir parâmetros, deve ser utilizada a sintaxe de argumento por palavra-chave, e vários parâmetros podem ser definidos de uma só vez. Para consultar, o nome do parâmetro deve ser citado como string, e apenas um parâmetro pode ser consultado de cada 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 forma de controlar interfaces de rede de vários tipos.

Funções de rede

As seguintes funções estão 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 utilizar para conformidade com regulamentação de rádio.

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

O código predefinido "XX" representa a região «mundial».

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

Obtém ou define o nome de anfitrião que identificará este dispositivo na rede. Será utilizado por todas as interfaces.

Este nome de anfitrião é utilizado para:

  • Envio ao servidor DHCP no pedido do cliente. (Se utilizar DHCP)

  • Difusão via mDNS. (Se ativado)

Se o parâmetro name for fornecido, o nome de anfitrião será definido para este valor. Se a função for chamada sem parâmetros, devolve o nome de anfitrião atual.

Uma alteração no nome de anfitrião é tipicamente aplicada apenas durante a ligação. Para o DHCP, isto deve-se ao facto de o nome de anfitrião fazer parte do pedido do cliente DHCP, e a implementação do mDNS na maioria dos ports apenas inicializa o nome de anfitrião uma vez durante a ligação. Por esta razão, deve definir o nome de anfitrião antes de ativar/ligar as suas interfaces de rede.

O comprimento do nome de anfitrião está limitado a 32 caracteres. Os ports do MicroPython podem optar por definir um limite inferior por razões de memória. Se o nome fornecido não couber, é lançado um ValueError.

O nome de anfitrião predefinido é tipicamente o nome da placa.

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

Obtém ou define parâmetros de configuração IP globais. 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 endereços IPv4 e IPv6.

  • prefer (4/6) Especifica o tipo de endereço a devolver, se um nome de domínio tiver registos A e AAAA. Note que isto não limpa a cache DNS local, pelo que quaisquer endereços obtidos anteriormente podem não ser alterados.