网关配置API¶

本文档引用的文件 - gateway_config.h - gateway_config.c - config.h（旧版） - config_manager.h - config_manager.c - config.h（新版） - wifi_manager.h - mqtt_client_wrapper.h（旧版） - ble_scanner.h（旧版）

目录¶

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

简介¶

本文件为网关配置管理组件的完整API文档，覆盖配置读取、写入、验证与持久化接口；详细说明配置结构体定义、默认值设置、配置加载与保存流程；并提供函数签名、参数说明、返回值类型与错误码定义。同时包含配置验证规则、热重载机制、备份恢复功能与配置迁移接口建议，并给出配置文件格式说明、版本兼容性处理与安全注意事项，以及实际配置示例与最佳实践指导。

项目结构¶

本项目采用模块化设计，配置管理分为“旧版”与“新版”两套实现： - 旧版：基于NVS键值对存储，面向WiFi、MQTT、BLE扫描等基础配置。 - 新版：统一的配置管理器，使用二进制blob存储，支持网络、BLE、MQTT、WebUI等完整配置，并内置版本控制与自动迁移。

graph TB
subgraph "配置管理旧版"
GC_H["gateway_config.h"]
GC_C["gateway_config.c"]
CFG_H_OLD["config.h旧版"]
WIFI_H["wifi_manager.h"]
MQTT_H_OLD["mqtt_client_wrapper.h旧版"]
BLE_H_OLD["ble_scanner.h旧版"]
end
subgraph "配置管理新版"
CM_H["config_manager.h"]
CM_C["config_manager.c"]
CFG_H_NEW["config.h新版"]
end
GC_H --> GC_C
GC_C --> CFG_H_OLD
GC_C --> WIFI_H
GC_C --> MQTT_H_OLD
GC_C --> BLE_H_OLD
CM_H --> CM_C
CM_C --> CFG_H_NEW

图表来源 - gateway_config.h - gateway_config.c - config.h（旧版） - wifi_manager.h - mqtt_client_wrapper.h（旧版） - ble_scanner.h（旧版） - config_manager.h - config_manager.c - config.h（新版）

章节来源 - gateway_config.h - gateway_config.c - config.h（旧版） - config_manager.h - config_manager.c - config.h（新版）

核心组件¶

本节概述两大配置管理组件及其职责： - 旧版配置管理器：提供设备名、WiFi、MQTT、BLE扫描与系统设置的读取、保存、重置与有效性检查。 - 新版配置管理器：提供统一的gateway_config_t结构，含系统、网络、BLE、MQTT、WebUI与版本号字段，支持初始化、加载、保存、重置与分项更新。

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

架构总览¶

新旧两套配置管理器在不同阶段服务于系统，其交互如下：

sequenceDiagram
participant APP as "应用模块"
participant CM as "配置管理器新版"
participant NVS as "NVS 存储"
participant GC as "配置管理器旧版"
APP->>CM : 初始化打开NVS
CM->>NVS : 读取配置blob
alt 配置存在且版本匹配
NVS-->>CM : 返回配置数据
CM->>CM : 设置默认值若缺失字段
CM-->>APP : 初始化完成
else 配置不存在或版本不匹配
CM->>CM : 设置默认值
CM->>NVS : 写入配置blob
CM-->>APP : 初始化完成
end
APP->>GC : 初始化创建互斥量，加载NVS
GC->>NVS : 读取键值对
alt 配置有效
NVS-->>GC : 返回配置
GC-->>APP : 初始化完成
else 无配置或无效
GC->>GC : 使用默认值
GC-->>APP : 初始化完成
end

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

详细组件分析¶

旧版配置管理器（gateway_config）¶

该组件负责将配置以键值形式存入NVS，支持以下操作： - 初始化：创建互斥量、设置默认值、尝试从NVS加载。 - 加载：按键读取字符串与数值，校验配置有效性标记。 - 保存：写入所有键值，最后设置有效性标记并提交。 - 重置：擦除NVS全部内容，恢复默认值。 - 查询：获取当前配置副本、指针、有效性与是否配置了WiFi/MQTT。

classDiagram
class GatewayConfig {
+char device_name[32]
+wifi_config_data_t wifi
+mqtt_config_t mqtt
+ble_scan_params_t ble_scan
+ble_device_filter_t ble_filter
+bool auto_start_scan
+uint32_t status_report_interval
}
class WiFiConfig {
+char ssid[32]
+char password[64]
}
class MQTTConfig {
+char broker_uri[128]
+char username[64]
+char password[64]
+char base_topic[256]
+uint16_t keepalive
+bool use_tls
+bool clean_session
}
class BLEScanParams {
+uint16_t scan_interval
+uint16_t scan_window
+uint8_t scan_type
+uint8_t filter_policy
+bool filter_duplicates
}
class BLEDeviceFilter {
+char name_filter[32]
+int8_t rssi_filter
+uint8_t mac_filter[6]
+bool mac_filter_enabled
}
GatewayConfig --> WiFiConfig : "包含"
GatewayConfig --> MQTTConfig : "包含"
GatewayConfig --> BLEScanParams : "包含"
GatewayConfig --> BLEDeviceFilter : "包含"

图表来源 - gateway_config.h - wifi_manager.h - mqtt_client_wrapper.h（旧版） - ble_scanner.h（旧版）

API清单（旧版） - 初始化 - 函数：gateway_config_init() - 参数：无 - 返回：ESP_OK 或错误码 - 说明：创建互斥量、设置默认值、尝试加载NVS - 加载 - 函数：gateway_config_load() - 参数：无 - 返回：ESP_OK 或 ESP_ERR_NOT_FOUND - 说明：读取键值对，校验有效性标记 - 保存 - 函数：gateway_config_save() - 参数：无 - 返回：ESP_OK 或错误码 - 说明：写入键值对并提交 - 重置 - 函数：gateway_config_reset() - 参数：无 - 返回：ESP_OK - 说明：擦除NVS并恢复默认值 - 获取/设置 - 函数：gateway_config_get(), gateway_config_set(), gateway_config_get_ptr() - 参数：gateway_config_t* - 返回：ESP_OK 或 ESP_ERR_INVALID_ARG - 有效性检查 - 函数：gateway_config_is_valid(), gateway_config_has_wifi(), gateway_config_has_mqtt() - 返回：布尔值

默认值设置（旧版） - 设备名：来自全局宏，默认值见全局配置头文件 - BLE扫描：间隔、窗口、类型、过滤策略、去重 - MQTT：基础主题、客户端ID、保活时间、清理会话 - 系统：自动开始扫描、状态上报间隔

章节来源 - gateway_config.c - gateway_config.c - gateway_config.c - gateway_config.c - gateway_config.c - gateway_config.c - gateway_config.c - gateway_config.h - config.h（旧版）

新版配置管理器（config_manager）¶

该组件提供统一的gateway_config_t结构，支持： - 初始化：打开NVS、尝试加载、失败则设置默认值并保存 - 加载：读取二进制blob，进行版本校验，不匹配则重置并保存 - 保存：写入二进制blob并提交 - 重置：设置默认值并保存 - 分项更新：网络、MQTT、BLE扫描配置的独立更新接口

flowchart TD
Start(["入口"]) --> Init["初始化打开NVS"]
Init --> Load["尝试加载配置"]
Load --> Found{"找到配置？"}
Found --> |否| Defaults["设置默认值"]
Found --> |是| VersionCheck["版本校验"]
VersionCheck --> Match{"版本匹配？"}
Match --> |否| ResetDefaults["重置为默认值并保存"]
Match --> |是| Ready["准备就绪"]
Defaults --> SaveDefaults["保存默认值"]
SaveDefaults --> Ready
ResetDefaults --> Ready
Ready --> End(["退出"])

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

API清单（新版） - 初始化/反初始化 - 函数：config_manager_init(), config_manager_deinit() - 返回：ESP_OK 或错误码 - 获取/设置 - 函数：config_manager_get(), config_manager_set() - 返回：ESP_OK 或 ESP_ERR_INVALID_ARG - 保存/加载/重置 - 函数：config_manager_save(), config_manager_load(), config_manager_reset() - 返回：ESP_OK 或错误码 - 分项更新 - 函数：config_manager_set_network(), config_manager_set_mqtt(), config_manager_set_ble_scan() - 返回：ESP_OK 或 ESP_ERR_INVALID_ARG

默认值设置（新版） - 系统：生成网关ID（基于MAC）、网关名称、版本号 - 网络：默认模式、DHCP启用 - BLE：启用扫描、扫描参数、主动扫描、RSSI过滤、最大连接数 - MQTT：禁用、保活、QoS、客户端ID - WebUI：启用、端口

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

配置结构体定义与字段说明¶

旧版gateway_config_t
字段：设备名、WiFi配置、MQTT配置、BLE扫描参数、BLE设备过滤器、自动启动扫描、状态上报间隔
关联子结构：wifi_config_data_t、mqtt_config_t、ble_scan_params_t、ble_device_filter_t
新版gateway_config_t
字段：网关ID、网关名称、网络配置、BLE扫描配置、最大BLE连接数、MQTT配置、WebUI开关与端口、配置版本号
关联子结构：network_config_t、ble_scan_config_t、mqtt_config_t

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

配置验证规则与热重载机制¶

旧版
通过有效性标记键判断配置是否有效；加载失败时回退到默认值。
支持热重载：调用加载接口可重新从NVS读取最新配置。
新版
通过配置版本号字段进行版本校验；不匹配时自动重置为默认值并保存。
支持热重载：调用加载接口后立即生效，分项更新接口会自动保存。

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

备份与恢复功能¶

旧版
提供重置接口，擦除NVS并恢复默认值；可结合外部工具导出NVS键值进行备份。
新版
通过保存/加载接口实现备份与恢复；建议定期保存当前配置，必要时从NVS恢复。

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

配置迁移接口建议¶

版本升级时，新版本加载旧版本配置：
若版本不匹配，先重置为默认值，再根据旧版本字段映射到新版本结构，最后保存。
建议保留迁移函数，避免直接覆盖用户配置。

章节来源 - config_manager.c

配置文件格式说明与版本兼容性¶

旧版：NVS键值对存储，键包括设备名、WiFi SSID/密码、MQTT URI/用户名/密码/主题、BLE自动扫描、配置有效性标记。
新版：NVS二进制blob存储，键为单一配置键，包含完整结构体；通过config_version字段进行版本兼容性控制。

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

安全考虑事项¶

密码与敏感信息：旧版以明文字符串形式存储于NVS，建议在产品环境中配合加密存储或安全启动方案。
权限控制：NVS读写需在受控环境下进行，避免并发写入导致损坏。
版本控制：新版本通过版本号强制迁移，防止跨版本配置冲突。

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

实际配置示例与最佳实践¶

示例（旧版）：设置设备名为“ESP32S3_BLE_GW”，WiFi为“HomeNetwork”和密码，“MQTT使用默认URI”，BLE自动扫描开启。
示例（新版）：启用MQTT、设置Broker URI与用户名密码、启用WebUI、设置BLE扫描参数与最大连接数。
最佳实践：
首次运行时调用初始化接口，确保默认值已设置并保存。
更新配置后及时调用保存接口，避免掉电丢失。
版本升级前做好备份，升级后验证配置可用性。
对外暴露的WebUI仅在可信网络内开放，生产环境关闭调试输出。

章节来源 - gateway_config.c - config_manager.c - config.h（新版）

依赖关系分析¶

旧版与新版配置管理器的依赖关系如下：

graph LR
CM_H["config_manager.h"] --> CM_C["config_manager.c"]
CM_C --> CFG_H_NEW["config.h新版"]
GC_H["gateway_config.h"] --> GC_C["gateway_config.c"]
GC_C --> CFG_H_OLD["config.h旧版"]
GC_C --> WIFI_H["wifi_manager.h"]
GC_C --> MQTT_H_OLD["mqtt_client_wrapper.h旧版"]
GC_C --> BLE_H_OLD["ble_scanner.h旧版"]

图表来源 - config_manager.h - config_manager.c - config.h（新版） - gateway_config.h - gateway_config.c - config.h（旧版） - wifi_manager.h - mqtt_client_wrapper.h（旧版） - ble_scanner.h（旧版）

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

性能考量¶

NVS访问：频繁读写NVS会影响系统性能，建议批量更新后再保存，避免多次commit。
互斥保护：旧版使用互斥量保护全局配置，避免并发读写；新版通过单点保存接口降低竞争。
版本校验：新版本在加载时进行版本校验，避免不兼容配置带来的运行时开销。
任务栈与优先级：参考全局配置头文件中任务栈大小与优先级设置，确保配置管理不影响关键任务。

章节来源 - gateway_config.c - config_manager.c - config.h（新版）

故障排查指南¶

常见问题与处理建议： - NVS打开失败：检查NVS命名空间与分区是否正确挂载。 - 加载失败或配置无效：确认有效性标记或版本号是否正确；必要时执行重置。 - 保存失败：检查NVS容量与磨损均衡，避免频繁写入。 - 并发访问冲突：旧版通过互斥量保护；如出现死锁，检查调用路径与释放顺序。 - 配置未生效：确认是否调用了保存接口，或是否处于热重载流程中。

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

结论¶

新版配置管理器提供了更完善的统一配置模型与版本控制能力，适合长期演进与维护；旧版配置管理器则适用于基础场景与快速集成。建议在新项目中优先采用新版，并结合版本迁移策略平滑过渡。

附录¶

错误码说明（部分）
ESP_OK：成功
ESP_ERR_INVALID_ARG：参数无效
ESP_ERR_INVALID_STATE：状态无效（如NVS未打开）
ESP_ERR_NOT_FOUND：未找到配置
ESP_ERR_NO_MEM：内存不足
其他：NVS相关错误由ESP-IDF返回

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