network — configuration réseau

Ce module fournit les pilotes réseau et la configuration du routage. Pour utiliser ce module, une variante/version de MicroPython dotée de capacités réseau doit être installée. Les pilotes réseau pour du matériel spécifique sont disponibles dans ce module et servent à configurer la ou les interfaces réseau matérielles. Les services réseau fournis par les interfaces configurées sont ensuite accessibles via le module socket.

Par exemple

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

Remplacez WLAN par WINC (ancien shield WiFi) ou LAN (Ethernet intégré) selon la caméra. Le schéma général construire -> activer -> connecter -> utiliser les sockets est le même dans les trois cas.

Interface commune des adaptateurs réseau

Cette section décrit une classe de base abstraite (implicite) pour toutes les classes d’interface réseau implémentées par les portages MicroPython pour les différents matériels. Cela signifie que MicroPython ne fournit pas réellement de classe AbstractNIC, mais que toute classe NIC concrète, telle que décrite dans les sections suivantes, implémente les méthodes décrites ici.

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

Instancie un objet d’interface réseau. Les paramètres dépendent de l’interface réseau. S’il existe plusieurs interfaces du même type, le premier paramètre doit être id.

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

Active ou désactive l’interface réseau.

Sans argument, renvoie l’état actuel – True lorsque l’interface est active, False sinon.

Passez True pour activer l’interface : mise sous tension / réinitialisation du contrôleur réseau sous-jacent, chargement du micrologiciel le cas échéant, et activation de la pile IP sur cette interface. Les appels ultérieurs qui dialoguent avec le réseau (connect(), scan(), ipconfig(), …) exigent que l’interface soit active.

Passez False pour désactiver l’interface : démontage de la pile IP et libération des ressources du pilote. Sur les interfaces sans fil, cela dissocie également de tout réseau actuellement rejoint.

Le comportement des autres méthodes appelées sur une interface inactive est indéfini.

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

Connecte l’interface à un réseau. Cette méthode est facultative et disponible uniquement pour les interfaces qui ne sont pas « toujours connectées ». Si aucun paramètre n’est fourni, se connecte au service par défaut (ou unique). Si un seul paramètre est fourni, il s’agit de l’identifiant principal d’un service auquel se connecter. Il peut être accompagné d’une clé (mot de passe) requise pour accéder à ce service. Il peut exister d’autres paramètres arbitraires en mot-clé uniquement, selon le type de support réseau et/ou l’appareil particulier. Les paramètres peuvent servir à : a) spécifier d’autres types d’identifiants de service ; b) fournir des paramètres de connexion supplémentaires. Selon les types de support, il existe différents ensembles de paramètres prédéfinis/recommandés, parmi lesquels :

  • WiFi : mot-clé bssid pour se connecter à un BSSID spécifique (adresse MAC)

disconnect() → None

Se déconnecte du réseau.

isconnected() → bool

Renvoie True si connecté au réseau, sinon renvoie False.

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

Recherche les services/connexions réseau disponibles. Renvoie une liste de tuples contenant les paramètres des services découverts. Selon les supports réseau, il existe différentes variantes de formats de tuples prédéfinis/recommandés, parmi lesquels :

  • WiFi : (ssid, bssid, channel, RSSI, security, hidden). Il peut y avoir d’autres champs, spécifiques à un appareil particulier.

La fonction peut accepter des arguments nommés supplémentaires pour filtrer les résultats du balayage (par exemple, rechercher un service particulier, sur un canal particulier, pour les services d’un ensemble particulier, etc.), et pour influer sur la durée du balayage et d’autres paramètres. Lorsque c’est possible, les noms de paramètres devraient correspondre à ceux de connect().

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

Interroge les informations d’état dynamiques de l’interface. Appelée sans argument, la valeur de retour décrit l’état de la liaison réseau. Sinon, param doit être une chaîne nommant le paramètre d’état particulier à récupérer.

Les types et les valeurs de retour dépendent du support/de la technologie réseau. Voici quelques-uns des paramètres qui peuvent être pris en charge :

  • WiFi STA : utilisez 'rssi' pour récupérer le RSSI du signal de l’AP

  • WiFi AP : utilisez 'stations' pour récupérer la liste de toutes les STA connectées à l’AP. La liste contient des tuples de la forme (MAC, RSSI).

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

Lit ou définit les paramètres de configuration IP propres à l’interface. Les paramètres pris en charge sont les suivants (la disponibilité d’un paramètre particulier dépend du portage et de l’interface réseau spécifique) :

  • dhcp4 (True/False) obtient une adresse IPv4, une passerelle et un serveur DNS via DHCP. Cette méthode n’est pas bloquante et n’attend pas l’obtention d’une adresse. Pour vérifier si une adresse a été obtenue, utilisez la propriété en lecture seule has_dhcp4.

  • gw4 Lit/définit la passerelle IPv4 par défaut.

  • dhcp6 (True/False) obtient un serveur DNS via DHCPv6 sans état. L’obtention d’adresses IP via DHCPv6 n’est pas encore implémentée.

  • autoconf6 (True/False) obtient une adresse IPv6 sans état via le préfixe réseau partagé dans les annonces de routeur. Pour vérifier si une adresse sans état a été obtenue, utilisez la propriété en lecture seule has_autoconf6.

  • addr4 (par ex. 192.168.0.4/24) obtient l’adresse IPv4 et le masque réseau actuels sous forme de tuple (ip, subnet), indépendamment de la manière dont cette adresse a été obtenue. Cette méthode peut servir à définir une adresse IPv4 statique, soit sous forme de tuple (ip, subnet), soit en notation CIDR.

  • addr6 (par ex. fe80::1234:5678) obtient une liste des adresses IPv6 actuelles sous forme de tuple (ip, state, preferred_lifetime, valid_lifetime). Cela inclut les adresses lien-local, slaac et statiques. preferred_lifetime et valid_lifetime représentent la durée de vie valide et préférée restante de chaque adresse IPv6, en secondes. state indique l’état actuel de l’adresse :

    • 0x08 - 0x0f indique que l’adresse est provisoire, en comptant le nombre de sondes envoyées.

    • 0x10 L’adresse est dépréciée (mais toujours valide)

    • 0x30 L’adresse est préférée (et valide)

    • 0x40 L’adresse est dupliquée et ne peut pas être utilisée.

    Cette méthode peut servir à définir une adresse IPv6 statique, en réglant ce paramètre sur l’adresse, comme fe80::1234:5678.

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

Note

Cette fonction est obsolète, utilisez ipconfig() à la place.

Lit/définit les paramètres réseau de niveau IP de l’interface : adresse IP, masque de sous-réseau, passerelle et serveur DNS. Appelée sans argument, cette méthode renvoie un 4-uplet contenant les informations ci-dessus. Pour définir ces valeurs, passez un 4-uplet contenant les informations requises. Par exemple

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

Lit ou définit les paramètres généraux de l’interface réseau. Ces méthodes permettent de travailler avec des paramètres supplémentaires au-delà de la configuration IP standard (traitée par ipconfig()). Cela inclut des paramètres propres au réseau et au matériel. Pour définir des paramètres, il faut utiliser la syntaxe des arguments nommés, et plusieurs paramètres peuvent être définis à la fois. Pour les interroger, un nom de paramètre doit être indiqué entre guillemets sous forme de chaîne, et un seul paramètre peut être interrogé à la fois

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

Implémentations de classes réseau spécifiques

Les classes concrètes suivantes implémentent l’interface AbstractNIC et offrent un moyen de contrôler des interfaces réseau de divers types.

Fonctions réseau

Voici les fonctions disponibles dans le module network.

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

Lit ou définit le code pays ISO 3166-1 Alpha-2 à deux lettres à utiliser pour la conformité radio.

Si le paramètre code est fourni, le pays sera réglé sur cette valeur. Si la fonction est appelée sans paramètres, elle renvoie le pays actuel.

Le code par défaut "XX" représente la région « mondiale ».

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

Lit ou définit le nom d’hôte qui identifiera cet appareil sur le réseau. Il sera utilisé par toutes les interfaces.

Ce nom d’hôte est utilisé pour :

  • L’envoi au serveur DHCP dans la requête du client. (Si DHCP est utilisé)

  • La diffusion via mDNS. (Si activée)

Si le paramètre name est fourni, le nom d’hôte sera réglé sur cette valeur. Si la fonction est appelée sans paramètres, elle renvoie le nom d’hôte actuel.

Un changement de nom d’hôte n’est généralement appliqué que lors de la connexion. Pour le DHCP, c’est parce que le nom d’hôte fait partie de la requête du client DHCP, et l’implémentation de mDNS dans la plupart des portages n’initialise le nom d’hôte qu’une seule fois lors de la connexion. Pour cette raison, vous devez définir le nom d’hôte avant d’activer/de connecter vos interfaces réseau.

La longueur du nom d’hôte est limitée à 32 caractères. Les portages MicroPython peuvent choisir de fixer une limite inférieure pour des raisons de mémoire. Si le nom fourni ne tient pas, une exception ValueError est levée.

Le nom d’hôte par défaut est généralement le nom de la carte.

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

Lit ou définit les paramètres globaux de configuration IP. Les paramètres pris en charge sont les suivants (la disponibilité d’un paramètre particulier dépend du portage et de l’interface réseau spécifique) :

  • dns Lit/définit le serveur DNS. Cette méthode peut prendre en charge à la fois les adresses IPv4 et IPv6.

  • prefer (4/6) Indique quel type d’adresse renvoyer si un nom de domaine possède à la fois des enregistrements A et AAAA. Notez que cela ne vide pas le cache DNS local, de sorte que les adresses obtenues précédemment peuvent ne pas changer.