WiFi管理器¶
本文引用的文件 - wifi_manager.h - wifi_manager.c - config.h - main.c - gateway_config.h - CMakeLists.txt（组件） - 顶层CMakeLists.txt
目录¶
简介¶
本文件为ESP32-S3 BLE网关中的WiFi管理器提供全面技术文档。内容涵盖： - WiFi连接模式：STA模式、AP模式与混合模式的配置与切换 - 自动重连机制：连接失败检测、重连策略与网络状态监控 - 网络配置管理：SSID设置、密码管理与安全协议选择 - 网络状态监控：连接质量评估、信号强度监测与网络可用性检查 - 完整API接口文档：初始化、配置设置、状态查询等 - 实际配置示例、故障排除与性能优化建议
项目结构¶
WiFi管理器位于旧版本工程中，作为独立组件提供STA/AP模式管理与事件处理能力。主程序通过网关配置模块加载持久化WiFi参数，并在启动时调用WiFi管理器完成连接或进入AP配置模式。
graph TB
subgraph "应用层"
MAIN["main.c<br/>应用入口与任务调度"]
GWCFG["gateway_config.h<br/>网关配置管理"]
end
subgraph "网络组件"
WMHDR["wifi_manager.h<br/>接口定义"]
WMC["wifi_manager.c<br/>实现与事件处理"]
CFG["config.h<br/>全局配置常量"]
end
MAIN --> GWCFG
MAIN --> WMHDR
WMHDR --> WMC
WMC --> CFG图表来源 - main.c - gateway_config.h - wifi_manager.h - wifi_manager.c - config.h
章节来源 - main.c - CMakeLists.txt（组件） - 顶层CMakeLists.txt
核心组件¶
- 接口头文件：定义WiFi状态枚举、配置数据结构、状态信息结构与全部API函数原型
- 实现文件：封装STA/AP模式切换、事件回调注册、连接状态跟踪、扫描与IP信息获取
- 全局配置：定义AP默认参数、重试次数、连接超时等运行时参数
- 应用集成：主程序在启动阶段加载网关配置并调用WiFi管理器进行连接或AP启动
章节来源 - wifi_manager.h - wifi_manager.c - config.h - main.c
架构总览¶
WiFi管理器基于ESP-IDF的事件驱动模型，使用事件组协调连接状态；通过STA与AP两种网络接口实现不同工作模式；结合网关配置模块实现持久化参数读取与写入。
sequenceDiagram
participant APP as "应用(main.c)"
participant CFG as "网关配置(gateway_config.h)"
participant WM as "WiFi管理器(wifi_manager.c)"
participant WIFI as "WiFi驱动(esp_wifi)"
participant NETIF as "网络接口(esp_netif)"
APP->>WM : 初始化
WM->>NETIF : 创建STA/ AP网络接口
WM->>WIFI : 初始化WiFi栈
APP->>CFG : 加载持久化配置
CFG-->>APP : 返回WiFi配置
APP->>WM : 设置配置
APP->>WM : 启动
alt 已配置SSID
WM->>WIFI : 设置STA模式
WM->>WIFI : 连接指定AP
WIFI-->>WM : 事件(WIFI_EVENT_STA_START/ DISCONNECTED/GOT_IP)
WM-->>APP : 回调通知(连接中/已连接/断开)
else 未配置SSID
WM->>WIFI : 设置AP模式
WM-->>APP : 回调通知(AP模式)
end图表来源 - main.c - gateway_config.h - wifi_manager.c - wifi_manager.c - wifi_manager.c
详细组件分析¶
数据结构与状态机¶
- 状态枚举：断开、连接中、已连接、AP模式、错误
- 配置结构：包含SSID、密码、是否使用静态IP及静态IP四元组
- 状态信息结构：包含当前状态、SSID、信道、RSSI、IP、网关、掩码、MAC地址
classDiagram
class wifi_state_t {
<<enumeration>>
+DISCONNECTED
+CONNECTING
+CONNECTED
+AP_MODE
+ERROR
}
class wifi_config_data_t {
+char ssid[]
+char password[]
+bool use_static_ip
+uint32_t static_ip
+uint32_t gateway
+uint32_t netmask
+uint32_t dns1
+uint32_t dns2
}
class wifi_status_t {
+wifi_state_t state
+char ssid[]
+uint8_t channel
+int8_t rssi
+uint32_t ip_addr
+uint32_t gateway
+uint32_t netmask
+uint8_t mac[6]
}
wifi_status_t --> wifi_state_t : "使用"
wifi_config_data_t --> wifi_status_t : "生成状态信息"图表来源 - wifi_manager.h
章节来源 - wifi_manager.h
事件处理与状态转换¶
- 事件处理器监听STA启动、断开、AP启动、STA接入/断开以及IP分配/丢失事件
- 状态机根据事件更新内部状态，并通过回调通知上层
- 连接超时与重试逻辑在连接流程中实现
flowchart TD
START(["事件触发"]) --> WEVENT{"WIFI_EVENT?"}
WEVENT --> |是| WETYPE{"事件类型"}
WEVENT --> |否| IPEVENT{"IP_EVENT?"}
IPEVENT --> |是| IPID{"事件ID"}
IPEVENT --> |否| END
WETYPE --> |STA_START| SETCON["设置状态=连接中<br/>发起首次连接"]
WETYPE --> |STA_DISCONNECTED| DISC{"重试计数 < 最大重试?"}
DISC --> |是| RECONN["重新连接<br/>重试计数+1"]
DISC --> |否| FAIL["设置状态=断开<br/>设置失败位"]
WETYPE --> |AP_START| APSTART["设置状态=AP模式"]
WETYPE --> |AP_STACONNECTED| STACONN["记录STA接入日志"]
WETYPE --> |AP_STADISCONNECTED| STADISCONN["记录STA断开日志"]
IPID --> |GOT_IP| GOTIP["保存IP信息<br/>设置状态=已连接<br/>设置成功位"]
IPID --> |LOST_IP| LOSTIP["清空IP<br/>设置状态=连接中"]
SETCON --> END
RECONN --> END
FAIL --> END
APSTART --> END
STACONN --> END
STADISCONN --> END
GOTIP --> END
LOSTIP --> END图表来源 - wifi_manager.c
章节来源 - wifi_manager.c
模式切换与启动流程¶
- 启动优先判断：若已配置SSID则尝试连接；否则启动AP模式供配置
- STA连接：设置STA模式、配置SSID/密码、启动WiFi并等待事件结果
- AP启动：根据配置参数设置AP模式，自动处理弱密码降级为开放认证
sequenceDiagram
participant APP as "应用"
participant WM as "WiFi管理器"
participant WIFI as "WiFi驱动"
APP->>WM : start()
alt 已配置SSID
WM->>WM : connect(ssid, password)
WM->>WIFI : set_mode(STA)
WM->>WIFI : set_config(STA)
WM->>WIFI : start()
WIFI-->>WM : 事件(GOT_IP 或 DISCONNECTED)
else 未配置SSID
WM->>WIFI : set_mode(AP)
WM->>WIFI : set_config(AP)
WM->>WIFI : start()
WIFI-->>WM : 事件(AP_START)
end图表来源 - wifi_manager.c - wifi_manager.c - wifi_manager.c
章节来源 - wifi_manager.c - wifi_manager.c - wifi_manager.c
自动重连机制¶
- 重试上限与超时：最大重试次数与连接超时由全局配置定义
- 断线重连：在断开事件中递增重试计数并自动重连，超过上限后标记失败
- 成功后复位：获取IP后重置重试计数并更新状态
flowchart TD
A["STA断开事件"] --> B{"重试计数 < 上限?"}
B --> |是| C["重试连接<br/>重试计数+1"]
B --> |否| D["设置状态=断开<br/>设置失败标志"]
C --> E["等待事件或超时"]
E --> F{"收到GOT_IP?"}
F --> |是| G["重试计数清零<br/>设置状态=已连接"]
F --> |否| H["继续等待或结束"]图表来源 - wifi_manager.c - wifi_manager.c - config.h
章节来源 - wifi_manager.c - wifi_manager.c - config.h
网络配置管理¶
- 配置项：SSID、密码、是否使用静态IP及静态IP四元组（IP、网关、掩码、DNS）
- 设置与读取：通过配置接口设置当前配置，状态查询接口返回当前状态与IP信息
- 安全协议：根据是否存在密码自动选择WPA2或开放网络
章节来源 - wifi_manager.h - wifi_manager.c - wifi_manager.c
网络状态监控¶
- 连接质量：通过RSSI与信道反映信号强度与干扰情况
- 可用性检查：IP地址有效性和MAC地址获取用于设备识别
- 状态查询：提供状态枚举、字符串化IP、连接判定等辅助查询
章节来源 - wifi_manager.h - wifi_manager.c - wifi_manager.c
API接口文档¶
- 初始化与去初始化：初始化WiFi栈、创建网络接口、注册事件；去初始化释放资源
- 启动与停止：按配置启动STA或AP；停止WiFi并复位状态
- 配置设置与读取：设置/读取WiFi配置
- 连接与断开：连接到指定AP；断开当前连接
- AP模式：启动AP模式并设置参数
- 扫描：扫描周边AP并返回列表
- 回调：注册事件回调以接收状态变化
- 查询：获取当前状态、连接状态、IP字符串
章节来源 - wifi_manager.h - wifi_manager.c - wifi_manager.c - wifi_manager.c - wifi_manager.c - wifi_manager.c - wifi_manager.c - wifi_manager.c - wifi_manager.c - wifi_manager.c
依赖关系分析¶
- 组件耦合：WiFi管理器依赖ESP-IDF的WiFi、网络接口与事件框架
- 外部依赖：使用TCP/IP栈、事件循环、内存分配与日志系统
- 集成点：主程序通过网关配置模块传递持久化参数，LED任务读取状态进行指示
graph LR
MAIN["main.c"] --> WM["wifi_manager.c"]
MAIN --> GWCFG["gateway_config.h"]
WM --> WMHDR["wifi_manager.h"]
WM --> CFG["config.h"]
WM --> ESP_WIFI["esp_wifi"]
WM --> ESP_NETIF["esp_netif"]
WM --> ESP_EVENT["esp_event"]图表来源 - main.c - gateway_config.h - wifi_manager.c - wifi_manager.h - config.h
章节来源 - CMakeLists.txt（组件） - 顶层CMakeLists.txt
性能考虑¶
- 事件驱动：采用事件组与回调减少轮询开销，提高响应效率
- 超时控制：连接超时与重试上限避免长时间阻塞
- 内存管理：合理使用静态缓冲区与事件组，避免频繁动态分配
- 日志级别：在生产环境中可降低日志级别以减少I/O开销
故障排除指南¶
- 无法连接到AP
- 检查SSID/密码正确性与安全协议匹配
- 查看断线原因与重试次数是否达到上限
- 确认AP通道与信号强度是否满足要求
- 连接后无IP
- 检查DHCP服务可用性与路由器配置
- 观察IP丢失事件并确认网络稳定性
- AP模式无法访问
- 确认AP参数（SSID、密码、信道）正确
- 检查客户端设备是否支持所选加密方式
- 状态不一致
- 使用状态查询接口核对当前状态与期望状态
- 检查事件回调是否被正确注册与处理
章节来源 - wifi_manager.c - wifi_manager.c - wifi_manager.c
结论¶
WiFi管理器提供了完整的STA/AP模式支持与事件驱动的状态管理，结合全局配置与网关配置模块实现了从启动到运行的自动化流程。通过清晰的API与完善的错误处理，能够满足BLE网关在不同网络环境下的稳定运行需求。
附录¶
配置示例¶
- 启动流程
- 初始化WiFi管理器
- 从网关配置加载WiFi参数
- 启动WiFi（有配置则连接，无配置则进入AP）
- 常用场景
- STA模式：设置ssid/password后调用连接API
- AP模式：调用AP启动API，供设备配置
- 扫描周边网络：调用扫描API获取可用AP列表
章节来源 - main.c - wifi_manager.c - wifi_manager.c - wifi_manager.c