【资料分享】MicoKit云数据通信协议

一、概述
本文档主要描述APP 如何通过FogCloud 访问Mico 设备的数据交互协议；
APP 和设备之间的消息收发采用MQTT 协议；
APP 开发者根据此协议完成APP 对已经连接上FogCloud 的Mico 设备的远程读写操作，从而完成对设备的远程控制操作。

二、设备描述
1.设备抽象
本协议将Mico 设备所具有的功能模块（如开关、LED、串口等外设）抽象成可访问的服务（service）；将每个模块所具有的功能（开关的状态、LED 灯的亮度值等）抽象成可读写的属性（property）。每一个service/property 都分配一个固定的iid，作为访问标识。
2. 设备描述表
将每个Mico 设备所具有的全部功能模块（services/properties）使用一个设备描述表（service_table）来表示。APP 从设备获取到该描述表之后，就可以描绘出整个设备所具有的功能模块，展示给用户。
设备描述表采用JSON 格式，使用一个services 对象数组表示设备的模块列表；每一个service 对象中使用一个properties 对象数组表示该模块所具有的所有属性；每一个属性中使用不同的字段表示该属性的特征。
设备描述表结构如下：

{
"services": [
{
"type": "UUID", // service1 UUID
"iid": , // service iid
"properties": [
{ // property 1
"type": "UUID", // property UUID
"iid": , // property iid
"format": "data_type", // property value type
"perms": [ // property permission
"pr", // can read
"pw", // can write
"ev" // will notify
],
"maxValue": , // max value for int/float
"minValue": , // min value for int/float
"minStep": , // min step value for int/float
"maxStringLen": // max string length in byte
"unit": "unit string" // property data unit
},
{ // property 2
...
}
...
]
},
{ // service2
...
},
...
]
}

其中:
(1).蓝色标识的属性字段为可选字段;
(2).UUID 为service 或者property 的类型，APP 根据此类型给用户提供相应的功能；
(3). iid 为该设备上所有services 和properties 的编号，是一个正整数；
(4). UUID 和iid 的详细说明见后续“UUID”和“内部ID”部分。

三、数据流
APP 和Mico 设备之间通过FogCloud 云的不同的数据通道进行数据交互。
1.设备数据通道
类型通道消息流向

其中，表示请求的来源（由APP 决定），设备根据此session_id 回复请求方，
不设置则表示广播该消息。

2.设备访问流程
（1）获取设备描述表

（2）读取设备属性

（3）写入设备属性

（4）读取设备服务（读取iid 服务下的所有属性）

（5）属性通知（设备自动上报）

四、异常处理
设备响应状态输出到/out/err 消息通道, APP 可从该通道中获取命令执行状态。
1.状态码

2. 异常消息
异常消息体数据格式如下：
执行成功：

{
“status”: 0
}

执行异常：

{
“status”: ,
“properties”: {
“iid1”: ,
“iid2”: ,
“iid3”: ,
...
}
}

其中：
properties 对象中表示执行异常的properties 及错误码。

五、UUID
1.UUID 定义规则
使用UUID（Universally Unique Identifier）来表示设备上不同services 和properties 的类型，APP 根据这些事先定义好的类型向用户展示相应的设备功能。

注意：目前UUID 码暂时未定，暂时仍使用唯一的字符串表示。格式如下：
.map..
其中：
（1）public 表示公开定义好的service 或者property，如:
public.map.service.dev_info 为每个设备必须有的第一个service；
public.map.property.name 表示一个模块的名字的字符串。
（2）private 表示某一类型的设备所特定的service 或者property，如：
private.map.service.xxx 表示该设备有一个特定类型的模块xxx；
private.map.property.yyy 表示该设备某个模块的一个特定的属性yyy。
（3）“map”为MicoKit Accessary Protocol 的缩写。
（4）表示是一个模块还是一个模块的属性。
（4）表示具体的类型，如adc, rgb_led, button 等。

2、实例
模块和属性的UUID 定义[暂时用字符串]

六、内部ID（iid）
1.iid 定义规则
(1). 每一个service 和property 都会分配一个固定的iid，并且在一个设备上唯一；
(2). 设备描述表的iid=0，设备的基本信息的iid=1，后续services/properties 按顺序分配；
(3). APP 可以一次使用多个iid 读取/设置多个不同的property；
(4). APP 可以一次使用多个iid 读取多个service 下的所有properties；
(5). 设置某个property 的值必须指定该property 的iid；
(6). iid 由固件程序按照设备描述表中所列出的所有services 和properties 的顺序自动分配。

2. 实例

七、消息体数据格式
APP 和设之间消息体的数据格式采用JSON 格式，每个property（或service）使用一个
key-value 对表示。key 为请求或者返回的service/property 的iid， value 为相应的属性值。
JSON 的一层Key-Value 结构：

{
“iid1”: ,
“iid2”: ,
“iid3”: ,
...
}

APP 读取属性值请求(其中k-v 的k 值为请求的iid 的字符串)：

{
“iid1”: ,
“iid2”: ,
“iid3”:
}

设备读取成功响应数据：

{
“iid1”: value1,
“iid2”: value2,
“iid3”: value3
}

APP 写属性值请求：

{
“iid1”: value1,
“iid2”: value2,
“iid3”: value3
}

设备写入成功响应数据：

{
“iid1”: value1,
“iid2”: value2,
“iid3”: value3
}

其中：
（1）value 为读取或写入成功的属性值；
（2）返回状态码见“异常处理”部分的说明。

八、实例
1. 设备具有三个模块：rgb_led, adc, uart，其中ADC 自动采集数并上报，uart 和云端实现数
据透传。
设备描述表如下：

{
"services": [
{
"type": "public.map.service.dev_info",
"iid": 1,
"properties": [
{
"type": "public.map.property.name",
"iid": 2,
"format": "string",
"perms": [
"pr",
"pw"
],
"maxStringLen": 16
},
{
"type": "public.map.property.manufacturer",
"iid": 3,
"format": "string",
"perms": [
"pr"
],
"maxStringLen": 16
}
]
},
{
"type": "public.map.service.rgb_led",
"iid": 4,
"properties": [
{
"type": "public.map.property.switch",
"iid": 5,
"format": "bool",
"perms": [
"pr",
"pw"
]
},
{
"type": "public.map.property.hues",
"iid": 6,
"format": "int",
"perms": [
"pr",
"pw"
],
"maxValue": 360,
"minValue": 0,
"minStep": 1,
"unit": "degree"
},
{
"type": "public.map.property.saturation",
"iid": 7,
"format": "int",
"perms": [
"pr",
"pw"
],
"maxValue": 100,
"minValue": 0,
"minStep": 1,
"unit": "percentage"
},
{
"type": "public.map.property.brightness",
"iid": 8,
"format": "int",
"perms": [
"pr", "pw"
],
"maxValue": 100,
"minValue": 0,
"minStep": 1,
"unit": "percentage"
}
]
},
{
"type": "public.map.service.adc",
"iid": 9,
"properties": [
{
"type": "public.map.property.value",
"iid": 10,
"format": "int",
"perms": [
"pr", "ev"
],
"maxValue": 4095,
"minValue": 0,
"minStep": 1
},
{
"type": "public.map.property.event",
"iid": 11,
"format": "bool",
"perms": [
"pr", "pw"
]
}
]
},
{
"type": "public.map.service.uart",
"iid": 12,
"properties": [
{
"type": "public.map.property.message",
"iid": 13,
"format": "string",
"perms": [
"pr",
"pw",
"ev"
],
"maxStringLen": 512,
"unit": "byte"
}
]
}
]
}

APP 消息通信：
（APP 使用MQTT 调试工具代替：http://api.easylink.io/tools/mqtt/）
（1）APP 请求设备描述表：
发送通道：/in/read/app123
发送数据：{}
设备响应：
数据通道：/out/read/app123
返回数据：设备描述表
状态通道：/out/err
状态数据：{ "status": 0 }

（2）APP 读取设备基本信息：
发送通道：/in/read/app123
发送数据：{"1":1}
设备响应：
数据通道：/out/read/app123
返回数据：{ "2": "MicoKit3288", "3": "MXCHIP" }
状态通道：/out/err
状态数据：{ "status": 0 }

（3）APP 读取rgb_led 开关状态：
发送通道：/in/read/app123
发送数据：{"5":5}
设备响应：
数据通道：/out/read/app123
返回数据：{ "5": false }
状态通道：/out/err
状态数据：{ "status": 0 }

（4）APP 设置rgb_led 灯为蓝色,，饱和度100，亮度100：
发送通道：/in/write/app123
发送数据：{"5":true, "6":240, "7":100, "8":100}
设备响应：
数据通道：/out/write/app123
返回数据：{ "5": true, "6": 240, "7": 100, "8": 100 }
状态通道：/out/err
状态数据：{ "status": 0 }

（5）设备ADC 自动上报ADC 采样数据：
上报通道：/out/read
上报数据：{ "10": 3700 }

（6）关闭ADC 自动上报：
发送通道：/in/write/app123
发送数据：{"11":false}
设备响应：
数据通道：/out/write/app123
返回数据：{"11":false}
状态通道：/out/err
状态数据：{ "status": 0 }

（7）APP 向设备串口发送数据：
发送通道：/in/write/app123
发送数据：{"13":"message from cloud!"}
设备响应：
数据通道：/out/write/app123
返回数据：{"13":"message from cloud!"}
状态通道：/out/err
状态数据：{ "status": 0 }
并且设备串口输出数据：

（8）从设备串口向云端发送数据：
设备串口发送：
APP 收到消息：

九、修订记录
版本作者时间内容
V0.1.0 wanges@mxchip.com 2015.3.11 初始版本
V0.1.3 wanges@mxchip.com 2015.4.3 新版本协议，使用设备描述表
V0.1.5 wanges@mxchip.com 2015.4.8 添加err 通道，添加APP 操作实例
V0.1.6 wanges@mxchip.com 2015.4.24 设备描述表删除value 字段，修改文档名称