network — konfigurace sítě

Tento modul poskytuje síťové ovladače a konfiguraci směrování. Pro použití tohoto modulu musí být nainstalována varianta/sestavení MicroPythonu se síťovými schopnostmi. Síťové ovladače pro konkrétní hardware jsou dostupné v rámci tohoto modulu a slouží ke konfiguraci hardwarového síťového rozhraní (rozhraní). Síťové služby poskytované nakonfigurovanými rozhraními jsou poté dostupné k použití prostřednictvím modulu socket.

Například:

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

Nahraďte WLAN třídou WINC (starší WiFi shield) nebo LAN (vestavěný Ethernet) podle toho, co odpovídá dané kameře. Vysokoúrovňový vzor vytvoření -> aktivace -> připojení -> použití socketů je ve všech třech případech stejný.

Společné rozhraní síťového adaptéru

Tato část popisuje (implicitní) abstraktní základní třídu pro všechny třídy síťových rozhraní implementované porty MicroPythonu pro různý hardware. To znamená, že MicroPython ve skutečnosti neposkytuje třídu AbstractNIC, ale každá skutečná třída NIC, jak je popsáno v následujících částech, implementuje metody popsané zde.

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

Vytvoří instanci objektu síťového rozhraní. Parametry závisí na síťovém rozhraní. Pokud existuje více než jedno rozhraní téhož typu, prvním parametrem by mělo být id.

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

Zapne nebo vypne síťové rozhraní.

Bez argumentu vrací aktuální stav – True, pokud je rozhraní aktivní, jinak False.

Předáním True rozhraní aktivujete: zapne se / resetuje základní síťový řadič, načte se firmware, kde je to relevantní, a uvede se do provozu IP zásobník na tomto rozhraní. Následná volání, která komunikují se sítí (connect(), scan(), ipconfig(), …), vyžadují, aby bylo rozhraní aktivní.

Předáním False rozhraní deaktivujete: zruší se IP zásobník a uvolní se prostředky ovladače. Na bezdrátových rozhraních tím rovněž dojde k odpojení od aktuálně připojené sítě.

Chování při volání jiných metod na neaktivním rozhraní není definováno.

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

Připojí rozhraní k síti. Tato metoda je volitelná a dostupná pouze u rozhraní, která nejsou „vždy připojená“. Pokud nejsou zadány žádné parametry, připojí se k výchozí (nebo jediné) službě. Je-li zadán jediný parametr, jde o primární identifikátor služby, ke které se připojit. Může být doprovázen klíčem (heslem) vyžadovaným pro přístup k dané službě. Mohou následovat další libovolné parametry zadávané pouze klíčovým slovem, v závislosti na typu síťového média a/nebo konkrétním zařízení. Parametry lze použít k: a) určení alternativních typů identifikátorů služeb; b) poskytnutí dalších parametrů připojení. Pro různé typy médií existují různé sady předdefinovaných/doporučených parametrů, mezi nimi:

  • WiFi: klíčové slovo bssid pro připojení ke konkrétnímu BSSID (MAC adrese)

disconnect() → None

Odpojí od sítě.

isconnected() → bool

Vrací True, je-li připojeno k síti, jinak vrací False.

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

Vyhledá dostupné síťové služby/připojení. Vrací seznam n-tic s objevenými parametry služeb. Pro různá síťová média existují různé varianty předdefinovaných/doporučených formátů n-tic, mezi nimi:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Mohou existovat další pole specifická pro konkrétní zařízení.

Funkce může přijímat další argumenty zadávané klíčovým slovem pro filtrování výsledků skenování (např. skenování konkrétní služby, na konkrétním kanálu, pro služby konkrétní sady atd.) a pro ovlivnění doby trvání skenování a dalších parametrů. Kde je to možné, názvy parametrů by měly odpovídat těm v connect().

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

Dotaz na dynamické stavové informace rozhraní. Při volání bez argumentu popisuje návratová hodnota stav síťové linky. Jinak by param měl být řetězec pojmenovávající konkrétní stavový parametr, který se má načíst.

Návratové typy a hodnoty závisí na síťovém médiu/technologii. Některé z parametrů, které mohou být podporovány, jsou:

  • WiFi STA: použijte 'rssi' pro načtení RSSI signálu AP

  • WiFi AP: použijte 'stations' pro načtení seznamu všech STA připojených k AP. Seznam obsahuje n-tice ve tvaru (MAC, RSSI).

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

Získá nebo nastaví parametry konfigurace IP specifické pro rozhraní. Podporované parametry jsou následující (dostupnost konkrétního parametru závisí na portu a konkrétním síťovém rozhraní):

  • dhcp4 (True/False) získá IPv4 adresu, bránu a dns server pomocí DHCP. Tato metoda neblokuje a nečeká na získání adresy. Pro kontrolu, zda byla adresa získána, použijte vlastnost has_dhcp4 určenou pouze pro čtení.

  • gw4 Získá/nastaví výchozí IPv4 bránu.

  • dhcp6 (True/False) získá DNS server pomocí bezstavového DHCPv6. Získávání IP adres pomocí DHCPv6 aktuálně není implementováno.

  • autoconf6 (True/False) získá bezstavovou IPv6 adresu prostřednictvím síťové předpony sdílené v oznámeních směrovače. Pro kontrolu, zda byla bezstavová adresa získána, použijte vlastnost has_autoconf6 určenou pouze pro čtení.

  • addr4 (např. 192.168.0.4/24) získá aktuální IPv4 adresu a síťovou masku jako n-tici (ip, subnet), bez ohledu na to, jak byla tato adresa získána. Tuto metodu lze použít k nastavení statické IPv4 adresy buď jako n-tici (ip, subnet), nebo v notaci CIDR.

  • addr6 (např. fe80::1234:5678) získá seznam aktuálních IPv6 adres jako n-tici (ip, state, preferred_lifetime, valid_lifetime). To zahrnuje link-local, slaac a statické adresy. preferred_lifetime a valid_lifetime představují zbývající platnou a preferovanou dobu životnosti každé IPv6 adresy v sekundách. state udává aktuální stav adresy:

    • 0x08 - 0x0f značí, že je adresa nezávazná (tentative), s počítáním počtu odeslaných sond.

    • 0x10 Adresa je zastaralá (ale stále platná)

    • 0x30 Adresa je preferovaná (a platná)

    • 0x40 Adresa je duplicitní a nelze ji použít.

    Tuto metodu lze použít k nastavení statické IPv6 adresy nastavením tohoto parametru na adresu, jako fe80::1234:5678.

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

Poznámka

Tato funkce je zastaralá, místo toho použijte ipconfig().

Získá/nastaví parametry síťového rozhraní na úrovni IP: IP adresu, masku podsítě, bránu a DNS server. Při volání bez argumentů vrací tato metoda 4prvkovou n-tici s výše uvedenými informacemi. Pro nastavení výše uvedených hodnot předejte 4prvkovou n-tici s požadovanými informacemi. Například:

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

Získá nebo nastaví obecné parametry síťového rozhraní. Tyto metody umožňují pracovat s dalšími parametry nad rámec standardní konfigurace IP (řešené pomocí ipconfig()). Patří sem parametry specifické pro síť a pro hardware. Pro nastavení parametrů by se měla použít syntaxe argumentů zadávaných klíčovým slovem a více parametrů lze nastavit najednou. Pro dotazování by měl být název parametru uveden v uvozovkách jako řetězec a najednou lze dotazovat pouze jeden parametr:

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

Konkrétní implementace tříd sítí

Následující konkrétní třídy implementují rozhraní AbstractNIC a poskytují způsob, jak ovládat síťová rozhraní různého druhu.

Síťové funkce

Následuje výčet funkcí dostupných v modulu network.

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

Získá nebo nastaví dvoupísmenný kód země podle ISO 3166-1 Alpha-2, který se má použít pro rádiovou shodu s předpisy.

Pokud je parametr code zadán, země bude nastavena na tuto hodnotu. Je-li funkce volána bez parametrů, vrací aktuální zemi.

Výchozí kód "XX" představuje „celosvětový“ region.

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

Získá nebo nastaví název hostitele, který bude toto zařízení v síti identifikovat. Bude použit všemi rozhraními.

Tento název hostitele se používá pro:

  • Odeslání DHCP serveru v požadavku klienta. (Při použití DHCP)

  • Vysílání přes mDNS. (Pokud je povoleno)

Pokud je parametr name zadán, název hostitele bude nastaven na tuto hodnotu. Je-li funkce volána bez parametrů, vrací aktuální název hostitele.

Změna názvu hostitele se obvykle uplatní až během připojování. U DHCP je to proto, že název hostitele je součástí požadavku DHCP klienta, a implementace mDNS ve většině portů inicializuje název hostitele pouze jednou během připojování. Z tohoto důvodu musíte název hostitele nastavit před aktivací/připojením svých síťových rozhraní.

Délka názvu hostitele je omezena na 32 znaků. Porty MicroPythonu mohou z paměťových důvodů zvolit nižší limit. Pokud se zadaný název nevejde, je vyvolána výjimka ValueError.

Výchozím názvem hostitele je obvykle název desky.

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

Získá nebo nastaví globální parametry konfigurace IP. Podporované parametry jsou následující (dostupnost konkrétního parametru závisí na portu a konkrétním síťovém rozhraní):

  • dns Získá/nastaví DNS server. Tato metoda umí podporovat jak IPv4, tak IPv6 adresy.

  • prefer (4/6) Určuje, který typ adresy se má vrátit, pokud má doménové jméno jak A, tak AAAA záznamy. Pozor, toto nevyprázdní lokální DNS cache, takže jakékoli dříve získané adresy se nemusí změnit.