扫描控制API¶

本文档引用的文件 - main.c - webui_server.c - rest_api.c - rest_api.h - ble_gateway.c - index.html - devices.html

目录¶

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

简介¶

本文档详细描述了ESP32-S3 BLE网关项目的扫描控制API。该API提供了对BLE扫描功能的远程控制能力，允许通过HTTP接口启动和停止BLE设备扫描。系统采用RESTful API设计，支持JSON格式的请求和响应数据。

BLE网关项目是一个企业级的双网络支持（以太网/WiFi）BLE扫描网关，集成了WiFi配置功能、BLE扫描和多设备连接管理。主要功能包括：

双网络支持：同时支持以太网和WiFi连接模式
BLE扫描控制：通过API控制BLE扫描的启停
设备发现：自动发现和跟踪BLE设备
Web界面：提供直观的Web管理界面
MQTT集成：可选的MQTT消息传输功能

项目结构¶

项目采用模块化架构设计，主要包含以下核心组件：

graph TB
subgraph "应用层"
WebUI[Web用户界面]
REST[REST API服务器]
end
subgraph "业务逻辑层"
BLEGateway[BLE网关服务]
ConfigManager[配置管理器]
NetworkManager[网络管理器]
end
subgraph "硬件抽象层"
HCITransport[HCI传输层]
BLEScanner[BLE扫描器]
end
subgraph "外设层"
LED指示灯
按钮
网络接口
end
WebUI --> REST
REST --> BLEGateway
REST --> ConfigManager
REST --> NetworkManager
BLEGateway --> HCITransport
HCITransport --> BLEScanner
BLEGateway --> LED指示灯
BLEGateway --> 按钮
NetworkManager --> 网络接口

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

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

核心组件¶

REST API服务器¶

REST API服务器是系统的核心通信接口，基于ESP-IDF的HTTP服务器框架构建。它提供了完整的RESTful API端点，支持GET、POST、PUT等HTTP方法。

主要特性： - URI路由：支持通配符URI匹配 - JSON处理：使用cJSON库进行JSON数据解析和生成 - 错误处理：标准HTTP状态码返回 - 内存管理：合理的内存分配和释放策略

BLE网关服务¶

BLE网关服务负责BLE设备的扫描、连接和数据管理。它通过HCI传输层与底层BLE硬件通信，实现了完整的BLE协议栈功能。

核心功能： - 扫描控制：启动和停止BLE扫描 - 设备管理：跟踪和管理发现的BLE设备 - 连接管理：建立和维护BLE连接 - 状态监控：实时监控扫描状态和设备数量

Web用户界面¶

Web用户界面提供了直观的图形化操作界面，用户可以通过浏览器访问系统状态和控制BLE扫描。

主要页面： - 仪表板：显示系统状态和网络信息 - 设备列表：展示发现的BLE设备 - 配置页面：系统配置和设置

章节来源 - rest_api.c - ble_gateway.c - index.html - devices.html

架构概览¶

系统采用分层架构设计，确保了良好的模块分离和可维护性：

sequenceDiagram
participant Client as 客户端
participant WebUI as Web界面
participant REST as REST API
participant Gateway as BLE网关
participant HCI as HCI传输
participant Scanner as BLE扫描器
Client->>WebUI : 访问Web界面
WebUI->>REST : GET /api/status
REST->>Gateway : 获取状态信息
Gateway->>Scanner : 查询扫描状态
Scanner-->>Gateway : 返回扫描状态
Gateway-->>REST : 状态数据
REST-->>WebUI : JSON响应
WebUI-->>Client : 渲染页面
Client->>REST : POST /api/devices/scan
REST->>Gateway : 启动/停止扫描
Gateway->>HCI : 发送HCI命令
HCI->>Scanner : 配置扫描参数
Scanner-->>Gateway : 扫描结果
Gateway-->>REST : 执行结果
REST-->>Client : {"status" : "ok"}

图表来源 - rest_api.c - ble_gateway.c

系统架构的关键特点：

分层设计：清晰的层次分离，便于维护和扩展
模块化：各组件职责明确，耦合度低
异步处理：使用FreeRTOS任务处理并发操作
资源管理：合理的内存和任务资源管理

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

详细组件分析¶

扫描控制API实现¶

API端点定义¶

系统提供了专门的BLE扫描控制API，位于 /api/devices/scan 端点。该端点支持POST方法，用于控制BLE扫描的启停。

API规范： - 端点：/api/devices/scan - 方法：POST - 内容类型：application/json - 请求体：包含 enable 布尔参数

请求格式¶

请求必须包含有效的JSON对象，其中包含 enable 参数：

{
  "enable": true
}

参数说明： - enable (boolean)：控制扫描启停的布尔值 - true：启动BLE扫描 - false：停止BLE扫描

响应格式¶

API调用成功时返回标准的JSON响应：

{
  "status": "ok"
}

响应状态码： - 200 OK：操作成功执行 - 400 Bad Request：请求格式无效或缺少必需参数 - 500 Internal Server Error：服务器内部错误

错误处理¶

API实现了完善的错误处理机制：

flowchart TD
Start([接收请求]) --> ParseJSON["解析JSON请求"]
ParseJSON --> ValidJSON{"JSON有效?"}
ValidJSON --> |否| Return400["返回400错误"]
ValidJSON --> |是| CheckParam["检查enable参数"]
CheckParam --> ValidParam{"参数有效?"}
ValidParam --> |否| Return400
ValidParam --> |是| ExecuteScan["执行扫描操作"]
ExecuteScan --> Success["返回200响应"]
Return400 --> End([结束])
Success --> End

图表来源 - rest_api.c

章节来源 - rest_api.c

BLE网关扫描实现¶

BLE网关服务通过发送HCI命令来控制底层BLE硬件的扫描行为：

扫描启动流程¶

sequenceDiagram
participant REST as REST API
participant Gateway as BLE网关
participant HCI as HCI传输
participant Hardware as BLE硬件
REST->>Gateway : enable = true
Gateway->>Gateway : 验证状态
Gateway->>HCI : 发送LE_SET_SCAN_PARAM
HCI->>Hardware : 设置扫描参数
Hardware-->>HCI : 命令确认
HCI-->>Gateway : 参数设置完成
Gateway->>HCI : 发送LE_SET_SCAN_ENABLE
HCI->>Hardware : 启动扫描
Hardware-->>HCI : 扫描开始确认
HCI-->>Gateway : 扫描启动完成
Gateway-->>REST : 返回成功状态

图表来源 - ble_gateway.c

扫描停止流程¶

sequenceDiagram
participant REST as REST API
participant Gateway as BLE网关
participant HCI as HCI传输
participant Hardware as BLE硬件
REST->>Gateway : enable = false
Gateway->>Gateway : 检查扫描状态
Gateway->>HCI : 发送LE_SET_SCAN_ENABLE(禁用)
HCI->>Hardware : 停止扫描
Hardware-->>HCI : 命令确认
HCI-->>Gateway : 扫描停止确认
Gateway-->>REST : 返回成功状态

图表来源 - ble_gateway.c

章节来源 - ble_gateway.c

Web界面集成¶

Web用户界面提供了直观的BLE扫描控制功能：

设备管理页面¶

设备管理页面包含了完整的BLE扫描控制界面：

graph LR
subgraph "设备管理界面"
StartBtn[开始扫描按钮]
StopBtn[停止按钮]
ClearBtn[清除按钮]
DeviceTable[设备列表表格]
end
StartBtn --> RESTAPI["/api/devices/scan<br/>POST {enable:true}"]
StopBtn --> RESTAPI2["/api/devices/scan<br/>POST {enable:false}"]
RESTAPI --> DeviceTable
RESTAPI2 --> DeviceTable
ClearBtn --> DeviceTable

图表来源 - devices.html

实时状态更新¶

Web界面通过定时轮询获取最新的系统状态：

sequenceDiagram
participant Browser as 浏览器
participant Server as Web服务器
participant API as REST API
participant Gateway as BLE网关
Browser->>Server : GET /api/status
Server->>API : 转发请求
API->>Gateway : 获取状态
Gateway-->>API : 返回状态数据
API-->>Server : JSON响应
Server-->>Browser : 渲染状态
Browser->>Browser : 3秒后再次请求

图表来源 - index.html

章节来源 - devices.html - index.html

依赖关系分析¶

系统组件之间的依赖关系如下：

graph TB
subgraph "外部依赖"
ESP_IDF[ESP-IDF框架]
cJSON[cJSON库]
FreeRTOS[FreeRTOS]
end
subgraph "核心组件"
WebUIServer[WebUI服务器]
RESTAPI[REST API]
BLEGateway[BLE网关]
ConfigManager[配置管理器]
NetworkManager[网络管理器]
end
subgraph "硬件接口"
HCITransport[HCI传输]
BLEScanner[BLE扫描器]
end
ESP_IDF --> WebUIServer
ESP_IDF --> RESTAPI
ESP_IDF --> BLEGateway
ESP_IDF --> ConfigManager
ESP_IDF --> NetworkManager
cJSON --> RESTAPI
FreeRTOS --> WebUIServer
FreeRTOS --> RESTAPI
WebUIServer --> RESTAPI
RESTAPI --> BLEGateway
RESTAPI --> ConfigManager
RESTAPI --> NetworkManager
BLEGateway --> HCITransport
HCITransport --> BLEScanner

图表来源 - main.c - rest_api.c

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

性能考虑¶

内存管理¶

系统采用了高效的内存管理策略：

静态分配：关键数据结构使用静态内存分配
缓冲区管理：HTTP请求缓冲区大小合理设置（64字节）
JSON处理：使用cJSON库进行高效的JSON解析和生成
内存回收：及时释放动态分配的内存

并发处理¶

系统使用FreeRTOS进行并发任务管理：

任务优先级：不同任务具有合适的优先级设置
队列通信：组件间通过队列进行异步通信
互斥锁：保护共享资源的访问
超时机制：避免无限等待，提高系统稳定性

网络优化¶

HTTP服务器配置：合理设置URI处理器数量和堆栈大小
静态文件服务：SPIFFS文件系统提供高效的静态文件服务
连接复用：支持HTTP连接复用减少开销

故障排除指南¶

常见问题及解决方案¶

API调用失败¶

问题：POST /api/devices/scan 返回400错误 可能原因： - 请求JSON格式不正确 - 缺少 enable 参数 - enable 参数类型不是布尔值

解决方法： 1. 确保请求包含有效的JSON对象 2. 验证 enable 参数存在且为布尔值 3. 检查网络连接是否稳定

扫描控制无效¶

问题：调用扫描控制API但扫描状态未改变 可能原因： - BLE硬件未正确初始化 - HCI传输层通信失败 - 权限不足

解决方法： 1. 检查BLE硬件连接状态 2. 验证HCI传输层初始化 3. 查看系统日志获取详细错误信息

Web界面无法访问¶

问题：无法通过浏览器访问Web界面 可能原因： - Web服务器未启动 - 网络连接问题 - 防火墙阻止访问

解决方法： 1. 确认Web服务器已成功启动 2. 检查网络配置和连接状态 3. 验证防火墙设置

章节来源 - rest_api.c - webui_server.c

结论¶

BLE扫描控制API为ESP32-S3 BLE网关项目提供了完整、可靠的BLE扫描管理功能。通过RESTful API设计，用户可以轻松地远程控制BLE扫描的启停，配合Web界面提供了直观的操作体验。

系统的主要优势包括：

简洁的API设计：单一端点提供完整的扫描控制功能
标准化响应：统一的JSON响应格式便于客户端集成
完善的错误处理：提供详细的错误信息和状态反馈
模块化架构：清晰的组件分离便于维护和扩展
实时状态监控：支持实时查看系统状态和设备信息

该API为构建更复杂的BLE应用奠定了坚实的基础，支持从简单的设备发现到复杂的企业级BLE网络管理场景。