【资料分享】MicoKit云数据通信协议 - MICO - 电子技术论坛 - 最好最受欢迎电子论坛!

电子发烧友官网论坛在线研讨会活动客服QQ:3144539146
开启辅助访问 收藏本站切换到宽版

电子技术论坛»论坛 › MICO

【资料分享】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 对象数组表示该模块所具有的所有属性；每一个属性中使用不同的字段表示该属性的特征。
设备描述表结构如下：
  1. {
  2. "services": [
  3. {
  4. "type": "UUID", // service1 UUID
  5. "iid": , // service iid
  6. "properties": [
  7. { // property 1
  8. "type": "UUID", // property UUID
  9. "iid": , // property iid
  10. "format": "data_type", // property value type
  11. "perms": [ // property permission
  12. "pr", // can read
  13. "pw", // can write
  14. "ev" // will notify
  15. ],
  16. "maxValue": , // max value for int/float
  17. "minValue": , // min value for int/float
  18. "minStep": , // min step value for int/float
  19. "maxStringLen": // max string length in byte
  20. "unit": "unit string" // property data unit
  21. },
  22. { // property 2
  23. ...
  24. }
  25. ...
  26. ]
  27. },
  28. { // service2
  29. ...
  30. },
  31. ...
  32. ]
  33. }
复制代码
其中:
(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. 异常消息
异常消息体数据格式如下：
执行成功：
  1. {
  2. “status”: 0
  3. }
复制代码
执行异常：
  1. {
  2. “status”: ,
  3. “properties”: {
  4. “iid1”: ,
  5. “iid2”: ,
  6. “iid3”: ,
  7. ...
  8. }
  9. }
复制代码
其中：
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 结构：
  1. {
  2. “iid1”: ,
  3. “iid2”: ,
  4. “iid3”: ,
  5. ...
  6. }
复制代码
APP 读取属性值请求(其中k-v 的k 值为请求的iid 的字符串)：
  1. {
  2. “iid1”: ,
  3. “iid2”: ,
  4. “iid3”:
  5. }
复制代码
设备读取成功响应数据：
  1. {
  2. “iid1”: value1,
  3. “iid2”: value2,
  4. “iid3”: value3
  5. }
复制代码
APP 写属性值请求：
  1. {
  2. “iid1”: value1,
  3. “iid2”: value2,
  4. “iid3”: value3
  5. }
复制代码
设备写入成功响应数据：
  1. {
  2. “iid1”: value1,
  3. “iid2”: value2,
  4. “iid3”: value3
  5. }
复制代码
其中：
（1）value 为读取或写入成功的属性值；
（2）返回状态码见“异常处理”部分的说明。

八、实例
1. 设备具有三个模块：rgb_led, adc, uart，其中ADC 自动采集数并上报，uart 和云端实现数
据透传。
设备描述表如下：
  1. {
  2. "services": [
  3. {
  4. "type": "public.map.service.dev_info",
  5. "iid": 1,
  6. "properties": [
  7. {
  8. "type": "public.map.property.name",
  9. "iid": 2,
  10. "format": "string",
  11. "perms": [
  12. "pr",
  13. "pw"
  14. ],
  15. "maxStringLen": 16
  16. },
  17. {
  18. "type": "public.map.property.manufacturer",
  19. "iid": 3,
  20. "format": "string",
  21. "perms": [
  22. "pr"
  23. ],
  24. "maxStringLen": 16
  25. }
  26. ]
  27. },
  28. {
  29. "type": "public.map.service.rgb_led",
  30. "iid": 4,
  31. "properties": [
  32. {
  33. "type": "public.map.property.switch",
  34. "iid": 5,
  35. "format": "bool",
  36. "perms": [
  37. "pr",
  38. "pw"
  39. ]
  40. },
  41. {
  42. "type": "public.map.property.hues",
  43. "iid": 6,
  44. "format": "int",
  45. "perms": [
  46. "pr",
  47. "pw"
  48. ],
  49. "maxValue": 360,
  50. "minValue": 0,
  51. "minStep": 1,
  52. "unit": "degree"
  53. },
  54. {
  55. "type": "public.map.property.saturation",
  56. "iid": 7,
  57. "format": "int",
  58. "perms": [
  59. "pr",
  60. "pw"
  61. ],
  62. "maxValue": 100,
  63. "minValue": 0,
  64. "minStep": 1,
  65. "unit": "percentage"
  66. },
  67. {
  68. "type": "public.map.property.brightness",
  69. "iid": 8,
  70. "format": "int",
  71. "perms": [
  72. "pr", "pw"
  73. ],
  74. "maxValue": 100,
  75. "minValue": 0,
  76. "minStep": 1,
  77. "unit": "percentage"
  78. }
  79. ]
  80. },
  81. {
  82. "type": "public.map.service.adc",
  83. "iid": 9,
  84. "properties": [
  85. {
  86. "type": "public.map.property.value",
  87. "iid": 10,
  88. "format": "int",
  89. "perms": [
  90. "pr", "ev"
  91. ],
  92. "maxValue": 4095,
  93. "minValue": 0,
  94. "minStep": 1
  95. },
  96. {
  97. "type": "public.map.property.event",
  98. "iid": 11,
  99. "format": "bool",
  100. "perms": [
  101. "pr", "pw"
  102. ]
  103. }
  104. ]
  105. },
  106. {
  107. "type": "public.map.service.uart",
  108. "iid": 12,
  109. "properties": [
  110. {
  111. "type": "public.map.property.message",
  112. "iid": 13,
  113. "format": "string",
  114. "perms": [
  115. "pr",
  116. "pw",
  117. "ev"
  118. ],
  119. "maxStringLen": 512,
  120. "unit": "byte"
  121. }
  122. ]
  123. }
  124. ]
  125. }
复制代码
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 字段，修改文档名称
MicoKit云数据通信协议v0.1.6.pdf (318.87 KB, 下载次数: 152)

【新技能】那些你不知道的红外热像“隐形”功能
回复 赞

举报 使用道具

10个回复
沙发
张馨 发表于 2015-6-2 11:24:51
谢谢！。。。。。。。。。。。。。。了解一下
华强芯城电阻小批量现货，下单即发，全网底价！点击进入>> 
回复 赞

举报 使用道具

板凳
829785 发表于 2015-6-3 08:49:37
好资料，学习一下，感谢！
回复 赞

举报 使用道具

4#
daojianxiao86 发表于 2015-6-10 09:18:16
有意思，发帖不容易，感谢分享
【新技能】那些你不知道的红外热像“隐形”功能
回复 赞 支持 反对

举报 使用道具

5#
王飞强 发表于 2015-8-30 20:09:03
感谢分享，有空学习了解一下哈
回复 赞 支持 反对

举报 使用道具

6#
weslydreamer 发表于 2015-9-2 16:40:33
随时准备上手 看外貌似乎是物联网利器啊
回复 赞 支持 反对

举报 使用道具

7#
chengjia213 发表于 2015-9-16 22:03:26
藏下`````````````````
回复 赞 支持 反对

举报 使用道具

8#
yangzhixiong11 发表于 2016-3-4 21:22:56
谢谢分享...............
回复 赞

举报 使用道具

9#
kob24bry81 发表于 2016-5-2 16:37:39
可以实现数据推送吗？还是说都是从服务器中拉数据到本地？
回复 赞 支持 反对

举报 使用道具

10#
马松 发表于 2017-6-20 20:45:42
谢谢分享
回复 赞

举报 使用道具

11#
Merciless友 发表于 2017-8-1 13:30:52
谢谢楼主分享资料！！！
回复 赞 支持 反对

举报 使用道具

高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 注册

本版积分规则

相关帖子


关闭

站长推荐上一条 /6 下一条

小黑屋|手机版|Archiver|电子发烧友 ( 湘ICP备2023018690号 )

GMT+8, 2024-4-20 04:48 , Processed in 0.472145 second(s), Total 41, Slave 29 queries .

Powered by 电子发烧友网

© 2015 bbs.elecfans.com

微信扫描
快速回复 返回顶部 返回列表