调试工具使用¶

本文档引用的文件 - platformio.ini - idf_component.yml - partitions.csv - main.c - hci_test_server.c - hci_passthrough.c - config.h - hci_transport.c - ble_scanner.c - wifi_manager.c - mqtt_client_wrapper.c - webui_server.c - gateway_config.c - ws2812_led.c - eth_manager.c - hci_test.html - hci_uart_tester.py - launch.json

简介¶

本指南面向ESP32S3 BLE网关项目的调试与问题定位，覆盖以下主题： - ESP-IDF调试工具链与PlatformIO集成 - ESP-Prog烧录器使用与串口监视器配置 - Log输出分析与过滤技巧 - 断点调试设置与变量监控 - 内存查看与堆栈分析 - Python调试脚本与HCITester工具使用 - 远程调试与实时监控 - 性能分析与调试报告模板

项目结构¶

项目采用ESP-IDF + PlatformIO工程组织方式，核心目录与职责如下： - old_version: 工程根目录，包含平台配置、组件实现、WebUI资源与工具脚本 - main/: 应用入口与HCI测试服务器 - components/: 功能模块化组件（BLE扫描、WiFi、MQTT、WebUI、配置管理等） - include/: 全局配置头文件 - data/: WebUI页面资源 - tools/: Python HCITester上位机工具 - .vscode/: VS Code调试配置

graph TB
A["工程根目录<br/>old_version"] --> B["main/<br/>应用入口与测试服务器"]
A --> C["components/<br/>功能组件"]
A --> D["include/<br/>全局配置"]
A --> E["data/<br/>WebUI资源"]
A --> F["tools/<br/>Python HCITester"]
A --> G[".vscode/<br/>调试配置"]
B --> B1["main.c"]
B --> B2["hci_test_server.c"]
B --> B3["hci_passthrough.c"]
C --> C1["hci_transport/"]
C --> C2["ble_scanner/"]
C --> C3["wifi_manager/"]
C --> C4["mqtt_client_wrapper/"]
C --> C5["webui_server/"]
C --> C6["gateway_config/"]
C --> C7["ws2812_led/"]
C --> C8["eth_manager/"]

图表来源 - main.c - hci_test_server.c - hci_passthrough.c

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

核心组件¶

应用入口与系统初始化：负责LED状态指示、系统信息打印、组件初始化顺序与主循环
HCI传输层：实现H4 UART协议与外部NRF52833控制器通信
BLE扫描器：基于LE事件解析广告数据、维护设备列表与连接状态
WiFi管理器：STA/AP模式切换、事件回调与状态上报
MQTT客户端：OpenMQTTGateway兼容的消息发布与订阅
WebUI服务器：SPIFFS托管页面、REST API、设备列表与控制
配置管理：NVS持久化存储、默认值与加载/保存流程
LED驱动：RMT编码WS2812，状态指示
以太网管理：CH390H SPI MAC/PHY驱动

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

架构总览¶

系统采用“应用层 → 组件层 → 硬件抽象层”的分层设计，通过事件回调与任务调度实现异步通信。

graph TB
subgraph "应用层"
M["main.c<br/>系统初始化与主循环"]
WUI["webui_server.c<br/>WebUI与REST API"]
PASSTHRU["hci_passthrough.c<br/>透明转发模式"]
end
subgraph "组件层"
HT["hci_transport.c<br/>H4 UART传输"]
SCN["ble_scanner.c<br/>BLE扫描与事件"]
WM["wifi_manager.c<br/>WiFi管理"]
MQ["mqtt_client_wrapper.c<br/>MQTT客户端"]
CFG["gateway_config.c<br/>配置管理"]
LED["ws2812_led.c<br/>LED状态指示"]
ETH["eth_manager.c<br/>CH390H以太网"]
end
subgraph "硬件抽象层"
UART["UART外设<br/>NRF52833控制器"]
SPI["SPI外设<br/>CH390H MAC/PHY"]
RMT["RMT外设<br/>WS2812驱动"]
end
M --> HT
M --> SCN
M --> WM
M --> MQ
M --> WUI
M --> CFG
M --> LED
M --> ETH
HT --> UART
PASSTHRU --> UART
ETH --> SPI
LED --> RMT

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

详细组件分析¶

应用入口与系统初始化¶

初始化NVS、事件循环与系统信息打印
加载配置、初始化各子系统（WiFi、MQTT、WebUI、BLE）
启动LED状态任务与主循环定时打印堆内存

sequenceDiagram
participant APP as "app_main()"
participant NVS as "NVS初始化"
participant SYS as "事件循环"
participant CFG as "配置加载"
participant HCI as "HCI传输"
participant ETH as "以太网"
participant WIFI as "WiFi管理器"
participant MQTT as "MQTT客户端"
participant WEB as "WebUI服务器"
participant SCN as "BLE扫描器"
APP->>NVS : nvs_flash_init()
APP->>SYS : esp_event_loop_create_default()
APP->>CFG : gateway_config_init()
APP->>HCI : hci_transport_init()
alt HCI就绪
APP->>SCN : ble_scanner_init()/start()
end
APP->>ETH : eth_manager_init()/start()
APP->>WIFI : wifi_manager_init()/start()
APP->>MQTT : mqtt_client_init()/start()
APP->>WEB : webui_server_init()
APP->>APP : 创建LED状态任务

图表来源 - main.c

章节来源 - main.c

HCI传输层（H4 UART）¶

硬件流控（RTS/CTS）与高波特率（1Mbps）
异步事件接收与命令完成同步
控制器复位与状态机管理

flowchart TD
START(["初始化"]) --> CFGGPIO["配置NRF复位GPIO"]
CFGGPIO --> UARTINIT["UART参数配置<br/>波特率/流控/引脚"]
UARTINIT --> RESET["复位NRF52833"]
RESET --> RXTASK["创建RX任务"]
RXTASK --> WAITCMD["等待事件包"]
WAITCMD --> |事件包| HANDLE["解析事件/ACL"]
HANDLE --> CB["调用用户回调"]
WAITCMD --> |超时/错误| LOGERR["记录错误"]
CB --> WAITCMD

图表来源 - hci_transport.c - hci_transport.c - hci_transport.c

章节来源 - hci_transport.c

BLE扫描器¶

设置事件掩码、随机地址、扫描参数与启用扫描
解析LE广告报告、提取设备名与RSSI
连接/断开流程与状态回调

sequenceDiagram
participant SCN as "BLE扫描器"
participant HT as "HCI传输"
participant CTRL as "NRF52833控制器"
SCN->>HT : 发送Set Event Mask
HT->>CTRL : H4命令
CTRL-->>HT : Command Complete
HT-->>SCN : 命令完成事件
SCN->>HT : 发送LE Set Random Address
SCN->>HT : 发送LE Set Scan Param
SCN->>HT : 发送LE Set Scan Enable ON
CTRL-->>HT : LE Meta Event(Advertising Report)
HT-->>SCN : 事件回调
SCN->>SCN : 更新设备列表/名称/RSSI

图表来源 - ble_scanner.c - ble_scanner.c

章节来源 - ble_scanner.c

WebUI服务器与REST API¶

SPIFFS挂载与静态页面服务
设备列表、扫描控制、连接控制、配置读写
状态聚合与JSON响应

sequenceDiagram
participant Browser as "浏览器"
participant WebUI as "WebUI服务器"
participant SCN as "BLE扫描器"
participant CFG as "配置管理"
Browser->>WebUI : GET /
WebUI-->>Browser : index.html
Browser->>WebUI : GET /api/devices
WebUI->>SCN : 获取设备列表
SCN-->>WebUI : 设备数组
WebUI-->>Browser : JSON设备列表
Browser->>WebUI : POST /api/scan?action=start
WebUI->>SCN : 启动扫描
WebUI-->>Browser : {"scanning" : true}
Browser->>WebUI : POST /api/config
WebUI->>CFG : 保存配置
WebUI-->>Browser : {"success" : true}

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

章节来源 - webui_server.c

配置管理（NVS）¶

默认值设定与键空间命名
加载/保存/重置流程，带有效性标记

flowchart TD
INIT["初始化"] --> DEFAULTS["设置默认值"]
DEFAULTS --> LOAD["尝试从NVS加载"]
LOAD --> |成功| APPLY["应用配置"]
LOAD --> |失败| USEDEF["使用默认值"]
APPLY --> READY["就绪"]
USEDEF --> READY
READY --> SAVE["保存配置"]
READY --> RESET["重置配置"]

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

章节来源 - gateway_config.c

以太网管理（CH390H）¶

SPI主机配置与CH390 MAC/PHY安装
事件回调与IP获取、状态上报

sequenceDiagram
participant ETH as "eth_manager"
participant SPI as "SPI主机"
participant MAC as "CH390 MAC"
participant PHY as "CH390 PHY"
ETH->>SPI : 配置SPI引脚与时钟
ETH->>MAC : 创建MAC实例
ETH->>PHY : 创建PHY实例
ETH->>ETH : 安装驱动并注册事件
ETH->>ETH : 启动以太网
ETH-->>ETH : 事件回调(连接/断开/IP)

图表来源 - eth_manager.c - eth_manager.c - eth_manager.c

章节来源 - eth_manager.c

透明转发模式（Passthrough）¶

将USB UART与NRF52833 UART双向转发
便于PC侧工具直接调试控制器

sequenceDiagram
participant PC as "PC工具"
participant USB as "UART0(USB)"
participant PASS as "Passthrough任务"
participant HCI as "UART1(HCI)"
PC->>USB : 发送命令
USB->>PASS : 读取数据
PASS->>HCI : 转发至NRF52833
HCI-->>PASS : 返回事件
PASS-->>USB : 转发回PC

图表来源 - hci_passthrough.c - hci_passthrough.c

章节来源 - hci_passthrough.c

HCITester工具（Python）¶

GUI上位机，支持常用HCI命令、事件解析、设备列表
支持1Mbps波特率、可选硬件流控
提供一键扫描序列与原始数据显示

sequenceDiagram
participant GUI as "HCITester GUI"
participant PY as "hci_uart_tester.py"
participant SERIAL as "串口驱动"
participant NRF as "NRF52833控制器"
GUI->>PY : 用户选择端口/波特率/流控
PY->>SERIAL : 打开端口
GUI->>PY : 发送预设命令/自定义HEX
PY->>SERIAL : 写入数据
SERIAL->>NRF : 通过UART发送
NRF-->>SERIAL : 返回事件/数据
SERIAL-->>PY : 读取缓冲区
PY->>GUI : 解析并展示事件/设备

图表来源 - hci_uart_tester.py - hci_uart_tester.py - hci_uart_tester.py

章节来源 - hci_uart_tester.py

依赖关系分析¶

构建与环境
PlatformIO默认环境与monitor_filters配置
分区表定义与SPIFFS分区
组件依赖（CH390H驱动）

graph LR
PIO["platformio.ini"] --> ENV["环境配置<br/>monitor_filters/构建标志"]
PIO --> PART["partitions.csv<br/>分区表"]
IDFCFG["idf_component.yml"] --> DEPS["组件依赖<br/>CH390H驱动"]

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

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