WebSocket API¶

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

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考虑
故障排除指南
结论
附录

简介¶

本文件为 ESP32S3 BLE 网关的 WebSocket API 文档，目标是帮助开发者与集成商理解如何通过 WebSocket 实时接收 BLE 设备状态变化、系统状态变更以及错误通知。文档涵盖以下内容： - 连接建立流程（连接 URL、握手协议、认证方式） - 消息格式与实时数据推送机制 - 客户端连接示例与消息处理思路 - 心跳机制、重连策略与错误处理 - 消息队列管理与并发连接限制

需要特别说明的是：当前仓库中未发现 WebSocket 服务器或客户端实现代码。本文在不虚构现有实现的前提下，基于项目中已有的网络栈（HTTP/HTTPS、SPIFFS、MQTT）与配置信息，提供一套可落地的 WebSocket API 设计方案与接入指南，便于后续扩展。

项目结构¶

该项目采用 ESP-IDF 组件化架构，主要模块如下： - 应用入口与系统初始化：负责引导启动流程、网络模式选择、服务初始化等 - WebUI 服务器：提供静态页面与 REST API - REST API：提供状态查询、设备管理等接口 - 配置与硬件抽象：定义网络端口、LED 引脚、BLE 参数等 - MQTT 客户端：用于远程控制与状态上报 - BLE 网关接口：设备发现、连接、回调注册等

graph TB
A["应用入口<br/>main.c"] --> B["WebUI 服务器<br/>webui_server.c"]
B --> C["REST API 注册<br/>rest_api.c"]
A --> D["BLE 网关接口<br/>ble_gateway.h"]
A --> E["MQTT 客户端<br/>gw_mqtt.c"]
A --> F["全局配置<br/>config.h"]
B --> G["静态页面<br/>data/*.html"]

图表来源 - main.c - webui_server.c - rest_api.c - config.h - ble_gateway.h - gw_mqtt.c

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

核心组件¶

全局配置（端口、网络参数等）
WebUI 默认端口：80
WebSocket 端口：81（预留）
最大客户端数：4（WebUI）
WebUI 服务器
基于 ESP-IDF httpd 启动，支持静态文件与 REST API
提供 /api/status、/api/devices 等接口
REST API
提供状态查询、设备列表、扫描控制等接口
BLE 网关接口
设备结构体、扫描/连接/断开、设备回调注册等
MQTT 客户端
支持鉴权、心跳、缓冲区大小等配置

章节来源 - config.h - webui_server.c - rest_api.c - ble_gateway.h - gw_mqtt.c

架构总览¶

下图展示从浏览器到 BLE 网关的整体数据流，包括 HTTP/WebSocket 接入层、BLE 状态采集层与消息分发层。

graph TB
subgraph "客户端"
W["浏览器/移动端"]
end
subgraph "接入层"
H["HTTP/HTTPS 服务器<br/>WebUI + REST API"]
WS["WebSocket 服务器<br/>待实现"]
end
subgraph "业务层"
BG["BLE 网关接口<br/>设备发现/连接"]
CFG["配置管理<br/>NVS/SPIFFS"]
end
subgraph "消息与状态"
MQ["MQTT 客户端<br/>远程控制/订阅"]
ST["系统状态<br/>内存/网络/设备数"]
end
W --> H
W --> WS
H --> BG
WS --> BG
BG --> ST
BG --> MQ
H --> CFG
WS --> CFG

图表来源 - webui_server.c - rest_api.c - ble_gateway.h - gw_mqtt.c - config.h

详细组件分析¶

WebSocket 连接与握手¶

连接 URL
WebSocket 端点：ws://:81/ws
若启用 TLS，则使用 wss://
握手协议
使用标准 WebSocket 协议，版本 13
可选子协议：ble-status、gateway-events
认证方式
令牌认证：请求头 Authorization: Bearer
或 Cookie 认证：登录后由 WebUI 会话维持
并发连接限制
建议最大连接数：4（与 WebUI 最大客户端一致）

章节来源 - config.h

消息格式与推送机制¶

消息类型
系统状态更新：包含网关标识、固件版本、运行时间、可用堆内存、网络连接状态、接口名、IP 地址、BLE 设备数量
BLE 设备事件：设备发现、连接/断开、RSSI 变化、广告数据片段
错误通知：网络异常、BLE 初始化失败、MQTT 断线、存储空间不足
消息队列管理
使用环形缓冲队列或固定长度数组，按 FIFO 策略丢弃最旧消息以避免阻塞
每个连接维护独立的发送队列，避免跨连接干扰
实时推送触发条件
BLE 设备状态变化（发现/消失/连接/断开）
系统资源阈值触发（低内存、网络切换）
MQTT/网络状态变化

sequenceDiagram
participant C as "客户端"
participant S as "WebSocket 服务器"
participant BG as "BLE 网关接口"
participant ST as "系统状态"
C->>S : "建立 WebSocket 连接"
S->>C : "握手成功，返回连接确认"
BG->>ST : "采集系统状态"
BG->>BG : "扫描/连接状态变更"
BG-->>S : "事件数据"
S-->>C : "实时推送消息"
C->>S : "心跳包"
S-->>C : "心跳响应"

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

客户端连接示例与消息处理¶

连接示例（伪代码思路）
使用浏览器原生 WebSocket API 或第三方库（如 Socket.IO）
设置超时与重连逻辑（指数退避）
订阅特定主题（如 ble-status），解析 JSON 消息
消息处理建议
对系统状态消息：更新 UI 状态卡
对 BLE 事件消息：刷新设备列表与连接状态
对错误消息：弹窗提示并记录日志

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

心跳机制与重连策略¶

心跳机制
保活间隔：建议 30 秒
心跳消息：{"type":"ping","timestamp":}
服务端响应：{"type":"pong","timestamp":}
重连策略
初始延迟：1 秒，最大延迟：60 秒
重连次数上限：10 次
失败原因分类：网络不可达、认证失败、服务端拒绝
资源保护
连接过多时拒绝新连接，返回错误码 429 Too Many Requests

章节来源 - config.h

错误处理与告警¶

常见错误
连接被拒：401 未授权、403 禁止访问
超时：602 网络超时、603 读取超时
资源不足：604 内存不足、605 存储空间不足
错误通知格式
{"type":"error","code":,"message":,"timestamp":}


建议处理
客户端记录错误并提示用户
服务端记录日志并清理资源


章节来源
- webui_server.c
数据模型与字段说明¶

系统状态对象
gateway_id：网关标识
firmware：固件版本
uptime：运行时间（秒）
heap_free：可用堆内存（字节）
network.connected：网络连接状态
network.ip：IP 地址
network.interface：活动接口名称
ble.devices：BLE 设备数量
BLE 设备对象
mac：设备 MAC 地址
name：设备名称
rssi：信号强度（dBm）
connected：是否已连接
last_seen：最后出现时间戳
adv_data：广告数据片段（最多 31 字节）

erDiagram
SYS_STATUS {
string gateway_id
string firmware
number uptime
number heap_free
boolean network_connected
string network_ip
string network_interface
number ble_devices
}
BLE_DEVICE {
string mac
string name
number rssi
boolean connected
number last_seen
bytes adv_data
}
图表来源
- rest_api.c
- ble_gateway.h
依赖关系分析¶

组件耦合
WebUI 服务器依赖 httpd 与 SPIFFS；REST API 依赖 cJSON 与网络管理
BLE 网关接口为纯接口定义，具体实现由底层驱动提供
MQTT 客户端与配置管理解耦，便于独立扩展
外部依赖
ESP-IDF httpd、cJSON、nvs、spiffs、mqtt
潜在循环依赖
当前未发现直接循环依赖；若引入 WebSocket 服务器，需避免与 WebUI 互相依赖

graph LR
WS["webui_server.c"] --> HTTPD["ESP-IDF httpd"]
WS --> SPIFFS["SPIFFS"]
RA["rest_api.c"] --> HTTPD
RA --> CJSON["cJSON"]
BG["ble_gateway.h"] --> |接口| 底层驱动
MQ["gw_mqtt.c"] --> |配置| CFG["配置管理"]
图表来源
- webui_server.c
- rest_api.c
- gw_mqtt.c
章节来源
- webui_server.c
- rest_api.c
- gw_mqtt.c
性能考虑¶

连接并发
建议最大连接数不超过 4，避免抢占 CPU 与内存
消息频率
BLE 事件按需推送，避免高频抖动；可合并同类型事件
内存管理
使用固定缓冲区与池化分配，减少碎片
网络栈
WebUI 与 WebSocket 共享底层网络栈，注意优先级调度

故障排除指南¶

无法连接
检查 IP 与端口是否正确
确认防火墙与路由器策略
认证失败
确认令牌有效性与过期时间
检查会话是否过期
心跳中断
检查网络质量与 NAT 超时设置
调整心跳间隔与超时阈值
消息丢失
检查队列容量与丢弃策略
确认客户端消费速度

章节来源
- webui_server.c
结论¶
本文件提供了在现有 ESP32S3 BLE 网关基础上扩展 WebSocket API 的完整设计与实施指南。尽管当前仓库未包含 WebSocket 实现，但通过复用现有的 WebUI 与 REST API 模块，结合 BLE 网关接口与 MQTT 客户端，可以快速构建一套稳定、可扩展的实时通信能力。建议先完成 WebSocket 服务器的实现与测试，再逐步完善消息格式与错误处理机制。
附录¶

REST API 端点参考
GET /api/status：系统状态
GET /api/devices：BLE 设备列表
POST /api/devices/scan：开始/停止扫描
GET /api/config：获取配置
PUT /api/config：更新配置
页面与交互
仪表盘页面：周期性拉取 /api/status 更新状态卡
设备页面：周期性拉取 /api/devices 更新设备表

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