Wi-Fi 开发者配置

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

github source code

rtw_edcca_mode

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

参数

rtw_edcca_mode

类型

u8

取值

RTW_EDCCA_NORM

根据实时信号强度测量值动态调整 EDCCA 阈值

  • 使用场景：通过忽略小能量的干扰信号来增加传输机会

RTW_EDCCA_ADAPT

ETSI Adaptivity 测试模式，固定阈值

RTW_EDCCA_CS

日本 Carrier Sense 测试模式，固定阈值

RTW_EDCCA_DISABLE

关闭 EDCCA 模式

默认值

RTW_EDCCA_NORM

tx_pwr_table_selection

一般情况下， Wi-Fi 发射功率由两组发射功率表的综合结果给出，取其中最小值作为最终的发射功率。

  • 速率功率表：满足射频性能的情况下不同速率的最大发射功率。

  • 功率限制表：当地法规为每个信道的 Wi-Fi 发射功率所施加的限制。

该参数则用于选择由哪组功率表来决定最终的发射功率：

参数

tx_pwr_table_selection

类型

u8

取值

0

选择速率功率表

  • 使用场景：增大传输功率

1

选择功率限制表和速率功率表综合的结果

  • 使用场景：节能

2

根据 efuse 中的设定值选择

默认值

2

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_DYNAMIC

保留

RTW_TRP_TIS_FIX_ACK_RATE

保留

RTW_TRP_TIS_FIX_PHY_ACK_HIGH_RATE

保留

默认值

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

不支持

antdiv_mode

Ameba 芯片支持天线分集（Antenna Diversity）机制，利用多根天线来对抗无线通信中 “多径衰落” 效应，从而提高信号质量和连接可靠性。

简而言之就是通过动态切换天线来达到较优的传输/接收性能。软件层统计一段时间内接收封包的资讯，对诸如信号强度指示（Received Signal Strength Indication） 、误差矢量幅度（Error Vector Magnitude）、吞吐量等进行对比决策出当前性能较优的天线作为下一段时间的收发器天线。

参数

antdiv_mode

类型

u8

取值

RTW_ANTDIV_AUTO

自动切换天线模式

RTW_ANTDIV_FIX_MAIN

固定在 MAIN 天线

RTW_ANTDIV_FIX_AUX

固定在 AUX 天线

RTW_ANTDIV_DISABLE

关闭天线切换功能

默认值

RTW_ANTDIV_DISABLE

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

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

    ./menuconfig.py

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

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

concurrent_enabled

Wi-Fi 并发模式允许 Ameba 设备同时扮演两个不同的网络角色：STA 模式和 SoftAP 模式，不同模式的介绍详见 Wi-Fi 基础模式 章节。

若是需要使用 Wi-Fi 并发模式，请配置 wifi_user_config.concurrent_enabled = 1。

SoftAP 配置

本节提供参数针对 SoftAP 模式进行能力、行为等的配置。

参数

类型

取值

描述

默认值

ap_sta_num

u8

1 ~ 14

Softap 最大可允许连接设备数目

5

ap_polling_sta

u8

0 / 1

Softap 周期发送问询帧来确认 STA 是否仍在线

  • 暂不支持

0

softap_addr_offset_idx

u8

0 ~ 5

指定 Softap 的 MAC 地址的增量偏移位置（增量为 1）

备注

  • wifi_user_config. concurrent_enabled = 1 时参数有效

  • MAC[0] 最低位为 1 时表征组播地址，所以增量偏移位置为 MAC[0] 时增量为 2

1

示例-地址换算

假定芯片的 MAC 地址是 00:e0:4c:01:02:03

  • softap_addr_offset_idx = 0 -> SoftAP 的 MAC 地址为 02:e0:4c:01:02:03

  • softap_addr_offset_idx = 1 -> SoftAP 的 MAC 地址为 00:e1:4c:01:02:03

  • softap_addr_offset_idx = 5 -> SoftAP 的 MAC 地址为 00:e0:4c:01:02:04

MAC 地址冲突限制

当 SoftAP 与芯片 MAC 地址相同时（wifi_user_config. concurrent_enabled = 0），STA 和 SoftAP 将无法同时工作，具体表现为：

  • SoftAP 启动后，STA 无法进行连线操作

  • STA 成功连线后，SoftAP 无法正确启动

省电配置

Ameba 系列芯片作为专为物联网（IoT）应用设计的低功耗 Wi-Fi/蓝牙 SoC，其核心设计理念之一便是极致的电源管理，允许开发者根据具体应用场景在性能、功耗和响应速度之间做出精确的权衡，省电模式的介绍可以参考 FreeRTOS 低功耗 章节获取详细信息。

下面对多种省电模式的配置进行详细展开：

  1. 非活动省电模式（Inactive Power Save）

    IPS 专为 Wi-Fi 未连接状态所设计，允许在没有网络连接时进入睡眠的状态，从而显著的延长电池续航的时间。

    IPS 支持两种睡眠的状态：

    • Wi-Fi 完全断电，此时处于最大程度的 Wi-Fi 省电状态。

    • 电源门控（Power Gating）模式，以求可以更快速的退出 IPS。

    IPS 通过定时监测的方式进入，系统周期性的检查当前 Wi-Fi 的状态，在 Wi-Fi 未连接且不存在诸如扫描等特殊行为的情况下，根据配置进入相应的省电层级。我们同时也提供了一种快速的方式进入 IPS 状态，开发者需要配置 wifi_user_config.ips_ctrl_by_usr = 1 ，然后调用 wifi_set_ips_internal() 实现快速进入 IPS 状态。

    ../../../_images/ips_flow.svg

    IPS 流程图

    参数

    类型

    取值

    描述

    默认值

    ips_enable

    u8

    0 / 1

    关闭/使能 IPS

    1

    ips_level

    u8

    RTW_IPS_WIFI_OFF

    IPS 状态下 Wi-Fi 断电

    RTW_IPS_WIFI_OFF

    RTW_IPS_WIFI_PG

    IPS 状态下 Wi-Fi 进入 PG 模式

    ips_ctrl_by_usr

    u8

    0 / 1

    是否允许更快速的进入 IPS 状态

    0

  2. 传统省电模式（Legacy Power Save）

    LPS 是基于 IEEE 802.11 标准最初的 Wi-Fi 省电机制所设计，其核心思想是允许客户端在 Wi-Fi 连接状态且不存在无线数据传输的情况下进入睡眠状态，此时接入点（Access Point）为其缓存下行数据从而达到节省功耗的目的。

    LPS 下客户端需要周期性唤醒来接收 AP 的信标帧，并通过解析信标帧中流量指示图 （Traffic Indication Map） 元素获知是否存在自己的数据等待接收，若存在则保持清醒继续和 AP 进行数据交互。

    参数

    类型

    取值

    描述

    默认值

    lps_enable

    u8

    0 / 1

    关闭/使能 LPS

    1

    lps_listen_interval

    u8

    0

    每个目标信标传输时间（Target Beacon Transmission Time）都唤醒来接收信标帧

    0

    > 0

    配置接收信标帧的间隔，单位：102.4ms（TBTT 间隔）

  3. 无线局域网唤醒模式（Wake on Wireless LAN）

    WoWLAN 是一种系统级的省电模式，当系统空闲时会暂停 CPU（不关闭时钟和电源），同时可配置实现射频状态的开启和关闭。在此模式下系统通过 Wi-Fi 的特殊事件来唤醒，比如收到单播数据包、收到广播/组播数据包以及接入点（Access Point）断联事件等，我们提供了配置可供开发者选择是否通过广播/组播数据包来唤醒系统工作。

    参数

    类型

    取值

    描述

    默认值

    wowlan_rx_bcmc_dis

    u8

    0 / 1

    使能/关闭 WoWLAN 模式下允许广播或组播帧唤醒系统

    0

其他配置参数

TBD