smart-home/CloudAlarmReporter_README.md

ESP32云端报警上报功能实现

功能概述

本功能实现了ESP32设备向云端服务器自动上报报警事件的能力。当ESP32检测到火灾、高温、异常升温等报警时，会自动将报警信息通过HTTP POST请求发送到云端服务器。

核心特性

• ✅ 异步上报: 不阻塞主程序，使用队列+后台任务处理
• ✅ 自动重试: 失败时自动重试，最多3次
• ✅ 幂等去重: 使用sourceEventId防止重复上报
• ✅ 设备鉴权: 使用X-Device-Key头进行设备身份验证
• ✅ 完整集成: 已集成到现有AlarmManager模块

实现架构

1. 核心模块

CloudAlarmReporter (云端报警上报模块)
├── 异步队列处理
├── HTTP客户端封装
├── JSON数据构建
├── 重试机制
└── 设备UID管理

2. 集成点

AlarmManager::addAlarmToHistory()
├── 保存本地历史记录
├── 调用CloudAlarmReporter::reportAlarmAsync()
└── 异步上报到云端

关键文件

新增文件

1. main/Module/CloudAlarmReporter.h - 头文件
2. main/Module/CloudAlarmReporter.cpp - 实现文件
3. test_cloud_alarm_reporter.py - 测试工具

修改文件

1. main/Module/AlarmManager.cpp - 添加云端上报调用
2. main/app_main.cpp - 添加模块初始化

配置参数

云端服务器配置

// 云端服务器URL
static constexpr const char* CLOUD_SERVER_URL = "http://115.190.167.176:36988/device-alarms";

// 设备认证密钥
static constexpr const char* DEVICE_KEY = "39dc753bd0cb19da5050a2f0edf932f851f5b21b90a6d06ecf9a28d81079a0a6";

性能参数

static constexpr int REPORT_QUEUE_SIZE = 20;        // 报警队列大小
static constexpr int HTTP_TIMEOUT_MS = 10000;       // HTTP超时时间
static constexpr int MAX_RETRY_COUNT = 3;           // 最大重试次数
static constexpr int RETRY_DELAY_MS = 2000;         // 重试延迟

API规范

HTTP请求格式

POST /device-alarms HTTP/1.1
Host: 115.190.167.176:36988
Content-Type: application/json
X-Device-Key: 39dc753bd0cb19da5050a2f0edf932f851f5b21b90a6d06ecf9a28d81079a0a6

{
  "physicalUid": "206EF1B3AD74",
  "sourceEventId": "206EF1B3AD74:1700000000000",
  "title": "燃烧报警",
  "level": "danger",
  "message": "检测到燃烧，峰值温度92.3°C，位置(12,21)",
  "temp": 92.3,
  "occurredAtMs": 1700000000000
}

字段说明

字段	类型	说明
physicalUid	string	设备物理UID（MAC地址，不带冒号大写）
sourceEventId	string	事件唯一ID（physicalUid:timestampMs）
title	string	报警标题
level	string	报警级别（danger/warning/info）
message	string	报警详细信息
temp	number	温度值
occurredAtMs	number	发生时间戳（毫秒）

报警类型映射

AlarmType	title	level
DANGER_TEMP_ALARM	高温报警	danger
HEATER_BURST_ALARM	异常升温报警	warning
HEATER_MOVING_ALARM	高温移动报警	warning
BURNING_ALARM	燃烧报警	danger
EXPANDING_ALARM	高温扩散报警	warning
UNATTENDED_ALARM	无人照看报警	warning

使用示例

1. 初始化（已自动集成）

// 在app_main.cpp中已自动初始化
CloudAlarmReporter::init();

2. 上报报警（已自动集成）

// 在AlarmManager::addAlarmToHistory中已自动调用
bool success = CloudAlarmReporter::reportAlarmAsync(
    AlarmManager::BURNING_ALARM,
    "检测到燃烧，峰值温度92.3°C，位置(12,21)",
    92.3f,
    "厨房区域"
);

3. 获取状态信息

// 获取队列大小
int queue_size = CloudAlarmReporter::getQueueSize();

// 检查上报器是否运行
bool is_running = CloudAlarmReporter::isReporterRunning();

测试验证

1. 运行测试工具

python test_cloud_alarm_reporter.py

2. 观察ESP32日志

I (12345) CloudAlarmReporter: 🌐 初始化云端报警上报模块
I (12346) CloudAlarmReporter: ✅ 云端报警上报模块初始化成功
I (12347) AlarmManager: 📝 添加报警历史: [14:30:25] 燃烧 - 检测到燃烧... (温度: 92.3°C)
I (12348) AlarmManager: ☁️ 报警已加入云端上报队列
I (12349) CloudAlarmReporter: 📨 开始上报报警: [燃烧报警] 206EF1B3AD74:1700000000000
I (12350) CloudAlarmReporter: 📡 HTTP响应状态码: 200
I (12351) CloudAlarmReporter: ✅ 报警上报成功: 206EF1B3AD74:1700000000000

3. 验证步骤

1. ✅ 确认App已登录并完成设备绑定
2. ✅ 触发一次真实报警
3. ✅ ESP32串口日志显示POST上报成功
4. ✅ 云端数据库alarm_records出现新记录
5. ✅ App报警历史页显示云端记录

故障排除

常见问题

1. HTTP请求失败

   • 检查网络连接
   • 确认云端服务器地址和端口
   • 验证设备密钥是否正确

2. 队列满

   • 检查网络状况
   • 增加队列大小
   • 检查云端服务器响应速度

3. 重复上报

   • 确认sourceEventId生成逻辑
   • 检查云端去重机制

调试日志

启用详细日志：

// 在menuconfig中设置日志级别为DEBUG
esp_log_level_set("CloudAlarmReporter", ESP_LOG_DEBUG);

性能影响

• 内存占用: 约8KB（任务栈 + 队列缓冲）
• CPU占用: 极低（仅在报警时激活）
• 网络流量: 每次报警约200-500字节
• 延迟影响: 无（异步处理）

扩展功能

未来可扩展的功能

1. 批量上报: 将多个报警打包上报
2. 离线缓存: 网络断开时缓存报警，恢复后上报
3. 压缩传输: 使用gzip压缩减少流量
4. 加密传输: 使用HTTPS加密通信
5. 配置动态更新: 支持远程更新服务器地址和密钥

总结

ESP32云端报警上报功能已完全集成到现有系统中，无需额外配置即可使用。该功能具有高可靠性、低延迟、易扩展的特点，为智能家居系统提供了完整的云端数据同步能力。