BLE过滤器API

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

目录

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

简介

BLE过滤器API是ESP32-S3 BLE网关系统中的一个关键功能模块，负责管理BLE设备的过滤规则。该API提供了两个主要端点：/api/ble/filter，支持GET和POST方法，用于获取和设置BLE设备过滤器配置。

该系统基于ESP-IDF框架构建，集成了双网络支持（以太网/WiFi）、BLE扫描和多设备连接管理等功能。BLE过滤器API允许用户通过HTTP接口动态配置设备过滤规则，包括设备名称过滤、RSSI阈值和MAC地址过滤器。

项目结构

BLE过滤器API位于整个系统的WebUI服务器架构中，与REST API和其他系统组件协同工作：

graph TB
subgraph "应用层"
WebUI[WebUI服务器]
REST[REST API]
end
subgraph "BLE处理层"
BLEScanner[BLE扫描器]
BLEGateway[BLE网关]
end
subgraph "硬件抽象层"
HCI[HCI传输]
Config[配置管理]
end
subgraph "网络层"
WiFi[WiFi管理器]
Ethernet[以太网管理器]
Network[网络管理器]
end
WebUI --> REST
REST --> BLEScanner
REST --> BLEGateway
BLEScanner --> HCI
BLEGateway --> HCI
WebUI --> Config
REST --> Config
WebUI --> Network
REST --> Network

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

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

核心组件

BLE过滤器API的核心组件包括：

数据结构定义

BLE过滤器使用以下数据结构来存储过滤配置：

classDiagram
class ble_device_filter_t {
+char name_filter[BLE_NAME_MAX_LEN + 1]
+int8_t rssi_filter
+uint8_t mac_filter[BLE_ADDR_LEN]
+bool mac_filter_enabled
}
class ble_device_t {
+uint8_t addr[BLE_ADDR_LEN]
+ble_addr_type_t addr_type
+int8_t rssi
+char name[BLE_NAME_MAX_LEN + 1]
+uint8_t adv_data[BLE_ADV_DATA_MAX]
+uint8_t adv_data_len
+uint32_t last_seen_ms
+bool is_new
}
class HTTP请求处理器 {
+api_ble_filter_handler(req) esp_err_t
+device_passes_filter(device) bool
}
ble_device_filter_t --> HTTP请求处理器 : "配置过滤器"
HTTP请求处理器 --> ble_device_t : "检查设备"

图表来源 - ble_scanner.h - ble_scanner.h

API端点定义

系统注册了两个主要的API端点：

端点	方法	功能描述
/api/ble/filter	GET	获取当前BLE过滤器配置
/api/ble/filter	POST	设置BLE过滤器参数

章节来源 - ble_scanner.h - webui_server.c

架构概览

BLE过滤器API采用分层架构设计，确保了良好的模块化和可维护性：

sequenceDiagram
participant Client as 客户端
participant WebUI as WebUI服务器
participant REST as REST API
participant Scanner as BLE扫描器
participant Filter as 过滤器
Client->>WebUI : GET /api/ble/filter
WebUI->>REST : 转发请求
REST->>Scanner : ble_scanner_get_filter()
Scanner->>Filter : 获取当前过滤配置
Filter-->>Scanner : 返回过滤器配置
Scanner-->>REST : 过滤器配置对象
REST-->>WebUI : JSON响应
WebUI-->>Client : 当前过滤器状态
Client->>WebUI : POST /api/ble/filter
WebUI->>REST : 转发请求
REST->>REST : 解析JSON请求体
REST->>Scanner : ble_scanner_set_filter()
Scanner->>Filter : 更新过滤器配置
Filter-->>Scanner : 确认更新
Scanner-->>REST : 操作成功
REST-->>WebUI : {"ok" : true}
WebUI-->>Client : 成功响应

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

详细组件分析

GET /api/ble/filter - 获取过滤器配置

GET方法用于查询当前的BLE过滤器配置状态：

响应格式

{
  "name": "字符串",
  "rssi": 整数,
  "mac": "AA:BB:CC:DD:EE:FF",
  "mac_enabled": 布尔值
}

字段说明

字段名	类型	描述	默认值
name	string	设备名称包含过滤器	空字符串
rssi	integer	RSSI阈值（dBm）	0
mac	string	MAC地址过滤器	空字符串
mac_enabled	boolean	MAC过滤器是否启用	false

实现流程

flowchart TD
Start([接收GET请求]) --> GetFilter[调用ble_scanner_get_filter]
GetFilter --> CreateJSON[创建JSON响应]
CreateJSON --> AddName[添加name字段]
AddName --> AddRSSI[添加rssi字段]
AddRSSI --> CheckMAC[检查MAC过滤器状态]
CheckMAC --> FormatMAC[格式化MAC地址]
FormatMAC --> AddMAC[添加mac字段]
AddMAC --> AddEnabled[添加mac_enabled字段]
AddEnabled --> SendResponse[发送JSON响应]
SendResponse --> End([完成])

图表来源 - webui_server.c

章节来源 - webui_server.c

POST /api/ble/filter - 设置过滤器参数

POST方法用于配置BLE过滤器参数：

请求格式

{
  "name": "设备名称过滤器",
  "rssi": -60,
  "mac": "AA:BB:CC:DD:EE:FF"
}

参数解析逻辑

flowchart TD
Start([接收POST请求]) --> ParseJSON[解析JSON请求体]
ParseJSON --> CheckName[检查name字段]
CheckName --> ParseName{存在且为字符串?}
ParseName --> |是| SetName[设置name过滤器]
ParseName --> |否| CheckRSSI[检查rssi字段]
SetName --> CheckRSSI
CheckRSSI --> ParseRSSI{存在且为数字?}
ParseRSSI --> |是| SetRSSI[设置RSSI过滤器]
ParseRSSI --> |否| CheckMAC[检查mac字段]
SetRSSI --> CheckMAC
CheckMAC --> ParseMAC{存在且为有效MAC?}
ParseMAC --> |是| SetMAC[设置MAC过滤器]
ParseMAC --> |否| ApplyFilter[应用过滤器]
SetMAC --> ApplyFilter
ApplyFilter --> SaveFilter[调用ble_scanner_set_filter]
SaveFilter --> Success[返回成功响应]
Success --> End([完成])

图表来源 - webui_server.c

章节来源 - webui_server.c

过滤器生效机制

BLE过滤器在设备发现时实时生效：

过滤算法

flowchart TD
DeviceFound[设备发现] --> CheckRSSI[RSSI过滤检查]
CheckRSSI --> RSSIValid{RSSI >= 阈值?}
RSSIValid --> |否| RejectDevice[拒绝设备]
RSSIValid --> |是| CheckName[名称过滤检查]
CheckName --> NameValid{名称匹配?}
NameValid --> |否| RejectDevice
NameValid --> |是| CheckMAC[MAC过滤检查]
CheckMAC --> MACValid{MAC匹配?}
MACValid --> |否| RejectDevice
MACValid --> |是| AcceptDevice[接受设备]
AcceptDevice --> UpdateList[更新设备列表]
RejectDevice --> End([结束])
UpdateList --> End

图表来源 - ble_scanner.c

过滤优先级

1. RSSI过滤：最严格的过滤条件
2. 名称过滤：部分字符串匹配
3. MAC过滤：精确地址匹配

章节来源 - ble_scanner.c

依赖关系分析

BLE过滤器API的依赖关系如下：

graph TB
subgraph "外部依赖"
cJSON[cJSON库]
ESP-IDF[ESP-IDF框架]
end
subgraph "内部组件"
WebUI[WebUI服务器]
REST[REST API]
Scanner[BLE扫描器]
Filter[过滤器引擎]
end
subgraph "硬件接口"
HCI[HCI传输]
Config[配置管理]
end
WebUI --> REST
REST --> Scanner
REST --> Filter
Scanner --> HCI
Filter --> Scanner
WebUI --> Config
REST --> Config
Scanner --> ESP-IDF
REST --> ESP-IDF
WebUI --> cJSON
REST --> cJSON

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

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

性能考虑

内存管理

• JSON解析使用动态内存分配，最大缓冲区大小为256字节
• 设备列表使用静态数组避免堆栈溢出
• 过滤器配置使用结构体直接传递

处理效率

• 过滤检查在设备发现时实时执行
• 使用位操作和内存比较优化性能
• 最大设备数量限制为20个

并发安全

• 设备列表访问使用互斥锁保护
• 过滤器配置更新原子性操作
• 异步事件处理避免阻塞

故障排除指南

常见错误及解决方案

错误类型	错误码	可能原因	解决方案
JSON解析错误	400 Bad Request	无效的JSON格式	检查请求体格式
MAC地址格式错误	400 Bad Request	MAC地址格式不正确	确保使用AA:BB:CC:DD:EE:FF格式
内存不足	500 Internal Server Error	JSON解析内存不足	减少请求体大小
设备不存在	404 Not Found	设备未被发现	确保设备在范围内

调试建议

1. 启用调试日志：检查ESP_LOG输出
2. 验证网络连接：确保WebUI服务器正常运行
3. 测试过滤器：使用简单过滤条件进行测试
4. 监控内存使用：注意内存泄漏问题

章节来源 - webui_server.c

结论

BLE过滤器API为ESP32-S3 BLE网关提供了灵活而强大的设备过滤功能。通过简单的HTTP接口，用户可以轻松配置复杂的过滤规则，包括多条件组合过滤。该API设计合理，实现了高效的实时过滤机制，并提供了完善的错误处理和调试支持。

主要优势包括： - 简单易用的HTTP接口 - 实时过滤生效机制
- 多层次过滤条件支持 - 良好的性能和内存管理 - 完善的错误处理机制

该API为BLE设备管理提供了坚实的基础，支持各种应用场景下的设备筛选需求。