Wi-Fi 开发者配置

所有配置参数统一通过 wifi_user_conf 结构体进行管理。本节将详细介绍该结构体中的各项参数及其配置方法。

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

github source code

• ameba_wificfg.c

rtw_edcca_mode

能量检测-信道空闲评估机制（Energy-Detection Clear Channel Assessment）是一种管理无线设备访问信道的技术。它通过对环境中的信号能量进行监测，如果能量低于预定义的阈值，则信道被视为 “空闲”，并且允许设备进行传输。该过程最大限度的减少数据碰撞，确保多设备可以在同频进行有效传输。

参数	rtw_edcca_mode
类型	u8
取值	RTW_EDCCA_NORM	根据实时信号强度测量值动态调整 EDCCA 阈值 使用场景：通过忽略小能量的干扰信号来增加传输机会
	RTW_EDCCA_ADAPT	ETSI Adaptivity 测试模式，固定阈值 使用场景：Wi-Fi 法规 - Adaptivity 测试
	RTW_EDCCA_CS	日本 Carrier Sense 测试模式，固定阈值 使用场景：Wi-Fi 法规 - Adaptivity 测试
	RTW_EDCCA_DISABLE	关闭 EDCCA 模式
默认值	RTW_EDCCA_NORM

tx_pwr_table_selection

请参考 发射功率表介绍

rtw_trp_tis_cert_en

客户会需要评估终端的天线性能和整机射频链路的好坏，也即针对射频性能做一些测试，该测试也被称为 OTA（Over-The-Air）测试，一般通过总辐射功率和总全向灵敏度这两个关键指标来衡量，通常在电波暗室（Anechoic Chamber）中进行测试。

• 总辐射功率（Total Radiated Power）：指设备在各个方向上发射的射频功率的总和，它衡量的是设备的发射性能。

• 总全向灵敏度（Total Isotropic Sensitivity）：指设备在各个方向上能够成功解调信号所需的最低接收功率的平均值，它衡量的是设备的接收性能。

因为匹配不同测试环境的需求，需要做一些定制化的处理，根据如下表格进行配置：

参数	rtw_trp_tis_cert_en
类型	u8
取值	RTW_TRP_TIS_DISABLE	关闭 TRP/TIS 测试定制化处理 使用场景：非 TRP/TIS 认证
	RTW_TRP_TIS_NORMAL	打开 TRP/TIS 测试定制化处理 使用场景：TRP/TIS 认证
默认值	RTW_TRP_TIS_DISABLE

wifi_wpa_mode_force

该参数用于强制指定一个特定的 Wi-Fi 保护接入（Wi-Fi Protected Acess）模式。

参数	wifi_wpa_mode_force
类型	u8
取值	RTW_WPA_AUTO_MODE	跟随 AP 能力自动选择 WPA 模式	兼容性问题排查 某些设备在处理 WPA 混合模式时可能存在问题，通过强制使用单一模式可以绕过有问题的协商过程，帮助设备成功连接。 这是一种常见的调试手段，用于定位问题是否出在安全模式的协商环节。 自动化测试 在某些测试环境中，测试人员需要验证设备在各种特定安全模式下的功能。
	RTW_WPA_ONLY_MODE	仅支持 WPA 模式
	RTW_WPA2_ONLY_MODE	仅支持 WPA2 模式
	RTW_WPA3_ONLY_MODE	仅支持 WPA3 模式
	RTW_WPA_WPA2_MIXED_MODE	支持 WPA/WPA2 模式
	RTW_WPA2_WPA3_MIXED_MODE	支持 WPA2/WPA3 模式
默认值	RTW_WPA_AUTO_MODE

tdma_dig_enable

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

不支持

antdiv_mode

请参考 Wi-Fi ANTDIV - 软件配置 获取详细信息。

SoftAP 配置

配置请参考 SoftAP 相关配置 章节。

省电配置

配置请参考 Wi-Fi 低功耗 章节。

UAPSD 配置

非调度自动省电模式（Unscheduled Automatic Power Save Delivery，U-APSD）是 Wi-Fi 多媒体扩展规范（WMM, Wi-Fi Multimedia）的一部分，属于 WMM-Power Save（WMM-PS）机制中的一种，旨在为对延迟敏感的实时应用（如 VoIP 语音通话、视频流）在提供低延迟的同时，最大限度地延长电池供电设备（如智能手机、IoT 设备）的续航时间。

它的核心思想是：让客户端设备（STA）来决定何时醒来获取数据，而不是被动地等待固定的时间点。

U-APSD 的工作时序

参数	类型	取值	描述	默认值
uapsd_enable	u8	0 / 1	关闭/使能 U-APSD 机制	0
uapsd_max_sp_len	u8	单个服务周期内允许交换的 MAC 服务数据单元（MAC Service Data Unit）数目		0
		RTW_UAPSD_NO_LIMIT	一个服务周期内允许AP 传输所有缓存数据帧
		RTW_UAPSD_TWO_MSDU	一个服务周期内最多允许两笔数据帧传输
		RTW_UAPSD_FOUR_MSDU	一个服务周期内最多允许四笔数据帧传输
		RTW_UAPSD_SIX_MSDU	一个服务周期内最多允许六笔数据帧传输
uapsd_ac_enable	u8	启用 U-APSD 的 AC 类别		0
		BIT0	AC_VO
		BIT1	AC_VI
		BIT2	AC_BK
		BIT3	AC_BE

帧聚合设定

帧聚合机制是 IEEE 802.11n 标准引入的一项特性，并在后续标准（如 802.11ac/ax）中得到增强。其主要目的是通过将多个较小的数据帧合并成一个较大的传输单元，来提高媒体访问控制（Media Access Control）层的效率。这个过程减少了与单独传输每个帧相关的大量开销，例如物理层前导码、帧间间隔（Inter-Frame Spacing）和确认帧（ACK），通过最小化这些开销，帧聚合机制能够显著提升网络的总吞吐量。

IEEE 802.11 标准定义了两种主要的帧聚合方法：

1. 聚合 MAC 服务数据单元（Aggregate MAC Service Data Unit， A-MSDU）

   • 机制：该方法将多个来自上层的 MSDU（例如 IP 数据包）聚合到一个 MAC 协议数据单元（MAC Protocol Data Unit）中。整个聚合后的载荷会作为一个带有单个 MAC 头部的帧被发送出去。

   • 优点：显著减少了 MAC 头部的开销。

   • 缺点：如果聚合帧在传输过程中有任何部分损坏，整个 A-MSDU 帧都必须重传，因为它由单个帧校验序列（Frame Check Sequence）保护，并由单个 ACK 帧进行确认。

2. 聚合 MAC 协议数据单元（Aggregate MAC Protocol Data Unit， A-MPDU）

   • 机制：该方法将多个完整的、各自带有独立 MAC 头部和 FCS 的 MPDU 聚合在一起，形成一个由物理层处理的传输块。

   • 优点：它对传输错误的鲁棒性更强。聚合中的每个子帧（MPDU）都可以使用一个块确认（Block Acknowledgement） 帧进行单独确认。如果某个子帧丢失或损坏，只需要重传该特定子帧，而无需重传整个聚合帧。

   • 应用：由于其稳健性，A-MPDU 是现代 Wi-Fi 标准中应用更广泛且为强制支持的聚合方法。

IEEE 802.11n 标准提到使用 A-MPDU 需要先建立块确认机制（Block Acknowledgement，Block ACK），其工作流程通常分为三个阶段：

1. 建立 Block ACK 会话

   在传输 A-MPDU 之前，发送方（Originator）和接收方（Recipient）需要先“商量好”使用块确认机制。这个过程通过交换管理帧来完成：

   • 添加块确认请求（Add Block Acknowledgment Request）：发送方会向接收方发送一个 ADDBA Request 帧。该帧中包含了关键参数，如：

     • 流量标识符（TID）：指明是为哪一类业务（如视频、语音、背景数据等）建立的会话。

     • 缓冲区大小（Buffer Size）：告知接收方自己一次最多会发送多少个帧，以便接收方预留足够的缓冲区。

   • 添加块确认响应（Add Block Acknowledgment Response）：接收方收到请求后，如果同意建立会话，就会回复一个 ADDBA Response 帧，确认会话参数（包括缓冲区大小和流量标识符）并表示自己已准备好接收 A-MPDU 帧。

     • 缓冲区大小（Buffer Size）：告知发送方自己一次最多可接收的帧数目，以自己能力为准，可不遵循发送方的建议值。发送方发送最大的聚合帧数目以接收方能力讯息为准。

2. 数据传输与块确认

   会话建立后，数据传输正式开始：

   • 发送 A-MPDU：发送方将多个 MPDU 聚合在一起，形成一个 A-MPDU，然后一次性发送出去。

   • 发送 Block ACK：接收方在收到 A-MPDU 后，不再为每个子帧单独回复 ACK。而是等待片刻（或在特定时机）回复一个 BlockAck 帧，其内部包含一个位图表征所有 MPDU 序列的接收情况。

3. 选择性重传

   发送方收到 BlockAck 帧后，解析其中的位图，就能准确知道哪些子帧需要重传。然后，它会将所有标记为 0 的子帧重新聚合，再次发送，而无需重传已经成功的子帧。

块确认机制建立及 A-MPDU 交互过程

Ameba 芯片针对 A-MPDU 聚合方案为开发人员提供了粒度控制，允许开关该机制以及聚合机制下针对聚合数目进行配置。

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

参数	类型	取值	描述	默认值
ampdu_rx_enable	u8	0 / 1	拒绝/接受建立块确认机制，是否响应 ADDBA Request 帧	1
ampdu_tx_enable	u8	0 / 1	不发起 / 发起建立块确认机制，是否发送 ADDBA Request 帧	1
rx_ampdu_num	u8	0 ~ 63	可接收 A-MPDU 的最大 MPDU数目，若是作为块确认机制的接收方，携带在 ADDBA Resp 帧的 Buffer Size 字段 备注 需要同步修改 skb_num_np	4
tx_ampdu_num	u8	0 ~ 63	传输 A-MPDU 时最大聚合的 MPDU 数目，若是作为块确认机制的发起方，携带在 ADDBA Req 帧的 Buffer Size 字段 0：程序默认值，聚合最大数目为 20 1：聚合数目为 1，等价于 ampdu_tx_enable = 0 最大可允许配置值： 0x3F 备注 实际最大聚合数目取决于该配置参数和接收方 ADDBA Resp 帧携带的 Buffer Size 中的最小值	0

ap_compatibilty_enabled

一些接入点设备不按照 IEEE 802.11 规范进行工作或者在某些特殊场景的测试行为和标准行为有一定的偏差，为了兼容非标测试场景，我们提供了一些必要的配置来控制 STA 模式下设备的行为。

参数	ap_compatibilty_enabled
类型	u8
取值	BIT0	在首次认证（Auth）失败后、发起下一次重认证前，客户端会主动发送一个去认证帧（Deauth Frame）。 核心问题：在信号干扰严重的环境下，客户端与接入点（AP）之间的认证帧可能丢包，导致双方的连接状态不一致（例如，AP 认为认证已成功，而客户端仍在尝试认证）。这种状态不一致会导致 AP 拒绝客户端后续的重认证请求。 策略：通过 Deauth 帧强制清空并同步双方的连接状态，确保后续的重认证过程能够被 AP 正确接收和处理，从而提高连接成功率。
	BIT2	在设备发起新的认证（Auth）流程之前，主动向 AP 发送一个去认证帧（Deauth Frame） 核心问题：当客户端设备（如 STA）在与接入点（AP）建立连接后发生异常断电，AP 端可能无法立即感知到客户端已离线。AP 会在一段时间内继续保留该客户端的连接状态信息（会话）。当设备上电并尝试快速重连时，AP 会因为认为该客户端“仍在线”而拒绝新的认证或关联请求，导致连接失败 策略：通过 Deauth 帧强制清除 AP 上缓存的关于此客户端的旧连接状态，确保 AP 将后续的连接请求视为一个全新的会话，从而显著提高异常断电后的重连成功率。
	BIT4	解决 Bloack Acknowledgment 机制和接入点（AP）的兼容性问题，比如 ADDBA Response 帧回复时机，重排序缓冲区定时器设定问题等。
默认值	0x07

RF 校准

射频校准（Radio Frequency Calibration）是 Wi-Fi 芯片内部一个重要的自动校准和补偿机制，该机制可以保证射频前端（Radio Front-End）的性能始终处于最佳状态。实际环境中，芯片的射频电路会受到多种因素的干扰和影响导致性能发生偏移，如温度变化、信道变化、电压波动、工艺偏差等。

常见的校准项目包括：

• 功率校准 （TX Power Calibration）：确保芯片的实际发射功率与软件设定的目标功率一致。

• 锁相校准（Phase-Locked Loop Calibration）：保证 Wi-Fi 芯片自动、高速且极其精确地“调谐”到目标信道频率。通常在 50+ 微秒级。

• 接收器直流偏置校准（DC Offset Calibration）: 消除接收链路中无用的直流分量，避免其影响有用信号的解调。通常在十毫秒级。

• 发射器功率间隙校准（Transmitter Signal Gap Calibration）：Wi-Fi 信号发射过程中因为功率的调整需要在功率放大器（Power Amplifier）和前级放大器 （Pre-Amplifier Driver） 之间切换，切换动作的时延会一定概率在信号功率上产生一个短暂的功率间隙，这个功率间隙可能破坏信号连续符号传输的完整性，降低性能。通常 2 ~ 5 毫秒。

• 本振泄漏校准 （Local Oscillator Leakage Calibration）：抑制发射信号中泄漏的载波频率成分，净化信号。通常在微秒级。

• 同相/正交分量不匹配校准 （In-phase/Quadrature Mismatch Calibration）：校正 I/Q 两路信号的增益和相位不平衡，这是保证调制精度（影响误差矢量幅度（Error Vector Magnitude））的关键。通常几十毫秒 ~ 百毫秒不等。

• 数字预失真校准（Digital Pre-Distortion Calibration）：其核心是补偿和校正 Wi-Fi 发射链路中 PA 的非线性失真来提升发射的 EVM。实际的功率放大器低功率输出是接近线性。当其接近最大输出功率时会进入非线性区或者饱和区，也即随着输入功率的增加，输出功率无法成比例增长从而导致信号失真。通常 10 ~ 50 毫秒。

  • DPD 技术的核心思想非常巧妙：既然我知道 PA 会如何“扭曲”信号，那我就在信号进入 PA 之前，先对其进行一次“反向的扭曲”，也即预失真，这样被预先“反向扭曲”的信号经过 PA 时，PA 自身的“正向扭曲”正好与预失真相互抵消，使得 PA 的输出信号就变得线性。

  • 校准算法为了完整地“学习”和“描绘”出其整个失真特性，芯片的基带处理器会生成一个特殊的宽带测试信号，这个测试信号的特点是具有很高的峰均功率比 PAPR（Peak-to-Average Power Ratio），这样就可以驱动 PA 进入其深度非线性区（饱和区）。为了输出这个瞬时的高功率射频信号，PA 必须从其电源汲取一个巨大的瞬时峰值电流（Peak Current of DPD），这个电流通常是 Wi-Fi 芯片在正常数据传输时平均电流的好几倍，这会导致在提升 PA 性能的同时带来极大的功耗。

射频校准存在一个固有的双重特性。他的根本目的在于对抗性能损耗：通过补偿环境因素（如温度）对射频电路的影响，来维持 Wi-Fi 的最佳性能。若忽略 RFK，长期的性能衰退将不可避免。但与此同时，RFK 的执行并非“免费”的。校准过程需要占用射频资源，无法进行正常的数据收发，用户可能观察到短暂的网络延迟或者吞吐量临时下降。尤其某些场景下（如信道切换） RFK 项目多，校准过程需要更长时间占用射频资源-大约在百毫秒级别的延迟，对于特别关注响应实时性的应用场景，这样的延迟会带来明显的性能下降。

基于此我们提供了部分配置参数允许客户在实时性和性能上做一个均衡的选择。

参数
rf_calibration_disable	类型	u16
	描述	配置是否关闭部分 RF 校准机制。
	取值	0	射频校准场景下所需校准项目均要进行。 使用场景：射频性能优先。
		RTW_RFK_DIS_DPK	射频校准时不做 DPK。 使用场景：极致省电而牺牲发射链路性能。
	默认值	0
dpk_peak_limit	类型	u8
	描述	配置做 DPK 时是否限制峰值电流。 备注 rf_calibration_disable != RTW_RFK_DIS_DPK 时有效。
	取值	0	默认 DPD 峰值电流。 使用场景：发射链路性能优先。
		1	限制 DPD 峰值电流。 使用场景：减小电流来降低功耗，并兼顾部分发射链路性能。
	默认值	0
TX 性能：Normal DPD > Limiting the Peak Current of DPD > DPD Off
set_channel_api_do_rfk	类型	u8
	描述	调用 wifi_set_channel() 切换信道时是否做射频校准。
	取值	0	不做，实时性优先。
		1	做，性能优先。
	默认值	1

country_code

请参考 国家码配置表

bw_40_enable

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

允许客户配置是否启用 40MHz 带宽，默认配置为不启用 wifi_user_config.bw_40_enable = 0。

freq_band_support

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

允许客户配置 Wi-Fi 芯片支持的频段。

参数	freq_band_support
类型	u8
取值	RTW_SUPPORT_BAND_2_4G	仅支持 2.4G
	RTW_SUPPORT_BAND_5G	仅支持 5G
	RTW_SUPPORT_BAND_2_4G_5G_BOTH	2.4G 和 5G 均支持
	RTW_SUPPORT_BAND_MAX	默认配置为芯片支持的最大能力
默认值	RTW_SUPPORT_BAND_MAX

rtw_802_11d_en

请参考 802.11d

Wi-Fi 重连配置

请参考 STA 上电自动重连 和 STA 断线自动重连 章节描述。

no_beacon_disconnect_time

Ameba Wi-Fi 实现了一个基于“无活动计时器”的链路丢失检测机制：如果客户端在一段可配置的时间内没有从接入点（Access Point）收到任何帧，就会认为连接已丢失。

这个超时周期由 wifi_user_config.no_beacon_disconnect_time 参数定义，总时长计算方式为 超时时间（秒）= wifi_user_config.no_beacon_disconnect_time * 2。一旦设定的计时器完全走完，且客户端仍然没有收到任何帧，固件就会判定链路已断开，并执行以下操作：

1. 内部断开与该 AP 的连接。

2. 向上层应用（如操作系统）报告状态：“Wi-Fi 已断开连接”。

3. 发起自动重连或者漫游到更合适的 AP。

TRX Buffer

Ameba Wi-Fi 解决方案选用 WHC IPC 作为基本的通信架构，详细介绍参见 Wi-Fi 基础架构 章节。

WHC IPC 架构下（Data）数据传输流程

Ameba Wi-Fi 在数据链路层存在一个 SKB 的内存池来管理接收到的协议栈数据（Ethernet Frame）或者应用程序调用 wifi_send_raw_frame() 传输的数据。

• WHC IPC 架构下应用程序准备传输（TX）的报文先转存到 AP 核的 SKB 中，然后通过 IPC 将 AP SKB 的信息传递到 NP 核，NP 核会进行帧转换然后 TX 出去。数据在拷贝到 AP SKB 时需要考虑帧转换所需要预留的空间。

• WHC IPC 架构下准备接收（RX）的报文先由硬件传递至 NP 核的 SKB 中，NP 核去除部分帧转换信息后将 NP SKB 的信息通过 IPC 传递到 AP 核， AP 进而将数据递交到应用程序。

另外 Ameba Wi-Fi 针对无线网络连接的管理帧/控制帧的处理均在 NP 核下，也即只占用 NP SKB。

WHC IPC 架构下管理帧/控制帧传输流程

Ameba Wi-Fi 提供了数据链路层数据的存储配置参数，允许客户根据场景需求（比如吞吐量、代码缩减等）来调整 AP/NP 的 SKB 数目及大小。

• AP SKB 数目的选择主要考虑传输数据帧的要求。

• NP SKB 数目的选择需要考虑多重因素

  • 数据帧接收：预留 SKB >= wifi_user_config.rx_ampdu_num （需要综合考虑 帧聚合设定 和吞吐量需求）

  • 管理帧传输/接收：预留 2 个 SKB

  • 硬件/软件接口：预留 4 个 SKB（可选）

• SKB 大小根据实际传输数据的大小进行设定。

  • TX 能存储的数据大小：SKB 大小 – TX 预留空间

  • RX 能存储的数据大小：SKB 大小 – RX 预留空间

备注

对于选定的 SKB 数目和大小，Ameba Wi-Fi 会在芯片启动阶段进行内存分配，这有可能导致默认预留给 NP 核的 RAM 不足，可参考 RAM 布局与配置 进行修改。

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

参考值

项目	大小（字节）	项目	大小（字节）
TX 预留空间	78	RX 预留空间	56

可配置参数

参数	类型	取值	描述	默认值
skb_num_np	s32	>= wifi_user_config.rx_ampdu_num + 6	设定 NP 核 SKB 的数目	10
skb_num_ap	s32	>= 1	设定 AP 核 SKB 的数目	4
skb_buf_size	u32	0	选用默认配置，skb 大小为 1632 字节	0
		(118，4095]	配置 SKB 的大小 备注 对于设定的 skb_buf_size，内部会进行缓存对齐（32bytes）处理。比如设置 skb_buf_size = 1117，实际 skb 大小为 1120 字节。 IEEE 802.11 标准限定单笔封包长度最大为 4095 字节。

force_cts2self

当同一基本服务集或者该服务集周遭环境中存在混合模式（如 IEEE 802.11b/g）设备时，可通过 CTS-to-self 机制实现传输保护，以减少帧交换重传次数提高吞吐量。

尽管高速率数据帧（如 IEEE 802.11n/ac/ax）的结构是分阶段的，包含一个前向兼容部分（传统前导码部分）和一个高速部分（高速前导码与数据部分），旧设备可以通过解码开头的兼容部分来避让后面的数据传输。传统前导码部分的保护虽然巧妙，但是在某些复杂、干扰严重的边缘场景下，传统设备可能会错误解码传统前导码部分导致保护失败，而 CTS-to-self 机制以最低的基本速率（例如 1Mbps 或 6Mbps）发送一笔 CTS 帧以保证所有 IEEE 802.11 设备（无论新旧）都能够解码该帧并保持静默，等待后续高速率数据帧传输完毕。

CTS-to-self 机制同时会带来额外的信令开销，对于数据传输而言，CTS 帧所占用的传输时间就是为保障后续高速数据传输成功而预先支付的、不可避免的“信道保险”成本。这个成本并非一个简单的数字，它由一个固定的流程和可计算的时间组成：

• 信道侦听等待

  • 在发送任何帧之前，无线设备必须先侦听信道，确保其在一段时间内是空闲的。这段时间通常是 DIFS（Distributed Inter-Frame Space）或者对于有 QoS 优先级的流量是 AIFS（Arbitration Inter-Frame Space）。这是 IEEE 802.11 协议的载波侦听多路访问/冲突避免（Carrier Sense Multiple Access with Collision Avoidance，CSMA/CA）核心规则，不可省略。

• CTS 帧传输时间，核心开销

  • CTS 帧大小包含：帧控制字段（2 字节） + 持续时间字段（2 字节） + 接收方地址（6 字节） + 帧校验序列（4 字节） = 14 字节。

  • 为了确保网络中所有老旧的传统设备都能听懂，CTS 帧必须使用所有设备都支持的最低基本速率之一来发送。通常为 6Mbps。

  • 物理层前导码 (Legacy Preamble) 时间：对于 IEEE 802.11a/g/n/ac/ax 的兼容模式，这个前导码部分（L-STF，L-LTF，L-SIG）的传输时间是固定的 20 微秒。

  • 传输时间：20 + (14 bytes * 8 bits/byte) / 6 Mbps ≈ 38.7 微秒

• 短帧间间隔（Short Inter-Frame Space）

  • 发送完 CTS 帧后，无线设备不能马上发送数据帧。它必须等待一个非常短的 SIFS 时间。SIFS 是 IEEE 802.11 中最短的帧间间隔，用于分隔一个操作序列中的连续帧（如 CTS 和它所保护的数据帧）。

所以仅仅一个 CTS 帧飞在空中的时间就接近 40 微秒。再加上 DIFS（例如 34µs for IEEE 802.11g）和 SIFS（例如 16µs for IEEE 802.11g），一次完整的 CTS-to-self 保护操作，在数据帧还没开始发送前，就已经消耗了大约 90 ~ 100 微秒的信道时间。当然这种开销影响不是一成不变的，它取决于所传输数据包的大小。

1. 对小数据包影响大。如果无线设备只是想发送一个非常小的数据包，其本身传输时间可能也只有几十微秒。如果为它也加上一个约 100 微秒的 CTS-to-self 保护，信令开销将超过数据本身的开销，效率极低。

2. 对大数据包价值高。对于一个聚合 MAC 协议数据单元（Aggregate MAC Protocol Data Unit，A-MPDU）、传输时间长达 2000 微秒的大数据块，为其增加 100 微秒的保护开销，仅占总时间的 5% 不到。用这 5% 的开销换取 99% 的传输成功率，是非常划算的买卖。

因此 Ameba 芯片提供了参数允许用户在不同场景下开启/关闭 CTS-to-self 机制，默认配置为不开启 CTS-to-self 机制 wifi_user_config.force_cts2self = 0。

MCC 配置

多通道并发模式（Multichannel Concurrent）是 Wi-Fi 并发模式的一种，其允许单个 Wi-Fi 射频芯片，通过快速地在不同信道之间进行切换，来模拟同时维持多个无线连接。

Ameba 设备通过时分复用（Time Division Multiplexing Acess）的方式将一个信标传输时间（Target Beacon Transmission Time）间隔进行时隙划分，按照预设比例分配给不同角色使用。

MCC 时隙切换机制

参数	类型	取值	描述	默认值
en_mcc	u8	0 / 1	关闭 / 开启 MCC 机制	0
mcc_force_p1_slot_ratio	u8	[12，80]	配置 MCC 机制下 port1 的时隙占比，比如 44 表示 port1（SoftAP 模式）工作时间占比为 44%，port0（STA 模式）工作时间占比为 56%	44

如果需要使用 MCC 机制，需要在编译固件的时候打开该功能，步骤如下：

1. 修改 Wi-Fi 开发者配置，使能 MCC 功能。

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

2. 导航至 {SDK}/amebaxxx_gcc_project 目录，执行以下指令：

   ./menuconfig.py
   

3. 找到 CONFIG WIFI > Enable MCC，选择 Enable MCC 后保存退出。

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

隐藏 SSID（Service Set Identifie） 的接入点（Access Point）在设计上不会响应通用的广播探测请求（Broadcast Probe Request）。只有当客户端发送的单播探测请求（Unicast Probe Request）中包含了其确切的 SSID 时，AP 才会做出回应。

另一方面，标准的被动扫描要求客户端在信道上保持静默监听，仅通过接收信标帧（Beacon Frame）来发现 AP。这种纯被动的机制天然无法发现隐藏 AP。

为解决这一矛盾，一种常见的兼容策略是：当在被动信道上监听到来自隐藏 AP 的信标帧（其 SSID 字段为空）后，客户端会主动发送一次单播探测请求，以获取其完整的网络信息。

为了满足不同场景的需求，Ameba Wi-Fi 提供了一个配置参数。客户可以通过该参数决定在被动扫描期间，是严格执行标准的静默扫描，还是为了发现并连接特定的隐藏 AP 而主动发送探测请求。

参数	probe_hidden_ap_on_passive_ch
类型	u8
取值	0	严格被动扫描模式 行为：在被动扫描信道上，设备只进行静默监听，绝不主动发送任何探测请求帧（Probe Request）。 使用场景：需要执行纯粹的被动扫描以实现最低功耗或避免任何无线发射的场合。在此模式下，设备无法发现位于这些信道上的隐藏 AP。
	1	混合扫描模式 (默认) 行为：当在被动扫描信道上侦听到来自隐藏 AP 的信标帧（即不含 SSID 的 Beacon）时，设备会主动发送一个单播探测请求，以获取其完整信息。 使用场景：需要确保能够发现并连接到隐藏 AP，即使该 AP 位于被动扫描信道列表内。这是为了最大化连接兼容性的推荐设置。
默认值	1

concurrent_enabled

请参考 SoftAP 与 STA 共存

rate_mask_cck

CCK（Complementary Code Keying）速率可以覆盖更远的范围，但同时因传输速率过小（比如 CCK 1M 传输一笔 1.5KB 大小的数据包大约需要 13 毫秒）导致吞吐量很低，这对部分吞吐量有明确需求的客户很不友好，故提供参数允许用户根据应用选择关闭部分或全部 CCK 速率。

此参数通过一个速率掩码（rate mask）精确控制 Wi-Fi 设备在发送数据帧时可用的 CCK 速率集。

rate_mask_cck 是一个位掩码（bitmask），每一位对应一个特定的 CCK 速率。其工作原理如下：

• 某位设置为 1：表示 屏蔽（mask） 或 禁用 对应的速率。当该位为 1 时，Wi-Fi 芯片的速率自适应算法将不会选择这个速率来发送数据。

• 某位设置为 0：表示 允许 使用对应的速率。

参数	rate_mask_cck
类型	u8
取值	BIT0	禁用 CCK 1Mbps
	BIT1	禁用 CCK 2Mbps
	BIT2	禁用 CCK 5.5Mbps
	BIT3	禁用 CCK 11Mbps
默认值	0x0

WPS 配置

Wi-Fi 保护设置（Wi-Fi Protected Setup）是由 Wi-Fi 联盟（Wi-Fi Alliance）制定的一种网络安全标准，旨在简化普通用户将设备连接到安全的无线网络的过程。其核心目标是让不熟悉无线安全设置的用户，能够无需输入复杂的 Wi-Fi 密码，就能快速、安全地将新的无线设备（如手机、打印机、智能电视等）添加到自己的网络中。

WPS 主要通过以下几种方式工作，其中前两种最为常见：

1. 按钮配置（Push Button Configuration，PBC）

   这是最流行和最简单的方式，其工作流程如下：

   • 用户在无线路由器上按一下物理的或虚拟的“WPS”按钮。

   • 路由器会开启一个短暂的（通常为 2 分钟）配对窗口。

   • 在此期间，用户在要连接的设备（如手机、打印机）上也选择 WPS 连接选项。

   • 两个设备会自动协商安全设置并完成连接，整个过程无需输入密码。

2. PIN 码（Personal Identification Number，PIN）

   这种方式使用一个 8 位数的 PIN 码来进行认证。它有两种模式：

   • 设备提供 PIN 码：一些没有按钮的设备（如网络打印机）会在屏幕上显示一个随机生成的 PIN 码。你需要将这个 PIN 码输入到路由器的管理界面中，路由器便会授权该设备接入。

   • 路由器提供 PIN 码：每个支持 WPS 的路由器在出厂时都会有一个固定的 PIN 码（通常贴在路由器背面的标签上）。你在新设备上选择 WPS 连接时，输入这个路由器的 PIN 码即可完成连接。

   • 重要提示：这种基于 PIN 码的方式存在严重的安全漏洞。

3. 近场通信（Near Field Communication，NFC）

   • 工作流程：将支持 NFC 的设备（如智能手机）靠近同样支持 NFC 的路由器，两者通过轻触即可自动交换网络凭据并完成连接。

   • 普及度：这种方式并不常见，需要路由器和客户端设备都支持 NFC。

Ameba Wi-Fi 解决方案允许设备对一次 WPS 连接尝试失败后的重试次数和重试间隔进行调整，以保证不同场景下 WPS 连接的健壮性和用户体验。

参数	类型	取值	描述	默认值
wps_retry_count	u8	—	定义了在首次 WPS 连接尝试失败后，设备将额外自动重试的最大次数。	4
wps_retry_interval	u32	—	定义了每次自动重试之间的时间间隔，单位：毫秒	5000

keepalive_interval

这个参数用于在 Wi-Fi 客户端（STA）模式下，配置一个自动“保活”机制的周期，其单位为秒。其核心目的是为了在设备与接入点（Access Point）之间没有活动数据传输时，通过周期性地发送一个特殊的数据包来维持 Wi-Fi 连接，防止因长时间处于空闲状态而被路由器断开。

核心作用

在许多 Wi-Fi 网络中，AP 为了优化性能和管理连接的客户端，会设置一个“空闲超时”机制。如果一个客户端设备在设定的时间内（例如 5 分钟）没有任何数据通信，AP 可能会认为该设备已经离线或不再需要网络，从而主动断开其连接以释放网络资源。

对于很多需要长期稳定在线的设备（尤其是物联网设备），AP 的“空闲超时”机制可能会导致频繁掉线和重连。keepalive_interval 参数就是为了解决这个问题而设计的。

工作原理

当 keepalive_interval 被设置为一个大于 0 的值时，设备会启动一个内部计时器。每当计时器到达设定的秒数，设备就会自动向其所连接的 AP 发送一个空数据包（Null Data Packet）。

• 空数据包：一种特殊的 Wi-Fi 数据帧，它不包含任何上层应用数据，仅仅是作为一个“心跳信号”。

• 作用：当 AP 收到这个空数据包后，它会刷新该设备的空闲计时器，从而认为该设备仍然是活动的。这样，即使设备的应用层长时间没有数据收发，其底层的 Wi-Fi 连接也能得以保持。

基于连接稳定性和设备功耗的考虑，默认配置为 wifi_user_config.keepalive_interval = 20。

rx_cca_thresh

本参数用于配置 Wi-Fi 模块在接收数据时可接受的最低信号强度阈值，单位为 dBm。

当收到的无线信号强度（Received Signal Strength Indication，RSSI）低于此阈值时，Wi-Fi 硬件或底层驱动将直接忽略该数据包，不进行后续处理。这实质上是调整了 CCA（Clear Channel Assessment，信道空闲评估）机制中的能量检测门限，帮助系统过滤掉无效的弱信号，从而在特定场景下优化性能和功耗。

参数	rx_cca_thresh
类型	s8
取值	0	保留值，启用动态阈值机制。 当设置为 0 时，系统将采用 Realtek 驱动内置的动态调整算法。该算法会根据当前的网络环境（如信道干扰、连接质量等）自动计算并设置一个最优的接收阈值。这是默认和推荐的设置，适用于绝大多数应用场景。
	[-100, 0)	手动指定静态阈值 用户可以手动设置一个固定的接收信号强度阈值（单位：dBm）。例如，如果设置为 -85，则任何信号强度低于 -85dBm 的 Wi-Fi 数据包都将被硬件忽略。 使用场景1: 高密度或高干扰环境。在 Wi-Fi 设备密集、信道干扰严重的环境中（如展会、办公楼），空气中可能充满了来自远处或不相关接入点（Access Point）的弱信号。适当提高此阈值可以有效过滤这些弱信号干扰，降低底层处理器的负载，专注于处理有效通信范围内的信号，从而提升连接稳定性和数据吞吐量。 使用场景2: 特定通信距离控制。如果设备只与特定物理范围内的强信号 AP 进行交互，可以通过设置一个较高的阈值来间接实现“距离筛选”，确保设备只连接到非常近的 AP。
默认值	0

Wi-Fi R-Mesh 相关

请参考 Wi-Fi R-Mesh - 编程接口 章节描述。