Wi-Fi Basic Architecture

WHC IPC is the default wireless communication architecture in the SDK, offering full-chip compatibility. Its core features include:

• Dual-core Architecture

  • Based on the AP and NP dual-core design of the Ameba chip

  • Enables communication between Host and Device through internal IPC interfaces

  • No external Host controller required

• Parallel Protocol Stack Execution

  • LWIP network protocol layer and Wi-Fi driver layer run on separate cores

  • Enables parallel processing to enhance data transmission efficiency

• Modular Isolation Design

  • Achieves secure decoupling between the Wi-Fi driver layer and user application layer

  • Improves system security, reliability, and robustness

WHC IPC architecture

Wi-Fi Initialization

The SDK enables Wi-Fi functionality by default. In the main() function, it automatically calls wifi_init() to initialize Wi-Fi. The complete Wi-Fi initialization flow is shown below:

Note

• After successful Wi-Fi initialization, the device defaults to STA Mode.

• To enable SoftAP Mode, call wifi_start_ap() after Wi-Fi initialization is complete. Refer to Common SoftAP Workflows for details.

Wi-Fi Scan

This section introduces several common scan configurations. For advanced configurations, please refer to wifi_scan_networks().

Wi-Fi scanning modes include synchronous scanning and asynchronous scanning, with the complete workflow as follows:

Synchronous Scan ModeAsynchronous Scan Mode

Configuration:

• Set block=1 when calling wifi_scan_networks()

Features:

• Thread-safe: Only blocks the calling thread, allowing other threads to continue running

• Recommended for: Most basic use cases

Synchronous scan flow

STA Mode

STA Connection Flow

This section introduces several common STA connection flows. For advanced configurations, refer to wifi_connect().

Synchronous Connection ModeAsynchronous Connection Mode

Configuration:

• Set block=1 when calling wifi_connect()

Features:

• Thread-safe: Only blocks the calling thread, allowing other threads to continue running

• Recommended for: Most basic use cases

Synchronous Connection Flow

Note

Setting rtw_network_info::channel (e.g., obtained through a separate scan) can significantly reduce connection latency if the AP channel is known.

STA Auto-reconnect on Disconnection

This section introduces the Auto-reconnect on Disconnection, When the STA fails to connect or is disconnected by the AP, it will automatically reconnect.

Auto-reconnect Flow

Related properties can be configured using the following parameters in the component/soc/usrcfg/amebaxxx/ameba_wificfg.c file

Parameters	Description
wifi_user_config.auto_reconnect_en	Enable/disable auto-reconnect feature, set to 1 to enable.
wifi_user_config.auto_reconnect_count	Maximum number of auto-reconnect attempts, 0xff means infinite retry count.
wifi_user_config.auto_reconnect_interval	Auto-reconnect interval in seconds.
wifi_user_config.no_beacon_disconnect_time	Disconnection interval after no beacon, in units of 2 seconds.

Note

After configuring the following settings, you can implement the custom reconnection function by referring to the file component/example/wifi/wifi_user_reconnect/example_wifi_user_reconnect.c.

wifi_user_config.auto_reconnect_en = 0;

STA Auto-reconnect on Power-up

This section introduces the Auto-reconnect on Power-up. After the STA connects successfully, the AP’s SSID, password, PSK, channel, and security type are stored in flash. Upon the next power-up, the device will automatically attempt to reconnect using this information. If the connection fails, up to four additional attempts will be made.

Auto-reconnect on Power-up Flow

It can be enabled by configuring the following parameter in the component/soc/usrcfg/amebaxxx/ameba_wificfg.c file

Parameters	Description
wifi_user_config.fast_reconnect_en	Enable/disable auto-reconnect on power-up feature, set to 1 to enable.

STA Power-saving Mode

TBD

SoftAP Mode

Common SoftAP Workflows

This section introduces common workflows for SoftAP. For advanced configurations, please refer to the SoftAP-related API documentation.

The common SoftAP workflow is shown in the following figure:

SoftAP MAC Address Configuration

The SoftAP MAC address is derived from the chip’s base MAC address and can be configured in the file component/soc/usrcfg/amebaxxx/ameba_wificfg.c.

For details, refer to the Wi-Fi User Configuration - SoftAP Configuration chapter.

Channel Switch Announcement (CSA) for SoftAP

SoftAP can perform channel switching and notify all connected STAs by calling wifi_ap_switch_chl_and_inform(). This enables STAs to quickly and seamlessly follow SoftAP to the new channel, preventing connection interruptions.

The channel switching sequence diagram for SoftAP is illustrated below:

The CSA Information Element (CSA IE) format in Beacon and CSA Action frames is as follows. Specific field values are determined by the input parameters of wifi_ap_switch_chl_and_inform():

CSA IE Format

Field	Length	Meaning	Source
Element ID	1 byte	CSA IE ID	Fixed
Channel Switch Mode	1 byte	STA transmission restriction mode	rtw_csa_parm::chl_switch_mode
New Channel Number	1 byte	New channel for SoftAP	rtw_csa_parm::new_chl
Channel Switch Count	1 byte	Remaining Beacon intervals to switch	Set from rtw_csa_parm::chl_switch_cnt, decremented per Beacon

Note

• Refer to rtw_csa_parm for detailed descriptions when configuring parameters for wifi_ap_switch_chl_and_inform().

• Regardless of the CSA Action frame type (rtw_csa_parm::action_type) selected, Beacon frames always include the CSA IE prior to channel switching.

Example: SoftAP switches to channel 7 after 10 Beacon intervals, sending 2 broadcast CSA Action frames per interval, without restricting STA transmission:

struct rtw_csa_parm csa_param = {0};

csa_param.new_chl = 7;
csa_param.chl_switch_cnt = 10;
csa_param.bc_action_cnt = 2;
csa_param.action_type = 1;
csa_param.chl_switch_mode = 0;
csa_param.callback = NULL;

wifi_ap_switch_chl_and_inform(&csa_param);

Note

In SoftAP/STA coexistence mode, if the STA is already connected to an AP, SoftAP channel switching will cause the STA to disconnect.

STA and SoftAP Coexistence

TBD

Promiscuous Mode

TBD