215 lines
6.2 KiB
Markdown
215 lines
6.2 KiB
Markdown
# 离线存储功能测试指南
|
||
|
||
## 功能概述
|
||
|
||
离线存储功能会在网络断开时自动将数据存储到 Flash 中，并在网络恢复后自动补传数据。
|
||
|
||
## 测试步骤
|
||
|
||
### 1. 编译并烧录固件
|
||
|
||
```bash
|
||
cd "/home/beihong/esp_projects/Distributed Collector Gateway"
|
||
idf.py build
|
||
idf.py flash monitor
|
||
```
|
||
|
||
### 2. 观察启动日志
|
||
|
||
系统启动时会显示以下关键日志：
|
||
|
||
```
|
||
I (xxxx) main: Initializing SPIFFS file system...
|
||
I (xxxx) FLASH_SPIFS: SPIFFS mounted successfully at /flash
|
||
I (xxxx) FLASH_SPIFS: Total size: 8388608 bytes, Used: 0 bytes
|
||
I (xxxx) main: Initializing offline storage module...
|
||
I (xxxx) OFFLINE_STORAGE: Offline storage initialized
|
||
I (xxxx) main: Offline data upload task started
|
||
```
|
||
|
||
### 3. 测试场景A：网络断开时的数据存储
|
||
|
||
**操作步骤：**
|
||
|
||
1. 在系统正常运行时，断开网络连接（拔掉网线或断开路由器）
|
||
2. 观察日志输出，应该看到网络断开的提示
|
||
3. 等待 MODBUS 数据采集任务产生数据
|
||
4. 观察日志，应该看到类似以下信息：
|
||
|
||
```
|
||
W (xxxx) MQTT_ESP: Network offline, storing data locally (topic: xxx, len: xxx)
|
||
I (xxxx) MQTT_ESP: Storing offline data (type=1, size=xxx)
|
||
I (xxxx) OFFLINE_STORAGE: Stored offline data: /flash/offline/xxxxxx.json
|
||
I (xxxx) MQTT_ESP: Storage usage: 4096 / 8388608 bytes (0.0%)
|
||
```
|
||
|
||
**预期结果：**
|
||
- 数据被成功存储到 Flash 中
|
||
- 显示存储使用情况
|
||
- 设备继续正常运行，不会因为网络断开而崩溃
|
||
|
||
### 4. 测试场景B：网络恢复时的自动补传
|
||
|
||
**操作步骤：**
|
||
|
||
1. 在测试场景A中存储了一些离线数据后
|
||
2. 重新连接网络（插上网线或恢复路由器）
|
||
3. 观察日志输出
|
||
|
||
**预期日志：**
|
||
|
||
```
|
||
I (xxxx) MQTT_ESP: Network online, resuming normal operation
|
||
I (xxxx) MQTT_ESP: Found 5 offline data files, uploading...
|
||
I (xxxx) MQTT_ESP: Publishing offline data (type=1, size=xxx)
|
||
I (xxxx) MQTT_ESP: Offline data published successfully, msg_id=xxx
|
||
I (xxxx) OFFLINE_STORAGE: Deleted offline data: /flash/offline/xxxxxx.json
|
||
I (xxxx) MQTT_ESP: Storage usage: 32768 / 8388608 bytes (0.4%)
|
||
```
|
||
|
||
**预期结果：**
|
||
- 系统自动检测到网络恢复
|
||
- 自动开始上传离线存储的数据
|
||
- 每次上传成功后删除对应文件
|
||
- 逐条上传，直到所有离线数据都上传完成
|
||
|
||
### 5. 测试场景C：设备状态数据的离线存储
|
||
|
||
**操作步骤：**
|
||
|
||
1. 断开网络连接
|
||
2. 等待设备状态上报周期（默认10秒）
|
||
3. 观察日志输出
|
||
|
||
**预期日志：**
|
||
|
||
```
|
||
W (xxxx) MQTT_ESP: Network offline, storing device status locally
|
||
I (xxxx) MQTT_ESP: Storing offline data (type=2, size=xxx)
|
||
I (xxxx) OFFLINE_STORAGE: Stored offline data: /flash/offline/xxxxxx.json
|
||
```
|
||
|
||
**预期结果：**
|
||
- 设备状态数据被正确识别为 OFFLINE_DATA_TYPE_DEVICE_STATUS 类型
|
||
- 数据成功存储到 Flash
|
||
|
||
### 6. 测试场景D：存储空间耗尽
|
||
|
||
**操作步骤：**
|
||
|
||
1. 持续在网络断开状态下运行设备
|
||
2. 让 MODBUS 数据持续产生（通过发送 MODBUS 查询命令）
|
||
3. 观察存储使用率的变化
|
||
|
||
**预期日志：**
|
||
|
||
```
|
||
I (xxxx) MQTT_ESP: Storage usage: 8355840 / 8388608 bytes (99.6%)
|
||
W (xxxx) OFFLINE_STORAGE: Storage nearly full (99.6%), consider clearing old data
|
||
```
|
||
|
||
**预期结果：**
|
||
- 当存储空间快满时，系统会发出警告
|
||
- 新数据仍然可以存储，直到空间完全耗尽
|
||
- 系统继续正常运行
|
||
|
||
### 7. 测试场景E：手动清空离线数据
|
||
|
||
如果需要手动清空所有离线数据，可以：
|
||
|
||
1. 通过串口终端发送清空命令（需要自行实现）
|
||
2. 或者重新格式化 SPIFFS 文件系统（会删除所有数据）
|
||
|
||
**格式化方法：**
|
||
- 在代码中调用 `flash_spiffs_format()` 函数
|
||
- 这会清空整个文件系统，包括离线数据和配置
|
||
|
||
## MQTT 服务器端验证
|
||
|
||
在 MQTT 服务器端（如使用 MQTTX 或 Mosquitto Client）：
|
||
|
||
1. 订阅设备发布的主题：`CONFIG_MQTT_PUB_TOPIC`（在 sdkconfig 中配置）
|
||
2. 在网络断开时，应该收不到新数据
|
||
3. 在网络恢复后，应该收到之前存储的离线数据
|
||
4. 验证接收到的数据完整性和顺序
|
||
|
||
## 常见问题排查
|
||
|
||
### 问题1：日志显示 "Failed to store offline data"
|
||
|
||
**可能原因：**
|
||
- SPIFFS 文件系统挂载失败
|
||
- Flash 存储空间已满
|
||
- 文件系统错误
|
||
|
||
**解决方法：**
|
||
1. 检查 SPIFFS 初始化日志
|
||
2. 查看存储使用情况
|
||
3. 必要时格式化文件系统
|
||
|
||
### 问题2：网络恢复后没有自动上传离线数据
|
||
|
||
**可能原因：**
|
||
- 离线上传任务未启动
|
||
- MQTT 客户端未连接
|
||
- 网络状态判断错误
|
||
|
||
**解决方法：**
|
||
1. 检查日志中是否有 "Offline data upload task started"
|
||
2. 确认 MQTT 客户端已连接
|
||
3. 检查 `g_is_online` 状态
|
||
|
||
### 问题3：离线数据上传不完整或丢失
|
||
|
||
**可能原因：**
|
||
- MQTT 发布失败
|
||
- 文件读取错误
|
||
- 文件删除时机问题
|
||
|
||
**解决方法：**
|
||
1. 查看日志中的错误信息
|
||
2. 确认 MQTT 服务器可用
|
||
3. 检查 Flash 文件完整性
|
||
|
||
## 性能测试
|
||
|
||
### 存储性能
|
||
|
||
- 每条数据存储时间：通常 < 100ms
|
||
- 支持的数据大小：最大 4096 bytes（单条）
|
||
- 存储容量：约 8MB（基于分区表配置）
|
||
|
||
### 上传性能
|
||
|
||
- 每条数据上传时间：取决于网络延迟
|
||
- 上传间隔：1 秒（在离线上传任务中）
|
||
- 支持的最大数据条数：约 2000 条（基于平均每条 4KB）
|
||
|
||
## 存储容量分析
|
||
|
||
基于当前配置：
|
||
|
||
- **分区大小**: 8MB
|
||
- **SPIFFS 开销**: 约 10-20%
|
||
- **可用空间**: 约 6.4-7.2MB
|
||
- **最小文件大小**: 4KB（SPIFFS 特性）
|
||
- **MODBUS 数据大小**: 约 200 bytes/秒
|
||
- **可存储时长**: 约 2-3 小时
|
||
|
||
**注意：** 由于 SPIFFS 最小文件大小为 4KB，即使只有 200 bytes 的数据也会占用 4KB 空间。如果需要更长时间的离线存储，建议：
|
||
1. 增大存储分区
|
||
2. 使用 LittleFS 文件系统（支持更小的文件块）
|
||
3. 实现数据打包存储（多条数据打包到一个文件）
|
||
|
||
## 测试总结
|
||
|
||
完成以上测试后，你应该能够验证：
|
||
|
||
1. ✅ 网络断开时数据能正确存储到 Flash
|
||
2. ✅ 网络恢复时数据能自动补传
|
||
3. ✅ 设备状态和 MODBUS 数据都能正确处理
|
||
4. ✅ 存储空间管理正常
|
||
5. ✅ 系统在各种网络状态切换下稳定运行
|
||
|
||
如有问题，请查看 ESP 日志输出，或参考 `docs/OFFLINE_STORAGE.md` 获取详细的技术文档。
|