标准数据点协议文档

Genius · 发表于 2016-9-6 17:45:11

原文转自：http://site.gizwits.com/zh-cn/document/m2m/i_02_datapoint/
目录：
标准数据点协议文档

数据点协议

机智云为了方便设备协议的定义、开发，并提供通用数据接口访问设备状态和历史数据，制定了数据点协议和机遇数据点协议的通用指令

数据点协议定义了和设备通讯所承载的单个数据的类型、变换、长度，和整个数据包的封包、解包规则。

其中类型(data_type)包括以下类型：

布尔型(bool)：可以使用 bit 来表示
枚举类型(enum)：可以使用 bit 来表示
数字类型(unit8,unit16,unit32,uint64)：采用无符号数值进行传输，可以表示8、16、32、64位的整数和浮点数，通过 unit_spec 进行定义
- min：, (x 最小值)
- max：, (x 最大值）
- ratio：, (修正系数k, default=1)
- addition：, (增量m, default=0)
- 显示值 y 计算公式：y = k * x + m
- 传输值 x：uint
扩展类型(binary)：采用二进制数据封装其他自定义类型，固定长度
- 从 0 开始自动累加
- ["item 0", "item 1"]，定义对应的显示信息

每种类型都可以指定为以下特性(type)：

读写：status_writable
只读：status_readonly
报警：alert
故障：fault

同时定义了该数据点在响应包的偏移量和长度：

byte_offset：字节序偏移量
bit_offset：位偏移量
unit: 单位，byte 或者 bit
len: 字节或位长度

每个数据点都有对应的命名和描述信息：

name：对应的变量名
display_name：显示名称
desc：详细的描述

并且提供了通用基础指令

写指令：指定要写的字段，和字段内容
读指令：请求读取所有数据点
通知：设备主动给上位机推送信息，包括所有数据点

获取产品配置

使用 Product Key 获取设备数据点配置

http://site.gizwits.com/v2/datapoint?product_key=SDK 操作数据点指南

数据点协议参照后续样本定义

写数据，使用 entity 和 attr 的 name 构建 Dictionary(iOS) 或者 JSON(Android)

JSON 结构如下：

{
"GoBoard": {
"set_led_color_R": 254,
"set_led_color_G": 100,
"set_led_color_B": 55
}
}

复制代码

如更新 LED 颜色 iOS

[device write:@{@"GoBoard": @{@"set_led_color_R": @254, @"set_led_color_G": @100, @"set_led_color_B": @55}}];

复制代码

或者 Android

JSONObject entity = new JSONObject();
JSONObject attrs = new JSONObject();
attrs.put("set_led_color_R", 254);
attrs.put("set_led_color_G", 100);
attrs.put("set_led_color_B", 55);
entity.put("GoBoard", attrs);
device.write(entity.toString());

复制代码

收到硬件数据回调， iOS

- (BOOL)XPGWifiDevice:(XPGWifiDevice *)device didReceiveData:(NSDictionary *)data result:(int)result
{
//处理P0数据刷新
NSDictionary *_data = [data valueForKey:@"data"];
if (_data) {
NSDictionary *values = [_data valueForKey:@"GoBoard"];
NSNumber *brightness = [values valueForKey:@"set_led_brightness"];
NSLog(@"接收到的LED亮度:%@", brightness);
}
//处理报警数据刷新
NSArray *_alters = [data valueForKey:@"alters"];
//处理错误数据刷新
NSArray *_faults = [data valueForKey:@"faults"];
//处理二进制数据刷新
NSArray *_binary = [data valueForKey:@"binary"];
}

复制代码

或者 Android

public void didReceiveData(XPGWifiDevice device, ConcurrentHashMap<String, Object> dataMap, int result) { if (dataMap.get("data") != null) { Log.i("info", (String)dataMap.get("data")); // 返回主线程处理P0数据刷新 } if (dataMap.get("alters") != null) { Log.i("info", (String)dataMap.get("alters")); // 返回主线程处理报警数据刷新 } if (dataMap.get("faults") != null) { Log.i("info", (String)dataMap.get("faults")); // 返回主线程处理错误数据刷新 } if (dataMap.get("binary") != null) { Log.i("info", "Binary data:" + bytesToHex((byte[])dataMap.get("binary"))); // 返回主线程处理二进制数据刷新 } };

主线程中处理P0数据举例：

JSONObject result = new JSONObject(data); JSONObject values = result.getJSONObject("GoBoard"); int brightness = values.getInt("set_led_brightness"); Log.i("info", "brightness: " + brightness); return true;数据点样本

以下为 gokit 的数据点协议样本

{ "protocolType": "standard", "packetVersion": "0x00000004", "product_key": "a001192634a511e4ac3200163ee2253c", "name": "机智云开发套件", "entities": [ { "id": 0, "name": "GoBoard", "display_name": "机智云开发套件", "attrs": [ { "id": "1", "name": "set_led_brightness", "display_name": "设定LED亮度", "desc": "......", "type": "status_writable", "data_type": "uint8", "position": { "byte_offset": 0, "bit_offset": 0, "unit": "byte", "len": 1 }, "uint_spec": { "min": 0, "max": 254, "step": 1, "ratio": 1, "addition": 0 } }, { "id": "2", "name": "set_led_color_R", "display_name": "设定LED颜色R值", "desc": "......", "type": "status_writable", "data_type": "uint8", "position": { "byte_offset": 1, "bit_offset": 0, "unit": "byte", "len": 1 }, "uint_spec": { "min": 0, "max": 254, "step": 1, "ratio": 1, "addition": 0 } }, { "id": "3", "name": "set_led_color_G", "display_name": "设定LED颜色G值", "desc": "......", "type": "status_writable", "data_type": "uint8", "position": { "byte_offset": 2, "bit_offset": 0, "unit": "byte", "len": 1 }, "uint_spec": { "min": 0, "max": 254, "step": 1, "ratio": 1, "addition": 0 } }, { "id": "4", "name": "set_led_color_B", "display_name": "设定LED颜色B值", "desc": "......", "type": "status_writable", "data_type": "uint8", "position": { "byte_offset": 3, "bit_offset": 0, "unit": "byte", "len": 1 }, "uint_spec": { "min": 0, "max": 254, "step": 1, "ratio": 1, "addition": 0 } }, { "id": "5", "name": "set_motor_speed", "display_name": "设定电机转速", "desc": "......", "type": "status_writable", "data_type": "uint16", "position": { "byte_offset": 4, "bit_offset": 0, "unit": "byte", "len": 2 }, "uint_spec": { "min": 0, "max": 65000, "step": 1, "ratio": 1, "addition": -32500 } }, { "id": "6", "name": "env_temperature", "display_name": "环境温度", "desc": "......", "type": "status_readonly", "data_type": "uint8", "position": { "byte_offset": 6, "bit_offset": 0, "unit": "byte", "len": 1 }, "uint_spec": { "min": 0, "max": 250, "step": 1, "ratio": 1, "addition": -125 } }, { "id": "7", "name": "env_humidity", "display_name": "环境湿度", "desc": "......", "type": "status_readonly", "data_type": "uint8", "position": { "byte_offset": 7, "bit_offset": 0, "unit": "byte", "len": 1 }, "uint_spec": { "min": 0, "max": 100, "step": 1, "ratio": 1, "addition": 0 } }, { "id": "8", "name": "ir_detection", "display_name": "红外探测", "desc": "是否探测到红外信号", "type": "status_readonly", "data_type": "bool", "position": { "byte_offset": 8, "bit_offset": 0, "unit": "bit", "len": 1 } }, { "id": "9", "name": "fault_led", "display_name": "led灯故障", "desc": "......", "type": "fault", "data_type": "bool", "position": { "byte_offset": 9, "bit_offset": 0, "unit": "bit", "len": 1 } }, { "id": "10", "name": "fault_temperature", "display_name": "温度传感器故障", "desc": "......", "type": "fault", "data_type": "bool", "position": { "byte_offset": 9, "bit_offset": 1, "unit": "bit", "len": 1 } }, { "id": "11", "name": "fault_humidity", "display_name": "湿度传感器故障", "desc": "......", "type": "fault", "data_type": "bool", "position": { "byte_offset": 9, "bit_offset": 2, "unit": "bit", "len": 1 } }, { "id": "12", "name": "fault_motor", "display_name": "电机故障", "desc": "......", "type": "fault", "data_type": "bool", "position": { "byte_offset": 9, "bit_offset": 3, "unit": "bit", "len": 1 } }, { "id": "13", "name": "fault_ir_detection", "display_name": "红外探测故障", "desc": "......", "type": "fault", "data_type": "bool", "position": { "byte_offset": 9, "bit_offset": 4, "unit": "bit", "len": 1 } } ] } ], }

bigfanofloT · 发表于 2016-9-6 18:06:29

排版。。。

[资料] 标准数据点协议文档