network --- cấu hình mạng

Mô-đun này cung cấp các trình điều khiển mạng và cấu hình định tuyến. Để sử dụng mô-đun này, cần phải cài đặt phiên bản/bản dựng MicroPython có khả năng mạng. Các trình điều khiển mạng cho phần cứng cụ thể có sẵn trong mô-đun này và được sử dụng để cấu hình (các) giao diện mạng phần cứng. Các dịch vụ mạng được cung cấp bởi các giao diện được cấu hình sau đó có thể sử dụng thông qua mô-đun socket.

Ví dụ:

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

Thay WLAN bằng WINC (shield WiFi cũ) hoặc LAN (Ethernet tích hợp) tùy theo cam. Mẫu cấp cao gồm tạo -> kích hoạt -> kết nối -> sử dụng socket là giống nhau trong cả ba trường hợp.

Giao diện adapter mạng chung

Phần này mô tả một lớp cơ sở trừu tượng (ngầm định) cho tất cả các lớp giao diện mạng được triển khai bởi các cổng MicroPython cho các phần cứng khác nhau. Điều này có nghĩa là MicroPython thực sự không cung cấp lớp AbstractNIC, nhưng bất kỳ lớp NIC thực tế nào, như được mô tả trong các phần sau, đều triển khai các phương thức như được mô tả ở đây.

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

Khởi tạo một đối tượng giao diện mạng. Các tham số phụ thuộc vào giao diện mạng. Nếu có nhiều hơn một giao diện cùng loại, tham số đầu tiên phải là id.

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

Bật hoặc tắt giao diện mạng.

Không có đối số, trả về trạng thái hiện tại -- True khi giao diện đang hoạt động, False nếu không.

Truyền True để kích hoạt giao diện: bật nguồn / đặt lại bộ điều khiển mạng nền tảng, tải firmware khi áp dụng, và khởi động ngăn xếp IP trên giao diện này. Các lệnh gọi tiếp theo giao tiếp với mạng (connect(), scan(), ipconfig(), ...) yêu cầu giao diện phải đang hoạt động.

Truyền False để hủy kích hoạt giao diện: tắt ngăn xếp IP và giải phóng tài nguyên trình điều khiển. Trên các giao diện không dây, điều này cũng ngắt kết nối với bất kỳ mạng nào đang kết nối hiện tại.

Hành vi khi gọi các phương thức khác trên giao diện không hoạt động là không xác định.

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

Kết nối giao diện với mạng. Phương thức này là tùy chọn và chỉ có sẵn cho các giao diện không "luôn kết nối". Nếu không có tham số nào được cung cấp, kết nối với dịch vụ mặc định (hoặc duy nhất). Nếu một tham số duy nhất được cung cấp, đó là định danh chính của dịch vụ cần kết nối. Nó có thể đi kèm với một khóa (mật khẩu) cần thiết để truy cập dịch vụ đó. Có thể có thêm các tham số chỉ từ khóa tùy ý, tùy thuộc vào loại phương tiện mạng và/hoặc thiết bị cụ thể. Các tham số có thể được sử dụng để: a) chỉ định các loại định danh dịch vụ thay thế; b) cung cấp các tham số kết nối bổ sung. Đối với các loại phương tiện khác nhau, có các tập hợp tham số được xác định trước/khuyến nghị khác nhau, trong số đó:

• WiFi: từ khóa bssid để kết nối với BSSID cụ thể (địa chỉ MAC)

disconnect() → None

Ngắt kết nối khỏi mạng.

isconnected() → bool

Trả về True nếu đã kết nối với mạng, ngược lại trả về False.

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

Quét các dịch vụ/kết nối mạng có sẵn. Trả về danh sách các tuple với các tham số dịch vụ được phát hiện. Đối với các phương tiện mạng khác nhau, có các biến thể khác nhau của định dạng tuple được xác định trước/khuyến nghị, trong số đó:

• WiFi: (ssid, bssid, channel, RSSI, security, hidden). Có thể có thêm các trường, đặc thù cho một thiết bị cụ thể.

Hàm có thể chấp nhận các đối số từ khóa bổ sung để lọc kết quả quét (ví dụ: quét một dịch vụ cụ thể, trên một kênh cụ thể, cho các dịch vụ của một tập hợp cụ thể, v.v.), và để ảnh hưởng đến thời gian quét và các tham số khác. Khi có thể, tên tham số nên khớp với những tên trong connect().

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

Truy vấn thông tin trạng thái động của giao diện. Khi được gọi không có đối số, giá trị trả về mô tả trạng thái liên kết mạng. Ngược lại, param phải là chuỗi đặt tên cho tham số trạng thái cụ thể cần lấy.

Các loại và giá trị trả về phụ thuộc vào phương tiện/công nghệ mạng. Một số tham số có thể được hỗ trợ là:

• WiFi STA: sử dụng 'rssi' để lấy RSSI của tín hiệu AP

• WiFi AP: sử dụng 'stations' để lấy danh sách tất cả các STA đã kết nối với AP. Danh sách chứa các tuple có dạng (MAC, RSSI).

ipconfig(param: str) → Any

ipconfig(**kwargs: Any) → None

Lấy hoặc đặt các tham số cấu hình IP theo giao diện. Các tham số được hỗ trợ như sau (sự khả dụng của một tham số cụ thể phụ thuộc vào cổng và giao diện mạng cụ thể):

• dhcp4 (True/False) lấy địa chỉ IPv4, gateway và máy chủ dns qua DHCP. Phương thức này không chặn và chờ địa chỉ được lấy. Để kiểm tra xem địa chỉ đã được lấy chưa, sử dụng thuộc tính chỉ đọc has_dhcp4.

• gw4 Lấy/đặt gateway mặc định IPv4.

• dhcp6 (True/False) lấy máy chủ DNS qua DHCPv6 không trạng thái. Việc lấy địa chỉ IP qua DHCPv6 hiện chưa được triển khai.

• autoconf6 (True/False) lấy địa chỉ IPv6 không trạng thái qua tiền tố mạng được chia sẻ trong các thông báo quảng cáo bộ định tuyến. Để kiểm tra xem địa chỉ không trạng thái đã được lấy chưa, sử dụng thuộc tính chỉ đọc has_autoconf6.

• addr4 (ví dụ: 192.168.0.4/24) lấy địa chỉ IPv4 hiện tại và mặt nạ mạng dưới dạng tuple (ip, subnet), bất kể địa chỉ này được lấy như thế nào. Phương thức này có thể được sử dụng để đặt địa chỉ IPv4 tĩnh dưới dạng tuple (ip, subnet) hoặc theo ký hiệu CIDR.

• addr6 (ví dụ: fe80::1234:5678) lấy danh sách các địa chỉ IPv6 hiện tại dưới dạng tuple (ip, state, preferred_lifetime, valid_lifetime). Bao gồm các địa chỉ link-local, slaac và tĩnh. preferred_lifetime và valid_lifetime biểu thị thời gian hợp lệ và ưu tiên còn lại của mỗi địa chỉ IPv6, tính bằng giây. state cho biết trạng thái hiện tại của địa chỉ:

  • 0x08 - 0x0f cho biết địa chỉ đang ở trạng thái tentative, đếm số lần thăm dò đã gửi.

  • 0x10 Địa chỉ đã bị loại bỏ (nhưng vẫn hợp lệ)

  • 0x30 Địa chỉ được ưu tiên (và hợp lệ)

  • 0x40 Địa chỉ bị trùng lặp và không thể sử dụng.

  Phương thức này có thể được sử dụng để đặt địa chỉ IPv6 tĩnh, bằng cách đặt tham số này thành địa chỉ, như fe80::1234:5678.

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

Ghi chú

Hàm này đã lỗi thời, hãy sử dụng ipconfig() thay thế.

Lấy/đặt các tham số giao diện mạng cấp IP: địa chỉ IP, mặt nạ mạng con, gateway và máy chủ DNS. Khi được gọi không có đối số, phương thức này trả về một 4-tuple với thông tin trên. Để đặt các giá trị trên, truyền một 4-tuple với thông tin cần thiết. Ví dụ:

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

Lấy hoặc đặt các tham số giao diện mạng tổng quát. Các phương thức này cho phép làm việc với các tham số bổ sung ngoài cấu hình IP tiêu chuẩn (như được xử lý bởi ipconfig()). Bao gồm các tham số đặc thù cho mạng và đặc thù cho phần cứng. Để đặt các tham số, cú pháp đối số từ khóa nên được sử dụng và có thể đặt nhiều tham số cùng một lúc. Để truy vấn, tên tham số phải được đặt trong dấu ngoặc kép như chuỗi và chỉ có thể truy vấn một tham số mỗi lần:

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

Các triển khai lớp mạng cụ thể

Các lớp cụ thể sau đây triển khai giao diện AbstractNIC và cung cấp cách điều khiển các giao diện mạng của nhiều loại khác nhau.

• class WINC -- trình điều khiển shield WiFi
• lớp WLAN -- điều khiển giao diện WiFi tích hợp
• class LAN -- điều khiển giao diện Ethernet

Các hàm mạng

Sau đây là các hàm có sẵn trong mô-đun network.

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

Lấy hoặc đặt mã quốc gia ISO 3166-1 Alpha-2 gồm hai chữ cái được sử dụng cho sự tuân thủ radio.

Nếu tham số code được cung cấp, quốc gia sẽ được đặt thành giá trị này. Nếu hàm được gọi không có tham số, nó trả về quốc gia hiện tại.

Mã mặc định "XX" đại diện cho vùng "toàn thế giới".

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

Lấy hoặc đặt tên máy chủ sẽ nhận dạng thiết bị này trên mạng. Nó sẽ được sử dụng bởi tất cả các giao diện.

Tên máy chủ này được sử dụng cho:

• Gửi đến máy chủ DHCP trong yêu cầu client. (Nếu sử dụng DHCP)

• Phát sóng qua mDNS. (Nếu được bật)

Nếu tham số name được cung cấp, tên máy chủ sẽ được đặt thành giá trị này. Nếu hàm được gọi không có tham số, nó trả về tên máy chủ hiện tại.

Thay đổi tên máy chủ thường chỉ được áp dụng trong quá trình kết nối. Đối với DHCP, điều này là do tên máy chủ là một phần của yêu cầu client DHCP, và việc triển khai mDNS trong hầu hết các cổng chỉ khởi tạo tên máy chủ một lần trong quá trình kết nối. Vì lý do này, bạn phải đặt tên máy chủ trước khi kích hoạt/kết nối các giao diện mạng của mình.

Độ dài của tên máy chủ bị giới hạn ở 32 ký tự. Các cổng MicroPython có thể chọn đặt giới hạn thấp hơn vì lý do bộ nhớ. Nếu tên đã cho không phù hợp, sẽ xuất hiện lỗi ValueError.

Tên máy chủ mặc định thường là tên của bo mạch.

network.ipconfig(param: str) → Any

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

Lấy hoặc đặt các tham số cấu hình IP toàn cục. Các tham số được hỗ trợ như sau (sự khả dụng của một tham số cụ thể phụ thuộc vào cổng và giao diện mạng cụ thể):

• dns Lấy/đặt máy chủ DNS. Phương thức này có thể hỗ trợ cả địa chỉ IPv4 và IPv6.

• prefer (4/6) Chỉ định loại địa chỉ nào sẽ được trả về, nếu tên miền có cả bản ghi A và AAAA. Lưu ý rằng điều này không xóa bộ nhớ đệm DNS cục bộ, vì vậy bất kỳ địa chỉ nào đã được lấy trước đó có thể không thay đổi.