系统控制API¶

本文档引用的文件 - main.c - webui_server.c - rest_api.c - config.h - led_indicator.c - led_indicator.h

目录¶

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

简介¶

本文件详细描述了ESP32-S3 BLE网关系统的系统控制API，特别是/api/reboot端点的POST方法。该API允许远程重启ESP32设备，是系统管理和维护的重要功能。文档涵盖了API的完整规范、实现细节、最佳实践以及故障排除指南。

项目结构¶

ESP32-S3 BLE网关采用模块化架构设计，主要包含以下核心组件：

graph TB
subgraph "应用层"
Main[app_main入口]
WebUI[WebUI服务器]
REST[REST API]
end
subgraph "硬件抽象层"
LED[LED指示器]
Config[配置管理]
end
subgraph "网络层"
HTTP[HTTP服务器]
SPIFFS[SPIFFS存储]
end
Main --> WebUI
WebUI --> REST
REST --> HTTP
WebUI --> SPIFFS
Main --> LED
Main --> Config

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

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

核心组件¶

WebUI服务器组件¶

WebUI服务器是整个系统的核心HTTP服务，负责处理所有REST API请求和静态文件服务。

主要特性： - 基于ESP-IDF HTTP服务器框架 - 支持多客户端并发访问（最大4个连接） - 集成REST API处理器 - SPIFFS文件系统支持

REST API组件¶

REST API模块提供了完整的HTTP接口，包括系统控制、状态查询、配置管理等功能。

API端点分类： - 系统控制：/api/reboot - 状态查询：/api/status, /api/devices - 配置管理：/api/config - 设备扫描：/api/devices/scan

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

架构概览¶

系统采用分层架构设计，确保各组件职责清晰、耦合度低：

sequenceDiagram
participant Client as 客户端
participant HTTP as HTTP服务器
participant REST as REST API
participant System as 系统内核
participant ESP as ESP32内核
Client->>HTTP : POST /api/reboot
HTTP->>REST : 调用api_reboot_handler
REST->>REST : 设置响应头和JSON数据
REST->>System : vTaskDelay(500ms)
REST->>ESP : esp_restart()
ESP-->>Client : 返回重启确认
Note over ESP : 系统立即重启

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

详细组件分析¶

/api/reboot 端点实现¶

API规范¶

端点定义： - URL: /api/reboot - 方法: POST - 内容类型: application/json - 认证: 无（基于硬件限制）

请求格式：

POST /api/reboot HTTP/1.1
Host: 192.168.1.100
Content-Type: application/json
Content-Length: 0

(empty body)

响应格式：

{
  "success": true,
  "message": "Rebooting..."
}

响应状态码： - 200 OK: 重启请求已接受 - 500 Internal Server Error: 服务器内部错误

实现细节¶

flowchart TD
Start([收到POST请求]) --> SetHeader["设置响应头<br/>Content-Type: application/json"]
SetHeader --> SendResponse["发送JSON响应"]
SendResponse --> Delay["延迟500ms<br/>vTaskDelay(500)"]
Delay --> Restart["调用esp_restart()"]
Restart --> End([重启完成])
SendResponse --> ErrorCheck{"检查发送错误"}
ErrorCheck --> |有错误| ErrorHandler["返回错误响应"]
ErrorCheck --> |无错误| Delay

图表来源 - webui_server.c

关键实现要点¶

异步响应机制：API先发送响应，然后执行重启操作
延迟处理：500ms延迟确保客户端收到响应
直接重启：使用ESP-IDF的esp_restart()函数
无参数要求：POST请求体为空，无需额外参数

章节来源 - webui_server.c

系统重启流程¶

状态变化序列¶

stateDiagram-v2
[*] --> 运行中
运行中 --> 准备重启 : 接收/reboot请求
准备重启 --> 发送响应 : 设置HTTP响应
发送响应 --> 延迟处理 : vTaskDelay(500ms)
延迟处理 --> 系统重启 : esp_restart()
系统重启 --> [*] : 设备重启
note right of 准备重启
LED指示器可能闪烁
网络连接断开
end note

重启前后的LED状态¶

重启前状态： - 系统LED（蓝色）：常亮或慢速闪烁 - 网络LED（黄色）：根据连接状态闪烁 - BLE LED（绿色）：根据设备连接状态闪烁

重启后状态： - 所有LED指示器重置 - 系统LED开始快速闪烁 - 等待初始化完成

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

依赖关系分析¶

组件依赖图¶

graph TB
subgraph "外部依赖"
ESP_IDF[ESP-IDF框架]
FreeRTOS[FreeRTOS]
cJSON[cJSON库]
end
subgraph "核心组件"
WebUI[WebUI服务器]
REST[REST API]
HTTP[HTTP服务器]
SPIFFS[SPIFFS文件系统]
end
subgraph "系统服务"
LED[LED指示器]
Config[配置管理]
Network[网络管理]
end
ESP_IDF --> WebUI
FreeRTOS --> WebUI
cJSON --> REST
WebUI --> REST
WebUI --> HTTP
WebUI --> SPIFFS
REST --> Network
REST --> Config
WebUI --> LED
Main --> LED

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

关键依赖关系¶

ESP-IDF集成：所有HTTP处理基于ESP-IDF的HTTP服务器框架
FreeRTOS任务调度：重启操作在独立的任务上下文中执行
cJSON库：用于JSON数据的解析和生成
SPIFFS文件系统：WebUI静态文件的存储和访问

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

性能考虑¶

并发处理能力¶

最大客户端数：4个并发连接
URI处理器数量：20个URI处理器
任务栈大小：8KB堆栈空间
内存使用：JSON响应缓冲区大小适中

响应时间优化¶

异步响应：不等待重启完成就返回响应
最小延迟：500ms延迟确保客户端接收响应
直接重启：避免复杂的重启前清理操作

内存管理¶

静态分配：HTTP服务器配置使用静态内存
动态分配：JSON数据使用动态内存分配
内存监控：系统启动时显示可用堆内存

故障排除指南¶

常见问题及解决方案¶

1. 重启请求无响应¶

症状： 客户端发送POST请求后长时间无响应

可能原因： - 网络连接中断 - HTTP服务器未正确启动 - 端口被占用

解决步骤： 1. 检查设备IP地址和网络连通性 2. 验证WebUI服务器是否正常运行 3. 确认端口80未被其他服务占用

2. 重启后无法连接¶

症状： 设备重启后无法通过网络访问

可能原因： - 网络配置丢失 - DHCP服务未启动 - 静态IP配置冲突

解决步骤： 1. 等待设备完全启动（约30秒） 2. 检查网络LED指示器状态 3. 重新配置网络设置

3. LED指示异常¶

症状： 重启前后LED状态不符合预期

可能原因： - LED驱动电路故障 - GPIO配置错误 - 电源供应不稳定

解决步骤： 1. 检查LED连接和电源 2. 验证GPIO配置参数 3. 测试LED指示器功能

诊断工具¶

系统状态查询¶

使用/api/status端点获取系统当前状态：

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

章节来源 - rest_api.c

结论¶

系统控制API为ESP32-S3 BLE网关提供了简单而有效的远程重启功能。通过精心设计的架构和实现，该API确保了：

可靠性：异步响应机制确保客户端始终能收到确认
安全性：基于硬件限制的访问控制
易用性：简单的JSON接口，无需复杂认证
效率：最小化的延迟和资源消耗

建议在生产环境中： - 使用稳定的网络连接进行重启操作 - 在维护窗口期间执行重启操作 - 监控重启后的系统状态 - 定期备份配置数据

该API为系统管理和维护提供了重要的基础设施支持，是构建可靠物联网解决方案的关键组件。