MIOC标准接入协议-通讯模组与云端-MQTT-架构V1.0-MIOTO WIKI

文档版本（31）

作者:admin于 2019年07月30日 发布在分类 / 产品相关 / 云平台 下,并于 2020年07月16日编辑

MIOC标准接入协议-通讯模组与云端-MQTT-架构V1.0

880

0

一、建立与MQTT服务器的连接

HOST ： auth.mqtt.9iot.cn

PORT ： 1883

USERNAME ：请登录厂商运营系统查看。

PASSWORD ：请登录厂商运营系统查看。

CLIENT ID ：请根据设备情况，写入设备全球唯一标识。一般为设备/WIFI 模块MAC地址。 16字节，不足末尾补零。

二、MQTT发布与订阅 TOPIC 格式约定

设备端：

发布： /${USERNAME}/${PASSWORD}/${device_mac}/update

订阅： /${USERNAME}/${PASSWORD}/${device_mac}/get

故障上报： /${USERNAME}/${PASSWORD}/${device_mac}/alert

客户端：

发布： /${APPLICATION_KEY}/${PRODUCT_ID}/${client_id}/set

订阅： /${APPLICATION_KEY}/${PRODUCT_ID}/${client_id}/get

Eg.
1、建立与MQTT服务的连接
2、设备端订阅主题
TOPIC : /${USERNAME}/${PASSWORD}/${device_mac}/get

3、设备端发布消息
TOPIC : /${USERNAME}/${PASSWORD}/${device_mac}/update
发送内容 eg.： {"peopleCount":10}
通知我方核验消息是否正确收到

4、云端发送消息
A)可通知我方发送消息，设备端检查是否正确收到

B) 可调用下方接口自主发送

https://mioc.9iot.cn/api/base/standard/v1/mqtt/custpub
请求参
请求参数：
topic ：发送主题Topic ，此处对应设备端订阅Topic
content : 发送内容，例如 {"success":true}

三、指令说明。

1）协议结构说明

	字段	大小（byte）	描述
协议头	version	2	版本号
	length	2	数据包大小
	header_crc	2	协议头校验码
协议体	body	Length - 8	数据体
协议体	body_crc	2	数据体校验码

Version : 版本号（公有协议 0001 开始，私有协议 0501开始）

Length : 完整协议包大小

Header_crc ：协议头校验码。采用的多项式为CRC-16/CCITT的16位循环校验码

Body : 数据体，以下为数据体结构定义

字段	大小（byte）	描述
PackageType	1	协议包类型
Command	2	应用命令字
Data	不定长	数据

PackageType ：协议包类型，用于应用层消息逻辑处理方式。以下为协议包类型值约定：

字节值	描述
0x00	Message，无需回复协议包类型
0x01	Get，需回复协议包类型，用于请求ke获取数据回复
0x02	Set，需回复协议包类型，用于设置数据需返回设置成功与否
0x03	Result，无需回复协议包类型，用于set/get类型正确回复包，序列号与set和get包相同
0x04	Error，无需回复协议包类型，用于set/get类型错误回复包，序列号与set和get包相同

Command ：应用命令字，以下为值约定：

数据包类型	command	source数据来源
设备登录认证	0x0001	设备
设备数据上传	0x0002	设备
发送设备控制指令	0x0003	Server
时间同步	0x0004	Server
心跳包	0xFFFF	设备
发送设备查询指令	0X0005	Server
数据透传	0x0010	Server/设备
故障上报	0x0006	设备

2）设备与服务端建立连接之后，应首先发送设备认证数据包。以下为设备认证指令说明与实例：

分类	描述	长度[字节]	字段名	数据样例
Header		2	VERSION/版本	0001
		2	LENGTH/长度	0000
		2	Header_CRC/头部校验码	0000
PayLoad		1	PackgeType / 协议包类型	01
		2	Command / 数据包类型	0001
		16	MAC ADDRESS /设备标识	00000000000000010000(不足末尾补零)
		20	USERNAME / 用户名对应APPID	[BG73ivJHX6OFxxxxXXXX] ASCII
		16	PASSWORD / 密码对应PRODUCT_ID	5D31FF4CA98943E9955A025C9CAC23F3
		1	Device Type / 设备类型	01
		2	PayLoad_CRC / 数据体校验码	0000

RES:

分类	描述	长度	字段名		数据样例
Header		2	version		0001
		2	length		0000
		2	header_crc		0000
Payload	Defination	1	PackageTypeee		03
		2	Command		0001
	Date	1	RES		00(成功) 01(认证失败)
	Tail	2	CRC	0000

设备(Device Type)类型说明:

设备	标识（1byte）
电视	0x01
灯	0x02
空调	0x03
空气净化器	0x04
插座	0x05
单开开关	0x06
扫地机器人	0x07
窗帘	0x08
加湿器	0x09
风扇	0x0A
暖奶机	0x0B
豆浆机	0x0C
电热水壶	0x0D
饮水机	0x0E
电饭煲	0x0F
热水器	0x10
烤箱	0x11
净水器	0x12
冰箱	0x13
机顶盒	0x14
洗衣机	0x16
智能床	0x17
香薰机	0x18
窗	0x19
空气开关	0x1A
温度传感器	0x1B
烟雾传感器	0x1C
可燃气体传感器	0x1D
PM2.5传感器	0x1E
人体传感器	0x1F
光照传感器	0x20
雨水传感器	0x21
油烟机	0x32
电子水尺	0x65
紧急按钮	0x66
计量插座	0x67

3）设备认证通过之后，应根据实际持续情况上报心跳包：

此处应结合接入设备和上层应用的实际情况，合理选择心跳包上传频率及方案。一般情况下，如设备在接受云端指令之外的动作触发（如机械或者红外等方案），应即时通过心跳方式将当前状态上报上来。

如设备某些参数时刻变化，如传感器类设备，则建议按一定时间间隔上报最新状态。

分类	描述	长度[字节]	字段名	数据样例
Header		2	VERSION/版本	0001
		2	LENGTH/长度	0000
		2	Header_CRC/头部校验码	0000
PayLoad		1	PackgeType / 协议包类型	00
		2	Command / 数据包类型	FFFF
		1	Device Type / 设备类型	01
		不定长	结合实际情况，一般可将设备当前状态值上报上来	0000
		2	PayLoad_CRC / 数据体校验码	0000

心跳发送约定

1、设备上电入网，认证通过，立即发送至少一次心跳

2、设备状态改变（包括且不限于，MIOC系统控制/外界条件触发/传统渠道如遥控、功能按钮），立即发送至少一次

3、一定时间间隔，如60s

4）云端接受各客户终端的控制请求，向设备发送控制指令：

分类	描述	长度[字节]	字段名	数据样例
Header		2	VERSION/版本	0001
		2	LENGTH/长度	0000
		2	Header_CRC/头部校验码	0000
PayLoad		1	PackgeType / 协议包类型	02
		2	Command / 数据包类型	0003
		1	Device Type / 受控设备类型	02
		8	Suite ID/套件标识	此处全部为00
		1	Control Type / 控制类型	01
		2	Control Value / 控制设值	0001
		2	PayLoad_CRC / 数据体校验码	0000

设备应反馈控制结果：

分类	描述	长度[字节]	字段名	数据样例
Header		2	VERSION/版本	0001
		2	LENGTH/长度	0000
		2	Header_CRC/头部校验码	0000
PayLoad		1	PackgeType / 协议包类型	03
		2	Command / 数据包类型	0002
		1	Device Type / 受控设备类型	02
		8	Suite Id/套件标识	此处全部00
		1	Control Type / 控制类型	01
		1	Control Value / 控制设值	00
		1	RESULT / 控制结果	00[SUCCESS] 0X[FAILD]
		2	PayLoad_CRC / 数据体校验码	0000

4）云端接受各客户终端的查询请求，向设备发送查询指令：

分类	描述	长度[字节]	字段名	数据样例
Header		2	VERSION/版本	0001
		2	LENGTH/长度	0000
		2	Header_CRC/头部校验码	0000
PayLoad		1	PackgeType / 协议包类型	02
		2	Command / 数据包类型	0005
		1	Device Type /设备类型	02
		8	Suite ID/套件标识	此处全部为00
		1	Query Type / 查询类型	01 [为查询所有状态值]

		2	PayLoad_CRC / 数据体校验码	0000

设备应反馈查询结果：

分类	描述	长度[字节]	字段名	数据样例
Header		2	VERSION/版本	0001
		2	LENGTH/长度	0000
		2	Header_CRC/头部校验码	0000
PayLoad		1	PackgeType / 协议包类型	03
		2	Command / 数据包类型	0002
		1	Device Type / 设备类型	01
		8	Suite ID/套件标识	此处全部为00
		不定长	结合实际情况	0000
		2	PayLoad_CRC / 数据体校验码	0000

5）设备故障上报：

分类	描述	长度[字节]	字段名	数据样例
Header		2	VERSION/版本	0001
		2	LENGTH/长度	0000
		2	Header_CRC/头部校验码	0000
PayLoad		1	PackgeType / 协议包类型	02
		2	Command / 数据包类型	0006
		1	Device Type / 设备类型	02
		8	Suite ID/套件标识	此处全部为00
		1	ERROR Code/ 故障代码	取值详情参照具体设备业务协议
		2	ERROR CONTENT / 故障内容	一般为故障参数值，具体参照具体设备业务协议
		2	PayLoad_CRC / 数据体校验码	0000

6）云端要求设备重发认证指令：

收到此指令，请暂停所有其他上报指令，优先完成认证操作

分类	描述	长度[字节]	字段名	数据样例
Header		2	VERSION/版本	0001
		2	LENGTH/长度	0000
		2	Header_CRC/头部校验码	0000
PayLoad		1	PackgeType / 协议包类型	02
		2	Command / 数据包类型	0003
		1	Device Type / 受控设备类型	02
		8	Suite ID/套件标识	此处全部00
		1	Contorl Type/控制类型	7C
		2	Contorl value/控制设值	0000
		2	PayLoad_CRC / 数据体校验码	0000

设备重新认证：

重发认证包

7）模组通知云端正在OTA：

分类	描述	长度[字节]	字段名	数据样例
Header		2	VERSION/版本	0001
		2	LENGTH/长度	0000
		2	Header_CRC/头部校验码	0000
PayLoad		1	PackgeType / 协议包类型	02
		2	Command / 数据包类型	0006
		1	Device Type / 受控设备类型	02
		8	Suite ID/套件标识	此处全部00
		1	Report Type/控制类型	7B
		2	Report value/控制设值	当前版本号
		2	PayLoad_CRC / 数据体校验码	0000

8）云端通知模组进行OTA检查：

分类

描述

长度[字节]

字段名

数据样例

Header

2

VERSION/版本

0001

2

LENGTH/长度

0000

2

Header_CRC/头部校验码

0000

PayLoad

1

PackgeType / 协议包类型

02

2

Command / 数据包类型

0003

1 Device Type / 受控设备类型
02

8 Suite ID/套件标识
此处全部00

1 Report Type/控制类型

8A

2 PayLoad_CRC / 数据体校验码 0000

9）OTA升级：

运营平台，固件管理功能，添加对应设备的固件

a、检查对应可接入设备的最新版本

https://mioc.9iot.cn/api/base/standard/v1/ota/versioncheck?mac=5CCF7FCCF2390000

MAC 设备MAC地址||设备唯一标识符

返回示例
RES:

{ "item": null, "version": null, "xt_userinfo_realName": null, "mtdpimg_base_url": null, "mtdpimg_base_path_url": null, "mtdpsources_base_url": null, "mtdpsources_base_path_url": null, "xt_attachmentPath": null, "sessionId": null, "firmware_id": "BEA42E2C8EC445FBBE6DB44989AD58CD", "firmware_name": "curtain motor 7", "firmware_version": "7", "size": "317876", "url": "https://mioc.9iot.cn/xtCommonController/downFile?xt_attachment_id=91CC36C75E4A42D1932BD4C0077C804E", "url1": "https://mioc.9iot.cn/xtCommonController/downFile?xt_attachment_id=A7E85266E96844658178454BEB53A7D4", "url2": "https://mioc.9iot.cn/xtCommonController/downFile?xt_attachment_id=3C69CB1CDF614777BE36537D2C93890D", "signtype": "MD5", "description": "curtain motor 7", "access_device_id": "97BA42A50BFE4AC68D59CCCF226D6456", "path": "91CC36C75E4A42D1932BD4C0077C804E" }

其中：

firmware_version 为最新固件版本号，请设备端自行与当前版本号进行比对，是否需要更新

size 为最新固件包大小，byte

url 为最新固件包下载地址，通过版本号的比对，如需更新则使用此地址进行固件下载

url1 WIFI模组OTA所需

url2 WIFI模组OTA所需

signtype 为密钥算法

设备端根据收到的数据中firmware_version字段自行判断是否需要升级，如当前云端最新版本号大于本地版本号，则使用url字段进行固件下载，下载完成，重启设备，完成固件升级过程。

如当前云端最新版本号小于或者等于本地版本号，则无需升级，结束版本检测过程。

访问权限

创建人	admin
工作小组	MIOC物联网开放平台
文档编辑权限	创建者私有
文档阅读权限	来自分类
分类阅读权限	所有人
分类编辑权限	所有人
分类审核权限	无

标签

协议数据设备类型回复校验码校验用于描述 server

历史版本

修改日期	修改人	备注
2020-07-16 10:58:34[当前版本]	admin	修正
2020-07-16 10:26:06	admin	增加检查更新协议
2019-07-30 14:34:04	秦大人	系统管理员修改
2019-07-04 10:24:40	admin	完善协议
2019-04-26 10:44:37	admin	增加设备类型
2019-01-02 17:21:26	admin	完善协议
2019-01-02 17:20:29	admin	完善协议
2019-01-02 17:19:03	admin	完善协议
2019-01-02 14:34:49	admin	修正协议
2018-12-06 16:40:56	admin	完善协议
2018-11-27 18:04:49	admin	完善协议
2018-11-01 15:29:42	admin	完善协议
2018-10-25 16:11:48	admin	完善协议
2018-10-25 15:50:10	admin	完善协议
2018-10-25 15:40:28	admin	增加重认证协议
2018-09-25 16:02:45	admin	格式调整
2018-08-23 16:27:55	admin	.
2018-08-23 16:27:27	admin	完善认证协议
2018-08-20 10:56:36	admin	修正TOPIC说明
2018-08-20 10:54:37	admin	增加设备类型
2018-08-20 10:44:32	admin	系统管理员修改
2018-08-18 15:33:58	admin	内部资料
2018-08-15 10:48:28	admin	增加设备故障上报协议
2018-06-26 10:44:24	admin	增加心跳发送机制描述
2018-06-20 10:56:39	admin	修改标题
2018-06-20 10:08:13	admin	修改标题
2018-05-25 17:20:25	admin	描述错误
2018-05-25 17:18:28	admin	增加设备控制回传附带设置参数
2018-05-25 16:16:22	admin	增加设备状态查询指令
2018-05-25 16:05:47	admin	系统管理员修改
2018-05-25 00:17:09	admin	CREAT