ESP-ADF wifi_service子模块wifi_ssid_manager凭证管理函数详解

ESP-ADF wifi_service子模块wifi_ssid_manager凭证管理函数详解

版本信息: v2.7-65-gcf908721

本章节分析的源码位于 /components/wifi_service/src/wifi_ssid_manager.c 文件

WiFi凭证管理函数分析

ESP-ADF的wifi_ssid_manager模块提供了一组函数用于实现WiFi凭证的存储和管理，包括保存SSID和密码、擦除存储的凭证等功能。这些函数构成了WiFi服务的持久化存储基础，使设备能够保存和管理多个WiFi网络信息。

wifi_ssid_manager_save

wifi_ssid_manager_save函数用于保存WiFi的SSID和密码到NVS闪存。下面是其源码实现：

/*** @brief 保存WiFi SSID和密码* * 该函数完成以下主要操作：* 1. 验证SSID和密码长度是否合法* 2. 检查SSID是否已存在* 3. 确定存储位置（新增或覆盖）* 4. 将SSID和密码保存到NVS存储* 5. 更新配置信息* * 本函数在SSID数量达到上限时使用FIFO(先进先出)策略，* 即会删除最早保存的SSID以腾出空间保存新的SSID。* * @param handle WiFi SSID管理器句柄* @param ssid WiFi网络名称* @param pwd WiFi密码* @return ESP_OK表示成功，ESP_FAIL表示失败*/
esp_err_t wifi_ssid_manager_save(wifi_ssid_manager_handle_t handle, const char *ssid, const char *pwd)
{esp_err_t ret = ESP_OK;// 检查SSID和密码长度是否超出限制if (strlen(ssid) >= WIFI_SSID_MAX_LENGTH || strlen(pwd) >= WIFI_PWD_MAX_LENGTH) {ESP_LOGE(TAG, "The length of wifi ssid or password is too long");return ESP_FAIL;}AUDIO_NULL_CHECK(TAG, handle, return ESP_FAIL);// 获取当前SSID配置信息nvs_ssid_conf_t conf = {0};nvs_ssid_list_conf_get(handle, &conf);// 检查SSID是否已存在int8_t stored_id = get_stored_id_by_ssid(handle, conf.exsit_ssid_num, ssid);uint8_t key_id = 0;if (stored_id < 0) { // SSID不存在，需要新增if (conf.exsit_ssid_num < conf.max_ssid_num) {// 还有存储空间，直接添加key_id = conf.exsit_ssid_num;conf.latest_ssid = conf.exsit_ssid_num;conf.exsit_ssid_num++;} else {// 存储空间已满，使用FIFO策略key_id = nvs_get_write_id(handle, conf.exsit_ssid_num);conf.latest_ssid = key_id;}} else {// SSID已存在，直接更新key_id = stored_id;conf.latest_ssid = stored_id;}// 准备并保存WiFi信息nvs_stored_info_t info = {.cnt = 0,.choosen = false,};memcpy(info.ssid, ssid, strlen(ssid));memcpy(info.pwd, pwd, strlen(pwd));// 执行存储操作ret |= nvs_wifi_info_save(handle, key_id, &info);ret |= nvs_set_counter(handle, conf.exsit_ssid_num);ret |= nvs_ssid_list_conf_save(handle, &conf);ret |= nvs_reset_choosen_flag(handle, &conf);if (ret != ESP_OK) {ESP_LOGE(TAG, "Fail to save url to nvs, ret = 0x%x", ret);return ESP_FAIL;}return ESP_OK;
}

下面的流程图展示了wifi_ssid_manager_save函数的执行流程：

这个函数实现了以下几个关键特性：

1. 自动去重：当保存已存在的SSID时，直接更新其密码
2. 有限队列：当SSID数量达到上限时，使用FIFO策略覆盖最旧的SSID
3. 标记最新：总是将最新保存的SSID标记为latest_ssid，便于优先连接
4. 重置标志：保存新SSID后重置所有choosen标志，确保连接逻辑的正确性

wifi_ssid_manager_erase_all

wifi_ssid_manager_erase_all函数用于擦除所有保存的WiFi凭证。下面是其源码实现：

/*** @brief 擦除所有保存的WiFi凭证* * 该函数完成以下主要操作：* 1. 获取当前最大SSID数量限制* 2. 清除所有WiFi信息命名空间数据* 3. 清除配置命名空间数据* 4. 重置配置信息（仅保留最大SSID数量设置）* * 调用此函数后，所有保存的WiFi网络信息将被删除，* 但管理器的最大SSID数量限制会被保留。* * @param handle WiFi SSID管理器句柄* @return ESP_OK表示成功，或者错误码*/
esp_err_t wifi_ssid_manager_erase_all(wifi_ssid_manager_handle_t handle)
{AUDIO_NULL_CHECK(TAG, handle, return ESP_FAIL);esp_err_t ret = ESP_OK;// 保存最大SSID数量限制uint8_t max_ssid_num = 0;nvs_ssid_conf_t conf = {0};ret |= nvs_ssid_list_conf_get(handle, &conf);max_ssid_num = conf.max_ssid_num;// 重置配置，仅保留最大数量限制memset(&conf, 0, sizeof(nvs_ssid_conf_t));conf.max_ssid_num = max_ssid_num;// 清除所有NVS数据action_result_t result = { 0 };ret |= esp_dispatcher_execute_with_func(handle->dispatcher, nvs_action_erase_all, (void *)handle->info_nvs, NULL, &result);ret |= esp_dispatcher_execute_with_func(handle->dispatcher, nvs_action_erase_all, (void *)handle->conf_nvs, NULL, &result);// 保存重置后的配置ret |= nvs_ssid_list_conf_save(handle, &conf);if (ret != ESP_OK) {ESP_LOGE(TAG, "Fail to erase nvs flash");}return ret;
}

下面的流程图展示了wifi_ssid_manager_erase_all函数的执行流程：

这个函数的主要特点包括：

1. 保留配置限制：清除所有凭证但保留最大SSID数量设置，保持管理器功能的一致性
2. 全面清除：同时清除WiFi信息和配置命名空间，确保所有凭证都被删除
3. 重置状态：重新初始化配置信息，将存储状态恢复到初始状态
4. 错误累积：使用|=运算符累积错误码，确保任何步骤失败都能被检测到

内部实现机制

存储策略分析

WiFi凭证管理函数采用了以下存储策略：

1. 双空间存储：使用两个NVS命名空间分别存储配置元数据和实际WiFi凭证

   • WIFI_CONF_NVS_NAMESPACE：存储配置元数据，如最大SSID数量、存储状态等
   • WIFI_INFO_NVS_NAMESPACE：存储实际的WiFi凭证（SSID和密码）

2. FIFO替换策略：当存储空间已满时，采用先进先出策略替换最早存储的凭证

   • 使用计数器(cnt)跟踪每个SSID的存储顺序
   • 通过nvs_get_write_id函数识别最旧的SSID

3. 自动去重：保存时自动检查SSID是否已存在，避免重复存储

   • 使用get_stored_id_by_ssid函数查找SSID是否已存在
   • 如已存在，直接更新对应的密码信息

4. 状态标记：使用多个标志位管理凭证状态

   • latest_ssid：标记最新保存的SSID，用于优先连接
   • choosen：标记当前选择的SSID，用于跟踪连接状态

内部数据流向

凭证管理函数内部的数据流向如下：

关键辅助函数分析

凭证管理函数依赖几个关键的内部辅助函数：

重要的内部辅助函数详解

以下三个函数是WiFi凭证管理的重要内部组件，虽然不直接暴露给用户，但它们实现了凭证管理的核心功能：

get_stored_id_by_ssid

/*** @brief 查找指定SSID在存储中的索引ID* * 遍历所有已存储的WiFi凭证，查找与给定参数匹配的SSID。* 该函数是实现自动去重功能的核心，确保相同的SSID不会* 多次添加到存储中。* * @param handle WiFi SSID管理器句柄* @param exsit_ssid_num 当前存在的SSID数量* @param ssid 要查找的SSID字符串* @return 成功返回找到的SSID索引，失败返回ESP_FAIL(-1)*/
static int8_t get_stored_id_by_ssid(wifi_ssid_manager_handle_t handle, uint8_t exsit_ssid_num, const char *ssid)
{// 初始化信息结构体nvs_stored_info_t info = {0};// 遍历所有存储的WiFi凭证for (int i = 0; i < exsit_ssid_num; i++) {// 清空信息结构，准备读取下一个凭证memset(&info, 0, sizeof(nvs_stored_info_t));// 从存储中获取凭证信息nvs_wifi_info_get(handle, i, &info);// 快速过滤：比较SSID长度，如果不同则跳过if (strlen(info.ssid) != strlen(ssid)) {continue;}// 比较SSID内容是否相同if (strcmp(info.ssid, ssid) == 0) {ESP_LOGD(TAG, "Found the same ssid in flash, update it");return i; // 返回找到的凭证索引}}// 未找到匹配项，返回失败return ESP_FAIL;
}

该函数用于遍历已存储的所有WiFi凭证，判断指定的SSID是否已存在。它先比较SSID长度进行快速过滤，如果长度相同才进一步比较内容。这个函数在凭证保存时起到了关键作用，确保了同一网络的凭证不会重复存储，而是直接更新密码。

nvs_get_write_id

/*** @brief 获取应覆盖的WiFi凭证ID* * 当存储空间已满时，该函数用于确定应该覆盖哪一个现有的* WiFi凭证。该函数实现了FIFO（先进先出）策略，即覆盖存储时间* 最长的凭证。* * @param handle WiFi SSID管理器句柄* @param exsit_ssid_num 当前存在的SSID数量* @return 需覆盖的WiFi凭证ID*/
static uint8_t nvs_get_write_id(wifi_ssid_manager_handle_t handle, uint8_t exsit_ssid_num)
{// 初始化计数器最大值和对应的IDuint8_t max_cnt = 0, max_cnt_id = 0;nvs_stored_info_t info = {0};// 遍历所有存储的WiFi凭证for (int i = 0; i < exsit_ssid_num; i++) {// 清空信息结构体memset(&info, 0, sizeof(nvs_stored_info_t));// 获取凭证信息nvs_wifi_info_get(handle, i, &info);// 如果当前凭证的计数器值大于或等于已记录的最大值// 则更新最大计数器值和对应IDif (info.cnt >= max_cnt) {max_cnt = info.cnt;max_cnt_id = i;}}// 返回计数器值最大的凭证IDreturn max_cnt_id;
}

该函数在存储空间已满需要替换现有凭证时使用。它通过遍历所有凭证并查找计数器值最大的凭证，实现了FIFO（先进先出）替换策略。这确保了在空间不足时，始终会覆盖最早添加的WiFi凭证。

nvs_set_counter 函数

/*** @brief 递增所有WiFi凭证的计数器值* * 递增所有已存储凭证的计数器值，用于跟踪凭证的“年龄”。* 该函数是实现FIFO（先进先出）替换策略的关键部分，确保* 新添加的凭证计数器值保持最小。* * @param handle WiFi SSID管理器句柄* @param exsit_ssid_num 当前存在的SSID数量* @return 成功返回ESP_OK，失败返回ESP_FAIL*/
static esp_err_t nvs_set_counter(wifi_ssid_manager_handle_t handle, uint8_t exsit_ssid_num)
{// 初始化返回值和信息结构体esp_err_t ret = ESP_OK;nvs_stored_info_t info = {0};// 遍历所有存在的WiFi凭证for (int i = 0; i < exsit_ssid_num; i++) {// 清空信息结构体，准备读取下一个凭证memset(&info, 0, sizeof(nvs_stored_info_t));// 从存储中获取凭证信息，并累积错误码ret |= nvs_wifi_info_get(handle, i, &info);// 将计数器值递增1，这是实现FIFO策略的关键info.cnt ++;// 保存更新后的凭证信息，并累积错误码ret |= nvs_wifi_info_save(handle, i, &info);}// 检查操作过程中是否有错误发生if (ret != ESP_OK) {ESP_LOGE(TAG, "Fail to set counter");return ESP_FAIL;}// 所有操作成功，返回ESP_OKreturn ESP_OK;
}

该函数的作用是递增所有已存储WiFi凭证的计数器值，是实现FIFO替换策略的关键辅助函数。它确保了计数器值能准确反映凭证的“年龄”。

nvs_reset_choosen_flag

重置所有凭证的选择标志

• 确保连接逻辑的正确性
• 防止多个凭证同时被标记为已选择

应用示例

下面是一个使用WiFi凭证管理函数的完整示例，展示了这些函数在实际应用中的使用方式：

#include <string.h>
#include "esp_log.h"
#include "wifi_ssid_manager.h"static const char *TAG = "WIFI_CRED_EXAMPLE";// 凭证管理示例函数
void wifi_credential_management_example(void)
{// 创建WiFi SSID管理器，最多保存5个SSIDwifi_ssid_manager_handle_t mgr = wifi_ssid_manager_create(5);if (mgr == NULL) {ESP_LOGE(TAG, "创建WiFi SSID管理器失败");return;}// 保存多个WiFi凭证ESP_LOGI(TAG, "保存WiFi凭证1");esp_err_t ret = wifi_ssid_manager_save(mgr, "HomeWiFi", "home123456");if (ret != ESP_OK) {ESP_LOGE(TAG, "保存WiFi凭证1失败");}ESP_LOGI(TAG, "保存WiFi凭证2");ret = wifi_ssid_manager_save(mgr, "OfficeWiFi", "office789");if (ret != ESP_OK) {ESP_LOGE(TAG, "保存WiFi凭证2失败");}ESP_LOGI(TAG, "保存WiFi凭证3");ret = wifi_ssid_manager_save(mgr, "CafeWiFi", "cafe2023");if (ret != ESP_OK) {ESP_LOGE(TAG, "保存WiFi凭证3失败");}// 显示当前存储的所有WiFi凭证ESP_LOGI(TAG, "显示所有存储的WiFi凭证:");wifi_ssid_manager_list_show(mgr);// 更新已存在的WiFi凭证密码ESP_LOGI(TAG, "更新HomeWiFi的密码");ret = wifi_ssid_manager_save(mgr, "HomeWiFi", "newhome888");if (ret != ESP_OK) {ESP_LOGE(TAG, "更新WiFi密码失败");}// 尝试获取最佳WiFi配置（通常会扫描并匹配信号最强的网络）wifi_config_t wifi_config = {0};ret = wifi_ssid_manager_get_best_config(mgr, &wifi_config);if (ret == ESP_OK) {ESP_LOGI(TAG, "获取到最佳WiFi配置: SSID=%s", (char *)wifi_config.sta.ssid);} else {ESP_LOGE(TAG, "获取最佳WiFi配置失败");}// 获取最新保存的WiFi配置memset(&wifi_config, 0, sizeof(wifi_config_t));ret = wifi_ssid_manager_get_latest_config(mgr, &wifi_config);if (ret == ESP_OK) {ESP_LOGI(TAG, "获取到最新WiFi配置: SSID=%s", (char *)wifi_config.sta.ssid);} else {ESP_LOGE(TAG, "获取最新WiFi配置失败");}// 擦除所有WiFi凭证ESP_LOGI(TAG, "擦除所有WiFi凭证");ret = wifi_ssid_manager_erase_all(mgr);if (ret != ESP_OK) {ESP_LOGE(TAG, "擦除WiFi凭证失败");}// 确认所有凭证已被擦除ESP_LOGI(TAG, "确认所有凭证已被擦除:");wifi_ssid_manager_list_show(mgr);// 销毁WiFi SSID管理器ESP_LOGI(TAG, "销毁WiFi SSID管理器");wifi_ssid_manager_destroy(mgr);
}void app_main(void)
{// 初始化NVS闪存（通常在应用程序开始时执行）esp_err_t ret = nvs_flash_init();if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {// NVS分区被充满或发现新版本，需要擦除处理ESP_ERROR_CHECK(nvs_flash_erase());ret = nvs_flash_init();}ESP_ERROR_CHECK(ret);// 执行凭证管理示例wifi_credential_management_example();
}

在这个示例中，我们演示了WiFi凭证管理函数的典型用法：

1. 创建管理器并设置最大存储数量
2. 保存多个WiFi凭证（包括新增和更新）
3. 列出当前存储的所有凭证
4. 获取最佳配置和最新配置
5. 擦除所有凭证
6. 销毁管理器释放资源

常见使用场景

WiFi凭证管理函数在以下场景中特别有用：

1. 多网络管理：设备需要在多个WiFi网络间切换，如家庭/办公室/公共场所
2. 配网后存储：通过配网（如SmartConfig、蓝牙配网等）获取的WiFi凭证需要持久化存储
3. 备用网络：存储多个备用网络，当主网络不可用时自动切换
4. 网络优先级：基于信号强度或保存顺序确定连接优先级
5. 恢复出厂设置：需要清除所有存储的网络凭证

总结

ESP-ADF的WiFi凭证管理函数提供了一套完整的接口，用于管理WiFi网络凭证的存储、检索和清除。这些函数具有以下几个关键特性：

1. 有限存储管理：通过最大SSID数量限制和FIFO替换策略，有效管理有限的存储空间
2. 自动去重：保存时自动检查SSID是否已存在，避免重复存储
3. 优先级管理：通过latest_ssid和choosen标志管理网络连接优先级
4. 持久化存储：利用NVS闪存实现WiFi凭证的持久化存储，断电不丢失
5. 完整的生命周期：提供从保存到擦除的完整生命周期管理

通过合理使用这些凭证管理函数，开发者可以轻松实现设备的多网络管理，提升用户体验和设备连接可靠性。