系统状态接口¶

本文档引用的文件 - main.c - rest_api.c - rest_api.h - network_manager.c - network_manager.h - ble_gateway.c - config_manager.h - config.h - index.html

目录¶

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

简介¶

本文档详细说明了ESP32S3 BLE网关系统的状态查询API接口。该接口提供系统运行时的关键状态信息，包括系统版本、运行时间、内存状态、网络连接状态、BLE扫描状态等。通过GET /api/status端点，客户端可以实时监控网关的运行状况。

项目结构¶

该项目采用模块化架构设计，主要包含以下核心组件：

graph TB
subgraph "应用层"
Main[主程序入口]
WebUI[Web界面]
end
subgraph "服务层"
REST[REST API服务]
Network[网络管理器]
BLE[BLE网关]
Config[配置管理器]
end
subgraph "硬件抽象层"
WiFi[WiFi管理器]
ETH[以太网管理器]
HCI[HCI传输层]
end
Main --> REST
WebUI --> REST
REST --> Network
REST --> BLE
REST --> Config
Network --> WiFi
Network --> ETH
BLE --> HCI

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

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

核心组件¶

REST API服务¶

REST API服务负责处理HTTP请求，提供系统状态查询功能。它集成了多个子系统的信息收集和格式化输出。

网络管理器¶

网络管理器负责管理以太网和WiFi连接状态，提供统一的网络状态查询接口。

BLE网关¶

BLE网关负责蓝牙设备的扫描和连接管理，提供设备列表和扫描状态信息。

配置管理器¶

配置管理器提供系统配置信息的访问接口，包括网关标识符和固件版本等。

章节来源 - rest_api.c - network_manager.c - ble_gateway.c

架构概览¶

系统状态查询API的完整架构流程如下：

sequenceDiagram
participant Client as 客户端
participant REST as REST API
participant Network as 网络管理器
participant BLE as BLE网关
participant Config as 配置管理器
Client->>REST : GET /api/status
REST->>Config : 获取网关配置
REST->>Network : 获取网络状态
REST->>BLE : 获取BLE设备数量
REST->>REST : 组装JSON响应
REST-->>Client : 返回系统状态JSON
Note over REST,Client : 响应包含所有系统状态信息

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

详细组件分析¶

GET /api/status 接口规范¶

请求方法和URL¶

方法: GET
路径: /api/status
内容类型: application/json

成功响应格式¶

接口返回标准的JSON格式，包含以下字段：

字段名	类型	描述	示例值
gateway_id	string	网关唯一标识符	"ESP32S3-BLE-Gateway-001"
firmware	string	固件版本号	"1.0.0"
uptime	number	系统运行时间（秒）	12345
heap_free	number	可用堆内存字节	1572864
network	object	网络状态对象	-
network.connected	boolean	网络连接状态	true
network.ip	string	当前IP地址	"192.168.1.100"
network.interface	string	活跃网络接口	"ETH"
ble	object	BLE状态对象	-
ble.devices	number	发现的BLE设备数量	5

错误处理机制¶

HTTP状态码	错误类型	描述	处理建议
200	成功	请求成功执行	正常处理响应数据
404	资源未找到	API端点不存在	检查URL路径是否正确
500	服务器内部错误	服务器处理异常	重试请求或检查服务器日志

响应示例¶

成功响应示例:

{
  "gateway_id": "ESP32S3-BLE-Gateway-001",
  "firmware": "1.0.0",
  "uptime": 12345,
  "heap_free": 1572864,
  "network": {
    "connected": true,
    "ip": "192.168.1.100",
    "interface": "ETH"
  },
  "ble": {
    "devices": 5
  }
}

最小响应示例:

{
  "gateway_id": "ESP32S3-BLE-Gateway-001",
  "firmware": "1.0.0",
  "uptime": 0,
  "heap_free": 0,
  "network": {
    "connected": false,
    "ip": "0.0.0.0",
    "interface": "NONE"
  },
  "ble": {
    "devices": 0
  }
}

数据字段详细说明¶

系统基本信息 - gateway_id: 网关的唯一标识符，用于区分不同的设备实例 - firmware: 当前运行的固件版本号，便于追踪升级状态 - uptime: 系统自启动以来的运行时间（以秒为单位） - heap_free: 当前可用的堆内存大小（以字节为单位）

网络状态信息 - network.connected: 真实的网络连接状态，支持以太网和WiFi两种模式 - network.ip: 当前活跃网络接口的IP地址 - network.interface: 当前使用的网络接口类型（"ETH"或"WIFI"）

BLE状态信息 - ble.devices: 当前扫描到的BLE设备总数

章节来源 - rest_api.c

状态获取实现细节¶

系统版本信息¶

固件版本信息从全局配置头文件中获取，确保版本信息与编译时配置保持一致。

运行时间计算¶

系统运行时间通过ESP-IDF的日志时间戳函数获取，转换为秒级精度的时间值。

内存状态获取¶

可用堆内存大小通过ESP-IDF的内存管理API获取，提供实时的内存使用情况。

网络状态获取¶

网络状态通过网络管理器的统一接口获取，支持多种网络模式的自动切换检测。

BLE扫描状态¶

BLE设备数量通过BLE网关的设备计数接口获取，反映当前的扫描结果。

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

客户端使用指南¶

基本使用示例¶

JavaScript示例:

fetch('/api/status')
  .then(response => response.json())
  .then(data => {
    console.log('网关ID:', data.gateway_id);
    console.log('固件版本:', data.firmware);
    console.log('运行时间:', data.uptime, '秒');
    console.log('可用内存:', data.heap_free, '字节');
    console.log('网络状态:', data.network.connected ? '已连接' : '未连接');
    console.log('IP地址:', data.network.ip);
    console.log('BLE设备数量:', data.ble.devices);
  })
  .catch(error => console.error('请求失败:', error));

Python示例:

import requests
import json

try:
    response = requests.get('http://192.168.1.100/api/status')
    response.raise_for_status()

    status_data = response.json()
    print(f"网关ID: {status_data['gateway_id']}")
    print(f"固件版本: {status_data['firmware']}")
    print(f"运行时间: {status_data['uptime']} 秒")
    print(f"可用内存: {status_data['heap_free']} 字节")

except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")

实时监控实现¶

推荐使用轮询机制实现状态监控，建议的轮询间隔为3-5秒，避免过度频繁的请求影响系统性能。

章节来源 - index.html

依赖关系分析¶

系统状态查询API的依赖关系图：

graph TD
REST[REST API] --> NetworkMgr[网络管理器]
REST --> BLEMgr[BLE网关]
REST --> ConfigMgr[配置管理器]
REST --> ESP32[ESP32系统API]
NetworkMgr --> WiFiMgr[WiFi管理器]
NetworkMgr --> ETHMgr[以太网管理器]
BLEMgr --> HCITrans[HCI传输层]
ESP32 --> FreeRTOS[FreeRTOS内核]
ESP32 --> ESPIDF[ESP-IDF框架]

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

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

性能考虑¶

响应时间优化¶

API调用应在毫秒级别完成，避免阻塞其他网络操作
使用轻量级的数据序列化库减少处理开销
缓存机制：对于不频繁变化的状态信息可考虑本地缓存

内存使用优化¶

动态分配内存时要确保及时释放
使用栈变量而非堆变量存储临时数据
监控内存使用情况，防止内存泄漏

并发处理¶

API处理应支持多客户端并发访问
使用互斥锁保护共享资源
避免长时间持有锁导致的阻塞

故障排除指南¶

常见问题及解决方案¶

1. API响应超时 - 检查网络连接状态 - 验证WebUI服务器是否正常运行 - 确认防火墙设置允许HTTP请求

2. JSON解析错误 - 验证响应内容是否为有效的JSON格式 - 检查网络传输过程中是否有数据损坏 - 确认客户端的JSON解析库版本兼容性

3. 状态信息不准确 - 检查系统时间同步状态 - 验证内存管理器是否正常工作 - 确认网络管理器的回调函数是否正确注册

4. 设备数量显示异常 - 检查BLE扫描功能是否正常启动 - 验证HCI传输层通信状态 - 确认设备过滤配置参数设置正确

调试建议¶

启用调试日志: 1. 在开发环境中启用详细的日志输出 2. 监控API调用的响应时间和错误率 3. 记录异常情况的上下文信息

性能监控: 1. 定期检查内存使用情况 2. 监控CPU使用率和任务调度状态 3. 分析网络带宽使用情况

章节来源 - main.c

结论¶

GET /api/status接口提供了ESP32S3 BLE网关系统的核心状态信息，通过简洁的JSON格式为客户端提供了全面的系统监控能力。该接口设计合理，实现了良好的模块化架构，便于维护和扩展。

接口的主要优势包括： - 实时性: 提供系统运行时的即时状态信息 - 完整性: 覆盖系统各个关键组件的状态 - 易用性: 简洁的JSON格式便于各种编程语言处理 - 可靠性: 完善的错误处理和状态管理机制

建议在生产环境中结合实际需求，合理设置监控频率，并建立完善的告警机制来及时发现和处理系统异常。