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 扩展板的 OpenMV 摄像头（M4 / M7 / H7 / H7 Plus / Pure Thermal）改用 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 —— station / 客户端模式。使用 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 获取（或通过 ipconfig() 静态分配）到 IPv4 地址时返回 True。当链路仍处于认证 / 关联 / DHCP 阶段时返回 False。

在 AP 模式下，当至少有一个 station 加入时返回 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 模式下，返回已连接 station 的列表。CYW43 返回 [(mac_bytes,), ...]；NINA 返回 [ip_string, ...]。

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

以 (ip, subnet, gateway, dns) 点分四段字符串组成的 4 元组形式获取或设置 IPv4 接口参数。

备注

新代码建议优先使用 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¶: Station / 客户端接口标识符。传给构造函数以选择 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（有线等效保密）的安全值。提供此项是为了兼容旧式接入点 —— 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。