nuciotsdk

README

Golang SDK

说明

提供了注册设备、上传设备运行信息、上传设备状态的接，内部封装实现了获取注册设备资源占用情况的功能。并支持设备上传文件，接收平台下发指令功能等，便于开发者二次开发。

SDK 获取

• 最新版本：1.1.0

环境要求

操作系统：win7,win10,Ubuntu,Centos

Golang SDK目录结构

---

|--cert mqtt连接所需证书
|--client 主程序
|--utils 工具帮助类,包括数据加密工具类、格式化工具类、时间转换工具类
|--models 项目依赖实体类,包括设备运行信息类、设备状态类、设备注册类、文件信息类、基础信息类
|--demo.go 示例程序，模拟开发者基于SDK进行开发。示例包括设备注册、设备发送状态、设备发送运行信息、设备上传文件以及对应回调函数的使用

SDK 功能列表

---

模块功能	功能点
设备注册	注册设备相关平台至物联网平台
自动重连	由于网络等原因，设备存在掉线的可能，SDK内置封装自动连接云平台
状态上报	向特定 topic 上报设备状态数据
信息上报	向特定 topic 上报设备运行信息
文件上传	上传文件至物联网S3平台
注册事件	为了满足业务开发者使用,可自行注册事件以便进行回调处理

SDK API 列表

---

函数	功能
NewIotClient	实例化SDK Client 相关选项
Configure	配置初始化
SendRegistration	设备注册
SendDeviceData	上报设备运行信息
SendDeviceStat	上报设备状态
SendFileInfo	上传文件信息
UploadFile2S3	上传文件到S3
RegisterEvent	注册事件

SDK 方法调用&数据类

---

NewIotClient

• 描述：新建IoT客户端实例，并初始化
• 输入参数

参数名称	参数数据类型	备注
DeviceReg	DeviceRegistrationReq	注册信息
MqttInfo	MqttBrokerInfo	mqtt信息
DeviceStg	DeviceStorage	存储信息

• 返回值

返回值数据类型	备注
*nucIotClient	IoT客户端实例

DeviceRegistrationReq

• 描述：设备注册请求

成员名称	成员数据类型	备注
ProtocolVersion	string	协议版本 1.1.1
DeveloperId	string	开发者ID,由平台提供
ProductKey	string	产品标识，如安检机、闸机、毫米波等等
DeviceId	string	设备唯一标识 如芯片号、MAC地址、设备序列号，需唯一确定
DeviceType	string	设备型号
DeviceIp	string	设备IP地址

MqttBrokerInfo

• 描述：Mqtt信息

成员名称	成员数据类型	备注
BrokerUrl	string	broker地址
MqttUsername	string	mqtt用户名
MqttPass	string	mqtt密码
Port	int	broker端口
IsCert	bool	是否开启证书

DeviceStorage

• 描述：设备存储信息

成员名称	成员数据类型	备注
S3Bucket	string	S3Bucket
S3AccessId	string	S3AccessId
S3AccessSecret	string	S3秘钥
LocalStoragePath	string	共享目录url
LocalStorageUserName	string	共享目录用户名
LocalStoragePass	string	共享目录密码

SendRegistration

• 描述：注册设备
• 返回值

返回值数据类型	备注
int	返回码 0：成功 其他：失败（具体失败原因参考错误码列表）

SendDeviceStat

• 描述：上传设备状态
• 输入参数

参数名称	参数数据类型	备注
deviceId	string	所注册设备的唯一标识
stat	int	所注册设备的状态 0：初始化 1：正常 2：故障 3：诊断 4：关机

UploadFile2S3

• 描述：上传文件到S3
• 输入参数

参数名称	参数数据类型	备注
deviceId	string	设备标识
filePath	string	文件本地路径
contentType	string	数据类型，可遵循 Web 数据格式，如【image/png】，【text/plain】等
fileType	EnumFileType	文件类型 具体类型参考文件类型列表

SendFileInfo

• 描述：上传成功后上报文件信息，可通过订阅上传成功回调获取上传成功的文件属性
• 输入参数

参数名称	参数数据类型	备注
deviceId	string	所注册设备的唯一标识
fileName	string	文件名称 可通过 OnUploadComplete 上传文件接口的回调方法中的 IotFileInfo 获取，对应成员为 FileName
fileType	EnumFileType	文件类型 可通过 OnUploadComplete 上传文件接口的回调方法中的 IotFileInfo 获取，对应成员为 FileType
filePath	string	文件路径 可通过 OnUploadComplete 上传文件接口的回调方法中的 IotFileInfo 获取，对应成员为 Url
fileSize	int	文件大小 可通过 OnUploadComplete 上传文件接口的回调方法中的 IotFileInfo 获取，对应成员为 FileSize

---

方法事件

ErrorEvent

• 描述：IoT 客户端调用任意接口发生错误事件
• 回调参数

参数名称	参数数据类型	备注
arg1	IotErrorInfo	错误信息

IotErrorInfo

• 描述：错误信息

成员名称	成员数据类型	备注
Code	int	错误码，具体参考错误码列表
Msg	string	错误内容 包含封装所给出的错误相关数据信息、文件信息，找到对应出错的标识性内容。还可能包含错误发生时，运行时抛出的异常信息。

UploadCompleteEvent

• 描述：IoT 客户端调用上传文件接口上传完成事件
• 回调参数

参数名称	参数数据类型	备注
arg1	IotFileInfo	文件信息
arg2	bool	文件上传是否成功 false：失败 true：成功

IotFileInfo

• 描述：文件信息，上传成功时应有对应的文件信息

成员名称	成员数据类型	备注
DeviceId	string	设备标识
FileName	string	文件名称
FileSize	int	文件大小
FileType	EnumFileType	文件类型
Url	string	文件在 S3 上的路径
UserData	string	用户自定义内容

UploadRequestEvent

• 描述：IoT 客户端收到文件上传请求事件
• 回调参数

参数名称	参数数据类型	备注
uploadReq	UploadReq	文件上传请求

UploadReq

• 描述：文件信息，上传成功时应有对应的文件信息

成员名称	成员数据类型	备注
StartTime	long	开始时间
EndTime	long	结束时间
FileType	EnumFileType	文件类型

错误码

封装库内所包含的数据结构 EnumErrorType 所对应的内容，用于枚举错误码。

错误码	错误描述	枚举名称
1000	消息订阅错误	SubscribeError
1001	注册错误	RegistrationError
1002	消息加密错误	AesError
1003	S3处理错误	S3Error
1004	与云端建立通讯错误	UnConnected
1005	消息组装错误	SetupContentError
1006	消息反序列化错误	DeserializeError
1007	消息队列处理错误	QueueError
1008	本地存储错误	LocalStorageError
1009	数据合法性错误	DataValidityError

文件类型

封装库内所包含的数据结构 EnumFileType 所对应的内容，用于枚举错误码。

文件类型	枚举类型
日志	Log
图像	Img
视频	Video
其他	Other

代码示例

package main

import (
	"fmt"
	"time"

	"gitee.com/magicyu90/nuciotsdk/client"
	"gitee.com/magicyu90/nuciotsdk/models"
	"gitee.com/magicyu90/nuciotsdk/utils"
)

// 错误回调
func OnError(args ...interface{}) {
	e := args[0].(*models.IotErrorInfo)
	fmt.Printf("OnError,code:%d,message:%s\n", e.Code, e.Message)
}

// 完成上传回调
func OnUploadComplete(args ...interface{}) {
	fmt.Println("OnUploadComplete...")
	// 发送文件信息
	ok := args[0].(bool)
	iotFileInfo := args[1].(*models.IotFileInfo)
	if ok {
		fmt.Printf("文件:%s上传1成功,上传文件信息...\n", iotFileInfo.FileName)
		n.SendFileInfo(iotFileInfo.DeviceId, iotFileInfo.FileName, iotFileInfo.Url, iotFileInfo.FileSize, iotFileInfo.FileType, iotFileInfo.UserData)
	} else {
		fmt.Printf("文件:%s上传失败...\n", iotFileInfo.FileName)
	}

}

var deviceId = "TFNBZ-XII-A01"

// 设备信息
var deviceInfo = models.DeviceRegistrationReq{
	DeveloperId:     "30b899f332114432b86da2045cc9c11b", //开发者ID
	ProtocolVersion: "1.1.1",
	DeviceId:        deviceId, //设备编号
	DeviceType:      "2000DC", //设备型号
	ProductKey:      "tr1",    //产品类型
	DeviceIp:        "192.168.1.1",
}

// mqtt信息
var mqttInfo = models.MqttBrokerInfo{
	BrokerUrl: "iot.nuctech.com", //mqtt地址
	//BrokerUrl:    "218.93.19.170",
	Port:         10884,           //mqtt端口
	MqttUsername: "tr",            //mqtt用户名
	MqttPass:     "NucTr#2020iot", //mqtt密码
	IsCert:       false,           //是否开启证书
}

// 存储信息
var storageInfo = models.DeviceStorage{
	S3Bucket:             "iot-tr",                                   //s3 bucket
	S3AccessId:           "QQRDE2APOUE0QUFDJ9A2",                     //s3 accessId
	S3AccessSecret:       "KShpiw4Y3ncrbyfzPurNMTJ3WCKAp8NidQUpwqbW", //s3 accesstoken
	LocalStoragePath:     "\\10.15.123.114\\share\\iot",              //共享目录
	LocalStorageUserName: "root",                                     //共享目录用户名
	LocalStoragePass:     "root123456",                               //共享目录密码
}

// 初始化客户端
var n = client.NewIotClient(deviceInfo, storageInfo, mqttInfo)

// 主函数
func main() {
	// 初始化配置
	n.Configure()
	// 注册错误事件
	n.RegisterEvent(models.ErrorEvent, OnError)
	// 注册上传完成事件
	n.RegisterEvent(models.UploadCompleteEvent, OnUploadComplete)

	retryTimes := 1
	// 设备注册
	for {
		fmt.Printf("开始进行第%d次注册...\n", retryTimes)
		result := n.SendRegistration()
		fmt.Printf("注册结果:%d\n", result)
		if result == 0 {
			break
		}
		retryTimes += 1
		time.Sleep(time.Duration(2) * time.Second)
	}
	fmt.Println("上报设备状态")
	go func() {
		for {
			// 发送设备状态
			n.SendDeviceStat(deviceId, 1)
			time.Sleep(time.Duration(2) * time.Second)
		}
	}()

	fmt.Println("上报设备运行信息")
	go func() {
		for {
			// 发送设备状态
			n.SendDeviceStat(deviceId, 1)
			dataItems := [2]models.DataItem{
				{DataKey: "k1", DataValue: "10", Clock: utils.GetCurrentTimestamp()},
				{DataKey: "k2", DataValue: "20", Clock: utils.GetCurrentTimestamp()}}
			n.SendDeviceData(deviceId, dataItems[:])
			time.Sleep(time.Duration(2) * time.Second)
		}
	}()

	fmt.Println("上传图片至s3")
	n.UploadFile2S3(deviceId, "C:/Users/hugonuc/Pictures/lake.jpg", models.Img, "")

	select {} // 阻塞
}