Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for a specific release, use the drop-down menu on the left.

ESP-Hosted Wi-Fi Coprocessor User Guide

Overview

RT-Smart provides two mutually independent ESP-Hosted drivers. Before selecting one, you must confirm the firmware protocol flashed onto the ESP slave; similar names do not indicate protocol compatibility.

RT-Smart Driver	Kconfig	ESP Firmware	Transport	Features
ESP-Hosted-FG/NG	RT_USING_ESP_HOSTED_WIFI	ESP-Hosted-FG or ESP-Hosted-NG	SPI Full-Duplex, SDIO	WLAN offload integration; FG handles connections in the firmware, while NG supports host authentication
ESP-Hosted-MCU	RT_USING_ESP_HOSTED_MCU	ESP-Hosted-MCU	SPI Full-Duplex, SPI Half-Duplex	RPC Wi-Fi control, with optional BLE HCI and full RPC

Both drivers register STA/SoftAP with RT-Thread WLAN and lwIP, so the upper layer continues to use wifi, NetMgmt, or CanMV network.WLAN. The protocol, transport, and slave configuration must be fully consistent with the host-side Kconfig.

Source Code Location

src/rtsmart/rtsmart/kernel/bsp/maix3/drivers/extdrv/esp_hosted/      # FG/NG
src/rtsmart/rtsmart/kernel/bsp/maix3/drivers/extdrv/esp_hosted_mcu/  # MCU

Driver Selection

ESP-Hosted-FG

FG delegates scanning, connection, and SoftAP management to the ESP firmware through RPC. It is suitable for scenarios where WPA management is intended to be performed by the coprocessor. An optional /dev/wlanctlN can be used for capability queries and diagnostics, but FG does not expose external supplicant capabilities.

ESP-Hosted-NG

NG provides the host with authentication, association, EAPOL, key, and management frame interfaces. RT-Smart’s embedded path supports common WPA/WPA2 STA and open/WPA2 SoftAP configurations; more complete security modes can be accessed through a userspace supplicant via /dev/wlanctlN.

ESP-Hosted-MCU

The MCU driver uses the generated protobuf-c schema and RPC. In addition to STA/SoftAP, it can register a remote Bluetooth controller as /dev/hciN and provide typed RPC, OTA, configuration, and event interfaces to native applications. The current MCU driver implements only the SPI backend and does not support SDIO.

General Hardware Requirements

All connections must share a common ground and satisfy the same I/O voltage. K230 GPIO numbers are not the development board header pin numbers; check the schematic and FPIOA capabilities before wiring.

SPI Full-Duplex uses the following signals:

K230	ESP	Direction
CLK	SPI CLK	K230 to ESP
D0/MOSI	MOSI	K230 to ESP
D1/MISO	MISO	ESP to K230
CS	CS	K230 to ESP
Handshake	HS	ESP to K230
Data Ready	DR	ESP to K230
Reset	EN/Reset	K230 to ESP

ESP-Hosted-MCU SPI Half-Duplex does not use Handshake. D0 and D1 are bidirectional data lines; Quad mode also requires D2 and D3. Half-Duplex can use the DR interrupt, or DR can be configured as -1 and the status register polled.

Warning

SPI 模式、频率、校验和、总线宽度、HS/DR 有效电平及所有引脚必须与 ESP 从机 固件一致。量产硬件建议连接 Reset；否则主机与从机应同时复位。

Configuring FG/NG

Run:

make <board>_defconfig
make rtsmart-menuconfig

Enable RT_USING_ESP_HOSTED_WIFI, and then select:

1. ESP_HOSTED_WIFI_FG or ESP_HOSTED_WIFI_NG;

2. ESP_HOSTED_WIFI_TRANSPORT_SPI or ESP_HOSTED_WIFI_TRANSPORT_SDIO;

3. The checksum, SPI/SDIO parameters, and frequency band that match the slave.

SPI uses spi0, Mode 3, 5 MHz, and GPIO 14 through 17, Handshake 20, and Data Ready 21 by default. Reset defaults to -1. These are only driver defaults and cannot replace board-level wiring configuration.

SDIO currently supports the common ESP IDs 6666:2222, 6666:3333, 0092:6666, and 0092:7777, but only one set of IDs can be configured per driver registration. Select the ID actually advertised by the slave through ESP_HOSTED_WIFI_SDIO_MANUFACTURER and ESP_HOSTED_WIFI_SDIO_PRODUCT.

ESP_HOSTED_WIFI_AUTO_START is enabled by default. The probe task waits for the firmware boot event in a thread and does not block RT-Smart initialization when no ESP is connected; after a failure, /dev/wlanctlN can still be retained for manual retry and diagnostics.

Configuring ESP-Hosted-MCU

Enable RT_USING_ESP_HOSTED_MCU, and then select a transport:

• ESP_HOSTED_TRANSPORT_SPI_FD: Full-Duplex; HS and DR must be connected, and Mode 0 is unavailable;

• ESP_HOSTED_TRANSPORT_SPI_HD: Half-Duplex; select 2-wire or 4-wire, with Modes 0 through 3 all available.

The current defaults are spi0, Mode 3, 5 MHz, CS 14, CLK 15, D0 16, and D1 17; the HS for Full-Duplex is 20 and the DR is 21; Reset defaults to -1. Quad SPI also requires configuring D2 18 and D3 19. The SPI-HD four-wire master initially starts in two-wire mode and switches to four-wire mode only after receiving the coprocessor capability packet.

Common runtime configurations:

Configuration Item	Description
ESP_HOSTED_CHECKSUM	Generates and verifies the transport checksum; master and slave must match
ESP_HOSTED_RPC_TIMEOUT_MS	RPC timeout, 10000 ms by default
ESP_HOSTED_MAX_SCAN_RESULTS	Maximum number of scan results, 20 by default
ESP_HOSTED_WIFI_MAX_TX_POWER	Requested value in units of 0.25 dBm, 84 (20 dBm) by default
ESP_HOSTED_BLE	Registers a dynamic /dev/hciN Bluetooth H:4 device
ESP_HOSTED_SPI_HD_STATS	Registers esp_spi_hd_stats for diagnostics only

The master and slave should use compatible ESP-Hosted-MCU schemas. At startup, the master must receive a new Event_ESPInit before enabling RPC, thereby avoiding treating leftover SPI-HD register state from a previous session as a valid connection.

Startup and Verification

First, check whether the startup log contains transport ready, the actual pins, the firmware version, and the negotiated width. Then run:

wifi devices
wifi -i spi scan
wifi -i spi join <ssid> <password>
wifi -i spi status
ifconfig
ping <gateway-address>

SoftAP verification:

wifi -i spi ap <ssid> <password>
wifi -i spi list_sta
wifi -i spi ap_stop

Enabling only STA and SoftAP does not unconditionally provide network sharing. The firmware must also enable the DHCP server and LWIP_USING_NAT; once these conditions are met, the WLAN layer automatically starts and stops NAT with the SoftAP. For configuration and limitations, see IPv4 NAT Usage Guide.

After enabling the control device in FG/NG, you can use the WLAN Offload Control Example to query the actual control device name, capabilities, and events.

BLE and RPC

After the MCU driver enables ESP_HOSTED_BLE, it registers /dev/hciN. This device provides only the H:4 controller transport; GAP, GATT, L2CAP, and SMP are provided by host stacks such as NimBLE. When the device is opened, the driver initializes and enables the remote controller through the FeatureControl RPC; when it is closed, the driver performs disabling and deinitialization.

For complete host/controller configuration and limitations, see Bluetooth HCI and NimBLE Usage Guide.

Native C applications that require the complete RPC can include esp_hosted_rpc.h; include esp_hosted_rpc_schema.h when generated protobuf-c types are needed. New code should preferably use rt_esp_hosted_rpc_call_message(), which validates the request and response descriptors. Whether RPC is available still depends on the ESP chip, ESP-IDF version, and slave compilation options.

Troubleshooting

1. No transport ready: first check the power, common ground, SPI mode, CS, HS/DR levels, and slave firmware personality; do not troubleshoot lwIP first.

2. SPI consistently reads 0xff: focus on checking D1/MISO, slave power, and whether the firmware is running.

3. Failure after restarting the master alone: connect Reset, or ensure that both ends are reset simultaneously.

4. FG/NG SDIO is not detected: verify the slave’s actual manufacturer/product ID and the selected host.

5. SPI-HD starts but there is no RPC: confirm that a new Event_ESPInit was received, and verify the schema and checksum.

6. 5 MHz is the connectivity verification frequency, not the performance target; increase the frequency step by step and verify signal integrity at each step.