设备接入接口协议

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

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

  1. MQTT连接

接入域名

企业版实例的接入域名，请在物联网平台控制台，找到对应的实例，单击实例，进入实例详情页面查看。

可变报头（variable header）：Keep Alive

CONNECT指令中需包含Keep Alive（保活时间）。保活心跳时间取值范围为30秒~1200秒，建议取值300秒以上。若网络不稳定，请将心跳时间设置长一些。如果心跳时间不在保活时间内，物联网平台会拒绝连接。

MQTT的CONNECT报文参数


  1. MQTT保活

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

  1. MQTT调试

推荐使用 mqttbox客户端工具。

  1. mqtt 连入步骤

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

  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. 增加设置返回

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

名称

类型

是否必选

示例值

描述

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. 查询设备请求

名称

类型

是否必选

示例值

描述

operator

string

是

QueryDevice

QueryDevice：查询设备

msg_id

String

是


消息ID

data




具体内容

  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. 下发升级指令

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

名称

类型

是否必选

示例值

描述

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. 升级确认消息回复

名称

类型

是否必选

示例值

描述

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. 下发获取当前软件版本指令

名称

类型

是否必选

示例值

描述

operator

string

是

Versions

获取当前版本

msg_id

String

是


消息ID

data




具体内容

  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. 设备上线下线通知

主要是设备连接上平台后，设备主动发送设备上线通知；设备下线后，设备主动发送设备下线通知。设备将主动推送上线下线通知消息到主题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. 设备上线通知

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

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

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

  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. 请求示例
{
"msg_id":”10201”,
"operator":"Online-Ack",
"code": 200,
"message": "操作成功",
"data":{
"device_id":"1305433" }
}
  1. 设备下线通知

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

  1. 请求示例
{
"operator": "Offline", "data": {
"device_id":"1305433", "time":"2020-03-07 14:09:47" }
}
  1. 心跳

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

  1. 接口名称

mqtt/device/heartbeat

  1. 请求参数

名称

类型

是否必选

示例值

描述

operator

string

是

heartbeat

操作类型：设备心跳

data





device_id

string


1306612

设备ID

time

String


2020-05-10 19:43:34

心跳时间

  1. 示例

请求URL

mqtt/device/heartbeat
  1. 请求示例
{
 “operator”:”heartbeat”,
”data”:{
   “device_id”:”1306612”,
”time”:” 2020-05-10 19:43:34”
 }
}
  1. 附加说明
  1. 返回编码