状态数据模型¶
本文档引用的文件 - main.c - config.h - led_indicator.h - led_indicator.c - config_manager.h - config_manager.c - network_manager.h - network_manager.c - wifi_manager.h - wifi_manager.c - eth_manager.h - eth_manager.c - wifi_provision.h - ble_gateway.h
目录¶
简介¶
本文件系统性阐述ESP32S3 BLE网关的状态数据模型，覆盖系统状态枚举、组件状态管理与状态转换规则；解释LED状态编码、网络连接状态与BLE扫描状态的表示方法；描述状态数据结构、更新机制与同步策略；并提供状态监控接口、事件通知与错误状态处理方案。同时给出状态持久化与恢复机制、诊断功能以及状态数据的序列化格式、传输协议与性能优化建议。
项目结构¶
系统采用分层模块化设计，主要由以下层次构成： - 应用入口与控制流：main.c负责启动流程、模式选择与主循环监控 - 硬件抽象与指示：LED指示器模块通过GPIO驱动三色LED - 配置管理层：负责全局配置的加载、保存与版本兼容 - 网络管理层：统一管理以太网与WiFi的连接与切换 - 子系统模块：WiFi管理、以太网管理、BLE网关等 - 事件与回调：各模块通过回调接口进行状态变更通知
graph TB
MAIN["应用入口<br/>main.c"] --> CFGM["配置管理<br/>config_manager.c/.h"]
MAIN --> LED["LED指示器<br/>led_indicator.c/.h"]
MAIN --> NETM["网络管理<br/>network_manager.c/.h"]
NETM --> WIFI["WiFi管理<br/>wifi_manager.c/.h"]
NETM --> ETH["以太网管理<br/>eth_manager.c/.h"]
MAIN --> BLE["BLE网关接口<br/>ble_gateway.h"]
MAIN --> PROV["WiFi配置门户<br/>wifi_provision.h"]图表来源 - main.c - config_manager.c - led_indicator.c - network_manager.c - wifi_manager.c - eth_manager.c - ble_gateway.h - wifi_provision.h
核心组件¶
本节概述状态相关的核心类型与职责： - 系统状态枚举：定义LED状态、网络状态、WiFi状态、以太网状态、配置版本、网络模式等 - 状态数据结构：封装当前状态信息（如网络状态、WiFi状态、BLE设备列表） - 更新机制：通过事件回调与定时器周期检查实现状态同步 - 同步策略：网络管理器聚合底层子系统状态，统一对外暴露
章节来源 - led_indicator.h - network_manager.h - wifi_manager.h - eth_manager.h - config_manager.h - config.h
架构总览¶
系统状态流从硬件与子系统出发，经由管理器汇总，最终由LED指示器与上层服务消费。主流程根据配置与外部条件选择启动模式，并在运行时持续监控与切换。
sequenceDiagram
participant APP as "应用入口(main)"
participant CFG as "配置管理"
participant NET as "网络管理"
participant ETH as "以太网"
participant WIFI as "WiFi"
participant LED as "LED指示器"
APP->>CFG : 初始化并加载配置
APP->>NET : 初始化网络管理(模式)
NET->>ETH : 初始化/启动
NET->>WIFI : 初始化/连接(按模式)
NET->>NET : 注册ETH/WiFi回调
NET->>APP : 状态变化回调
APP->>LED : 设置LED状态(系统/网络/BLE)
APP->>APP : 主循环打印状态摘要图表来源 - main.c - network_manager.c - led_indicator.c
详细组件分析¶
LED状态编码与指示¶
LED模块提供三种物理指示灯与五种状态码，用于直观反映系统、网络与BLE状态： - LED索引：网络(黄)、BLE(绿)、系统(蓝) - 状态码：关闭、常亮、慢闪(1Hz)、快闪(4Hz)、单次闪烁 - 实现要点：使用定时器周期翻转硬件电平，即时更新常量状态，支持单次闪烁触发
classDiagram
class LedIndicator {
+初始化()
+反初始化()
+设置(索引, 状态)
+获取(索引) 状态
+全部设置(状态)
+单次闪烁(索引, 毫秒)
}
class LedState {
<<枚举>>
OFF
ON
BLINK_SLOW
BLINK_FAST
BLINK_ONCE
}
LedIndicator --> LedState : "使用"图表来源 - led_indicator.h - led_indicator.c
章节来源 - led_indicator.h - led_indicator.c - led_indicator.c - led_indicator.c
网络连接状态与切换逻辑¶
网络管理器统一管理以太网与WiFi的连接状态与模式切换，支持四种网络模式： - 仅以太网、仅WiFi、以太网优先、WiFi优先 - 状态机：断开、以太网已连、WiFi已连、AP模式 - 切换策略：基于定时器周期检查与事件回调，实现自动倒换与回切
stateDiagram-v2
[*] --> 断开
断开 --> 以太网已连 : "ETH连接成功"
断开 --> WiFi已连 : "WIFI连接成功"
断开 --> AP模式 : "启动AP"
以太网已连 --> WiFi已连 : "ETH断开(优先级切换)"
WiFi已连 --> 以太网已连 : "ETH恢复且优先"
WiFi已连 --> 断开 : "WIFI断开且无ETH"
以太网已连 --> 断开 : "ETH断开且无WIFI"图表来源 - network_manager.h - network_manager.c - network_manager.c
章节来源 - network_manager.h - network_manager.c - network_manager.c - network_manager.c - network_manager.c
WiFi状态与扫描状态¶
WiFi管理器维护STA与AP两种工作形态，提供连接状态、RSSI、信道、IP等信息，并支持主动扫描： - 状态枚举：断开、连接中、已连、AP模式、错误 - 状态结构：包含SSID、密码、RSSI、信道、MAC、IP、掩码、网关 - 扫描结果：返回可用AP列表（SSID、RSSI、信道、认证方式）
flowchart TD
Start(["开始扫描"]) --> Config["配置扫描参数"]
Config --> StartScan["启动扫描"]
StartScan --> ScanOK{"扫描成功?"}
ScanOK --> |否| ReturnErr["返回错误"]
ScanOK --> |是| GetCount["获取AP数量"]
GetCount --> Alloc["分配记录缓冲"]
Alloc --> GetRecords["读取AP记录"]
GetRecords --> CopyOut["拷贝到输出数组"]
CopyOut --> Free["释放缓冲"]
Free --> Done(["完成"])
ReturnErr --> Done图表来源 - wifi_manager.h - wifi_manager.c
章节来源 - wifi_manager.h - wifi_manager.c - wifi_manager.c - wifi_manager.c - wifi_manager.c
以太网状态¶
以太网管理器提供链路状态、速度、双工、IP等信息： - 状态枚举：断开、连接中、已连、错误 - 状态结构：包含链路状态、速率、双工、MAC、IP、掩码、网关
章节来源 - eth_manager.h - eth_manager.c - eth_manager.c
BLE扫描状态与设备管理¶
BLE网关接口定义了设备发现、连接、断开与设备列表查询能力： - 设备结构：包含MAC、地址类型、名称、RSSI、广告数据、最后出现时间、连接状态与句柄 - 接口：初始化、启动/停止扫描、连接/断开、获取设备列表与数量、注册回调
章节来源 - ble_gateway.h - ble_gateway.h
状态数据结构与更新机制¶
- 配置结构：包含系统标识、网络配置、BLE扫描参数、MQTT配置、WebUI开关与端口、配置版本
- 状态聚合：网络管理器将ETH与WiFi状态合并为统一网络状态
- 更新策略：事件回调驱动即时更新，定时器周期检查保证一致性
章节来源 - config_manager.h - network_manager.c - network_manager.c
同步策略与事件通知¶
- 回调注册：各子系统通过回调函数上报状态变化
- 管理器聚合：网络管理器统一处理并转发状态
- LED联动：应用根据状态设置LED指示灯
章节来源 - network_manager.c - wifi_manager.c - eth_manager.c - main.c
依赖关系分析¶
组件间的依赖关系如下： - 应用入口依赖配置管理、LED指示器、网络管理、BLE网关、WiFi配置门户 - 网络管理器依赖WiFi与以太网管理器 - LED指示器独立，但被应用入口与按钮任务调用
graph LR
MAIN["main.c"] --> CFGM["config_manager.c/.h"]
MAIN --> LED["led_indicator.c/.h"]
MAIN --> NETM["network_manager.c/.h"]
NETM --> WIFI["wifi_manager.c/.h"]
NETM --> ETH["eth_manager.c/.h"]
MAIN --> BLE["ble_gateway.h"]
MAIN --> PROV["wifi_provision.h"]图表来源 - main.c - network_manager.c - wifi_manager.c - eth_manager.c
章节来源 - main.c - network_manager.c
性能考量¶
- 定时器周期：LED闪烁定时器采用固定周期，避免频繁上下文切换
- 事件驱动：WiFi与以太网事件回调减少轮询开销
- 周期检查：网络管理器定时器每5秒检查一次，平衡实时性与功耗
- 内存管理：扫描结果动态分配，及时释放，避免内存碎片
- NVS访问：配置保存采用批量写入与提交，降低NVS磨损
章节来源 - led_indicator.c - network_manager.c - wifi_manager.c - config_manager.c
故障排查指南¶
- LED指示异常
- 检查LED初始化与GPIO配置
- 确认定时器创建与启动
- 使用单次闪烁验证硬件路径
- 网络连接失败
- 查看网络管理器状态与模式
- 检查ETH/WiFi事件回调是否正确注册
- 观察定时器倒换逻辑是否触发
- WiFi扫描无结果
- 确认扫描参数与启动状态
- 检查AP记录获取与缓冲区大小
- 配置加载失败
- 检查NVS命名空间与键值
- 关注版本不匹配导致的重置
- 蓝牙设备列表为空
- 确认BLE网关初始化与扫描启动
- 检查设备超时与清理逻辑
章节来源 - led_indicator.c - led_indicator.c - network_manager.c - wifi_manager.c - config_manager.c - ble_gateway.h
结论¶
本状态数据模型以清晰的枚举与结构体定义了系统、网络、WiFi、以太网与BLE的关键状态；通过事件回调与定时器实现高效的状态同步；LED指示器提供直观的可视化反馈。配置管理器确保状态的持久化与版本兼容。整体设计具备良好的可扩展性与可维护性，适合在资源受限的嵌入式环境中稳定运行。
附录¶
状态数据结构与字段说明¶
- 网络状态结构：包含当前状态、模式、以太网与WiFi可用性、IP地址、网关、活动接口
- WiFi状态结构：包含当前状态、SSID、RSSI、信道、MAC、IP、掩码、网关
- 以太网状态结构：包含当前状态、链路状态、速率、双工、MAC、IP、掩码、网关
- 配置结构：包含系统标识、网络配置、BLE扫描参数、MQTT配置、WebUI开关与端口、配置版本
章节来源 - network_manager.h - wifi_manager.h - eth_manager.h - config_manager.h
状态转换规则与约束¶
- 网络模式约束：不同模式下ETH与WIFI的优先级与备份策略不同
- 事件驱动约束：状态变更必须通过回调或定时器更新，避免竞态
- LED映射约束：LED状态与系统阶段强关联，需在合适时机设置
章节来源 - network_manager.c - main.c
状态持久化与恢复机制¶
- NVS存储：配置以二进制Blob形式保存，包含版本号
- 加载策略：若未找到或版本不匹配则重置为默认配置并保存
- 恢复流程：启动时优先尝试加载，失败则生成默认配置
章节来源 - config_manager.c - config_manager.c - config_manager.c
诊断功能与监控接口¶
- 日志输出：主循环定期打印堆内存、网络连接状态与BLE设备数量
- 事件日志：各模块在关键状态变更时输出调试信息
- LED诊断：通过不同闪烁模式快速识别系统阶段与异常
章节来源 - main.c - network_manager.c - wifi_manager.c - led_indicator.c
序列化格式、传输协议与性能优化¶
- 序列化格式：配置采用二进制Blob直接存储，避免解析开销
- 传输协议：状态通过回调与共享结构体传递，零拷贝共享
- 性能优化：事件驱动减少轮询、定时器统一管理、扫描结果缓存、NVS批量写入
章节来源 - config_manager.c - network_manager.c - wifi_manager.c