Wi-Fi 基础架构

WHC IPC 是 SDK 默认的无线通信架构，具备全芯片兼容性，其核心特性包含：

  • 双核架构

    • 基于 Ameba 芯片的 AP 和 NP 双核设计

    • 通过内部 IPC 接口实现 Host 与 Device 之间的通信

    • 无须外置 Host 控制器

  • 协议栈并行执行

    • LWIP 网络协议层和 Wi-Fi 驱动层分别在不同的核上运行

    • 实现并行处理，提升数据传输效率

  • 模块化隔离设计

    • Wi-Fi 驱动层与用户应用层实现安全解耦

    • 提高系统的安全性、可靠性和鲁棒性


../../_images/wifi_basic_architecture.svg

WHC IPC 架构

Wi-Fi 初始化

SDK 默认启用 Wi-Fi 功能，在 main() 函数中会自动调用 wifi_init() 进行 Wi-Fi 初始化。完整的 Wi-Fi 初始化流程如下图所示：

../../_images/wifi_basic_init.svg

备注

  • Wi-Fi 初始化成功后，设备默认处于 STA 模式。

  • 若需启用 SoftAP 模式 ，请在 Wi-Fi 初始化完成之后调用 wifi_start_ap()。详细说明请参考 SoftAP 常见工作流程。

Wi-Fi 扫描

本节介绍几种常见的扫描配置，更多高级配置请参考 wifi_scan_networks()。

Wi-Fi 扫描模式包括同步扫描和异步扫描，其完整扫描流程如下：

配置方式:

模式特点：

  • 单线程安全：仅阻塞调用线程，其他线程正常运行

  • 推荐场景：大多数基础场景

../../_images/wifi_basic_scan_sync.svg

同步扫描流程

STA 模式

STA 连线流程

本节介绍几种常见的 STA 连线流程，更多高级配置请参考 wifi_connect()。

配置方式：

模式特点：

  • 单线程安全：仅阻塞调用线程，其他线程正常运行

  • 推荐场景：大多数基础场景

../../_images/wifi_basic_connect_sync.svg

同步连线流程

备注

若已知 AP 信道（如通过独立扫描获取），设置 rtw_network_info::channel 可大幅减少连线耗时。

STA 断线自动重连

Wi-Fi 断线自动重连机制旨在让用户在无感知或者最少干预的情况下实现/恢复网络连接。

断线分为两类：1）STA 发起的连接失败；2）因 AP 原因被动断线。此时 STA 将自动发起重新连接。

项目

现象

常见原因

连线失败

认证/关联超时

  1. 严重信号干扰

  2. 信道拥堵

  3. 密码错误

  4. AP 固件假死

四次握手失败

DHCP 超时

被动断线

信标帧丢失

  1. 设备远离信号覆盖范围

  2. AP 意外断电或重启
../../_images/wifi_basic_auto_reconnect.svg

自动重连流程

一旦检测到断连事件，系统将会遵循一套智能化策略，以平衡连接恢复速度和资源消耗，在无用户手动干预的情况下发起重新连接过程，并且为避免信号在持续不佳的环境中耗尽电量或对网络造成不必要的负担，重连尝试之间会有一个可允许配置的等待间隔以及最大尝试重连的次数。

参数

类型

取值

描述

默认值

auto_reconnect_en

u8

0 / 1

关闭 / 开启自动重连机制

1

auto_reconnect_count

u8

>= 1

配置自动重连尝试的最大次数

备注

0xFF 表示无限制的尝试

10

auto_reconnect_interval

u8

—

每次发起重新关联的间隔，单位：秒

5

备注

可在如下设置后，参考 example_wifi_user_reconnect.c 文件实现自定义的断线重连功能。

wifi_user_config.auto_reconnect_en = 0;

STA 上电自动重连

Wi-Fi 上电自动重连机制旨在让客户端在重启后能够自主识别已保存的 Wi-Fi 配置文件，并依此信息关联到目标网络，确保了设备在无需任何人工干预的情况下，能够持久且可靠地接入已知网络。

Ameba 芯片在每次 Wi-Fi 网络连接成功后，系统会保存一个包含安全凭证（密码/加密类型）、信道、服务集标识符（Service Set Identifier）等信息的配置文件，这个配置文件被保存在设备的非易失性存储（flash）中。在意外重新上电或者手动重启后，设备会自动读取该配置文件并驱动 Wi-Fi 硬件开始扫描周围环境，进入自主的网络连接流程，无需等待任何用户指令或应用程序请求。

../../_images/wifi_basic_fast_connect.svg

上电自动重连流程

该功能默认开启，可通过配置 wifi_user_config.fast_reconnect_en = 0 关闭此功能，此时设备每次重启后需要通过指令或软件调度触发网络连接过程。

SoftAP 模式

SoftAP 常见工作流程

SoftAP 的常见工作流程如下图所示：

../../_images/wifi_basic_softap_workflow.svg

SoftAP MAC 地址

SoftAP MAC 地址默认由 STA MAC 地址（芯片 MAC 地址）偏移而来， 通过 wifi_user_config.softap_addr_offset_idx 控制偏移位置，举例如下：

芯片MAC地址

softap_addr_offset_idx

SoftAP MAC地址

00:e0:4c:01:02:03

0

02:e0:4c:01:02:03

1(SDK默认值)

00:e1:4c:01:02:03

5

00:e0:4c:01:02:04

若希望设置 SoftAP MAC 地址为芯片 MAC 地址，则设置：

wifi_user_config.concurrent_enabled = 0;

备注

wifi_user_config.concurrent_enabled = 0 时 STA 与 SoftAP 无法同时工作，详细可参考 SoftAP 与 STA 共存

SoftAP 信道切换通知（CSA）

SoftAP 可以通过调用 wifi_ap_switch_chl_and_inform() 来执行信道切换，并同时通知所有连接的 STA 。 这使得 STA 能够快速、无缝地跟随 SoftAP 切换到新信道，避免连接中断。

SoftAP 信道切换时序如下图所示：

../../_images/wifi_basic_softap_csa.svg

图中 Beacon 帧和 CSA Action 帧中的 CSA IE 格式如下表所示，部分字段的具体取值由 wifi_ap_switch_chl_and_inform() 的输入参数决定：

CSA IE 格式

Field

长度

含义

配置来源

Element ID

1 byte

CSA IE 标识符

无需用户配置

Channel Switch Mode

1 byte

STA 传输限制模式

rtw_csa_parm::chl_switch_mode

New Channel Number

1 byte

SoftAP 将要切换到的新信道

rtw_csa_parm::new_chl

Channel Switch Count

1 byte

剩余 Beacon 间隔

初始值为 rtw_csa_parm::chl_switch_cnt，每过 1 个 Beacon 间隔减 1

备注

示例： SoftAP 在 10 个 Beacon 间隔后切换到 7 信道，每个间隔发送 2 个广播 CSA Action 帧，且不限制 STA 传输：

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

备注

SoftAP / STA 共存模式下，如果 STA 已经与 AP 连线， SoftAP 信道切换将会导致 STA 断线。

SoftAP 与 STA 共存

Ameba 支持 STA 模式与 SoftAP 模式同时工作：

SDK 默认开启此功能：

wifi_user_config.concurrent_enabled =1;

当同时满足以下条件时，Wi-Fi 处于 SoftAP/ STA 共存状态：

  • SoftAP 接口处于启动状态

  • STA 接口处于连线成功或连线过程状态

与单纯的 STA 或 SoftAP 模式开发有如下几点差异：

  • 需要预留 2 个 MAC 地址，STA 接口 的 MAC 地址来自 efuse，SoftAP MAC 地址由 STA MAC 地址偏移得到，详细请参考 SoftAP 相关配置

  • 当 STA 接口连线时，SoftAP 会自动切换到与 STA 接口相同的信道。（可利用 CSA 机制减少 SoftAP 下面的 STA 掉线，详细请参考 SoftAP 信道切换通知（CSA） ）

通过如下设置可禁用 SoftAP/ STA 共存功能：

wifi_user_config.concurrent_enabled = 0;

禁用后的限制为：

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

  • STA 接口连线成功或连线过程中，SoftAP 无法启动

一般用在需要限制 SoftAP MAC 地址为芯片 MAC 地址的情况（参考 SoftAP MAC 地址）

SoftAP 相关配置

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

Wi-Fi 配置文件： component/soc/usrcfg/amebaxxx/ameba_wificfg.c

参数

类型

取值

描述

默认值

ap_sta_num

u8

1 ~ 5

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

5

ap_polling_sta

u8

0 / 1

Softap 周期发送问询帧来确认 STA 是否仍在线（暂不支持）

0

softap_addr_offset_idx

u8

0 ~ 5

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

1

Promiscuous 模式

promiscuous 模式可以将 Wi-Fi 原始封包直接上报给应用层。

API

调用 wifi_promisc_enable() 可以配置并使能 promiscuous 模式。

常见工作流程

promiscuous 的常见工作流程如下图：

../../_images/wifi_basic_promisc.png

备注

  • 回调函数会卡住 Wi-Fi 驱动的执行，所以只能进行简单快速的操作，建议单独建一个任务处理复杂的操作

应用示例

Wi-Fi 天线分集

天线分集（Antenna Diversity，ANTDIV）是一项通过部署多根天线来提升无线通信稳定性和性能的技术。其核心原理是动态地从多根天线中选择信号质量最佳的一根进行数据收发，以有效对抗无线信号在传播过程中因反射、折射而产生的“多径衰落”效应，从而提高信号质量与连接可靠性。

工作机制

Ameba 芯片的天线分集功能分为两部分实现：

../../_images/wifi_basic_hw_antdiv.svg

  1. 硬件部分：根据不同工作模式下有所区分

    • 数据接收阶段（RX）：在接收每个数据包时，硬件会利用其前导码（Preamble）部分，在不同天线间进行快速切换和评估，以确定信号质量最佳的天线。随后，硬件将锁定该最优天线，用以接收该数据包的剩余数据净荷（Payload）。

    • 链路空闲阶段（RX-idle）：硬件固定使用前一个周期由软件决策出的最优天线进行环境侦听和信道空闲评估（CCA）。

    • 数据传输阶段（TX）：硬件会固定使用前一个周期由软件决策出的最优天线进行数据传输。

  2. 软件部分：通过统计一个周期内接收信号在不同天线上的功率指标，决策出表现“最优”的天线作为下一个周期 RX-idle 和 TX 阶段的天线。

切换控制

不同射频前端（Radio Front-End，RFE）类型的功能支持和控制引脚可能会有所差异，具体需要参考文件 WR-date-IC-RFE Type Definition-Rxx.xlsx 中描述，文件可联系 HW FAE 获取。

芯片 Tape-out 后，RFE 类型及其控制引脚映射即被硬件固化。RFE 类型标识符被烧录于 eFuse 地址 0x13A。开发人员需读取此值，并确保软件配置与芯片硬件定义的引脚映射相匹配。

不同 RFE type 一般对应不同的控制引脚，图示 RFE 类型 2 通过 PB2/PB3 控制 SPDT（Single Pole Double Throw）来切换天线。

../../_images/wifi_basic_rfe_type_dplus.svg

备注

并非所有的 RFE 类型都支持 ANTDIV 机制，实际以芯片硬件设计为准。

使用指南

软件配置

Ameba Wi-Fi 提供了参数供用户选择不同的 ANTDIV 模式。

参数

antdiv_mode

类型

u8

取值

RTW_ANTDIV_AUTO

自动切换天线模式

RTW_ANTDIV_FIX_MAIN

固定在 MAIN 天线

RTW_ANTDIV_FIX_AUX

固定在 AUX 天线

RTW_ANTDIV_DISABLE

关闭天线切换功能

默认值

RTW_ANTDIV_DISABLE

备注

若使用 ANTDIV 机制，必须配置 wifi_user_config.antdiv_mode != 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 --->
    ... --->

  3. 再次定位到 {SDK}/amebaxxx_gcc_project 目录，执行以下指令：

    ./build.py

调试指令

可执行 AT+WLDBG=antdiv_get 获取当前 TRX 选择的天线。

#AT+WLDBG=antdiv_get              //Wi-Fi IPS
[WLDBG]: _AT_WLAN_IWPRIV_
[WLAN-A] [iwpriv_command] cmd name: antdiv_set
[WLAN-A] get antdiv m:1+P:02017560(ips:BITx->PA_x)  //mode-RTW_ANTDIV_FIX_MAIN; P(PIN)-check rfe control PIN level

#AT+WLDBG=antdiv_get              //Wi-Fi LPS
[WLDBG]: _AT_WLAN_IWPRIV_
[WLAN-A] [iwpriv_command] cmd name: regu
[WLAN-A] get antdiv m:1+ant:0     //m(mode)-RTW_ANTDIV_FIX_MAIN; ant(antenna):0-MAIN_ANT/1-AUX_ANT

可执行 AT+WLDBG=antdiv_set,value 修改当前配置的 ANTDIV 模式。

#AT+WLDBG=antdiv_set,0
[WLDBG]: _AT_WLAN_IWPRIV_
[WLAN-A] [iwpriv_command] cmd name: antdiv_set
[WLAN-A] change antdiv=0[0-auto;1-main;2-aux;f-disable]