network — Netzwerkkonfiguration

Dieses Modul stellt Netzwerktreiber und Routing-Konfiguration bereit. Um dieses Modul zu verwenden, muss eine MicroPython-Variante/-Build mit Netzwerkfähigkeiten installiert sein. Netzwerktreiber für spezifische Hardware sind innerhalb dieses Moduls verfügbar und werden zur Konfiguration von Hardware-Netzwerkschnittstellen verwendet. Die von den konfigurierten Schnittstellen bereitgestellten Netzwerkdienste stehen dann über das socket-Modul zur Verfügung.

Zum Beispiel:

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

Ersetzen Sie WLAN durch WINC (älteres WiFi-Shield) oder LAN (integriertes Ethernet), je nachdem, was für die Kamera passend ist. Das übergeordnete Muster aus Erzeugen -> Aktivieren -> Verbinden -> Sockets verwenden ist in allen drei Fällen gleich.

Gemeinsame Netzwerkadapter-Schnittstelle

Dieser Abschnitt beschreibt eine (implizite) abstrakte Basisklasse für alle Netzwerkschnittstellenklassen, die von MicroPython ports für unterschiedliche Hardware implementiert werden. Das bedeutet, dass MicroPython nicht tatsächlich eine AbstractNIC-Klasse bereitstellt, sondern dass jede konkrete NIC-Klasse, wie in den folgenden Abschnitten beschrieben, die hier beschriebenen Methoden implementiert.

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

Instanziiert ein Netzwerkschnittstellenobjekt. Die Parameter sind von der Netzwerkschnittstelle abhängig. Wenn mehr als eine Schnittstelle desselben Typs vorhanden ist, sollte der erste Parameter id sein.

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

Schaltet die Netzwerkschnittstelle ein oder aus.

Ohne Argument wird der aktuelle Zustand zurückgegeben – True, solange die Schnittstelle aktiv ist, andernfalls False.

Übergeben Sie True, um die Schnittstelle zu aktivieren: den zugrunde liegenden Netzwerkcontroller einschalten / zurücksetzen, gegebenenfalls Firmware laden und den IP-Stack auf dieser Schnittstelle hochfahren. Nachfolgende Aufrufe, die mit dem Netzwerk kommunizieren (connect(), scan(), ipconfig(), …), erfordern, dass die Schnittstelle aktiv ist.

Übergeben Sie False, um die Schnittstelle zu deaktivieren: den IP-Stack abbauen und Treiberressourcen freigeben. Bei drahtlosen Schnittstellen wird dadurch außerdem die Verbindung zu jedem aktuell verbundenen Netzwerk getrennt.

Das Verhalten beim Aufruf anderer Methoden auf einer inaktiven Schnittstelle ist undefiniert.

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

Verbindet die Schnittstelle mit einem Netzwerk. Diese Methode ist optional und nur für Schnittstellen verfügbar, die nicht „immer verbunden“ sind. Werden keine Parameter angegeben, wird eine Verbindung mit dem Standarddienst (oder dem einzigen Dienst) hergestellt. Wird ein einzelner Parameter angegeben, ist dies die primäre Kennung eines Dienstes, mit dem eine Verbindung hergestellt werden soll. Sie kann von einem Schlüssel (Passwort) begleitet werden, der für den Zugriff auf den genannten Dienst erforderlich ist. Es kann weitere beliebige nur-Schlüsselwort-Parameter geben, abhängig vom Typ des Netzwerkmediums und/oder vom konkreten Gerät. Parameter können verwendet werden, um: a) alternative Kennungstypen für Dienste anzugeben; b) zusätzliche Verbindungsparameter bereitzustellen. Für verschiedene Medientypen gibt es unterschiedliche Sätze vordefinierter/empfohlener Parameter, darunter:

  • WiFi: Schlüsselwort bssid, um sich mit einer bestimmten BSSID (MAC-Adresse) zu verbinden

disconnect() → None

Trennt die Verbindung zum Netzwerk.

isconnected() → bool

Gibt True zurück, wenn eine Verbindung zum Netzwerk besteht, andernfalls False.

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

Sucht nach den verfügbaren Netzwerkdiensten/-verbindungen. Gibt eine Liste von Tupeln mit den entdeckten Dienstparametern zurück. Für verschiedene Netzwerkmedien gibt es unterschiedliche Varianten vordefinierter/empfohlener Tupelformate, darunter:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Es können weitere Felder vorhanden sein, die für ein bestimmtes Gerät spezifisch sind.

Die Funktion kann zusätzliche Schlüsselwortargumente akzeptieren, um Scan-Ergebnisse zu filtern (z. B. nach einem bestimmten Dienst, auf einem bestimmten Kanal, nach Diensten einer bestimmten Menge usw. zu suchen) sowie um die Scan-Dauer und andere Parameter zu beeinflussen. Wo möglich, sollten die Parameternamen denen in connect() entsprechen.

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

Fragt dynamische Statusinformationen der Schnittstelle ab. Beim Aufruf ohne Argument beschreibt der Rückgabewert den Status der Netzwerkverbindung. Andernfalls sollte param ein String sein, der den abzurufenden Statusparameter benennt.

Die Rückgabetypen und -werte sind vom Netzwerkmedium/von der Netzwerktechnologie abhängig. Einige der möglicherweise unterstützten Parameter sind:

  • WiFi STA: Verwenden Sie 'rssi', um den RSSI des AP-Signals abzurufen

  • WiFi AP: Verwenden Sie 'stations', um eine Liste aller mit dem AP verbundenen STAs abzurufen. Die Liste enthält Tupel der Form (MAC, RSSI).

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

Liest oder setzt schnittstellenspezifische IP-Konfigurationsparameter. Die folgenden Parameter werden unterstützt (die Verfügbarkeit eines bestimmten Parameters hängt vom Port und der jeweiligen Netzwerkschnittstelle ab):

  • dhcp4 (True/False) bezieht eine IPv4-Adresse, ein Gateway und einen DNS-Server per DHCP. Diese Methode blockiert nicht und wartet nicht, bis eine Adresse bezogen wurde. Um zu prüfen, ob eine Adresse bezogen wurde, verwenden Sie die schreibgeschützte Eigenschaft has_dhcp4.

  • gw4 Liest/setzt das IPv4-Standard-Gateway.

  • dhcp6 (True/False) bezieht einen DNS-Server per zustandslosem DHCPv6. Das Beziehen von IP-Adressen per DHCPv6 ist derzeit nicht implementiert.

  • autoconf6 (True/False) bezieht eine zustandslose IPv6-Adresse über das in Router-Advertisements geteilte Netzwerkpräfix. Um zu prüfen, ob eine zustandslose Adresse bezogen wurde, verwenden Sie die schreibgeschützte Eigenschaft has_autoconf6.

  • addr4 (z. B. 192.168.0.4/24) ruft die aktuelle IPv4-Adresse und Netzwerkmaske als (ip, subnet)-Tupel ab, unabhängig davon, wie diese Adresse bezogen wurde. Diese Methode kann verwendet werden, um eine statische IPv4-Adresse entweder als (ip, subnet)-Tupel oder in CIDR-Notation zu setzen.

  • addr6 (z. B. fe80::1234:5678) ruft eine Liste der aktuellen IPv6-Adressen als (ip, state, preferred_lifetime, valid_lifetime)-Tupel ab. Diese umfasst Link-Local-, SLAAC- und statische Adressen. preferred_lifetime und valid_lifetime stellen die verbleibende gültige und bevorzugte Lebensdauer jeder IPv6-Adresse in Sekunden dar. state gibt den aktuellen Zustand der Adresse an:

    • 0x08 - 0x0f gibt an, dass die Adresse vorläufig ist, und zählt die Anzahl der gesendeten Probes.

    • 0x10 Die Adresse ist veraltet (aber noch gültig)

    • 0x30 Die Adresse ist bevorzugt (und gültig)

    • 0x40 Die Adresse ist dupliziert und kann nicht verwendet werden.

    Diese Methode kann verwendet werden, um eine statische IPv6-Adresse zu setzen, indem dieser Parameter auf die Adresse gesetzt wird, wie fe80::1234:5678.

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

Bemerkung

Diese Funktion ist veraltet, verwenden Sie stattdessen ipconfig().

Liest/setzt Netzwerkschnittstellenparameter auf IP-Ebene: IP-Adresse, Subnetzmaske, Gateway und DNS-Server. Beim Aufruf ohne Argumente gibt diese Methode ein 4-Tupel mit den oben genannten Informationen zurück. Um die oben genannten Werte zu setzen, übergeben Sie ein 4-Tupel mit den erforderlichen Informationen. Zum Beispiel:

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

Liest oder setzt allgemeine Netzwerkschnittstellenparameter. Diese Methoden ermöglichen die Arbeit mit zusätzlichen Parametern über die Standard-IP-Konfiguration hinaus (die von ipconfig() behandelt wird). Dazu gehören netzwerkspezifische und hardwarespezifische Parameter. Zum Setzen von Parametern sollte die Schlüsselwortargument-Syntax verwendet werden, und es können mehrere Parameter auf einmal gesetzt werden. Zum Abfragen sollte ein Parametername als String in Anführungszeichen angegeben werden, und es kann jeweils nur ein Parameter abgefragt werden:

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

Konkrete Netzwerkklassen-Implementierungen

Die folgenden konkreten Klassen implementieren die AbstractNIC-Schnittstelle und bieten eine Möglichkeit, Netzwerkschnittstellen verschiedener Art zu steuern.

Netzwerkfunktionen

Im Folgenden sind die im network-Modul verfügbaren Funktionen aufgeführt.

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

Liest oder setzt den zweibuchstabigen ISO-3166-1-Alpha-2-Ländercode, der zur Einhaltung von Funkvorschriften verwendet werden soll.

Wenn der Parameter code angegeben wird, wird das Land auf diesen Wert gesetzt. Wird die Funktion ohne Parameter aufgerufen, gibt sie das aktuelle Land zurück.

Der Standardcode "XX" steht für die „weltweite“ Region.

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

Liest oder setzt den Hostnamen, der dieses Gerät im Netzwerk identifiziert. Er wird von allen Schnittstellen verwendet.

Dieser Hostname wird verwendet für:

  • Senden an den DHCP-Server in der Client-Anfrage. (Bei Verwendung von DHCP)

  • Übertragung per mDNS. (Falls aktiviert)

Wenn der Parameter name angegeben wird, wird der Hostname auf diesen Wert gesetzt. Wird die Funktion ohne Parameter aufgerufen, gibt sie den aktuellen Hostnamen zurück.

Eine Änderung des Hostnamens wird in der Regel nur während der Verbindung angewendet. Bei DHCP liegt dies daran, dass der Hostname Teil der DHCP-Client-Anfrage ist, und die Implementierung von mDNS in den meisten Ports initialisiert den Hostnamen nur einmal während der Verbindung. Aus diesem Grund müssen Sie den Hostnamen setzen, bevor Sie Ihre Netzwerkschnittstellen aktivieren/verbinden.

Die Länge des Hostnamens ist auf 32 Zeichen begrenzt. MicroPython ports können aus Speichergründen eine niedrigere Grenze festlegen. Wenn der angegebene Name nicht passt, wird ein ValueError ausgelöst.

Der Standard-Hostname ist in der Regel der Name des Boards.

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

Liest oder setzt globale IP-Konfigurationsparameter. Die folgenden Parameter werden unterstützt (die Verfügbarkeit eines bestimmten Parameters hängt vom Port und der jeweiligen Netzwerkschnittstelle ab):

  • dns Liest/setzt den DNS-Server. Diese Methode kann sowohl IPv4- als auch IPv6-Adressen unterstützen.

  • prefer (4/6) Legt fest, welcher Adresstyp zurückgegeben werden soll, wenn ein Domänenname sowohl A- als auch AAAA-Einträge hat. Beachten Sie, dass dies den lokalen DNS-Cache nicht leert, sodass sich zuvor bezogene Adressen möglicherweise nicht ändern.