设备管理API¶
本文档引用的文件 - main.c - webui_server.c - rest_api.c - ble_gateway.c - ble_gateway.h - config.h - rest_api.h
目录¶
简介¶
本文档详细描述了ESP32-S3 BLE网关项目的设备管理API。该系统提供了两个主要的API端点：/api/devices用于获取BLE设备列表，以及/api/ble/devices用于管理BLE设备列表。这些API基于ESP-IDF框架构建，使用cJSON库进行JSON数据处理，并通过内置HTTP服务器提供RESTful接口。
项目结构¶
该项目采用模块化架构设计，主要包含以下核心组件：
graph TB
subgraph "应用层"
Main[主应用程序<br/>main.c]
WebUI[WebUI服务器<br/>webui_server.c]
REST[REST API<br/>rest_api.c]
end
subgraph "业务逻辑层"
BLEGateway[BLE网关核心<br/>ble_gateway.c]
Config[配置管理<br/>config.h]
end
subgraph "硬件抽象层"
HCI[HCI传输<br/>hci_transport]
Network[网络管理<br/>network_manager]
end
Main --> WebUI
Main --> REST
WebUI --> REST
REST --> BLEGateway
BLEGateway --> HCI
BLEGateway --> Network
REST --> Config图表来源 - main.c - webui_server.c - rest_api.c
章节来源 - main.c - webui_server.c - rest_api.c
核心组件¶
BLE设备数据模型¶
系统使用统一的BLE设备结构体来表示所有发现的设备信息：
classDiagram
class ble_device_t {
+uint8_t[6] mac
+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 BLEGateway {
-ble_device_t[100] s_devices
-uint16_t s_device_count
-SemaphoreHandle_t s_mutex
+ble_gateway_init() esp_err_t
+ble_gateway_get_devices() esp_err_t
+ble_gateway_clear_devices() esp_err_t
+ble_gateway_start_scan() esp_err_t
+ble_gateway_stop_scan() esp_err_t
}
BLEGateway --> ble_device_t : "管理"图表来源 - ble_gateway.h - ble_gateway.c
API端点架构¶
系统提供两个主要的设备管理API端点：
| 端点 | 方法 | 功能描述 |
|---|---|---|
/api/devices |
GET | 获取当前发现的所有BLE设备列表 |
/api/ble/devices |
GET | 获取BLE设备列表（旧版本API） |
/api/ble/devices |
POST | 清空BLE设备列表 |
章节来源 - rest_api.c - webui_server.c
架构概览¶
sequenceDiagram
participant Client as 客户端
participant HTTP as HTTP服务器
participant REST as REST API
participant Gateway as BLE网关
participant HCI as HCI传输
Client->>HTTP : GET /api/devices
HTTP->>REST : 调用api_devices_handler
REST->>Gateway : ble_gateway_get_devices()
Gateway->>Gateway : 获取设备列表
Gateway-->>REST : 返回设备数组
REST->>REST : 构建JSON响应
REST-->>HTTP : JSON设备列表
HTTP-->>Client : HTTP响应
Note over Client,HCI : 设备发现过程
HCI->>Gateway : 广告数据包
Gateway->>Gateway : 更新设备状态
Gateway->>Gateway : 更新RSSI和时间戳图表来源 - rest_api.c - ble_gateway.c
详细组件分析¶
/api/devices 端点¶
GET方法实现¶
/api/devices端点提供当前发现的所有BLE设备的完整列表。该端点使用GET方法，返回JSON格式的设备信息数组。
请求格式
- 方法: GET
- URL: /api/devices
- 头部: 无特殊要求
响应格式
成功响应返回标准HTTP 200状态码和JSON数组：
[
{
"mac": "AA:BB:CC:DD:EE:FF",
"name": "Device Name",
"rssi": -65,
"connected": false
},
{
"mac": "12:34:56:78:90:AB",
"name": "Another Device",
"rssi": -82,
"connected": true
}
]
字段说明
| 字段名 | 类型 | 必需 | 描述 | 示例值 |
|---|---|---|---|---|
| mac | string | 是 | 设备的MAC地址 | "AA:BB:CC:DD:EE:FF" |
| name | string | 是 | 设备名称 | "Device Name" |
| rssi | integer | 是 | 接收信号强度指示器 | -65 |
| connected | boolean | 是 | 设备是否已连接 | false |
实现细节
API处理器从BLE网关获取设备列表，将每个设备转换为标准JSON对象。MAC地址格式化为大写十六进制字符串，RSSI值为整数形式，连接状态为布尔值。
章节来源 - rest_api.c - ble_gateway.c
/api/ble/devices 端点¶
GET方法¶
/api/ble/devices端点提供BLE设备列表的另一种访问方式，主要用于向后兼容性。
请求格式
- 方法: GET
- URL: /api/ble/devices
响应格式
与/api/devices相同，返回相同的JSON数组格式。
POST方法¶
/api/ble/devices端点支持POST方法来清空设备列表。
请求格式
- 方法: POST
- URL: /api/ble/devices
- 请求体: 无内容或空JSON对象
响应格式 成功响应返回标准HTTP 200状态码和简单JSON对象：
实现细节
POST请求触发BLE网关的设备列表清空功能，内部调用ble_gateway_clear_devices()函数重置设备存储。
章节来源 - webui_server.c - ble_gateway.c
设备数据结构详解¶
BLE设备信息通过统一的数据结构进行管理，包含以下关键字段：
erDiagram
BLE_DEVICE {
uint8_t[6] mac_address
uint8_t address_type
char[32] device_name
int8_t rssi_value
uint8_t[31] advertisement_data
uint8_t data_length
uint32_t last_seen_timestamp
bool is_connected
uint16_t connection_handle
}
BLE_GATEWAY {
ble_device_t[100] device_array
uint16_t device_count
SemaphoreHandle_t mutex
bool is_scanning
}
BLE_GATEWAY ||--o{ BLE_DEVICE : manages图表来源 - ble_gateway.h - ble_gateway.c
字段详细说明
| 字段名 | 数据类型 | 描述 | 用途 |
|---|---|---|---|
| mac | uint8_t[6] | 设备MAC地址 | 唯一标识设备 |
| addr_type | uint8_t | 地址类型 | 0=公共地址, 1=随机地址 |
| name | char[32] | 设备名称 | 用户可读的设备名称 |
| rssi | int8_t | 信号强度 | 接收功率指示器(dBm) |
| adv_data | uint8_t[31] | 广告数据 | BLE广告包中的原始数据 |
| adv_len | uint8_t | 广告数据长度 | 广告数据的有效字节数 |
| last_seen | uint32_t | 最后出现时间 | 时间戳，秒级精度 |
| connected | bool | 连接状态 | 设备是否处于连接状态 |
| conn_handle | uint16_t | 连接句柄 | 当前连接的句柄值 |
章节来源 - ble_gateway.h
依赖关系分析¶
graph LR
subgraph "外部依赖"
cJSON[cJSON库]
ESP_IDF[ESP-IDF框架]
FreeRTOS[FreeRTOS]
end
subgraph "内部模块"
REST_API[REST API模块]
WEBUI[WebUI服务器]
BLE_GATEWAY[BLE网关核心]
CONFIG[配置管理]
end
REST_API --> cJSON
REST_API --> ESP_IDF
REST_API --> BLE_GATEWAY
REST_API --> CONFIG
WEBUI --> REST_API
WEBUI --> ESP_IDF
BLE_GATEWAY --> FreeRTOS
BLE_GATEWAY --> ESP_IDF
BLE_GATEWAY --> CONFIG
CONFIG --> ESP_IDF图表来源 - rest_api.c - webui_server.c - ble_gateway.c
关键依赖关系¶
- cJSON库: 用于JSON数据的序列化和反序列化
- ESP-IDF框架: 提供HTTP服务器、网络栈和硬件抽象
- FreeRTOS: 提供任务调度和同步机制
- BLE网关核心: 实际的BLE设备管理和扫描功能
章节来源 - rest_api.c - webui_server.c - ble_gateway.c
性能考虑¶
内存管理¶
系统在设计时考虑了内存效率：
- 设备数组大小: 默认支持最多100个设备的存储
- 缓冲区管理: 使用固定大小的缓冲区避免动态内存分配
- 互斥锁: 使用FreeRTOS互斥锁确保线程安全
扫描性能¶
- 扫描间隔: 默认50ms的扫描间隔平衡了响应性和功耗
- 设备超时: 60秒的设备超时防止内存泄漏
- 并发控制: 使用信号量保护共享资源
网络性能¶
- HTTP服务器: 配置了适当的堆栈大小和URI处理器数量
- JSON生成: 使用cJSON库高效生成JSON响应
- 静态文件服务: 支持SPIFFS上的静态文件托管
故障排除指南¶
常见问题及解决方案¶
问题1: API响应为空数组 - 检查BLE扫描是否已启动 - 确认设备是否在有效范围内 - 验证设备过滤设置
问题2: 设备列表不更新 - 确认扫描参数配置正确 - 检查设备超时设置 - 验证网络连接状态
问题3: 内存不足错误 - 检查设备数量是否超过限制 - 优化扫描间隔设置 - 清理不需要的设备条目
调试建议¶
- 启用调试日志: 在开发环境中启用详细的ESP_LOG输出
- 监控内存使用: 定期检查可用堆内存
- 验证网络连接: 确保HTTP服务器正常运行
- 测试设备发现: 使用简单的BLE设备进行功能测试
章节来源 - ble_gateway.c - config.h
结论¶
本设备管理API为ESP32-S3 BLE网关提供了完整的BLE设备发现和管理功能。通过标准化的JSON接口，开发者可以轻松集成BLE设备管理到各种应用中。系统的设计考虑了性能、可靠性和易用性，在保持低资源消耗的同时提供了丰富的功能。
主要优势包括： - 标准化的RESTful API接口 - 高效的JSON数据处理 - 线程安全的设备管理 - 可扩展的架构设计 - 完善的错误处理机制
未来可以考虑的功能增强包括： - 更精细的设备过滤选项 - 设备历史数据跟踪 - 批量操作支持 - 更详细的设备状态信息