Wi-Fi User Configuration

All configuration parameters are managed through the wifi_user_conf structure. This section will detail the parameters within this structure and their configuration methods.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

github source code

• ameba_wificfg.c

rtw_edcca_mode

The Energy-Detection Clear Channel Assessment (EDCCA) mechanism governs channel access for wireless devices. It operates by sensing the energy level on a channel; if the energy is below a predefined threshold, the channel is considered “clear” or “idle,” and a device is permitted to transmit. This process minimizes data collisions and enables reliable co-channel communication among multiple devices.

Parameter	rtw_edcca_mode
Type	u8
Value	RTW_EDCCA_NORM	Dynamically adjusts the EDCCA detection threshold based on real-time RSSI measurements. User Case: Increases transmission opportunities by ignoring weak interference signals.
	RTW_EDCCA_ADAPT	ETSI Adaptivity test mode, fixed threshold. User Case: Wi-Fi Regulatory Testing - Adaptivity Test
	RTW_EDCCA_CS	Carrier Sense to comply with Japan’s interference avoidance regulations, fixed threshold. User Case: Wi-Fi Regulatory Testing - Adaptivity Test
	RTW_EDCCA_DISABLE	Disable the EDCCA mechanism.
Default	RTW_EDCCA_NORM

tx_pwr_table_selection

In general, the final Wi-Fi transmit (Tx) power is determined by taking the minimum value from two power tables:

• Power by Rate Table: Specifies maximum transmit power for different data rates while meeting Radio Frequency (RF) performance requirements.

• Power Limit Table: Specifies the restrictions imposed by local regulations on Wi-Fi output Tx power of each channel.

This parameter is used to select which power table(s) will determine the final Tx power.

Parameter	tx_pwr_table_selection
Type	u8
Value	0	Use the Power by Rate Table. Use Case: Increase transmission power
	1	Use the minimum value from the Power Limit Table and the Power by Rate Table Use Case: Power Saving
	2	Select based on the setting in eFuse.
Default	2

rtw_trp_tis_cert_en

Customers will need to evaluate the antenna performance and the overall RF link quality of the end device. This involves conducting tests on its RF performance, also known as OTA (Over-the-Air) tests. And performance is generally measured by two key indicators, Total Radiated Power and Total Isotropic Sensitivity, with tests typically conducted in an anechoic chamber.

• Total Radiated Power (TRP): The sum of the RF power transmitted by the device in all directions. It measures the device’s transmission performance.

• Total Isotropic Sensitivity (TIS): The average value of the minimum received power required for the device to successfully demodulate a signal, averaged over all directions. It measures the device’s reception performance.

To meet the requirements of different testing environments, some customized configurations are necessary. Please configure according to the table below:

Parameter	rtw_trp_tis_cert_en
Type	u8
Value	RTW_TRP_TIS_DISABLE	Disable TRP/TIS Test Customization Use Case: Non-TRP/TIS Certification
	RTW_TRP_TIS_NORMAL	Enable TRP/TIS Test Customization Use Case: TRP/TIS Certification
	RTW_TRP_TIS_DYNAMIC	Reserved
	RTW_TRP_TIS_FIX_ACK_RATE	Reserved
	RTW_TRP_TIS_FIX_PHY_ACK_HIGH_RATE	Reserved
Default	RTW_TRP_TIS_DISABLE

wifi_wpa_mode_force

Use this parameter to enforce a specific Wi-Fi Protected Access (WPA) mode.

Parameter	wifi_wpa_mode_force
Type	u8
Value	RTW_WPA_AUTO_MODE	Automatically selects the WPA mode based on the AP’s capabilities.	Compatibility Testing Some devices may have some bugs when handling WPA mixed mode, leading to connection failures or instability. This is a common debugging method used to determine if the issue lies in the security mode negotiation phase. Automated Testing In certain test environments, testers need to verify device functionality under various specific WPA modes.
	RTW_WPA_ONLY_MODE	Supports WPA mode only.
	RTW_WPA2_ONLY_MODE	Supports WPA2 mode only.
	RTW_WPA3_ONLY_MODE	Supports WPA3 mode only.
	RTW_WPA_WPA2_MIXED_MODE	Supports WPA/WPA2 mixed mode.
	RTW_WPA2_WPA3_MIXED_MODE	Supports WPA2/WPA3 mixed mode.
Default	RTW_WPA_AUTO_MODE

tdma_dig_enable

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

Not Support

antdiv_mode

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

Ameba chips feature Antenna Diversity to mitigate the effects of multipath fading in wireless communication, resulting in improved signal quality and connection reliability.

The core principle is to dynamically switch between antennas to achieve optimal transmit (Tx) and receive (Rx) performance. At the software level, the system collects and analyzes metrics from received packets over a set interval, including Received Signal Strength Indication (RSSI), Error Vector Magnitude (EVM), and throughput, etc. The antenna demonstrating superior performance is then selected for use by the transceiver during the next operational period.

Parameter	antdiv_mode
Type	u8
Value	RTW_ANTDIV_AUTO	Automatic antenna switching mode
	RTW_ANTDIV_FIX_MAIN	Fixed to MAIN antenna
	RTW_ANTDIV_FIX_AUX	Fixed to AUX antenna
	RTW_ANTDIV_DISABLE	Disable antenna diversity mechanism
Default	RTW_ANTDIV_DISABLE

If the antenna diversity mechanism is required, the feature must be enabled when compiling the firmware. Please follow the steps below:

1. Navigate to {SDK}/amebaxxx_gcc_project and run the following command:

   ./menuconfig.py
   

2. Locate CONFIG WIFI > Enable ANTDIV, select Enable ANTDIV, then save and exit.

   ----Connectivity config----
       CONFIG WHC INTF --->
       CONFIG WIFI --->
                SDK MODE (NORMAL INIC)  --->
         [ ]    Enable WPS
         [ ]    Enable CSI
         [*]    Enable ANTDIV
         ---
       CONFIG BT --->
       ... --->
   

concurrent_enabled

The Wi-Fi concurrent mode enables the Ameba device to operate in two different network roles at the same time: STA mode and SoftAP mode, please reference Wi-Fi Basic Mode chapter for detail information.

To use Wi-Fi concurrent mode, set wifi_user_config.concurrent_enabled = 1.

SoftAP Configuration

This section provides parameters to configure the capabilities, behavior, and other aspects of the SoftAP mode.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

Parameter	Type	Value	Description	Default
ap_sta_num	u8	1 ~ 14	Maximum number of allowed connected devices for SoftAP.	5
ap_polling_sta	u8	0 / 1	Softap sends inquiry frames periodically to confirm if STA is still online. Not Support	0
softap_addr_offset_idx	u8	0 ~ 5	Specifies the incremental offset position for the SoftAP’s MAC address (increment is 1). Note Valid when wifi_user_config. concurrent_enabled = 1. Since the LSB of MAC[0] being 1 indicates a multicast address, the increment is 2 when the offset position is MAC[0].	1

Example-MAC address Conversion

Assuming the chip’s base MAC address is 00:e0:4c:01:02:03

• softap_addr_offset_idx = 0 -> SoftAP MAC address: 02:e0:4c:01:02:03

• softap_addr_offset_idx = 1 -> SoftAP MAC address: 00:e1:4c:01:02:03

• softap_addr_offset_idx = 5 -> SoftAP MAC address: 00:e0:4c:01:02:04

MAC Address Conflict Restriction

STA and SoftAP will not operate simultaneously When the SoftAP MAC address matches the chip’s MAC address (wifi_user_config. concurrent_enabled = 0):

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

• SoftAP cannot start if STA is already connected.

Power Saving Configuration

The Ameba chips are low-power Wi-Fi/Bluetooth SoCs specifically designed for Internet of Things (IoT) applications. A core design principle is advanced power management, which allows developers to strike a precise balance between performance, power consumption, and response time based on their specific application needs. For a detailed introduction to the power-saving modes, please refer to the FreeRTOS Power Saving section.

The configuration of various power-saving modes is detailed below:

1. Inactive Power Save (IPS) Mode

   RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

   The IPS mode is specifically designed for scenarios where the device is not connected to a Wi-Fi network. It enables the device to enter a sleep state during periods of inactivity, thereby significantly extending battery life.

   IPS supports two distinct sleep states:

   • Wi-Fi Power Off: In this state, the Wi-Fi module is completely powered down to achieve maximum power savings.

   • Power Gating (PG) Mode: This state utilizes power gating techniques, which allows for a much faster exit from IPS mode upon wakeup.

   By default, the device enters IPS mode through a periodic monitoring mechanism. The system periodically checks the Wi-Fi status and if it detects that Wi-Fi is disconnected and no special operations (such as scanning) are in progress, it will transition into the appropriate, pre-configured sleep state.

   Additionally, a manual-trigger mechanism is available for immediate entry into IPS mode. To use this, the developer must set the configuration parameter wifi_user_config.ips_ctrl_by_usr = 1 and subsequently call the function wifi_set_ips_internal().

   

   IPS flow

   Parameter	Type	Value	Description	Default
   ips_enable	u8	0 / 1	Disable/Enable IPS	1
   ips_level	u8	RTW_IPS_WIFI_OFF	Wi-Fi power off in IPS	RTW_IPS_WIFI_OFF
   		RTW_IPS_WIFI_PG	Wi-Fi power gating in IPS
   ips_ctrl_by_usr	u8	0 / 1	Enable fast entry into IPS mode	0

2. Legacy Power Save (LPS) Mode

   LPS is the original power-saving mechanism defined in the IEEE 802.11 standard. Its core principle allows a client station (STA) to enter a low-power sleep state while connected to an Access Point (AP) but with no active data traffic. During this sleep period, the AP buffers any incoming downstream data intended for the STA, thus conserving the STA’s power.

   An STA operating in LPS mode must periodically wake up to listen for beacon frames broadcast by the AP. By examining the Traffic Indication Map (TIM) element within these beacons, the STA can determine if the AP has buffered data for it. If the TIM indicates that data is pending, the STA will remain awake to communicate with the AP and retrieve the buffered frames. Otherwise, it can return to sleep until the next scheduled wakeup.

   Parameter	Type	Value	Description	Default
   lps_enable	u8	0 / 1	Disable/Enable LPS	1
   lps_listen_interval	u8	0	Wakes up at each Target Beacon Transmission Time (TBTT) to receive the beacon frame.	0
   		> 0	Configure the interval for receiving beacon frames, unit: 102.4ms (TBTT interval)

3. Wake on Wireless LAN (WoWLAN) Mode

   WoWLAN is a system-level power-saving mode designed for periods of system inactivity. In this mode, the CPU is suspended, but its core clock and power supply remain active to enable a rapid resume. Furthermore, the state of the Radio Frequency (RF) module can be configured to be either enabled or disabled during this mode.

   The system is awakened from this low-power state by specific Wi-Fi events. These wake-up triggers include:

   • Receipt of a targeted unicast packet.

   • Receipt of a broadcast or multicast packet.

   • An Access Point (AP) disconnection event.

   To provide developers with granular control, we offer a configuration option to specify whether incoming broadcast and multicast packets should trigger a system wake-up.

   Parameter	Type	Value	Description	Default
   wowlan_rx_bcmc_dis	u8	0 / 1	Enable/Disable the ability for broadcast or multicast frames to wake the system in WoWLAN mode.	0

Others

TBD