lớp WLAN -- điều khiển giao diện WiFi tích hợp¶

Lớp WLAN điều khiển các radio WiFi tích hợp trên các OpenMV Cam hiện đại. Cùng một lớp bao bọc hai trình điều khiển nền tảng khác nhau tùy thuộc vào WiFi MCU của bo mạch:

CYW43 (Mô-đun WiFi Infineon CYW43xxx Murata). Được sử dụng bởi OpenMV Cam N6, OpenMV Cam RT1062, Arduino Portenta H7, Arduino Nicla Vision và Arduino Giga R1 WiFi.
NINA W10 (u-blox NINA-W10 / ESP32-WROOM). Được sử dụng bởi Arduino Nano RP2040 Connect.

Hai trình điều khiển này cung cấp các tên phương thức giống nhau nhưng khác nhau ở một số đối số và tập hợp các khóa config() được chấp nhận. Các điểm khác biệt được đánh dấu bên dưới.

Các OpenMV Cam có shield WiFi WINC1500 cũ (M4 / M7 / H7 / H7 Plus / Pure Thermal) sử dụng WINC thay thế.

Ví dụ sử dụng:

import network

# Enable the station interface and connect to a WiFi AP.
nic = network.WLAN(network.WLAN.IF_STA)
nic.active(True)
nic.connect("your-ssid", "your-key")
while not nic.isconnected():
    pass

print(nic.ipconfig("addr4"))

Các Constructor¶

class network.WLAN(interface_id: int = WLAN.IF_STA) → None¶

Tạo một đối tượng giao diện WLAN.

interface_id chọn giao diện nào để thao tác:

WLAN.IF_STA -- chế độ trạm / client. Kết nối đến điểm truy cập thượng nguồn bằng connect(). Đây là mặc định.

WLAN.IF_AP -- chế độ điểm truy cập. Cấu hình AP bằng config() và chấp nhận kết nối client.

Cùng một radio vật lý hỗ trợ cả hai giao diện; tạo một giao diện không loại trừ giao diện kia.

Các Phương thức¶

active(is_active: bool | None = None) → bool¶

Bật hoặc tắt radio WiFi.

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

active(True) cấp nguồn cho WiFi MCU, tải firmware của nó (CYW43 tải blob firmware từ bộ nhớ flash; NINA xác thực phiên bản firmware hiện đang được flash) và khởi động lwIP netif cho giao diện này. Tất cả các phương thức khác -- connect(), scan(), ipconfig() và các phương thức liên quan -- yêu cầu giao diện phải đang hoạt động.

active(False) tắt nguồn radio. Trên giao diện STA, điều này cũng ngắt kết nối với AP hiện tại và giải phóng netif.

connect(ssid: str, key: str | None = None, *, security: int = -1, bssid: bytes | None = None, channel: int = -1) → None¶

Liên kết giao diện STA với điểm truy cập đã cho.

ssid -- SSID của mạng (chuỗi hoặc bytes).

key -- mật khẩu / khóa chia sẻ trước. Truyền None cho mạng mở.

security (chỉ từ khóa) -- một trong các hằng số SEC_*. -1 (mặc định) tự động chọn: SEC_OPEN khi key rỗng, SEC_WPA_WPA2 nếu không.

bssid (chỉ từ khóa, chỉ CYW43) -- giới hạn liên kết với AP có địa chỉ MAC 6 byte này. Bị bỏ qua bởi trình điều khiển NINA.

channel (chỉ từ khóa) -- kênh radio ưu tiên. Mặc định là "để trình điều khiển tự chọn".

disconnect() → None¶: Trong chế độ STA, ngắt kết nối với điểm truy cập hiện đang liên kết. Giao diện vẫn hoạt động; gọi connect() lại để kết nối lại, hoặc active() (False) để tắt nguồn radio hoàn toàn. Không thực hiện gì khi không có liên kết hiện tại.

isconnected() → bool¶

Trong chế độ STA, trả về True khi đã liên kết với điểm truy cập và địa chỉ IPv4 đã được lấy từ DHCP (hoặc được gán tĩnh qua ipconfig()). Trả về False trong khi liên kết vẫn đang ở giai đoạn xác thực/liên kết/DHCP.

Trong chế độ AP, trả về True khi có ít nhất một trạm đã tham gia.

scan(*, passive: bool = False, ssid: bytes | None = None, bssid: bytes | None = None) → List[Tuple[bytes, bytes, int, int, int, int]]¶

Quét các điểm truy cập lân cận và trả về danh sách các 6-tuple:

[0] SSID (bytes; rỗng cho mạng ẩn).

[1] BSSID (MAC 6 byte, bytes). Chuyển đổi bằng binascii.hexlify().

[2] Số kênh.

[3] RSSI tính bằng dBm.

[4] Chế độ bảo mật (một trong các hằng số SEC_*).

[5] Dành riêng (luôn là 1).

Tất cả các đối số từ khóa chỉ dành cho CYW43:

passive -- nếu là True, sử dụng quét thụ động thay vì quét yêu cầu thăm dò chủ động mặc định.

ssid -- giới hạn quét đến một SSID.

bssid -- giới hạn quét đến một BSSID.

Quét chỉ có ý nghĩa trên giao diện STA.

status() → int¶

status(param: str) → Any

Truy vấn trạng thái kết nối.

Không có đối số, trả về trạng thái liên kết dưới dạng số nguyên nhỏ (mã hóa theo trình điều khiển -- giá trị truthy nghĩa là "đã liên kết").

Với đối số chuỗi:

"rssi" -- trong chế độ STA, trả về RSSI hiện tại tính bằng dBm.

"stations" -- trong chế độ AP, trả về danh sách các trạm đã kết nối. CYW43 trả về [(mac_bytes,), ...]; NINA trả về [ip_string, ...].

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

Lấy hoặc đặt các tham số giao diện IPv4 dưới dạng 4-tuple của các chuỗi dấu chấm (ip, subnet, gateway, dns).

Ghi chú

Ưu tiên sử dụng ipconfig() cho mã mới:

nic.ipconfig(addr4="192.168.0.4/24", gw4="192.168.0.1")
network.ipconfig(dns="8.8.8.8")

ipconfig(param: str) → Any¶
ipconfig(**kwargs: Any) → None: Lấy hoặc đặt các tham số giao diện IPv4 / IPv6. Trình điều khiển CYW43 ủy quyền cho triển khai lwIP tiêu chuẩn và hỗ trợ đầy đủ tập hợp các khóa được ghi lại trên AbstractNIC.ipconfig(). Trình điều khiển NINA triển khai tập hợp con nhỏ hơn theo từng giao diện -- dhcp4 và has_dhcp4 (chỉ đọc), cùng với addr4 và gw4 để lấy / đặt.

config(param: str) → Any¶

config(**kwargs: Any) → None

Lấy hoặc đặt các tham số giao diện đặc thù cho WiFi.

Với một đối số chuỗi vị trí duy nhất, trả về giá trị của tham số đó. Với các đối số từ khóa, đặt một hoặc nhiều tham số cùng lúc -- các thay đổi ảnh hưởng đến AP đang chạy khiến AP tắt và khởi động lại tự động.

Ví dụ:

# Set up the access-point name and channel.
ap.config(ssid="My AP", channel=11)
# Query params one at a time.
print(ap.config("ssid"))
print(ap.config("mac"))

Trình điều khiển CYW43 -- các tham số có thể lấy:

"antenna" -- bộ chọn anten (int).

"channel" -- kênh hiện tại.

"ssid" / "essid" -- SSID hiện tại (chuỗi).

"security" -- chế độ xác thực của AP (một trong SEC_*).

"mac" -- địa chỉ MAC của giao diện (6 bytes).

"pm" -- giá trị quản lý nguồn điện.

"txpower" -- công suất phát tính bằng dBm.

"hostname" -- tên máy chủ DHCP/mDNS. Không dùng nữa; sử dụng network.hostname() thay thế.

Trình điều khiển CYW43 -- các tham số có thể đặt:

antenna=<int> -- bộ chọn anten.

channel=<int> -- kênh AP.

ssid=<str> / essid=<str> -- SSID của AP.

key=<str> / password=<str> -- khóa chia sẻ trước của AP.

security=<int> -- chế độ xác thực của AP (một trong SEC_*).

pm=<int> -- chế độ quản lý nguồn điện (một trong PM_NONE, PM_PERFORMANCE, PM_POWERSAVE).

monitor=<int> -- bật chế độ monitor / all-multicast.

txpower=<int> -- công suất phát tính bằng dBm.

trace=<int> -- bitmask theo dõi nội bộ của trình điều khiển.

hostname=<str> -- tên máy chủ DHCP/mDNS. Không dùng nữa; sử dụng network.hostname() thay thế.

Trình điều khiển NINA -- các tham số có thể lấy:

"ssid" -- SSID hiện tại (chuỗi).

"security" -- chế độ xác thực của AP.

"mac" / "bssid" -- địa chỉ MAC của giao diện (6 bytes).

"fw_version" -- một 3-tuple (major, minor, patch).

Trình điều khiển NINA -- các tham số có thể đặt: lệnh gọi chuyển tiếp đến connect() và chấp nhận các đối số từ khóa tương tự (ssid, key, security, channel). Chỉ hợp lệ trên giao diện AP.

deinit() → None¶: Khởi động lại nguồn WiFi MCU và giải phóng mọi tài nguyên mà trình điều khiển đang giữ (bộ đệm firmware, lwIP netif, bus SPI/SDIO). Sau khi gọi hàm này, đối tượng WLAN phải được xây dựng lại trước khi sử dụng. Sử dụng hàm này thay vì active() (False) khi bạn cần đặt lại hoàn toàn (ví dụ: trước khi flash lại firmware của radio hoặc để khôi phục từ trạng thái trình điều khiển bị treo). Chỉ dành cho CYW43.

send_ethernet(buf: bytes) → None¶: Đưa frame Ethernet thô buf trực tiếp vào đường truyền của trình điều khiển, bỏ qua ngăn xếp IP. Dành cho các consumer chỉ dùng L2 -- bridging, các giao thức EtherType tùy chỉnh, và tương tự. Frame phải bao gồm MAC đích/nguồn và EtherType (không có FCS -- phần cứng thêm vào). Chỉ dành cho CYW43.

ioctl(cmd: int, buf: bytearray) → None¶: Phát lệnh điều khiển đặc thù cho trình điều khiển. cmd là mã ioctl số được xác định bởi firmware radio nền tảng và buf là bộ đệm có thể thay đổi được sử dụng cho cả payload lệnh và phản hồi. Tập hợp các giá trị cmd hợp lệ là đặc thù của trình điều khiển và không thể chuyển đổi giữa CYW43 và NINA. Chủ yếu được sử dụng bởi các tập lệnh kiểm tra cấp thấp và mã khởi động chip.

Các Hằng số¶

IF_STA: int¶: Định danh giao diện trạm / client. Truyền đến constructor để chọn chế độ STA.

IF_AP: int¶: Định danh giao diện điểm truy cập. Truyền đến constructor để chọn chế độ AP.

SEC_OPEN: int¶: Giá trị bảo mật cho mạng không được mã hóa. Có sẵn trên cả hai trình điều khiển.

SEC_WPA_WPA2: int¶: Giá trị bảo mật cho WPA / WPA2 với khóa chia sẻ trước. Mặc định khi cung cấp khóa cho connect(). Có sẵn trên cả hai trình điều khiển.

SEC_WPA3: int¶: Giá trị bảo mật cho WPA3 (SAE) với khóa chia sẻ trước. Chỉ dành cho CYW43.

SEC_WPA2_WPA3: int¶: Giá trị bảo mật cho chế độ chuyển tiếp WPA2 / WPA3. Chỉ dành cho CYW43.

SEC_WEP: int¶: Giá trị bảo mật cho WEP (Wired Equivalent Privacy). Được cung cấp để tương thích với các điểm truy cập cũ -- WEP đã bị phá vỡ về mặt mật mã và không nên được sử dụng trong các triển khai mới. Chỉ dành cho NINA.

OPEN: int¶: Bí danh tương thích ngược cho SEC_OPEN. Mã mới nên sử dụng SEC_OPEN. Chỉ dành cho NINA.

WEP: int¶: Bí danh tương thích ngược cho SEC_WEP. Mã mới nên sử dụng SEC_WEP. Chỉ dành cho NINA.

WPA_PSK: int¶: Bí danh tương thích ngược cho SEC_WPA_WPA2. Mã mới nên sử dụng SEC_WPA_WPA2. Chỉ dành cho NINA.

PM_NONE: int¶: Truyền đến config(pm=...) để tắt quản lý nguồn điện WiFi. Chỉ dành cho CYW43.

PM_PERFORMANCE: int¶: Truyền đến config(pm=...) để bật quản lý nguồn điện WiFi được tối ưu cho hiệu suất. Chỉ dành cho CYW43.

PM_POWERSAVE: int¶: Truyền đến config(pm=...) để bật quản lý nguồn điện WiFi được tối ưu cho thời lượng pin tối đa. Chỉ dành cho CYW43.