系统配置数据模型

本文档引用的文件 - config.h - config_manager.h - config_manager.c - network_manager.h - wifi_manager.h - mqtt_client_wrapper.h - ble_scanner.h - gateway_config.h - gateway_config.c - config.h

目录

1. 引言
2. 项目结构
3. 核心组件
4. 架构概览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排除指南
9. 结论
10. 附录

引言

本文档详细说明ESP32S3 BLE网关的系统配置数据模型，包括全局配置结构体的层次结构、字段定义和默认值设置。文档涵盖WiFi配置参数、MQTT连接设置、网络接口配置、配置验证规则、参数约束、业务逻辑检查、持久化机制（NVS存储格式）、热重载功能、配置迁移策略、版本兼容性与回滚机制，以及配置备份恢复、导入导出功能和安全考虑。

项目结构

项目采用模块化设计，配置管理分为新旧两个版本：

graph TB
subgraph "新版本配置管理"
CM[config_manager.c]
CMH[config_manager.h]
CFG[config.h]
NM[network_manager.h]
WM[wifi_manager.h]
MM[mqtt_client_wrapper.h]
BM[ble_scanner.h]
end
subgraph "旧版本配置管理"
OGC[gateway_config.c]
OGCH[gateway_config.h]
OCFG[old_version/include/config.h]
end
CM --> CFG
CM --> NM
CM --> WM
CM --> MM
CM --> BM
OGC --> OGCH
OGC --> OCFG

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

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

核心组件

全局配置结构体层次结构

新版本采用分层配置模型：

classDiagram
class gateway_config_t {
+char gateway_id[32]
+char gateway_name[32]
+network_config_t network
+ble_scan_config_t ble_scan
+uint8 max_ble_connections
+mqtt_config_t mqtt
+bool webui_enabled
+uint16 webui_port
+uint32 config_version
}
class network_config_t {
+network_mode_t mode
+char wifi_ssid[32]
+char wifi_password[64]
+bool eth_dhcp
+uint32 eth_static_ip
+uint32 eth_gateway
+uint32 eth_netmask
}
class ble_scan_config_t {
+bool enabled
+uint16 interval
+uint16 window
+bool active_scan
+int8 rssi_filter
+char name_filter[32]
+uint8 mac_filter[6]
+bool mac_filter_enabled
}
class mqtt_config_t {
+bool enabled
+char broker_uri[128]
+char username[32]
+char password[64]
+char client_id[32]
+uint16 keepalive
+uint8 qos
}
gateway_config_t --> network_config_t
gateway_config_t --> ble_scan_config_t
gateway_config_t --> mqtt_config_t

图表来源 - config_manager.h

字段定义与默认值

系统配置字段

• gateway_id: 网关唯一标识符，默认为空字符串
• gateway_name: 网关显示名称，默认为"ESP32S3-BLE-Gateway"
• config_version: 配置版本号，默认为1

网络配置字段

• mode: 网络模式，默认为NET_MODE_ETH_PRIMARY
• wifi_ssid: WiFi SSID，默认为空字符串
• wifi_password: WiFi密码，默认为空字符串
• eth_dhcp: 以太网DHCP开关，默认为true
• eth_static_ip: 静态IP地址，默认为0
• eth_gateway: 网关地址，默认为0
• eth_netmask: 子网掩码，默认为0

BLE扫描配置字段

• enabled: 扫描启用开关，默认为true
• interval: 扫描间隔（毫秒），默认为50ms
• window: 扫描窗口（毫秒），默认为30ms
• active_scan: 主动扫描模式，默认为true
• rssi_filter: RSSI过滤阈值，默认为-60dBm
• name_filter: 设备名称过滤器，默认为空字符串
• mac_filter: MAC地址过滤器，默认全零
• mac_filter_enabled: MAC过滤器开关，默认为false

MQTT配置字段

• enabled: MQTT服务开关，默认为true
• broker_uri: Broker URI，默认为空字符串
• username: 用户名，默认为空字符串
• password: 密码，默认为空字符串
• client_id: 客户端ID，默认为"ESP32S3-BLE-Gateway"
• keepalive: Keepalive间隔（秒），默认为60
• qos: QoS级别，默认为0

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

架构概览

配置管理系统采用分层架构，支持热重载和版本控制：

graph TB
subgraph "应用层"
APP[应用程序]
API[REST API]
WEBUI[Web界面]
end
subgraph "配置管理层"
CM[Config Manager]
NM[Network Manager]
WM[WiFi Manager]
MM[MQTT Manager]
BM[BLE Manager]
end
subgraph "存储层"
NVS[NVS Flash]
SPIFFS[SPIFFS]
end
subgraph "硬件抽象层"
ETH[CH390 Ethernet]
WIFI[WiFi Radio]
BLE[BLE Controller]
end
APP --> CM
API --> CM
WEBUI --> CM
CM --> NM
CM --> WM
CM --> MM
CM --> BM
CM --> NVS
CM --> SPIFFS
NM --> ETH
WM --> WIFI
BM --> BLE

图表来源 - config_manager.c - network_manager.h - config.h

详细组件分析

配置管理器实现

配置管理器提供完整的配置生命周期管理：

sequenceDiagram
participant App as 应用程序
participant CM as 配置管理器
participant NVS as NVS存储
participant CB as 回调函数
App->>CM : 初始化配置管理器
CM->>NVS : 加载配置
NVS-->>CM : 返回配置数据
CM->>CM : 设置默认值
CM->>CB : 触发初始化完成回调
App->>CM : 更新配置
CM->>CM : 验证配置有效性
CM->>NVS : 保存配置
NVS-->>CM : 确认保存
CM->>CB : 触发配置变更回调
App->>CM : 获取配置
CM-->>App : 返回当前配置

图表来源 - config_manager.c

关键实现特性

1. 线程安全: 使用互斥锁保护配置访问
2. 版本控制: 支持配置版本追踪和迁移
3. 热重载: 运行时配置更新无需重启
4. 持久化: 自动保存到NVS存储
5. 回调机制: 支持配置变更通知

章节来源 - config_manager.c

网络配置管理

网络管理器支持多种网络模式和动态切换：

stateDiagram-v2
[*] --> Disconnected
Disconnected --> EthConnected : 启动以太网
Disconnected --> WifiConnected : 启动WiFi
Disconnected --> ApMode : 启动AP模式
EthConnected --> WifiConnected : 切换到WiFi优先
WifiConnected --> EthConnected : 切换到以太网优先
EthConnected --> Disconnected : 断开连接
WifiConnected --> Disconnected : 断开连接
ApMode --> Disconnected : 停止AP模式

图表来源 - network_manager.h

网络模式配置

模式	描述	默认行为
ETH_ONLY	仅使用以太网	独立连接
WIFI_ONLY	仅使用WiFi	独立连接
ETH_PRIMARY	以太网优先	以太网可用时优先
WIFI_PRIMARY	WiFi优先	WiFi可用时优先

章节来源 - network_manager.h - config.h

WiFi配置参数

WiFi配置采用严格的参数验证和约束：

flowchart TD
Start([WiFi配置输入]) --> ValidateSSID["验证SSID长度<br/>(1-32字符)"]
ValidateSSID --> SSIDValid{"SSID有效?"}
SSIDValid --> |否| ErrorSSID["返回错误"]
SSIDValid --> |是| ValidatePass["验证密码长度<br/>(0-63字符)"]
ValidatePass --> PassValid{"密码有效?"}
PassValid --> |否| ErrorPass["返回错误"]
PassValid --> |是| ValidateIP["验证静态IP配置"]
ValidateIP --> IPValid{"IP配置有效?"}
IPValid --> |否| ErrorIP["返回错误"]
IPValid --> |是| ApplyConfig["应用WiFi配置"]
ApplyConfig --> Success["配置成功"]
ErrorSSID --> End([结束])
ErrorPass --> End
ErrorIP --> End
Success --> End

图表来源 - wifi_manager.h

WiFi参数约束

• SSID长度: 1-32字符，不能为空
• 密码长度: 0-63字符（开放网络可为空）
• 静态IP配置: 当启用静态IP时，必须提供完整的网络参数
• DNS服务器: 支持主备DNS配置

章节来源 - wifi_manager.h

MQTT连接设置

MQTT配置支持多种连接模式和安全选项：

classDiagram
class mqtt_config_t {
+char broker_uri[128]
+char username[32]
+char password[64]
+char client_id[32]
+char base_topic[256]
+uint16 keepalive
+bool use_tls
+bool clean_session
}
class mqtt_state_t {
<<enumeration>>
DISCONNECTED
CONNECTING
CONNECTED
ERROR
}
class mqtt_message_t {
+char topic[256]
+char* payload
+uint16 payload_len
+uint8 qos
+bool retain
}
mqtt_config_t --> mqtt_state_t
mqtt_config_t --> mqtt_message_t

图表来源 - mqtt_client_wrapper.h

MQTT配置验证规则

1. Broker URI格式: 支持mqtt://和mqtts://协议
2. 客户端ID: 最大32字符，建议使用设备唯一标识
3. Keepalive时间: 10-300秒范围内
4. 用户名密码: 长度限制在配置常量范围内
5. 主题前缀: 符合MQTT主题规范

章节来源 - mqtt_client_wrapper.h

BLE扫描配置

BLE扫描配置提供灵活的设备过滤和监控能力：

flowchart LR
subgraph "扫描参数"
Interval[扫描间隔<br/>50ms]
Window[扫描窗口<br/>30ms]
Type[扫描类型<br/>主动/被动]
Filter[重复过滤<br/>启用]
end
subgraph "设备过滤"
RSSI[RSSI阈值<br/>-60dBm]
Name[名称过滤<br/>空=禁用]
MAC[MAC过滤<br/>禁用]
end
subgraph "连接参数"
ConnMax[最大连接数<br/>8]
IntervalMin[最小间隔<br/>30ms]
IntervalMax[最大间隔<br/>50ms]
Latency[连接延迟<br/>0]
end
Interval --> RSSI
Window --> Name
Type --> MAC
Filter --> ConnMax
ConnMax --> IntervalMin
IntervalMin --> IntervalMax
IntervalMax --> Latency

图表来源 - ble_scanner.h - config.h

BLE配置参数

• 扫描间隔: 10-1000ms，默认50ms
• 扫描窗口: 10-1000ms，默认30ms
• 扫描类型: 主动扫描支持读取响应数据
• 重复过滤: 减少重复设备报告
• 最大设备数: 10-500台，默认100台
• 设备超时: 30-300秒，默认60秒

章节来源 - ble_scanner.h - config.h

依赖关系分析

配置系统各组件之间的依赖关系：

graph TB
subgraph "配置定义层"
CFGH[config.h]
CMH[config_manager.h]
end
subgraph "实现层"
CM[config_manager.c]
NM[network_manager.c]
WM[wifi_manager.c]
MM[mqtt_client_wrapper.c]
end
subgraph "外部依赖"
NVS[nvs_flash.h]
ESPIDF[ESP-IDF]
LWIP[lwip]
end
CFGH --> CMH
CMH --> CM
CM --> NVS
CM --> ESPIDF
CM --> LWIP
CM --> NM
CM --> WM
CM --> MM

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

组件耦合度分析

组件	内聚性	耦合度	依赖关系
Config Manager	高	中等	依赖所有子系统
Network Manager	高	低	仅依赖底层网络
WiFi Manager	高	低	仅依赖WiFi驱动
MQTT Manager	高	低	仅依赖MQTT库
Storage Layer	高	低	仅依赖NVS

章节来源 - config_manager.c

性能考虑

配置访问优化

1. 内存布局: 配置结构体按使用频率排序，减少缓存未命中
2. 批量操作: 支持批量配置更新，减少NVS写入次数
3. 异步处理: 配置变更采用异步通知机制
4. 缓存策略: 频繁访问的配置项进行内存缓存

存储性能

• NVS分区: 配置数据存储在独立NVS分区
• 写入合并: 多次配置更新合并为单次写入
• 磨损均衡: 通过配置版本控制避免频繁擦写
• 快速启动: 启动时快速加载关键配置

故障排除指南

常见配置问题

NVS存储问题

• 症状: 配置无法保存或丢失
• 原因: NVS分区损坏或空间不足
• 解决方案: 调试模式下重置NVS分区

网络连接问题

• 症状: WiFi连接失败或不稳定
• 原因: 配置参数不正确或网络环境异常
• 解决方案: 检查WiFi配置和网络信号强度

MQTT连接问题

• 症状: 无法连接到MQTT Broker
• 原因: Broker地址错误或认证失败
• 解决方案: 验证Broker配置和凭据

章节来源 - config_manager.c

调试工具

1. 配置状态查询: 获取当前配置和运行状态
2. 日志输出: 详细的配置操作日志
3. 错误码映射: 清晰的错误信息说明
4. 配置重置: 快速恢复到默认配置

结论

ESP32S3 BLE网关的配置数据模型采用模块化、分层的设计理念，提供了完整的配置管理能力。系统支持热重载、版本控制、持久化存储和多种网络模式，能够满足工业级应用的需求。通过严格的参数验证和错误处理机制，确保了配置的安全性和可靠性。

附录

配置验证规则总结

配置类别	验证规则	错误处理
网络配置	IP格式验证、端口范围检查	返回具体错误码
WiFi配置	SSID长度、密码格式、IP配置	参数修正或拒绝
MQTT配置	URI格式、认证信息、主题规范	配置回退或提示
BLE配置	数值范围、设备数量限制	使用默认值

版本兼容性矩阵

版本	新增功能	兼容性	迁移要求
v1.0	初始版本	完全兼容	无
v1.1	添加网络模式	向后兼容	自动迁移
v1.2	增强安全选项	向后兼容	配置更新