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.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

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. Use Case: Increases transmission opportunities by ignoring weak interference signals.
	RTW_EDCCA_ADAPT	ETSI Adaptivity test mode, fixed threshold. Use Case: Wi-Fi Regulatory Testing - Adaptivity Test
	RTW_EDCCA_CS	Carrier Sense to comply with Japan’s interference avoidance regulations, fixed threshold. Use Case: Wi-Fi Regulatory Testing - Adaptivity Test
	RTW_EDCCA_DISABLE	Disable the EDCCA mechanism.
Default	RTW_EDCCA_NORM

tx_pwr_table_selection

Please refer TX Power table

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
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

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

Not Support

antdiv_mode

Please refer to Wi-Fi ANTDIV - Software Configuration for detailed information.

SoftAP Configuration

Please refer to SoftAP Configuration chapter.

Power Saving Configuration

Please refer to Wi-Fi Power Saving chapter.

UAPSD Configuration

Unscheduled Automatic Power Save Delivery (U-APSD) is part of the Wi-Fi Multimedia (WMM) specification and a feature within the WMM-Power Save (WMM-PS) mechanism. It is designed to provide low latency for real-time, latency-sensitive applications (such as VoIP calls and video streaming) while maximizing the battery life of battery-powered devices (e.g., smartphones, IoT devices).

Its core concept is to allow the client device (STA) to decide when to wake up to retrieve data, rather than passively waiting for a fixed point in time.

U-APSD Timing Sequence

Parameter	Type	Value	Description	Default
uapsd_enable	u8	0 / 1	Disable/Enable U-APSD mechanism.	0
uapsd_max_sp_len	u8	The maximum number of MAC Service Data Units (MSDUs) that can be exchanged in a single Service Period (SP).		0
		RTW_UAPSD_NO_LIMIT	Allow the AP to deliver all buffered frames within one SP.
		RTW_UAPSD_TWO_MSDU	Up to 2 transmissions per SP.
		RTW_UAPSD_FOUR_MSDU	Up to 4 transmissions per SP.
		RTW_UAPSD_SIX_MSDU	Up to 6 transmissions per SP.
uapsd_ac_enable	u8	Configure the Access Categories for U-APSD.		0
		BIT0	AC_VO
		BIT1	AC_VI
		BIT2	AC_BK
		BIT3	AC_BE

Frame Aggregation Configuration

Frame Aggregation is a feature introduced in the IEEE 802.11n standard and enhanced in subsequent standards (like 802.11ac/ax). Its primary purpose is to improve the efficiency of the MAC (Media Access Control) layer by combining multiple smaller data frames into a single, larger transmission.

This process reduces the significant overhead associated with transmitting each frame individually, such as the physical layer preamble, inter-frame spacing (IFS), and acknowledgement (ACK) frames. By minimizing this overhead, frame aggregation leads to a substantial increase in overall network throughput.

There are two primary methods of frame aggregation defined in the IEEE 802.11 standard:

1. A-MSDU (Aggregate MAC Service Data Unit)

   • Mechanism: This method combines multiple MSDUs (e.g., IP packets from upper layers) into a single MPDU (MAC Protocol Data Unit). The entire aggregated payload is then sent as one frame with a single MAC header.

   • Advantages: Reduces MAC header overhead significantly.

   • Disadvantages: If any part of the aggregated frame is corrupted during transmission, the entire A-MSDU frame must be retransmitted because it is protected by a single Frame Check Sequence (FCS) and acknowledged with a single ACK.

2. A-MPDU (Aggregate MAC Protocol Data Unit)

   • Mechanism: This method combines multiple complete MPDUs, each with its own MAC header and FCS, into a single transmission block handled by the physical layer.

   • Advantages: It is more robust against transmission errors. Each subframe (MPDU) within the aggregate can be individually acknowledged using a Block Acknowledgement (Block ACK) frame. If a subframe is lost or corrupted, only that specific subframe needs to be retransmitted, not the entire aggregate.

   • Application: Due to its robustness, A-MPDU is the more widely used and mandatory aggregation method in modern Wi-Fi standards.

The IEEE 802.11n standard specifies that the use of A-MPDU requires the prior establishment of a Block Ack mechanism. The process is typically divided into three stages:

1. Setting up the Block ACK Session

   Before transmitting an A-MPDU, the sender (Originator) and the receiver (Recipient) need to negotiate the use of the Block ACK mechanism. This process is accomplished by exchanging management frames:

   • Add Block Acknowledgment Request: The sender sends an ADDBA Request frame to the receiver, this frame contains key parameters, such as:

     • Traffic Identifier (TID): Specifies for which class of service (e.g., video, voice, background data) the session is being established.

     • Buffer Size: Informs the receiver of the maximum number of frames the sender will transmit in a single block, allowing the receiver to reserve sufficient buffer space.

   • Add Block Acknowledgment Response: Upon receiving the request, if the receiver agrees to establish the session, it replies with an ADDBA Response frame, confirming the session parameters and indicating that it is ready to receive A-MPDU frames.

     • Buffer Size: The receiver declares its maximum receivable frame count based on its own capacity, which may override the sender’s suggestion. Consequently, the sender must limit the maximum number of aggregated frames to the capacity specified by the receiver.

2. Data Transmission and Block Acknowledgement

   Once the session is established, data transmission begins:

   • Sending the A-MPDU: The sender aggregates multiple MPDUs into a single A-MPDU and transmits it in one go.

   • Sending the Block ACK: After receiving the A-MPDU, the receiver no longer replies with individual ACKs for each subframe. Instead, it waits for a moment (or at a specific opportunity) and replies with a single BlockAck frame. This frame is the essence of the mechanism and contains a bitmap.

     • Bitmap: This is a binary sequence where each bit corresponds to a subframe within the A-MPDU.

       • bit = 1 indicates that the corresponding subframe was received successfully.

       • bit = 0 indicates that the corresponding subframe was lost or corrupted.

3. Selective Retransmission

   After receiving the BlockAck frame, the sender parses the bitmap to know exactly which subframes need to be retransmitted. It then re-aggregates all subframes marked with a 0 and sends them again, without retransmitting the ones that were already successful.

Block Ack Establishment and A-MPDU Exchange

The Ameba chip provides developers with granular control over the A-MPDU aggregation scheme, allowing them to enable/disable the mechanism and configure the number of aggregated frames.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

Parameter	Type	Value	Description	Default
ampdu_rx_enable	u8	0 / 1	Reject / Accept Block Ack Establishmen: whether the device will respond to an incoming ADDBA Request frame.	1
ampdu_tx_enable	u8	0 / 1	Off / On Block Ack Initiation: whether the device will initiate a Block Ack mechanism by sending an ADDBA Request frame.	1
rx_ampdu_num	u8	0 ~ 63	Defines the maximum number of MPDUs the device can receive within a single A-MPDU, this value is advertised in the Buffer Size field of the ADDBA Response frame. Note The skb_num_np value needs to be modified accordingly.	4
tx_ampdu_num	u8	0 ~ 63	Maximum number of MPDUs in a transmitted A-MPDU 0: Use the default setting, which sets the maximum aggregation number to 20. 1: The aggregation number is 1, which is equivalent to setting ampdu_tx_enable = 0. Maximum configurable value: 0x3F Note The actual maximum number of aggregated MPDUs is the minimum value between this parameter’s configuration and the Buffer Size field advertised in the recipient’s ADDBA Response frame.	0

ap_compatibilty_enabled

Some Access Points (APs) may not be fully compliant with the IEEE 802.11 specification, or their behavior might deviate from the standard in certain specific scenarios. To ensure compatibility with such non-standard behaviors and test environments, we provide necessary configuration options to control the device’s behavior in STA mode.

Parameter	ap_compatibilty_enabled
Type	u8
Value	BIT0	After an initial authentication (Auth) fails, the client proactively sends a Deauthentication (Deauth) frame before initiating the next re-authentication attempt. Core Problem: In environments with severe signal interference, authentication frames between the client and the Access Point (AP) may be lost. This can lead to a state mismatch between the two parties (e.g., the AP considers the authentication success, while the client is still attempting to authentication). This state inconsistency will cause the AP to reject subsequent re-authentication requests from the client. Strategy: The Deauth frame forcibly clears and synchronizes the connection state on both sides. This ensures that the subsequent re-authentication process can be correctly received and processed by the AP, thereby improving the connection success rate.
	BIT2	Proactively send a Deauthentication (Deauth) frame to the AP before initiating a new authentication (Auth) process. Core Problem: When a client device (e.g., a STA) experiences an abrupt power-off after establishing a connection with an Access Point (AP), the AP may not immediately detect that the client has gone offline. The AP will retain the client’s connection state information (session) for a period. Consequently, when the device powers on and attempts a fast reconnection, the AP rejects the new authentication or association request because it still considers the client to be “online”, leading to connection failure. Strategy: The Deauth frame is used to forcibly clear the AP’s cached, stale connection state for this client. This ensures that the AP treats the subsequent connection request as a brand-new session, thereby significantly improving the reconnection success rate after an unexpected power loss.
	BIT4	Addressing compatibility problems with the AP’s Block Acknowledgment (BA) mechanism, such as the timing of the ADDBA Response frame and issues with the reordering buffer timer settings.
默认值	0x07

RF Calibration

Radio Frequency (RF) Calibration is a crucial automatic calibration and compensation mechanism within a Wi-Fi chip. This mechanism ensures that the performance of the RF front-end remains in an optimal state. In a real-world environment, the chip’s RF circuitry can be affected by various factors that cause its performance to drift, such as temperature variations, channel changes, voltage fluctuations, and process variations.

Common calibration items include:

• TX Power Calibration: Ensures the chip’s actual transmit power matches the target power set by the software.

• Phase-Locked Loop Calibration (LCK): Guarantees that the Wi-Fi chip automatically, rapidly, and precisely tunes to the target channel frequency. This typically takes 50+ microseconds.

• DC Offset Calibration (DCK): Eliminates unwanted DC components in the receiver chain to prevent them from interfering with the demodulation of the useful signal. This typically takes tens of milliseconds.

• Transmitter signal Gap Calibration (TxGapK): During Wi-Fi signal transmission, power adjustments may require switching between the Power Amplifier (PA) and the Pre-Amplifier Driver. The delay in this switching action can, with some probability, create a brief power gap in the signal. This gap can disrupt the integrity of continuous symbol transmission, degrading performance. This typically takes 2 ~ 5 milliseconds.

• Local Oscillator Leakage Calibration (LOK): Suppresses the leakage of the carrier frequency component in the transmitted signal to purify the signal. This typically occurs in the microsecond range.

• In-phase/Quadrature Mismatch Calibration (IQK): Corrects the gain and phase imbalances between the I/Q signal paths. This is critical for ensuring modulation accuracy, which directly affects the Error Vector Magnitude (EVM). This typically takes anywhere from tens to hundreds of milliseconds.

• Digital Pre-Distortion Calibration (DPK): Its core purpose is to compensate for and correct the non-linear distortion of the PA in the Wi-Fi transmit chain to improve the transmission EVM. An actual power amplifier is nearly linear at low power outputs. As it approaches its maximum output power, it enters a non-linear or saturation region, meaning that as the input power increases, the output power fails to grow proportionally, leading to signal distortion.

  • The core idea of DPD technology is quite ingenious: “Since I know how the PA will distort the signal, I will first apply an ‘inverse distortion’ to the signal before it enters the PA.” This process is called pre-distortion. Thus, when the pre-distorted signal passes through the PA, the PA’s own “forward distortion” is canceled out by the pre-distortion, making the PA’s output signal linear.

  • To fully “learn” and “characterize” its complete distortion profile, the chip’s baseband processor generates a special wideband test signal. This test signal is characterized by a very high Peak-to-Average Power Ratio (PAPR), which drives the PA into its deep non-linear (saturation) region. To output this instantaneous high-power RF signal, the PA must draw a huge instantaneous peak current from its power supply. This current is typically several times the average current consumed by the Wi-Fi chip during normal data transmission, which leads to significant power consumption while improving PA performance.

RF calibration has an inherent dual nature. Its fundamental purpose is to combat performance loss by compensating for the effects of environmental factors (like temperature) on the RF circuitry, thereby maintaining optimal Wi-Fi performance. If RF calibration is neglected, long-term performance degradation is inevitable. However, at the same time, performing RF calibration is not “free”. The calibration process requires occupying RF resources, during which normal data transmission cannot occur. Users may observe brief network latency or a temporary drop in throughput. Especially in certain scenarios (such as channel switching), where multiple calibration items are performed, the calibration process needs to occupy RF resources for a longer time - leading to latency on the order of hundreds of milliseconds. For applications that are particularly sensitive to real-time responsiveness, such latency can cause a noticeable performance drop.

For this reason, we provide several configuration parameters that allow customers to make a balanced choice between real-time responsiveness and optimal performance.

Parameter
rf_calibration_disable	Type	u16
	Description	Disable Partial RF Calibration
	Value	0	All necessary calibration procedures shall be executed during RF calibration. Use Case: High-performance mode
		RTW_RFK_DIS_DPK	DPK is not performed during RF calibration. Use Case: Extreme power saving at the expense of transmit (TX) link performance.
	Default	0
dpk_peak_limit	Type	u8
	Description	Whether to limit the peak current when performing DPK. Note Valid when rf_calibration_disable != RTW_RFK_DIS_DPK
	Value	0	Default DPD Peak Current Use Case: Enhanced TX mode
		1	Limit DPD Peak Current Use Case: Balanced mode with reduced current for power saving while considering TX performance.
	Default	0
TX Performance: Normal DPD > Limiting the Peak Current of DPD > DPD Off
set_channel_api_do_rfk	Type	u8
	Description	Whether to perform RF calibration when switching channels by calling wifi_set_channel().
	Value	0	Disabled, prioritizing low latency.
		1	Enabled, prioritizing signal quality.
	Default	1

country_code

Please refer Country Code Configuration Table

bw_40_enable

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

Allows the customer to configure whether to enable 40MHz bandwidth. The default configuration is disabled: wifi_user_config.bw_40_enable = 0。

freq_band_support

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

Allows users to configure the supported Wi-Fi bands.

Parameter	freq_band_support
Type	u8
Value	RTW_SUPPORT_BAND_2_4G	Only Support 2.4G.
	RTW_SUPPORT_BAND_5G	Only Support 5G.
	RTW_SUPPORT_BAND_2_4G_5G_BOTH	Supports both 2.4G and 5G.
	RTW_SUPPORT_BAND_MAX	Defaults to the chip’s maximum supported capability.
Default	RTW_SUPPORT_BAND_MAX

rtw_802_11d_en

Please refer 802.11d

Wi-Fi reconnection

Please refer to the descriptions in the sections STA Auto-reconnect on Power-up and STA Auto-reconnect on Disconnection.

no_beacon_disconnect_time

Ameba Wi-Fi implements a link-loss detection mechanism based on an inactivity timer. If the client receives no frames from the Access Point (AP) within a configurable period, it will consider the connection lost.

The timeout period is defined by the wifi_user_config.no_beacon_disconnect_time parameter, with the total duration calculated as: Timeout (seconds) = wifi_user_config.no_beacon_disconnect_time * 2. Once this timer expires and the client has still not received any frames, the firmware determines the link is down and performs the following actions:

1. Terminate the internal connection to the AP.

2. Report a “Wi-Fi disconnected” status to upper-layer applications (e.g., the operating system).

3. Initiate an auto-reconnection or attempt to roam to a more suitable AP.

TRX Buffer

The Ameba Wi-Fi solution uses WHC IPC as its basic communication architecture. For more details, refer to the Wi-Fi Basic Architecture chapter.

Data Frame transmission under the WHC IPC architecture

In its data link layer, Ameba Wi-Fi maintains a SKB memory pool to manage data received from the LWIP (Ethernet Frames) or data transmitted via application calls wifi_send_raw_frame().

• Transmit (TX): Under the WHC IPC architecture, packets prepared by an application for transmission are first copied to an SKB on the AP core. Information about this AP SKB is then passed to the NP core via IPC. The NP core performs frame conversion and then transmits the data. Therefore, when copying data into the AP SKB, the necessary space (headroom) for frame conversion must be reserved.

• Recept (RX): For reception under the WHC IPC architecture, incoming packets are first delivered by the hardware to an SKB on the NP core. The NP core strips some of the frame conversion information and passes information about the NP SKB to the AP core via IPC. The AP core then delivers the data up to the application.

Additionally, in the Ameba Wi-Fi solution, the processing of management and control frames for wireless network connections is handled entirely by the NP core, meaning they only occupy NP SKBs.

Management/Control Frame transmission under the WHC IPC architecture

Ameba Wi-Fi provides configuration parameters for data storage at the data link layer, allowing customers to adjust the number and size of AP/NP SKBs based on their use case requirements (e.g., throughput, or code size reduction).

• The number of AP SKBs mainly considers the requirements for transmitting data frames.

• The number of NP SKBs needs to consider multiple factors:

  • RX Data Frame: >= wifi_user_config.rx_ampdu_num SKBs, accounting for Frame Aggregation Configuration and throughput requirements.

  • Management Frame TX/RX: 2 SKBs

  • HW/SW Interface: 4 SKBs (optional)

• The SKB size is set based on the actual size of the transmitted data.

  • Data size that can be stored for TX: SKB Size - TX Headroom

  • Data size that can be stored for RX: SKB Size - RX Headroom

Note

For the selected number and size of SKBs, Ameba Wi-Fi performs memory allocation during the chip startup phase. This may cause the RAM reserved for the NP core by default to be insufficient. This can be modified by referring to RAM Layout .

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

Reference Value

Parameter	Size (Bytes)	Parameter	Size (Bytes)
TX Headroom	78	TX Headroom	56

Configurable Parameters

Parameter	Type	Value	Description	Default
skb_num_np	s32	>= wifi_user_config.rx_ampdu_num + 6	Configure the NP core’s SKB count.	10
skb_num_ap	s32	>= 1	Configure the AP core’s SKB count.	4
skb_buf_size	u32	0	Use the default configuration with an SKB size of 1632 bytes.	0
		(118, 4095]	Configure SKB Size Note The provided skb_buf_size value is internally adjusted for 32-byte cache alignment. For instance, if skb_buf_size is set to 1117, the effective SKB size will be 1120 bytes. According to the IEEE 802.11 standard, the maximum length for a single frame is 4095 bytes.

force_cts2self

In mixed-mode environments where legacy devices (e.g., IEEE 802.11b/g) coexist within the same Basic Service Set (BSS) or its vicinity, the CTS-to-self mechanism can be employed. This provides transmission protection, reducing the number of frame retransmission exchanges and thereby enhancing throughput.

While modern high-throughput data frames (e.g., 802.11n/ac/ax) are structured with a forward-compatible legacy preamble, this standard protection method is not always foolproof. In theory, legacy devices can decode this preamble and defer their own transmissions to avoid collision. However, in complex, high-interference environments, legacy devices might mis-decode the preamble, causing the protection to fail.

The CTS-to-self mechanism offers a more robust alternative. It involves transmitting a CTS frame at a very low basic rate (e.g., 1 or 6 Mbps) that all IEEE 802.11 devices, both old and new, can reliably decode. This forces all nearby devices to remain silent, effectively clearing the channel for the subsequent high-rate data transmission to proceed without contention.

However, the CTS-to-self mechanism introduces additional signaling overhead. The airtime consumed by the CTS frame can be seen as a necessary “channel insurance” premium, paid to ensure the successful delivery of the subsequent high-rate data frame. This overhead is not a single figure but is composed of a fixed procedure and a calculable duration:

• Channel Sensing

  • Before transmitting any frame, a station must first sense the channel to ensure it is idle for a specific duration. This period is typically the DIFS (Distributed Inter-Frame Space) or, the AIFS (Arbitration Inter-Frame Space) for QoS-prioritized traffic.This is a mandatory part of the core CSMA/CA (Carrier Sense Multiple Access with Collision Avoidance) rules defined in the IEEE 802.11 protocol.

• CTS Frame Transmission Time (Core Overhead)

  • The CTS-to-self frame is compact, consisting of: Frame Control (2 bytes) + Duration (2 bytes) + Receiver Address (RA) (6 bytes) + Frame Check Sequence (4 bytes) = 14 bytes.

  • To ensure all legacy stations can interpret it, the CTS frame must be sent at one of the lowest supported basic rates, typically 6 Mbps.

  • The transmission includes a fixed 20 µs physical layer legacy preamble (L-STF, L-LTF, L-SIG).

  • Total Transmission Time: 20 µs (Preamble) + (14 bytes * 8 bits/byte) / 6 Mbps ≈ 38.7 µs.

• Short Inter-Frame Space (SIFS)

  • After sending the CTS frame, the station must wait for a SIFS period before sending the actual data frame. SIFS is the shortest inter-frame space, used to separate consecutive frames within a single operational sequence (like a CTS and the data frame it protects).

In total, the on-air time for the CTS frame alone is nearly 40 µs. When combined with channel access delays like DIFS (e.g., 34 µs for IEEE 802.11g) and SIFS (e.g., 16 µs for IEEE 802.11g), a complete CTS-to-self protection sequence consumes approximately 90 ~ 100 µs of channel time before the actual data frame is even transmitted.

Naturally, this overhead does not have a uniform impact. Its significance varies depending on the size of the transmitted data packet.

1. High Impact on Small Packets: If a station needs to send a very small packet whose own transmission time is only a few dozen microseconds, adding ~100 µs of protection overhead is highly inefficient. The signaling cost would exceed the payload’s transmission cost.

2. More Efficient for Large Packets: Conversely, for a large data block like an Aggregated MAC Protocol Data Unit (A-MPDU) that might take 2000 µs to transmit, an additional 100 µs of protection overhead accounts for less than 5% of the total time. Trading 5% of overhead to achieve a near-certain transmission success rate is an extremely worthwhile trade-off.

Consequently, the Ameba chip provides a parameter that allows users to enable or disable the CTS-to-self mechanism based on their specific scenario. By default, this feature is disabled by setting wifi_user_config.force_cts2self = 0.

MCC Configuration

Multichannel Concurrent (MCC) mode is a type of Wi-Fi concurrency mode that enables a single Wi-Fi radio chip to simulate maintaining multiple wireless connections simultaneously by rapidly switching between different channels.

The Ameba device uses Time Division Multiplexing Access (TDMA) to divide a Target Beacon Transmission Time (TBTT) interval into time slots, allocating them to different roles based on a preset ratio.

MCC time-slot switching mechanism

Parameter	Type	Value	Description	Default
en_mcc	u8	0 / 1	Disable / Enable MCC mechanism	0
mcc_force_p1_slot_ratio	u8	[12, 80]	Sets the duty cycle for port1 (SoftAP mode) in the MCC configuration. For instance, 44 assigns a 44% duty cycle to port1, leaving the remaining 56% for port0 (STA mode).	44

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

1. Modify the Wi-Fi user configuration to enable MCC functionality..

   wifi_user_config.concurrent_enabled = 1;
   wifi_user_config.en_mcc = 1;
   wifi_user_config.mcc_force_p1_slot_ratio = 44;
   

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

   ./menuconfig.py
   

3. Locate CONFIG WIFI > Enable MCC, select Enable MCC, then save and exit.

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

probe_hidden_ap_on_passive_ch

To discover an AP with a hidden Service Set Identifier (SSID), a client must send a unicast Probe Request that specifies the SSID.

On the other hand, standard passive scanning requires a client to passively listen on each channel, discovering APs solely by receiving their Beacon Frames. This purely passive mechanism is inherently unable to discover hidden APs.

To resolve this conflict, a common strategy is for the client to actively send a unicast Probe Request after detecting a Beacon Frame from a hidden AP (which has an empty SSID field). This allows the client to obtain the AP’s complete network information.

To cater to different use cases, Ameba Wi-Fi provides a configuration parameter. This allows customers to choose whether to perform a strict, silent passive scan or to actively send Probe Request during the scan period to ensure the discovery of and connection to hidden APs.

Parameter	probe_hidden_ap_on_passive_ch
Type	u8
Value	0	Strict Passive Scan Mode Behavior: On passive scan channels, the device performs silent listening only and never actively sends any Probe Request frames. Use Case: For scenarios requiring a pure passive scan to achieve minimum power consumption or to avoid any wireless transmissions. In this mode, the device cannot discover hidden APs on these channels.
	1	Hybrid Scan Mode (Default) Behavior: When a beacon frame from a hidden AP (i.e., a beacon without an SSID) is detected on a passive scan channel, the device actively sends a unicast Probe Request to obtain its full information. Use Case: To ensure the discovery and connection of hidden APs, even if they are located on channels designated for passive scanning. This is the recommended setting for maximum connection compatibility.
Default	1

concurrent_enabled

Please refer SoftAP and STA Concurrent

rate_mask_cck

While CCK (Complementary Code Keying) rates offer extended coverage, their low transmission speeds lead to poor throughput. For example, transmitting a 1.5KB packet at the CCK 1M rate takes approximately 13 milliseconds. This is not ideal for customers with specific throughput requirements. Consequently, a parameter is provided to allow users to disable some or all CCK rates based on their application.

This parameter utilizes a rate mask to precisely control the set of available CCK rates for data frame transmission.

rate_mask_cck is a bitmask where each bit corresponds to a specific CCK rate. It works as follows:

• Setting a bit to 1: Masks (or disables) the corresponding rate. When a bit is set to 1, the device’s rate adaptive algorithm will not select this rate for transmission.

• Setting a bit to 0: Allows the corresponding rate to be used.

Parameter	rate_mask_cck
Type	u8
Value	BIT0	Mask CCK 1Mbps
	BIT1	Mask CCK 2Mbps
	BIT2	Mask CCK 5.5Mbps
	BIT3	Mask CCK 11Mbps
Default	0x0

WPS Configuration

Wi-Fi Protected Setup (WPS) is a network security standard created by the Wi-Fi Alliance to simplify the process for average users to connect devices to a secure wireless network. Its core objective is to allow users who are unfamiliar with wireless security settings to quickly and securely add new wireless devices (such as smartphones, printers, smart TVs, etc.) to their network without needing to enter a complex Wi-Fi password.

WPS primarily works through several methods, with the first two being the most common:

1. Push Button Configuration (PBC)

   This is the most popular and simplest method. Its workflow is as follows:

   • The user presses a physical or virtual “WPS” button on the wireless router.

   • The router then opens a short pairing window (typically 2 minutes).

   • During this time, the user also selects the WPS connection option on the device to be connected (e.g., a smartphone or printer).

   • The two devices will automatically negotiate security settings and complete the connection, all without requiring a password.

2. Personal Identification Number (PIN)

   This method uses an 8-digit PIN for authentication and has two modes:

   • Device-provided PIN: Some devices without buttons (like network printers) will display a randomly generated PIN on their screen. You need to enter this PIN into the router’s management interface, and the router will then authorize the device to connect.

   • Router-provided PIN: Every WPS-enabled router has a fixed factory PIN (usually found on a label on the back of the router). When you select the WPS connection option on a new device, you can complete the connection by entering this router PIN.

   • Note: This PIN-based method has a serious security vulnerability.

3. Near Field Communication (NFC)

   • Workflow: Bring an NFC-enabled device (like a smartphone) close to an NFC-enabled router. The two can automatically exchange network credentials and establish a connection by simply tapping.

   • Prevalence: This method is not common, as it requires both the router and the client device to support NFC.

The Ameba Wi-Fi solution allows devices to adjust the number of retries and the retry interval after a failed WPS connection attempt, ensuring the robustness and user experience of WPS connections across different scenarios.

Parameter	Type	Value	Description	Default
wps_retry_count	u8	—	Maximum number of automatic retries after the initial WPS connection attempt fails.	4
wps_retry_interval	u8	—	Time interval between automatic retries, in milliseconds.	5000

keepalive_interval

This parameter is used in Wi-Fi STA mode to configure the period of an automatic “keep-alive” mechanism, in seconds. Its core purpose is to maintain the Wi-Fi connection by periodically sending a special packet when there is no active data transmission between the device and the Access Point (AP), preventing disconnection by the router due to long periods of inactivity.

Core Function

In many Wi-Fi networks, APs implement an “idle timeout” mechanism to optimize performance and manage connected clients. If a client device has no data communication within a set period (e.g., 5 minutes), the AP might assume the device is offline or no longer needs the network and will actively disconnect it to free up network resources.

For many devices that require a long-term, stable online connection (especially IoT devices), this mechanism can lead to frequent disconnections and reconnections. The keepalive_interval parameter is designed to solve this problem.

How It Works

When keepalive_interval is set to a value greater than 0, the device starts an internal timer. Whenever the timer reaches the set number of seconds, the device automatically sends a Null Data Packet to the AP it is connected to.

• Null Data Packet: This is a special type of Wi-Fi data frame that contains no upper-layer application data. It serves merely as a “heartbeat” signal.

• Function: When the AP receives this Null Data packet, it resets the idle timer for that device, thus considering the device to be still active. In this way, even if the device’s application layer has no data transmission for a long time, its underlying Wi-Fi connection can be maintained.

Based on considerations for connection stability and device power consumption, the default configuration is set to wifi_user_config.keepalive_interval = 20.

rx_cca_thresh

This parameter configures the minimum receivable signal strength threshold for the Wi-Fi module when receiving data, measured in dBm.

When the received wireless signal strength (RSSI) is below this threshold, the Wi-Fi hardware or low-level driver will ignore the packet, preventing it from being processed further. This effectively adjusts the energy detection threshold of the Clear Channel Assessment (CCA) mechanism, helping the system to filter out weak, irrelevant signals and thereby optimize performance and power consumption in specific scenarios.

Parameter	rx_cca_thresh
Type	s8
Value	0	Reserved value. Enables the dynamic threshold mechanism When set to 0, the system uses the Realtek driver’s built-in dynamic adjustment algorithm. This algorithm automatically calculates and sets an optimal reception threshold based on the current network environment (e.g., channel interference, connection quality). This i the default and recommended setting, suitable for most application scenarios.
	[-100, 0)	Manually specifies a static threshold The user can manually set a fixed received signal strength threshold (in dBm). For example, if set to -85, any Wi-Fi packet with a signal strength below -85 dBm will be ignored by the hardware. Use Case1: High-Density or High-Interference Environments. In environments with dense Wi-Fi device deployment and severe channel interference (e.g., exhibitions, office buildings), the air may be filled with weak signals from distant or irrelevant APs. By raising this threshold, the weak interfering signals can be effectively filtered out. This reduces the load on the low-level processor and allows it to focus on signals within the effective communication range, thereby improving connection stability and data throughput. Use Case2: Specific Communication Range Control. If your application requires the device to interact only with strong-signal APs within a specific physical range, you can set a higher threshold to indirectly implement “distance filtering”, ensuring the device only connects to very close APs.
Default	1

Wi-Fi R-Mesh Related

For detailed information, refer to Wi-Fi R-Mesh - Programming Interface chapter.