项目概述

本文档引用的文件 - main.c - gateway_config.h - ble_scanner.h - wifi_manager.h - mqtt_client_wrapper.h - webui_server.h - hci_transport.h - eth_manager.h - ws2812_led.h - CMakeLists.txt - platformio.ini - index.html - ble_scanner.c - webui_server.c - README.md

目录

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

简介

本项目是一个基于ESP32-S3与NRF52833的BLE网关系统，旨在实现BLE设备的本地扫描、数据转发与远程管理。系统通过ESP32-S3作为主控制器，使用NRF52833作为外部BLE控制器（Zephyr HCI），通过UART进行通信；同时集成WiFi、以太网（CH390H）、MQTT、WebUI等模块，形成完整的边缘网关能力。其核心目标是： - 实现BLE设备的持续扫描与广告数据解析 - 将设备信息通过MQTT转发至远程平台（兼容OpenMQTTGateway） - 提供WebUI进行配置、监控与设备管理 - 支持LED状态指示与系统健康监测

项目结构

项目采用ESP-IDF工程结构，顶层通过CMakeLists组织组件目录，PlatformIO负责编译配置与烧录参数。主要目录与文件职责如下： - old_version/main：主程序入口与示例代码 - old_version/include：各组件接口头文件 - old_version/components：可复用组件实现（BLE扫描器、WebUI服务器、CH390以太网驱动等） - old_version/data：WebUI静态资源（HTML/CSS/JS） - old_version/docs：相关文档与连线说明 - 平台配置：CMakeLists.txt、platformio.ini

graph TB
A["顶层工程<br/>CMakeLists.txt"] --> B["组件目录<br/>EXTRA_COMPONENT_DIRS"]
A --> C["主程序<br/>main.c"]
A --> D["配置文件<br/>platformio.ini"]
C --> E["组件接口<br/>include/*.h"]
C --> F["组件实现<br/>components/*/*.c"]
F --> G["BLE扫描器<br/>ble_scanner.c"]
F --> H["WebUI服务器<br/>webui_server.c"]
F --> I["CH390以太网驱动<br/>README.md"]
C --> J["WebUI资源<br/>data/*.html, *.css"]

图表来源 - CMakeLists.txt - platformio.ini - main.c

章节来源 - CMakeLists.txt - platformio.ini

核心组件

• 系统初始化与主流程：负责NVS初始化、事件循环、系统信息打印、组件启动顺序与LED状态任务
• 配置管理：统一管理设备名、WiFi、MQTT、BLE扫描与过滤策略等配置，支持持久化存储与读取
• BLE扫描器：通过NRF52833控制器执行扫描，解析广告数据，维护设备列表与连接状态
• WiFi管理：STA/AP模式切换、网络扫描、连接状态回调
• MQTT客户端：连接远程Broker，发布BLE设备数据与网关状态，支持订阅与消息回调
• WebUI服务器：嵌入式HTTP服务，提供状态查询、设备列表、BLE控制、配置修改等REST接口
• HCI传输层：UART到NRF52833的H4协议封装，命令与事件处理
• 以太网管理（CH390H）：SPI接口的工业级以太网控制器，提供稳定网络连接
• LED指示：WS2812三色LED指示WiFi/MQTT/BLE状态

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

架构总览

系统采用“主控+外设”的双芯片架构：ESP32-S3负责系统控制、网络与业务逻辑，NRF52833负责BLE协议栈与扫描。数据流从BLE扫描器经MQTT转发到远程平台，WebUI提供可视化与配置入口。

graph TB
subgraph "硬件层"
MCU["ESP32-S3<br/>主控制器"]
NRF["NRF52833<br/>BLE控制器"]
ETH["CH390H<br/>以太网PHY/MAC"]
LED["WS2812 LED"]
end
subgraph "软件层"
SYS["系统初始化<br/>main.c"]
CFG["配置管理<br/>gateway_config.h"]
HCI["HCI传输<br/>hci_transport.h"]
BLE["BLE扫描器<br/>ble_scanner.h/.c"]
WIFI["WiFi管理<br/>wifi_manager.h"]
MQTT["MQTT客户端<br/>mqtt_client_wrapper.h"]
WEB["WebUI服务器<br/>webui_server.h/.c"]
end
MCU --> SYS
SYS --> CFG
SYS --> HCI
SYS --> WIFI
SYS --> MQTT
SYS --> WEB
SYS --> LED
HCI < --> NRF
BLE --> HCI
WIFI --> MCU
MQTT --> MCU
WEB --> MCU
ETH --> MCU

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

详细组件分析

BLE扫描器组件

BLE扫描器负责与NRF52833交互，解析广告数据，维护设备列表与连接状态。其核心流程包括： - 初始化与参数设置（扫描间隔、窗口、过滤策略） - 广告数据解析（名称、制造商数据等） - 设备去重与列表更新 - 连接/断开控制与状态回调

sequenceDiagram
participant APP as "主程序<br/>main.c"
participant BLE as "BLE扫描器<br/>ble_scanner.c"
participant HCI as "HCI传输<br/>hci_transport.h"
participant NRF as "NRF52833"
APP->>BLE : 初始化与注册回调
APP->>BLE : 设置扫描参数/过滤器
APP->>BLE : 启动扫描
BLE->>HCI : 发送LE Set Scan Enable命令
HCI->>NRF : 通过UART发送H4包
NRF-->>HCI : 返回LE Advertising Report事件
HCI-->>BLE : 解析事件并回调设备
BLE->>APP : 触发设备发现回调
APP->>MQTT : 发布BLE设备数据

图表来源 - main.c - ble_scanner.c - hci_transport.h

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

WebUI服务器组件

WebUI服务器提供嵌入式HTTP服务，提供以下接口： - 状态查询：系统版本、运行时间、内存、WiFi/MQTT/BLE状态 - 设备列表：扫描结果、过滤与详情展示 - BLE控制：启动/停止扫描、连接/断开设备、过滤器设置 - 配置管理：WiFi/MQTT参数保存、重启设备

sequenceDiagram
participant Browser as "浏览器"
participant Web as "WebUI服务器<br/>webui_server.c"
participant BLE as "BLE扫描器"
participant CFG as "配置管理"
Browser->>Web : GET /api/status
Web->>BLE : 查询扫描状态/设备数
Web-->>Browser : 返回JSON状态
Browser->>Web : POST /api/scan {enable : true}
Web->>BLE : 启动扫描
Web-->>Browser : 返回扫描状态
Browser->>Web : POST /api/config {wifi/mqtt}
Web->>CFG : 写入配置并保存
Web-->>Browser : 返回成功

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

章节来源 - webui_server.h - index.html

配置管理组件

配置管理负责设备名、WiFi、MQTT、BLE扫描与过滤策略的持久化存储与加载，确保系统重启后仍能保持用户设置。

flowchart TD
Start(["系统启动"]) --> LoadCfg["加载配置<br/>gateway_config_load"]
LoadCfg --> HasWifi{"是否配置WiFi?"}
HasWifi --> |是| ApplyWifi["应用WiFi配置<br/>wifi_manager_set_config"]
HasWifi --> |否| StartAP["启动AP模式"]
ApplyWifi --> StartWifi["启动WiFi连接"]
StartAP --> StartWifi
StartWifi --> HasMQTT{"是否配置MQTT?"}
HasMQTT --> |是| ApplyMQTT["设置MQTT配置<br/>mqtt_client_set_config"]
HasMQTT --> |否| SkipMQTT["跳过MQTT"]
ApplyMQTT --> StartMQTT["启动MQTT客户端"]
SkipMQTT --> InitBLE["初始化BLE扫描器"]
StartMQTT --> InitBLE

图表来源 - main.c - gateway_config.h

章节来源 - gateway_config.h

以太网管理组件（CH390H）

CH390H提供工业级以太网能力，支持10/100M自适应与自动MDI-X，适合有线网络场景。组件通过SPI接口与ESP32-S3通信，提供稳定的网络连接能力。

章节来源 - eth_manager.h - README.md

LED状态指示组件

WS2812三色LED分别指示WiFi、MQTT与BLE状态，便于现场调试与运维监控。

章节来源 - main.c - ws2812_led.h

依赖关系分析

系统组件间存在清晰的依赖关系：主程序依赖所有子系统；BLE扫描器依赖HCI传输层；WebUI依赖BLE、WiFi、MQTT与配置管理；MQTT依赖网络层；LED独立但受主程序调度。

graph LR
MAIN["main.c"] --> CFG["gateway_config.h"]
MAIN --> HCI["hci_transport.h"]
MAIN --> WIFI["wifi_manager.h"]
MAIN --> MQTT["mqtt_client_wrapper.h"]
MAIN --> WEB["webui_server.h"]
MAIN --> LED["ws2812_led.h"]
BLE["ble_scanner.h/.c"] --> HCI
WEB --> BLE
WEB --> CFG
WEB --> WIFI
WEB --> MQTT
MQTT --> WIFI

图表来源 - main.c - ble_scanner.h - webui_server.h

章节来源 - main.c

性能考虑

• BLE扫描参数：合理设置扫描间隔与窗口，平衡功耗与实时性
• 设备列表容量：限制最大设备数量，避免内存压力
• MQTT发布频率：根据网络状况调整发布策略，减少带宽占用
• WebUI轮询：自动刷新需按需开启，降低服务器负载
• LED刷新：固定周期更新，避免频繁写入影响系统性能

故障排除指南

• BLE无法扫描：检查NRF52833连接与复位引脚配置，确认HCI初始化成功
• WiFi连接失败：确认SSID/密码正确，必要时进入AP模式进行配置
• MQTT连接异常：检查Broker地址、认证信息与网络连通性
• WebUI无法访问：确认SPIFFS挂载与静态资源路径，检查端口占用
• LED不亮：检查WS2812引脚配置与电源供电

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

结论

本项目通过ESP32-S3与NRF52833的协同，构建了功能完备的BLE网关系统。其模块化设计、清晰的接口定义与丰富的管理能力，使其适用于多种边缘计算与IoT场景。建议在实际部署中关注硬件连线、网络稳定性与配置持久化，以获得最佳体验。