network — konfiguracja sieci

Ten moduł udostępnia sterowniki sieciowe i konfigurację routingu. Aby z niego korzystać, musi być zainstalowany wariant/kompilacja MicroPython z funkcjami sieciowymi. W module tym dostępne są sterowniki sieciowe dla konkretnego sprzętu, które służą do konfiguracji sprzętowych interfejsów sieciowych. Usługi sieciowe udostępniane przez skonfigurowane interfejsy są następnie dostępne do użytku za pośrednictwem modułu socket.

Na przykład:

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

Zastąp WLAN przez WINC (starsza nakładka WiFi) lub LAN (wbudowany Ethernet), zależnie od kamery. Ogólny schemat: utworzenie -> aktywacja -> połączenie -> użycie gniazd jest taki sam we wszystkich trzech przypadkach.

Wspólny interfejs adaptera sieciowego

Ta sekcja opisuje (domniemaną) abstrakcyjną klasę bazową dla wszystkich klas interfejsów sieciowych implementowanych przez porty MicroPython dla różnego sprzętu. Oznacza to, że MicroPython w rzeczywistości nie udostępnia klasy AbstractNIC, lecz każda rzeczywista klasa NIC, opisana w kolejnych sekcjach, implementuje metody opisane tutaj.

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

Tworzy obiekt interfejsu sieciowego. Parametry zależą od interfejsu sieciowego. Jeśli istnieje więcej niż jeden interfejs tego samego typu, pierwszym parametrem powinno być id.

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

Włącza lub wyłącza interfejs sieciowy.

Bez argumentu zwraca bieżący stan – True, gdy interfejs jest aktywny, False w przeciwnym razie.

Przekaż True, aby aktywować interfejs: włączyć zasilanie / zresetować bazowy kontroler sieciowy, załadować oprogramowanie układowe tam, gdzie ma to zastosowanie, oraz uruchomić stos IP na tym interfejsie. Kolejne wywołania komunikujące się z siecią (connect(), scan(), ipconfig(), …) wymagają, aby interfejs był aktywny.

Przekaż False, aby dezaktywować interfejs: wyłączyć stos IP i zwolnić zasoby sterownika. Na interfejsach bezprzewodowych powoduje to także odłączenie od każdej aktualnie połączonej sieci.

Zachowanie przy wywoływaniu innych metod na nieaktywnym interfejsie jest niezdefiniowane.

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

Łączy interfejs z siecią. Ta metoda jest opcjonalna i dostępna tylko dla interfejsów, które nie są „zawsze połączone”. Jeśli nie podano parametrów, łączy się z domyślną (lub jedyną) usługą. Jeśli podano pojedynczy parametr, jest to główny identyfikator usługi, z którą należy się połączyć. Może mu towarzyszyć klucz (hasło) wymagany do uzyskania dostępu do tej usługi. Mogą występować kolejne dowolne parametry przekazywane wyłącznie jako słowa kluczowe, w zależności od typu medium sieciowego i/lub konkretnego urządzenia. Parametry mogą służyć do: a) określenia alternatywnych typów identyfikatorów usług; b) podania dodatkowych parametrów połączenia. Dla różnych typów medium istnieją różne zestawy predefiniowanych/zalecanych parametrów, między innymi:

  • WiFi: słowo kluczowe bssid, aby połączyć się z konkretnym BSSID (adresem MAC)

disconnect() → None

Rozłącza z siecią.

isconnected() → bool

Zwraca True, jeśli istnieje połączenie z siecią, w przeciwnym razie zwraca False.

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

Skanuje dostępne usługi/połączenia sieciowe. Zwraca listę krotek z wykrytymi parametrami usług. Dla różnych mediów sieciowych istnieją różne warianty predefiniowanych/zalecanych formatów krotek, między innymi:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Mogą występować dodatkowe pola, specyficzne dla konkretnego urządzenia.

Funkcja może przyjmować dodatkowe argumenty słów kluczowych w celu filtrowania wyników skanowania (np. skanowanie konkretnej usługi, na konkretnym kanale, dla usług z konkretnego zestawu itp.) oraz w celu wpływania na czas trwania skanowania i inne parametry. Tam, gdzie to możliwe, nazwy parametrów powinny odpowiadać tym w connect().

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

Sprawdza dynamiczne informacje o stanie interfejsu. Wywołana bez argumentu zwraca wartość opisującą stan łącza sieciowego. W przeciwnym razie param powinien być ciągiem znaków nazywającym konkretny parametr stanu do pobrania.

Typy i wartości zwracane zależą od medium/technologii sieciowej. Niektóre z parametrów, które mogą być obsługiwane, to:

  • WiFi STA: użyj 'rssi', aby pobrać RSSI sygnału AP

  • WiFi AP: użyj 'stations', aby pobrać listę wszystkich stacji STA połączonych z AP. Lista zawiera krotki w postaci (MAC, RSSI).

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

Pobiera lub ustawia parametry konfiguracji IP specyficzne dla interfejsu. Obsługiwane są następujące parametry (dostępność konkretnego parametru zależy od portu i konkretnego interfejsu sieciowego):

  • dhcp4 (True/False) uzyskuje adres IPv4, bramę i serwer dns za pośrednictwem DHCP. Ta metoda nie blokuje i nie czeka na uzyskanie adresu. Aby sprawdzić, czy adres został uzyskany, użyj właściwości tylko do odczytu has_dhcp4.

  • gw4 Pobiera/ustawia domyślną bramę IPv4.

  • dhcp6 (True/False) uzyskuje serwer DNS za pośrednictwem bezstanowego DHCPv6. Uzyskiwanie adresów IP za pośrednictwem DHCPv6 nie jest obecnie zaimplementowane.

  • autoconf6 (True/False) uzyskuje bezstanowy adres IPv6 za pośrednictwem prefiksu sieci udostępnianego w komunikatach rozgłoszeniowych routera. Aby sprawdzić, czy uzyskano adres bezstanowy, użyj właściwości tylko do odczytu has_autoconf6.

  • addr4 (np. 192.168.0.4/24) uzyskuje bieżący adres IPv4 i maskę sieci jako krotkę (ip, subnet), niezależnie od tego, w jaki sposób uzyskano ten adres. Tej metody można użyć do ustawienia statycznego adresu IPv4 jako krotki (ip, subnet) albo w notacji CIDR.

  • addr6 (np. fe80::1234:5678) uzyskuje listę bieżących adresów IPv6 jako krotki (ip, state, preferred_lifetime, valid_lifetime). Obejmuje to adresy link-local, slaac i statyczne. preferred_lifetime i valid_lifetime reprezentują pozostały ważny i preferowany czas życia każdego adresu IPv6, w sekundach. state wskazuje bieżący stan adresu:

    • 0x08 - 0x0f wskazuje, że adres jest wstępny, zliczając liczbę wysłanych sond.

    • 0x10 Adres jest przestarzały (ale wciąż ważny)

    • 0x30 Adres jest preferowany (i ważny)

    • 0x40 Adres jest zduplikowany i nie może być używany.

    Tej metody można użyć do ustawienia statycznego adresu IPv6 poprzez ustawienie tego parametru na adres, na przykład fe80::1234:5678.

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

Informacja

Ta funkcja jest przestarzała, zamiast niej użyj ipconfig().

Pobiera/ustawia parametry interfejsu sieciowego na poziomie IP: adres IP, maskę podsieci, bramę i serwer DNS. Wywołana bez argumentów zwraca 4-elementową krotkę z powyższymi informacjami. Aby ustawić powyższe wartości, przekaż 4-elementową krotkę z wymaganymi informacjami. Na przykład:

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

Pobiera lub ustawia ogólne parametry interfejsu sieciowego. Metody te pozwalają pracować z dodatkowymi parametrami wykraczającymi poza standardową konfigurację IP (którą zajmuje się ipconfig()). Obejmują one parametry specyficzne dla sieci i sprzętu. Do ustawiania parametrów należy używać składni argumentów słów kluczowych, przy czym można ustawić wiele parametrów naraz. Do zapytań nazwę parametru należy podać jako ciąg znaków w cudzysłowie, a jednorazowo można odpytać tylko 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'))

Implementacje konkretnych klas sieciowych

Następujące konkretne klasy implementują interfejs AbstractNIC i zapewniają sposób sterowania różnego rodzaju interfejsami sieciowymi.

Funkcje sieciowe

Poniżej znajdują się funkcje dostępne w module network.

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

Pobiera lub ustawia dwuliterowy kod kraju ISO 3166-1 Alpha-2 używany do zgodności radiowej.

Jeśli podano parametr code, kraj zostanie ustawiony na tę wartość. Jeśli funkcja jest wywoływana bez parametrów, zwraca bieżący kraj.

Domyślny kod "XX" reprezentuje region „ogólnoświatowy”.

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

Pobiera lub ustawia nazwę hosta, która będzie identyfikować to urządzenie w sieci. Będzie używana przez wszystkie interfejsy.

Ta nazwa hosta jest używana do:

  • Wysyłania do serwera DHCP w żądaniu klienta. (Jeśli używany jest DHCP)

  • Rozgłaszania za pośrednictwem mDNS. (Jeśli włączone)

Jeśli podano parametr name, nazwa hosta zostanie ustawiona na tę wartość. Jeśli funkcja jest wywoływana bez parametrów, zwraca bieżącą nazwę hosta.

Zmiana nazwy hosta jest zazwyczaj stosowana dopiero podczas połączenia. W przypadku DHCP wynika to z tego, że nazwa hosta jest częścią żądania klienta DHCP, a implementacja mDNS w większości portów inicjalizuje nazwę hosta tylko raz, podczas połączenia. Z tego powodu nazwę hosta należy ustawić przed aktywacją/połączeniem interfejsów sieciowych.

Długość nazwy hosta jest ograniczona do 32 znaków. Porty MicroPython mogą ustawić niższy limit ze względów pamięciowych. Jeśli podana nazwa się nie zmieści, zgłaszany jest błąd ValueError.

Domyślną nazwą hosta jest zazwyczaj nazwa płytki.

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

Pobiera lub ustawia globalne parametry konfiguracji IP. Obsługiwane są następujące parametry (dostępność konkretnego parametru zależy od portu i konkretnego interfejsu sieciowego):

  • dns Pobiera/ustawia serwer DNS. Ta metoda może obsługiwać zarówno adresy IPv4, jak i IPv6.

  • prefer (4/6) Określa, który typ adresu zwrócić, jeśli nazwa domeny ma zarówno rekordy A, jak i AAAA. Należy pamiętać, że nie czyści to lokalnej pamięci podręcznej DNS, więc wcześniej uzyskane adresy mogą się nie zmienić.