network — netwerkconfiguratie

Deze module biedt netwerkdrivers en routeringsconfiguratie. Om deze module te gebruiken moet een MicroPython-variant/-build met netwerkmogelijkheden zijn geïnstalleerd. Netwerkdrivers voor specifieke hardware zijn beschikbaar binnen deze module en worden gebruikt om hardware-netwerkinterface(s) te configureren. Netwerkdiensten die door geconfigureerde interfaces worden geboden, zijn vervolgens beschikbaar voor gebruik via de socket-module.

Bijvoorbeeld:

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

Vervang WLAN door WINC (verouderd WiFi-shield) of LAN (ingebouwde Ethernet), afhankelijk van wat geschikt is voor de cam. Het high-level patroon van construeren -> activeren -> verbinden -> sockets gebruiken is in alle drie de gevallen hetzelfde.

Algemene interface voor netwerkadapters

Deze sectie beschrijft een (impliciete) abstracte basisklasse voor alle netwerkinterfaceklassen die door MicroPython ports voor verschillende hardware worden geïmplementeerd. Dit betekent dat MicroPython niet daadwerkelijk een AbstractNIC-klasse biedt, maar dat elke daadwerkelijke NIC-klasse, zoals beschreven in de volgende secties, de hier beschreven methoden implementeert.

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

Instantieer een netwerkinterfaceobject. Parameters zijn afhankelijk van de netwerkinterface. Als er meer dan één interface van hetzelfde type is, moet de eerste parameter id zijn.

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

Schakel de netwerkinterface in of uit.

Zonder argument wordt de huidige status geretourneerd – True zolang de interface actief is, anders False.

Geef True door om de interface te activeren: schakel de onderliggende netwerkcontroller in / reset deze, laad waar van toepassing firmware, en breng de IP-stack op deze interface omhoog. Daaropvolgende aanroepen die met het netwerk communiceren (connect(), scan(), ipconfig(), …) vereisen dat de interface actief is.

Geef False door om de interface te deactiveren: breek de IP-stack af en geef driverresources vrij. Op draadloze interfaces wordt hierdoor ook de associatie met een eventueel verbonden netwerk verbroken.

Het gedrag bij het aanroepen van andere methoden op een inactieve interface is ongedefinieerd.

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

Verbind de interface met een netwerk. Deze methode is optioneel en alleen beschikbaar voor interfaces die niet “altijd verbonden” zijn. Als er geen parameters worden opgegeven, wordt verbinding gemaakt met de standaarddienst (of de enige dienst). Als er één parameter wordt opgegeven, is dit de primaire identifier van een dienst waarmee verbinding moet worden gemaakt. Deze kan vergezeld gaan van een key (wachtwoord) die nodig is om toegang te krijgen tot die dienst. Er kunnen verdere willekeurige keyword-only-parameters zijn, afhankelijk van het type netwerkmedium en/of het specifieke apparaat. Parameters kunnen worden gebruikt om: a) alternatieve identifiertypen voor diensten op te geven; b) aanvullende verbindingsparameters te bieden. Voor verschillende mediumtypen zijn er verschillende sets voorgedefinieerde/aanbevolen parameters, waaronder:

  • WiFi: bssid-keyword om verbinding te maken met een specifiek BSSID (MAC-adres)

disconnect() → None

Verbreek de verbinding met het netwerk.

isconnected() → bool

Retourneert True indien verbonden met het netwerk, anders retourneert het False.

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

Scan op de beschikbare netwerkdiensten/-verbindingen. Retourneert een lijst van tuples met de ontdekte dienstparameters. Voor verschillende netwerkmedia zijn er verschillende varianten van voorgedefinieerde/aanbevolen tuple-formaten, waaronder:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Er kunnen verdere velden zijn, specifiek voor een bepaald apparaat.

De functie kan aanvullende keyword-argumenten accepteren om scanresultaten te filteren (bijv. scannen op een bepaalde dienst, op een bepaald kanaal, op diensten van een bepaalde set, enz.), en om de scanduur en andere parameters te beïnvloeden. Waar mogelijk dienen parameternamen overeen te komen met die in connect().

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

Vraag dynamische statusinformatie van de interface op. Wanneer zonder argument aangeroepen, beschrijft de retourwaarde de status van de netwerklink. Anders moet param een string zijn die de specifieke op te halen statusparameter benoemt.

De retourtypen en -waarden zijn afhankelijk van het netwerkmedium/de netwerktechnologie. Enkele van de parameters die ondersteund kunnen worden zijn:

  • WiFi STA: gebruik 'rssi' om de RSSI van het AP-signaal op te halen

  • WiFi AP: gebruik 'stations' om een lijst op te halen van alle STA’s die met het AP verbonden zijn. De lijst bevat tuples van de vorm (MAC, RSSI).

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

Verkrijg of stel interfacespecifieke IP-configuratie-interfaceparameters in. De ondersteunde parameters zijn de volgende (de beschikbaarheid van een bepaalde parameter hangt af van de port en de specifieke netwerkinterface):

  • dhcp4 (True/False) verkrijg een IPv4-adres, gateway en dns-server via DHCP. Deze methode blokkeert niet en wacht niet totdat een adres is verkregen. Gebruik de alleen-lezen-eigenschap has_dhcp4 om te controleren of een adres is verkregen.

  • gw4 Verkrijg/stel de IPv4-standaardgateway in.

  • dhcp6 (True/False) verkrijg een DNS-server via stateless DHCPv6. Het verkrijgen van IP-adressen via DHCPv6 is momenteel niet geïmplementeerd.

  • autoconf6 (True/False) verkrijg een stateless IPv6-adres via de netwerkprefix die in router advertisements wordt gedeeld. Gebruik de alleen-lezen-eigenschap has_autoconf6 om te controleren of een stateless adres is verkregen.

  • addr4 (bijv. 192.168.0.4/24) verkrijg het huidige IPv4-adres en netwerkmasker als (ip, subnet)-tuple, ongeacht hoe dit adres is verkregen. Deze methode kan worden gebruikt om een statisch IPv4-adres in te stellen, hetzij als (ip, subnet)-tuple, hetzij in CIDR-notatie.

  • addr6 (bijv. fe80::1234:5678) verkrijg een lijst van huidige IPv6-adressen als (ip, state, preferred_lifetime, valid_lifetime)-tuple. Dit omvat link-local-, slaac- en statische adressen. preferred_lifetime en valid_lifetime vertegenwoordigen de resterende geldige en preferente levensduur van elk IPv6-adres, in seconden. state geeft de huidige status van het adres aan:

    • 0x08 - 0x0f geeft aan dat het adres tentatief is, waarbij het aantal verzonden probes wordt geteld.

    • 0x10 Het adres is verouderd (maar nog steeds geldig)

    • 0x30 Het adres is preferent (en geldig)

    • 0x40 Het adres is gedupliceerd en kan niet worden gebruikt.

    Deze methode kan worden gebruikt om een statisch IPv6-adres in te stellen, door deze parameter op het adres in te stellen, zoals fe80::1234:5678.

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

Notitie

Deze functie is verouderd, gebruik in plaats daarvan ipconfig().

Verkrijg/stel netwerkinterfaceparameters op IP-niveau in: IP-adres, subnetmasker, gateway en DNS-server. Wanneer zonder argumenten aangeroepen, retourneert deze methode een 4-tuple met bovenstaande informatie. Om de bovenstaande waarden in te stellen, geef je een 4-tuple met de vereiste informatie door. Bijvoorbeeld:

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

Verkrijg of stel algemene netwerkinterfaceparameters in. Deze methoden maken het mogelijk om te werken met aanvullende parameters buiten de standaard IP-configuratie (zoals afgehandeld door ipconfig()). Hieronder vallen netwerkspecifieke en hardwarespecifieke parameters. Voor het instellen van parameters dient de keyword-argumentsyntaxis te worden gebruikt, en meerdere parameters kunnen tegelijk worden ingesteld. Voor het opvragen moet een parameternaam tussen aanhalingstekens als string worden opgegeven, en er kan slechts één parameter tegelijk worden opgevraagd:

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

Specifieke implementaties van netwerkklassen

De volgende concrete klassen implementeren de AbstractNIC-interface en bieden een manier om netwerkinterfaces van verschillende soorten aan te sturen.

Netwerkfuncties

Hieronder volgen de functies die beschikbaar zijn in de network-module.

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

Verkrijg of stel de uit twee letters bestaande ISO 3166-1 Alpha-2-landcode in die voor radioconformiteit moet worden gebruikt.

Als de parameter code wordt opgegeven, wordt het land op deze waarde ingesteld. Als de functie zonder parameters wordt aangeroepen, retourneert deze het huidige land.

De standaardcode "XX" vertegenwoordigt de “wereldwijde” regio.

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

Verkrijg of stel de hostnaam in die dit apparaat op het netwerk identificeert. Deze wordt door alle interfaces gebruikt.

Deze hostnaam wordt gebruikt voor:

  • Verzenden naar de DHCP-server in het clientverzoek. (Bij gebruik van DHCP)

  • Uitzenden via mDNS. (Indien ingeschakeld)

Als de parameter name wordt opgegeven, wordt de hostnaam op deze waarde ingesteld. Als de functie zonder parameters wordt aangeroepen, retourneert deze de huidige hostnaam.

Een wijziging van de hostnaam wordt doorgaans alleen toegepast tijdens het verbinden. Voor DHCP komt dit doordat de hostnaam onderdeel is van het DHCP-clientverzoek, en de implementatie van mDNS in de meeste ports initialiseert de hostnaam slechts één keer tijdens het verbinden. Om deze reden moet je de hostnaam instellen voordat je je netwerkinterfaces activeert/verbindt.

De lengte van de hostnaam is beperkt tot 32 tekens. MicroPython ports kunnen ervoor kiezen om om geheugenredenen een lagere limiet in te stellen. Als de opgegeven naam niet past, wordt een ValueError opgeworpen.

De standaardhostnaam is doorgaans de naam van het bord.

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

Verkrijg of stel globale IP-configuratieparameters in. De ondersteunde parameters zijn de volgende (de beschikbaarheid van een bepaalde parameter hangt af van de port en de specifieke netwerkinterface):

  • dns Verkrijg/stel de DNS-server in. Deze methode kan zowel IPv4- als IPv6-adressen ondersteunen.

  • prefer (4/6) Geef aan welk adrestype geretourneerd moet worden als een domeinnaam zowel A- als AAAA-records heeft. Let op: dit wist de lokale DNS-cache niet, zodat eerder verkregen adressen mogelijk niet veranderen.