221 lines
6.0 KiB
Markdown
221 lines
6.0 KiB
Markdown
# 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`** - 添加模块初始化
|
||
|
||
## 配置参数
|
||
|
||
### 云端服务器配置
|
||
|
||
```cpp
|
||
// 云端服务器URL
|
||
static constexpr const char* CLOUD_SERVER_URL = "http://115.190.167.176:36988/device-alarms";
|
||
|
||
// 设备认证密钥
|
||
static constexpr const char* DEVICE_KEY = "39dc753bd0cb19da5050a2f0edf932f851f5b21b90a6d06ecf9a28d81079a0a6";
|
||
```
|
||
|
||
### 性能参数
|
||
|
||
```cpp
|
||
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请求格式
|
||
|
||
```http
|
||
POST /device-alarms HTTP/1.1
|
||
Host: 115.190.167.176:36988
|
||
Content-Type: application/json
|
||
X-Device-Key: 39dc753bd0cb19da5050a2f0edf932f851f5b21b90a6d06ecf9a28d81079a0a6
|
||
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| 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. 初始化（已自动集成）
|
||
|
||
```cpp
|
||
// 在app_main.cpp中已自动初始化
|
||
CloudAlarmReporter::init();
|
||
```
|
||
|
||
### 2. 上报报警（已自动集成）
|
||
|
||
```cpp
|
||
// 在AlarmManager::addAlarmToHistory中已自动调用
|
||
bool success = CloudAlarmReporter::reportAlarmAsync(
|
||
AlarmManager::BURNING_ALARM,
|
||
"检测到燃烧，峰值温度92.3°C，位置(12,21)",
|
||
92.3f,
|
||
"厨房区域"
|
||
);
|
||
```
|
||
|
||
### 3. 获取状态信息
|
||
|
||
```cpp
|
||
// 获取队列大小
|
||
int queue_size = CloudAlarmReporter::getQueueSize();
|
||
|
||
// 检查上报器是否运行
|
||
bool is_running = CloudAlarmReporter::isReporterRunning();
|
||
```
|
||
|
||
## 测试验证
|
||
|
||
### 1. 运行测试工具
|
||
|
||
```bash
|
||
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生成逻辑
|
||
- 检查云端去重机制
|
||
|
||
### 调试日志
|
||
|
||
启用详细日志：
|
||
|
||
```cpp
|
||
// 在menuconfig中设置日志级别为DEBUG
|
||
esp_log_level_set("CloudAlarmReporter", ESP_LOG_DEBUG);
|
||
```
|
||
|
||
## 性能影响
|
||
|
||
- **内存占用**: 约8KB（任务栈 + 队列缓冲）
|
||
- **CPU占用**: 极低（仅在报警时激活）
|
||
- **网络流量**: 每次报警约200-500字节
|
||
- **延迟影响**: 无（异步处理）
|
||
|
||
## 扩展功能
|
||
|
||
### 未来可扩展的功能
|
||
|
||
1. **批量上报**: 将多个报警打包上报
|
||
2. **离线缓存**: 网络断开时缓存报警，恢复后上报
|
||
3. **压缩传输**: 使用gzip压缩减少流量
|
||
4. **加密传输**: 使用HTTPS加密通信
|
||
5. **配置动态更新**: 支持远程更新服务器地址和密钥
|
||
|
||
## 总结
|
||
|
||
ESP32云端报警上报功能已完全集成到现有系统中，无需额外配置即可使用。该功能具有高可靠性、低延迟、易扩展的特点，为智能家居系统提供了完整的云端数据同步能力。
|