连接控制接口¶

本文引用的文件 - components/rest_api/rest_api.c - include/rest_api.h - components/ble_gateway/ble_gateway.c - include/ble_gateway.h - main/main.c - include/config.h - components/network_manager/network_manager.c - include/network_manager.h - include/hci_transport.h - old_version/components/ble_scanner/ble_scanner.c - old_version/include/ble_scanner.h

简介¶

本文件面向BLE连接控制API，系统性阐述以下内容： - 查询连接状态：GET /api/ble/connection - 建立/断开连接：POST /api/ble/connection - 连接状态枚举与设备地址格式 - 连接参数配置（间隔、延迟、超时等） - 超时处理、安全断开机制与状态实时监控 - 完整的调用流程与故障排除建议

当前仓库中REST API未直接实现上述两个端点，但底层BLE网关模块已具备连接与断开的函数接口，且配置层提供了连接参数常量。本文将基于现有实现进行扩展设计与说明，并给出可落地的集成方案。

项目结构¶

本项目采用组件化分层架构，REST API位于独立组件中，BLE网关在另一组件内，二者通过HTTP服务器注册路由后协同工作。

graph TB
subgraph "应用入口"
MAIN["main.c<br/>应用启动与服务初始化"]
end
subgraph "网络与配置"
CFG["include/config.h<br/>全局配置与参数常量"]
NETMGR["components/network_manager/network_manager.c<br/>网络状态管理"]
end
subgraph "BLE子系统"
BLEGW["components/ble_gateway/ble_gateway.c<br/>BLE网关核心"]
HCIT["include/hci_transport.h<br/>HCI传输接口"]
end
subgraph "Web服务"
REST["components/rest_api/rest_api.c<br/>REST API实现"]
RESTH["include/rest_api.h<br/>REST API接口"]
end
MAIN --> NETMGR
MAIN --> BLEGW
MAIN --> REST
REST --> BLEGW
BLEGW --> HCIT
MAIN --> CFG

图表来源 - main/main.c - components/rest_api/rest_api.c - components/ble_gateway/ble_gateway.c - include/hci_transport.h - include/config.h

章节来源 - main/main.c - components/rest_api/rest_api.c - components/ble_gateway/ble_gateway.c - include/hci_transport.h - include/config.h

核心组件¶

REST API模块：负责HTTP路由注册与请求处理，当前未实现“/api/ble/connection”相关端点，需扩展。
BLE网关模块：提供连接/断开接口，封装底层HCI命令发送与状态管理。
配置模块：定义BLE连接参数（如连接间隔、超时等）。
网络管理模块：提供网络状态，保障API可用性。
主程序：协调各模块初始化与运行。

章节来源 - components/rest_api/rest_api.c - components/ble_gateway/ble_gateway.c - include/config.h - components/network_manager/network_manager.c

架构总览¶

下图展示从HTTP请求到BLE连接控制的端到端流程，以及关键数据结构与回调关系。

sequenceDiagram
participant Client as "客户端"
participant HTTP as "HTTP服务器"
participant REST as "REST API处理器"
participant BLE as "BLE网关"
participant HCI as "HCI传输层"
Client->>HTTP : "POST /api/ble/connection"
HTTP->>REST : "路由分发"
REST->>REST : "解析请求体目标MAC/动作"
REST->>BLE : "ble_gateway_connect()/ble_gateway_disconnect()"
BLE->>HCI : "发送HCI命令LE Create Connection/Disconnect"
HCI-->>BLE : "返回事件/状态"
BLE-->>REST : "更新内部状态"
REST-->>Client : "返回结果成功/失败"
Note over Client,BLE : "GET /api/ble/connection用于查询当前连接状态"

图表来源 - components/rest_api/rest_api.c - components/ble_gateway/ble_gateway.c - include/hci_transport.h

详细组件分析¶

REST API扩展：/api/ble/connection¶

当前已注册的API包括状态查询、设备列表、扫描启停、配置读取与更新等，但未包含连接控制端点。
建议新增：
GET /api/ble/connection：返回当前连接状态与已连接设备列表
POST /api/ble/connection：建立或断开指定设备连接
请求体字段建议：
mac：目标设备MAC地址（十六进制字符串，格式如 AA:BB:CC:DD:EE:FF）
action：操作类型（connect/disconnect）
响应体字段建议：
status：操作结果（ok/error）
message：简要描述
connected：当前连接状态布尔值
devices：连接设备数组（含mac/name/rssi/connected）

章节来源 - components/rest_api/rest_api.c - include/ble_gateway.h

BLE网关：连接与断开¶

接口概览：
连接：ble_gateway_connect(mac)
断开：ble_gateway_disconnect(mac)
设备信息：ble_gateway_get_devices(...)、ble_gateway_get_device_count()
数据结构：
设备结构体包含MAC、名称、RSSI、是否已连接、连接句柄等字段
实现现状：
函数声明存在，但具体HCI命令发送逻辑标记为TODO，尚未实现
参考旧版本实现（可迁移）：
连接流程：停止扫描 → 发送LE Create Connection命令 → 等待连接完成事件
断开流程：发送Disconnect命令 → 监听断开完成事件

flowchart TD
Start(["进入连接流程"]) --> StopScan["停止BLE扫描"]
StopScan --> BuildCmd["构造LE Create Connection命令"]
BuildCmd --> SendCmd["发送HCI命令"]
SendCmd --> WaitEvt{"等待事件"}
WaitEvt --> |连接成功| SetConn["设置连接状态为已连接"]
WaitEvt --> |连接失败| SetDisc["设置连接状态为断开"]
SetConn --> End(["结束"])
SetDisc --> End

图表来源 - components/ble_gateway/ble_gateway.c - old_version/components/ble_scanner/ble_scanner.c

章节来源 - components/ble_gateway/ble_gateway.c - include/ble_gateway.h - old_version/components/ble_scanner/ble_scanner.c

连接状态与设备地址¶

连接状态枚举（参考旧版本）：
disconnected、connecting、connected
设备地址格式：
MAC地址为6字节，建议以冒号分隔的大写十六进制字符串表示（AA:BB:CC:DD:EE:FF）
地址类型：public或random（由设备广播决定）
设备信息结构体字段：
mac、addr_type、name、rssi、adv_data、adv_len、last_seen、connected、conn_handle

章节来源 - include/ble_gateway.h - old_version/include/ble_scanner.h

连接参数配置¶

参数来源（配置头文件）：
最大连接数、扫描间隔/窗口、连接间隔范围、连接超时、延迟等
关键参数含义：
连接间隔最小/最大：影响功耗与延迟
连接超时：链路空闲检测与断开阈值
连接延迟：允许的空闲周期数，降低能耗
使用建议：
在POST请求中支持动态调整（如通过配置管理模块持久化），或在初始化阶段统一设置

章节来源 - include/config.h

超时处理与安全断开¶

超时策略：
建立连接时等待Command Status/Complete事件，超时则判定失败并清理状态
连接建立后，若长时间无活动，依据超时参数触发断开
安全断开机制：
显式发送Disconnect命令，避免强制复位
监听Disconnection Complete事件，确保资源释放
状态一致性：
通过互斥量保护设备列表与连接状态，避免竞态

章节来源 - old_version/components/ble_scanner/ble_scanner.c - old_version/components/ble_scanner/ble_scanner.c

实时监控¶

设备列表与连接状态：
提供GET /api/devices返回设备列表，其中包含connected字段
可结合WebSocket或轮询方式推送状态变更
网络状态：
GET /api/status返回网络连通性，便于判断API可用性

章节来源 - components/rest_api/rest_api.c - components/rest_api/rest_api.c

依赖关系分析¶

REST API依赖BLE网关与网络管理模块，用于执行业务逻辑与返回系统状态
BLE网关依赖HCI传输层，用于与nRF52833通信
主程序负责初始化顺序与任务调度

graph LR
REST["REST API"] --> BLE["BLE网关"]
REST --> NET["网络管理"]
BLE --> HCI["HCI传输"]
MAIN["主程序"] --> REST
MAIN --> BLE
MAIN --> NET
MAIN --> CFG["配置"]

图表来源 - main/main.c - components/rest_api/rest_api.c - components/ble_gateway/ble_gateway.c - include/hci_transport.h

章节来源 - main/main.c - components/rest_api/rest_api.c - components/ble_gateway/ble_gateway.c - include/hci_transport.h

性能考虑¶

扫描与连接冲突：连接前应停止扫描，避免资源竞争
事件驱动：使用事件回调处理连接/断开完成，减少轮询开销
内存与并发：设备列表访问使用互斥量保护；合理设置任务栈大小与优先级
参数优化：根据应用场景调整连接间隔与超时，平衡功耗与实时性

故障排除指南¶

API不可用：
检查网络状态（GET /api/status），确认ETH/WiFi已连接
确认REST API已注册路由
连接失败：
确认目标MAC格式正确（AA:BB:CC:DD:EE:FF）
检查设备是否处于可连接状态（RSSI、广播类型）
查看连接超时与参数配置是否合理
断不开：
确认已发送Disconnect命令并监听Disconnection Complete事件
检查连接句柄有效性
资源泄露：
确保事件回调中释放资源，互斥量使用成对出现

章节来源 - components/network_manager/network_manager.c - components/rest_api/rest_api.c - old_version/components/ble_scanner/ble_scanner.c

结论¶

当前REST API未实现“/api/ble/connection”，需按本文建议扩展
BLE网关已提供连接/断开接口，可作为实现基础
通过合理的超时与断开机制、参数配置与实时监控，可构建稳定可靠的BLE连接控制能力

附录¶

API定义与示例（路径引用）¶

GET /api/ble/connection
功能：查询当前连接状态与已连接设备列表
响应字段：status、connected、devices[]
参考实现位置：components/rest_api/rest_api.c
POST /api/ble/connection
请求体字段：mac、action（connect/disconnect）
响应字段：status、message、connected、devices[]
参考实现位置：components/rest_api/rest_api.c
连接状态枚举
参考：old_version/include/ble_scanner.h
设备地址格式
MAC字符串格式：AA:BB:CC:DD:EE:FF
参考：components/rest_api/rest_api.c
连接参数配置
参考：include/config.h
连接建立与断开流程
参考：old_version/components/ble_scanner/ble_scanner.c
参考：old_version/components/ble_scanner/ble_scanner.c