BLE设备管理接口

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

目录

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

简介

本项目是一个基于ESP32-S3的BLE网关系统，提供了完整的BLE设备管理API接口。该系统支持双网络模式（以太网/WiFi），具备BLE扫描和多设备连接管理功能，并通过Web界面提供用户交互。

系统的核心功能包括： - BLE设备发现和管理 - 设备列表获取和过滤 - 扫描控制和设备清除 - 连接状态查询和连接/断开操作 - 实时状态监控和配置管理

项目结构

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

graph TB
subgraph "应用层"
WebUI[Web用户界面]
REST[REST API服务]
end
subgraph "业务逻辑层"
BLEGW[BLE网关核心]
Config[配置管理]
Network[网络管理]
end
subgraph "硬件抽象层"
HCI[HCI传输层]
ETH[以太网控制器]
WIFI[WiFi管理器]
end
subgraph "硬件层"
ESP32S3[ESP32-S3芯片]
nRF52833[nRF52833 BLE控制器]
end
WebUI --> REST
REST --> BLEGW
REST --> Config
REST --> Network
BLEGW --> HCI
Network --> ETH
Network --> WIFI
HCI --> nRF52833
ESP32S3 --> HCI

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

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

核心组件

BLE设备数据模型

系统定义了标准的BLE设备数据结构，用于存储设备信息和状态：

classDiagram
class ble_device_t {
+uint8_t mac[6]
+uint8_t addr_type
+char name[32]
+int8_t rssi
+uint8_t adv_data[31]
+uint8_t adv_len
+uint32_t last_seen
+bool connected
+uint16_t conn_handle
}
class BLE网关接口 {
+ble_gateway_init() esp_err_t
+ble_gateway_start_scan() esp_err_t
+ble_gateway_stop_scan() esp_err_t
+ble_gateway_connect(mac) esp_err_t
+ble_gateway_disconnect(mac) esp_err_t
+ble_gateway_get_devices() esp_err_t
+ble_gateway_get_device_count() uint16_t
+ble_gateway_clear_devices() esp_err_t
}
BLE网关接口 --> ble_device_t : "使用"

图表来源 - ble_gateway.h

网络配置参数

系统支持多种网络模式和配置参数：

参数	值	描述
网络模式	ETH_ONLY, WIFI_ONLY, ETH_PRIMARY, WIFI_PRIMARY	网络优先级设置
默认主机名	"ble-gateway"	设备默认主机名
WebUI端口	80	Web界面监听端口
WebSocket端口	81	实时通信端口
WiFi AP设置	SSID: "BLE-Gateway-Setup", 密码: "12345678"	配置模式设置

章节来源 - config.h

架构概览

系统采用分层架构设计，从底层硬件到上层应用形成清晰的层次结构：

sequenceDiagram
participant Client as 客户端
participant WebUI as Web界面
participant REST as REST API
participant BLEGW as BLE网关
participant HCI as HCI传输
participant nRF as nRF52833
Client->>WebUI : 访问设备页面
WebUI->>REST : GET /api/devices
REST->>BLEGW : 获取设备列表
BLEGW->>HCI : 查询设备状态
HCI->>nRF : 发送HCI命令
nRF-->>HCI : 返回设备信息
HCI-->>BLEGW : 设备数据
BLEGW-->>REST : 设备数组
REST-->>WebUI : JSON响应
WebUI-->>Client : 渲染设备列表
Note over Client,nRF : 设备连接流程
Client->>WebUI : 点击连接按钮
WebUI->>REST : POST /api/devices/{mac}/connect
REST->>BLEGW : 执行连接操作
BLEGW->>HCI : 发送连接命令
HCI->>nRF : 建立BLE连接
nRF-->>HCI : 连接确认
HCI-->>BLEGW : 连接结果
BLEGW-->>REST : 操作结果
REST-->>WebUI : 连接状态
WebUI-->>Client : 更新界面状态

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

详细组件分析

REST API服务

REST API服务提供了完整的BLE设备管理接口，包括状态查询、设备管理、扫描控制等功能。

设备管理端点

系统提供了两个主要的设备管理端点，它们在功能和用途上有明确的区别：

GET /api/devices - 设备列表获取

此端点用于获取当前发现的所有BLE设备列表，返回格式化的设备信息数组：

sequenceDiagram
participant Client as 客户端
participant REST as REST服务
participant BLEGW as BLE网关
participant HCI as HCI传输
Client->>REST : GET /api/devices
REST->>BLEGW : ble_gateway_get_devices()
BLEGW->>HCI : 查询设备状态
HCI-->>BLEGW : 设备数据
BLEGW-->>REST : 设备数组
REST->>REST : 格式化JSON响应
REST-->>Client : 设备列表JSON

图表来源 - rest_api.c

GET /api/ble/devices - 旧版本兼容端点

此端点是旧版本系统的兼容接口，功能与/api/devices相同，但路径不同：

flowchart TD
A[客户端请求] --> B[REST服务接收]
B --> C[调用BLE网关]
C --> D[获取设备列表]
D --> E[格式化设备数据]
E --> F[返回JSON响应]
F --> G[客户端接收]

图表来源 - webui_server.c

扫描控制端点

POST /api/devices/scan - 扫描启停控制

该端点用于控制BLE扫描功能的启停：

flowchart TD
A[客户端发送请求] --> B{enable参数检查}
B --> |true| C[启动扫描]
B --> |false| D[停止扫描]
C --> E[HCI发送扫描命令]
D --> F[HCI发送停止命令]
E --> G[更新扫描状态]
F --> G
G --> H[返回状态响应]

图表来源 - rest_api.c

设备操作端点

POST /api/devices/{mac}/connect - 设备连接

该端点用于建立BLE设备连接，支持指定设备MAC地址和连接类型：

sequenceDiagram
participant Client as 客户端
participant REST as REST服务
participant BLEGW as BLE网关
participant HCI as HCI传输
participant nRF as nRF52833
Client->>REST : POST /api/devices/{mac}/connect
REST->>BLEGW : ble_gateway_connect(mac)
BLEGW->>HCI : 发送连接命令
HCI->>nRF : LE Create Connection
nRF-->>HCI : 连接事件
HCI-->>BLEGW : 连接完成
BLEGW-->>REST : 连接结果
REST-->>Client : 连接状态

图表来源 - ble_gateway.h

DELETE /api/devices - 清除设备列表

该端点用于清空所有已发现的BLE设备记录：

flowchart TD
A[客户端请求清除] --> B[验证请求]
B --> C[调用清除函数]
C --> D[重置设备计数器]
D --> E[清空设备数组]
E --> F[更新状态]
F --> G[返回成功响应]

图表来源 - rest_api.c

章节来源 - rest_api.c - ble_gateway.h

WebUI服务器

WebUI服务器提供了一个直观的图形用户界面，用于实时监控和管理BLE设备：

graph LR
subgraph "Web界面组件"
Dashboard[仪表板]
Devices[设备管理]
Config[配置页面]
end
subgraph "JavaScript功能"
StatusUpdater[状态更新器]
DeviceManager[设备管理器]
Scanner[扫描器]
end
subgraph "API集成"
StatusAPI[/api/status]
DevicesAPI[/api/devices]
ScanAPI[/api/devices/scan]
ConfigAPI[/api/config]
end
Dashboard --> StatusUpdater
Devices --> DeviceManager
DeviceManager --> Scanner
StatusUpdater --> StatusAPI
DeviceManager --> DevicesAPI
Scanner --> ScanAPI
Config --> ConfigAPI

图表来源 - webui_server.c - index.html - devices.html

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

BLE网关核心

BLE网关核心负责处理BLE设备的发现、连接和状态管理：

设备发现机制

BLE网关通过以下步骤实现设备发现：

1. 扫描参数配置：使用预定义的扫描间隔和窗口参数
2. 设备列表管理：维护固定大小的设备数组，支持最大设备数量限制
3. 设备状态跟踪：记录每个设备的最后出现时间，支持超时清理
4. 并发安全：使用互斥锁确保多任务环境下的数据一致性

连接管理

系统支持最多8个同时连接的BLE设备，具有以下特性：

• 连接参数：最小连接间隔30ms，最大连接间隔50ms
• 超时设置：5秒监督超时
• 连接状态：支持连接中、已连接、断开连接三种状态
• 自动重连：断开后可重新连接

章节来源 - ble_gateway.h

依赖关系分析

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

graph TB
subgraph "外部依赖"
ESP_IDF[ESP-IDF框架]
cJSON[cJSON库]
HTTP_Server[HTTP服务器]
end
subgraph "内部组件"
Main[主程序]
REST_API[REST API]
WebUI[Web界面]
BLE_Gateway[BLE网关]
Config_Manager[配置管理]
Network_Manager[网络管理]
end
subgraph "硬件接口"
HCI_Transport[HCI传输]
ETH_Manager[以太网管理]
WIFI_Manager[WiFi管理]
end
ESP_IDF --> Main
ESP_IDF --> REST_API
ESP_IDF --> WebUI
ESP_IDF --> BLE_Gateway
ESP_IDF --> Config_Manager
ESP_IDF --> Network_Manager
cJSON --> REST_API
HTTP_Server --> WebUI
HTTP_Server --> REST_API
Main --> REST_API
Main --> WebUI
Main --> BLE_Gateway
Main --> Network_Manager
REST_API --> BLE_Gateway
REST_API --> Config_Manager
REST_API --> Network_Manager
BLE_Gateway --> HCI_Transport
Network_Manager --> ETH_Manager
Network_Manager --> WIFI_Manager

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

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

性能考虑

内存管理

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

• 静态分配：设备数组在编译时确定大小，避免运行时内存分配
• 缓冲区大小：BLE设备数组大小为100个设备，满足大多数应用场景
• 内存优化：使用紧凑的数据结构减少内存占用

并发处理

系统通过以下机制保证并发安全性：

• 互斥锁：保护设备列表的访问和修改
• 信号量：协调不同任务间的同步
• 原子操作：确保关键数据的完整性

网络性能

• HTTP服务器配置：支持最多4个并发客户端连接
• WebSocket：提供实时双向通信能力
• 缓存策略：合理利用内存缓存提高响应速度

故障排除指南

常见问题及解决方案

问题1：设备无法被发现 - 检查nRF52833是否正确连接 - 验证扫描参数设置 - 确认设备在有效范围内

问题2：连接失败 - 检查设备是否处于可连接状态 - 验证MAC地址格式 - 确认连接参数配置

问题3：Web界面无法访问 - 检查网络连接状态 - 验证WebUI端口配置 - 确认防火墙设置

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

结论

本BLE设备管理API提供了完整的企业级BLE网关解决方案，具有以下特点：

功能完整性 - 支持设备发现、连接、状态监控等核心功能 - 提供灵活的过滤和搜索能力 - 具备良好的扩展性和可维护性

性能优势 - 高效的内存管理和并发处理 - 优化的网络通信协议 - 实时的状态更新机制

用户体验 - 直观的Web界面 - 丰富的API接口 - 完善的错误处理和诊断功能

该系统适用于工业物联网、资产追踪、智能建筑等多种应用场景，为企业提供可靠的BLE设备管理解决方案。