BLE连接管理API¶
本文档引用的文件 - webui_server.c - ble_scanner.h - ble_scanner.c - index.html - main.c - ble_gateway.h - ble_gateway.c
目录¶
简介¶
BLE连接管理API是ESP32-S3 BLE网关系统的核心功能模块，负责管理BLE设备的连接状态和控制操作。该API提供了两个主要端点：/api/ble/connection用于查询当前连接状态和执行连接控制操作。
本API支持以下核心功能： - 查询当前BLE连接状态（连接状态、连接句柄、对端设备地址） - 建立新的BLE连接 - 断开现有的BLE连接 - 支持多种地址类型的BLE设备连接
项目结构¶
BLE连接管理API位于WebUI服务器组件中，与BLE扫描器和网关核心组件协同工作：
graph TB
subgraph "WebUI服务器层"
API[REST API端点]
Handler[HTTP处理器]
end
subgraph "BLE管理层"
Scanner[BLE扫描器]
Gateway[BLE网关]
end
subgraph "硬件接口层"
HCI[HCI传输层]
Transport[传输接口]
end
subgraph "硬件设备"
ESP32S3[ESP32-S3控制器]
nRF52833[nRF52833 BLE控制器]
end
API --> Handler
Handler --> Scanner
Handler --> Gateway
Scanner --> HCI
Gateway --> HCI
HCI --> Transport
Transport --> nRF52833
nRF52833 --> ESP32S3图表来源 - webui_server.c - ble_scanner.c
章节来源 - webui_server.c - main.c
核心组件¶
连接状态管理¶
BLE连接状态通过枚举类型进行管理，包含三种基本状态：
| 状态值 | 状态名称 | 描述 |
|---|---|---|
| 0 | DISCONNECTED | 未连接状态 |
| 1 | CONNECTING | 连接中状态 |
| 2 | CONNECTED | 已连接状态 |
连接信息结构¶
连接信息结构体包含完整的连接元数据：
classDiagram
class ble_connection_t {
+uint16_t conn_handle
+uint8_t peer_addr[6]
+uint8_t peer_addr_type
+ble_conn_state_t state
+uint16_t conn_interval
+uint16_t conn_latency
+uint16_t supervision_timeout
}
class ble_conn_state_t {
<<enumeration>>
DISCONNECTED
CONNECTING
CONNECTED
}
class ble_addr_type_t {
<<enumeration>>
PUBLIC
RANDOM
PUBLIC_ID
RANDOM_ID
}
ble_connection_t --> ble_conn_state_t : "使用"
ble_connection_t --> ble_addr_type_t : "使用"图表来源 - ble_scanner.h
章节来源 - ble_scanner.h
架构概览¶
BLE连接管理API采用分层架构设计，确保了良好的模块化和可维护性：
sequenceDiagram
participant Client as 客户端
participant API as REST API
participant Handler as HTTP处理器
participant Scanner as BLE扫描器
participant HCI as HCI传输层
Note over Client,API : GET /api/ble/connection 查询连接状态
Client->>API : GET /api/ble/connection
API->>Handler : 路由到连接状态处理器
Handler->>Scanner : 获取连接信息
Scanner->>Scanner : 读取连接状态
Scanner-->>Handler : 返回连接信息
Handler-->>Client : JSON响应
Note over Client,API : POST /api/ble/connection 连接控制
Client->>API : POST /api/ble/connection
API->>Handler : 路由到连接控制处理器
Handler->>Handler : 解析JSON请求体
alt action = connect
Handler->>Scanner : 执行连接操作
Scanner->>HCI : 发送连接命令
else action = disconnect
Handler->>Scanner : 执行断开操作
Scanner->>HCI : 发送断开命令
end
Handler-->>Client : 操作结果图表来源 - webui_server.c - ble_scanner.c
详细组件分析¶
GET /api/ble/connection 端点¶
功能描述¶
GET端点用于查询当前BLE连接状态，返回包括连接状态、连接句柄和对端设备地址的完整信息。
请求格式¶
- 方法: GET
- URL:
/api/ble/connection - 内容类型: 无（无请求体）
响应格式¶
响应为JSON格式，包含以下字段：
| 字段名 | 类型 | 描述 | 示例值 |
|---|---|---|---|
| state | number | 连接状态（0=未连接，1=连接中，2=已连接） | 2 |
| handle | number | 连接句柄（16位整数） | 1234 |
| peer_addr | string | 对端设备MAC地址（AA:BB:CC:DD:EE:FF格式） | "AC:23:3F:4D:5E:6F" |
响应示例¶
错误处理¶
- 当没有设备连接时，
peer_addr字段为空字符串 - 状态码: 200 OK
章节来源 - webui_server.c - ble_scanner.c
POST /api/ble/connection 端点¶
功能描述¶
POST端点用于控制BLE连接的建立或断开操作。通过JSON请求体中的action参数指定操作类型。
请求格式¶
- 方法: POST
- URL:
/api/ble/connection - 内容类型: application/json
请求体参数¶
| 参数名 | 类型 | 必需 | 描述 | 示例值 |
|---|---|---|---|---|
| action | string | 是 | 操作类型：connect 或 disconnect |
"connect" |
| mac | string | 否 | 目标设备MAC地址（连接时必需） | "AC:23:3F:4D:5E:6F" |
| addr_type | number | 否 | 设备地址类型（连接时可选，默认0） | 0 |
地址类型定义： - 0: 公共地址（Public Address） - 1: 随机地址（Random Address） - 2: 公共标识地址（Public Identity Address） - 3: 随机标识地址（Random Identity Address）
成功响应¶
成功时返回JSON对象：
错误响应¶
可能的错误情况： - 400 Bad Request: 无效的JSON格式或缺少必需参数 - 404 Not Found: 设备未找到（连接时） - 500 Internal Server Error: 操作失败
章节来源 - webui_server.c - ble_scanner.h
连接控制流程¶
flowchart TD
Start([开始连接控制]) --> ParseJSON["解析JSON请求体"]
ParseJSON --> CheckAction{"检查action参数"}
CheckAction --> |connect| CheckParams["验证必需参数"]
CheckAction --> |disconnect| Disconnect["执行断开操作"]
CheckParams --> ValidateMAC["验证MAC地址格式"]
ValidateMAC --> ValidMAC{"MAC地址有效?"}
ValidMAC --> |否| SendError["发送错误响应"]
ValidMAC --> |是| ParseAddr["解析地址类型"]
ParseAddr --> SendConnect["发送连接命令"]
SendConnect --> WaitEvent["等待连接事件"]
WaitEvent --> Connected{"连接成功?"}
Connected --> |是| Success["返回成功响应"]
Connected --> |否| Fail["返回失败响应"]
Disconnect --> HCICommand["发送断开命令"]
HCICommand --> Success
SendError --> End([结束])
Success --> End
Fail --> End图表来源 - webui_server.c - ble_scanner.c
章节来源 - webui_server.c
依赖关系分析¶
BLE连接管理API依赖于多个核心组件，形成了清晰的依赖层次：
graph TB
subgraph "API层"
API[REST API端点]
end
subgraph "处理层"
ConnHandler[连接处理器]
StatusHandler[状态处理器]
end
subgraph "业务逻辑层"
BLEScanner[BLE扫描器]
BLEGateway[BLE网关]
end
subgraph "硬件抽象层"
HCITransport[HCI传输]
ConfigManager[配置管理]
end
subgraph "硬件层"
ESP32S3[ESP32-S3]
nRF52833[nRF52833]
end
API --> ConnHandler
API --> StatusHandler
ConnHandler --> BLEScanner
StatusHandler --> BLEScanner
BLEScanner --> HCITransport
BLEGateway --> HCITransport
HCITransport --> nRF52833
nRF52833 --> ESP32S3图表来源 - webui_server.c - main.c
章节来源 - webui_server.c - main.c
性能考虑¶
连接状态查询优化¶
- 使用轻量级JSON序列化避免内存分配
- 直接访问内部连接状态结构体减少复制开销
- MAC地址格式化采用预分配缓冲区
连接控制性能¶
- 连接建立前自动停止BLE扫描以避免冲突
- 异步处理HCI命令避免阻塞主线程
- 连接状态变更通过回调机制通知
内存管理¶
- 静态缓冲区用于JSON响应生成
- 连接信息结构体直接传递避免额外拷贝
- 及时释放cJSON对象防止内存泄漏
故障排除指南¶
常见问题及解决方案¶
连接失败¶
症状: POST请求返回失败，状态仍为未连接 可能原因: - 目标设备不在范围内 - MAC地址格式不正确 - 设备不支持连接请求
解决步骤: 1. 验证设备是否在扫描范围内 2. 检查MAC地址格式是否为AA:BB:CC:DD:EE:FF 3. 确认设备支持BLE连接
断开连接异常¶
症状: 调用断开操作后连接状态仍然显示已连接 可能原因: - HCI命令发送失败 - 设备主动断开连接 - 状态更新延迟
解决步骤: 1. 检查网络连接状态 2. 重新查询连接状态 3. 稍后重试断开操作
并发连接问题¶
症状: 多个客户端同时操作连接导致状态混乱 解决步骤: 1. 实现连接状态锁机制 2. 在连接建立过程中暂停扫描 3. 使用原子操作更新连接状态
章节来源 - ble_scanner.c
结论¶
BLE连接管理API为ESP32-S3 BLE网关提供了完整的连接控制能力。通过清晰的REST API设计和健壮的状态管理机制，用户可以轻松地查询连接状态和控制BLE设备的连接行为。
主要特性¶
- 简洁的API设计: 两个核心端点满足所有连接管理需求
- 完整的状态信息: 提供连接状态、句柄和设备地址的完整视图
- 灵活的连接控制: 支持多种地址类型和连接策略
- 健壮的错误处理: 提供详细的错误信息和状态反馈
- 高性能实现: 优化的内存管理和异步处理机制
未来改进方向¶
- 添加连接超时机制
- 实现连接重试策略
- 增加连接统计信息
- 支持批量连接操作
- 添加连接日志记录
该API为构建更复杂的BLE网关应用奠定了坚实的基础，支持从简单的设备连接到复杂的企业级部署场景。