文章标题：《数据点编辑指南》 文档更新时间：2015.5.26
数据点标准协议：机智云为智能硬件开发提供的一套定义硬件功能及其参数的标准协议。
一、数据点详解¶
1、基本描述¶
机智云数据点协议每一个数据点包含三项基本描述信息：
显示名称（display_name）：¶
用最清晰的方式描述一个数据点的名称，支持所有中英文及符号字符类型（为了正常显示请避免使用特殊字符）。不在硬件端存储传输，用于虚拟设备及IoE Demo App开发调试时的识别，如果你的硬件项目需要团队协同开发，请规范命名［显示名称］。
标识名（name）：¶
用于应用层传输，客户端或业务云开发时需要使用，不在硬件端存储和传输。命名规则遵循标准的开发语言变量名命名规范，支持英文字母、数字和下划线，以英文字母开头。
备注（desc）：¶
选填，用一段文本描述当前数据点的功能及定义方法，对字符格式不做限制。只用于提高数据点的易读性，如果需要团队协作开发，建议规范填写。
2、读写操作类型¶
数据点包括四种读写操作的类型：
只读（status_readonly）：¶
根据不同智能设备的功能及元器件，对于只能读取状态而无法接受客户端或云端控制的传感器或元器件（如温度传感器、湿度传感器等），选择使用［只读］类型。
可写（status_writable）：¶
如果你要定义的元器件和对应的功能支持客户端或云端控制（改变元器件状态），那就需要选择［可写］类型，（如LED等的开关和亮度调节）
故障（fault）：¶
结合智能硬件研发时的具体设计情况，我们给出了［故障］这一特殊读写操作类型的数据点。此类型数据点一般无需在客户端上展示，只作为特定事件发生时的报警或状态上报。开发者可利用此类型数据点定义设备的故障点，我们建议每一个故障点使用一个数据点，以布尔型数据定义。
报警（alert）：¶
报警类型与故障类型相似，开发者可利用次类型数据点作为向客户端发送消息推送的依据。同样我们也建议每一个报警点使用一个数据点，以布尔型数据定义。
3、数据类型¶
数据点除了需要定义读写操作类型之外，还需要定义数据点的数据类型格式，定义适当的数据类型格式不仅可以简化MCU程序的实现，也大大节省了指令传输的字节长度和设备运行效率。机智云数据点标准协议支持4种类型的格式：
布尔（bool）：¶
只有［true］和［false］两个值，占用空间1bit。当你要定义的某个功能（元器件）只有两个状态，如开关状态等，建议使用布尔数据类型。
枚举（enum）：¶
可定义一个有限的取值集合，每2个值占用1bit。当你要定义的某个功能（元器件）有固定的若干个值，如全彩LED的颜色选择可以定义12个颜色等，建议采用枚举数据类型。
数值（num）：¶
通过取值范围（最小值、最大值）和分辨率（步进长度）来定义一个功能点的参数，取值范围支持8位长度（包含小数）的数字，分辨率支持4位长度并且大于0的数字。后台根据用户的输入自动将数值换算成可用于MCU开发的uint类型数据，并自动选择uint8、uint16、uint32以最大限度节省空间占用。
扩展（binary）：¶
扩展类型就是开发者的自定义（透传）指令，只需指定数据点长度（单位Byte），机智云作为传输管道，由开发者自行通过设备端和客户端（或业务云）进行指令翻译。如果以上三种类型无法满足对功能的定义时使用，机智云不建议使用此类型数据，因为此类型数据机智云无法识别，也就无法使用机智云其他的各种基于数据分析的服务和增值服务（当你觉得需要使用扩展类型时，请尝试向机智云寻求帮助，机智云的工程师大多数情况下可以帮助你避免使用扩展类型数据点）
二、编辑数据点¶
针对不同类型数据格式，需要填写的参数均有所不同，以下分别对不同数据类型提供编辑方法：
布尔型数据类型添加/编辑方法：¶
布尔型是最简单的格式类型，没有参数，只有两个值：true (1) 、false (0)。如图
枚举型数据类型添加/编辑方法：¶
“数据类型”选择［枚举］类型后，在“枚举范围”文本框中直接输入枚举值，每一个值使用英文逗号“,”隔开。点击保存提交后，程序将自动为每一个枚举值添加一个序号，客户端或硬件端开发直接使用枚举序号。如图
数值型数据类型添加/编辑方法：¶
数值类型的编辑是相对比较复杂的操作，我们尽量通过程序的自动换算来减低数值类型的编辑难度，关于换算的算法，有兴趣的可以通过本文后半部分了解。这里我们提供普通开发者需要掌握的编辑方法，唯一的技巧就是，你购买的元器件电气参数规定了什么就输入什么（包括小数、负数），也可以根据最终想要的效果输入适当的值。
“数据类型”选择［数值］类型后，出现数据范围和分辨率文本框，数据范围输入最小值和最大值，分辨率就是你希望可调节的精度或元器件本身支持的最高精度。如图
扩展型数据类型添加/编辑方法：¶
“数据类型”选择［扩展］类型后，出现“数据长度”必填文本框，开发者可输入小于等于2047（单位Byte）的正整数。本质上就是约定了一条指令为此数据点保留的空间长度。
以上就是定义数据点会需要掌握的方法，另外需要特别强调的就是，当你完成数据点的定义并根据自动生成的设备串口协议文档实现了设备功能之后，每一次对数据点的修改都会导致设备无法连接云端，此时需要重新下载设备串口协议文档更新MCU程序。
三、数值型数据类型自动换算实现原理：¶
如以上提到，我们在定义数值型数据点的时候，取值范围可以使用包括小数、负数等非uint类型数值，熟悉嵌入式开发的开发者会知道，这些数值在设备端都是不被支持的。
机智云为了让设备功能定义更加简单直接、所见即所得，研究出来一套算法，用于将用户输入的数值转换成设备能够识别的uint类型，这套算法的核心公式是：y=kx+m
其中，
y表示“显示值”，就是用户可见的最终数值，也是数据点定义时输入的值。包括 Ymin(最小值) 和 Ymax(最大值)
x表示“传输值”，就是实际指令间传输使用的数值，一定是uint格式。也包括 Xmin 和 Xmax
k表示“分辨率”，就是用户输入的分辨率一值，确定了每个取值的步进。
m表示“取值偏移量”，算法通过m值将y值偏移到满足x值uint格式的要求，m值默认等于Ymin，确保Xmin＝0 。
以下用一个电子温度计举例说明换算过程 数据点内容： 取值范围：-30（Ymin） ~ 50（Ymax），分辨率：0.1
根据公式：y=kx＋m，m默认等于Ymin -30
Xmin = (-30+30) / 0.1 = 0
Xmax = (50+30) / 0.1 = 800
