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

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

TBD

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.

Assuming the chip’s base MAC address is 00:e0:4c:01:02:03, the SoftAP MAC address can be configured as follows:

Example 1: Default Configuration (Byte 1 + 1)Example 2: Byte 5 + 1Example 3: Same as Chip MAC Address

SoftAP MAC address: 00:e1:4c:01:02:03

wifi_user_config.concurrent_enabled = 1;
wifi_user_config.softap_addr_offset_idx = 1;

MAC Address Conflict Restriction

When the SoftAP MAC address matches the chip’s MAC address (Example 3), STA and SoftAP cannot operate simultaneously:

• STA cannot connect to any AP after SoftAP is activated.

• SoftAP cannot start if STA is already connected.

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	Element ID	Channel Switch Mode	New Channel Number	Channel Switch Count
Length	1 byte	1 byte	1 byte	1 byte
Meaning	CSA IE ID	STA transmission restriction mode	New channel for SoftAP	Remaining Beacon intervals before switching
Source	Fixed	rtw_csa_parm::chl_switch_mode	rtw_csa_parm::new_chl	Initialized by rtw_csa_parm::chl_switch_cnt, decremented each Beacon interval

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