network — verkkomääritykset

Tämä moduuli tarjoaa verkko-ohjaimet ja reitityksen määritykset. Tämän moduulin käyttäminen edellyttää, että asennettuna on verkkominaisuuksilla varustettu MicroPython-variantti/-käännös. Tietyn laitteiston verkko-ohjaimet ovat saatavilla tämän moduulin sisällä, ja niitä käytetään laitteiston verkkorajapintojen määrittämiseen. Määritettyjen rajapintojen tarjoamat verkkopalvelut ovat tämän jälkeen käytettävissä socket-moduulin kautta.

Esimerkiksi:

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

Korvaa WLAN luokalla WINC (vanhempi WiFi-laajennus) tai LAN (sisäänrakennettu Ethernet) kameralle sopivasti. Korkean tason kaava rakenna -> aktivoi -> yhdistä -> käytä socketteja on sama kaikissa kolmessa tapauksessa.

Yhteinen verkkosovittimen rajapinta

Tässä osiossa kuvataan (epäsuora) abstrakti perusluokka kaikille verkkorajapintaluokille, jotka MicroPython-portit toteuttavat eri laitteistoille. Tämä tarkoittaa, että MicroPython ei varsinaisesti tarjoa AbstractNIC-luokkaa, mutta jokainen varsinainen NIC-luokka, kuten seuraavissa osioissa kuvataan, toteuttaa tässä kuvatut metodit.

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

Luo verkkorajapintaobjekti. Parametrit ovat verkkorajapintakohtaisia. Jos samaa tyyppiä on useampi kuin yksi rajapinta, ensimmäisen parametrin tulisi olla id.

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

Käynnistä verkkorajapinta tai sammuta se.

Ilman argumenttia palauttaa nykyisen tilan – True kun rajapinta on aktiivinen, muutoin False.

Anna True aktivoidaksesi rajapinnan: kytke virta päälle / nollaa taustalla oleva verkko-ohjain, lataa laiteohjelmisto tarvittaessa ja käynnistä IP-pino tässä rajapinnassa. Myöhemmät kutsut, jotka kommunikoivat verkon kanssa (connect(), scan(), ipconfig(), …), edellyttävät, että rajapinta on aktiivinen.

Anna False deaktivoidaksesi rajapinnan: pura IP-pino ja vapauta ohjaimen resurssit. Langattomissa rajapinnoissa tämä myös purkaa yhteyden mihin tahansa tällä hetkellä liitettyyn verkkoon.

Muiden metodien kutsumisen käyttäytyminen ei-aktiivisessa rajapinnassa on määrittelemätön.

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

Yhdistä rajapinta verkkoon. Tämä metodi on valinnainen ja saatavilla vain rajapinnoille, jotka eivät ole ”aina yhdistettyjä”. Jos parametreja ei anneta, yhdistä oletuspalveluun (tai ainoaan palveluun). Jos annetaan yksi parametri, se on yhdistettävän palvelun ensisijainen tunniste. Sen mukana voi olla avain (salasana), joka vaaditaan kyseisen palvelun käyttämiseen. Lisäksi voi olla muita mielivaltaisia vain-avainsana-parametreja riippuen verkon mediatyypistä ja/tai tietystä laitteesta. Parametreja voidaan käyttää: a) vaihtoehtoisten palvelutunnistetyyppien määrittämiseen; b) lisäyhteysparametrien tarjoamiseen. Eri mediatyypeille on erilaisia ennalta määriteltyjen/suositeltujen parametrien joukkoja, niiden joukossa:

  • WiFi: bssid-avainsana yhdistämään tiettyyn BSSID:hen (MAC-osoite)

disconnect() → None

Katkaise yhteys verkkoon.

isconnected() → bool

Palauttaa True, jos yhteys verkkoon on muodostettu, muutoin palauttaa False.

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

Etsi saatavilla olevia verkkopalveluja/-yhteyksiä. Palauttaa listan monikoita löydettyjen palvelujen parametreilla. Eri verkkomedioille on erilaisia variantteja ennalta määritellyistä/suositelluista monikkomuodoista, niiden joukossa:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Lisäksi voi olla muita kenttiä, jotka ovat tietylle laitteelle ominaisia.

Funktio voi hyväksyä lisäavainsana-argumentteja skannaustulosten suodattamiseen (esim. tietyn palvelun, tietyn kanavan tai tietyn joukon palvelujen skannaamiseen jne.) sekä skannauksen keston ja muiden parametrien vaikuttamiseen. Mahdollisuuksien mukaan parametrien nimien tulisi vastata connect():n parametreja.

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

Kysele rajapinnan dynaamista tilatietoa. Kun kutsutaan ilman argumenttia, palautusarvo kuvaa verkkolinkin tilaa. Muutoin param tulisi olla merkkijono, joka nimeää tietyn haettavan tilaparametrin.

Palautustyypit ja -arvot riippuvat verkkomediasta/-teknologiasta. Joitakin tuettuja parametreja voivat olla:

  • WiFi STA: käytä 'rssi' hakeaksesi tukiaseman signaalin RSSI:n

  • WiFi AP: käytä 'stations' hakeaksesi listan kaikista tukiasemaan yhdistetyistä STA:ista. Lista sisältää monikoita muotoa (MAC, RSSI).

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

Hae tai aseta rajapintakohtaiset IP-määritysrajapinnan parametrit. Tuetut parametrit ovat seuraavat (tietyn parametrin saatavuus riippuu portista ja tietystä verkkorajapinnasta):

  • dhcp4 (True/False) hanki IPv4-osoite, yhdyskäytävä ja DNS-palvelin DHCP:n kautta. Tämä metodi ei estä eikä odota osoitteen saamista. Tarkistaaksesi, saatiinko osoite, käytä vain luettavaa ominaisuutta has_dhcp4.

  • gw4 Hae/aseta IPv4-oletusyhdyskäytävä.

  • dhcp6 (True/False) hanki DNS-palvelin tilattoman DHCPv6:n kautta. IP-osoitteiden hankkimista DHCPv6:n kautta ei ole tällä hetkellä toteutettu.

  • autoconf6 (True/False) hanki tilaton IPv6-osoite reititinilmoituksissa jaetun verkkoetuliitteen kautta. Tarkistaaksesi, saatiinko tilaton osoite, käytä vain luettavaa ominaisuutta has_autoconf6.

  • addr4 (esim. 192.168.0.4/24) hae nykyinen IPv4-osoite ja verkkomaski (ip, subnet)-monikkona riippumatta siitä, miten tämä osoite saatiin. Tätä metodia voidaan käyttää staattisen IPv4-osoitteen asettamiseen joko (ip, subnet)-monikkona tai CIDR-merkinnällä.

  • addr6 (esim. fe80::1234:5678) hae lista nykyisistä IPv6-osoitteista (ip, state, preferred_lifetime, valid_lifetime)-monikkona. Tämä sisältää link-local-, slaac- ja staattiset osoitteet. preferred_lifetime ja valid_lifetime edustavat kunkin IPv6-osoitteen jäljellä olevaa voimassa- ja ensisijaisuusaikaa sekunteina. state ilmaisee osoitteen nykyisen tilan:

    • 0x08 - 0x0f ilmaisee, että osoite on alustava, laskien lähetettyjen koetinten määrää.

    • 0x10 Osoite on vanhentunut (mutta edelleen voimassa)

    • 0x30 Osoite on ensisijainen (ja voimassa)

    • 0x40 Osoite on kaksinkertainen eikä sitä voi käyttää.

    Tätä metodia voidaan käyttää staattisen IPv6-osoitteen asettamiseen asettamalla tämä parametri osoitteeksi, kuten fe80::1234:5678.

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

Muista

Tämä funktio on vanhentunut, käytä sen sijaan ipconfig().

Hae/aseta IP-tason verkkorajapinnan parametrit: IP-osoite, aliverkon peite, yhdyskäytävä ja DNS-palvelin. Kun kutsutaan ilman argumentteja, tämä metodi palauttaa 4-monikon yllä mainituilla tiedoilla. Asettaaksesi yllä olevat arvot, anna 4-monikko, jossa on vaaditut tiedot. Esimerkiksi:

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

Hae tai aseta yleiset verkkorajapinnan parametrit. Nämä metodit mahdollistavat työskentelyn standardin IP-määrityksen lisäparametrien kanssa (joista ipconfig() huolehtii). Näihin kuuluvat verkkokohtaiset ja laitteistokohtaiset parametrit. Parametrien asettamiseen tulisi käyttää avainsana-argumenttisyntaksia, ja useita parametreja voidaan asettaa kerralla. Kyselyssä parametrin nimi tulisi lainata merkkijonona, ja vain yhtä parametria voidaan kysyä kerrallaan:

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

Tietyt verkkoluokkien toteutukset

Seuraavat konkreettiset luokat toteuttavat AbstractNIC-rajapinnan ja tarjoavat tavan ohjata erityyppisiä verkkorajapintoja.

Verkkofunktiot

Seuraavat ovat network-moduulissa saatavilla olevia funktioita.

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

Hae tai aseta kaksikirjaiminen ISO 3166-1 Alpha-2 -maakoodi, jota käytetään radiomääräysten noudattamiseen.

Jos code-parametri annetaan, maa asetetaan tähän arvoon. Jos funktio kutsutaan ilman parametreja, se palauttaa nykyisen maan.

Oletuskoodi "XX" edustaa ”maailmanlaajuista” aluetta.

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

Hae tai aseta isäntänimi, joka tunnistaa tämän laitteen verkossa. Sitä käyttävät kaikki rajapinnat.

Tätä isäntänimeä käytetään seuraaviin:

  • Lähettäminen DHCP-palvelimelle asiakaspyynnössä. (Jos käytetään DHCP:tä)

  • Lähettäminen mDNS:n kautta. (Jos käytössä)

Jos name-parametri annetaan, isäntänimi asetetaan tähän arvoon. Jos funktio kutsutaan ilman parametreja, se palauttaa nykyisen isäntänimen.

Isäntänimen muutos otetaan tyypillisesti käyttöön vain yhteyden muodostamisen aikana. DHCP:n osalta tämä johtuu siitä, että isäntänimi on osa DHCP-asiakaspyyntöä, ja useimpien porttien mDNS-toteutus alustaa isäntänimen vain kerran yhteyden muodostamisen aikana. Tämän vuoksi isäntänimi on asetettava ennen verkkorajapintojen aktivointia/yhdistämistä.

Isäntänimen pituus on rajoitettu 32 merkkiin. MicroPython-portit voivat valita asettaa alemman rajan muistisyistä. Jos annettu nimi ei mahdu, nostetaan ValueError.

Oletusisäntänimi on tyypillisesti kortin nimi.

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

Hae tai aseta globaalit IP-määritysparametrit. Tuetut parametrit ovat seuraavat (tietyn parametrin saatavuus riippuu portista ja tietystä verkkorajapinnasta):

  • dns Hae/aseta DNS-palvelin. Tämä metodi voi tukea sekä IPv4- että IPv6-osoitteita.

  • prefer (4/6) Määritä, mikä osoitetyyppi palautetaan, jos verkkotunnuksella on sekä A- että AAAA-tietueet. Huomaa, että tämä ei tyhjennä paikallista DNS-välimuistia, joten aiemmin saadut osoitteet eivät välttämättä muutu.