配置管理器¶

本文引用的文件 - config_manager.c - config_manager.h - config.h - CMakeLists.txt - gateway_config.c - gateway_config.h - partitions.csv - main.c

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考虑
故障排除指南
结论
附录

简介¶

本文件面向ESP32S3 BLE网关的“配置管理器”，系统性阐述其在NVS（非易失性存储）中的持久化机制、配置数据结构、验证与迁移策略、以及热重载能力。文档同时对比了旧版基于键值对的实现与新版统一二进制Blob的实现，帮助读者理解两种方案的差异与适用场景。

项目结构¶

配置管理器位于components/config_manager目录，对外通过头文件暴露统一的API；全局配置常量定义于include/config.h；旧版本实现位于old_version/components/gateway_config与include/gateway_config.h；分区表定义于old_version/partitions.csv；应用入口main.c展示了如何在启动阶段加载配置并驱动其他子系统。

graph TB
subgraph "应用层"
APP["app_main<br/>main.c"]
WEBUI["WebUI服务器"]
WIFI["WiFi管理器"]
MQTT["MQTT客户端"]
BLE["BLE扫描器"]
end
subgraph "配置管理层"
CM["配置管理器<br/>config_manager.c/.h"]
NVS["NVS存储<br/>NVS_NAMESPACE"]
end
subgraph "旧版实现"
GWCFG["旧版配置管理器<br/>gateway_config.c/.h"]
PART["分区表<br/>partitions.csv"]
end
APP --> CM
APP --> WEBUI
APP --> WIFI
APP --> MQTT
APP --> BLE
CM --> NVS
GWCFG --> PART
GWCFG --> NVS

图表来源 - main.c - config_manager.c - gateway_config.c - partitions.csv

章节来源 - config_manager.c - config_manager.h - config.h - gateway_config.c - gateway_config.h - partitions.csv - main.c

核心组件¶

新版配置管理器：以统一的gateway_config_t作为全局配置模型，使用NVS Blob进行一次性读写，内置版本号用于迁移。
旧版配置管理器：以键值对形式存储设备名、WiFi、MQTT、BLE等参数，使用校验位标记配置有效性。
全局配置常量：定义NVS命名空间、默认端口、主题前缀、任务栈大小等系统级参数。
分区表：定义nvs分区位置与大小，确保NVS可被正确初始化与擦写。

章节来源 - config_manager.c - config_manager.h - gateway_config.c - gateway_config.h - config.h - partitions.csv

架构总览¶

配置管理器在系统启动时初始化NVS句柄，尝试从NVS加载配置；若失败则采用默认值并保存。配置结构体包含系统、网络、BLE、MQTT、WebUI等字段，便于集中管理与热更新。

sequenceDiagram
participant APP as "应用入口<br/>main.c"
participant CM as "配置管理器<br/>config_manager.c"
participant NVS as "NVS存储"
APP->>CM : 调用初始化
CM->>NVS : 打开命名空间
CM->>NVS : 读取Blob配置
alt 配置存在且版本匹配
NVS-->>CM : 返回配置
CM->>CM : 设置为当前配置
else 配置不存在或版本不匹配
CM->>CM : 设置默认值
CM->>NVS : 写入默认配置
end
CM-->>APP : 初始化完成

图表来源 - main.c - config_manager.c - config_manager.c

详细组件分析¶

数据结构与存储格式¶

新版统一配置模型gateway_config_t包含：
系统：gateway_id、gateway_name、config_version
网络：network_config_t（模式、SSID、密码、DHCP/静态IP）
BLE：ble_scan_config_t（启用、间隔、窗口、主动扫描、RSSI过滤、名称/MAC过滤）、最大连接数
MQTT：mqtt_config_t（启用、Broker URI、用户名、密码、Client ID、KeepAlive、QoS）
WebUI：webui_enabled、webui_port
存储方式：使用nvs_set_blob/nvs_get_blob以单Blob形式存取整个结构体，简化一致性与版本控制。

classDiagram
class 网络配置 {
+模式
+SSID
+密码
+DHCP
+静态IP
+网关
+掩码
}
class BLE扫描配置 {
+启用
+间隔
+窗口
+主动扫描
+RSSI过滤
+名称过滤
+MAC过滤
+启用MAC过滤
}
class MQTT配置 {
+启用
+BrokerURI
+用户名
+密码
+ClientID
+KeepAlive
+QoS
}
class 网关配置 {
+网关ID
+网关名称
+网络配置
+BLE扫描配置
+最大BLE连接数
+MQTT配置
+WebUI启用
+WebUI端口
+配置版本
}
网关配置 --> 网络配置 : "包含"
网关配置 --> BLE扫描配置 : "包含"
网关配置 --> MQTT配置 : "包含"

图表来源 - config_manager.h

章节来源 - config_manager.h - config_manager.c

NVS存储机制与分区布局¶

命名空间：NVS_NAMESPACE（来自config.h），所有键均在该命名空间下。
旧版分区表：nvs分区位于固定偏移，大小满足键值对存储需求。
新版实现：直接使用nvs_set_blob/nvs_get_blob，无需逐键读写，减少碎片与错误率。
权限控制：NVS由SDK负责擦写均衡与坏块管理；应用侧通过只读/读写打开句柄控制访问模式。

章节来源 - config.h - partitions.csv - config_manager.c - config_manager.c

配置验证与迁移策略¶

版本字段：config_version用于识别配置结构变化。
加载流程：读取Blob后比较版本，不匹配则重置为默认值并保存，确保兼容性。
旧版校验位：通过NVS_KEY_CONFIG_VALID字节标记配置有效性，未通过则视为无有效配置。

flowchart TD
Start(["开始加载"]) --> OpenNVS["打开NVS句柄"]
OpenNVS --> ReadBlob["读取Blob配置"]
ReadBlob --> Found{"找到配置？"}
Found --> |否| UseDefaults["设置默认值"]
Found --> |是| CheckVersion["比较config_version"]
CheckVersion --> Match{"版本匹配？"}
Match --> |否| ResetDefaults["重置默认值并保存"]
Match --> |是| ApplyCfg["应用配置"]
UseDefaults --> SaveCfg["保存默认配置"]
ResetDefaults --> SaveCfg
SaveCfg --> Done(["完成"])
ApplyCfg --> Done

图表来源 - config_manager.c - config_manager.c

章节来源 - config_manager.c - gateway_config.c

热重载与动态更新¶

动态更新：通过config_manager_set_*系列函数更新网络、MQTT、BLE扫描等子配置，并自动触发保存。
回滚机制：当前实现未提供显式回滚；建议在调用保存前先备份当前配置，保存失败时恢复备份。
变更检测：新旧实现均未提供“变更检测”回调；可在上层业务中比较新旧配置指针或字段，按需触发子系统重启。

章节来源 - config_manager.c - config_manager.c

API接口文档¶

初始化/反初始化：config_manager_init、config_manager_deinit
读取/写入/重置：config_manager_get、config_manager_set、config_manager_save、config_manager_load、config_manager_reset
子配置更新：config_manager_set_network、config_manager_set_mqtt、config_manager_set_ble_scan
旧版API（对比参考）：gateway_config_init、gateway_config_load、gateway_config_save、gateway_config_reset、gateway_config_get、gateway_config_set、gateway_config_get_ptr、gateway_config_is_valid、gateway_config_has_wifi、gateway_config_has_mqtt

章节来源 - config_manager.h - gateway_config.h

启动流程与配置加载¶

应用入口在启动时： - 初始化NVS与事件循环 - 初始化WS2812 LED状态指示 - 初始化以太网、WiFi、MQTT、WebUI、BLE扫描器 - 从NVS加载配置并应用到各子系统

sequenceDiagram
participant APP as "app_main"
participant CM as "配置管理器"
participant WIFI as "WiFi管理器"
participant MQTT as "MQTT客户端"
participant WEBUI as "WebUI服务器"
participant BLE as "BLE扫描器"
APP->>CM : 初始化并加载配置
CM-->>APP : 返回当前配置
APP->>WIFI : 应用WiFi配置
APP->>MQTT : 应用MQTT配置并启动
APP->>WEBUI : 初始化
APP->>BLE : 初始化并启动扫描

图表来源 - main.c

章节来源 - main.c

依赖关系分析¶

组件耦合：配置管理器依赖NVS Flash、ESP-IDF日志与内存接口；对外仅暴露有限API，内聚性良好。
外部依赖：NVS命名空间、默认端口、主题前缀等常量来源于config.h。
旧版对比：旧版使用多键存储与互斥锁保护，新版合并为单一Blob并引入版本号，降低复杂度。

graph LR
CM["config_manager.c"] --> CFG["config.h"]
CM --> NVS["NVS SDK"]
CM --> LOG["ESP_LOG"]
CM --> MEM["内存操作"]
GW["gateway_config.c"] --> CFG
GW --> NVS
GW --> SEM["互斥锁"]

图表来源 - config_manager.c - gateway_config.c

章节来源 - config_manager.c - gateway_config.c