class WINC -- WiFi 扩展板驱动¶

WINC 类驱动 OpenMV WiFi 扩展板上的 Atmel WINC1500 802.11 b/g/n WiFi 模块。可用于 OpenMV Cam M4、M7、H7、H7 Plus 和 Pure Thermal（即 WiFi 扩展板专为其设计的那些 STM32 开发板）。对于内置 WiFi 的开发板（OpenMV Cam N6、OpenMV Cam RT1062、Arduino Giga），请改用 WLAN。

示例 -- 连接到接入点并打印地址:

import network

wlan = network.WINC()
wlan.connect("SSID", "KEY", security=network.WINC.WPA_PSK)

print("status:    ", "connected" if wlan.isconnected() else "off")
print("rssi:      ", wlan.rssi(), "dBm")
print("interface: ", wlan.ifconfig())
print("netinfo:   ", wlan.netinfo())

示例 -- 启动一个开放接入点并等待客户端:

import network

wlan = network.WINC(mode=network.WINC.MODE_AP)
wlan.start_ap("OpenMV-Cam", security=network.WINC.OPEN, channel=6)

print("waiting for a station to associate...")
print(wlan.wait_for_sta(timeout=None))

构造函数¶

class network.WINC(mode: int = WINC.MODE_STA) → None¶

创建一个 WINC 驱动对象并启动 WiFi 扩展板。

mode 选择模块启动时的工作模式：

WINC.MODE_STA -- 站点 / 客户端。使用 connect() 连接到接入点。这是默认值。

WINC.MODE_AP -- 接入点。使用 start_ap() 配置 AP，然后接受客户端连接。

WINC.MODE_P2P -- WiFi Direct。

WINC.MODE_BSP -- 仅启动 BSP（不启用射频）。

WINC.MODE_FIRMWARE -- 固件更新模式；fw_dump() 和 fw_update() 需要此模式。

备注

在 AP 模式下，WINC1500 存在硬件限制：

同一时间只能连接一个客户端。
仅支持 OPEN 或 WEP 安全模式。
WiFi 模块固件存在一个 bug，当客户端断开连接时会导致任何已绑定的套接字停止工作。请为服务器套接字设置超时，使其抛出一个异常，你可以借此重新打开它。

方法¶

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

启用或停用 WiFi 扩展板。

无参数时，返回当前状态 -- 扩展板已初始化且射频已启动时为 True，否则为 False。

active(True) 通过 SPI 执行 WINC1500 固件握手，并以所配置的 mode 启动射频。如果接口已处于激活状态，则为无操作。connect() 在尚未调用本方法时会自动调用它；对于任何其他方法（scan()、rssi()、netinfo()，……），你必须先调用 active(True)。

active(False) 重新关闭射频（WINC 降至仅 BSP 模式）并释放 SPI 引脚。

connect(ssid: str, key: str | None = None, *, security: int = WINC.WPA_PSK, channel: int = 1) → None¶

在射频信道 channel 上，使用密码 key 和安全模式 security（OPEN、WPA_PSK 或 802.1X 常量之一）与 WiFi 网络 ssid 建立关联。security 和 channel 为仅关键字参数。

连接后，使用 socket 模块打开 TCP/UDP 端口。

本方法会阻塞，直到关联完成或失败。

config(ssid: str, key: str | None = None, *, security: int = WINC.WPA_PSK, channel: int = 1) → None¶: connect() 的别名。提供它是为了与在其他 network 接口上调用 config 的代码兼容。

start_ap(ssid: str, key: str | None = None, *, security: int = WINC.OPEN, channel: int = 1) → None¶: connect() 的别名，在以 mode=MODE_AP 构造对象后使用，用于配置并启动接入点。AP 仅支持 OPEN 或 WEP 安全模式；如果使用 WEP，则 key 为必填项。

disconnect() → None¶: 在 STA 模式下，与当前关联的接入点解除关联。扩展板保持激活；调用 connect() 可重新关联。当前未关联时为无操作。

isconnected() → bool¶: 在 STA 模式下，当已与接入点关联且已获得 IPv4 地址（通过 DHCP 或 ifconfig()）时返回 True。在仍处于认证 / 关联 / DHCP 阶段时返回 False。

connected_sta() → List[str]¶: 在 AP 模式下，返回一个包含当前已连接客户端 IP 地址的列表（若无客户端连接则为空列表）。

wait_for_sta(timeout: int | None) → List[str]¶: 在 AP 模式下，阻塞直到有客户端连接，并返回一个包含该客户端 IP 地址的列表。timeout 是以毫秒为单位的最长等待时间；传入 None 表示无限期等待。

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

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

无参数调用时：返回当前配置。

传入四元组调用时：设置一个静态 IP 配置，取代通过 DHCP 获取的配置。

示例 -- 在连接前固定一个静态 IP:

wlan = network.WINC()
wlan.ifconfig(("192.168.1.100", "255.255.255.0",
               "192.168.1.1", "192.168.1.1"))
wlan.connect(SSID, key=KEY, security=network.WINC.WPA_PSK)

备注

WINC 不实现现代的 AbstractNIC.ipconfig() API；此处请使用 ifconfig()。

netinfo() → Tuple[int, int, str, str, str]¶

返回一个描述当前关联的五元组：

[0] RSSI，为整数（dBm）。

[1] 安全模式 -- 安全常量之一。

[2] SSID 字符串。

[3] BSSID，为 "XX:XX:XX:XX:XX:XX" 形式的 MAC 字符串。

[4] IPv4 地址，为点分四段字符串。

scan() → List[Tuple[str, str, int, int, int, int]]¶

扫描附近的接入点。返回一个六元组的列表：

[0] SSID 字符串。

[1] BSSID，为 "XX:XX:XX:XX:XX:XX" 形式的 MAC 字符串。

[2] 信道号。

[3] RSSI，单位 dBm。

[4] 安全模式 -- 安全常量之一。

[5] 保留（始终为 1）。

可以在未先与网络关联的情况下调用。

rssi() → int¶: 返回当前关联接入点的 RSSI，单位 dBm。大致而言：-30 为极佳，-67 对流式传输尚可，-80 为勉强，-90 及以下则无法使用。仅在 STA 模式下且 isconnected() 为 True 时有意义。

fw_version() → Tuple[int, int, int, int, int, int, int]¶

返回一个描述 WINC1500 固件和驱动版本的七元组：

[0] 固件主版本号。

[1] 固件次版本号。

[2] 固件补丁号。

[3] 驱动主版本号。

[4] 驱动次版本号。

[5] 驱动补丁号。

[6] 芯片硬件修订版。

fw_dump(path: str) → None¶

读取 WINC1500 的内部闪存，并将得到的固件镜像写入 OpenMV 文件系统上 path 处的文件。在调用 fw_update() 之前，可用此方法备份当前已安装的镜像。

要求模块以 mode=MODE_FIRMWARE 构造。

fw_update(path: str) → None¶

擦除 WINC1500 的内部闪存，并用 path 处的二进制镜像对其进行编程。镜像必须符合 OpenMV 固件所期望的布局（通常由 Atmel / Microchip 随 WINC SDK 提供）。

在闪存编程和校验期间，该调用会阻塞数秒。调用返回后，请对 OpenMV Cam 进行电源重启，以便 WINC1500 从新镜像启动。

要求模块以 mode=MODE_FIRMWARE 构造。

常量¶

OPEN: int¶: 用于未加密网络的安全值。传给 connect() / start_ap() 的 security 参数。

WPA_PSK: int¶: 用于使用预共享密钥的 WPA/WPA2 的安全值。connect() 的默认值。

备注

还存在一个 WPA/WPA2 企业版（802.1X）安全值。固件以 802_1X 这个名称暴露它，而这不是一个有效的 Python 标识符 -- 请通过 getattr(network.WINC, "802_1X") 访问它。

MODE_STA: int¶: 站点模式 -- 作为客户端连接到接入点。默认的构造函数模式。

MODE_AP: int¶: 接入点模式 -- WINC 成为客户端与之关联的 AP。

MODE_P2P: int¶: WiFi-Direct（点对点）模式。

MODE_BSP: int¶: 仅初始化 WINC 板级支持包 -- 射频不会被启动。由固件更新流程使用。

MODE_FIRMWARE: int¶: 固件更新模式。fw_dump() 和 fw_update() 需要此模式。