开发指南¶

本文档引用的文件 - CMakeLists.txt - platformio.ini - idf_component.yml - partitions.csv - main.c - config.h - gateway_config.h - ble_scanner.c - wifi_manager.c - eth_manager.c - mqtt_client_wrapper.c - webui_server.c - ws2812_led.c - hci_transport.c

目录¶

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

简介¶

本指南面向ESP32-S3 BLE网关项目的开发者，提供从开发环境搭建到代码贡献、组件扩展与第三方集成的完整流程。项目采用ESP-IDF框架，结合PlatformIO进行构建管理，支持通过NRF52833外部BLE控制器实现低功耗蓝牙扫描，并通过MQTT向OpenMQTTGateway兼容的消息格式转发数据；同时提供基于SPIFFS的WebUI配置界面与LED状态指示。

项目结构¶

项目采用“顶层工程 + 组件化模块”的组织方式： - 顶层工程：CMakeLists.txt定义组件目录，platformio.ini定义构建环境与编译参数，idf_component.yml声明依赖组件（如CH390以组件形式引入），partitions.csv定义分区表。 - 组件模块：components目录下按功能划分，包括BLE扫描、WiFi管理、以太网（CH390）、MQTT封装、WebUI服务器、LED驱动、HCI传输等。 - 头文件：include目录集中定义全局配置与公共接口。 - 应用入口：main目录包含应用主程序与示例文件。

graph TB
subgraph "顶层工程"
CMake["CMakeLists.txt"]
PIO["platformio.ini"]
IDFCFG["idf_component.yml"]
PART["partitions.csv"]
end
subgraph "组件模块"
HCI["hci_transport.c"]
BLE["ble_scanner.c"]
WIFI["wifi_manager.c"]
ETH["eth_manager.c"]
MQTT["mqtt_client_wrapper.c"]
WEB["webui_server.c"]
LED["ws2812_led.c"]
end
subgraph "头文件"
CFG["config.h"]
GCFG["gateway_config.h"]
end
APP["main.c"]
CMake --> APP
PIO --> APP
IDFCFG --> APP
PART --> APP
APP --> HCI
APP --> WIFI
APP --> ETH
APP --> MQTT
APP --> WEB
APP --> LED
APP --> BLE
APP --> CFG
APP --> GCFG

图表来源 - CMakeLists.txt - platformio.ini - idf_component.yml - partitions.csv - main.c - config.h - gateway_config.h

章节来源 - CMakeLists.txt - platformio.ini - idf_component.yml - partitions.csv

核心组件¶

应用入口与系统初始化：负责NVSD初始化、事件循环、组件初始化顺序与任务调度。
配置管理：统一管理设备名、WiFi、MQTT、BLE扫描与过滤参数，持久化至NVS。
BLE扫描器：通过外部NRF52833控制器执行扫描，解析广告数据，维护设备列表与连接状态。
WiFi管理器：STA/AP模式切换、连接重试、事件回调与状态查询。
以太网管理器（CH390）：SPI主机配置、MAC/PHY初始化、中断与事件处理。
MQTT客户端封装：事件回调、订阅命令主题、发布设备与状态信息。
WebUI服务器：基于HTTPD的嵌入式Web服务，提供状态查询、配置修改、BLE控制与文件服务。
LED驱动：基于RMT的WS2812驱动，用于系统状态指示。
HCI传输层：UART H4协议、硬件流控、命令/事件同步与控制器复位。

章节来源 - main.c - gateway_config.h - ble_scanner.c - wifi_manager.c - eth_manager.c - mqtt_client_wrapper.c - webui_server.c - ws2812_led.c - hci_transport.c

架构总览¶

系统采用“主任务协调 + 多组件协作”的架构： - 主任务负责系统初始化、组件启动顺序与周期性监控。 - 各组件通过事件回调与共享状态交互，确保异步事件（BLE事件、网络事件、MQTT事件）被正确处理。 - WebUI作为用户交互入口，提供REST风格API与静态资源服务。

graph TB
Main["主任务(app_main)"]
NVS["NVS闪存"]
EventLoop["事件循环"]
Config["配置管理"]
HCI["HCI传输层"]
BLE["BLE扫描器"]
WiFi["WiFi管理器"]
Eth["以太网(CH390)"]
MQTT["MQTT客户端封装"]
Web["WebUI服务器"]
LED["WS2812 LED"]
SPIFFS["SPIFFS文件系统"]
Main --> NVS
Main --> EventLoop
Main --> Config
Main --> HCI
Main --> WiFi
Main --> Eth
Main --> MQTT
Main --> Web
Main --> LED
BLE --> HCI
Web --> SPIFFS
Web --> Config
Web --> BLE
Web --> WiFi
Web --> MQTT
LED --> Main

图表来源 - main.c - hci_transport.c - ble_scanner.c - wifi_manager.c - eth_manager.c - mqtt_client_wrapper.c - webui_server.c - ws2812_led.c

详细组件分析¶

应用入口与系统初始化¶

初始化NVSD与事件循环，打印系统信息与硬件配置。
加载并应用配置（WiFi/MQTT/BLE），启动各子系统。
初始化并启动BLE扫描器（若HCI可用），注册发现回调。
启动WebUI服务器与LED状态任务，进入主循环打印内存信息。

sequenceDiagram
participant Main as "主任务"
participant NVS as "NVS"
participant Event as "事件循环"
participant Cfg as "配置管理"
participant HCI as "HCI传输"
participant Eth as "以太网"
participant WiFi as "WiFi"
participant MQTT as "MQTT"
participant Web as "WebUI"
participant BLE as "BLE扫描器"
Main->>NVS : 初始化NVSD
Main->>Event : 创建默认事件循环
Main->>Cfg : 初始化并加载配置
Main->>HCI : 初始化传输层
alt HCI成功
Main->>BLE : 初始化并启动扫描
BLE-->>Main : 注册设备发现回调
else HCI失败
Main-->>Main : 警告并禁用BLE
end
Main->>Eth : 初始化并启动
Main->>WiFi : 初始化并启动
Main->>MQTT : 初始化并按配置启动
Main->>Web : 初始化并启动
Main->>Main : 启动LED状态任务

图表来源 - main.c

章节来源 - main.c

配置管理¶

提供配置的初始化、加载、保存、重置与校验接口。
支持读写设备名、WiFi、MQTT、BLE扫描参数与过滤条件。
通过NVS命名空间存储，保证断电不丢失。

flowchart TD
Start(["调用gateway_config_init"]) --> Load["从NVS加载配置"]
Load --> Valid{"配置有效?"}
Valid --> |是| Ready["返回成功"]
Valid --> |否| Reset["重置为默认值"]
Reset --> Save["保存默认配置"]
Save --> Ready

图表来源 - gateway_config.h

章节来源 - gateway_config.h

BLE扫描器¶

初始化时注册事件回调，发送HCI命令启用事件掩码与随机地址。
扫描参数可配置，支持去重与过滤（RSSI、名称、MAC）。
解析LE广告报告事件，提取设备名称与RSSI，维护设备列表。
支持连接/断开指定设备，跟踪连接状态。

flowchart TD
Init(["初始化"]) --> RegCB["注册HCI事件回调"]
RegCB --> CmdMask["设置事件掩码"]
CmdMask --> CmdLEMask["设置LE事件掩码"]
CmdLEMask --> RandAddr["设置随机地址"]
RandAddr --> StartScan["开始扫描"]
StartScan --> OnEvt{"收到事件?"}
OnEvt --> |是| Parse["解析事件/广告"]
Parse --> Filter{"通过过滤器?"}
Filter --> |是| Notify["触发设备发现回调"]
Filter --> |否| Drop["丢弃"]
OnEvt --> |否| Loop["等待事件"]
Notify --> Loop
Drop --> Loop
Loop --> StartScan

图表来源 - ble_scanner.c

章节来源 - ble_scanner.c

WiFi管理器¶

初始化TCP/IP栈、STA/AP网络接口与默认事件处理器。
支持STA连接（含重试）、AP模式、热点扫描与状态查询。
事件驱动的状态机，通过事件组通知连接结果。

stateDiagram-v2
[*] --> 未初始化
未初始化 --> 已初始化 : 初始化
已初始化 --> 连接中 : 连接到配置网络
已初始化 --> AP模式 : 启动AP
连接中 --> 已连接 : 获取IP
连接中 --> 失败 : 达到最大重试次数
已连接 --> 断开 : 主动断开或失去IP
AP模式 --> 断开 : 停止AP

图表来源 - wifi_manager.c

章节来源 - wifi_manager.c

以太网管理器（CH390）¶

SPI主机初始化、CH390 MAC/PHY创建与驱动安装。
GPIO中断服务、硬件复位、事件与IP事件处理。
提供连接状态查询与速率/双工检测。

sequenceDiagram
participant App as "应用"
participant ETH as "以太网管理器"
participant SPI as "SPI主机"
participant MAC as "CH390 MAC"
participant PHY as "CH390 PHY"
participant NET as "TCP/IP栈"
App->>ETH : 初始化
ETH->>SPI : 配置SPI引脚与时钟
ETH->>MAC : 创建MAC实例
ETH->>PHY : 创建PHY实例
ETH->>ETH : 安装驱动并附加到TCP/IP
ETH->>NET : 注册事件处理器
App->>ETH : 启动
ETH-->>App : 返回状态

图表来源 - eth_manager.c

章节来源 - eth_manager.c

MQTT客户端封装¶

事件驱动：连接、断开、订阅、发布、错误等事件回调。
发布BLE设备数据遵循OpenMQTTGateway格式，发布状态信息。
支持动态配置更新与状态查询。

sequenceDiagram
participant App as "应用"
participant MQTT as "MQTT封装"
participant Broker as "MQTT代理"
App->>MQTT : 设置配置并启动
MQTT->>Broker : 连接(用户名/密码/ClientID)
Broker-->>MQTT : 连接成功事件
MQTT->>Broker : 订阅命令主题
App->>MQTT : 发布设备数据(JSON)
App->>MQTT : 发布状态信息

图表来源 - mqtt_client_wrapper.c

章节来源 - mqtt_client_wrapper.c

WebUI服务器¶

基于HTTPD的嵌入式Web服务，提供静态页面与REST API。
支持设备列表查询、扫描启停、连接控制、过滤设置、配置读写、重启等。
文件服务从SPIFFS读取静态资源。

flowchart TD
Start(["启动HTTPD"]) --> Mount["挂载SPIFFS"]
Mount --> RegHandlers["注册URI处理器"]
RegHandlers --> ServeFiles["静态文件服务"]
RegHandlers --> APIStatus["/api/status"]
RegHandlers --> APIDevices["/api/devices"]
RegHandlers --> APIConfig["/api/config"]
RegHandlers --> APIScan["/api/scan"]
RegHandlers --> APIBLE["/api/ble/*"]
APIBLE --> APIClear["清除设备列表"]
APIBLE --> APIScanCtrl["启停扫描"]
APIBLE --> APIConn["连接/断开设备"]
APIBLE --> APIFilter["设置过滤器"]
APIConfig --> GETCfg["GET配置"]
APIConfig --> POSTCfg["POST更新配置"]

图表来源 - webui_server.c

章节来源 - webui_server.c

LED驱动（WS2812）¶

基于RMT通道与自定义编码器，实现WS2812像素缓冲与刷新。
支持单灯/全灯设置、亮度调节与状态指示。

章节来源 - ws2812_led.c

HCI传输层¶

UART H4协议实现，硬件流控（RTS/CTS），命令/事件同步。
提供命令发送、等待命令完成、事件回调注册与控制器复位。

章节来源 - hci_transport.c

依赖关系分析¶

构建依赖：CMakeLists通过EXTRA_COMPONENT_DIRS引入components；platformio.ini设置框架版本、板型、分区表与构建标志；idf_component.yml声明CH390组件依赖。
运行时依赖：各组件通过config.h中的宏配置引脚、波特率、缓冲区大小等；BLE扫描器依赖HCI传输层；WebUI依赖SPIFFS与各业务组件；MQTT封装依赖BLE扫描器以发布设备数据。

graph LR
CMake["CMakeLists.txt"] --> Components["components/*"]
PIO["platformio.ini"] --> Build["构建配置"]
IDFCFG["idf_component.yml"] --> Deps["组件依赖"]
PART["partitions.csv"] --> Flash["分区布局"]
Components --> BLE["ble_scanner"]
Components --> HCI["hci_transport"]
Components --> WIFI["wifi_manager"]
Components --> ETH["eth_manager"]
Components --> MQTT["mqtt_client_wrapper"]
Components --> WEB["webui_server"]
Components --> LED["ws2812_led"]
BLE --> HCI
WEB --> SPIFFS["SPIFFS"]
WEB --> BLE
WEB --> WIFI
WEB --> MQTT

图表来源 - CMakeLists.txt - platformio.ini - idf_component.yml - partitions.csv

章节来源 - CMakeLists.txt - platformio.ini - idf_component.yml - partitions.csv