传感器数据一键式上云的使用说明
- DTC（Data to Cloud）简介
- 云端配置
- 设备端配置
- 功能调试
LD平台是阿里云针对物联网领域提供的端到端一站式开发平台，可覆盖各个物联网行业应用场景。将每一类具有相同功能定义的IoT设备以产品的方式进行管理，通过对产品的功能模型定义，将不同的“物”统一接入并抽象为网络上的资源，实现与应用的快速集成，赋能各类IoT场景和行业开发者，实现从连接到服务的智能升级。
DTC是AliOS Things中uData模块的一键上云功能，目的是通过设备端SDK连接阿里云，并将物理传感器等相关数据，发送到LD平台云端平台。 一个IoT设备的传感器自动连云的完整流程是先进行云端产品开发、云端测试设备添加；再进行设备端配置，以及功能调试 **本文重点讲述uData中的DTC部分，其他的内容只是简单介绍 **
在产品开发前，首先保证LD平台的云端的产品、设备已完成配置。如果已经在LD平台的云端已经完成了该工作，则可以跳过该章节；如果用户想创建一个新产品、新设备，可以参考该章节完成。
LD平台将每一类具有相同功能定义的物联网设备以产品的方式进行管理，以ProductKey作为区分，一款产品包含特定的名称、型号、通讯方式及扩展类描述等信息。产品开发前，请确定已经完成以下工作
- 拥有阿里云平台的使用账号，如果没有您需要进行账号注册；
- 正常登录开发平台；
平台连接： https://linkdevelop.aliyun.com/admin
1.开始创建产品
2.产品基本属性配置
按照下图说明，设置产品所属分类、名称，配置产品的数据格式、通讯方式。需要注意的是：如果已有对应的产品所属分类，与设备端的传感器类型、功能相匹配，则可以直接选取使用；如果没有，则可选取“其他类型”，通过自定义的方式添加产品。
数据格式建议选取标准的Alink格式。
通过以下两步进入产品开发流程
产品即为一类具有相同功能定义的设备，而对于传感器验证Demo产品来讲，如果包含温度传感器、加速度传感器等，我们可以添加其对应的功能。
需要注意的事项如下：
标识符-- 表示功能的名称，设备端需要上报该功能属性时，必须采用该唯一的标识符；
数据类型、单位、范围、精度 -- 这几项需要结合在一起说明，代表产品的相关功能属性，设备端在上报时，需要采用相同的配置。数据类型、精度、单位不统一，则导致上报数据出错；范围不对，则导致上报的数据被过滤掉；
而对于三轴加速度传感器，每次数据采集，则会有三组数据需要上报，其数据格式可考虑采用JSON格式的数据，然后将三组数据再JSON格式数据内再分别添加
多组传感器数据添加后，会得到如下所示的功能定义列表
设备开发比较简单，即增加一个产品中唯一的设备名称即可。
添加成功后，可以获取Productkey、devicename以及devicesecret
设备创建成功后，云端的配置已经完成，记录以下信息，在后续的设备端开发中会使用。
在产品功能定义完成后，平台将自动生成JSON格式的TSL（即 Thing Specification Language），用来描述物的模型。该部分内容需要保存下来。
| 名词 | 说明 |
|---|---|
| 产品 | 一组具备共同功能定义的设备集合，以ProductKey作为区分，一款产品包含特定的名称、型号、通讯方式及扩展类描述等信息 |
| 设备 | 具备唯一标识的具体设备，以设备凭证作为区分，一般包括能够与云端独立进行交互的直连设备，也包括通过网关接入云端的子设备 |
| ProductKey | 由平台颁发的产品唯一标识，11位长度的英文数字随机组合 |
| ProductSecret | 由平台颁发的产品加密密钥，通常与ProductKey成对出现，可用于一型一密的认证方案 |
| DeviceName | 用户注册设备时生成的设备唯一编号，支持系统自动生成，也可支持用户添加自定义编号，产品维度内唯一 |
| DeviceSecret | 设备密钥，与DeviceName成对出现，可用于一机一密的认证方案 |
| 设备激活凭证 | 设备在云端预注册后颁发的设备认证证书，包含ProductKey、DeviceName和DeviceSecret三元组，开发者可下载到本地（excel文件），用于产线批量烧录，设备上线时根据该凭证进行认证鉴权 |
| 属性 | 即property，设备的功能模型之一，一般用于描述产品固有的特性，例如检测的温度、湿度等 |
| 事件 | 即events，设备端post给云端的消息，新建一个property时，其event应该有property的identifier，这个在建立property时，event自动生成，不过其method为thing.event.property.post |
| 服务 | 即service，产品提供给云端的能力,云端可以通过sevice，向设备发起一系列命令 |
根据云端产生的设备凭证（参考2.5.1和2.5.2章节），修改头文件aos\framework\protocol\alink-ilop\sdk-encap\imports\iot_import_product.h下的设备凭证信息（当前是由编译宏ON_PRE2控制，编译宏定定义位于文件aos\example\linkkitapp\linkkitapp.mk）。
#define PRODUCT_KEY "a1Enz5qfxxx"
#define PRODUCT_SECRET "ouov8ya7p3Ichxxx"
#define DEVICE_NAME "aos_air_boxxxx"
#define DEVICE_SECRET "zImMgPN6kJ4KH2YyrH4DM6l12345uxxx"
在产品功能定义完成后，平台将自动生成JSON格式的TSL（即 Thing Specification Language），用来描述物的模型，获取方式请参考2.5.3章节。该信息经过“压缩并转义”后，转换成C语言下的json格式，这样可以添加到设备端的TSL信息中。“压缩并转义”的方式可以参考下面的链接：https://www.sojson.com/yasuo.html
在创建物的对象时，需要转义后的TSL信息，其修改可以参考文件在aos\example\dtcapp\dtc_tsl.c。
const char TSL_STRING[] = "{\"schema\":\"https://iot-tsl.oss-cn-shanghai.aliyuncs.com/schema.json\",\"profile\":{\"productKey\":\"a1Enz5qfa8e\"},\"services\":[{\"outputData\":[],\"identifier\":\"set\",\"inputData\":[{\"identifier\":\"PowerSwitch\",\"dataType\":{\"specs\":{\"0\":\"关闭\",\"1\":\"打开\"},\"type\":\"bool\"},\"name\":\"电源开关\"}],\"method\":\"thing.service.property.set\",\"name\":\"set\",\"required\":true,\"callType\":\"sync\",\"desc\":\"属性设置\"},{\"outputData\":[{\"identifier\":\"PowerSwitch\",\"dataType\":{\"specs\":{\"0\":\"关闭\",\"1\":\"打开\"},\"type\":\"bool\"},\"name\":\"电源开关\"},{\"identifier\":\"CurrentHumidity\",\"dataType\":{\"specs\":{\"unit\":\"%\",\"min\":\"0\",\"unitName\":\"百分比\",\"max\":\"100\"},\"type\":\"int\"},\"name\":\"当前湿度\"},{\"identifier\":\"CurrentTemperature\",\"dataType\":{\"specs\":{\"unit\":\"°C\",\"min\":\"-40\",\"unitName\":\"摄氏度\",\"max\":\"55\"},\"type\":\"double\"},\"name\":\"当前温度\"}],\"identifier\":\"get\",\"inputData\":[\"PowerSwitch\",\"CurrentHumidity\",\"CurrentTemperature\"],\"method\":\"thing.service.property.get\",\"name\":\"get\",\"required\":true,\"callType\":\"sync\",\"desc\":\"属性获取\"}],\"properties\":[{\"identifier\":\"PowerSwitch\",\"dataType\":{\"specs\":{\"0\":\"关闭\",\"1\":\"打开\"},\"type\":\"bool\"},\"name\":\"电源开关\",\"accessMode\":\"rw\",\"required\":true},{\"identifier\":\"CurrentHumidity\",\"dataType\":{\"specs\":{\"unit\":\"%\",\"min\":\"0\",\"unitName\":\"百分比\",\"max\":\"100\"},\"type\":\"int\"},\"name\":\"当前湿度\",\"accessMode\":\"r\",\"required\":false},{\"identifier\":\"CurrentTemperature\",\"dataType\":{\"specs\":{\"unit\":\"°C\",\"min\":\"-40\",\"unitName\":\"摄氏度\",\"max\":\"55\"},\"type\":\"double\"},\"name\":\"当前温度\",\"accessMode\":\"r\",\"required\":false}],\"events\":[{\"outputData\":[{\"identifier\":\"PowerSwitch\",\"dataType\":{\"specs\":{\"0\":\"关闭\",\"1\":\"打开\"},\"type\":\"bool\"},\"name\":\"电源开关\"},{\"identifier\":\"CurrentHumidity\",\"dataType\":{\"specs\":{\"unit\":\"%\",\"min\":\"0\",\"unitName\":\"百分比\",\"max\":\"100\"},\"type\":\"int\"},\"name\":\"当前湿度\"},{\"identifier\":\"CurrentTemperature\",\"dataType\":{\"specs\":{\"unit\":\"°C\",\"min\":\"-40\",\"unitName\":\"摄氏度\",\"max\":\"55\"},\"type\":\"double\"},\"name\":\"当前温度\"}],\"identifier\":\"post\",\"method\":\"thing.event.property.post\",\"name\":\"post\",\"type\":\"info\",\"required\":true,\"desc\":\"属性上报\"},{\"outputData\":[{\"identifier\":\"ErrorCode\",\"dataType\":{\"specs\":{\"0\":\"恢复正常\"},\"type\":\"enum\"},\"name\":\"故障代码\"}],\"identifier\":\"Error\",\"method\":\"thing.event.Error.post\",\"name\":\"故障上报\",\"type\":\"info\",\"required\":true}]}";
用户自己创建的设备，如果需要上报云端的TSL属性标识符与源代码service_dtc_default_name_init中不同，则需要通过以下接口修改标识符名称；如果名称已经匹配，则不需要调用该函数。
| 名称 | 描述 |
|---|---|
| 函数 | int service_dtc_name_set(udata_type_e type, char* src[], int num) |
| 说明 | 修改udata服务所对应的标识符名称 |
| 返回值 | 0: 修改udata服务所对应的标识符名称成功; 非0值: 修改udata服务所对应的标识符名称失败 |
| 参数 | 类型 | 描述 | 备注 |
|---|---|---|---|
| type | udata_type_e | udata服务类型 | 可参考结构体udata_type_e，默认只初始化了有物理传感器对应的类型 |
| src | char* (src)[] | 标识符名称所对应的字符串指针数据 | 0: 从本地获取物模型，非0: 从云端获取物模型 |
| num | int | 字符串指针的个数 | 大于1的值：复合型数据对应的字符串（结构体类型）；1：标准型数据对应的字符串（int float 等） |
当前数据上报云端默认的周期为2秒；如果用户需要修改该上报周期，可以调用以下接口完成；如果默认的上报周期能够满足要求，则不需要进行修改。
| 名称 | 描述 |
|---|---|
| 函数 | int service_dtc_publish_cycle_set(udata_type_e type, uint32_t cycle) |
| 说明 | 修改udata服务上报云端的周期 |
| 返回值 | 0: 修改udata服务所对应的标识符名称成功; 非0值: 修改udata服务所对应的标识符名称失败 |
| 参数 | 类型 | 描述 | 备注 |
|---|---|---|---|
| type | udata_type_e | udata服务类型 | 可参考结构体udata_type_e，默认只初始化了有物理传感器对应的类型 |
| cycle | uint32_t | udata服务上报云端的周期 | 单位是毫秒，如果该值小于物理sensor 的读取周期，则实际上报周期与物理sensor的读取周期相同 |
下面以developer kit板为例说明linkkit用例的调试过程。
example\uDataapp目录下已集成了相关的用例代码，2、3两个章节完成配置修改后，执行以下命令则可以编译用例 aos make udataapp@developerkit dtc=1
编译完成后，生成的可执行文件为out\udataapp@developerkit\binary\udataapp@developerkit.bin
通过ST-LINK工具可以将版本烧录到版本中；
烧录完成后，复位单板，开始运行；待打印停止后，通过netmgr命令连接网络；
- netmgr connect your_ssid your_password
- 后面两个参数分别对应ssid和密码
等待约20S后，即可完成设备与阿里云的链接；此时登录该设备所对应的云平台，找到相应的设备，可以发现，设备已经是在线状态；
点击查看按键，如果已经开启物理传感器，则在云端可以看到上传的数据
云端数据类型如下所示
| 传感器名称 | 简称 | 单位 | 云端数据类型 | 说明 |
|---|---|---|---|---|
| 加速度计 | acc | g | float | 1 g = 9.8 m/s2（米每平方秒） |
| 陀螺仪 | gyro | dps | float | dps(度每秒) |
| 磁力计 | mag | G | float | 1 G(Gaus) = 1000 mG(毫高斯) |
| 接近光 | proximity | -- | int | 代表物体到传感器的距离大小，单位：无 |
| 光感计 | als | lux | int | 亮度流明值 |
| 气压计 | baro/pressure | hPa（百帕） | int | 100 Pa = 1 hPa（百帕） |
| 温度计 | temp | °c | float | 0.1摄氏度 |
| 湿度计 | humi | % | float | 相对湿度RH，云端用%（百分比）表示 |
| 心率计 | hr | bpm | int | bpm：次数每秒 |