network — configurazione di rete

Questo modulo fornisce driver di rete e configurazione di routing. Per utilizzare questo modulo è necessario installare una variante/build di MicroPython con funzionalità di rete. I driver di rete per hardware specifico sono disponibili all’interno di questo modulo e vengono utilizzati per configurare le interfacce di rete hardware. I servizi di rete forniti dalle interfacce configurate sono quindi disponibili tramite il modulo socket.

Per esempio:

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

Sostituisci WLAN con WINC (shield WiFi legacy) o LAN (Ethernet integrata) a seconda della camera. Lo schema di alto livello costruisci -> attiva -> connetti -> usa i socket è lo stesso in tutti e tre i casi.

Interfaccia comune dell’adattatore di rete

Questa sezione descrive una classe base astratta (implicita) per tutte le classi di interfaccia di rete implementate dai port di MicroPython per i diversi hardware. Ciò significa che MicroPython non fornisce effettivamente una classe AbstractNIC, ma qualunque classe NIC concreta, come descritto nelle sezioni seguenti, implementa i metodi qui descritti.

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

Istanzia un oggetto interfaccia di rete. I parametri dipendono dall’interfaccia di rete. Se è presente più di un’interfaccia dello stesso tipo, il primo parametro dovrebbe essere id.

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

Attiva o disattiva l’interfaccia di rete.

Senza argomenti, restituisce lo stato corrente – True quando l’interfaccia è attiva, False altrimenti.

Passa True per attivare l’interfaccia: accendi / resetta il controller di rete sottostante, carica il firmware ove applicabile e attiva lo stack IP su questa interfaccia. Le chiamate successive che comunicano con la rete (connect(), scan(), ipconfig(), …) richiedono che l’interfaccia sia attiva.

Passa False per disattivare l’interfaccia: smonta lo stack IP e rilascia le risorse del driver. Sulle interfacce wireless questo provoca anche la disassociazione da qualunque rete attualmente unita.

Il comportamento delle altre chiamate di metodo su un’interfaccia inattiva è indefinito.

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

Connette l’interfaccia a una rete. Questo metodo è opzionale e disponibile solo per le interfacce che non sono «sempre connesse». Se non viene fornito alcun parametro, si connette al servizio predefinito (o all’unico disponibile). Se viene fornito un singolo parametro, esso è l’identificatore primario del servizio a cui connettersi. Può essere accompagnato da una chiave (password) necessaria per accedere a tale servizio. Possono esserci ulteriori parametri arbitrari solo-keyword, a seconda del tipo di mezzo di rete e/o del dispositivo particolare. I parametri possono essere usati per: a) specificare tipi di identificatore di servizio alternativi; b) fornire parametri di connessione aggiuntivi. Per i vari tipi di mezzo esistono diversi insiemi di parametri predefiniti/raccomandati, tra cui:

  • WiFi: keyword bssid per connettersi a uno specifico BSSID (indirizzo MAC)

disconnect() → None

Disconnette dalla rete.

isconnected() → bool

Restituisce True se connesso alla rete, altrimenti restituisce False.

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

Cerca i servizi/le connessioni di rete disponibili. Restituisce un elenco di tuple con i parametri dei servizi scoperti. Per i vari mezzi di rete esistono diverse varianti di formati di tupla predefiniti/raccomandati, tra cui:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Possono esserci ulteriori campi, specifici di un particolare dispositivo.

La funzione può accettare argomenti keyword aggiuntivi per filtrare i risultati della scansione (ad esempio, cercare un particolare servizio, su un particolare canale, per servizi di un particolare insieme, ecc.) e per influenzare la durata della scansione e altri parametri. Ove possibile, i nomi dei parametri dovrebbero corrispondere a quelli di connect().

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

Interroga le informazioni di stato dinamiche dell’interfaccia. Quando viene chiamata senza argomenti, il valore restituito descrive lo stato del collegamento di rete. Altrimenti param dovrebbe essere una stringa che indica il particolare parametro di stato da recuperare.

I tipi e i valori restituiti dipendono dal mezzo/tecnologia di rete. Alcuni dei parametri che possono essere supportati sono:

  • WiFi STA: usa 'rssi' per recuperare l’RSSI del segnale dell’AP

  • WiFi AP: usa 'stations' per recuperare un elenco di tutte le STA connesse all’AP. L’elenco contiene tuple della forma (MAC, RSSI).

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

Ottiene o imposta i parametri di configurazione IP specifici dell’interfaccia. I parametri supportati sono i seguenti (la disponibilità di un particolare parametro dipende dal port e dalla specifica interfaccia di rete):

  • dhcp4 (True/False) ottiene un indirizzo IPv4, un gateway e un server dns tramite DHCP. Questo metodo non si blocca in attesa che venga ottenuto un indirizzo. Per verificare se è stato ottenuto un indirizzo, usa la proprietà di sola lettura has_dhcp4.

  • gw4 Ottiene/imposta il gateway predefinito IPv4.

  • dhcp6 (True/False) ottiene un server DNS tramite DHCPv6 stateless. L’ottenimento di indirizzi IP tramite DHCPv6 non è attualmente implementato.

  • autoconf6 (True/False) ottiene un indirizzo IPv6 stateless tramite il prefisso di rete condiviso negli annunci del router. Per verificare se è stato ottenuto un indirizzo stateless, usa la proprietà di sola lettura has_autoconf6.

  • addr4 (ad esempio 192.168.0.4/24) ottiene l’indirizzo IPv4 corrente e la maschera di rete come tupla (ip, subnet), indipendentemente da come questo indirizzo è stato ottenuto. Questo metodo può essere usato per impostare un indirizzo IPv4 statico, sia come tupla (ip, subnet) sia in notazione CIDR.

  • addr6 (ad esempio fe80::1234:5678) ottiene un elenco degli indirizzi IPv6 correnti come tupla (ip, state, preferred_lifetime, valid_lifetime). Ciò include indirizzi link-local, slaac e statici. preferred_lifetime e valid_lifetime rappresentano il tempo di vita valido e preferito rimanente di ciascun indirizzo IPv6, in secondi. state indica lo stato corrente dell’indirizzo:

    • 0x08 - 0x0f indica che l’indirizzo è provvisorio (tentative), contando il numero di probe inviate.

    • 0x10 L’indirizzo è deprecato (ma ancora valido)

    • 0x30 L’indirizzo è preferito (e valido)

    • 0x40 L’indirizzo è duplicato e non può essere usato.

    Questo metodo può essere usato per impostare un indirizzo IPv6 statico, impostando questo parametro all’indirizzo, ad esempio fe80::1234:5678.

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

Nota

Questa funzione è deprecata, usa invece ipconfig().

Ottiene/imposta i parametri dell’interfaccia di rete a livello IP: indirizzo IP, maschera di sottorete, gateway e server DNS. Quando viene chiamato senza argomenti, questo metodo restituisce una tupla di 4 elementi con le informazioni sopra indicate. Per impostare i valori suddetti, passa una tupla di 4 elementi con le informazioni richieste. Per esempio:

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

Ottiene o imposta i parametri generali dell’interfaccia di rete. Questi metodi consentono di lavorare con parametri aggiuntivi oltre alla configurazione IP standard (gestita da ipconfig()). Tra questi rientrano parametri specifici della rete e dell’hardware. Per impostare i parametri si dovrebbe usare la sintassi con argomenti keyword, ed è possibile impostare più parametri contemporaneamente. Per le interrogazioni, il nome del parametro dovrebbe essere fornito tra virgolette come stringa, ed è possibile interrogare un solo parametro alla volta:

# 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'))

Implementazioni di classi di rete specifiche

Le seguenti classi concrete implementano l’interfaccia AbstractNIC e forniscono un modo per controllare interfacce di rete di vario tipo.

Funzioni di rete

Le seguenti sono funzioni disponibili nel modulo network.

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

Ottiene o imposta il codice paese ISO 3166-1 Alpha-2 di due lettere da usare per la conformità radio.

Se viene fornito il parametro code, il paese verrà impostato a questo valore. Se la funzione viene chiamata senza parametri, restituisce il paese corrente.

Il codice predefinito "XX" rappresenta la regione «mondiale».

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

Ottiene o imposta l’hostname che identificherà questo dispositivo sulla rete. Verrà usato da tutte le interfacce.

Questo hostname è usato per:

  • L’invio al server DHCP nella richiesta del client. (Se si usa DHCP)

  • La trasmissione tramite mDNS. (Se abilitata)

Se viene fornito il parametro name, l’hostname verrà impostato a questo valore. Se la funzione viene chiamata senza parametri, restituisce l’hostname corrente.

Una modifica dell’hostname viene tipicamente applicata solo durante la connessione. Per il DHCP ciò avviene perché l’hostname fa parte della richiesta del client DHCP, e l’implementazione di mDNS nella maggior parte dei port inizializza l’hostname una sola volta durante la connessione. Per questo motivo, devi impostare l’hostname prima di attivare/connettere le tue interfacce di rete.

La lunghezza dell’hostname è limitata a 32 caratteri. I port di MicroPython possono scegliere di impostare un limite inferiore per ragioni di memoria. Se il nome fornito non rientra, viene sollevato un ValueError.

L’hostname predefinito è tipicamente il nome della scheda.

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

Ottiene o imposta i parametri di configurazione IP globali. I parametri supportati sono i seguenti (la disponibilità di un particolare parametro dipende dal port e dalla specifica interfaccia di rete):

  • dns Ottiene/imposta il server DNS. Questo metodo può supportare sia indirizzi IPv4 sia IPv6.

  • prefer (4/6) Specifica quale tipo di indirizzo restituire, se un nome di dominio ha sia record A sia record AAAA. Nota che ciò non svuota la cache DNS locale, quindi eventuali indirizzi ottenuti in precedenza potrebbero non cambiare.