Upload
hoangxuyen
View
228
Download
0
Embed Size (px)
Citation preview
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 1 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
MQTT Version 3.1.1 1
Working Draft 11 2
September 10, 2013 3
Technical Committee: 4 OASIS Message Queuing Telemetry Transport (MQTT) TC 5
Chairs: 6 Raphael J Cohn ([email protected]), Individual 7 Richard J Coppen ([email protected]), IBM 8
Editors: 9 Andrew Banks ([email protected]), IBM 10 Rahul Gupta ([email protected]), IBM 11
12 Additional artifacts: 13
• None 14
Related work: 15 Declared XML namespaces: 16
• None 17
Abstract: 18 19 MQ Telemetry Transport (MQTT) is a lightweight broker-based publish/subscribe messaging 20
protocol designed to be open, simple, lightweight and easy to implement. These characteristics 21 make it ideal for use in constrained environments, for example, but not limited to: 22
23 o Where the network is expensive, has low bandwidth or is unreliable 24 o When run on an embedded device with limited processor or memory resources 25
26 Features of the protocol include: 27 28
o The publish/subscribe message pattern to provide one-to-many message distribution and 29 decoupling of applications 30
o A messaging transport that is agnostic to the content of the payload 31 o The use of TCP/IP to provide basic network connectivity 32 o Three qualities of service for message delivery: 33
• "At most once", where messages are delivered according to the best efforts of 34 the operating environment. Message loss or duplication can occur. This level could 35 be used, for example, with ambient sensor data where it does not matter if an 36 individual reading is lost as the next one will be published soon after. 37
• "At least once", where messages are assured to arrive but duplicates may occur. 38
• "Exactly once", where message are assured to arrive exactly once. This level 39 could be used, for example, with billing systems where duplicate or lost messages 40 could lead to incorrect charges being applied. 41
o A small transport overhead and protocol exchanges minimized to reduce network traffic 42 o A mechanism to notify interested parties to an abnormal disconnection of a client using 43
the Last Will and Testament feature 44 45 Status: 46
This Working Draft (WD) has been produced by one or more TC Members; it has not yet been 47 voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a 48 Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote 49 to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re-50 approve it any number of times as a Committee Draft. 51
Deleted: 0
Deleted: August 29, 2013August 27, 2013
Field Code Changed
Deleted: in
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 2 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Initial URI pattern: 55 http://docs.oasis-open.org/mqtt/mqtt/v4.0/csd01/mqtt-v4.0-csd01.doc 56
(Managed by OASIS TC Administration; please don’t modify.) 57
58
59
60
61
62
63
64
65
66
67
68
69
70
Copyright © OASIS Open 2013. All Rights Reserved. 71
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual 72 Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website. 73
This document and translations of it may be copied and furnished to others, and derivative works that 74 comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, 75 and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice 76 and this section are included on all such copies and derivative works. However, this document itself may 77 not be modified in any way, including by removing the copyright notice or references to OASIS, except as 78 needed for the purpose of developing any document or deliverable produced by an OASIS Technical 79 Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must 80 be followed) or as required to translate it into languages other than English. 81
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors 82 or assigns. 83
This document and the information contained herein is provided on an "AS IS" basis and OASIS 84 DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY 85 WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY 86 OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 87 PARTICULAR PURPOSE. 88
89
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 3 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Table of contents 90
Contents 91
1 Introduction ........................................................................................................................................... 6 92
This specification is split into six main sections: ....................................................................................... 6 93
• Introduction and concepts ................................................................................................................ 6 94
• Control packet format ....................................................................................................................... 6 95
• The specific details of each Control Packet type ............................................................................. 6 96
• Operational behaviour of the Client and Server ............................................................................... 6 97
1.1 Terminology ........................................................................................................................................ 6 98
1.2 Conventions ........................................................................................................................................ 7 99
1.3 Normative references ......................................................................................................................... 7 100
1.4 Non normative references .................................................................................................................. 8 101
1.5 Acknowledgements ............................................................................................................................. 8 102
2 MQTT Control Packet format ............................................................................................................... 9 103
2.1 Data representations .......................................................................................................................... 9 104
2.1.1 Integer data values ...................................................................................................................... 9 105
2.1.2 UTF-8 encoded strings ................................................................................................................ 9 106
2.2 Fixed header ..................................................................................................................................... 10 107
2.2.1 MQTT Control Packet types ...................................................................................................... 10 108
2.2.2 Flags .......................................................................................................................................... 11 109
2.2.3 Remaining Length ..................................................................................................................... 13 110
2.3 Variable header ................................................................................................................................ 15 111
2.3.1 Packet identifier ......................................................................................................................... 15 112
2.4 Payload ............................................................................................................................................. 16 113
3 MQTT Control Packets ....................................................................................................................... 17 114
3.1 CONNECT – Client requests a connection to a server .................................................................... 17 115
3.1.1 Fixed header.............................................................................................................................. 17 116
3.1.2 Variable header ......................................................................................................................... 17 117
3.1.3 Payload ...................................................................................................................................... 22 118
3.1.4 Response .................................................................................................................................. 23 119
3.2 CONNACK – Acknowledge connection request ............................................................................... 24 120
3.2.1 Fixed header.............................................................................................................................. 24 121
3.2.2 Variable header ......................................................................................................................... 24 122
3.2.3 Payload ...................................................................................................................................... 25 123
3.3 PUBLISH – Publish message ........................................................................................................... 25 124
3.3.1 Fixed header.............................................................................................................................. 25 125
3.3.2 Variable header ......................................................................................................................... 25 126
3.3.3 Payload ...................................................................................................................................... 26 127
3.3.4 Response .................................................................................................................................. 27 128
3.3.5 Actions ....................................................................................................................................... 27 129
3.4 PUBACK – Publish acknowledgement ............................................................................................. 27 130
3.4.1 Fixed header.............................................................................................................................. 27 131
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 4 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.4.2 Variable header ......................................................................................................................... 28 132
3.4.3 Payload ...................................................................................................................................... 28 133
3.4.4 Actions ....................................................................................................................................... 28 134
3.5 PUBREC – Publish received (QoS 2 publish received, part 1) ........................................................ 28 135
3.5.1 Fixed header.............................................................................................................................. 28 136
3.5.2 Variable header ......................................................................................................................... 28 137
3.5.3 Payload ...................................................................................................................................... 29 138
3.5.4 Actions ....................................................................................................................................... 29 139
3.6 PUBREL – Publish release (QoS 2 publish received, part 2)........................................................... 29 140
3.6.1 Fixed header.............................................................................................................................. 29 141
3.6.2 Variable header ......................................................................................................................... 30 142
3.6.3 Payload ...................................................................................................................................... 30 143
3.6.4 Actions ....................................................................................................................................... 30 144
3.7 PUBCOMP – Publish complete (QoS 2 publish received, part 3) .................................................... 30 145
3.7.1 Fixed header.............................................................................................................................. 30 146
3.7.2 Variable header ......................................................................................................................... 30 147
3.7.3 Payload ...................................................................................................................................... 31 148
3.7.4 Actions ....................................................................................................................................... 31 149
3.8 SUBSCRIBE - Subscribe to topics ................................................................................................... 31 150
3.8.1 Fixed header.............................................................................................................................. 31 151
3.8.2 Variable header ......................................................................................................................... 32 152
3.8.3 Payload ...................................................................................................................................... 32 153
3.8.4 Response .................................................................................................................................. 33 154
3.9 SUBACK – Subscription acknowledgement ..................................................................................... 34 155
3.9.1 Fixed header.............................................................................................................................. 34 156
3.9.2 Variable header ......................................................................................................................... 35 157
3.9.3 Payload ...................................................................................................................................... 35 158
3.10 UNSUBSCRIBE – Unsubscribe from topics ................................................................................... 35 159
3.10.1 Fixed header............................................................................................................................ 36 160
3.10.2 Variable header ....................................................................................................................... 36 161
3.10.3 Response ................................................................................................................................ 37 162
3.11 UNSUBACK – Unsubscribe acknowledgement.............................................................................. 37 163
3.11.1 Fixed header............................................................................................................................ 37 164
3.11.2 Variable header ....................................................................................................................... 38 165
3.11.3 Payload .................................................................................................................................... 38 166
3.12 PINGREQ – PING request ............................................................................................................. 38 167
3.12.1 Fixed header............................................................................................................................ 38 168
3.12.2 Variable header ....................................................................................................................... 38 169
3.12.3 Payload .................................................................................................................................... 38 170
3.12.4 Response ................................................................................................................................ 39 171
3.13 PINGRESP – PING response ........................................................................................................ 39 172
3.13.1 Fixed header............................................................................................................................ 39 173
3.13.2 Variable header ....................................................................................................................... 39 174
3.13.3 Payload .................................................................................................................................... 39 175
3.14 DISCONNECT – Disconnect notification ........................................................................................ 39 176
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 5 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.14.1 Fixed header............................................................................................................................ 39 177
3.14.2 Variable header ....................................................................................................................... 40 178
3.14.3 Payload .................................................................................................................................... 40 179
3.14.4 Response ................................................................................................................................ 40 180
4 Operational behaviour ........................................................................................................................ 41 181
4.1 Storing state ...................................................................................................................................... 41 182
4.2 Quality of Service levels and flows ................................................................................................... 41 183
4.2.1 QoS 0: At most once delivery .................................................................................................... 41 184
4.2.2 QoS 1: At least once delivery .................................................................................................... 42 185
4.2.3 QoS 2: Exactly once delivery .................................................................................................... 42 186
4.3 Message delivery retry ...................................................................................................................... 43 187
4.4 Message ordering ............................................................................................................................. 44 188
4.5 Topic Names and Topic Filters ......................................................................................................... 45 189
4.5.1 Topic wildcards .......................................................................................................................... 45 190
4.5.2 Topic semantic and usage ........................................................................................................ 46 191
4.6 Handling protocol violations .............................................................................................................. 47 192
5 Security ............................................................................................................................................... 48 193
6 # Conformance ................................................................................................................................... 50 194
6.1 Conformance Targets ....................................................................................................................... 50 195
6.1.1 MQTT Server ............................................................................................................................. 50 196
6.1.2 MQTT Client .............................................................................................................................. 50 197
Appendix A. Title text ............................................................................................................................. 51 198
A.1 Subsidiary section ............................................................................................................................ 51 199
A.1.1 Sub-subsidiary section .............................................................................................................. 51 200
Appendix B. Revision history ................................................................................................................. 52 201
202 Formatted: Normal, Tab stops: Not at 0.55"
Formatted: Bullets and Numbering
Deleted: ¶¶¶¶¶
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 6 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
1 Introduction 208
This specification is split into six main sections: 209
• Introduction and concepts 210
• Control packet format 211
• The specific details of each Control Packet type 212
• Operational behaviour of the Client and Server 213
• Security considerations 214
• Conformance requirements for this version of the specification 215
1.1 Terminology 216
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 217 NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as 218 described in IETF RFC 2119 [RFC2119]. 219
TCP Connection: 220
• Defined in [RFC793] . 221
• Connects the Client to the Server, 222
• Provides the means to send an ordered, lossless, stream of bytes in both directions. 223
224
>>>>>>>>>>Needs to be Generalised to SSSL/Websockets etc. 225 ClientClientClientClient:::: 226
A program that establishes the TCP Connection: 227
The client can: 228
• Publish application Payload Messages that other Clients may be interested in. 229
• Subscribe to request Payload Messages that it is interested in receiving. 230
• Unsubscribe to remove a request for Payload Messages. 231
• Disconnect from the server. 232 ServerServerServerServer:::: 233
Accepts connections from Clients. It is the intermediary between the Client publishing Payload Messages 234 and the Clients which have made Subscriptions. 235 Payload MessagePayload MessagePayload MessagePayload Message:::: 236
The data carried by the MQTT protocol across the network for the application. 237 Payload Messages are transported by MQTT they have an associated Quality of Service and a Topic 238 Name. 239
Deleted: [RFC793]
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 7 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
>>>>> should be Application Message 241 TTTTopic Nameopic Nameopic Nameopic Name:::: 242
The label attached to a Payload Message which is matched against the subscriptions known to the 243 Server. The Payload Message is sent to each client with a matching Subscription. 244 SubscriptionSubscriptionSubscriptionSubscription:::: 245
The request made by a client to receive Payload Messages published by Clients. The Subscription 246 contains a Topic Name which can include wild card characters so that it may match many Topic Names. 247 Session:Session:Session:Session: 248
A stateful interaction between a Client and a Server. Some sessions only last as long as the TCP 249 Connection, others span multiple TCP Connections. 250 MQTTMQTTMQTTMQTT CCCControl ontrol ontrol ontrol PPPPacketacketacketacket:::: 251
The packet of information that MQTT flows across the network, this might contain the “Payload Message”. 252
1.2 Conventions 253
Bits in a byte are labeled 7 through 0. Bit number 7 is the most significant bit, the least significant bit is 254 assigned bit number 0. 255
All 16-bit word presented in this specification is in big-endian order: higher order bytes precede lower 256 order bytes over the wire. A 16-bit word is presented on the wire as Most Significant Byte (MSB), followed 257 by Least Significant Byte (LSB). This is based on IETF RFC 1700. 258
1.3 Normative references 259 [RFC793][RFC793][RFC793][RFC793] 260
Postel, J., "Transmission Control Protocol", STD 7, RFC 793, September 1981. 261 http://www.ietf.org/rfc/rfc793.txt 262 263 [RFC2119][RFC2119][RFC2119][RFC2119] 264
S. Bradner, Key words for use in RFCs to Indicate Requirement Levels. IETF RFC 2119, March 1997. 265 http://www.ietf.org/rfc/rfc2119.txt 266
267 [RFC 3629][RFC 3629][RFC 3629][RFC 3629] 268
F. Yergeau UTF-8, a transformation format of ISO 10646 IETF RFC 3629, November 2003. 269 http://www.ietf.org/rfc/rfc3629.txt 270
271 [Unicode 6.2][Unicode 6.2][Unicode 6.2][Unicode 6.2] Unicode 6.2 specification 272
http://www.unicode.org/versions/Unicode6.2.0 273
274 [RFC 1700][RFC 1700][RFC 1700][RFC 1700] 275
Joyce K. Reynolds, Internet standard STD 2, IETF RFC 1700, October 1994 276
http://tools.ietf.org/html/rfc1700 277
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 8 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
1.4 Non normative references 278
279
[MQTTV31] 280
MQTT V3.1 Protocol Specification. 281
http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html 282 http://www.ibm.com/developerworks/webservices/library/ws-mqtt/index.html. 283 284
1.5 Acknowledgements 285
Secretary: 286 Geoff Brown ([email protected]), M2MI 287
288
289
290
291
292
293
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 9 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
2 MQTT Control Packet format 294
295
The MQTT protocol works by exchanging a series of MQTT Control Packets in a defined way. This 296 section describes the format of these packets. An MQTT Control Packet consists of up to three parts, 297 always in the following order: 298
299
Fixed header, present in all MQTT Control Packet
Variable header, present in some MQTT Control Packet
Payload, present in some MQTT Control Packet
300 301
Unless stated otherwise, if either the server or client receives a Control Packet which does not meet this 302 specification, it MUST disconnect the TCP Connection. 303
2.1 Data representations 304
2.1.1 Integer data values 305
Integer data values are in big-endian order: higher order bytes precede lower order bytes. A 16-bit 306 word is presented on the wire as Most Significant Byte (MSB), followed by Least Significant Byte 307 (LSB). 308
2.1.2 UTF-8 encoded strings 309
Many of the fields in the Control Packets are encoded as UTF-8. UTF-8 [RFC3629] is an efficient 310 encoding of Unicode character-strings that optimizes the encoding of ASCII characters in support of 311 text-based communications. 312
313
In MQTT many of the Control Packets contain components that are defined as UTF-8 encoded 314 strings. Each of these strings is prefixed with a two byte length field that gives the number of bytes in 315 the UTF-8 encoded string itself, as shown in table below. Consequently there is a limit on the size of 316 a string that can be passed in one of these UTF-8 encoded string components; you cannot use a 317 string that would encode to more than 65535 bytes. 318
Unless stated otherwise all UTF-8 encoded strings are 0 to 65535 bytes in length. 319
320
Bit 7 6 5 4 3 2 1 0
Byte 1 String byte length MSB
Byte 2 String byte length LSB
Byte 3 …. UTF-8 Encoded Character Data, if length > 0.
321
Non normative example. 322
For example, the string A� which is LATIN CAPITAL Letter A followed by the code point 323
U+2A6D4 (which represents a CJK IDEOGRAPH EXTENSION B character). 324
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 10 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
325
Bit 7 6 5 4 3 2 1 0
byte 1 Message Length MSB (0x00)
0 0 0 0 0 0 0 0
byte 2 Message Length LSB (0x05)
0 0 0 0 0 1 0 1
byte 3 'A' (0x41)
0 1 0 0 0 0 0 1
byte 4 (0xF0)
1 1 1 1 0 0 0 0
byte 5 (0xAA)
1 0 1 0 1 0 1 0
byte 6 (0x9B)
1 0 0 1 1 0 1 1
byte 7 (0x94)
1 0 0 1 0 1 0 0
326
327
2.2 Fixed header 328
Each MQTT Control Packet contains a fixed header. The table below shows the fixed header format. 329
330
Bit 7 6 5 4 3 2 1 0
Byte 1 MQTT Control Packet type Flags specific to each MQTT Control Packet type
Byte 2… Remaining Length
331
2.2.1 MQTT Control Packet types 332
333
Position: byte 1, bits 7-4. 334
Represented as a 4-bit unsigned value, the values are shown in the table below. 335
336
Name Value Direction of flow
Description
Reserved 0 Forbidden Reserved
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 11 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
CONNECT 1 Client to server Client request to connect to server
CONNACK 2 Server to client Connect acknowledgment
PUBLISH 3 Client to server
or
Server to client
Publish message
PUBACK 4 Client to server
or
Server to client
Publish acknowledgment
PUBREC 5 Client to server
or
Server to client
Publish received (assured delivery part 1)
PUBREL 6 Client to server
or
Server to client
Publish release (assured delivery part 2)
PUBCOMP 7 Client to server
or
Server to client
Publish complete (assured delivery part 3)
SUBSCRIBE 8 Client to server Client subscribe request
SUBACK 9 Server to client Subscribe acknowledgment
UNSUBSCRIBE 10 Client to server Client unsubscribe request
UNSUBACK 11 Server to client Unsubscribe acknowledgment
PINGREQ 12 Client to server PING request
PINGRESP 13 Server to client PING response
DISCONNECT 14 Client to server Client is disconnecting
Reserved 15 Forbidden Reserved
337
2.2.2 Flags 338
The remaining bits[3-0] of byte 1 in the fixed header contain flags specific to each MQTT Control Packet 339 type as detailed in the table below. Where a bit is unused, it must be set to zero and is reserved for 340 future use. If invalid flags are received, the receiver MUST disconnect the TCP connection. 341
342
Control Packet Fixed header flags Bit 3 Bit 2 Bit 1 Bit 0
CONNECT Reserved 0 0 0 0
CONNACK Reserved 0 0 0 0
PUBLISH Used in MQTT Dup QoS QoS RETAIN
PUBACK Reserved 0 0 0 0
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 12 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
PUBREC Reserved 0 0 0 0
PUBREL Used in MQTT Dup 0
1 0
PUBCOMP Reserved 0 0 0 0
SUBSCRIBE Used in MQTT Dup 0 1 0
SUBACK Reserved 0 0 0 0
UNSUBSCRIBE Used in MQTT Dup 0 1 0
UNSUBACK Reserved 0 0 0 0
PINGREQ Reserved 0 0 0 0
PINGRESP Reserved 0 0 0 0
DISCONNECT Reserved 0 0 0 0
343
Dup = Duplicate delivery of Control Packet 344
QoS = Quality of Service 345
RETAIN = Retain flag 346
2.2.2.1 Dup 347
See MQTT Issue-27. 348
Position: byte 1, bit 3. 349
This flag MUST be set to 1 by the client or server when it attempts to re-deliver a PUBLISH, 350 PUBREL, SUBSCRIBE or UNSUBSCRIBE Control Packet. The Dup flag MUST be 0 if QoS 0. If Dup 351 0 then the flow is the first occasion that the client or server has attempted to send the MQTT Control 352 Packet. If Dup 1 then the flow is a re-delivery of an earlier packet. 353
354
Non Normative comment. 355
If 1, the recipient might have previously received the Control Packet it should not treat this flag as an 356 indication that it has previously received the MQTT Control Packet and should not use the Dup flag 357 alone to guarantee to its application that a duplicate message is being redelivered to its application 358 interface. 359
2.2.2.2 QoS 360
Position: byte 1, bit 2-1. 361
This field indicates the level of assurance for delivery of a Payload Message. The QoS levels are 362 shown in the table below. 363
364
QoS value bit 2 bit 1 Description
0 0 0 At most once delivery
1 0 1 At least once delivery
2 1 0 Exactly once delivery
3 1 1 Reserved
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 13 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
2.2.2.3 RETAIN 365
Position: byte 1, bit 0. 366
367
See issue MQTT-10. 368
This flag is only used on the PUBLISH Control Packet. 369
370
If 1, in a PUBLISH packet sent by a client to a server, the server MUST store the publication, so that it 371 can be delivered to future subscribers whose subscriptions match the topic. When a new subscription 372 is established, the last retained message, if any, on each matching topic MUST be sent to the 373 subscriber. 374
375
If 0, in a PUBLISH packet sent by a client to a server, the server does not store the message nor 376 does it remove or replace any existing retained publication. 377
378
When sending a PUBLISH Packet to a client the server MUST set the RETAIN bit to 1 if a message is 379 sent as a result of a new subscription being made by a client. It MUST set the RETAIN bit to 0 when a 380 PUBLISH packet is sent to a client because it matches an established subscription regardless of how 381 the bit was set in the message it received. 382
A server MAY delete a retained message if it receives a message with a zero-length payload and the 383 Retain flag set on the same topic. 384
385
A PUBLISH Packet with a retain flag set to 1 and a payload containing zero bytes will be processed 386 as normal by the server and sent to clients with a subscription matching the topic name. Additionally 387 any existing retained publication with the same topic name will be removed and any future 388 subscribers for the topic will not receive a retained publication. As normal means that the retained bit 389 is not set in the message received by existing clients. 390
391
Non normative comment. 392
Retained messages are useful where publishers send state messages on an irregular basis. A new 393 subscriber will receive the most recent state. 394
395
2.2.3 Remaining Length 396
Position: byte 2. 397
398
The Remaining length is the number of bytes remaining within the current packet, including data in 399 the variable header and the payload. The Remaining Length does not include the bytes used to 400 encode the Remaining Length. 401
402
The Remaining Length is encoded using a variable length encoding scheme which uses a single byte 403 for values up to 127. Larger values are handled as follows. Seven bits of each byte encode the data, 404 and the eighth bit indicates that there are following bytes in the representation. Each byte encodes 405 128 values and a "continuation bit". The maximum number of bytes in the Remaining Length is four. 406
407
Non normative comment. 408
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 14 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
For example, the number 64 decimal is encoded as a single byte, decimal value 64, hex 0x40. The 409 number 321 decimal (= 65 + 2*128) is encoded as two bytes, least significant first. The first byte 410 65+128 = 193. Note that the top bit is set to indicate at least one following byte. The second byte is 2. 411
412
Non normative comment. 413
This allows applications to send packets of size up to 268,435,455 (256 MB). The representation of 414 this number on the wire is: 0xFF, 0xFF, 0xFF, 0x7F. The table below shows the Remaining Length 415 values represented by increasing numbers of bytes. 416
417
Digits From To
1 0 (0x00) 127 (0x7F)
2 128 (0x80, 0x01) 16 383 (0xFF, 0x7F)
3 16 384 (0x80, 0x80, 0x01) 2 097 151 (0xFF, 0xFF, 0x7F)
4 2 097 152 (0x80, 0x80, 0x80, 0x01) 268 435 455 (0xFF, 0xFF, 0xFF, 0x7F)
418
Non normative comment. 419
The algorithm for encoding a non negative integer (X) into the variable length encoding scheme is as 420 follows: 421
do 422
encodedByte = X MOD 128 423
X = X DIV 128 424
// if there are more data to encode, set the top bit of this byte 425
if ( X > 0 ) 426
encodedByte = encodedByte OR 128 427
endif 428
'output' encodedByte 429
while ( X > 0 ) 430
431
Where MOD is the modulo operator (% in C), DIV is integer division (/ in C), and OR is bit-wise or (| in 432
C). 433
434
Non normative comment. 435
The algorithm for decoding the Remaining Length field is as follows: 436
437
multiplier = 1 438
value = 0 439
do 440
encodedByte = 'next byte from stream' 441
value += (encodedByte AND 127) * multiplier 442
multiplier *= 128 443
if (multiplier > 128*128*128) 444
throw Error(Malformed Remaining Length) 445
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 15 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
while ((encodedByte AND 128) != 0) 446
447
where AND is the bit-wise and operator (& in C). 448
449
When this algorithm terminates, value contains the Length. 450
2.3 Variable header 451
Some types of MQTT Control Packets also contain a variable header component. It resides between 452 the fixed header and the payload. The Packet Identifier is common to several packet types 453
2.3.1 Packet identifier 454
Bit 7 6 5 4 3 2 1 0
Packet Identifier MSB
Packet Identifier LSB
455
The variable header component of many of the Control Packet types includes a 2 byte Packet 456 Identifier (PacketId) field. These Control Packets are PUBLISH (where QoS > 0), PUBACK, 457 PUBREC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK. 458
459
A PUBACK, PUBREC, PUBREL Control Packet MUST contain the same PacketId as the PUBLISH 460 Control Packet that initiated the flow. Similarly SUBACK and UNSUBACK MUST contain the PacketId 461 that was used in the corresponding SUBSCRIBE and UNSUBSCRIBE Control Packet respectively. 462
463
A PUBLISH Control Packet MUST NOT contain a PacketId if its QoS value is set to 0. 464
465
SUBSCRIBE, UNSUBSCRIBE, and PUBLISH (in cases where QoS > 0) MUST contain a non-zero 466 16-bit PacketId. Each time a client sends a new packet of one of these types it MUST assign it a 467 currently unused PacketId. If a client resends a particular Control Packet, then it MUST use the same 468 PacketId in subsequent resends of that packet. The PacketId becomes available for reuse after the 469 client has processed the corresponding acknowledgement packet (PUBREC in the case of QoS 2). 470 The same conditions apply to a server when it sends a PUBLISH with QoS > 0. 471
472
Control Packets that contain a Packet Identifier 473
Control packet Packet Identifier field
CONNECT NO
CONNACK NO
PUBLISH YES (If Qos > 0)
PUBACK YES
PUBREC YES
PUBREL YES
PUBCOMP YES
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 16 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
SUBSCRIBE YES
SUBACK YES
UNSUBSCRIBE YES
UNSUBACK YES
PINGREQ NO
PINGRESP NO
DISCONNECT NO
474
475
The client and server assign PacketIds independently of each other. As a result, client server pairs 476 can participate in concurrent message exchanges using the same PacketId. 477
478
Non-Normative comment 479
480
It is possible for a client to send a PUBLISH Control Packet with PacketId 0x0001 and then receive a 481 different PUBLISH with PacketId 0x0001 from its server before it receives a PUBACK for the 482 PUBLISH that it sent. 483
Client server 484 Publish PacketId=0x1234---� 485 --Publish PacketId=0x1234 486 PUBACKPacketId=0x1234---� 487 --PUBACK PacketId=0x1234 488
489
490
2.4 Payload 491
Some MQTT Control Packets contain a payload as the final part of the packet ,as described in section 492 3 493
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 17 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3 MQTT Control Packets 494
3.1 CONNECT – Client requests a connection to a server 495
496
After a TCP/IP [RFC793] connection is established by a client to a server, the first flow from the client 497 to the server MUST be a CONNECT Packet. 498
499
The payload contains one or more encoded fields. They specify a unique client identifier for the client, 500 a Will topic and message and the User Name and Password. All but the client identifier are optional 501 and their presence is determined based on flags in the variable header. 502
3.1.1 Fixed header 503
The fixed header format is shown in the table below. 504
505
bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (1) Reserved
0 0 0 1 0 0 0 0
byte 2… Remaining Length
506
Remaining Length field 507
Remaining Length is the length of the variable header (10 bytes) plus the length of the Payload. As 508 described in section 2.2.3 509
3.1.2 Variable header 510
The variable header for the CONNECT Control Packet consists of four fields in the following order: 511 Protocol Name, Protocol Level, Connect Flags, and Keep Alive Timer. 512
3.1.2.1 Protocol Name 513
514
Description 7 6 5 4 3 2 1 0
Protocol Name
byte 1 Length MSB (0) 0 0 0 0 0 0 0 0
byte 2 Length LSB (4) 0 0 0 0 0 1 0 0
byte 3 ‘M’ 0 1 0 0 1 1 0 1
byte 4 ‘Q’ 0 1 0 1 0 0 0 1
byte 5 ‘T’ 0 1 0 1 0 1 0 0
byte 6 ‘T’ 0 1 0 1 0 1 0 0
515
Deleted: 2.2.32.2.3
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 18 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
The Protocol Name, is a UTF-8 encoded string that represents the protocol name “MQTT”, capitalized 517 as shown. The string, its offset and length will not be changed by future versions of the MQTT 518 specification. 519
520
The server MAY disconnect the client if the protocol name is incorrect. 521
522
Non normative comment 523
Packet inspectors, such as firewalls, can use the Protocol Name to identify MQTT traffic 524
3.1.2.2 Protocol Level 525
Description 7 6 5 4 3 2 1 0
Protocol Level
byte 7 Level(4) 0 0 0 0 0 1 0 0
526
The 8 bit unsigned value that represents the revision level of the protocol used by the client. The 527 value of the Protocol Level field for the current version of the protocol is 4 (0x04). The server MUST 528 respond to the CONNECT packet with a CONNACK return code 0x01 (unacceptable protocol level) 529 and then disconnect the client if the Protocol Level is not supported by the server. 530
531
3.1.2.3 Connect Flags 532
The Connect Flags byte contains a number of parameters specifying the behavior of the MQTT 533 connection. It also indicates the presence or absence of fields in the payload. 534
535
7 6 5 4 3 2 1 0
User Name Flag
Password Flag
Will Retain Will QoS Will Flag Clean Session
Reserved
byte 8 X X X X X X X 0
The server MUST validate that reserved bits are set to zero and disconnect the client if they are not zero. 536
537
3.1.2.3.1 Clean Session 538
Position: bit 1 of the Connect Flags byte. 539
540
See issue MQTT-7 541
If set to 0, the Server resumes communications with the Client based on state from the current 542 Session, otherwise it creates a new Session. The Client and Server will store the Session after the 543 Client and Server are disconnected. The Server will accumulate further QoS 1 and QoS 2 messages 544 that match any subscriptions that the client had at the time of disconnection. 545
546
If set to 1, the Client and Server MUST discard any previous Session and start a new one. This 547 Session lasts as long as the TCP Connection and MUST NOT be reused. 548
549
The Session state in the client consists of: 550
Deleted: n immutable
Formatted: Font: 10 pt, Font color: Auto,Pattern: Clear
Formatted: Font: Bold
Formatted: Indent: Left: 0", First line: 0.25"
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 19 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
• QoS 1 and QoS 2 messages for which transmission to the server is incomplete. 552
• The client MAY store QoS 0 messages for transmission after the connect packet has flowed. 553
554
The Session state in the server consists of: 555
• The client subscriptions which it has acknowledged. 556
• All QoS 1 and QoS 2 messages for which transmission to the client is incomplete. 557
• The server MAY store QoS 0 messages for which transmission is incomplete. 558
559
Retained publications do not form part of the Session state in the server, they MUST NOT be deleted 560 when the Session ends. 561
562
State could be lost by either the client or server due to the storage mechanism used, or an administrator 563 action. This could result in the loss or duplication of messages regardless of the QoS used. 564
565
When Clean Session is set to 1 the client and server need not process the deletion of state atomically. 566
567
Non Normative comment. 568
Consequently in the event of a failure to connect the client should repeat its attempts to connect with 569 Clean Session set to 1, until it connects successfully. 570
571
Non Normative comment. 572
Typically, a client will always connect using CleanSession 0 or CleanSession 1 and not swap between the 573 two values.. The choice will depend on the application. A client using CleanSession 1 will not receive old 574 publications and has to subscribe afresh to any topics that it is interested in each time it connects. A client 575 using CleanSession 0 will receive all QoS 1 or QoS 2 messages that were published whilst it was 576 disconnected. Hence, to ensure that you do not loose messages use QoS 1 or QoS 2 with CleanSession 577 0. 578
579
3.1.2.3.2 Will Flag 580
Position: bit 2 of the Connect Flags. 581
582
The Will Flag indicates that a Will Message MUST be published by the server when the server detects 583 that the client is disconnected for any reason other than the client flowing a DISCONNECT Control 584 Packet. This includes but is not limited to the flowing situations: 585
• An I/O error or network failure detected by the server. 586
• The client fails to communicate within the Keep Alive Timer schedule. 587
• The client disconnects the TCP connection without first sending a DISCONNECT Control Packet. 588
589
If the Will Flag is set to 1, the Will QoS and Will Retain fields in the Connect Flags will be used by the 590 server, and the Will Topic and Will Message fields MUST be present in the payload. 591
592
3.1.2.3.3 Will QoS 593
Position: bits 4 and 3 of the Connect Flags. 594
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 20 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
595
A connecting client specifies the QoS level of the Will message in the Will QoS field. 596
597
If the Will Flag is set to 0, then the Will QoS MUST be set to 0 (0x00). 598
If the will Flag is set to 1, the value of Will QoS can be 0 (0x00), 1 (0x01), or 2 (0x02). 599
3.1.2.3.4 Will Retain 600
Position: bit 5 of the Connect Flags. 601
602
If the Will Flag is set to 0, then the Will Retain Flag MUST be set to 0 603
604
If the Will Flag is set to 1: 605
• If Will Retain is set to 0, the server MUST publish the will message as a non-retained publication. 606
• If Will Retain is set to 1, the server MUST publish the will message as a retained publication. 607
608
3.1.2.3.5 User Name Flag 609
Position: bit 7 of the Connect Flags. 610
611
If the User Name Flag is set to 0, a user name MUST NOT be present in the payload. 612
If the User Name Flag is set to 1, a user name MUST be present in the payload. 613
614
3.1.2.3.6 Password Flag 615
Position: bit 6 of the Connect Flags byte. 616
617
If the Password Flag is set to 0, a password MUST NOT be present in the payload. 618
If the Password Flag is set to 1, a password MUST be present in the payload. 619
If the User Name Flag is set to 0 then the Password Flag MUST be set to 0. 620
621
3.1.2.4 Keep Alive 622
7 6 5 4 3 2 1 0
byte 9 Keep Alive MSB
byte 10 Keep Alive LSB
623
The Keep Alive is a time interval measured in seconds. Expressed as a 16-bit word, it is the maximum 624 time interval that is permitted to elapse between Control Packets sent by a client. 625
626
It is the responsibility of the client to ensure that the interval between Control Packets being sent does not 627 exceed the Keep Alive value. In the absence of sending any other Control Packets, the client MUST send 628 a PINGREQ Control Packet. 629
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 21 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
The client can send PINGREQ at any time and use the PINGRESP to determine that the network and the 630 server are working. 631
632
If the server does not receive a Control Packet from the client within one and a half times the Keep Alive 633 time period, it MUST disconnect the client as if the network had failed. 634
635
If a client does not receive a PINGRESP packet within a reasonable amount of time after it has sent a 636 PINGREQ, it SHOULD close the TCP connection. 637
638
A Keep Alive value of zero (0) has the effect of turning off the keep alive mechanism. 639
640
Non normative comment. 641
The actual value of the Keep Alive is application-specific, typically this is a few minutes. The maximum 642 value is approximately 18 hours. 643
644
3.1.2.5 Variable header example, Non normative 645
646
Description 7 6 5 4 3 2 1 0
Protocol Name
byte 1 Length MSB (0) 0 0 0 0 0 0 0 0
byte 2 Length LSB (4) 0 0 0 0 0 1 0 0
byte 3 ‘M’ 0 1 0 0 1 1 0 1
byte 4 ‘Q’ 0 1 0 1 0 0 0 1
byte 5 ‘T’ 0 1 0 1 0 1 0 0
byte 6 ‘T’ 0 1 0 1 0 1 0 0
Protocol Level
Description 7 6 5 4 3 2 1 0
byte 7 Level (4) 0 0 0 0 0 1 0 0
Connect Flags
byte 8
User Name Flag (1)
Password Flag (1)
Will Retain (0)
Will QoS (01)
Will Flag (1)
Clean Session (1)
Reserved (0)
1
1
0
0
1
1
1
0
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 22 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Keep Alive
byte 9 Keep Alive MSB (0) 0 0 0 0 0 0 0 0
byte 10 Keep Alive LSB (10) 0 0 0 0 1 0 1 0
647
3.1.3 Payload 648
The payload of the CONNECT Control Packet contains one or more length-prefixed fields, whose 649 presence is determined by the flags in the variable header. These fields, if present, MUST appear in the 650 order below. 651
652
3.1.3.1 Client Identifier 653
The Client Identifier (ClientId) MUST be present and is the first field in the payload. 654
655
The ClientId MUST comprise only Unicode characters, and the length of the UTF-8 encoding 656 MUST be at least one byte and no more than 65535 bytes. 657 658 The server MAY restrict the ClientId it allows in terms of their lengths and the characters they 659 contain, however the server MUST allow ClientIds which are 23 or fewer UTF-8 encoded bytes in 660 length, and contain only the characters 661 "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ". 662
If the server rejects the ClientId it MUST respond to the CONNECT packet with a CONNACK 663 return code 0x02 (Identifier rejected) and then terminate the TCP connection. 664
665
The ClientId identifies the client to the server. The ClientId MUST be unique for each client 666 connecting to the server, It can be used by clients and by servers to identify state that they hold 667 relating to this MQTT connection between the client and the server. 668
3.1.3.2 Will Topic 669
If the Will Flag is set to 1, the Will Topic is the next field in the payload. The Will Topic is a UTF-8 670 encoded string. 671
3.1.3.3 Will Message 672
See Issue MQTT-2 673
If the Will Flag is set to 1 the Will Message is the next field in the payload. The Will Message 674 defines the payload content of the message that is published to the Will Topic if the client is 675 disconnected for any reason other than the client sending a DISCONNECT packet. This field 676 consists of a 2-byte length followed by the payload for the Will Message expressed as a 677 sequence of zero or more bytes. The length gives the number of bytes in the payload that follows 678 and does not include the 2 bytes taken up by the length itself. 679
680
When the Will Message is published to the Will Topic its payload consists only of the payload 681 portion of this field, not the first two length bytes. 682
3.1.3.4 User Name 683
If the User Name Flag is set to 1, this is the next field in the payload. User Name is a UTF-8 684 encoded string and can be used by the server for authentication, and authorization. 685
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 23 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.1.3.5 Password 686
If the Password Flag is set to 1, this is the next field in the payload.,Password is a UTF-8 687 encoded string and can be used by the server for authentication of the client 688
3.1.4 Response 689
Note that a server MAY support multiple protocols (including earlier versions of this protocol) on 690 the same TCP port. If the server determines that the protocol is MQTT 3.1.1 then it MUST 691 validate the connection attempt as follows. 692
693
1. If the server does not receive a CONNECT packet within a reasonable amount of time 694 after the TCP connection is established, the server SHOULD close the connection. 695 696
2. The server MUST validate that the CONNECT Packet conforms to section 3.1 and close 697 the TCP connection without sending a CONNACK if it does not conform. 698 699
3. The server MAY check that the contents of the CONNECT Packet meet any further 700 restrictions and MAY perform authentication and authorization checks. If any of these 701 checks fail, it SHOULD send an appropriate CONNACK response with a non zero return 702 code as described in section 3.2 and it MUST close the TCP connection. 703
704
If validation is successful the server MUST perform the following steps. 705
706
1. If the ClientId represents a client already connected to the server then the server MUST 707 disconnect the existing client. 708
709
2. Processing of Clean Session is performed as described in section 3.1.2.3.1. 710
711
3. The server acknowledges the CONNECT Packet with a CONNACK Packet containing a 712 zero return code. 713
714
4. Start message delivery and keep alive monitoring. 715
716
717
Clients are allowed to send further Control Packets immediately after sending a CONNECT 718 packet; clients need not wait for a CONNACK packet to arrive from the server. If the server 719 rejects the CONNECT, it MUST NOT process any data sent by the client after the CONNECT 720 packet. 721 722
Non Normative comment. 723 724 Clients typically wait for a CONNACK Control Packet, However, if the client exploits its freedom to 725 send Control Packets before it receives a CONNACK, it might simplify the client implementation 726 as it does not have to police the connected state. The client accepts that any data that it sends 727 before it receives a CONNACK packet from the server will not be processed if the server rejects 728 the connection. 729
730
731
732
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 24 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.2 CONNACK – Acknowledge connection request 733
734
The CONNACK Control Packet is the packet sent by the server in response to a CONNECT Packet 735 received from a client. The first packet sent from the server to the client MUST be a CONNACK Packet. 736
737
If the client does not receive a CONNACK packet from the server within a reasonable amount of time, the 738 client SHOULD close the TCP connection. A "reasonable" amount of time depends on the type of 739 application and the communications infrastructure. 740
741
3.2.1 Fixed header 742
743
The fixed header format is shown in the table below. 744
745
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet Type (2) Reserved
0 0 1 0 0 0 0 0
byte 2 Remaining Length (2)
0 0 0 0 0 0 1 0
746
Remaining Length field 747
This is the length of the variable header. For the CONNACK Packet this has the value 2. 748
3.2.2 Variable header 749
The variable header format is shown in the table below.- 750
Description 7 6 5 4 3 2 1 0
Reserved for future use
byte 1 0 0 0 0 0 0 0 0
CONNECT Return code
byte 2
751
The values for the one byte unsigned CONNECT Return code field are shown in the table below. 752
753
Value Description
0 Connection accepted
1 Connection refused: Unacceptable protocol level
2 Connection refused: Identifier rejected
3 Connection refused: Server unavailable
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 25 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
4 Connection refused: Bad user name or password
5 Connection refused: Not authorized
6-255 Reserved for future use
754
3.2.3 Payload 755
There is no payload in the CONNACK Packet. 756
757
3.3 PUBLISH – Publish message 758
A PUBLISH Control Packet is sent from a client to a server or from server to a client to transport a 759 Payload Message. 760
3.3.1 Fixed header 761
The table below shows the fixed header format: 762
763
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (3) Dup flag QoS level RETAIN
0 0 1 1 X X X X
byte 2 Remaining Length
764
Dup flag 765
See Dup section 2.2.2.1 for details. 766
767
QoS level 768
See QoS section 2.2.2.2 for details. 769
770
RETAIN flag 771
See Retain section 2.2.2.3 for details. 772
773
Remaining Length field 774
This is the length of variable header plus the length of the payload. 775
776
3.3.2 Variable header 777
The variable header contains the following fields in the order below: 778
3.3.2.1 Topic name 779
The topic name is always present as the first field in the variable header. The topic name identifies the 780 information channel to which payload data is published. 781
782
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 26 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
The Topic name MUST be a UTF-8 encoded string as defined in section 2.1.2. 783
784
The topic name in the PUBLISH Packet received by a subscribing client MUST NOT contain wild card 785 characters. The topic name received will match the subscribers topic filter, it may not be the same as that 786 in the message as published by the publisher. 787
3.3.2.2 Packet Identifier 788
The Packet Identifier (PacketId) field is only present in PUBLISH Packets where the QoS level is 1 or 2. 789 See Packet Identifiers section 2.3.1 for more details. 790
791
3.3.2.3 Variable header example Non Normative 792
793
The table below illustrates an example of variable header for a PUBLISH Packet. 794
795
Field Value
Topic Name a/b
PacketId 10
796
The format of the variable header in this case is shown in the table below. 797
798
Description 7 6 5 4 3 2 1 0
Topic Name
byte 1 Length MSB (0) 0 0 0 0 0 0 0 0
byte 2 Length LSB (3) 0 0 0 0 0 0 1 1
byte 3 ‘a’ (0x61) 0 1 1 0 0 0 0 1
byte 4 ‘/’ (0x2F) 0 0 1 0 1 1 1 1
byte 5 ‘b’ (0x62) 0 1 1 0 0 0 1 0
Packet Identifier
byte 6 PacketId MSB (0) 0 0 0 0 0 0 0 0
byte 7 PacketId LSB (10) 0 0 0 0 1 0 1 0
799
3.3.3 Payload 800
The Payload contains the data for publishing. The content and format of the data is application specific. 801 The length of the payload can be calculated by subtracting the length of the variable header from the 802 Remaining Length field that is in the Fixed Header. It is valid for a PUBLISH packet to contain a zero 803 length payload. 804
805
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 27 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.3.4 Response 806
The response to a PUBLISH Packet depends on the QoS level. The table below shows the expected 807 responses. 808
809
QoS Level Expected Response
QoS 0 None
QoS 1 PUBACK Packet
QoS 2 PUBREC Packet
The Packet Identifier in the PUBACK Packet or PUBREC Packet MUST be the same as that in the 810 PUBLISH Packet. 811
812
3.3.5 Actions 813
The client uses a PUBLISH Packet to send an application message to the server for distribution to clients 814 with matching subscriptions. 815
816
The server uses a PUBLISH Packet to send an application message to clients with matching 817 subscriptions. 818
819
The action of the recipient when it receives a PUBLISH packet depends on the QoS level as described in 820 section 4.2. 821
822
See MQTT issue-52 823
Note that if a server implementation does not authorize a PUBLISH to be performed by a client; it has no 824 way of informing that client. It must therefore make a positive acknowledgement, according to the normal 825 QoS rules, and the client will not be informed that it was not authorized to publish the message. 826
827
3.4 PUBACK – Publish acknowledgement 828
829
A PUBACK Packet is the response to a PUBLISH Packet with QoS level 1. 830
3.4.1 Fixed header 831
The table below shows the format of the fixed header. 832
833
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (4) Reserved
0 1 0 0 0 0 0 0
byte 2 Remaining Length (2)
0 0 0 0 0 0 1 0
834
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 28 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Remaining Length field 835
This is the length of the variable header. For the PUBACK Packet this has the value 2. 836
3.4.2 Variable header 837
838
Contains the Packet Identifier (PacketId) from the PUBLISH Packet that is being acknowledged. The 839 table below shows the format of the variable header. 840
841
Bit 7 6 5 4 3 2 1 0
byte 1 PacketId MSB
byte 2 PacketId LSB
842
3.4.3 Payload 843
There is no payload in the PUBACK Packet. 844
3.4.4 Actions 845
When the sender of a PUBLISH Packet receives a PUBACK Packet it discards the original message. 846
The action of the recipient is fully described in section 4.2. 847
848
3.5 PUBREC – Publish received (QoS 2 publish received, part 1) 849
850
A PUBREC Control Packet is the response to a PUBLISH Packet with QoS 2. It is the second packet of 851 the QoS 2 protocol flow. 852
3.5.1 Fixed header 853
The table below shows the format of the fixed header. 854
855
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (5) Reserved
0 1 0 1 0 0 0 0
byte 2 Remaining Length (2)
0 0 0 0 0 0 1 0
856
Remaining Length field 857
This is the length of the variable header. For the PUBREC Packet this has the value 2. 858
859
3.5.2 Variable header 860
861
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 29 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
The variable header contains the Packet Identifier for the acknowledged PUBLISH Packet. The table 862 below shows the format of the variable header. 863
864
bit 7 6 5 4 3 2 1 0
byte 1 PacketId MSB
byte 2 PacketId LSB
865
3.5.3 Payload 866
There is no payload in the PUBREC Packet. 867
868
3.5.4 Actions 869
When the sender of a PUBLISH Packet receives a PUBREC Packet, it MUST reply with a PUBREL 870 Packet. 871
872
The action of the recipient is fully described in section 4.2. 873
874
3.6 PUBREL – Publish release (QoS 2 publish received, part 2) 875
876
A PUBREL Control Packet is the response to a PUBREC Packet. 877
3.6.1 Fixed header 878
The table below shows the format of the fixed header. 879
880
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (6) Dup flag Reserved
0 1 1 0 0 0 1 0
byte 2 Remaining Length (2)
0 0 0 0 0 0 1 0
881
Dup flag 882
See Dup section 2.2.2.1 for details. 883
884
Bits 2,1,0 of the fixed header are reserved and must be set to 0,1,0. The server MUST treat any other 885 value as malformed and close the TCP Connection. 886
887
Remaining Length field 888
This is the length of the variable header. For the PUBREL Packet this has the value 2. 889
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 30 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.6.2 Variable header 890
The variable header contains the same Packet Identifier as the PUBREC Packet that is being 891 acknowledged. The table below shows the format of the variable header. 892
893
Bit 7 6 5 4 3 2 1 0
byte 1 PacketId MSB
byte 2 PacketId LSB
894
3.6.3 Payload 895
There is no payload in the PUBREL packet. 896
3.6.4 Actions 897
When the sender of a PUBREC Packet receives a PUBREL Packet it MUST reply with a PUBCOMP 898 Packet. 899
900
The action of the recipient is fully described in section 4.2. 901
3.7 PUBCOMP – Publish complete (QoS 2 publish received, part 3) 902
The PUBCOMP Control Packet is the response to a PUBREL Packet. 903
904
3.7.1 Fixed header 905
The table below shows the format of the fixed header. 906
907
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (7) Reserved
0 1 1 1 0 0 0 0
byte 2 Remaining Length (2)
0 0 0 0 0 0 1 0
908
Remaining Length field 909
This is the length of the variable header. For the PUBCOMP Packet this has the value 2. 910
911
3.7.2 Variable header 912
The variable header contains the same Packet Identifier as the acknowledged PUBREL Packet. 913
914
915
916
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 31 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Bit 7 6 5 4 3 2 1 0
byte 1 PacketId MSB
byte 2 PacketId LSB
917
3.7.3 Payload 918
There is no payload in the PUBCOMP Packet. 919
920
3.7.4 Actions 921
When the sender of a PUBREL Packet receives a PUBCOMP Packet it removes any remaining state 922 associated with the original PUBLISH Packet. 923
924
The action of the recipient is fully described in section 4.2. 925
3.8 SUBSCRIBE - Subscribe to topics 926
The SUBSCRIBE Control Packet is sent from the Client to the Server to register an interest in one or 927 more Topics. Payload Messages that match the topic filter are delivered to the Client using a PUBLISH 928 Control Packet. The SUBSCRIBE packet also specifies the maximum QoS with which the server sends 929 publications to the Client. 930
931
3.8.1 Fixed header 932
The table below shows the format of the fixed header. 933
934
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (8) Dup flag Reserved
1 0 0 0 0 0 1 0
byte 2 Remaining Length
935
See MQTT Issue-27 936
Dup flag 937
Set to zero (0). This means that the packet is being sent for the first time. See DUP section 938 2.1.2.1 for more details. 939
940
Bits 2,1,0 of the fixed header are reserved and must be set to 0,1,0. The server MUST treat any other 941 value as malformed and close the TCP Connection. 942
943
Remaining Length field 944
This is the length of variable header (2 bytes) plus the length of the payload. 945
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 32 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.8.2 Variable header 946
The variable header contains a Packet Identifier. See section 2.3.1 for more details. 947
948
3.8.2.1 Variable Header Non Normative example 949
The table below shows an example of the variable header with a Packet Identifier of 10. 950
951
Description 7 6 5 4 3 2 1 0
Packet Identifier
byte 1 Packet Identifier MSB (0) 0 0 0 0 0 0 0 0
byte 2 Packet Identifier LSB (10) 0 0 0 0 1 0 1 0
952
3.8.3 Payload 953
The payload of a SUBSCRIBE Packet contains a list of topic filters to which the Client wants to subscribe. 954 The topic filters are UTF-8 encoded strings. Each filter is followed by a byte giving the maximum QoS 955 level at which the Server sends publications to the Client 956
957
Topic filters MAY contain special wildcard characters to represent a set of topics, see section 4.5.1. 958 These topic filter / QoS pairs are packed contiguously as shown in the example payload in the table 959 below. 960
961
The requested maximum QoS field is encoded in the byte following each UTF-8 encoded topic name as 962 shown in the table below. 963
964
Description 7 6 5 4 3 2 1 0
Topic filter
byte 1 Length MSB
byte 2 Length LSB
byte 3-N Topic filter
Requested QoS
Reserved QoS
byte N+1 0 0 0 0 0 0 X X
965
The upper 6 bits of this byte are not used in the current version of the protocol. They are reserved for 966 future use. 967
968
3.8.3.1 Payload Non Normative Example 969
Topic name “a/b”
Deleted: 4.5
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 33 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Requested QoS 0x01
Topic name “c/d”
Requested QoS 0x02
971
The format of the example payload is shown in the table below. 972
973
Description 7 6 5 4 3 2 1 0
Topic filter
byte 1 Length MSB (0) 0 0 0 0 0 0 0 0
byte 2 Length MSB (3) 0 0 0 0 0 0 1 1
byte 3 ‘a’ (0x61) 0 1 1 0 0 0 0 1
byte 4 ‘/’ (0x2F) 0 0 1 0 1 1 1 1
byte 5 ‘b’ (0x62) 0 1 1 0 0 0 1 0
Requested QoS
byte 6 Requested QoS(1) 0 0 0 0 0 0 0 1
Topic filter
byte 7 Length MSB (0) 0 0 0 0 0 0 0 0
byte 8 Length MSB (3) 0 0 0 0 0 0 1 1
byte 9 ‘c’ (0x63) 0 1 1 0 0 0 1 1
byte 10 ‘/’ (0x2F) 0 0 1 0 1 1 1 1
byte 11 ‘d’ (0x64) 0 1 1 0 0 1 0 0
Requested QoS
byte 12 Requested QoS(2) 0 0 0 0 0 0 1 0
974
3.8.4 Response 975
See MQTT Issues 52,58,59,60. Processing of subscribe requests, sending retained publications, storing 976 subscriptions, starting the flow of publications. 977
978
979
When the Server receives a SUBSCRIBE Packet from a Client, the Server MUST respond with a 980 SUBACK Packet. The SUBACK Packet MUST have the same Packet Identifier as the SUBSCRIBE 981 Packet. 982
983
The Server MAY start sending PUBLISH packets matching the subscription before the Server sends the 984 SUBACK Packet. 985
986
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 34 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
See MQTT Issue-52 987
Note that if a server implementation does not authorize a SUBSCRIBE request to be made by a 988 subscriber, it has no way of informing that subscriber. It MUST therefore make a positive 989 acknowledgement with a SUBACK, and the subscriber will not be informed that it was not authorized to 990 subscribe. 991
992
The SUBACK Packet sent to the Client by the Server contains the maximum QoS for each Topic Filter 993 that the Server will use. The Server might grant a lower level of QoS than the subscriber requested. 994
995
The QoS of Payload Messages sent in response to a subscription MUST be the minimum of the 996 published message and the granted QoS returned by the Server to the Client. 997
998
Non normative comment. 999
For example, if a subscriber has requested QoS 1 for a particular topic filter, then a QoS 0 Message 1000 matching the filter is delivered to the Client at QoS 0. A QoS 2 Message published to the same topic is 1001 downgraded by the Server to QoS 1 for delivery to the Client. 1002
1003
Non normative comment. 1004
A corollary to this is that subscribing to a topic filter at QoS 2 is equivalent to saying "I would like to 1005 receive Messages matching this filter at the QoS with which they were published". This means a publisher 1006 is responsible for determining the maximum QoS a Message can be delivered at, but a subscriber is able 1007 to require that the Server downgrades the QoS to one more suitable for its usage. 1008
1009
3.9 SUBACK – Subscription acknowledgement 1010
1011
A SUBACK Control Packet is sent by the Server to the Client, to confirm receipt and processing of a 1012 SUBSCRIBE packet. 1013
1014
A SUBACK Packet contains a list of granted QoS levels. 1015
3.9.1 Fixed header 1016
The table below shows the fixed header format. 1017
1018
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (9) Reserved
1 0 0 1 0 0 0 0
byte 2 Remaining Length
1019
Remaining Length field 1020
This is the length of variable header (2 bytes) plus the length of the payload. 1021
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 35 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.9.2 Variable header 1022
The variable header contains the Packet Identifier from the SUBSCRIBE Packet that is being 1023 acknowledged. The table below shows the format of the variable header. 1024
1025
7 6 5 4 3 2 1 0
byte 1 Packet Identifier MSB
byte 2 Packet Identifier LSB
3.9.3 Payload 1026
The payload contains a list of granted QoS levels. Each QoS level corresponds to a topic filter in the 1027 SUBSCRIBE Packet being acknowledged. The order of granted QoS levels in the SUBACK Packet 1028 MUST match the order of topic filters in the SUBSCRIBE Packet. 1029
1030
The table below shows the Granted QoS field encoded in a byte. 1031
1032
Description 7 6 5 4 3 2 1 0
Reserved Granted QoS
byte 1 0 0 0 0 0 0 X X
1033
The upper 6 bits of this byte are not used in the current version of the protocol. They are reserved for 1034 future use. 1035
1036
3.9.3.1 Payload Non Normative Example 1037
1038
Granted QoS 0
Granted QoS 2
1039
The payload for this example is shown in the table below. 1040
1041
Description 7 6 5 4 3 2 1 0
byte 1 Granted QoS (0) 0 0 0 0 0 0 0 0
byte 2 Granted QoS (2) 0 0 0 0 0 0 1 0
3.10 UNSUBSCRIBE – Unsubscribe from topics 1042
See MQTT Issue-60,64 1043
An UNSUBSCRIBE Packet is sent by the Client to the Server, to unsubscribe from topics. 1044
1045
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 36 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.10.1 Fixed header 1046
The table below shows an example fixed header format. 1047
1048
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (10) Dup flag Reserved
1 0 1 0 0 0 1 0
byte 2 Remaining Length
See MQTT Issue-27 1049
Dup flag 1050
Set to zero (0). This means that the packet is being sent for the first time. See Dup section 2.1.2.1 1051 for more details. 1052
1053
Bits 2,1,0 of the fixed header are reserved and must be set to 0,1,0. The server MUST treat any other 1054 value as malformed and close the TCP Connection. 1055
1056
Remaining Length field 1057
This is the length of variable header (2 bytes) plus the length of the payload. 1058
3.10.2 Variable header 1059
The variable header contains a Packet Identifier. See section 2.3.1 for more details. 1060
1061
The table below shows the format of the variable header. 1062
1063
7 6 5 4 3 2 1 0
byte 1 Packet Identifier MSB
byte 2 Packet Identifier LSB
1064
3.10.2.1 Payload 1065
The payload for the UNSUBSCRIBE Packet contains the list of topic filters that the Client wishes to 1066 unsubscribe from. The topic filters are UTF-8 string, packed contiguously. 1067
1068
1069
3.10.2.2 Payload Non Normative example 1070
The table below shows an example payload. 1071
1072
Topic filter “a/b”
Topic filter “c/d”
1073
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 37 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
The table below shows the format of this payload. 1074
1075
Description 7 6 5 4 3 2 1 0
Topic Filter
byte 1 Length MSB (0) 0 0 0 0 0 0 0 0
byte 2 Length MSB (3) 0 0 0 0 0 0 1 1
byte 3 ‘a’ (0x61) 0 1 1 0 0 0 0 1
byte 4 ‘/’ (0x2F) 0 0 1 0 1 1 1 1
byte 5 ‘b’ (0x62) 0 1 1 0 0 0 1 0
Topic Filter
byte 6 Length MSB (0) 0 0 0 0 0 0 0 0
byte 7 Length MSB (3) 0 0 0 0 0 0 1 1
byte 8 ‘c’ (0x63) 0 1 1 0 0 0 1 1
byte 9 ‘/’ (0x2F) 0 0 1 0 1 1 1 1
byte 10 ‘d’ (0x64) 0 1 1 0 0 1 0 0
3.10.3 Response 1076
See MQTT Issue-64. 1077
The Server sends an UNSUBACK Packet to the Client in response to an UNSUBSCRIBE Packet. The 1078 UNSUBACK Packet MUST have the same Packet Identifier as the UNSUBSCRIBE Packet. 1079
1080
3.11 UNSUBACK – Unsubscribe acknowledgement 1081
1082
The UNSUBACK Packet is sent by the Server to the Client to confirm receipt and processing of an 1083 UNSUBSCRIBE Packet. 1084
3.11.1 Fixed header 1085
The table below shows the fixed header format. 1086
1087
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (11) Reserved
1 0 1 1 0 0 0 0
byte 2 Remaining Length (2)
0 0 0 0 0 0 1 0
Remaining Length field 1088
This is the length of the variable header. For the UNSUBACK Packet this has the value 2. 1089
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 38 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.11.2 Variable header 1090
The variable header contains the Packet Identifier of the UNSUBSCRIBE packet that is being 1091 acknowledged. The table below shows the format of the variable header. 1092
1093
7 6 5 4 3 2 1 0
byte 1 Packet Identifier MSB
byte 2 Packet Identifier LSB
1094
3.11.3 Payload 1095
There is no payload. 1096
1097
3.12 PINGREQ – PING request 1098
1099
The PINGREQ Packet is sent from a Client to the Server. It can be used to: 1100
1. Indicate to the Server that the Client is alive in the absence of any other Control Packets flowing 1101 from the Client to the Server. 1102
2. Request that the Server responds to confirm that it is alive. 1103
3. Exercise the network to indicate that the TCP Connection is active. 1104
1105
This Packet is used in Keep Alive processing, see section 3.1.2.4 for more details. 1106
1107
3.12.1 Fixed header 1108
The table below shows the fixed header format. 1109
1110
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (12) Reserved
1 1 0 0 0 0 0 0
byte 2 Remaining Length (0)
0 0 0 0 0 0 0 0
1111
3.12.2 Variable header 1112
There is no variable header. 1113
3.12.3 Payload 1114
There is no payload. 1115
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 39 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
3.12.4 Response 1116
See MQTT Ussue-54. 1117
The Server MUST send a PINGRESP Packet in response to a PINGREQ packet. 1118
1119
3.13 PINGRESP – PING response 1120
1121
A PINGRESP Packet is sent by the Server to the Client in response to a PINGREQ Packet, it indicates 1122 that the server is alive. 1123
1124
This Packet is used in Keep Alive processing, see 3.1.2.4 for more details. 1125
1126
3.13.1 Fixed header 1127
The table below shows the fixed header format. 1128
1129
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (13) Reserved
1 1 0 1 0 0 0 0
byte 2 Remaining Length (0)
0 0 0 0 0 0 0 0
1130
3.13.2 Variable header 1131
There is no variable header. 1132
3.13.3 Payload 1133
There is no payload. 1134
1135
3.14 DISCONNECT – Disconnect notification 1136
1137
The DISCONNECT Packet is the final Control Packet sent from the Client to the Server. It indicates that 1138 the Client is disconnecting cleanly. 1139
3.14.1 Fixed header 1140
The table below shows the fixed header format. 1141
1142
Bit 7 6 5 4 3 2 1 0
byte 1 MQTT Control Packet type (14) Reserved
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 40 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
1 1 1 0 0 0 0 0
byte 2 Remaining Length (0)
0 0 0 0 0 0 0 0
The server MUST validate that reserved bits are set to zero and disconnect the client if they are not zero. 1143
3.14.2 Variable header 1144
There is no variable header. 1145
3.14.3 Payload 1146
There is no payload. 1147
3.14.4 Response 1148
After sending a DISCONNECT Packet the Client: 1149
• MUST close the TCP Connection. 1150
• MUST NOT send any more Control Packets on that TCP Connection. 1151
1152
On receipt of DISCONNECT the Server: 1153
• MUST discard the Will Message without publishing it, see 3.1.2.3.2. 1154
• SHOULD close the TCP Connection if the client has not already done so. 1155
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 41 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
4 Operational behaviour 1156
4.1 Storing state 1157
The client and server implement data storage independently and the duration for which data persists can 1158 be different in each. The Client and Server MUST store data for at least as long as the TCP Connection 1159 lasts. Quality of Service guarantees are only valid so long as both client and server store data. Durable 1160 subscriptions and retained publications are only survive as long as the Server stores them. 1161
1162
Non normative comment. 1163
An MQTT user should evaluate the storage capabilities of the MQTT Client and Server implementations 1164 to ensure that they are sufficient for their needs. 1165
1166
For example, a user wishing to gather electricity meter readings may decide that they need to use QoS 1 1167 messages because they need to protect the readings against loss over the network, however they may 1168 decide that the power supply is sufficiently reliable that the data in the Client and Server can be stored in 1169 volatile memory without too much risk of its loss. 1170
1171
Conversely a parking meter payment application provider might decide that there are no circumstances 1172 where a payment message can be lost so they require that all data are force written to non-volatile 1173 memory before it is transmitted across the network. 1174
4.2 Quality of Service levels and flows 1175
1176
MQTT delivers Payload Messages according to the Quality of Service (QoS) levels defined here. The 1177 delivery protocol is symmetric, in the diagrams below the Client and Server can each take the role of 1178 either Sender or Receiver. In the case of the Client, “Deliver Application Message” means give the 1179 message to the application. In the case of the Server it means send a copy of the Message to each Client 1180 with a matching subscription. 1181
4.2.1 QoS 0: At most once delivery 1182
The message is delivered according to the capabilities of the underlying network. No response is sent by 1183 the receiver and no retry is performed by the sender. The message arrives at the receiver either once or 1184 not at all. 1185
1186
The diagram below shows the QoS 0 protocol flow. 1187
1188
Sender Action Control Packet Receiver Action
PUBLISH QoS 0
---------->
Deliver Application Message
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 42 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
4.2.2 QoS 1: At least once delivery 1189
The receiver of a QoS 1 PUBLISH Packet acknowledges receipt with a PUBACK Packet. If the Client 1190 reconnects and the Session is resumed, the sender MUST resend any in flight Qos 1 messages with the 1191 Dup flag set to 1. 1192
1193
See MQTT Issue-68. 1194
or the acknowledgement message is not received after a specified period of time, 1195
1196
The message arrives at the receiver at least once. 1197
1198
A QoS 1 message has a Packet Identifier in its variable header see section 2.3.1. 1199
1200
The diagram below shows the QoS 1 protocol flow. 1201
1202
Sender Action Control Packet Receiver action
Store message
Send PUBLISH QoS 1, Dup 0, <Packet Identifier>
---------->
Initiate onward delivery of the Application Message
1
<---------- Send PUBACK <Packet Identifier>
Discard message
1203
1 The receiver is not required to complete delivery of the Application Message before sending the 1204
PUBACK. In the case of the Server it MUST make sure that it can honour the QoS requirements of the 1205 onward delivery. 1206
1207
See MQTT Issue-27. 1208
When it receives a PUBLISH Packet with Dup set to 1 the receiver MUST perform the same actions as 1209 above which might result in a redelivery of the Application Message. 1210
1211
4.2.3 QoS 2: Exactly once delivery 1212
This is the highest quality of service, for use when neither loss nor duplication of messages are 1213 acceptable. There is an increased overhead associated with this quality of service. 1214
A QoS 2 message has a Packet Identifier in its variable header see section 2.3.1. 1215
1216
The diagram below shows the QoS 2 protocol flow. There are two semantics available for how this flow 1217 should be handled by the receiver. They affect the point within the flow at which the message is made 1218 available for onward delivery. The choice of semantic is implementation specific and does not affect the 1219 guarantees of a QoS 2 flow. 1220
1221
1222
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 43 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Sender Action Control Packet Receiver Action
Store message
PUBLISH QoS 2 <Packet Identifier>
Dup 0
---------->
Store message
or
Store PacketId then Initiate onward delivery of the Application Message
1
PUBREC <Packet Identifier>
<----------
Discard message, Store PUBREC received <Packet Identifier>
PUBREL <Packet Identifier>
---------->
Initiate onward delivery of the Application Message
1 then discard
message
or
Discard Packet Identifier
Send PUBCOMP <Packet Identifier>
<----------
Discard stored state
1 The receiver is not required to complete delivery of the Application Message before sending the 1223
PUBREC or PUBCOMP. In the case of the Server it MUST make sure that it can honour the QoS 1224 requirements of the onward delivery. 1225
See MQTT Issue-68 1226
If a failure is detected, or after a defined time period, the protocol flow is retried from the last 1227 unacknowledged protocol message; either the PUBLISH or PUBREL. See Message delivery retry for 1228 more details. The additional protocol flows ensure that the message is delivered to subscribers once only. 1229
See Issue MQTT-70 1230
4.3 Message delivery retry 1231
In any network, it is possible for devices or communication links to fail. If this happens, one end of the link 1232 might not know what is happening at the other end; these are known as in doubt windows. In these 1233 scenarios assumptions have to be made about the reliability of the devices and networks involved in 1234 message delivery. 1235
1236
When a Client reconnects, if it is not marked clean session, both the client and server MUST redeliver any 1237 previous in-flight messages. 1238
1239
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 44 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
See MQTT Issue-68. 1240
1241
Although TCP normally guarantees delivery of packets, there are certain scenarios where an MQTT 1242 message may not be received. In the case of MQTT messages that expect a response (QoS >0 1243 PUBLISH, PUBREL, SUBSCRIBE, UNSUBSCRIBE), if the response is not received within a certain time 1244 period, the sender may retry delivery. The sender should set the Dup flag on the message. 1245
1246
The retry timeout should be a configurable option. However care must be taken to ensure message 1247 delivery does not timeout while it is still being sent. For example, sending a large message over a slow 1248 network will naturally take longer than a small message over a fast network. Repeatedly retrying a timed-1249 out message could often make matters worse so a strategy of increasing the timeout value across 1250 multiple retries should be used. 1251
1252
Other than this "on reconnect" retry behavior, clients are not required to retry message delivery. Brokers, 1253 however, should retry any unacknowledged message. 1254
1255
4.4 Message ordering 1256
See MQTT Issue-71 1257
Application Messages from a single Client or Server are delivered in order as long as they have the same 1258 QoS and the same Topic Name. The Client or Server MUST respond in the same order that it receives 1259 the inbound Packets for application messages with identical Topic Names and Qos. 1260
1261
Non normative comment. 1262
Message ordering can be affected by a number of factors, including how many in-flight PUBLISH flows a 1263 client allows and whether the client is single- or multi-threaded. For purposes of discussion, clients are 1264 assumed to be single-threaded at the point packets are written to and read from the network. 1265
1266
For an implementation to provide any guarantees regarding the ordering of messages it must ensure 1267 each stage of the message delivery flows are completed in the order they were started. For example, in a 1268 series of QoS level 2 flows, the PUBREL flows must be sent in the same order as the original PUBLISH 1269 flows: 1270
1271
1272
Client Message and direction
Server
PUBLISH 1 ---------->
PUBLISH 2 ---------->
PUBLISH 3 ---------->
<---------- PUBREC 1
<---------- PUBREC 2
PUBREL 1 ---------->
<---------- PUBREC 3
PUBREL 2 ---------->
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 45 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
<---------- PUBCOMP 1
PUBREL 3 ---------->
<---------- PUBCOMP 2
<---------- PUBCOMP 3
1273
The number of in-flight messages permitted also has an effect on the type of guarantees that can be 1274 made: 1275
• With an in-flight window of 1, each delivery flow is completed before the next one starts. This 1276 means that messages are carried between the Client and Server in order. 1277
• With an in-flight window greater than 1, message ordering can only be achieved within the QoS 1278 level. 1279
1280
4.5 Topic Names and Topic Filters 1281
4.5.1 Topic wildcards 1282
A subscription may contain special characters, which allow you to subscribe to multiple topics at once. 1283
1284
The topic level separator is used to introduce structure into the topic, and can therefore be specified 1285 within the topic for that purpose. The multi-level wildcard character and single-level wildcard character 1286 can be used for subscriptions. Wildcard characters MUST NOT be used within a topic name of a 1287 PUBLISH Packet. 1288
4.5.1.1 Topic level separator 1289
The forward slash (‘/’ 0x2F) is used to separate each level within a topic tree and provide a 1290 hierarchical structure to the topic names. The use of the topic level separator is significant when 1291 either of the two wildcard characters are encountered in topic filters specified by subscribing 1292 Clients. 1293
4.5.1.2 Multi-level wildcard 1294
The number sign (‘#’ 0x23) is a wildcard character that matches any number of levels within a topic. 1295
The multi-level wildcard represents the parent and any number of child levels. The multi-level wildcard 1296 character MUST be specified on its own or following a topic level separator, in either case it MUST be the 1297 last character specified in the topic filter. 1298
1299
Non normative comment. 1300
For example, if a Client subscribes to “sport/tennis/nadal/#”, it receives messages published using these 1301 topic names: 1302
1303 “sport/tennis/nadal” 1304 “sport/tennis/nadal/ranking” 1305 “sport/tennis/nadal/score/wimbledon” 1306 1307 1308
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 46 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Non normative comment. 1309
1310
• “sport/#” also matches the singular sport, since # includes the parent level. 1311
• “#” is valid and will receive every publication 1312
• “sport/tennis/#” is valid 1313
• “sport/tennis#” is not valid 1314
• “sport/tennis/#/ranking” is not valid 1315
1316
4.5.1.3 Single level wildcard 1317
The plus sign (‘+’ 0x2B) is a wildcard character that matches only one topic level. 1318
1319
The single-level wildcard can be used at any level in the topic filter. It can be used in conjunction with the 1320 multilevel wildcard. 1321
It MUST be the only character between two topic level separators, or the last level, or on its own. 1322
1323
Non normative comment. 1324
For example, sport/tennis/+ matches sport/tennis/nadal and sport/tennis/murray, but not 1325 sport/tennis/nadal/ranking. Also, because the single-level wildcard matches only a single level, sport/+ 1326 does not match sport. 1327
1328
Non normative comment. 1329
• “+” is valid 1330
• “sport/+” is valid 1331
• “sport+” is not valid 1332
• “sport/+/nadal” is valid 1333
• “/finance” matches "+/+" and "/+", but not "+" 1334
1335
4.5.2 Topic semantic and usage 1336
1337
The following rules apply to topic names and topic filters 1338
See MQTT Issue-44 1339
1340
• A topic names and topic filters MUST be at least one character long 1341
• Topic names and topic filters are case sensitive 1342
• Topic names and topic filters can include the space character 1343
• A leading "/" creates a distinct topic name or topic filter 1344
• Topic names and topic filters MUST NOT include the null character (Unicode \x0000) 1345
• Topic names and topic filters are UTF-8 encoded strings, they MUST NOT encode to more than 1346 65535 bytes. 1347
• There is no limit to the number of levels in a topic name or topic filter. 1348
1349
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 47 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Non normative comment. 1350
• “ACCOUNTS” and “Accounts” are two different topic names 1351
• “Accounts payable” is a valid topic name 1352
• “/finance” is different from “finance” 1353
1354
4.6 Handling protocol violations 1355
See MQTT Issue-8,6,50 etc 1356
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 48 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
5 Security 1357
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 49 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
1358
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 50 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
6 # Conformance 1359
1360
The MQTT specification defines conformance for MQTT Client implementations and MQTT Server 1361 implementations. 1362
1363
A single entity MAY conform as both an MQTT Client and MQTT Server implementation. For example, a 1364 server that both accepts inbound connections and establishes outbound connections to other servers 1365 MUST conform as both an MQTT Client and MQTT Server. 1366
1367
Conformant implementations SHALL NOT require the use of any extensions defined outside of this 1368 specification in order to interoperate with any other conformant implementation. 1369
6.1 Conformance Targets 1370
6.1.1 MQTT Server 1371
1372
An MQTT Server accepts TCP connections from MQTT Clients. 1373
1374
An MQTT Server conforms to this specification if it satisfies all of the MUST level requirements in the 1375 following sections that are identified for the Server: 1376
- [MQTT0001] Section 2 - MQTT Control Packet format 1377
- [MQTT0002] Section 3 - MQTT Control Packets 1378
- [MQTT0003] Section 4 - Operational behaviour 1379
- [MQTT0004] Section 5 - Security 1380
1381
6.1.2 MQTT Client 1382
1383
An MQTT Client creates a TCP connection to an MQTT Server. 1384
1385
An MQTT Client conforms to this specification if it satisfies all of the MUST level requirements in the 1386 following sections that are identified for the Client: 1387
- [MQTT0005] Section 2 - MQTT Control Packet format 1388
- [MQTT0006] Section 3 - MQTT Control Packets 1389
- [MQTT0007] Section 4 - Operational behaviour 1390
- [MQTT0008] Section 5 - Security 1391
1392
Formatted: Heading 2 Char,H2 Char
Formatted: Heading 2,H2
Formatted: Heading 3,H3
Deleted: MQTT is a machine-to-machine connectivity protocol. It is open, lean, reliable, simple and extremely lightweight publish/subscribe messaging transport. Implementations claiming conformance to this specification, MUST implement, at a minimum, all mandatory requirements and provisions set forth in sections 2,3,4 and 5 in this document.¶¶ This specification references a number of other specifications. In order to be conformant with this specification, an implementation MUST implement the portions of referenced specifications necessary to comply with the required provisions of this specification. Conformant implementation MUST NOT require the use of any extensions defined outside this specification in order to interoperate with any other conformant implementation.¶¶Implementation conformance could be validated and tested from conformance sub sections detailed below; following conformance targets are defined in order to support the specification of conformance to this standard:
Deleted: <#>Conformance for the implemented entity¶A conformant implementation MUST either act as a MQTT client or a MQTT Server. MQTT implementations acting in the client SHOULD be capable of being configured to connect to an implementation in the MQTT server role that is following this specification.¶<#>Conformance as a client¶A conformant implementation client MUST act as a MQTT publisher or a MQTT subscriber. Client MUST establish a TCP connection to MQTT server for messaging transport. Once the TCP connection is established with the server, client MUST interact with the server using Control Packets.¶Conformance as a server¶A conformant implementation Server MUST accept TCP connection from a client. Server MUST close the TCP connection incase a malformed Control Packet is received by a client.¶Conformance to Control Packets¶A conformant implementation MUST maintain the integrity of Control Packet. Server MUST ¶Conformance to flow order of Control Packets¶A conformant implementation MUST preserve the flow order of Control Packet ... [1]
Formatted: Heading 3,H3, Indent: Left:
0.44", Hanging: 0.5"
Formatted: Bullets and Numbering
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 51 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Appendix A. Title text 1481
text 1482
A.1 Subsidiary section 1483
text 1484
A.1.1 Sub-subsidiary section 1485
text 1486
mqtt-v3.1.1-wd11 Working Draft 11 10 September 2013 Standards Track Draft Copyright © OASIS Open 2013. All Rights Reserved. Page 52 of 52
Deleted: 0
Deleted: 0
Deleted: 29 August 201327 August 2013
Appendix B. Revision history 1487
1488
Revision Date Editor Changes Made
[02] [29 April 2013] [A Banks] [Tighten up language for Connect packet]
[03] [09 May 2013] [ A Banks] [Tighten up language in Section 02 Command Message Format]
[04] [20 May 2013] [Rahul Gupta] Tighten up language for PUBLISH message
[05] [5th June 2013] [ A Banks]
[Rahul Gupta]
[ Issues -5,9,13 ]
[Formatting and language tighten up in PUBACK, PUBREC, PUBREL, PUBCOMP message]
[06] [20th June 2013] [Rahul Gupta] [Issue – 17, 2, 28, 33]
[Formatting and language tighten up in SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK, PINGREQ, PINGRESP, DISCONNECT Control Packets]
Terms Command message change to Control Packet
Term “message” is generically used, replaced this word accordingly with packet, publication, subscription.
[06] [21 June 2013] [A Banks]
[Rahul Gupta]
Resolved Issues – 12,20,15, 3, 35, 34, 23, 5, 21
Resolved Issues – 32,39, 41
[07] [03 July 2013] [A Banks]
[Rahul Gupta]
Resolved Issues – 18,11,4
Resolved Issues – 26,31,36,37
[08] [19 July 2013] [A Banks]
[Rahul Gupta]
Resolved Issues – 6, 29, 45
Resolved Issues – 36, 25, 24
Added table for fixed header and payload
[09] [01 August 2013] [A Banks] Resolved Issues – 49, 53, 46, 67, 29, 66, 62, 45, 69, 40, 61, 30
[10] [10 August 2013] [A Banks]
[Rahul Gupta]
Resolved Issues – 19, 63, 57, 65, 72
Conformance section added
[11] [10 September 2013]
[A Banks]
[N O'Leary & Rahul Gupta]
Resolved Issues – 56
Updated Conformance section
1489
Deleted: 1 August
Page 50: [1] Deleted Rahul Gupta 9/10/2013 9:59:00 PM
Conformance for the implemented entity
A conformant implementation MUST either act as a MQTT client or a MQTT Server. MQTT implementations acting in the client SHOULD be capable of being configured to connect to an implementation in the MQTT server role that is following this specification.
Conformance as a client
A conformant implementation client MUST act as a MQTT publisher or a MQTT subscriber. Client MUST establish a TCP connection to MQTT server for messaging transport. Once the TCP connection is established with the server, client MUST interact with the server using Control Packets.
Conformance as a server
A conformant implementation Server MUST accept TCP connection from a client. Server MUST close the TCP connection incase a malformed Control Packet is received by a client.
Conformance to Control Packets
A conformant implementation MUST maintain the integrity of Control Packet. Server MUST
Conformance to flow order of Control Packets
A conformant implementation MUST preserve the flow order of Control Packet while delivering payload on required Quality of Service.
Conformance to security guidelines