network — nätverkskonfiguration

Denna modul tillhandahåller nätverksdrivrutiner och routingkonfiguration. För att använda denna modul måste en MicroPython-variant/-build med nätverksfunktioner vara installerad. Nätverksdrivrutiner för specifik hårdvara finns tillgängliga i denna modul och används för att konfigurera hårdvarans nätverksgränssnitt. Nätverkstjänster som tillhandahålls av konfigurerade gränssnitt blir sedan tillgängliga för användning via modulen socket.

Till exempel:

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

Ersätt WLAN med WINC (äldre WiFi-sköld) eller LAN (inbyggt Ethernet) beroende på vad som är lämpligt för kameran. Det övergripande mönstret konstruera -> aktivera -> ansluta -> använda sockets är detsamma i alla tre fallen.

Gemensamt gränssnitt för nätverksadaptrar

Detta avsnitt beskriver en (underförstådd) abstrakt basklass för alla nätverksgränssnittsklasser som implementeras av MicroPython ports för olika hårdvara. Detta innebär att MicroPython inte faktiskt tillhandahåller någon AbstractNIC-klass, men att varje faktisk NIC-klass, så som beskrivs i de följande avsnitten, implementerar metoder så som beskrivs här.

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

Instansiera ett nätverksgränssnittsobjekt. Parametrarna är beroende av nätverksgränssnittet. Om det finns fler än ett gränssnitt av samma typ bör den första parametern vara id.

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

Starta upp eller stäng av nätverksgränssnittet.

Utan argument returneras det aktuella tillståndet – True medan gränssnittet är aktivt, False annars.

Skicka True för att aktivera gränssnittet: slå på/återställ den underliggande nätverksstyrenheten, läs in fast programvara där det är tillämpligt och starta upp IP-stacken på detta gränssnitt. Efterföljande anrop som kommunicerar med nätverket (connect(), scan(), ipconfig(), …) kräver att gränssnittet är aktivt.

Skicka False för att inaktivera gränssnittet: riv ned IP-stacken och frigör drivrutinsresurser. På trådlösa gränssnitt kopplas detta även bort från eventuellt anslutet nätverk.

Beteendet vid anrop av andra metoder på ett inaktivt gränssnitt är odefinierat.

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

Anslut gränssnittet till ett nätverk. Denna metod är valfri och tillgänglig endast för gränssnitt som inte är ”alltid anslutna”. Om inga parametrar anges, anslut till standardtjänsten (eller den enda tjänsten). Om en enda parameter anges är det den primära identifieraren för en tjänst att ansluta till. Den kan åtföljas av en nyckel (lösenord) som krävs för att komma åt nämnda tjänst. Det kan finnas ytterligare godtyckliga parametrar som endast anges med nyckelord, beroende på typ av nätverksmedium och/eller specifik enhet. Parametrar kan användas för att: a) ange alternativa typer av tjänsteidentifierare; b) tillhandahålla ytterligare anslutningsparametrar. För olika medietyper finns det olika uppsättningar av fördefinierade/rekommenderade parametrar, bland dem:

  • WiFi: nyckelordet bssid för att ansluta till ett specifikt BSSID (MAC-adress)

disconnect() → None

Koppla bort från nätverket.

isconnected() → bool

Returnerar True om ansluten till nätverket, annars returneras False.

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

Sök efter tillgängliga nätverkstjänster/-anslutningar. Returnerar en lista med tupler innehållande upptäckta tjänsteparametrar. För olika nätverksmedier finns det olika varianter av fördefinierade/rekommenderade tupelformat, bland dem:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Det kan finnas ytterligare fält, specifika för en viss enhet.

Funktionen kan acceptera ytterligare nyckelordsargument för att filtrera sökresultaten (t.ex. söka efter en viss tjänst, på en viss kanal, efter tjänster av en viss uppsättning osv.) och för att påverka sökningens varaktighet och andra parametrar. Där det är möjligt bör parameternamnen matcha dem i connect().

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

Fråga efter dynamisk statusinformation för gränssnittet. Vid anrop utan argument beskriver returvärdet nätverkets länkstatus. Annars bör param vara en sträng som namnger den specifika statusparameter som ska hämtas.

Returtyperna och -värdena är beroende av nätverksmediet/-tekniken. Några av de parametrar som kan stödjas är:

  • WiFi STA: använd 'rssi' för att hämta RSSI:n för åtkomstpunktens signal

  • WiFi AP: använd 'stations' för att hämta en lista över alla STA:er som är anslutna till åtkomstpunkten. Listan innehåller tupler på formen (MAC, RSSI).

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

Hämta eller ange gränssnittsspecifika parametrar för IP-konfiguration. Parametrar som stöds är följande (tillgängligheten av en viss parameter beror på porten och det specifika nätverksgränssnittet):

  • dhcp4 (True/False) erhåll en IPv4-adress, gateway och dns-server via DHCP. Denna metod blockerar inte och väntar inte på att en adress ska erhållas. För att kontrollera om en adress erhölls, använd den skrivskyddade egenskapen has_dhcp4.

  • gw4 Hämta/ange standardgateway för IPv4.

  • dhcp6 (True/False) erhåll en DNS-server via tillståndslös DHCPv6. Att erhålla IP-adresser via DHCPv6 är för närvarande inte implementerat.

  • autoconf6 (True/False) erhåll en tillståndslös IPv6-adress via nätverksprefixet som delas i router-annonseringar. För att kontrollera om en tillståndslös adress erhölls, använd den skrivskyddade egenskapen has_autoconf6.

  • addr4 (t.ex. 192.168.0.4/24) erhåll den aktuella IPv4-adressen och nätverksmasken som en (ip, subnet)-tupel, oavsett hur denna adress erhölls. Denna metod kan användas för att ange en statisk IPv4-adress antingen som en (ip, subnet)-tupel eller i CIDR-notation.

  • addr6 (t.ex. fe80::1234:5678) erhåll en lista över aktuella IPv6-adresser som en (ip, state, preferred_lifetime, valid_lifetime)-tupel. Detta inkluderar länklokala, slaac- och statiska adresser. preferred_lifetime och valid_lifetime representerar den återstående giltiga och föredragna livslängden för varje IPv6-adress, i sekunder. state anger adressens aktuella tillstånd:

    • 0x08 - 0x0f anger att adressen är preliminär, och räknar antalet skickade prober.

    • 0x10 Adressen är föråldrad (men fortfarande giltig)

    • 0x30 Adressen är föredragen (och giltig)

    • 0x40 Adressen är duplicerad och kan inte användas.

    Denna metod kan användas för att ange en statisk IPv6-adress, genom att sätta denna parameter till adressen, t.ex. fe80::1234:5678.

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

Anteckning

Denna funktion är föråldrad, använd ipconfig() istället.

Hämta/ange nätverksgränssnittsparametrar på IP-nivå: IP-adress, nätmask, gateway och DNS-server. Vid anrop utan argument returnerar denna metod en 4-tupel med ovanstående information. För att ange ovanstående värden, skicka en 4-tupel med den begärda informationen. Till exempel:

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

Hämta eller ange allmänna nätverksgränssnittsparametrar. Dessa metoder gör det möjligt att arbeta med ytterligare parametrar utöver standard-IP-konfiguration (som hanteras av ipconfig()). Dessa inkluderar nätverksspecifika och hårdvaruspecifika parametrar. För att ange parametrar bör syntaxen med nyckelordsargument användas, och flera parametrar kan anges på en gång. För att fråga bör ett parameternamn anges som en sträng inom citationstecken, och endast en parameter kan frågas åt gången:

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

Implementationer av specifika nätverksklasser

Följande konkreta klasser implementerar AbstractNIC-gränssnittet och tillhandahåller ett sätt att styra olika typer av nätverksgränssnitt.

Nätverksfunktioner

Följande är funktioner tillgängliga i network-modulen.

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

Hämta eller ange den tvåställiga landskoden enligt ISO 3166-1 Alpha-2 som ska användas för radioefterlevnad.

Om parametern code anges sätts landet till detta värde. Om funktionen anropas utan parametrar returnerar den det aktuella landet.

Standardkoden "XX" representerar regionen ”världsomspännande”.

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

Hämta eller ange värdnamnet som ska identifiera denna enhet på nätverket. Det kommer att användas av alla gränssnitt.

Detta värdnamn används för:

  • Att skickas till DHCP-servern i klientförfrågan. (Om DHCP används)

  • Att sändas ut via mDNS. (Om aktiverat)

Om parametern name anges sätts värdnamnet till detta värde. Om funktionen anropas utan parametrar returnerar den det aktuella värdnamnet.

En ändring av värdnamn tillämpas vanligtvis endast under anslutning. För DHCP beror detta på att värdnamnet är en del av DHCP-klientförfrågan, och implementationen av mDNS i de flesta portar initierar värdnamnet endast en gång under anslutningen. Av denna anledning måste du ange värdnamnet innan du aktiverar/ansluter dina nätverksgränssnitt.

Värdnamnets längd är begränsad till 32 tecken. MicroPython ports kan välja att sätta en lägre gräns av minnesskäl. Om det angivna namnet inte ryms genereras ett ValueError.

Standardvärdnamnet är vanligtvis kortets namn.

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

Hämta eller ange globala parametrar för IP-konfiguration. Parametrar som stöds är följande (tillgängligheten av en viss parameter beror på porten och det specifika nätverksgränssnittet):

  • dns Hämta/ange DNS-server. Denna metod kan stödja både IPv4- och IPv6-adresser.

  • prefer (4/6) Ange vilken adresstyp som ska returneras, om ett domännamn har både A- och AAAA-poster. Observera att detta inte tömmer den lokala DNS-cachen, så att eventuella tidigare erhållna adresser kanske inte ändras.