产品数据格式详解

1. 概述

创建产品

创建产品需选择数据格式(即产品下设备数据传输过程中的组织格式),本文档我们将对数据格式进行详细介绍。

2. 数据点-TLV

2.1 功能介绍

数据点即设备产品的功能的抽象,用于描述产品功能及其参数。通过创建数据点,设备与云端通讯的数据格式即可确定,设备、云平台便可以相互识别数据。

2.2 序号

创建数据点时,将自动为数据点分配一个序号。序号与数据点一一对应。

2.2 名称

数据点名称分为中文名称英文名称,主要用于显示。

2.3 描述

用一段文本描述当前数据点的功能及定义方法,对字符格式不做限制。只用于提高数据点的易读性,如果需要团队协作开发,建议规范填写。

2.4 数据类型

数据点支持5中数据类型,具体说明如下:

2.4.1 布尔型

该类型用于表示两个状态:True或False。如开关状态等,建议使用布尔型。

2.4.2 数值型

填写数值范围,数值可为负数/小数,IntoYun将自动把数值转换为正数进行传输。具体转换方法请参考数值型详解

2.4.3 枚举型

可定义一个有限的取值集合。当产品的某个功能有固定的若干个值,例如灯光效果可分为“自定义,黄色,紫色,粉色”, 建议使用枚举型。

2.4.4 字符串型

该类型定义一个字符串数据。如果发送一个字符串,建议使用该类型。

2.4.5 扩展型

对于无法使用上述类型表示的数据点,可以采取扩展型表示。扩展型数据内容由用户自定义。对于扩展型,IntoYun平台无法识别也不做解析处理。

2.5 传输类型

2.4.1 可上报

可上报表示该数据点数据可以从设备往平台传输。

2.4.2 可下发

可下发表示该数据点数据可以从平台往设备传输。

2.6 数值型详解

在定义数值型数据点的时候,取值范围可以使用包括小数、负数等非uint类型数值。为了避免不同的设备对整形和浮点型数据的不同处理,我们采取把整形,浮点型统一转换成正整数进行传输。

可以通过如下算法进行转换:x = (y - m) * 10^k。变量描述如下:

  • x表示“传输值”,就是设备与平台之间传输值。一定是uint格式。也包括 Xmin 和 Xmax。
  • y表示“实际值”,就是用户可见的最终数值,也是数据点定义时输入的值。包括Ymin(最小值) 和 Ymax(最大值)。
  • k表示“小数点位数”,就是用户输入的小数点一值,用于确定数据的小数点位数。
  • m表示“取值偏移量”或“增量”,算法通过m值将y值偏移到满足x值uint格式的要求,m值默认等于Ymin,确保Xmin=0。

以下用一个电子温度计举例说明换算过程 数据点内容: 取值范围:-30(Ymin) ~ 50(Ymax),小数点: 1位

根据公式:x = (y - m) * 10^k,m默认等于Ymin -30

Xmin = (-30+30) / 0.1 = 0

Xmax = (50+30) / 0.1 = 800

2.6 TLV组织格式

我们采取了TLV(type-length-value)格式组织数据点,具体参考TLV二进制格式说明

3. 自定义

如果您的产品已经有自己的数据格式,你可以选择自定义数据格式。如果采取这种数据格式,IntoYun平台不对设备数据进行解析处理。