Wi-Fi 驱动与设备选择#

概述#

CanMV 的 network.WLAN 建立在 RT-Smart WLAN 和 NetMgmt 之上。当前 SDK 包含 Realtek RTL8189FTV/RTL8733BS、CYW43xx/AP6212、RW007、AIC8800 系列以及 ESP-Hosted 驱动。Python API 不直接调用厂商驱动，而是按 USB、SDIO 或 SPI 传输类型选择已注册的物理射频。

是否能直接使用某个方案取决于目标板固件的 defconfig、接口接线、模组型号和协处理器固件。标准固件未启用的驱动需要自定义构建。

警告

当前发布的 K230D 标准固件不支持网络功能。本页的 K230D 相关使用场景属于自定义板级和驱动适配范围，不能直接套用标准固件。

支持方案#

方案	传输	CanMV 能力	注册型号
RTL8189FTV	SDIO	2.4 GHz Wi-Fi 4，STA、SoftAP	`rtl8189ftv`
RTL8733BS	SDIO	支持 5 GHz 的 Wi-Fi 4，STA、SoftAP	`rtl8733bs`
CYW43438/AP6212	SDIO	2.4 GHz Wi-Fi 4，STA、SoftAP	`cyw43438`
RW007	SPI Mode 0	STA、SoftAP	`rw007`
AIC8800/AIC8801、D80/D40/D80X2/DC/DW	USB；部分型号支持 SDIO	STA、SoftAP；USB 组合设备可选 BLE HCI	AIC 具体型号
ESP-Hosted-FG	SPI Full-Duplex、SDIO	ESP 固件管理连接和 WPA	`esp-hosted-fg`
ESP-Hosted-NG	SPI Full-Duplex、SDIO	主机认证路径，可提供 WLAN offload 控制设备	`esp-hosted-ng`
ESP-Hosted-MCU	SPI Full-Duplex、Dual/Quad SPI Half-Duplex	RPC Wi-Fi，可选 BLE HCI	`esp-hosted-mcu`

ESP-Hosted-FG、NG 和 MCU 的 wire protocol 不兼容。主机驱动必须与 ESP 端烧录的 firmware personality 一致。ESP-Hosted-MCU 当前没有 RT-Smart SDIO backend。

CYW43xx 端口虽然来自支持 Bluetooth 的上游驱动，但当前 AP6212 集成将 CYW43_ENABLE_BLUETOOTH 设为 0，不能作为 CanMV NimBLE controller。BLE 的配置和使用见 NimBLE 低功耗蓝牙。

默认板级配置#

当前源码中：

k230_canmv_defconfig 已启用 CYW43xx/AP6212 和 Realtek SDIO；
多数带板载 SDIO Wi-Fi 的 CanMV defconfig 已启用 Realtek，默认选择 RTL8189FTV；使用 RTL8733BS 时需要更改 Realtek module 选项；
k230_canmv_rtt_evb_defconfig 已启用 RW007；
k230_canmv_01studio_defconfig 已启用 AIC8800 USB 和 SDIO；
k230_canmv_01studio_emmc_defconfig 已启用 AIC8800 USB；
k230_canmv_lckfb_defconfig 已启用 AIC8800 USB；
ESP-Hosted 需要按实际接线在自定义固件中启用。

板级默认值只说明构建配置，不能替代硬件核对。同一 SDIO 插槽可以同时编译多个厂商驱动，运行时按 SDIO manufacturer/product ID 匹配；但 Realtek 驱动内部一次只能选择 RTL8189FTV 或 RTL8733BS 中的一种。

AIC 固件由 manifest 中的独立子仓库提供。执行 repo sync 后，应存在：

src/rtsmart/rtsmart/kernel/bsp/maix3/drivers/extdrv/aic8800/firmware/

构建系统会把所需文件安装到镜像的 /bin/firmware。这些二进制具有独立的 vendor 许可条款。

自定义固件配置#

先按自定义固件选择板级配置，再运行 make rtsmart-menuconfig 或对应的容器命令。

SDIO 公共板级配置#

Realtek、CYW43xx、AIC8800 SDIO 和 ESP-Hosted SDIO 共用以下板级设置：

BSP_WIFI_SDIO_HOST_0=y              # 或 BSP_WIFI_SDIO_HOST_1
BSP_WIFI_SDIO_REG_ON_PIN=<gpio>     # -1 表示使用板级固定接线
BSP_WIFI_SDIO_RESET_ACTIVE_LOW=y
BSP_WIFI_SDIO_RESET_PULSE_MS=200
BSP_WIFI_SDIO_POWER_UP_DELAY_MS=50

选择的 host 必须已启用对应的 RT_USING_SDIO0 或 RT_USING_SDIO1。REG_ON、复位有效电平和上电延时必须按原理图及模组手册设置。

Realtek RTL8189FTV/RTL8733BS#

启用 RT_USING_REALTEK，并且在 Realtek module 选项中二选一：

REALTEK_SDIO_RTL8189FTV=y
# REALTEK_SDIO_RTL8733BS=y

RTL8189FTV 的 SDIO ID 为 024c:f179，RTL8733BS 为 024c:b733。驱动按 ID 绑定设备；选错模块时即使 SDIO 总线发现了卡也不会注册 WLAN。调试命令和驱动日志可分别通过 REALTEK_INTERACTIVE_CMD 和 REALTEK_ENABLE_DEBUG 启用。

CYW43xx/AP6212#

启用：

RT_USING_CYW43XX=y

当前端口按 02d0:a9a6 匹配 CYW43438/AP6212，并在驱动中内置 Wi-Fi firmware 和 NVRAM。CYW43XX_THREAD_PRIORITY 与 CYW43XX_THREAD_STACK_SIZE 可用于调整工作线程。此端口当前只启用 Wi-Fi，不启用 CYW43xx Bluetooth。

RW007#

启用 RT_USING_RW007，并按板级接线配置：

RW007_SPI_BUS_NAME="spi0"
RW007_SPI_MAX_HZ=25000000
RW007_RST_PIN=20
RW007_CS_PIN=63
RW007_INT_BUSY_PIN=62

驱动使用 SPI Mode 0、8-bit、单数据线，并把从设备挂载为 wspi。上面的 GPIO 只是 Kconfig 默认值，移植到其他板卡时必须核对 Reset、CS 和 INT/BUSY 引脚。

AIC8800#

启用：

RT_USING_AIC8800_WIFI=y
AIC8800_WIFI_TRANSPORT_USB=y        # USB 网卡
AIC8800_WIFI_TRANSPORT_SDIO=y       # SDIO 模组，可与 USB 同时启用

2.4 GHz-only 模组应关闭 AIC8800_WIFI_5GHZ。AIC8800D40L 与 D80 可能使用相同 USB ID，D40L 必须启用 AIC8800_WIFI_USB_LIMIT_40MHZ。USB BLE 需要 AIC8800_WIFI_BLE，同时 CanMV 顶层还需启用 ENABLE_BLUETOOTH。

ESP-Hosted-FG/NG#

启用 RT_USING_ESP_HOSTED_WIFI，选择 FG 或 NG，再选择 SPI Full-Duplex 或 SDIO。SPI mode、频率、checksum、Handshake/Data Ready 电平及引脚必须与 ESP 固件一致。SDIO 还需填写从机实际发布的 manufacturer/product ID。当前 FG/NG 端口不向 CanMV 注册 BLE HCI controller。

ESP-Hosted-MCU#

启用 RT_USING_ESP_HOSTED_MCU，选择 SPI Full-Duplex 或 SPI Half-Duplex。 Half-Duplex 使用 2/4 条双向数据线，不支持 1-line 模式。启用 ESP_HOSTED_BLE 后，再启用 CanMV ENABLE_BLUETOOTH，MicroPython NimBLE 才能使用动态注册的 /dev/hciN controller。

所有 ESP-Hosted 方案都应优先连接可控 Reset。Reset 未连接时，只重启 K230 或 ESP 一端可能使 transport session 不同步。

Python 设备选择#

构造 network.WLAN 时第二个参数选择传输：

import network

auto_sta = network.WLAN(network.STA_IF, network.WLAN_AUTO)
usb_sta = network.WLAN(network.STA_IF, network.WLAN_USB)
sdio_sta = network.WLAN(network.STA_IF, network.WLAN_SDIO)
spi_ap = network.WLAN(network.AP_IF, network.WLAN_SPI)

对应常量：

常量	传输和适用驱动
`network.WLAN_AUTO`	保持当前可用射频，否则按 SDIO、SPI、USB 选择
`network.WLAN_USB`	AIC8800 USB
`network.WLAN_SDIO`	RTL8189FTV、RTL8733BS、CYW43438/AP6212、AIC8800、ESP-Hosted-FG/NG
`network.WLAN_SPI`	RW007、ESP-Hosted-FG/NG/MCU

该参数选择传输类型，不选择 vendor model。通常使用 WLAN_AUTO；只有多块 Wi-Fi 同时存在且应用确实依赖某条总线时才固定类型。当前 Python API 不能区分同一传输上同时存在的两个不同型号。

连接并查询动态 netdev：

import network
import time

sta = network.WLAN(network.STA_IF, network.WLAN_AUTO)
if not sta.active(True):
    raise RuntimeError("Wi-Fi device unavailable")

sta.connect("TEST", "12345678")
deadline = time.time() + 20
while not sta.isconnected() and time.time() < deadline:
    time.sleep_ms(200)

print(network.get_dev_list())
print(sta.netdev_name())
print(sta.ifconfig())

网卡名通常是 wlanN/wlanNap，但 N 由探测顺序决定。不要在脚本中写死 wlan0。

安全模式限制#

Realtek、CYW43xx 和 RW007 的安全模式取决于厂商驱动及模组 firmware；切换模组时应重新验证扫描、STA 加密连接和 SoftAP。
AIC8800 STA 的普通 WPA/WPA2 Personal 可由内置认证路径完成；受限 WPA3-SAE 使用 group 19，不支持 SAE H2E 和 Enterprise/802.1X。
AIC8800 SoftAP 支持开放网络和 WPA2-PSK/CCMP，不支持 WPA3、Enterprise、WPS、 DFS/CAC 或动态 VLAN。
ESP-Hosted-FG 的实际安全能力由 ESP firmware 提供。
ESP-Hosted-NG 可使用内置普通 WPA/WPA2 STA 和开放/WPA2 SoftAP 路径；其他安全模式需要完整用户态 supplicant。
ESP-Hosted-MCU 的实际能力取决于 ESP 芯片、ESP-IDF 和从机编译配置。

验证与排错#

network.get_dev_list() 没有 WLAN：检查固件是否启用对应驱动、接口供电、 SDIO host/REG_ON、RW007 SPI 引脚、AIC firmware 文件或 ESP transport ready 日志。
Realtek 未注册：核对 SDIO ID，并确认选择的是 RTL8189FTV 还是 RTL8733BS。
RW007 未注册：核对 SPI bus、Mode 0、最大频率、CS、Reset 和 INT/BUSY。
active(True) 返回 False：指定传输当前没有可用设备，先改为 network.WLAN_AUTO。
AIC D40 连接速率异常：检查 AIC8800_WIFI_USB_LIMIT_40MHZ。
ESP 无法初始化：优先核对 firmware personality、SPI mode、checksum、引脚和 HS/DR 有效电平。
已关联但不能访问网络：先检查 ifconfig() 是否取得非零 IP 和网关，再测试局域网网关，最后排查 DNS 和公网。

Python 接口和完整示例分别见 network 模块 API 和无线网例程。

Wi-Fi 驱动与设备选择

目录

Wi-Fi 驱动与设备选择#

概述#

支持方案#

默认板级配置#

自定义固件配置#

SDIO 公共板级配置#

Realtek RTL8189FTV/RTL8733BS#

CYW43xx/AP6212#

RW007#

AIC8800#

ESP-Hosted-FG/NG#

ESP-Hosted-MCU#

Python 设备选择#

安全模式限制#

验证与排错#