数据点协议¶
机智云为了方便设备协议的定义、开发，并提供通用数据接口访问设备状态和历史数据，制定了数据点协议和机遇数据点协议的通用指令
数据点协议定义了和设备通讯所承载的单个数据的类型、变换、长度，和整个数据包的封包、解包规则。
其中类型(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
- min：
- 扩展类型(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
}
}
]
}
],
}
