# iot-data-sdk

**Repository Path**: L17326185675/iot-data-sdk

## Basic Information

- **Project Name**: iot-data-sdk
- **Description**: 本 SDK 旨在提供**设备数据存储、状态上报及离线检测**功能，适用于**物联网设备数据管理**，采用 **MQTT 协议** 进行数据上报，并支持 **数据持久化存储** 及**断点续传**。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-02-12
- **Last Updated**: 2025-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# **IoT 设备数据存储与上报 SDK**

本 SDK 旨在提供**设备数据存储、状态上报及离线检测**功能，适用于**物联网设备数据管理**，采用 **MQTT 协议** 进行数据上报，并支持 **数据持久化存储** 及**断点续传**。

---

## **📁 版本管理**
| 版本号  | 说明             | 发布时间       |
|--------|----------------|--------------|
| v1.0.0 | 初始版本发布    | 2025-02-12  |


## **📁 目录结构**

```text
.
├── README.md          # 项目说明文档
├── config/
│   └── config.go      # 配置管理
├── example/
│   └── main.go        # SDK 使用示例
├── go.mod             # Go 依赖管理
├── go.sum
├── iot.go             # 主要逻辑
├── iotsdk/
│   └── iotsdk.go      # SDK 实现
├── model/
│   ├── property.go    # 设备属性定义
│   └── state.go       # 设备状态
├── mqtt/
│   └── mqtt.go        # MQTT 相关实现
├── status/
│   └── status.go      # 设备状态管理
└── storage/
    ├── retransmission.go  # 数据补传逻辑
    └── storage.go         # 数据存储管理
```

---


## **📌 功能特性**
✅ **设备数据存储**：数据文件化存储，支持 `.data`、`.index` 和 `.log` 文件，方便本地缓存与断点恢复  
✅ **定时上报设备状态**：根据采集服务的配置上报间隔，定时将设备状态上报。若设备超过指定的超时时间未上报，则视为离线。 
✅ **自动清理过期数据**：自动清理超过指定天数的过期数据。  
✅ **定时补传未成功数据**：每天定时补传前 3 天未成功上报的数据，并在成功后标记。
✅ **选择时间段上报数据**：选择某段时间内的设备数据进行上报，注意开始时间 (startTimeStr) 和结束时间 (endTimeStr) 需要在同一天
---


## 📂数据存储格式

### **1. 目录结构**

#### 1.1数据文件
设备的实时数据以 `.data` 文件存储，文件命名格式为：/data/iot/device/2025-01-01/{device_name}-{index}.data
每个文件的内容为 JSON 格式，且每行包含设备上报的 JSON 数据。文件大小限制为 5MB，超出后会创建新的文件进行存储。
存储格式如：`UUID | 设备数据时间 | 设备数据 | productkey | deviceID `

#### 1.2日期索引文件
对应的日期索引文件存储为 `.index` 文件，文件命名格式为：/data/iot/device/2025-01-01/{device_name}-{index}.index
每行记录设备数据的时间戳，以便于根据时间查找历史数据。
存储格式如：`UUID | 设备数据时间戳`

#### 1.3上报结果文件
上报结果文件存储为 `.log` 文件，文件命名格式为：/data/iot/device/{platform}/2025-01-01/{device_name}-{index}.log
文件记录设备的每次上报结果。
成功为 `UUID | 上报时间 | success`
失败为 `UUID | 上报时间 | fail`

---

## **定时任务**

### **1. 定时上报设备状态**
- SDK 会根据 `StateTimeout` 配置的上报间隔，定时上报设备状态。
- 若设备超出 `OfflineTimeout` 未上报数据，则系统标记设备为 **离线**。

### **2. 定时补传上报失败的数据**
- **每天 00:30**，系统扫描 **前 3 天** `.log` 文件，找到 **上报失败** 的数据进行补传。
- 补传成功后，**更新 `.log` 记录为 "成功"**。

---

## **⚙️SDK 配置项**

SDK 通过 `config.Config` 结构体配置参数，示例如下：

```go
// Config 定义 SDK 的所有配置参数
type Config struct {
    Broker         string        // MQTT 服务器地址
    ClientID       string        // MQTT 客户端 ID
    Username       string        // MQTT 用户名
    Password       string        // MQTT 密码
    OfflineTimeout time.Duration // 设备超时未上报视为离线（例如：15 分钟）
    StateTimeout   time.Duration // 设备状态定时上报
    // 数据存储相关配置
    DataStoragePath string // 数据存储根目录，例如："/data/iot/device"
    ExpireDays      int    // 数据保存天数（自动清理过期目录）
    Platform        string // 平台名称，用于生成上报结果文件所在路径（例如："iot_platform"）
}
```

---

# 🚀使用示例
以下代码演示如何初始化 SDK，并使用 ProcessData 方法上报设备数据：
```go
package main

import (
	iot_data_sdk "iot-data-sdk"
	"iot-data-sdk/config"
	"time"
)

func main() {
	// 初始化配置
	conf := &config.Config{
		Broker:          "tcp://127.0.0.1:1883",
		ClientID:        "test-client",
		Username:        "admin",
		Password:        "public",
		OfflineTimeout:  15 * time.Second,
		StateTimeout:    1 * time.Minute,
		DataStoragePath: "./data/iot/device",
		ExpireDays:      30,
		Platform:        "iot_platform",
	}
	cfg := config.NewConfig(conf)

	// 实例化 SDK
	sdk := iot_data_sdk.NewIotSdk(cfg)

	productKey := "aaaaa"
	deviceID := "device-001"

	// 模拟周期性上报数据
	for i := 0; i < 5; i++ {
		data := `{"temperature":25.3,"humidity":60}`
		dataTime := time.Now()

		// 调用 ProcessData 方法：内部存储数据并上报
		sdk.ProcessData(productKey, deviceID, data, dataTime)

		// 每 2 分钟上报一次
		time.Sleep(2 * time.Minute)
	}

	// 保持程序运行
	select {}
}

```