ONENET设备终端接入协议4MQTT.docx

ONENET设备终端接入协议4MQTT.docx

《ONENET设备终端接入协议4MQTT.docx》由会员分享，可在线阅读，更多相关《ONENET设备终端接入协议4MQTT.docx（22页珍藏版）》请在冰豆网上搜索。

ONENET设备终端接入协议4MQTT

MessageQueuingTelemetryTransport（MQTT）

版本号

修订日期

修订内容

说明

2015/9/8

草稿

2016/4/8

重构

Liuyuan

2016/4/19

丰富报文格式，业务流程

Leihong

2016/7/13

增加设备间订阅，创建topic功能

Leihong

说明

MQTT协议详细内容请参见MQTTversion官方文档，本文档对此不做详细说明，仅指明OneNet的要求、默认参数、以及当前实现与MQTT官方文档的差异。

该版本支持的功能:

鉴权;

数据点上报（平台指定topic）;

创建topic;

获取项目的topic列表;

订阅/取消平台的topic;

设备间topic订阅;

平台命令下发;

Qos0（cS）,Qos1（C->S）;

接入流程

访问平台注册用户；

用户根据业务情况，在“连接请求”章节中选择EDP登录方式（目前公测阶段，页面还未提供MQTT登录选项，登录方式与EDP兼容）；

登录需填写设备相关属性，在项目下新增设备，获取项目ID、设备ID，以及authinfo等信息；

设备发送TCP连接请求到以下地址，发送封装的报文与平台交互。

平台服务器地址，TCP端口6002

Packet格式说明

包格式包含三部分：

FixedHeader

所有packet中都必须有

VarableHeader

部分包含有

Payload

部分包含有

Fixedheader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

0

0

0

0

byte2-5

RemainingLength（该字段占用1-4个字节）

该版本支持的所有类型：

名字

值

流向

描述

CONNECT

1

C->S

客户端请求与服务端建立连接

CONNACK

2

S->C

服务端确认连接建立

PUBLISH

3

CS

发布消息

PUBACK

4

CS

收到发布消息确认

SUBSCRIBE

8

C->S

订阅请求

SUBACK

9

S->C

订阅确认

UNSUBSCRIBE

10

C->S

取消订阅

UNSUBACK

11

S->C

取消订阅确认

VariableHeader&Payload

消息类型

VariableHeader

Payload

CONNECT

有

有

CONNACK

有

有

PUBLISH

有

有

PUBACK

有

无

SUBSCRIBE

有

有

SUBACK

有

有

UNSUBSCRIBE

有

有

UNSUBACK

有

无

支持的packet

CONNECT

FixedHeader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

0

0

0

0

byte2-5

RemainingLength（该字段占用1-4个字节）

VariableHeader

Description

7

6

5

4

3

2

1

0

byte1-2

ProtocolNameLength

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

0

byte3

‘M’

0

1

0

0

1

1

0

1

byte4

‘Q’

0

1

0

1

0

0

0

1

byte5

‘T’

0

1

0

1

0

1

0

0

byte6

‘T’

0

1

0

1

0

1

0

0

Byte7

ProtocolLevel

0

0

0

0

0

0

0

1

Byte8

ConnectFlag

User

flag

Password

flag

WillRetain

Flag

WillQosFlag

WillFlag

CleanSession

Flag

Reserve

Byte9-10

KeepAlive

版本

必须设置为4，平台只支持版本v，不支持更老的版本。

使用第三方客户端时需要注意选择正确的版本。

userflag与passwordflag

平台不允许匿名登陆，因此这两个标志位在连接时必须设置为1，否则认为协议错误，平台将会断开连接。

willflag与Willretainflag/Willqosflag

平台暂不支持willflag，WillRetainFlag与WillQosFlag必须设置为0。

CleanSessionFlag

若客户端将cleansession标志位设置为0，当其断开后，平台将会保存session，session需保持的内容包含：

客户端订阅的topic列表.

客户端保存session的内容包含：

已经发送到服务端的但还没有收到确认的Qos1消息列表.

待发送的Qos0列表.

Reserve

保留位，置0。

KeepAlive保活时间

每个客户端可自定义设置连接保持时间，最短120秒，最长65535秒。

Payload

Description

是否必须存在

格式

Field1

ClientIdentifier

是

2字节字串长度+utf8字串

Field2

UserName

是

2字节字串长度+utf8字串

Field3

UserPassword

是

2字节字串长度+utf8字串

与鉴权相关的字段包含clientid，username和password，支持鉴权方式。

字段设置

消息示例

client_id设置为平台创建设备时的设备id

username设置为“项目ID”

password设置为“鉴权信息（auth_info）”

client_id=”123”

username=”433223”

password=”注册的鉴权信息”

各字段说明如下：

项目ID：

在平台添加项目时平台生成的ID；

鉴权信息（auth_info）：

在平台申请设备时填写设备的auth_info属性（数字+字母的字符串），该属性需要产品内具备唯一性；

CONNACK

FixedHeader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

0

0

0

0

byte2-5

RemainingLength（该字段占用1-4个字节）

VariableHeader

Description

7

6

5

4

3

2

1

0

byte1

AcknowledgeFlags

0

0

0

0

0

0

0

Sp

byte2

ReturnCode

x

x

x

x

x

x

x

x

Sp:

SessionPresentFlag，session信息在服务器已保持，置1；未保存，置0。

返回码说明：

返回码

描述

0

成功

1

协议版本错误

2

非法的clientid

3

服务不可用

4

用户名或密码错误

5

非法链接（比如token非法）

失败：

*如果connect包不符合协议内容约束，则直接断掉连接，而不需要发送connack包.

*如果鉴权或授权失败，回复一个带非0错误码的connack包.

成功：

*必须断掉重复的clientid.

*执行cleansession对应的操作.

*必须回复一个connack，回复码为0.

*开始消息传递，并加入keepalive的监视.

PS：

客户端需要等到服务端的connack报文，才能发送后续的数据包.

PUBLISH（client->server）

Fixedheader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

DUPflag

QoSLevel

RETAIN

byte2-5

RemainingLength（该字段占用1-4个字节）

DUP:

QoS1：

如果为0，则表示是第一次发送该包，如果为1，则表示为重复发送的包。

Qos0：

DUP必须为0

QOS:

指定了该publish包的qos等级如下

RETAIN:

暂不实现

Qos值

Bit2

Bit1

描述

0

0

0

最多发送一次

1

0

1

至少发送一次

PS:

该版本只实现Qos0，Qos1

VariableHeader

Description

格式

是否必须

Field1

TopicName

2字节字串长度+utf8字串

是

Field2

PacketIdentifier

2字节

QoS0:

否，QoS1:

是

Payload

内容根据不同业务自定义.

PUBLISH（server->client）

Fixedheader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

DUPflag

QoSLevel

RETAIN

byte2-5

RemainingLength（该字段占用1-4个字节）

DUP:

QoS1：

如果为0，则表示是第一次发送该包，如果为1，则表示为重复发送的包。

Qos0：

DUP必须为0

QOS:

指定了该publish包的qos等级如下

RETAIN:

Qos值

Bit2

Bit1

描述

0

0

0

最多发送一次

PS:

该版本只实现Qos0

VariableHeader

Description

格式

Field1

TopicName

2字节字串长度+utf8字串

Payload

内容根据不同业务自定义.

PUBACK

Fixedheader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

0

0

0

0

byte2~5

RemainingLength（该字段占用1-4个字节）

VariableHeader

Description

7

6

5

4

3

2

1

0

byte1~2

PacketIdentifier

PacketIdentifier

SUBSCRIBE

Fixedheader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

0

0

0

0

byte2~5

RemainingLength（该字段占用1-4个字节）

VariableHeader

Description

7

6

5

4

3

2

1

0

byte1~2

PacketIdentifier

PacketIdentifier

Payload

Description

格式

Byte1~n

TopicName

2字节字串长度+utf8字串

Byten+1

Reserved

保留字节（兼容

说明

可以包含一个或多个topic.

topic必须是数字、英文、反斜杠（/）的组合，目前不支持通配符。

每个客户端最多订阅100个topic；

以下topic被系统保留使用，（客户端不能订阅）：

类型

说明

$开头

平台保留

SUBACK

Fixedheader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

0

0

0

0

byte2~5

RemainingLength（该字段占用1-4个字节）

VariableHeader

Description

7

6

5

4

3

2

1

0

byte1~2

PacketIdentifier

PacketIdentifier

Payload

Description

7

6

5

4

3

2

1

0

byte1

retcode

返回码说明：

返回码

描述

0x00

成功

0x80

失败

UNSUBSCRIBE

Fixedheader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

0

0

0

0

byte2~5

RemainingLength（该字段占用1-4个字节）

VariableHeader

Description

7

6

5

4

3

2

1

0

byte1~2

PacketIdentifier

PacketIdentifier

Payload

Description

格式

Byte1~n

TopicName

2字节字串长度+utf8字串

可以包含一个或多个topic.

UNSUBACK

Fixedheader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

0

0

0

0

byte2~5

RemainingLength（该字段占用1-4个字节）

VariableHeader

Description

7

6

5

4

3

2

1

0

byte1~2

PacketIdentifier

PacketIdentifier

接入流程

连接鉴权

设备向平台发起connect请求.connect中携带鉴权信息,具体参见（报文格式参考

平台拿到鉴权信息进行鉴权.

鉴权通过后，如果cleansession=0,平台将会加载保存的设备的一些信息.如订阅列表中描述）.

如果cleansession=1,设备没有保存信息在平台，则不加载设备相关信息.

返回鉴权结果ConnAck（报文格式参考.

消息发布

数据点上报

设备使用publish报文来上传数据点，报文格式如下：

VariableHeader：

Field名称

说明

格式

Field1

TopicName=”$dp”

$dp为系统上传数据点的指令

2字节字串长度+utf8字串

Payload:

Payload包含真正的数据点内容,支持的格式如下：

字节

说明\bit

7

6

5

4

3

2

1

0

Byte1

Bit0-5数据类型指示，目前支持：

Type=1

.

Byten

Qos1（Client->Server）

设备发布Qos0消息（上报数据点）

平台收到上报数据点后保存起来.

平台给设备回复PubAck（报文格式参考

平台命令（下发&回复）

命令下发

平台使用publish报文来下发平台指令，报文格式如下：

FixHeader：

参考VariableHeader：

Field名称

说明

格式

Field1

TopicName=”$creq/cmduuid”

$creq为系统下发Cmd的指令，cmduuid为该条指令的uuid

2字节字串长度+utf8字串

Payload:

Payload包含真正的指令内容

Qos0（Server->Client）

命令下发：

平台向设备发送topic为$creq的消息（该topic为平台命令）.

设备收到topic为$creq的topic时，需将其作为平台下发的指令来处理.

命令回复

设备使用publish报文来回复平台指令，报文格式如下：

FixHeader：

参考VariableHeader：

Field名称

说明

格式

Field1

TopicName=”$crsp/cmduuid”

$crsp为系统处理设备回复cmd的指令，cmduuid为该条指令的uuid

2字节字串长度+utf8字串

Payload:

Payload包含真正回复的指令内容

Qos0（Client->Server）

Qos1（Client<->Server）

如果设备回复响应时以Qos1回复，则平台需要给设备回复一个Puback消息

创建Topic

设备通过发送HTTP请求进行topic的创建操作.

平台收到请求后创建topic并返回结果.

请求及响应定义如下：

HTTP方法

POST

URL

头部

api-key:

xxxx-ffff-zzzzz，必须masterkey

URL参数

HTTPbody内容

{

“name”:

”xxxxxx”

报文格式参考

平台收到请求后更新topic列表.

平台给设备回复SubAck.（报文格式参考

取消订阅

设备发起取消订阅请求.（报文格式参考

平台收到请求后更新topic列表.

平台给设备回复UnSubAck.（报文格式参考

推送设备Topic

Publish报文推送:

设备发起推送topic请求.（报文格式参考平台收到请求后,将topic推送到相关订阅设备.（目前只支持在线推送）

平台返回推送ack（取决于qos）.（报文格式参考

设备使用publish报文来推送Topic.报文格式如下：

FixHeader：

参考VariableHeader：

Field名称

说明

格式

Field1

TopicName

填写设备订阅的topic

2字节字串长度+utf8字串

Payload：

Payload为设备自定义内容

HTTP请求推送

设备以HTTP的方式发起推送topic请求.

平台收到请求后,将topic推送到相关订阅设备.（目前只支持在线推送）

平台返回推送结果.

请求及响应定义如下：

HTTP方法

POST

URL

头部

api-key:

xxxx-ffff-zzzzz，必须masterkey

URL参数

topic=“XXXXXX”，必选，在发送mqtt协议的topic.必填

HTTPbody内容

用户自定义Json或二进制数据（小于64K）

成功返回

{

"errno":

0,

"error":

“succ”

}

PS:

欢迎访问设备云门户网站注册用户，获取最新文档。