class WLAN -- 控制內建 WiFi 介面¶

WLAN 類別用於驅動現代 OpenMV Cam 上的板載 WiFi 無線電。同一個類別會依據板子的 WiFi MCU 包裝兩種不同的底層驅動程式：

CYW43（Infineon CYW43xxx Murata WiFi 模組）。用於 OpenMV Cam N6、OpenMV Cam RT1062、Arduino Portenta H7、Arduino Nicla Vision 與 Arduino Giga R1 WiFi。
NINA W10（u-blox NINA-W10 / ESP32-WROOM）。用於 Arduino Nano RP2040 Connect。

這兩種驅動程式提供相同的方法名稱，但在少數引數與所接受的 config() 鍵集合上有所不同。差異會在下方標示。

使用舊式 WINC1500 WiFi 擴充板（M4 / M7 / H7 / H7 Plus / Pure Thermal）的 OpenMV 相機則改用 WINC。

使用範例:

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

建構式¶

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

建立一個 WLAN 介面物件。

interface_id 用於選擇要操作的介面：

WLAN.IF_STA -- 工作站 / 用戶端模式。使用 connect() 連線至上游存取點。此為預設值。

WLAN.IF_AP -- 存取點模式。使用 config() 設定 AP 並接受用戶端連線。

兩個介面共用同一個實體無線電；建構其中一個並不會排除另一個。

方法¶

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

啟動或關閉 WiFi 無線電。

若不帶引數，則回傳目前的狀態 -- 無線電啟動時為 True，否則為 False。

active(True) 會為 WiFi MCU 供電、載入其韌體（CYW43 從快閃記憶體擷取韌體 blob；NINA 驗證目前已燒錄的韌體版本），並為此介面啟動 lwIP netif。所有其他方法 -- connect()、scan()、ipconfig() 等 -- 都需要介面處於作用中狀態。

active(False) 會將無線電重新關閉電源。在 STA 介面上，這也會與目前的 AP 解除關聯並釋放 netif。

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

將 STA 介面與指定的存取點建立關聯。

ssid -- 網路 SSID（字串或位元組）。

key -- 密碼 / 預先共用金鑰。對於開放網路請傳入 None。

security（僅限關鍵字）-- SEC_* 常數之一。-1（預設值）會自動選擇：當 key 為空時使用 SEC_OPEN，否則使用 SEC_WPA_WPA2。

bssid（僅限關鍵字，僅限 CYW43）-- 將關聯限制在具有此 6 位元組 MAC 位址的 AP。NINA 驅動程式會忽略此項。

channel（僅限關鍵字）-- 偏好的無線電頻道。預設為「讓驅動程式自行選擇」。

disconnect() → None¶: 在 STA 模式下，與目前關聯的存取點解除關聯。介面仍保持作用中；再次呼叫 connect() 以重新關聯，或呼叫 active() (False) 以完全關閉無線電電源。當目前未關聯時，此操作不會有任何作用。

isconnected() → bool¶

在 STA 模式下，當已與存取點關聯且已透過 DHCP 取得 IPv4 位址（或透過 ipconfig() 靜態指派）時回傳 True。當連線仍處於驗證/關聯/DHCP 階段時則回傳 False。

在 AP 模式下，當至少有一個工作站已加入時回傳 True。

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

掃描附近的存取點並回傳一個 6 元組的清單：

[0] SSID（位元組；隱藏網路為空）。

[1] BSSID（6 位元組 MAC，bytes）。使用 binascii.hexlify() 進行轉換。

[2] 頻道號碼。

[3] 以 dBm 為單位的 RSSI。

[4] 安全模式（SEC_* 常數之一）。

[5] 保留（永遠為 1）。

所有關鍵字引數皆僅限 CYW43：

passive -- 若為 True，則使用被動掃描，而非預設的主動探測請求掃描。

ssid -- 將掃描限制在單一 SSID。

bssid -- 將掃描限制在單一 BSSID。

掃描僅在 STA 介面上有意義。

status() → int¶

status(param: str) → Any

查詢連線狀態。

若不帶引數，則以小整數回傳連結狀態（驅動程式特定的編碼 -- 為真值表示「已關聯」）。

帶字串引數時：

"rssi" -- 在 STA 模式下，回傳以 dBm 為單位的目前 RSSI。

"stations" -- 在 AP 模式下，回傳已連線工作站的清單。CYW43 回傳 [(mac_bytes,), ...]；NINA 回傳 [ip_string, ...]。

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

取得或設定 IPv4 介面參數，格式為 (ip, subnet, gateway, dns) 點分四段字串的 4 元組。

備註

新程式碼建議改用 ipconfig():

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: 取得或設定 IPv4 / IPv6 介面參數。CYW43 驅動程式委派給標準 lwIP 實作，並支援 AbstractNIC.ipconfig() 上所記錄的完整鍵集合。NINA 驅動程式則實作一個較小的每介面子集 -- dhcp4 與 has_dhcp4（唯讀），以及用於取得 / 設定的 addr4 與 gw4。

config(param: str) → Any¶

config(**kwargs: Any) → None

取得或設定 WiFi 特定的介面參數。

帶單一位置字串引數時，回傳該參數的值。帶關鍵字引數時，可一次設定一個或多個參數 -- 影響執行中 AP 的變更會使 AP 自動關閉再重新啟動。

範例:

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

CYW43 驅動程式 -- 可取得的參數：

"antenna" -- 天線選擇器（int）。

"channel" -- 目前頻道。

"ssid" / "essid" -- 目前的 SSID（字串）。

"security" -- AP 的驗證模式（SEC_* 之一）。

"mac" -- 介面 MAC 位址（6 個 bytes）。

"pm" -- 電源管理值。

"txpower" -- 以 dBm 為單位的發射功率。

"hostname" -- DHCP/mDNS 主機名稱。已棄用；請改用 network.hostname()。

CYW43 驅動程式 -- 可設定的參數：

antenna=<int> -- 天線選擇器。

channel=<int> -- AP 頻道。

ssid=<str> / essid=<str> -- AP SSID。

key=<str> / password=<str> -- AP 預先共用金鑰。

security=<int> -- AP 驗證模式（SEC_* 之一）。

pm=<int> -- 電源管理模式（PM_NONE、PM_PERFORMANCE、PM_POWERSAVE 之一）。

monitor=<int> -- 啟用監控 / 全多播模式。

txpower=<int> -- 以 dBm 為單位的發射功率。

trace=<int> -- 內部驅動程式追蹤位元遮罩。

hostname=<str> -- DHCP/mDNS 主機名稱。已棄用；請改用 network.hostname()。

NINA 驅動程式 -- 可取得的參數：

"ssid" -- 目前的 SSID（字串）。

"security" -- AP 的驗證模式。

"mac" / "bssid" -- 介面 MAC 位址（6 個 bytes）。

"fw_version" -- 一個 3 元組 (major, minor, patch)。

NINA 驅動程式 -- 可設定的參數： 此呼叫會轉發給 connect()，並接受相同的關鍵字引數（ssid、key、security、channel）。僅在 AP 介面上有效。

deinit() → None¶: 對 WiFi MCU 進行電源循環，並釋放驅動程式持有的每一項資源（韌體緩衝區、lwIP netif、SPI/SDIO 匯流排）。呼叫此方法之後，WLAN 物件必須重新建構後才能使用。當您需要完整重設時（例如在重新燒錄無線電韌體之前，或為了從卡死的驅動程式狀態中復原），請使用此方法而非 active() (False)。僅限 CYW43。

send_ethernet(buf: bytes) → None¶: 將原始乙太網路影格 buf 直接注入驅動程式的傳送路徑，繞過 IP 堆疊。專為僅限 L2 的使用情境設計 -- 橋接、自訂 EtherType 協定及類似用途。影格必須包含目的地/來源 MAC 與 EtherType（不含 FCS -- 硬體會自行附加）。僅限 CYW43。

ioctl(cmd: int, buf: bytearray) → None¶: 發出驅動程式特定的控制命令。cmd 是底層無線電韌體所定義的數值 ioctl 代碼，buf 則是同時用於命令酬載與回應的可變緩衝區。有效的 cmd 值集合是驅動程式特定的，在 CYW43 與 NINA 之間不可移植。主要由低階測試指令碼與晶片啟動程式碼使用。

常數¶

IF_STA: int¶: 工作站 / 用戶端介面識別碼。傳入建構式以選擇 STA 模式。

IF_AP: int¶: 存取點介面識別碼。傳入建構式以選擇 AP 模式。

SEC_OPEN: int¶: 用於未加密網路的安全值。兩種驅動程式皆可用。

SEC_WPA_WPA2: int¶: 用於搭配預先共用金鑰的 WPA / WPA2 的安全值。當有金鑰提供給 connect() 時為預設值。兩種驅動程式皆可用。

SEC_WPA3: int¶: 用於搭配預先共用金鑰的 WPA3（SAE）的安全值。僅限 CYW43。

SEC_WPA2_WPA3: int¶: 用於 WPA2 / WPA3 過渡模式的安全值。僅限 CYW43。

SEC_WEP: int¶: 用於 WEP（Wired Equivalent Privacy）的安全值。為與舊式存取點相容而提供 -- WEP 在密碼學上已被破解，不應在新部署中使用。僅限 NINA。

OPEN: int¶: SEC_OPEN 的回溯相容別名。新程式碼應使用 SEC_OPEN。僅限 NINA。

WEP: int¶: SEC_WEP 的回溯相容別名。新程式碼應使用 SEC_WEP。僅限 NINA。

WPA_PSK: int¶: SEC_WPA_WPA2 的回溯相容別名。新程式碼應使用 SEC_WPA_WPA2。僅限 NINA。

PM_NONE: int¶: 傳入 config(pm=...) 以停用 WiFi 電源管理。僅限 CYW43。

PM_PERFORMANCE: int¶: 傳入 config(pm=...) 以啟用針對效能調校的 WiFi 電源管理。僅限 CYW43。

PM_POWERSAVE: int¶: 傳入 config(pm=...) 以啟用針對最長電池壽命調校的 WiFi 電源管理。僅限 CYW43。