network — налаштування мережі

Цей модуль надає мережеві драйвери та конфігурацію маршрутизації. Для використання цього модуля необхідно встановити варіант/збірку MicroPython з мережевими можливостями. Мережеві драйвери для конкретного обладнання доступні в цьому модулі та використовуються для налаштування апаратних мережевих інтерфейсів. Мережеві служби, що надаються налаштованими інтерфейсами, стають доступними для використання через модуль socket.

Наприклад:

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

Замініть WLAN на WINC (старий WiFi-щит) або LAN (вбудований Ethernet) відповідно до камери. Загальна схема побудова -> активація -> підключення -> використання сокетів однакова в усіх трьох випадках.

Загальний інтерфейс мережевого адаптера

Цей розділ описує (неявний) абстрактний базовий клас для всіх класів мережевих інтерфейсів, реалізованих портами MicroPython для різного обладнання. Це означає, що MicroPython насправді не надає клас AbstractNIC, але будь-який реальний клас NIC, описаний у наступних розділах, реалізує методи, описані тут.

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

Створює об’єкт мережевого інтерфейсу. Параметри залежать від мережевого інтерфейсу. Якщо є більше одного інтерфейсу одного типу, першим параметром має бути id.

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

Вмикає або вимикає мережевий інтерфейс.

Без аргументу повертає поточний стан – True, якщо інтерфейс активний, False інакше.

Передайте True для активації інтерфейсу: увімкнення / скидання базового мережевого контролера, завантаження мікропрограми де необхідно та підняття IP-стеку на цьому інтерфейсі. Подальші виклики, що звертаються до мережі (connect(), scan(), ipconfig(), …), вимагають, щоб інтерфейс був активний.

Передайте False для деактивації інтерфейсу: вимкнення IP-стеку та звільнення ресурсів драйвера. На бездротових інтерфейсах це також від’єднує від будь-якої поточно приєднаної мережі.

Поведінка при виклику інших методів на неактивному інтерфейсі не визначена.

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

Підключає інтерфейс до мережі. Цей метод необов’язковий і доступний лише для інтерфейсів, які не є «завжди підключеними». Якщо параметри не задані, підключається до служби за замовчуванням (або єдиної). Якщо задано один параметр, це основний ідентифікатор служби для підключення. Він може супроводжуватись ключем (паролем), необхідним для доступу до цієї служби. Можуть бути додаткові довільні параметри лише у вигляді ключових слів, залежно від типу мережевого середовища та/або конкретного пристрою. Параметри можуть використовуватись для: а) зазначення альтернативних типів ідентифікатора служби; б) надання додаткових параметрів підключення. Для різних типів середовищ існують різні набори попередньо визначених/рекомендованих параметрів, серед них:

  • WiFi: ключове слово bssid для підключення до конкретного BSSID (MAC-адреса)

disconnect() → None

Від’єднується від мережі.

isconnected() → bool

Повертає True, якщо підключено до мережі, інакше повертає False.

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

Сканує доступні мережеві служби/з’єднання. Повертає список кортежів з виявленими параметрами служб. Для різних мережевих середовищ існують різні варіанти попередньо визначених/рекомендованих форматів кортежів, серед них:

  • WiFi: (ssid, bssid, channel, RSSI, security, hidden). Можуть бути додаткові поля, специфічні для конкретного пристрою.

Функція може приймати додаткові ключові аргументи для фільтрації результатів сканування (наприклад, сканування конкретної служби, на конкретному каналі, для служб конкретного набору тощо) та для впливу на тривалість сканування та інші параметри. Де можливо, назви параметрів мають відповідати тим, що у connect().

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

Запит динамічної інформації про стан інтерфейсу. При виклику без аргументу повертане значення описує статус мережевого з’єднання. Інакше param має бути рядком, що вказує конкретний параметр стану для отримання.

Типи та значення, що повертаються, залежать від мережевого середовища/технології. Деякі з параметрів, які можуть підтримуватись:

  • WiFi STA: використовуйте 'rssi' для отримання RSSI сигналу AP

  • WiFi AP: використовуйте 'stations' для отримання списку всіх STА, підключених до AP. Список містить кортежі виду (MAC, RSSI).

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

Отримує або задає специфічні для інтерфейсу параметри IP-конфігурації. Підтримувані параметри наведено нижче (доступність конкретного параметра залежить від порту та конкретного мережевого інтерфейсу):

  • dhcp4 (True/False) отримати адресу IPv4, шлюз та DNS-сервер через DHCP. Цей метод не блокує і не чекає на отримання адреси. Щоб перевірити, чи отримано адресу, використовуйте властивість лише для читання has_dhcp4.

  • gw4 Отримати/задати шлюз IPv4 за замовчуванням.

  • dhcp6 (True/False) отримати DNS-сервер через stateless DHCPv6. Отримання IP-адрес через DHCPv6 наразі не реалізовано.

  • autoconf6 (True/False) отримати stateless адресу IPv6 через мережевий префікс, що надається у повідомленнях Router Advertisement. Щоб перевірити, чи отримано stateless адресу, використовуйте властивість лише для читання has_autoconf6.

  • addr4 (наприклад, 192.168.0.4/24) отримати поточну адресу IPv4 та маску мережі у вигляді кортежу (ip, subnet) незалежно від способу отримання цієї адреси. Цей метод можна використовувати для задання статичної адреси IPv4 у вигляді кортежу (ip, subnet) або в нотації CIDR.

  • addr6 (наприклад, fe80::1234:5678) отримати список поточних адрес IPv6 у вигляді кортежу (ip, state, preferred_lifetime, valid_lifetime). Це включає link-local, slaac та статичні адреси. preferred_lifetime та valid_lifetime представляють залишковий дійсний та бажаний термін служби кожної адреси IPv6 в секундах. state вказує поточний стан адреси:

    • 0x08 - 0x0f вказує, що адреса є тимчасовою (tentative), рахуючи кількість відправлених probe-запитів.

    • 0x10 Адреса є застарілою (але ще дійсною)

    • 0x30 Адреса є бажаною (та дійсною)

    • 0x40 Адреса є продубльованою і не може бути використана.

    Цей метод можна використовувати для задання статичної адреси IPv6, встановивши цей параметр на адресу, наприклад fe80::1234:5678.

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

Примітка

Ця функція застаріла, використовуйте натомість ipconfig().

Отримує/задає мережеві параметри інтерфейсу на рівні IP: IP-адресу, маску підмережі, шлюз та DNS-сервер. При виклику без аргументів цей метод повертає 4-кортеж з наведеною вище інформацією. Для встановлення наведених вище значень передайте 4-кортеж з необхідною інформацією. Наприклад:

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

Отримує або задає загальні параметри мережевого інтерфейсу. Ці методи дозволяють працювати з додатковими параметрами поза стандартною IP-конфігурацією (яку забезпечує ipconfig()). Вони включають мережеві та апаратно-специфічні параметри. Для встановлення параметрів слід використовувати синтаксис ключових аргументів, і кілька параметрів можна задати одночасно. Для запиту назва параметра має бути задана у вигляді рядка, і одночасно можна запитати лише один параметр:

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

Конкретні реалізації класів мережі

Наступні конкретні класи реалізують інтерфейс AbstractNIC і надають спосіб керування мережевими інтерфейсами різних видів.

Мережеві функції

Нижче наведено функції, доступні в модулі network.

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

Отримує або задає двобуквений код країни ISO 3166-1 Alpha-2 для дотримання радіочастотних норм.

Якщо параметр code задано, країна буде встановлена на це значення. Якщо функція викликається без параметрів, вона повертає поточний код країни.

Код за замовчуванням "XX" представляє «всесвітній» регіон.

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

Отримує або задає ім’я хоста, яке ідентифікуватиме цей пристрій у мережі. Воно використовуватиметься всіма інтерфейсами.

Це ім’я хоста використовується для:

  • Надсилання DHCP-серверу у запиті клієнта. (При використанні DHCP)

  • Широкомовлення через mDNS. (Якщо увімкнено)

Якщо параметр name задано, ім’я хоста буде встановлено на це значення. Якщо функція викликається без параметрів, вона повертає поточне ім’я хоста.

Зміна імені хоста зазвичай застосовується лише під час підключення. Для DHCP це пов’язано з тим, що ім’я хоста є частиною запиту DHCP-клієнта, а реалізація mDNS у більшості портів ініціалізує ім’я хоста лише один раз під час підключення. З цієї причини необхідно задати ім’я хоста до активації/підключення мережевих інтерфейсів.

Довжина імені хоста обмежена 32 символами. Порти MicroPython можуть встановити нижчий ліміт з міркувань пам’яті. Якщо задане ім’я не вміщується, виникає ValueError.

Ім’я хоста за замовчуванням зазвичай є назвою плати.

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

Отримує або задає глобальні параметри IP-конфігурації. Підтримувані параметри наведено нижче (доступність конкретного параметра залежить від порту та конкретного мережевого інтерфейсу):

  • dns Отримати/задати DNS-сервер. Цей метод підтримує як адреси IPv4, так і IPv6.

  • prefer (4/6) Вказати, який тип адреси повертати, якщо доменне ім’я має записи A і AAAA. Зверніть увагу, що це не очищає локальний кеш DNS, тому раніше отримані адреси можуть не змінитися.