ONENET设备终端接入协议4MQTT.docx
《ONENET设备终端接入协议4MQTT.docx》由会员分享，可在线阅读，更多相关《ONENET设备终端接入协议4MQTT.docx（25页珍藏版）》请在冰点文库上搜索。
ONENET设备终端接入协议4MQTT
MessageQueuingTelemetryTransport（MQTT）
版本号
修订日期
修订内容
说明
2015/9/8
草稿
2016/4/8
重构
Liuyuan
2016/4/19
丰富报文格式，业务流程
Leihong
2016/7/13
增加设备间订阅，创建topic功能
Leihong
1说明
MQTT协议详细内容请参见MQTTversion官方文档，本文档对此不做详细说明，仅指明OneNet的要求、默认参数、以及当前实现与MQTT官方文档的差异。
该版本支持的功能:
鉴权;
数据点上报（平台指定topic）;
创建topic;
获取项目的topic列表;
订阅/取消平台的topic;
设备间topic订阅;
平台命令下发;
Qos0（cS）,Qos1（C->S）;
2接入流程
2.1访问平台注册用户；
2.2用户根据业务情况，在“连接请求”章节中选择EDP登录方式（目前公测阶段，页面还未提供MQTT登录选项，登录方式与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
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
有
无
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
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
（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
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属性（数字+字母的字符串），该属性需要产品内具备唯一性；
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非法）
失败：
*如果connect包不符合协议内容约束，则直接断掉连接，而不需要发送connack包.
*如果鉴权或授权失败，回复一个带非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：
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
内容根据不同业务自定义.
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:
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
内容根据不同业务自定义.
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连接鉴权
设备向平台发起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
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消息
5.3创建Topic
设备通过发送HTTP请求进行topic的创建操作.
平台收到请求后创建topic并返回结果.
请求及响应定义如下：
HTTP方法
POST
URL
头部
api-key:
xxxx-ffff-zzzzz，必须masterkey
URL参数
HTTPbody内容
{
“name”:
”xxxxxx”
报文格式参考
平台收到请求后更新topic列表.
平台给设备回复SubAck.（报文格式参考
5.4取消订阅
设备发起取消订阅请求.（报文格式参考
平台收到请求后更新topic列表.
平台给设备回复UnSubAck.（报文格式参考
5.5推送设备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:
欢迎访问设备云门户网站注册用户，获取最新文档。
升级会员 