ONENET设备终端接入协议.docx

ONENET设备终端接入协议.docx

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

ONENET设备终端接入协议

（MQTT）

MessageQueuingTelemetryTransport

版本号

修订日期

修订内容

说明

2015/9/8

草稿

2016/4/8

重构

Liuyuan

2016/4/19

丰富报文格式，业务流程

Leihong

2016/7/13

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

Leihong

MessageQueuingTelemetryTransport（MQTT）1

1说明3

2接入流程4

3Packet格式说明4

Fixedheader4

VariableHeader&Payload5

4支持的packet6

4.1CONNECT6

FixedHeader6

VariableHeader6

Payload7

4.2CONNACK8

FixedHeader8

VariableHeader8

4.3PUBLISH（client->server）9

Fixedheader9

VariableHeader10

Payload10

4.4PUBLISH（server->client）10

Fixedheader10

VariableHeader11

Payload11

4.5PUBACK11

Fixedheader11

VariableHeader11

4.6SUBSCRIBE12

Fixedheader12

VariableHeader12

Payload12

4.7SUBACK13

Fixedheader13

VariableHeader13

Payload13

4.8UNSUBSCRIBE14

Fixedheader14

VariableHeader14

Payload14

UNSUBACK14

Fixedheader14

VariableHeader15

5接入流程15

5.1连接鉴权15

5.2消息发布16

数据点上报16

平台命令（下发&回复）20

5.3创建Topic23

5.4取消订阅24

5.5推送设备Topic25

Publish报文推送:

25

HTTP青求推送26

1说明

OneNet的要求、默认

MQTT协议详细内容请参见MQTTversion官方文档，本文档对此不做详细说明，仅指明

参数、以及当前实现与MQTT官方文档的差异。

该版本支持的功能

鉴权;

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

仓U建topic;

获取项目的topic列表；

订阅/取消平台的topic;

设备间topic订阅；

平台命令下发；

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

2接入流程

2.1访问平台注册用户；

2.2用户根据业务情况，在“连接请求”章节中选择EDP登录方式（目前公测阶段，页面还未提供MQT■登录

选项，登录方式与EDP兼容）；

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

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

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

3Packet格式说明

包格式包含三部分:

FixedHeader

所有packet中都必须有

VarableHeader

部分包含有

Payload

部分包含有

Fixedheader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

0

0

0

0

该版本支持的所有类型:

名字

值

流向

描述

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

消息类型

Variable

Header

Payload

CONNECT

有

有

CONNACK

有

有

PUBLISH

有

有

PUBACK

有

无

SUBSCRIBE

有

有

SUBACK

有

有

UNSUBSCRIBE

有

有

UNSUBACK

有

无

4支持的packet

4.1CONNECT

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

ProtocolName

0

0

0

0

0

0

0

0

Length

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

Password

WillRetain

WillQos

WillFlag

CleanSession

Reserve

flag

flag

Flag

Flag

Flag

Byte9-10

KeepAlive

（1）版本

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

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

（2）userflag与passwordflag

1，否则认为协议错误，平台将会断开连接。

平台不允许匿名登陆，因此这两个标志位在连接时必须设置为

（3）willflag与Willretainflag/Willqosflag

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

（4）CleanSessionFlag

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

客户端订阅的topic列表.

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

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

待发送的Qos0列表.

（5）Reserve

保留位，置0。

（6）KeepAlive保活时间

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

Payload

Description

是否必须存在

格式

Field1

Client

是

2字节字串长度+utf8字串

Identifier

Field2

UserName

是

2字节字串长度+utf8字串

Field3

UserPassword

是

2字节字串长度+utf8字串

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

字段设置

消息示例

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

client_id=”123”

设备id

username=”433223”

username设置为项目ID

password=”注册的鉴权信息”

password设置为"鉴权信息

（auth_info）”

各字段说明如下：

项目ID:

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

鉴权信息（auth_info）:

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

品内具备唯一性；

4.2CONNACK

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非法）

失败：

connack包.

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

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

成功：

*必须断掉重复的clientid.

*执行cleansession对应的操作.

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

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

PS:

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

4.3PUBLISH（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:

DUF必须为0

QOS:

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

RETAIN:

暂不实现

Qos值

Bit2

Bit1

描述

0

0

0

取多发送一次

1

0

1

至少发送一次

PS:

该版本只实现QosO,Qos1

VariableHeader

Description

格式

是否必须

Field1

TopicName

2字节字串长度+utf8字串

是

Field2

PacketIdentifier

2字节

QoS0:

:

否,QoS1:

是

Payload

内容根据不同业务自定义

4.4PUBLISH（server->client）

Fixedheader

Bit

7

6

5

4

3

2

1

0

byte1

MQTTPacketType

DUPflag

QoSLevel

RETAIN

byte2-5

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

DUP:

1,则表示为重复发送的包。

QoS1:

如果为0,则表示是第一次发送该包，如果为

Qos0:

DUP必须为0

QOS:

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

RETAIN:

Qos值

Bit2

Bit1

描述

0

0

0

取多发送一次

PS:

该版本只实现QosO

VariableHeader

Description

格式

Field1

TopicName

2字节字串长度+utf8字串

Payload

内容根据不同业务自定义

4.5PUBACK

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

4.6SUBSCRIBE

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被系统保留使用，（客户端不能订阅）：

类型

说明

$开头

平台保留

4.7SUBACK

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

失败

4.8UNSUBSCRIBE

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

5接入流程

5.1连接鉴权

Device

Onenet

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

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

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

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

5.2消息发布

数据点上报

设备使用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

DeviceOneNet

Publish$dp（Qos0）

1R

存储

透~1

Qos1（Client->Server）

Device

OneNet

Publish$dp（Qos1）

PubAck

存储

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

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

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

平台命令（下发&回复）

命令下发

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

FixHeader:

参考VariableHeader

Field名称

说明

格式

Field1

TopicName=”$creq/cmduuid”

$creq为系统下发Cmd的指令，

cmduuid为该条指令的uuid

2字节字串长度+utf8字串

Payload:

Payload包含真正的指令内容

QosO（Server->Client）

Device

OneNet

Publish$creq（Qos0）

命令下发：

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

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

命令回复

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

FixHeader:

参考VariableHeader

Field名称

说明

格式

Field1

TopicName=”$crsp/cmduuid”

$crsp为系统处理设备回复cmd的

指令,cmduuid为该条指令的uuid

2字节字串长度+utf8字串

Payload:

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

QosO（Client->Server）

OneNetDevice

—

Pulish$crsp（QosO）

Qos1（Client<->Server）

OneNet

Device

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

5.3创建Topic

DeviceOneNet

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

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

请求及响应定义如下:

HTTP方法

POST

URL

头部

api-key:

xxxx-ffff-zzzzz，必须masterkey

URL参数

HTTPbody

{

内容

a?

?

?

?

?

?

name:

xxxxxx

DeviceOneNet

报文格式参考

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

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

5.4取消订阅

DeviceOneNet

设备发起取消订阅请求.（报文格式参考平台收到请求后更新topic列表.

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

5.5推送设备Topic

Publish

报文推送:

Device

OneNet

Device

a,

Publish

Publish

Publish到订阅设备

PubAck

PubAck

Publish到订阅设备

设备发起推送

topic请求.（报文格式参考平台收到请求后，将topic推送到相关订阅设