network — configuración de red

Este módulo proporciona controladores de red y configuración de enrutamiento. Para usar este módulo, debe estar instalada una variante/compilación de MicroPython con capacidades de red. Dentro de este módulo hay disponibles controladores de red para hardware específico que se usan para configurar la(s) interfaz(ces) de red por hardware. Los servicios de red proporcionados por las interfaces configuradas quedan luego disponibles para su uso a través del módulo socket.

Por ejemplo:

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

Reemplaza WLAN por WINC (shield WiFi heredado) o LAN (Ethernet integrado) según corresponda a la cámara. El patrón de alto nivel de construir -> activar -> conectar -> usar sockets es el mismo en los tres casos.

Interfaz común de adaptador de red

Esta sección describe una clase base abstracta (implícita) para todas las clases de interfaz de red implementadas por los puertos de MicroPython para diferentes hardware. Esto significa que MicroPython en realidad no proporciona la clase AbstractNIC, pero cualquier clase NIC real, como se describe en las secciones siguientes, implementa los métodos descritos aquí.

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

Instancia un objeto de interfaz de red. Los parámetros dependen de la interfaz de red. Si hay más de una interfaz del mismo tipo, el primer parámetro debe ser id.

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

Activa o desactiva la interfaz de red.

Sin argumentos, devuelve el estado actual – True mientras la interfaz está activa, False en caso contrario.

Pasa True para activar la interfaz: enciende / reinicia el controlador de red subyacente, carga el firmware cuando corresponda y levanta la pila IP en esta interfaz. Las llamadas posteriores que se comunican con la red (connect(), scan(), ipconfig(), …) requieren que la interfaz esté activa.

Pasa False para desactivar la interfaz: derriba la pila IP y libera los recursos del controlador. En las interfaces inalámbricas esto también desasocia de cualquier red a la que se esté unido actualmente.

El comportamiento al llamar a otros métodos en una interfaz inactiva es indefinido.

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

Conecta la interfaz a una red. Este método es opcional y está disponible solo para las interfaces que no están «siempre conectadas». Si no se dan parámetros, conecta al servicio predeterminado (o al único). Si se da un único parámetro, es el identificador principal del servicio al que conectarse. Puede ir acompañado de una clave (contraseña) necesaria para acceder a dicho servicio. Puede haber además parámetros arbitrarios solo por palabra clave, según el tipo de medio de red y/o el dispositivo concreto. Los parámetros pueden usarse para: a) especificar tipos alternativos de identificador de servicio; b) proporcionar parámetros de conexión adicionales. Para distintos tipos de medio existen diferentes conjuntos de parámetros predefinidos/recomendados, entre ellos:

  • WiFi: palabra clave bssid para conectarse a un BSSID específico (dirección MAC)

disconnect() → None

Desconecta de la red.

isconnected() → bool

Devuelve True si está conectado a la red; de lo contrario, devuelve False.

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

Busca los servicios/conexiones de red disponibles. Devuelve una lista de tuplas con los parámetros de los servicios descubiertos. Para distintos medios de red existen diferentes variantes de formatos de tupla predefinidos/recomendados, entre ellas:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Puede haber campos adicionales, específicos de un dispositivo concreto.

La función puede aceptar argumentos de palabra clave adicionales para filtrar los resultados del escaneo (p. ej., buscar un servicio concreto, en un canal concreto, servicios de un conjunto concreto, etc.) y para afectar la duración del escaneo y otros parámetros. Cuando sea posible, los nombres de los parámetros deben coincidir con los de connect().

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

Consulta información dinámica de estado de la interfaz. Cuando se llama sin argumentos, el valor devuelto describe el estado del enlace de red. De lo contrario, param debe ser una cadena que nombre el parámetro de estado concreto a recuperar.

Los tipos y valores devueltos dependen del medio/tecnología de red. Algunos de los parámetros que pueden admitirse son:

  • WiFi STA: usa 'rssi' para recuperar el RSSI de la señal del AP

  • WiFi AP: usa 'stations' para recuperar una lista de todas las STA conectadas al AP. La lista contiene tuplas de la forma (MAC, RSSI).

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

Obtiene o establece los parámetros de configuración IP específicos de la interfaz. Los parámetros admitidos son los siguientes (la disponibilidad de un parámetro concreto depende del puerto y de la interfaz de red específica):

  • dhcp4 (True/False) obtiene una dirección IPv4, una puerta de enlace y un servidor DNS mediante DHCP. Este método no se bloquea ni espera a que se obtenga una dirección. Para comprobar si se obtuvo una dirección, usa la propiedad de solo lectura has_dhcp4.

  • gw4 Obtiene/establece la puerta de enlace predeterminada IPv4.

  • dhcp6 (True/False) obtiene un servidor DNS mediante DHCPv6 sin estado. La obtención de direcciones IP mediante DHCPv6 no está implementada actualmente.

  • autoconf6 (True/False) obtiene una dirección IPv6 sin estado mediante el prefijo de red compartido en los anuncios del enrutador. Para comprobar si se obtuvo una dirección sin estado, usa la propiedad de solo lectura has_autoconf6.

  • addr4 (p. ej. 192.168.0.4/24) obtiene la dirección IPv4 y la máscara de red actuales como una tupla (ip, subnet), independientemente de cómo se obtuviera esta dirección. Este método puede usarse para establecer una dirección IPv4 estática, ya sea como una tupla (ip, subnet) o en notación CIDR.

  • addr6 (p. ej. fe80::1234:5678) obtiene una lista de las direcciones IPv6 actuales como una tupla (ip, state, preferred_lifetime, valid_lifetime). Esto incluye direcciones de enlace local, slaac y estáticas. preferred_lifetime y valid_lifetime representan el tiempo de vida válido y preferido restante de cada dirección IPv6, en segundos. state indica el estado actual de la dirección:

    • 0x08 - 0x0f indica que la dirección es tentativa, contando el número de sondas enviadas.

    • 0x10 La dirección está obsoleta (pero sigue siendo válida)

    • 0x30 La dirección es preferida (y válida)

    • 0x40 La dirección está duplicada y no se puede usar.

    Este método puede usarse para establecer una dirección IPv6 estática, estableciendo este parámetro a la dirección, como fe80::1234:5678.

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

Nota

Esta función está obsoleta, usa ipconfig() en su lugar.

Obtiene/establece los parámetros de la interfaz de red a nivel IP: dirección IP, máscara de subred, puerta de enlace y servidor DNS. Cuando se llama sin argumentos, este método devuelve una tupla de 4 elementos con la información anterior. Para establecer los valores anteriores, pasa una tupla de 4 elementos con la información requerida. Por ejemplo:

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

Obtiene o establece parámetros generales de la interfaz de red. Estos métodos permiten trabajar con parámetros adicionales más allá de la configuración IP estándar (gestionada por ipconfig()). Estos incluyen parámetros específicos de la red y específicos del hardware. Para establecer parámetros, debe usarse la sintaxis de argumentos de palabra clave, y se pueden establecer múltiples parámetros a la vez. Para consultar, un nombre de parámetro debe ir entrecomillado como cadena, y solo se puede consultar un parámetro a la 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'))

Implementaciones de clases de red específicas

Las siguientes clases concretas implementan la interfaz AbstractNIC y proporcionan una forma de controlar interfaces de red de diversos tipos.

Funciones de red

Las siguientes son funciones disponibles en el módulo network.

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

Obtiene o establece el código de país ISO 3166-1 Alpha-2 de dos letras que se usará para el cumplimiento normativo de radio.

Si se proporciona el parámetro code, el país se establecerá a este valor. Si la función se llama sin parámetros, devuelve el país actual.

El código predeterminado "XX" representa la región «mundial».

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

Obtiene o establece el nombre de host que identificará este dispositivo en la red. Lo usarán todas las interfaces.

Este nombre de host se usa para:

  • Enviarlo al servidor DHCP en la solicitud del cliente. (Si se usa DHCP)

  • Difundirlo mediante mDNS. (Si está habilitado)

Si se proporciona el parámetro name, el nombre de host se establecerá a este valor. Si la función se llama sin parámetros, devuelve el nombre de host actual.

Un cambio en el nombre de host normalmente solo se aplica durante la conexión. Para DHCP esto se debe a que el nombre de host forma parte de la solicitud del cliente DHCP, y la implementación de mDNS en la mayoría de los puertos solo inicializa el nombre de host una vez durante la conexión. Por esta razón, debes establecer el nombre de host antes de activar/conectar tus interfaces de red.

La longitud del nombre de host está limitada a 32 caracteres. Los puertos de MicroPython pueden optar por establecer un límite más bajo por motivos de memoria. Si el nombre dado no cabe, se lanza un ValueError.

El nombre de host predeterminado es normalmente el nombre de la placa.

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

Obtiene o establece parámetros globales de configuración IP. Los parámetros admitidos son los siguientes (la disponibilidad de un parámetro concreto depende del puerto y de la interfaz de red específica):

  • dns Obtiene/establece el servidor DNS. Este método puede admitir tanto direcciones IPv4 como IPv6.

  • prefer (4/6) Especifica qué tipo de dirección devolver si un nombre de dominio tiene tanto registros A como AAAA. Ten en cuenta que esto no borra la caché DNS local, por lo que cualquier dirección obtenida previamente podría no cambiar.