跳转至

快速开始

本文引用的文件 - platformio.ini - CMakeLists.txt - sdkconfig.defaults - partitions.csv - main.c - config.h - ble_scanner.c - wifi_manager.c - mqtt_client_wrapper.c - CH390H_Wiring.md

目录

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

简介

本指南面向首次接触 ESP32-S3 BLE 网关项目的开发者，提供从环境准备、工具链安装、IDE 配置、编译与烧录到硬件连接与系统启动验证的完整流程。项目采用 ESP-IDF 与 PlatformIO 双模式支持，核心功能包括：通过外部 NRF52833 以 HCI UART 实现 BLE 扫描、WiFi 连接、MQTT 数据转发、WebUI 配置以及 CH390H 以太网接口（预留）。

项目结构

项目采用 ESP-IDF 的组件化组织方式，顶层使用 CMakeLists.txt 管理工程，PlatformIO 提供额外的构建与上传配置。关键目录与文件： - 顶层工程与配置：CMakeLists.txt、platformio.ini、sdkconfig.defaults、partitions.csv - 应用入口：main/main.c - 全局配置：include/config.h - 组件实现：components 下各子模块（如 ble_scanner、wifi_manager、mqtt_client_wrapper） - 文档与接线：docs/CH390H_Wiring.md

graph TB
A["顶层工程<br/>CMakeLists.txt"] --> B["组件目录<br/>EXTRA_COMPONENT_DIRS"]
A --> C["平台配置<br/>platformio.ini"]
A --> D["SDK配置默认值<br/>sdkconfig.defaults"]
A --> E["分区表<br/>partitions.csv"]
A --> F["应用入口<br/>main/main.c"]
F --> G["BLE扫描器<br/>components/ble_scanner/ble_scanner.c"]
F --> H["WiFi管理器<br/>components/wifi_manager/wifi_manager.c"]
F --> I["MQTT客户端封装<br/>components/mqtt_client_wrapper/mqtt_client_wrapper.c"]
F --> J["全局配置头<br/>include/config.h"]
F --> K["CH390H接线文档<br/>docs/CH390H_Wiring.md"]

图表来源 - CMakeLists.txt - platformio.ini - sdkconfig.defaults - partitions.csv - main.c - config.h - ble_scanner.c - wifi_manager.c - mqtt_client_wrapper.c - CH390H_Wiring.md

章节来源 - CMakeLists.txt - platformio.ini - sdkconfig.defaults - partitions.csv - main.c

核心组件

  • 应用入口与系统初始化：负责 NVS 初始化、事件循环、系统信息打印、组件初始化顺序与 LED 状态指示。
  • BLE 扫描器：通过 HCI UART 与外部 NRF52833 通信，解析广告数据，维护设备列表，支持连接与断开。
  • WiFi 管理器：支持 STA/AP 模式切换、连接重试、AP 客户端接入通知、IP 获取与状态查询。
  • MQTT 客户端封装：基于 esp-mqtt，发布 BLE 设备数据与状态消息，订阅命令主题。
  • 全局配置：集中定义 UART 引脚、BLE 参数、WiFi、MQTT、WebUI、LED、CH390H 等参数。

章节来源 - main.c - ble_scanner.c - wifi_manager.c - mqtt_client_wrapper.c - config.h

架构总览

系统启动流程概览如下：

sequenceDiagram
participant Boot as "上电/复位"
participant Main as "app_main()"
participant NVS as "NVS初始化"
participant Sys as "事件循环"
participant LED as "WS2812状态灯"
participant HCI as "HCI传输层"
participant ETH as "以太网(CH390H)"
participant WiFi as "WiFi管理器"
participant MQTT as "MQTT客户端"
participant WebUI as "WebUI服务器"
participant BLE as "BLE扫描器"
Boot->>Main : "调用 app_main()"
Main->>NVS : "nvs_flash_init()"
Main->>Sys : "esp_event_loop_create_default()"
Main->>LED : "初始化并设置启动状态"
Main->>HCI : "初始化(若NRF52833在线)"
Main->>ETH : "初始化并启动(若CH390H在线)"
Main->>WiFi : "初始化并加载配置"
WiFi-->>Main : "启动STA或AP"
Main->>MQTT : "初始化并按配置启动"
Main->>WebUI : "初始化WebUI"
Main->>BLE : "初始化并启动扫描(若HCI就绪)"
Main->>LED : "创建状态任务周期更新"
Main-->>Boot : "系统运行中，主循环打印堆内存"

图表来源 - main.c - ble_scanner.c - wifi_manager.c - mqtt_client_wrapper.c - CH390H_Wiring.md

详细组件分析

BLE 扫描器

  • 功能要点：初始化事件掩码、设置随机地址、启用 LE 广告报告；解析广告数据提取设备名；维护设备列表与超时清理；支持连接/断开流程。
  • 关键流程（启动扫描）：
flowchart TD
Start(["进入 ble_scanner_start"]) --> SetParam["发送 LE Set Scan Param 命令"]
SetParam --> WaitParam["等待 Command Complete"]
WaitParam --> EnableScan["发送 LE Set Scan Enable 启用扫描"]
EnableScan --> WaitEnable["等待 Command Complete"]
WaitEnable --> Running["标记为扫描中"]
Running --> End(["返回"])

图表来源 - ble_scanner.c

章节来源 - ble_scanner.c

WiFi 管理器

  • 功能要点：STA/AP 模式切换、连接重试、AP 客户端接入/断开事件、IP 获取、状态查询。
  • 关键流程（STA 连接）：
flowchart TD
Enter(["进入 wifi_manager_connect"]) --> SetCfg["配置WiFi参数"]
SetCfg --> StartSTA["启动STA并尝试连接"]
StartSTA --> WaitEvt["等待连接事件"]
WaitEvt --> Connected{"连接成功?"}
Connected --> |是| SaveCfg["保存配置并返回成功"]
Connected --> |否| Retry{"达到最大重试次数?"}
Retry --> |否| Reconnect["再次尝试连接"]
Retry --> |是| Fail["返回失败"]

图表来源 - wifi_manager.c

章节来源 - wifi_manager.c

MQTT 客户端封装

  • 功能要点：初始化/销毁、连接/断开、订阅/发布、状态回调、BLE 设备数据与状态消息发布。
  • 关键流程（发布 BLE 设备数据）：
sequenceDiagram
participant BLE as "BLE扫描器"
participant MQ as "MQTT封装"
participant Broker as "MQTT代理"
BLE->>MQ : "publish_ble_device(device)"
MQ->>MQ : "构造JSON负载"
MQ->>Broker : "publish(base_topic/BTtoMQTT/mac, payload)"
Broker-->>MQ : "确认"
MQ-->>BLE : "返回结果"

图表来源 - mqtt_client_wrapper.c

章节来源 - mqtt_client_wrapper.c

全局配置

  • 关键点：定义 HCI UART 引脚、波特率、NRF52833 复位引脚；BLE 扫描参数与设备列表上限；WiFi AP 默认参数；MQTT 主题与端口；WebUI 端口与任务栈；WS2812 LED 数量与引脚；CH390H SPI 引脚与时钟频率等。

章节来源 - config.h

依赖关系分析

  • 组件耦合：main.c 作为协调者，依次初始化各子系统；BLE 扫描器依赖 HCI 传输层；MQTT 封装依赖 BLE 扫描器与配置；WiFi 与 MQTT 分别独立但共享全局配置。
  • 外部依赖：ESP-IDF、esp-mqtt、cJSON、FreeRTOS、NVS、LWIP、HTTPD 等。
  • 编译配置：CMakeLists.txt 指定 EXTRA_COMPONENT_DIRS；platformio.ini 指定平台、板型、分区表、文件系统、构建标志与额外组件路径；sdkconfig.defaults 提供默认 SDK 配置；partitions.csv 定义分区布局。
graph LR
Main["main/main.c"] --> CFG["include/config.h"]
Main --> HCI["hci_transport(由BLE扫描器使用)"]
Main --> BLE["components/ble_scanner/ble_scanner.c"]
Main --> WIFI["components/wifi_manager/wifi_manager.c"]
Main --> MQTT["components/mqtt_client_wrapper/mqtt_client_wrapper.c"]
Main --> WEBUI["WebUI服务器(由main.c初始化)"]
BLE --> CFG
WIFI --> CFG
MQTT --> CFG
BLE --> MQTT
Main --> ETHDoc["docs/CH390H_Wiring.md"]

图表来源 - main.c - config.h - ble_scanner.c - wifi_manager.c - mqtt_client_wrapper.c - CH390H_Wiring.md

章节来源 - CMakeLists.txt - platformio.ini - sdkconfig.defaults - partitions.csv

性能考虑

  • 内存与任务栈：各组件任务栈大小在 config.h 中集中定义，建议根据实际并发需求调整。
  • 日志级别：platformio.ini 设置了调试日志级别与颜色过滤器，便于开发阶段定位问题。
  • 优化选项：sdkconfig.defaults 启用了编译器性能优化与栈检查模式。
  • SPIFFS 文件系统：platformio.ini 指定了 SPIFFS 作为文件系统，用于存放 WebUI 资源与配置。

章节来源 - config.h - platformio.ini - sdkconfig.defaults - platformio.ini

故障排除指南

  • 无法连接到 NRF52833 导致 BLE 功能不可用
  • 现象：系统初始化时提示 HCI 传输初始化失败，BLE 功能被禁用。
  • 排查：确认硬件连接、NRF52833 复位引脚配置、UART 引脚与波特率设置。
  • 参考：main.c、config.h
  • WiFi 连接失败或反复重连
  • 现象：STA 模式下连接超时或频繁断开。
  • 排查：检查 SSID/密码、信号强度、重试次数与超时配置。
  • 参考：wifi_manager.c、config.h
  • MQTT 无法连接或未收到订阅消息
  • 现象：MQTT 状态为断开或未订阅命令主题。
  • 排查：确认 broker URI、用户名/密码、TLS 设置、订阅主题是否正确。
  • 参考：mqtt_client_wrapper.c、config.h
  • CH390H 以太网无法工作
  • 现象：以太网初始化失败或无网络连接。
  • 排查：检查 SPI 引脚连接、中断与复位引脚、PHY 地址与时钟频率。
  • 参考：CH390H_Wiring.md、config.h
  • 日志与串口监控
  • 使用 platformio.ini 中的 monitor_speed 与 monitor_filters 查看实时日志。
  • 参考：platformio.ini

章节来源 - main.c - wifi_manager.c - mqtt_client_wrapper.c - CH390H_Wiring.md - platformio.ini

结论

本指南提供了从环境搭建到系统验证的完整路径。建议先完成工具链与 IDE 配置，再进行首次编译与烧录，随后进行硬件连接与启动验证。遇到问题时，结合日志与本指南的故障排除部分逐步排查。

附录

开发环境搭建与工具链安装

  • 安装 ESP-IDF：参考官方文档安装最新版本的 ESP-IDF。
  • 安装 PlatformIO：在 VS Code 中安装 PlatformIO IDE 插件。
  • 安装 Python 依赖：确保 pip 可用，安装必要的 Python 包（如 pio、idf 等）。
  • 安装串口驱动：根据目标开发板选择合适的 USB/串口驱动。

IDE 配置（VS Code + PlatformIO）

  • 打开仓库根目录（含 platformio.ini）。
  • 在 PlatformIO Home 中选择环境 esp32s3，确保平台、板型与分区表正确。
  • 配置监视器端口与波特率（platformio.ini 中已预设）。
  • 参考：platformio.ini、platformio.ini

编译配置（ESP-IDF 与 PlatformIO）

  • ESP-IDF 方式
  • 顶层工程：使用 CMakeLists.txt 指定 EXTRA_COMPONENT_DIRS。
  • 参考：CMakeLists.txt
  • PlatformIO 方式
  • 环境配置：平台 espressif32@6.9.0、板型 esp32-s3-devkitc-1、分区表 partitions.csv、文件系统 spiffs。
  • 构建标志：调试日志级别、颜色过滤、HC1 UART 引脚与波特率、NRF52833 复位引脚、网关名称与版本。
  • 参考：platformio.ini、platformio.ini、platformio.ini
  • SDK 配置默认值
  • 系统、WiFi、LWIP、HTTPD、UART、日志、NVS、看门狗、分区表、优化等。
  • 参考：sdkconfig.defaults
  • 分区表
  • 自定义分区表，包含 factory、ota_0、ota_1、nvs、phy_init、spiffs 等。
  • 参考：partitions.csv

首次编译与烧录

  • ESP-IDF 流程
  • 在工程根目录执行构建命令，生成固件镜像。
  • 使用烧录工具写入 Flash，或通过 PlatformIO 一键烧录。
  • PlatformIO 流程
  • 在 VS Code 中打开工程，选择环境 esp32s3，点击“Upload”按钮完成烧录。
  • 参考：platformio.ini

硬件连接示例

  • CH390H 以太网模块接线
  • 引脚对应：SDI/MOSI、SDO/MISO、SCK、SCS、INT、RST、VCC/GND。
  • 参考：CH390H_Wiring.md
  • NRF52833 与 ESP32-S3 的 HCI UART 连接
  • 引脚：TX、RX、RTS、CTS；波特率与复位引脚在配置中定义。
  • 参考：config.h

系统启动验证

  • 观察串口日志：确认系统初始化、WiFi 启动、MQTT 连接、BLE 扫描启动、以太网初始化等关键节点。
  • LED 状态：WS2812 三色 LED 显示 WiFi、MQTT、BLE 状态。
  • 参考：main.c
  • WebUI 访问：在浏览器访问 WebUI（端口与任务栈在配置中定义），查看设备列表与配置界面。
  • 参考：config.h