ESP-Hosted Wi-Fi 协处理器使用指南#

ESP-Hosted 驱动可以把 ESP32 系列芯片作为 K230/K230D 的 Wi-Fi 协处理器使用。K230 通过 SPI 与运行 ESP-Hosted-MCU 从机固件的 ESP 芯片通信，驱动向 RT-Thread WLAN 和 lwIP 注册 STA、SoftAP 两个网络接口。

当前移植基于 ESP-Hosted-MCU 2.12.x，支持 SPI Full-Duplex 和 SPI Half-Duplex 传输。Half-Duplex 使用硬件 Dual/Quad SPI，支持 2 或 4 条数据线，不支持 1 条数据线模式。已验证的全双工从机固件版本为 2.12.11。K230 侧不依赖 ESP-IDF，仅需要在 ESP 芯片侧编译和烧录 ESP-Hosted-MCU 从机固件。

功能范围#

当前 RT-Smart 移植支持以下功能：

STA 和 SoftAP 模式，以及 STA 与 SoftAP 并发
阻塞式 Wi-Fi 扫描
STA 连接、断开和状态查询
SoftAP 启动、停止和已连接终端查询
SoftAP 主动断开指定终端
RSSI、信道、MAC 地址和 Wi-Fi 省电配置
RT-Thread 国家枚举与 ESP 两字符国家码转换
通过 lwIP 收发以太网帧
Bluetooth H:4 控制器接口；CanMV 可使用 NimBLE 提供 BLE Central、Peripheral、GAP、GATT、L2CAP 和 SMP

当前不支持以下 ESP-Hosted 功能：

SDIO 和 UART 传输
Wi-Fi 混杂模式

RT-Smart 不重新实现 BLE 协议栈。内核只提供可复用的 H:4 HCI 设备层，ESP-Hosted、后续 USB Bluetooth 或其他控制器驱动均可注册到该层；GAP、GATT、ATT、L2CAP 和 SMP 使用经过验证的 NimBLE host stack。

硬件连接#

SPI Full-Duplex 使用 D0/MOSI 和 D1/MISO，并额外使用 HS、DR 两个控制信号：

主机和 ESP 从机之间需要连接以下信号，并确保两块板共地、电平兼容：

K230 主机信号	ESP 从机信号	方向
SPI CLK	SPI CLK	K230 到 ESP
SPI D0/MOSI	SPI MOSI	K230 到 ESP
SPI D1/MISO	SPI MISO	ESP 到 K230
CS	SPI CS	K230 到 ESP
HS	Handshake	ESP 到 K230
DR	Data Ready	ESP 到 K230
RESET	ESP EN 或从机复位 GPIO	K230 到 ESP

SPI Half-Duplex 不使用 HS。D0、D1 在 Dual SPI 中双向传输；Quad SPI 还需要 D2、D3：

K230 主机信号	ESP 从机信号	方向
SPI CLK	SPI-HD CLK	K230 到 ESP
SPI D0-D1	SPI-HD D0-D1	双向
SPI D2-D3	SPI-HD D2-D3	双向，仅 Quad SPI
CS	SPI-HD CS	K230 到 ESP
DR	Data Ready	ESP 到 K230
RESET	ESP EN 或从机复位 GPIO	K230 到 ESP

当前验证使用下面的 ESP32-C6 接线。RT-Smart 中除 RESET 外的引脚与 Kconfig 默认值一致；RESET 由默认的 -1 改为 GPIO 10，以便主机复位 ESP 从机并同步传输状态。实际引脚必须与 ESP-Hosted-MCU 从机工程的配置保持一致。

RT-Smart 配置项	K230 GPIO	ESP32-C6 GPIO	信号
`ESP_HOSTED_SPI_CS_PIN`	14	18	CS
`ESP_HOSTED_SPI_CLK_PIN`	15	20	CLK
`ESP_HOSTED_SPI_D0_PIN`	16	14	MOSI
`ESP_HOSTED_SPI_D1_PIN`	17	15	MISO
`ESP_HOSTED_HANDSHAKE_PIN`	18	19	HS
`ESP_HOSTED_DATA_READY_PIN`	19	8	DR
`ESP_HOSTED_RESET_PIN`	10	9	RESET

警告

K230 GPIO 编号不是开发板排针编号。接线前需要查阅所用开发板的原理图或引脚图，同时确认该 GPIO 支持所选 SPI 控制器的 FPIOA 功能。

配置 RT-Smart#

先选择目标开发板的 defconfig，然后进入 RT-Smart menuconfig。例如：

make <board>_defconfig
make rtsmart-menuconfig

进入以下菜单：

Drivers Configuration
    -> Ext Driver
        -> Enable ESP-Hosted Wi-Fi coprocessor

该选项依赖 RT-Thread SPI、K230 QSPI 驱动和 RT-Thread Wi-Fi 框架。ESP-Hosted 与 RW007、CYW43XX 和 Realtek Wi-Fi 驱动互斥，因为这些驱动会使用相同的 sta 和 ap 设备名。

SPI 配置#

先通过 Transport choice 选择传输协议：

菜单选项	用途
`SPI full-duplex`	标准 MOSI/MISO 全双工协议，使用 HS 和 DR
`SPI half-duplex`	ESP SPI-HD 协议，使用 2/4 条双向数据线和 DR

SPI 总线通过 choice 菜单选择，控制器对应关系如下：

菜单选项	RT-Thread 总线	K230 控制器
`spi0 (OSPI controller)`	`spi0`	OSPI
`spi1 (QSPI0)`	`spi1`	QSPI0
`spi2 (QSPI1)`	`spi2`	QSPI1

需要重点确认以下配置：

配置项	默认值	说明
`ESP_HOSTED_SPI_DEVICE_NAME`	`esp-hosted`	SPI 设备名
`ESP_HOSTED_SPI_MAX_HZ`	5000000	SPI 时钟，范围 1 MHz 到 40 MHz
`ESP_HOSTED_SPI_MODE`	Full-Duplex 为 3，Half-Duplex 为 0	必须与所选 ESP 从机传输配置一致
`ESP_HOSTED_SPI_CS_PIN`	14	CS GPIO，`-1` 表示使用硬件 CS
`ESP_HOSTED_SPI_CLK_PIN`	15	CLK GPIO
`ESP_HOSTED_SPI_D0_PIN`	16	Full-Duplex MOSI 或 Half-Duplex D0
`ESP_HOSTED_SPI_D1_PIN`	17	Full-Duplex MISO 或 Half-Duplex D1
`ESP_HOSTED_CHECKSUM`	开启	必须与从机校验和配置一致

建议先使用默认的 5 MHz 验证通信，再逐步提高频率。ESP32 的 SPI 频率上限为 10 MHz，其他受支持芯片通常可配置到 40 MHz，但最终稳定频率还取决于接线长度、信号质量和板级设计。

Half-Duplex 还需要选择最大总线宽度：

配置项	说明
`ESP_HOSTED_SPI_HD_WIDTH_2`	使用 D0、D1，启动和后续传输均为 Dual SPI
`ESP_HOSTED_SPI_HD_WIDTH_4`	启动时先使用 D0、D1，能力协商成功后切换到 D0-D3
`ESP_HOSTED_SPI_D2_PIN`	Quad SPI D2 GPIO，仅 4 线模式可见
`ESP_HOSTED_SPI_D3_PIN`	Quad SPI D3 GPIO，仅 4 线模式可见
`ESP_HOSTED_SPI_HD_POLL_INTERVAL_MS`	DR 为 `-1` 时读取从机状态的轮询间隔

选择 4 线模式时必须配置 D2、D3，并确认它们未与 DR、RESET 或其他外设冲突。K230 与从机都配置 4 线时，能力包之前的初始化仍按协议使用 2 线，之后才切换到 4 线。

控制信号配置#

配置项	默认值	说明
`ESP_HOSTED_HANDSHAKE_PIN`	18	Full-Duplex 必需的握手信号；Half-Duplex 不使用
`ESP_HOSTED_HANDSHAKE_ACTIVE_LOW`	关闭	Full-Duplex HS 有效电平，默认高有效
`ESP_HOSTED_DATA_READY_PIN`	19	从机有数据待发送的通知信号；Full-Duplex 必需
`ESP_HOSTED_DATA_READY_ACTIVE_LOW`	关闭	DR 有效电平，默认高有效
`ESP_HOSTED_RESET_PIN`	-1	ESP EN 或从机复位 GPIO
`ESP_HOSTED_RESET_ACTIVE_LOW`	开启	RESET 默认低有效

支持 -1 的引脚配置含义如下：

CLK、D0、D1、D2 和 D3 为 -1：驱动保留开发板已有的 FPIOA 配置。
CS 为 -1：使用 SPI 控制器硬件 CS；否则由 ESP-Hosted 驱动使用 GPIO 控制 CS。
Half-Duplex 的 DR 为 -1：使用轮询方式检查从机状态寄存器。Full-Duplex 的 HS 和 DR 均不可禁用。
RESET 为 -1：K230 不控制 ESP 复位。

SPI 传输协议要求主机与从机的计数器和传输状态在启动时同步。RESET 为 -1 时，应由外部硬件同时复位 K230 和 ESP；如果只重启其中一端，传输状态可能无法恢复。量产硬件建议连接 RESET 信号。

其他配置#

通常可以保留以下默认值：

配置项	默认值	说明
`ESP_HOSTED_RPC_TIMEOUT_MS`	10000	控制命令超时时间，单位为毫秒
`ESP_HOSTED_MAX_SCAN_RESULTS`	20	单次扫描最多返回的 AP 数量
`ESP_HOSTED_BLE`	关闭	注册 ESP Bluetooth 控制器，并自动选择通用 `RT_USING_BT_HCI` 设备层
`ESP_HOSTED_BT_HCI_DEVICE_NAME`	`hci0`	H:4 字符设备名，对应 `/dev/hci0`
`ESP_HOSTED_BT_HCI_RX_BUFFER_SIZE`	8192	完整 HCI 事件和 ACL 数据包的接收缓存
`ESP_HOSTED_THREAD_PRIORITY`	8	SPI 传输线程优先级
`ESP_HOSTED_THREAD_STACK_SIZE`	8192	SPI 传输线程栈大小
`ESP_HOSTED_EVENT_THREAD_STACK_SIZE`	8192	WLAN 事件线程栈大小

配置 ESP-Hosted-MCU 从机工程#

在完整的 ESP-Hosted-MCU 工程配置步骤补充前，从机工程至少需要满足以下兼容要求：

使用 ESP-Hosted-MCU 2.12.x 的 slave 示例。
传输方式必须与 RT-Smart 的 Transport choice 一致。
Full-Duplex 的 SPI mode 与 ESP_HOSTED_SPI_MODE 一致，推荐先使用 mode 3。
Half-Duplex 的 mode 和数据线数量与 RT-Smart 一致，只选择 2 或 4 条数据线。
CLK、数据线、CS、控制信号和 RESET 引脚与 K230 接线一致。
HS、DR 和 RESET 的有效电平与 RT-Smart 配置一致。
主从两端同时开启或同时关闭 SPI checksum。
使用 BLE 时，从机启用 Bluetooth controller，并选择通过当前 SPI/SPI-HD transport 传输 HCI，而不是 HCI UART。

建议使能 RESET 引脚，使通信稳定。

ESP 从机启动日志应能显示实际使用的 SPI 模式和引脚，例如：

SPI Ctrl:1 mode: 3, Freq:ConfigAtHost
GPIOs: CLK:20 MOSI:14 MISO:15 CS:18 HS:19 DR:8
Using GPIO [9] as slave reset pin

应以该日志中的实际值核对 K230 接线和 RT-Smart Kconfig，不能只参考 ESP 工程中的历史配置文件。

启动检查#

驱动启动时会打印总线参数和完整引脚配置：

[I/esp.hosted] SPI: bus=spi0 mode=3 freq=5000000 Hz full-duplex
[I/esp.hosted] GPIOs: CLK:15 MOSI:16 MISO:17 CS:14 HS:18 DR:19 RESET:10
[I/esp.hosted] waiting for transport handshake

通信成功后会出现类似日志：

[I/esp.hosted] transport ready: SPI full-duplex, chip=0x0d firmware=2.12.11

Half-Duplex 启动时会先显示 2 线数据通路，在处理从机能力包后显示最终协商宽度：

[I/esp.spi.hd] SPI-HD data path open: width=2 TX=1600 RX=1600
[I/esp.spi.hd] SPI-HD negotiated 4 data lines
[I/esp.hosted] transport ready: SPI half-duplex, chip=0x0d firmware=2.12.11

启用 ESP_HOSTED_BLE 且从机能力匹配时，还会出现：

[I/esp.hci] Bluetooth HCI registered as hci0
[I/esp.hosted] BLE controller transport available (BLE-only)

此时 ls /dev 应包含 hci0。如果只出现 HCI 注册日志，却提示从机未发布 Bluetooth 能力，应检查 ESP-Hosted-MCU 的 Bluetooth 和 HCI transport 配置。

随后驱动向 RT-Thread WLAN 框架注册 STA 和 SoftAP 设备。执行 ifconfig 时应能看到：

w0：STA 网络接口
w1：SoftAP 网络接口

如果没有出现 transport ready，不要继续排查 lwIP 或 Wi-Fi 命令，应先检查 SPI 和控制信号。

功能验证#

STA 扫描和联网#

执行扫描：

wifi scan

连接 AP：

wifi join <SSID> <password>

连接成功并通过 DHCP 获取地址后，检查状态和网络接口：

wifi status
ifconfig
ping <gateway_ip>

建议先 ping 局域网网关或同一局域网中的主机，避免把路由器无法访问公网误判为 ESP-Hosted 数据通路故障。

断开 STA：

wifi disc

SoftAP#

启动 SoftAP：

wifi ap <SSID> <password>

使用手机或电脑连接后查询已连接终端：

wifi list_sta
ifconfig

CanMV 可以使用 status("stations") 获取终端 MAC，再调用 SoftAP 接口的 disconnect() 主动断开指定终端：

stations = ap.status("stations")
if stations:
    ap.disconnect(tuple(stations[0]))

主动断开后，终端应从 wifi list_sta 的结果中消失。

停止 SoftAP：

wifi ap_stop

STA 与 SoftAP 并发#

先使用 wifi join 连接上游 AP，再使用 wifi ap 启动 SoftAP。执行 ifconfig，确认 w0 和 w1 都处于 LINK_UP 状态。

STA 与 SoftAP 同时工作只表示两个 Wi-Fi 接口都已建立，不代表系统会自动在两个接口之间启用 NAT 或路由转发。

BLE#

内核侧启用 ESP_HOSTED_BLE 后，可由任意 H:4 host stack 打开 /dev/hci0。CanMV 已接入 MicroPython 自带的 NimBLE，实现完整 BLE host 功能；在 SDK 顶层 menuconfig 中启用：

CanMV Micropython Components Configurations
    -> Enable Bluetooth module (NimBLE over RT-Smart HCI)

BLUETOOTH_HCI_DEVICE_PATH 默认是 /dev/hci0，必须与 RT-Smart 的 ESP_HOSTED_BT_HCI_DEVICE_NAME 一致。NimBLE 是 MicroPython 的 git submodule，首次构建前需初始化：

git -C src/canmv/micropython submodule update --init lib/mynewt-nimble

打开 /dev/hci0 时，内核通过 ESP-Hosted FeatureControl RPC 初始化并使能 ESP 端 Bluetooth controller；关闭设备时先关闭再反初始化 controller，但不释放其内存，因此之后可以再次打开。ESP-Hosted-MCU 2.5.2 及以后版本默认不会自动启动 Bluetooth controller，这两个 RPC 步骤不能省略。

先验证控制器初始化和扫描：

import bluetooth
import time

_IRQ_SCAN_RESULT = 5
_IRQ_SCAN_DONE = 6

def irq(event, data):
    if event == _IRQ_SCAN_RESULT:
        addr_type, addr, adv_type, rssi, adv_data = data
        print("scan", bytes(addr).hex(), rssi, bytes(adv_data))
    elif event == _IRQ_SCAN_DONE:
        print("scan done")

ble = bluetooth.BLE()
ble.active(True)
ble.irq(irq)
ble.gap_scan(5000, 30000, 30000)
time.sleep_ms(6000)

再验证 Peripheral 广播：

payload = b"\x02\x01\x06\x0b\x09CanMV-K230"
ble.gap_advertise(500000, adv_data=payload)

手机 BLE 扫描工具应能发现 CanMV-K230。扫描验证 Observer/Central 数据通路，广播验证 Broadcaster/Peripheral 数据通路；之后可使用 MicroPython examples/bluetooth 中的 temperature peripheral/central 示例测试 GATT service discovery、读写和 notification。

Wi-Fi 和 HCI 共用 ESP transport，但使用独立优先级队列。RPC/control 优先级最高，HCI 次之，WLAN data 最后；WLAN flow-control 不会停止 HCI 命令和 ACL 数据。

吞吐量测试#

如需使用 iperf，需要在 SDK 配置中启用：

CONFIG_PKG_USING_NETUTILS=y
CONFIG_PKG_NETUTILS_IPERF=y

可使用局域网内的 PC 作为对端进行 TCP 或 UDP 测试：

iperf -c <PC_IP>
iperf -s
iperf -u -c <PC_IP>
iperf -u -s

常见问题#

启动时长时间等待#

Full-Duplex 先检查 HS、DR 和 RESET；Half-Duplex 先检查 DR、RESET、SPI mode 和数据线数量。未连接 ESP 从机时，驱动会在后台退避等待，不应阻塞系统启动；连接从机后必须出现 transport ready 才表示协议初始化完成。

SPI 接收一直为 `0xff`#

日志可能包含：

SPI RX stuck at 0xff; check spi0 D1/MISO wiring and coprocessor power

这通常表示 MISO 悬空、接错、从机未上电，或者 ESP 从机没有驱动 MISO。重点检查 D1/MISO，不要把 K230 的 D0 和 D1 与 ESP 的 MOSI、MISO 反接。

SPI 接收一直为 `0x00`#

依次检查以下项目：

ESP 从机是否已运行 SPI Full-Duplex 固件。
SPI mode 是否与从机一致。
CS 是否接到从机配置的 CS GPIO，并在整个 1600 字节帧期间保持有效。
MISO 和共地是否连接可靠。
HS、DR 是否接反或有效电平配置错误。
先把 SPI 频率降到 1 MHz 或 5 MHz，再排除信号质量问题。

可以扫描但不能连接#

先重新执行 wifi scan，确认目标 SSID 仍在当前扫描结果中，再执行 wifi join。同时检查密码和 AP 的安全类型。驱动的扫描结果数量受 ESP_HOSTED_MAX_SCAN_RESULTS 限制，目标 AP 较弱时可适当提高该值。

已连接并获取 IP，但无法访问网络#

先执行 ping <gateway_ip> 验证局域网数据通路。如果网关可达而域名不可用，再检查 DHCP 下发的 DNS；如果公网 IP 也不可达，应检查上游路由器的互联网连接，不要仅根据域名 ping 结果判断驱动故障。

主机单独重启后通信失败#

这是 RESET 配置为 -1 时最常见的问题。SPI 传输状态不会因为 K230 单独重启而自动同步。连接 K230 GPIO 到 ESP EN/RESET，或者确保外部复位电路同时复位主机和从机。

代码位置#

RT-Smart 端实现位于：

src/rtsmart/rtsmart/kernel/bsp/maix3/drivers/extdrv/esp_hosted/

协议帧、收发队列和上层回调位于 transport 公共层，SPI Full-Duplex 与 SPI Half-Duplex 分别由独立后端实现。后续增加 SDIO 时应实现新的 transport 后端，不应把 SDIO 状态加入 WLAN/RPC 层。驱动目录中的 README.md 记录移植范围和实现约束；Kconfig 是 menuconfig 选项的最终依据。

ESP-Hosted Wi-Fi 协处理器使用指南

目录

ESP-Hosted Wi-Fi 协处理器使用指南#

功能范围#

硬件连接#

配置 RT-Smart#

SPI 配置#

控制信号配置#

其他配置#

配置 ESP-Hosted-MCU 从机工程#

启动检查#

功能验证#

STA 扫描和联网#

SoftAP#

STA 与 SoftAP 并发#

BLE#

吞吐量测试#

常见问题#

启动时长时间等待#

SPI 接收一直为 0xff#

SPI 接收一直为 0x00#

可以扫描但不能连接#

已连接并获取 IP，但无法访问网络#

主机单独重启后通信失败#

代码位置#

SPI 接收一直为 `0xff`#

SPI 接收一直为 `0x00`#