Wi-Fi 基础架构

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

• 双核架构

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

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

  • 无须外置 Host 控制器

• 协议栈并行执行

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

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

• 模块化隔离设计

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

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

WHC IPC 架构

Wi-Fi 初始化

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

备注

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

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

Wi-Fi 扫描

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

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

同步扫描模式异步扫描模式

配置方式:

• 调用 wifi_scan_networks() 时设置 block=1

模式特点：

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

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

同步扫描流程

STA 模式

STA 连线流程

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

同步连线模式异步连线模式

配置方式：

• 调用 wifi_connect() 时设置 block=1

模式特点：

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

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

同步连线流程

备注

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

STA 断线自动重连

本节介绍断线自动重连功能，当 STA 连线失败或因 AP 被动断线时，将自动发起重连

自动重连流程

相关属性可以通过 component/soc/usrcfg/amebaxxx/ameba_wificfg.c 文件的如下参数配置：

wifi_user_config.auto_reconnect_en:

自动重连功能开关，写 1 表示使能。

wifi_user_config.auto_reconnect_count:

自动重连尝试次数上限，写 0xff 表示不限制。

wifi_user_config.auto_reconnect_interval:

自动重连时间间隔，单位 s。

wifi_user_config.no_beacon_disconnect_time:

无 beacon 后断线的时间间隔，单位 2s。

备注

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

wifi_user_config.auto_reconnect_en = 0;

STA 上电自动重连

TBD

STA 省电模式

TBD

SoftAP 模式

SoftAP 常见工作流程

本节介绍 SoftAP 的常见工作流程，更多高级配置请参考 SoftAP 相关 API 文档。

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

SoftAP MAC 地址配置

SoftAP MAC 地址与芯片 MAC 地址有关，通过 component/soc/usrcfg/amebaxxx/ameba_wificfg.c 文件进行配置。

假设芯片的 MAC 地址为 00:e0:4c:01:02:03 ，则 SoftAP MAC 地址可以通过以下方式配置：

示例 1：默认配置（字节 1 加 1）示例 2：字节 5 加 1示例 3：与芯片 MAC 地址相同

SoftAP MAC 地址： 00:e1:4c:01:02:03

wifi_user_config.concurrent_enabled = 1;
wifi_user_config.softap_addr_offset_idx = 1;

MAC 地址冲突限制

当 SoftAP 与芯片 MAC 地址相同时（示例 3），STA 和 SoftAP 将无法同时工作，具体表现为：

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

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

SoftAP 信道切换通知（CSA）

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

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

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

CSA IE 格式

字段	Element ID	Channel Switch Mode	New Channel Number	Channel Switch Count
长度	1 byte	1 byte	1 byte	1 byte
含义	CSA IE 标识符	STA 传输限制模式	SoftAP 将要切换到的新信道	剩余 Beacon 间隔数
配置来源	无需用户配置	rtw_csa_parm::chl_switch_mode	rtw_csa_parm::new_chl	初始值为 rtw_csa_parm::chl_switch_cnt，每过 1 个 Beacon 间隔减 1

备注

• 配置 wifi_ap_switch_chl_and_inform() 参数时，请参考 rtw_csa_parm 结构体说明。

• 无论选择哪种类型的 CSA Action 帧 （rtw_csa_parm::action_type），在切换信道前 SoftAP 的 Beacon 帧都将包含 CSA IE。

示例： 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 共存

TBD

混杂模式

TBD