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 shield รุ่นเก่า) หรือ LAN (Ethernet ในตัว) ตามความเหมาะสมกับกล้อง รูปแบบระดับสูง construct -> activate -> connect -> use sockets เหมือนกันทั้งสามกรณี

อินเทอร์เฟซ network adapter ทั่วไป

ส่วนนี้อธิบายคลาสพื้นฐานนามธรรม (โดยนัย) สำหรับคลาสอินเทอร์เฟซเครือข่ายทั้งหมดที่ใช้งานโดย MicroPython ports สำหรับฮาร์ดแวร์ที่แตกต่างกัน ซึ่งหมายความว่า 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

เชื่อมต่ออินเทอร์เฟซกับเครือข่าย เมธอดนี้เป็นทางเลือก และมีให้ใช้เฉพาะกับอินเทอร์เฟซที่ไม่ "เชื่อมต่อตลอดเวลา" หากไม่มีพารามิเตอร์ จะเชื่อมต่อกับบริการเริ่มต้น (หรือบริการเดียว) หากมีพารามิเตอร์เดียว จะเป็นตัวระบุหลักของบริการที่จะเชื่อมต่อ อาจมีคีย์ (รหัสผ่าน) ที่จำเป็นในการเข้าถึงบริการดังกล่าวด้วย อาจมีอาร์กิวเมนต์ keyword-only เพิ่มเติมที่ไม่แน่นอน ขึ้นอยู่กับประเภทสื่อเครือข่ายและ/หรืออุปกรณ์เฉพาะ พารามิเตอร์สามารถใช้เพื่อ: a) ระบุประเภทตัวระบุบริการอื่น; b) ให้พารามิเตอร์การเชื่อมต่อเพิ่มเติม สำหรับประเภทสื่อต่างๆ มีชุดพารามิเตอร์ที่กำหนดไว้ล่วงหน้า/แนะนำที่แตกต่างกัน ในจำนวนนี้ได้แก่:

• WiFi: คีย์เวิร์ด bssid เพื่อเชื่อมต่อกับ BSSID เฉพาะ (ที่อยู่ MAC)

disconnect() → None

ยกเลิกการเชื่อมต่อจากเครือข่าย

isconnected() → bool

คืนค่า True หากเชื่อมต่อกับเครือข่าย ไม่เช่นนั้นคืนค่า False

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

สแกนหาบริการ/การเชื่อมต่อเครือข่ายที่ใช้ได้ คืนค่ารายการ tuple ที่มีพารามิเตอร์บริการที่ค้นพบ สำหรับสื่อเครือข่ายต่างๆ มีรูปแบบ tuple ที่กำหนดไว้ล่วงหน้า/แนะนำที่แตกต่างกัน ในจำนวนนี้ได้แก่:

• WiFi: (ssid, bssid, channel, RSSI, security, hidden) อาจมีฟิลด์เพิ่มเติมที่เฉพาะเจาะจงกับอุปกรณ์นั้นๆ

ฟังก์ชันนี้อาจรับอาร์กิวเมนต์คีย์เวิร์ดเพิ่มเติมเพื่อกรองผลการสแกน (เช่น สแกนหาบริการเฉพาะ บนช่องเฉพาะ สำหรับบริการในชุดเฉพาะ เป็นต้น) และเพื่อส่งผลต่อระยะเวลาการสแกนและพารามิเตอร์อื่นๆ หากเป็นไปได้ ชื่อพารามิเตอร์ควรตรงกับชื่อใน connect()

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

ตรวจสอบข้อมูลสถานะแบบไดนามิกของอินเทอร์เฟซ เมื่อเรียกโดยไม่มีอาร์กิวเมนต์ ค่าที่คืนมาจะอธิบายสถานะลิงก์เครือข่าย มิฉะนั้น param ควรเป็น string ที่ตั้งชื่อพารามิเตอร์สถานะเฉพาะที่ต้องการดึงข้อมูล

ประเภทและค่าที่คืนมาขึ้นอยู่กับสื่อ/เทคโนโลยีเครือข่าย บางพารามิเตอร์ที่อาจรองรับได้แก่:

• WiFi STA: ใช้ 'rssi' เพื่อดึงค่า RSSI ของสัญญาณ AP

• WiFi AP: ใช้ 'stations' เพื่อดึงรายการ STA ทั้งหมดที่เชื่อมต่อกับ AP รายการมี tuple ในรูปแบบ (MAC, RSSI)

ipconfig(param: str) → Any

ipconfig(**kwargs: Any) → None

รับหรือตั้งค่าพารามิเตอร์การกำหนดค่า IP เฉพาะอินเทอร์เฟซ พารามิเตอร์ที่รองรับมีดังต่อไปนี้ (ความพร้อมใช้งานของพารามิเตอร์เฉพาะขึ้นอยู่กับ port และอินเทอร์เฟซเครือข่ายเฉพาะ):

• dhcp4 (True/False) รับที่อยู่ IPv4, gateway และ DNS server ผ่าน DHCP เมธอดนี้ไม่บล็อกและรอให้ได้รับที่อยู่ หากต้องการตรวจสอบว่าได้รับที่อยู่แล้วหรือไม่ ใช้คุณสมบัติอ่านได้อย่างเดียว has_dhcp4

• gw4 รับ/ตั้งค่า IPv4 default-gateway

• dhcp6 (True/False) รับ DNS server ผ่าน stateless DHCPv6 การรับที่อยู่ IP ผ่าน DHCPv6 ยังไม่ได้รับการใช้งานในขณะนี้

• autoconf6 (True/False) รับที่อยู่ IPv6 แบบ stateless ผ่านคำนำหน้าเครือข่ายที่แบ่งปันในประกาศ router หากต้องการตรวจสอบว่าได้รับที่อยู่ stateless แล้วหรือไม่ ใช้คุณสมบัติอ่านได้อย่างเดียว has_autoconf6

• addr4 (เช่น 192.168.0.4/24) รับที่อยู่ IPv4 ปัจจุบันและ network mask เป็น tuple (ip, subnet) โดยไม่คำนึงว่าได้รับที่อยู่นี้มาอย่างไร เมธอดนี้สามารถใช้เพื่อตั้งค่าที่อยู่ IPv4 แบบ static ทั้งแบบ tuple (ip, subnet) หรือในรูปแบบ CIDR

• addr6 (เช่น fe80::1234:5678) รับรายการที่อยู่ IPv6 ปัจจุบันเป็น tuple (ip, state, preferred_lifetime, valid_lifetime) ซึ่งรวมถึงที่อยู่ link-local, slaac และ static preferred_lifetime และ valid_lifetime แทนอายุการใช้งานที่เหลืออยู่ที่ถูกต้องและที่ต้องการของที่อยู่ IPv6 แต่ละรายการ เป็นวินาที state ระบุสถานะปัจจุบันของที่อยู่:

  • 0x08 - 0x0f ระบุว่าที่อยู่นั้นเป็น tentative กำลังนับจำนวน probe ที่ส่งออกไป

  • 0x10 ที่อยู่นั้นเลิกใช้แล้ว (แต่ยังคงถูกต้อง)

  • 0x30 ที่อยู่นั้นอยู่ในสถานะ preferred (และถูกต้อง)

  • 0x40 ที่อยู่นั้นซ้ำกันและไม่สามารถใช้งานได้

  เมธอดนี้สามารถใช้เพื่อตั้งค่าที่อยู่ IPv6 แบบ static โดยการตั้งค่าพารามิเตอร์นี้เป็นที่อยู่ เช่น fe80::1234:5678

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

Note

ฟังก์ชันนี้เลิกใช้แล้ว ใช้ ipconfig() แทน

รับ/ตั้งค่าพารามิเตอร์อินเทอร์เฟซเครือข่ายระดับ IP: ที่อยู่ IP, subnet mask, gateway และ DNS server เมื่อเรียกโดยไม่มีอาร์กิวเมนต์ เมธอดนี้จะคืนค่า 4-tuple ที่มีข้อมูลข้างต้น หากต้องการตั้งค่าข้างต้น ส่ง 4-tuple พร้อมข้อมูลที่ต้องการ ตัวอย่าง:

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()) ซึ่งรวมถึงพารามิเตอร์เฉพาะเครือข่ายและเฉพาะฮาร์ดแวร์ สำหรับการตั้งค่าพารามิเตอร์ ควรใช้ไวยากรณ์อาร์กิวเมนต์คีย์เวิร์ด และสามารถตั้งค่าพารามิเตอร์หลายตัวพร้อมกันได้ สำหรับการสอบถาม ควรใส่ชื่อพารามิเตอร์เป็น string และสามารถสอบถามได้ทีละหนึ่งพารามิเตอร์:

# 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 และให้วิธีควบคุมอินเทอร์เฟซเครือข่ายประเภทต่างๆ

• class WINC -- ไดรเวอร์ WiFi shield
• คลาส WLAN -- ควบคุมอินเทอร์เฟซ WiFi ในตัว
• class LAN -- ควบคุมอินเทอร์เฟซ Ethernet

ฟังก์ชันเครือข่าย

ต่อไปนี้คือฟังก์ชันที่ใช้ได้ในโมดูล network

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

รับหรือตั้งค่ารหัสประเทศ ISO 3166-1 Alpha-2 สองตัวอักษรที่จะใช้สำหรับการปฏิบัติตามข้อกำหนดวิทยุ

หากระบุพารามิเตอร์ code ประเทศจะถูกตั้งค่าเป็นค่านี้ หากเรียกฟังก์ชันโดยไม่มีพารามิเตอร์ จะคืนค่าประเทศปัจจุบัน

รหัสเริ่มต้น "XX" แทนภูมิภาค "worldwide"

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

รับหรือตั้งค่าชื่อโฮสต์ที่จะระบุอุปกรณ์นี้บนเครือข่าย จะถูกใช้โดยอินเทอร์เฟซทั้งหมด

ชื่อโฮสต์นี้ใช้สำหรับ:

• ส่งไปยัง DHCP server ในคำร้องขอของไคลเอนต์ (หากใช้ DHCP)

• ประกาศผ่าน mDNS (หากเปิดใช้งาน)

หากระบุพารามิเตอร์ name ชื่อโฮสต์จะถูกตั้งค่าเป็นค่านี้ หากเรียกฟังก์ชันโดยไม่มีพารามิเตอร์ จะคืนค่าชื่อโฮสต์ปัจจุบัน

การเปลี่ยนแปลงชื่อโฮสต์มักจะถูกนำไปใช้เฉพาะระหว่างการเชื่อมต่อ สำหรับ DHCP นั่นเป็นเพราะชื่อโฮสต์เป็นส่วนหนึ่งของคำร้องขอไคลเอนต์ DHCP และการใช้งาน mDNS ในพอร์ตส่วนใหญ่จะเริ่มต้นชื่อโฮสต์เพียงครั้งเดียวระหว่างการเชื่อมต่อ ด้วยเหตุนี้ คุณต้องตั้งชื่อโฮสต์ก่อนเปิดใช้งาน/เชื่อมต่ออินเทอร์เฟซเครือข่ายของคุณ

ความยาวของชื่อโฮสต์จำกัดอยู่ที่ 32 ตัวอักษร MicroPython ports อาจเลือกตั้งค่าขีดจำกัดที่ต่ำกว่าด้วยเหตุผลด้านหน่วยความจำ หากชื่อที่กำหนดไม่พอดี จะมีการยกข้อผิดพลาด ValueError

ชื่อโฮสต์เริ่มต้นโดยทั่วไปคือชื่อของบอร์ด

network.ipconfig(param: str) → Any

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

รับหรือตั้งค่าพารามิเตอร์การกำหนดค่า IP ทั่วโลก พารามิเตอร์ที่รองรับมีดังต่อไปนี้ (ความพร้อมใช้งานของพารามิเตอร์เฉพาะขึ้นอยู่กับ port และอินเทอร์เฟซเครือข่ายเฉพาะ):

• dns รับ/ตั้งค่า DNS server เมธอดนี้รองรับทั้งที่อยู่ IPv4 และ IPv6

• prefer (4/6) ระบุประเภทที่อยู่ที่จะคืนค่า หากชื่อโดเมนมีทั้งระเบียน A และ AAAA โปรดทราบว่าสิ่งนี้ไม่ได้ล้าง DNS cache ในเครื่อง ดังนั้นที่อยู่ที่ได้รับมาก่อนหน้านี้อาจไม่เปลี่ยนแปลง