设备管理接口规范_MQTT协议

设备接入接口协议

1. MQTT接口协议
   1. MQTT客户端直连

客户端使用MQTT协议连接服务器，认证参数客户ID、帐号、密码等。

1. 1. MQTT连接

接入域名	企业版实例的接入域名，请在物联网平台控制台，找到对应的实例，单击实例，进入实例详情页面查看。
可变报头（variable header）：Keep Alive	CONNECT指令中需包含Keep Alive（保活时间）。保活心跳时间取值范围为30秒~1200秒，建议取值300秒以上。若网络不稳定，请将心跳时间设置长一些。如果心跳时间不在保活时间内，物联网平台会拒绝连接。
MQTT的CONNECT报文参数

1. 1. MQTT保活

设备端在保活时间间隔内，至少需要发送一次报文，包括ping请求。连接保活时间的取值范围为30秒~1200秒。建议取值300秒以上。从物联网平台发送CONNACK响应CONNECT消息时，开始心跳计时。收到PUBLISH、SUBSCRIBE、PING或 PUBACK消息时，会重置计时器。超过指定1.5倍心跳时间未收到消息（指定心跳时间乘以1.5），服务器将自动断开连接。

1. 1. MQTT调试

推荐使用 mqttbox客户端工具。

1. 1. 1. mqtt 连入步骤

确认系统防火墙已经关闭，首先新增一个连接打开连接设置。

1. 接口规范
   1. 设备管理

提供给终端调用，进行设备的增加、修改、查询等信息。

1. 1. 1. 增加设备

终端设备调用平台的接口进行增加设备，平台回复设备增加结果。

1. 1. 1. 1. 增加设备请求

终端设备调用平台的接口进行增加设备。

名称	类型	是否必选	示例值	描述
operator	string	是	AddDevice	AddDevice：增加设备
msg_id	String	是		消息ID
data				具体内容
device_id	string			设备ID
unique_id	String			设备编号
device_type	string			设备类型
device_name	string			设备名称
longitude	string			经度
latitude	string			纬度

终端设备向平台发起请求示例：

{

"operator": "Add", "msg_id":” 10201”,

"data": {

"device_id":"","unique_id":"12345432",

"device_type":”终端设备",

"device_name":"172.168.2.202",

"longitude":"234",”latitude”:”” }

}

1. 1. 1. 1. 增加设置返回

平台收到终端增加设置后，平台处理完成后，给终端设备响应

名称	类型	是否必选	示例值	描述
operator	string	是	AddDevice-Ack	AddDevice-Ack:增加回复
msg_id	String	是		消息ID
code	int	是		返回值 200：成功
message	string			不成功的原因描述
data				具体内容
device_id	string			设备ID
unique_id	String			设备编号

增加信息回复的响应示例：

{

"operator":"Add-Ack",

"msg_id":”10201”,

"code": 200,

"message": "操作成功",

"data":{

"device_id":"1305433", "unique_id":"12345432"}

}

1. 1. 1. 查询设备

终端向平台发起查询设备，平台返回终端列表信息。

1. 1. 1. 1. 查询设备请求

名称	类型	是否必选	示例值	描述
operator	string	是	QueryDevice	QueryDevice：查询设备
msg_id	String	是		消息ID
data				具体内容

1. 1. 1. 1. 返回查询设备列表

平台给终端返回设备列表信息。

名称	类型	是否必选	示例值	描述
operator	string	是	QueryDevice-Ack	QueryDevice-Ack:查询结果回复
msg_id	String	是		消息ID
code	int	是		返回值 200：成功
message	string			不成功的原因描述
data		是		具体内容
device_id	string	是		设备ID
unique_id	String	是		设备编号
device_type	string			设备类型
device_name	string	是		设备名称
longitude	string			经度
latitude	string			纬度

1. 1. 远程升级版本和获取版本信息
      1. 升级指令

远程升级指令由服务器端发送对应升级信息到终端设备，确认信息由终端发送到服务器端。

1. 1. 1. 1. 下发升级指令

服务器端发送对应升级信息到终端设备。

名称	类型	是否必选	示例值	描述
operator	string	是	Upgrade	Upgrade：升级指令
msg_id	String	是		消息ID
data				具体内容
name	string	是	V1.00.000	版本名称
path	String	是	http://w88.com/	版本下载地址

如下发升级指令的示例：

{

"msg_id":"ID:localhost-637050900934386959:42763:53:1", "operator":"Upgrade", "data":

{

"name":"最新版本", "path":"https://mqttxxxx.oss-cn-shenzhen.aliyuncs.com/face/ba30fcbe-4758-4e1c-a287-5ab448a475ed.swx" }

}

1. 1. 1. 1. 升级确认消息回复

名称	类型	是否必选	示例值	描述
operator	string	是	Upgrade-Ack	Upgrade-Ack：升级回复
msg_id	String	是		消息ID
code	int	是		200：成功
message	string			不成功的原因描述
data				具体内容
name	string	是	V1.00.000	版本名称
device_id	string	是		设备ID

回复示例：

{"msg_id":"ID:localhost-637050900934386959:42763:53:1","operator": "Upgrade-Ack",”code”:200,”message”:”升级成功”, "data": { "device_id":"5d0848e581c3e6f1938a035f", "name":"最新版本"} }

1. 1. 1. 获取当前软件版本

由服务器端发送获取软件版本信息到终端设备，确认信息由终端发送到服务器端。

1. 1. 1. 1. 下发获取当前软件版本指令

名称	类型	是否必选	示例值	描述
operator	string	是	Versions	获取当前版本
msg_id	String	是		消息ID
data				具体内容

1. 1. 1. 1. 返回获取当前软件版本信息

名称	类型	是否必选	示例值	描述
operator	string	是	Upgrade-Ack	Upgrade-Ack：升级回复
msg_id	String	是		消息ID
code	int	是		200：成功
message	string			不成功的原因描述
data				具体内容
name	string	是	V1.00.000	软件版本号
buildtime	string	是	2019-12-02 10:46:05	软件版本生成时间
device_id	string	是		设备ID

1. 1. 设备上线下线通知

主要是设备连接上平台后，设备主动发送设备上线通知；设备下线后，设备主动发送设备下线通知。设备将主动推送上线下线通知消息到主题mqtt/face/basic 中。

名称	类型	是否必选	示例值	描述
operator	string	是	Online Online-Ack Offline	Online：设备上线通知 Online-Ack:设备接收平台上线的回复 Offline:设备下线通知
data
device_id	string		1306612	设备ID
user_name	String			云端用户名
ip	String			设备地址
device_name	String			设备本机名称
time	String		2020-05-10 19:43:34	心跳时间

1. 1. 1. 设备上线通知

设备在连接平台成功的前提下，向平台发送上线通知消息，平台接收到上线通知消息后，需要回复设备接收设备上线通知回复，否则设备会间隔时间内（大

概一分钟）不断发送上线通知消息到平台，直至接收到平台确认信息。设备默认

推送上线通知消息话题为 mqtt/face/basic。

1. 1. 1. 1. 请求示例

{

"msg_id":” 10201”,

"operator": "Online", "data": {

"device_id":"1305433","user_name":"admin", "time":"2020-05-12 15:11:10", "ip":"172.168.2.202", "device_name":"Face1" }

}

1. 1. 1. 设备接收上线通知回复

平台接收到设备的上线通知后，需要回复设备接收到上线通知，否则设备会间隔时间内（大概一分钟）不断发送上线通知指令到平台，直至接收到平台确认信息。

1. 1. 1. 1. 请求示例

{

"msg_id":”10201”,

"operator":"Online-Ack",

"code": 200,

"message": "操作成功",

"data":{

"device_id":"1305433" }

}

1. 1. 1. 设备下线通知

设备下线后发送设备下线通知，由设备主动推送消息至平台服务器。设备默认推送上线通知消息话题。

1. 1. 1. 1. 请求示例

{

"operator": "Offline", "data": {

"device_id":"1305433", "time":"2020-03-07 14:09:47" }

}

1. 1. 心跳

为了解决检测到设备与云平台的联通情况，设备主动增加心跳信息，设备将主动每间隔一段时间左右推送心跳消息到主题。此接口不需要响应

1. 1. 1. 接口名称

mqtt/device/heartbeat

1. 1. 1. 请求参数

名称	类型	是否必选	示例值	描述
operator	string	是	heartbeat	操作类型：设备心跳
data
device_id	string		1306612	设备ID
time	String		2020-05-10 19:43:34	心跳时间

1. 1. 1. 示例

请求URL

mqtt/device/heartbeat

1. 1. 1. 1. 请求示例

{  “operator”:”heartbeat”, ”data”:{    “device_id”:”1306612”, ”time”:” 2020-05-10 19:43:34”  } }

1. 附加说明
   1. 返回编码