配置管理API

本文档引用的文件 - rest_api.c - config_manager.c - config_manager.h - webui_server.c - main.c

目录

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

简介

配置管理API是ESP32S3 BLE网关系统中的核心功能模块，负责管理系统配置的获取、更新和持久化存储。该API提供了RESTful接口，允许用户通过HTTP协议访问和修改网关的各种配置参数，包括网络连接设置、MQTT通信配置和BLE扫描参数。

本API基于ESP-IDF框架构建，使用cJSON库进行JSON数据处理，并通过NVS（Non-Volatile Storage）进行配置的持久化存储。系统支持完整的配置生命周期管理，从初始化默认配置到运行时动态更新，再到重启后的配置恢复。

项目结构

配置管理API在项目中的位置和相关组件关系如下：

graph TB
subgraph "应用层"
Main[main.c]
WebUI[webui_server.c]
end
subgraph "API层"
REST[rest_api.c]
end
subgraph "配置管理层"
ConfigMgr[config_manager.c]
ConfigHdr[config_manager.h]
end
subgraph "存储层"
NVS[NVS Flash]
end
Main --> REST
WebUI --> REST
REST --> ConfigMgr
ConfigMgr --> NVS
ConfigHdr --> ConfigMgr

图表来源 - main.c - webui_server.c - rest_api.c

章节来源 - main.c - webui_server.c - rest_api.c

核心组件

配置管理API由以下核心组件构成：

REST API处理器

• 提供HTTP接口：GET /api/config 和 PUT /api/config
• 使用cJSON库进行JSON数据序列化和反序列化
• 集成到ESP-IDF HTTP服务器框架中

配置管理器

• 负责配置的加载、保存和更新
• 使用NVS进行非易失性存储
• 提供配置版本管理和默认值设置

配置数据模型

• 定义完整的配置结构，包括网络、MQTT、BLE等参数
• 支持运行时配置修改
• 提供类型安全的配置访问接口

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

架构概览

配置管理API采用分层架构设计，确保了良好的模块分离和可维护性：

sequenceDiagram
participant Client as 客户端
participant HTTP as HTTP服务器
participant REST as REST API
participant Config as 配置管理器
participant NVS as NVS存储
Note over Client,HTTP : GET /api/config 请求流程
Client->>HTTP : GET /api/config
HTTP->>REST : 调用api_get_config_handler
REST->>Config : config_manager_get()
Config->>Config : 获取当前配置
Config-->>REST : 返回配置指针
REST->>REST : 构建JSON响应
REST-->>Client : 返回配置JSON
Note over Client,NVS : PUT /api/config 请求流程
Client->>HTTP : PUT /api/config
HTTP->>REST : 调用api_put_config_handler
REST->>REST : 解析JSON请求体
REST->>Config : 更新配置
Config->>NVS : 保存到Flash
NVS-->>Config : 确认保存
Config-->>REST : 返回保存结果
REST-->>Client : 返回成功响应

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

详细组件分析

REST API接口定义

配置管理API提供两个主要接口：

GET /api/config - 获取配置

此接口返回当前系统的完整配置信息：

请求格式

GET /api/config
Host: 192.168.4.1
Content-Type: application/json

响应格式

{
  "gateway_id": "字符串",
  "gateway_name": "字符串",
  "network": {
    "mode": 数字,
    "wifi_ssid": "字符串",
    "eth_dhcp": 布尔值
  },
  "mqtt": {
    "enabled": 布尔值,
    "broker_uri": "字符串",
    "username": "字符串"
  },
  "ble": {
    "scan_enabled": 布尔值,
    "rssi_filter": 数字
  }
}

响应示例

{
  "gateway_id": "GW-ABC123",
  "gateway_name": "BLE Gateway",
  "network": {
    "mode": 1,
    "wifi_ssid": "MyWiFi",
    "eth_dhcp": true
  },
  "mqtt": {
    "enabled": false,
    "broker_uri": "",
    "username": ""
  },
  "ble": {
    "scan_enabled": true,
    "rssi_filter": -100
  }
}

PUT /api/config - 更新配置

此接口用于更新系统配置：

请求格式

PUT /api/config
Host: 192.168.4.1
Content-Type: application/json

{
  "gateway_id": "字符串",
  "gateway_name": "字符串",
  "network": {
    "mode": 数字,
    "wifi_ssid": "字符串",
    "wifi_password": "字符串",
    "eth_dhcp": 布尔值
  },
  "mqtt": {
    "enabled": 布尔值,
    "broker_uri": "字符串",
    "username": "字符串",
    "password": "字符串"
  },
  "ble": {
    "scan_enabled": 布尔值,
    "rssi_filter": 数字
  }
}

响应格式

{
  "status": "ok"
}

章节来源 - rest_api.c

配置数据结构

配置管理器定义了完整的配置数据结构：

classDiagram
class gateway_config_t {
+char gateway_id[32]
+char gateway_name[32]
+network_config_t network
+ble_scan_config_t ble_scan
+uint8_t max_ble_connections
+mqtt_config_t mqtt
+bool webui_enabled
+uint16_t webui_port
+uint32_t config_version
}
class network_config_t {
+network_mode_t mode
+char wifi_ssid[32]
+char wifi_password[64]
+bool eth_dhcp
+uint32_t eth_static_ip
+uint32_t eth_gateway
+uint32_t eth_netmask
}
class ble_scan_config_t {
+bool enabled
+uint16_t interval
+uint16_t window
+bool active_scan
+int8_t rssi_filter
+char name_filter[32]
+uint8_t 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_t keepalive
+uint8_t qos
}
gateway_config_t --> network_config_t
gateway_config_t --> ble_scan_config_t
gateway_config_t --> mqtt_config_t

图表来源 - config_manager.h

配置验证和保存机制

配置管理器实现了完整的配置验证和保存流程：

flowchart TD
Start([开始配置更新]) --> ParseJSON["解析JSON请求体"]
ParseJSON --> ValidateConfig["验证配置参数"]
ValidateConfig --> ConfigValid{"配置有效?"}
ConfigValid --> |否| ReturnError["返回错误响应"]
ConfigValid --> |是| UpdateConfig["更新内存配置"]
UpdateConfig --> SaveToNVS["保存到NVS"]
SaveToNVS --> CommitNVS["提交到Flash"]
CommitNVS --> SaveSuccess{"保存成功?"}
SaveSuccess --> |否| HandleSaveError["处理保存错误"]
SaveSuccess --> |是| ReturnSuccess["返回成功响应"]
HandleSaveError --> ReturnError
ReturnError --> End([结束])
ReturnSuccess --> End

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

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

依赖关系分析

配置管理API的依赖关系图展示了各组件之间的交互：

graph LR
subgraph "外部依赖"
cJSON[cJSON库]
NVS[NVS存储]
HTTPD[ESP-IDF HTTP服务器]
end
subgraph "内部组件"
REST[REST API模块]
CM[配置管理器]
CFG[配置头文件]
end
REST --> cJSON
REST --> HTTPD
REST --> CM
CM --> NVS
CM --> CFG
CFG --> CM

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

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

性能考虑

配置管理API在设计时考虑了以下性能因素：

内存管理

• 使用固定大小的缓冲区避免动态内存分配
• JSON解析使用流式处理减少内存占用
• 配置结构体紧凑布局优化内存使用

存储优化

• NVS存储采用二进制格式提高写入效率
• 配置版本控制避免不必要的重写
• 批量操作减少Flash擦写次数

并发处理

• 单线程设计简化并发控制
• 非阻塞I/O操作提高响应速度
• 适当的超时机制防止死锁

故障排除指南

常见问题及解决方案

配置无法保存 - 检查NVS分区是否正确挂载 - 验证Flash空间是否充足 - 确认权限设置正确

JSON解析失败 - 检查请求体格式是否符合要求 - 验证必需字段是否存在 - 确认数据类型匹配

配置加载失败 - 检查配置版本兼容性 - 验证NVS键值是否存在 - 确认数据完整性

章节来源 - config_manager.c

结论

配置管理API为ESP32S3 BLE网关提供了完整、可靠的配置管理解决方案。通过RESTful接口，用户可以轻松地获取和更新系统配置，同时系统确保了配置的安全存储和可靠恢复。

该API的设计充分考虑了嵌入式系统的特殊需求，在保证功能完整性的同时优化了资源使用和性能表现。完善的错误处理机制和配置验证确保了系统的稳定性和可靠性。

未来可以考虑添加以下增强功能： - 配置导入导出功能 - 配置模板和预设方案 - 实时配置变更通知机制 - 更细粒度的配置权限控制