设备管理界面¶

本文档引用的文件 - devices.html - index.html - style.css - hci_test.html - main.c - ble_scanner.c - webui_server.c

目录¶

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

简介¶

本文件为ESP32S3 BLE网关的设备管理界面提供全面的前端开发文档。内容涵盖设备列表页面的布局与交互、设备过滤功能、设备详情展示、表格数据渲染机制、过滤器实现逻辑、连接状态管理、对话框弹窗实现、MAC地址格式化与RSSI信号强度显示、设备自动刷新机制、连接状态同步以及用户交互响应等。同时提供过滤条件应用逻辑、数据缓存策略与性能优化建议，帮助开发者快速理解并扩展该界面。

项目结构¶

该仓库包含嵌入式固件与WebUI前端资源两部分： - 嵌入式固件（C/C++）：负责BLE扫描、设备管理、网络与状态上报、WebUI服务端等。 - WebUI前端（HTML/CSS/JS）：提供仪表盘、设备列表、配置与HCITester等页面。

graph TB
subgraph "嵌入式固件"
FW_Main["main.c<br/>系统初始化与任务调度"]
FW_BLE["ble_scanner.c<br/>BLE扫描与设备列表"]
FW_WebUI["webui_server.c<br/>HTTP服务与API端点"]
end
subgraph "WebUI前端"
UI_Devices["devices.html<br/>设备列表页面"]
UI_Index["index.html<br/>仪表盘页面"]
UI_Style["style.css<br/>样式定义"]
UI_HCITest["hci_test.html<br/>HCITester页面"]
end
FW_WebUI --> UI_Devices
FW_WebUI --> UI_Index
FW_WebUI --> UI_HCITest
FW_BLE --> FW_WebUI
FW_Main --> FW_BLE

图表来源 - main.c - ble_scanner.c - webui_server.c - devices.html - index.html - style.css - hci_test.html

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

核心组件¶

设备列表页面（devices.html）
提供开始扫描、停止扫描、清空设备列表的操作按钮。
使用表格展示设备的MAC地址、名称、RSSI、状态与操作列。
通过定时轮询从后端API获取设备数据并动态渲染。
支持连接设备请求。
仪表盘页面（index.html）
展示系统状态、网络状态与BLE状态信息。
定时刷新系统状态数据。
样式文件（style.css）
定义卡片、网格、按钮、表格等通用样式，确保页面一致的视觉风格。
HCITester页面（hci_test.html）
提供HCITester工具，支持命令发送、事件轮询、设备列表展示与解析。
后端WebUI服务（webui_server.c）
提供REST API端点：/api/status、/api/devices、/api/devices/scan等。
负责从BLE扫描模块读取设备数据并序列化为JSON返回给前端。
BLE扫描模块（ble_scanner.c）
实现设备发现、过滤（RSSI、名称、MAC）、设备列表维护与连接状态管理。

章节来源 - devices.html - index.html - style.css - hci_test.html - webui_server.c - ble_scanner.c

架构总览¶

前端通过HTTP请求与嵌入式WebUI服务通信，后端从BLE扫描模块获取设备数据并返回JSON。前端定时刷新设备列表，用户可触发扫描控制与设备连接。

sequenceDiagram
participant Browser as "浏览器"
participant WebUI as "WebUI服务(webui_server.c)"
participant BLE as "BLE扫描(ble_scanner.c)"
Browser->>WebUI : GET /api/devices
WebUI->>BLE : 获取设备列表
BLE-->>WebUI : 设备数组(JSON)
WebUI-->>Browser : JSON响应
Browser->>WebUI : POST /api/devices/scan {enable : true/false}
WebUI->>BLE : 开始/停止扫描
WebUI-->>Browser : {scanning : true/false}
Browser->>WebUI : POST /api/devices/{mac}/connect
WebUI->>BLE : 连接指定设备
WebUI-->>Browser : {"ok" : true/false}

图表来源 - webui_server.c - ble_scanner.c - devices.html

详细组件分析¶

设备列表页面（devices.html）¶

页面布局
顶部导航栏包含“仪表盘”、“设备列表”、“配置”链接。
卡片容器内包含设备表格，表头包含MAC地址、名称、RSSI、状态、操作列。
操作区提供“开始扫描”、“停止扫描”、“清空”按钮。
数据渲染机制
首次加载与每3秒定时刷新调用loadDevices()。
loadDevices()通过fetch('/api/devices')获取JSON数据，遍历设备数组生成表格行。
当设备列表为空时显示提示文本。
RSSI信号强度显示
通过getRssiClass()根据RSSI值返回CSS类名，实现不同强度的颜色区分（弱/中/强）。
用户交互
“开始扫描”、“停止扫描”分别向后端发送POST请求控制扫描启停。
“清空”删除设备列表并立即重新加载。
“连接”按钮向后端发送连接请求。

flowchart TD
Start(["页面加载"]) --> Init["绑定按钮事件<br/>启动定时刷新"]
Init --> Timer["每3秒执行一次"]
Timer --> Fetch["GET /api/devices"]
Fetch --> HasData{"是否有设备?"}
HasData --> |否| Empty["显示空提示"]
HasData --> |是| Render["生成表格行<br/>设置RSSI样式"]
Render --> End(["等待下一次刷新"])
Empty --> End

图表来源 - devices.html - devices.html

章节来源 - devices.html

设备过滤功能¶

前端过滤（devices.html）
当前devices.html未实现前端过滤器UI与逻辑，但后端提供了完整的过滤能力。
后端过滤（webui_server.c + ble_scanner.c）
过滤器字段：名称包含、最小RSSI阈值、MAC地址精确匹配、仅显示有名称设备。
应用逻辑：在设备更新时进行过滤判断，仅对通过过滤器的设备触发回调或返回给前端。
设置方式：通过/api/ble/filter接口GET获取当前过滤器，POST设置新过滤器。

flowchart TD
ApplyFilter["应用过滤器"] --> CheckRSSI["比较RSSI阈值"]
CheckRSSI --> CheckName["检查名称是否包含"]
CheckName --> CheckMAC["检查MAC地址是否匹配"]
CheckMAC --> Pass{"全部通过?"}
Pass --> |是| Include["加入设备列表"]
Pass --> |否| Exclude["忽略设备"]

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

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

设备详情展示¶

devices.html当前未实现设备详情对话框，但具备展示设备基本信息的能力。
如需实现详情对话框：
在表格行点击“详情”按钮时，通过fetch('/api/devices/{mac}')获取设备详细信息。
弹出模态框展示设备属性（MAC、名称、RSSI、连接状态、广告数据解析结果等）。
可结合后端连接状态API同步当前连接状态。

章节来源 - devices.html

设备连接状态管理¶

前端
devices.html提供连接按钮，向后端发送连接请求。
可通过定时刷新同步连接状态并在表格中高亮当前连接设备。
后端
连接状态通过BLE扫描模块维护，并可通过API查询当前连接状态。
连接/断开请求由webui_server.c处理并转发至BLE扫描模块。

sequenceDiagram
participant UI as "设备列表UI"
participant API as "WebUI API"
participant BLE as "BLE扫描模块"
UI->>API : POST /api/devices/{mac}/connect
API->>BLE : 触发连接流程
BLE-->>API : 返回连接结果
API-->>UI : {"ok" : true/false}
UI->>API : GET /api/ble/connection
API->>BLE : 查询连接状态
BLE-->>API : 返回连接状态
API-->>UI : {"state","peer_addr"}

图表来源 - webui_server.c - ble_scanner.c - devices.html

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

MAC地址格式化¶

后端在返回设备列表时，将字节数组地址格式化为标准MAC地址字符串（XX:XX:XX:XX:XX:XX）。
前端直接显示该字符串，无需额外格式化。

章节来源 - webui_server.c

设备自动刷新机制¶

devices.html使用setInterval定期调用loadDevices()，默认3秒刷新一次。
index.html使用setInterval定期调用updateStatus()，默认5秒刷新一次。
建议：
根据网络状况与设备数量调整刷新间隔。
在页面不可见时暂停刷新，可见时恢复，以节省带宽与CPU。

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

用户交互响应¶

扫描控制：开始/停止扫描按钮通过POST请求切换扫描状态。
清空设备：DELETE请求清空设备列表并立即刷新。
连接设备：POST请求发起连接，前端可结合连接状态API确认结果。

章节来源 - devices.html

依赖关系分析¶

前端页面依赖WebUI服务提供的API端点。
WebUI服务依赖BLE扫描模块获取设备数据与状态。
BLE扫描模块依赖硬件传输层（NRF52833 via HCI UART）。

graph LR
DevicesHTML["devices.html"] --> WebUI["webui_server.c"]
IndexHTML["index.html"] --> WebUI
WebUI --> BLEScanner["ble_scanner.c"]
BLEScanner --> Hardware["NRF52833(HCI UART)"]

图表来源 - devices.html - index.html - webui_server.c - ble_scanner.c - main.c

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

性能考虑¶

刷新频率优化
将设备列表刷新间隔从3秒调整为5-10秒，减少网络与CPU压力。
在页面隐藏时暂停刷新，显示时恢复。
数据渲染优化
使用虚拟滚动或分页展示大量设备，避免一次性渲染过多DOM节点。
对RSSI样式计算与字符串拼接进行缓存，减少重复计算。
缓存策略
前端可缓存最近一次设备列表，在刷新失败时回退显示。
后端对设备列表进行去重与限流，避免重复推送。
网络与并发
控制并发请求数量，避免短时间内多次请求导致拥塞。
对错误请求进行重试与退避策略。

故障排除指南¶

设备列表不刷新
检查浏览器控制台是否存在跨域或网络错误。
确认后端WebUI服务已启动且API端点可用。
扫描按钮无效
确认后端BLE扫描模块已初始化成功。
检查NRF52833硬件连接与供电状态。
连接失败
检查目标设备是否在扫描范围内且可连接。
查看后端日志确认连接状态变化。
RSSI显示异常
确认后端返回的RSSI值范围与前端样式映射一致。
检查设备信号强度是否处于正常范围。

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

结论¶

设备管理界面通过简洁的HTML结构与定时轮询实现了设备列表的实时展示与基本交互。后端提供了完善的BLE扫描、过滤与连接管理能力，前端可在此基础上扩展设备详情对话框、更精细的过滤器UI与连接状态同步机制。通过合理的刷新策略与缓存优化，可在保证用户体验的同时提升系统性能与稳定性。