Abstract: 17 18 MQ Telemetry Transport (MQTT) is a lightweight broker-based publish/subscribe messaging 19
protocol designed to be open, simple, lightweight and easy to implement. These characteristics 20 make it ideal for use in constrained environments, for example, but not limited to: 21
22 o Where the network is expensive, has low bandwidth or is unreliable 23 o When run on an embedded device with limited processor or memory resources 24
25 Features of the protocol include: 26 27
o The publish/subscribe message pattern to provide one-to-many message distribution and 28 decoupling of applications 29
o A messaging transport that is agnostic to the content of the payload 30 o The use of TCP/IP to provide basic network connectivity 31 o Three qualities of service for message delivery: 32
• "At most once", where messages are delivered according to the best efforts of 33 the underlying TCP/IP network. Message loss or duplication can occur. This level 34 could be used, for example, with ambient sensor data where it does not matter if an 35 individual reading is lost as the next one will be published soon after. 36
• "At least once", where messages are assured to arrive but duplicates may occur. 37
• "Exactly once", where message are assured to arrive exactly once. This level 38 could be used, for example, with billing systems where duplicate or lost messages 39 could lead to incorrect charges being applied. 40
o A small transport overhead (the fixed-length header is just 2 bytes), and protocol 41 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: Message Queuing Telemetry Transport
Deleted: 4.0
Deleted: This prose specification is one component of a Work Product which also includes:¶
Deleted: XML schemas: (list file names or directory name)
Deleted: This specification replaces or supersedes:¶<#>MQTT V3.1 Protocol Specification. http://public.dhe.ibm.com/software/dw/webservices/ws-mqtt/mqtt-v3r1.html and http://www.ibm.com/developerworks/webservices/library/ws-mqtt/index.html.¶This specification is related to:¶<#>Related specifications (hyperlink, if available)¶
Deleted: list namespaces declared within this specification
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual 69 Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website. 70
This document and translations of it may be copied and furnished to others, and derivative works that 71 comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, 72 and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice 73 and this section are included on all such copies and derivative works. However, this document itself may 74 not be modified in any way, including by removing the copyright notice or references to OASIS, except as 75 needed for the purpose of developing any document or deliverable produced by an OASIS Technical 76 Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must 77 be followed) or as required to translate it into languages other than English. 78
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors 79 or assigns. 80
This document and the information contained herein is provided on an "AS IS" basis and OASIS 81 DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY 82 WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY 83 OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 84 PARTICULAR PURPOSE. 85
2.2.4 Clean session flag ..................................................................................................................... 11 100
2.2.5 Will flag ...................................................................................................................................... 12 101
2.2.6 Will QoS..................................................................................................................................... 13 102
2.2.7 Will Retain flag........................................................................................................................... 13 103
2.2.8 User name and password flag................................................................................................... 13 104
Single level wildcard ........................................................................................................................... 47 193
Topic semantic and usage...................................................................................................................... 47 194
Appendix B. Title Text ........................................................................................................................... 48 195
This specification is split into three main sections: 205
• The message format that is common to all packet types 206
• The specific details of each packet type 207
• How the packets flow between client and server 208
1.1 Terminology 209
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", 210 "MAY", and "OPTIONAL" in this specification are to be interpreted as described in IETF RFC 2119 [RFC2119]. 211
1.2 Normative References 212
[ASCII] 213 American National Standards Institute, Inc., American National Standard for Information Systems, Coded Character Sets - 7-Bit 214 American National Standard Code for Information Interchange (7-Bit ASCII), ANSI X3.4-1986, March 26, 1986. 215
[RFC2119] 216 S. Bradner, Key words for use in RFCs to Indicate Requirement Levels. IETF RFC 2119, March 1997. 217 http://www.ietf.org/rfc/rfc2119.txt 218
Deleted: <#>Changes¶The following are the changes between MQTT V3 and MQTT V3.1:¶<#>User name and password can now be sent with a CONNECT packet¶<#>New return codes on CONNACK packets, for security problems¶<#>Clarifications that clients are not informed of un-authorized PUBLISH or SUBSCRIBE commands, and that the normal MQTT flow should complete even though the command has not been performed¶<#>Strings in MQTT now support full UTF-8, instead of just the US-ASCII subset¶¶The protocol version number passed with CONNECT packets, is unchanged for this revision, and remains as the "3". Existing MQTT V3 server implementations should be able
The message header for each MQTT command message contains a fixed header. Some messages also 233 require a variable header and a payload. The format for each part of the message header is described in 234 the following sections: 235
2.1 Fixed header 236
The message header for each MQTT command message contains a fixed header. The table below 237 shows the fixed header format. 238
bit 7 6 5 4 3 2 1 0
Byte 1 Message Type DUP flag QoS level RETAIN
Byte 2 Remaining Length
239
Byte 1 240
Contains the Message Type and Flags (DUP, QoS level, and RETAIN) fields 241
242
Byte 2 243
(At least one byte) contains the Remaining Length field 244
245
The fields are described in the following sections. All data values are in big-endian order: higher order 246 bytes precede lower order bytes. A 16-bit word is presented on the wire as Most Significant Byte (MSB), 247 followed by Least Significant Byte (LSB). 248
2.1.1 Message Type 249
Position: byte 1, bits 7-4. 250
Represented as a 4-bit unsigned value. The enumerations for this version of the protocol are shown in the 251 table below. 252
253
Mnemonic Enumeration Description
Reserved 0 Reserved
CONNECT 1 Client request to connect to server
CONNACK 2 Connect acknowledgment
PUBLISH 3 Publish message
PUBACK 4 Publish acknowledgment
PUBREC 5 Publish received (assured delivery part 1)
PUBREL 6 Publish release (assured delivery part 2)
PUBCOMP 7 Publish complete (assured delivery part 3)
The remaining bits of byte 1 contain the fields DUP, QoS, and RETAIN. The bit positions are encoded to 256 represent the flags as shown in the table below. 257
258
Bit position Name Description
3 DUP Duplicate delivery
2-1 QoS Quality of service
0 RETAIN RETAIN flag
259
2.1.2.1 DUP 260
Position: byte 1, bit 3. 261
This flag is set when the client or server attempts to re-deliver a PUBLISH, PUBREL, SUBSCRIBE or 262 UNSUBSCRIBE message. This applies to messages where the value of QoS is greater than zero (0), and 263 an acknowledgment is required. When the DUP bit is set, the variable header includes a Message ID. 264
265
The recipient should treat this flag as a hint as to whether the message may have been previously 266 received. It should not be relied on to detect duplicates. 267
2.1.2.2 QoS 268
Position: byte 1, bit 2-1. 269
This flag indicates the level of assurance for delivery of a PUBLISH message. The QoS levels are shown 270 in the table below. 271
This flag is only used on PUBLISH messages. When a client sends a PUBLISH to a server, if the Retain 283 flag is set (1), the server should hold on to the message after it has been delivered to the current 284 subscribers. 285
286
When a new subscription is established on a topic, the last retained message on that topic should be sent 287 to the subscriber with the Retain flag set. If there is no retained message, nothing is sent. 288
289
This is useful where publishers send messages on a "report by exception" basis, where it might be some 290 time between messages. This allows new subscribers to instantly receive data with the retained, or Last 291 Known Good, value. 292
293
When a server sends a PUBLISH to a client as a result of a subscription that already existed when the 294 original PUBLISH arrived, the Retain flag should not be set, regardless of the Retain flag of the original 295 PUBLISH. This allows a client to distinguish messages that are being received because they were 296 retained and those that are being received "live". 297
298
Retained messages should be kept over restarts of the server. 299
300
A server may delete a retained message if it receives a message with a zero-length payload and the 301 Retain flag set on the same topic. 302
303
2.1.3 Remaining Length 304
Position: byte 2. 305
306
Represents the number of bytes remaining within the current message, including data in the variable 307 header and the payload. 308
309
The variable length encoding scheme uses a single byte for messages up to 127 bytes long. Longer 310 messages are handled as follows. Seven bits of each byte encode the Remaining Length data, and the 311 eighth bit indicates any following bytes in the representation. Each byte encodes 128 values and a 312 "continuation bit". For example, the number 64 decimal is encoded as a single byte, decimal value 64, 313 hex 0x40. The number 321 decimal (= 65 + 2*128) is encoded as two bytes, least significant first. The first 314 byte 65+128 = 193. Note that the top bit is set to indicate at least one following byte. The second byte is 315 2. 316 Deleted: 4.0
The protocol limits the number of bytes in the representation to a maximum of four. 317
318
This allows applications to send messages of up to 268 435 455 (256 MB). The representation of this 319 number on the wire is: 0xFF, 0xFF, 0xFF, 0x7F. The table below shows the Remaining Length values 320 represented by increasing numbers of bytes. 321
Remaining Length encoding is not part of the variable header. The number of bytes used to encode the 352 Remaining Length does not contribute to the value of the Remaining Length. The variable length 353 "extension bytes" are part of the fixed header, not the variable header. 354
355
2.2 Variable header 356
Some types of MQTT command messages also contain a variable header component. It resides between 357 the fixed header and the payload. 358
359
The variable length Remaining Length field is not part of the variable header. The bytes of the Remaining 360 Length field do not contribute to the byte count of the Remaining Length value. This value only takes 361 account of the variable header and the payload. See Fixed header for more information. 362
363
The format of the variable header fields are described in the following sections, in the order in which they 364 must appear in the header: 365
366
2.2.1 Protocol name 367
The protocol name is present in the variable header of a MQTT CONNECT message. This field is a UTF-368 encoded string that represents the protocol name MQIsdp, capitalized as shown. 369
370
2.2.2 Protocol version 371
The protocol version is present in the variable header of a CONNECT message. 372
373
The field is an 8-bit unsigned value that represents the revision level of the protocol used by the client. 374 The value of the Protocol version field for the current version of the protocol, 3 (0x03), is shown in the 375 table below. 376
377
Bit 7 6 5 4 3 2 1 0
Protocol Version
0 0 0 0 0 0 1 1
378
2.2.3 Connect flags 379
The Clean session, Will, Will QoS, and Retain flags are present in the variable header of a CONNECT 380 message. 381
382
2.2.4 Clean session flag 383
Position: bit 1 of the Connect flags byte. 384
385
If not set (0), then the server must store the subscriptions of the client after it disconnects. This includes 386 continuing to store QoS 1 and QoS 2 messages for the subscribed topics so that they can be delivered 387
when the client reconnects. The server must also maintain the state of in-flight messages being delivered 388 at the point the connection is lost. This information must be kept until the client reconnects. 389
390
If set (1), then the server must discard any previously maintained information about the client and treat 391 the connection as "clean". The server must also discard any state when the client disconnects. 392
393
Typically, a client will operate in one mode or the other and not change. The choice will depend on the 394 application. A clean session client will not receive stale information and it must resubscribe each time it 395 connects. A non-clean session client will not miss any QoS 1 or QoS 2 messages that were published 396 whilst it was disconnected. QoS 0 messages are never stored, since they are delivered on a best efforts 397 basis. 398
399
This flag was formerly known as "Clean start". It has been renamed to clarify the fact it applies to the 400 whole session and not just to the initial connect. 401
402
A server may provide an administrative mechanism for clearing stored information about a client which 403 can be used when it is known that a client will never reconnect. 404
405
bit 7 6 5 4 3 2 1 0
User Name Flag
Password Flag
Will Retain Will QoS Will Flag Clean Session
Reserved
X X X X X X X
406
Bit 0 of this byte is not used in the current version of the protocol. It is reserved for future use. 407
2.2.5 Will flag 408
Position: bit 2 of the Connect flags byte. 409
410
The Will message defines that a message is published on behalf of the client by the server when either 411 an I/O error is encountered by the server during communication with the client, or the client fails to 412 communicate within the Keep Alive timer schedule. Sending a Will message is not triggered by the server 413 receiving a DISCONNECT message from the client. 414
415
If the Will flag is set, the Will QoS and Will Retain fields must be present in the Connect flags byte, and 416 the Will Topic and Will Message fields must be present in the payload. 417
418
The format of the Will flag is shown in the table below. 419
420
bit 7 6 5 4 3 2 1 0
User Name Flag
Password Flag
Will Retain Will QoS Will Flag Clean Session
Reserved
X X X X X X X
421
Bit 0 of this byte is not used in the current version of the protocol. It is reserved for future use. 422 Deleted: 4.0
Position: bits 4 and 3 of the Connect flags byte. 424
425
A connecting client specifies the QoS level in the Will QoS field for a Will message that is sent in the 426 event that the client is disconnected involuntarily. The Will message is defined in the payload of a 427 CONNECT message. 428
429
If the Will flag is set, the Will QoS field is mandatory, otherwise its value is disregarded. 430
431
The value of Will QoS is 0 (0x00), 1 (0x01), or 2 (0x02). The Will QoS flag is shown in the table below. 432
433
bit 7 6 5 4 3 2 1 0
User Name Flag
Password Flag
Will Retain Will QoS Will Flag Clean Session
Reserved
X X X 1 X X
434
Bit 0 of this byte is not used in the current version of the protocol. It is reserved for future use. 435
436
2.2.7 Will Retain flag 437
Position: bit 5 of the Connect flags byte. 438
439
The Will Retain flag indicates whether the server should retain the Will message which is published by the 440 server on behalf of the client in the event that the client is disconnected unexpectedly. 441
442
The Will Retain flag is mandatory if the Will flag is set, otherwise, it is disregarded. The format of the Will 443 Retain flag is shown in the table below. 444
445
bit 7 6 5 4 3 2 1 0
User Name Flag
Password Flag
Will Retain Will QoS Will Flag Clean Session
Reserved
X X X X 1 X X
446
Bit 0 of this byte is not used in the current version of the protocol. It is reserved for future use. 447
448
2.2.8 User name and password flag 449
Position: bits 6 and 7 of the Connect flags byte. 450
451
A connecting client can specify a user name and a password, and setting the flag bits signifies that a User 452 Name, and optionally a password, are included in the payload of a CONNECT message. 453
If the User Name flag is set, the User Name field is mandatory; otherwise its value is disregarded. If the 455 Password flag is set, the Password field is mandatory; otherwise its value is disregarded. It is not valid to 456 supply a password without supplying a user name. 457
458
bit 7 6 5 4 3 2 1 0
User Name Flag
Password Flag
Will Retain Will QoS Will Flag Clean Session
Reserved
X X X X X X
459
Bit 0 of this byte is not used in the current version of the protocol. It is reserved for future use. 460
461
2.2.9 Keep alive timer 462
The Keep Alive timer is present in the variable header of a MQTT CONNECT message. 463
464
The Keep Alive timer, measured in seconds, defines the maximum time interval between messages 465 received from a client. It enables the server to detect that the network connection to a client has dropped, 466 without having to wait for the long TCP/IP timeout. The client has a responsibility to send a message 467 within each Keep Alive time period. In the absence of a data-related message during the time period, the 468 client sends a PINGREQ message, which the server acknowledges with a PINGRESP message. 469
470
If the server does not receive a message from the client within one and a half times the Keep Alive time 471 period (the client is allowed "grace" of half a time period), it disconnects the client as if the client had sent 472 a DISCONNECT message. This action does not impact any of the client's subscriptions. See 473 DISCONNECT for more details. 474
475
If a client does not receive a PINGRESP message within a Keep Alive time period after sending a 476 PINGREQ, it should close the TCP/IP socket connection. 477
478
The Keep Alive timer is a 16-bit value that represents the number of seconds for the time period. The 479 actual value is application-specific, but a typical value is a few minutes. The maximum value is 480 approximately 18 hours. A value of zero (0) means the client is not disconnected. 481
482
The format of the Keep Alive timer is shown in the table below. The ordering of the 2 bytes of the Keep 483 Alive Timer is MSB, then LSB (big-endian). 484
The connect return code is sent in the variable header of a CONNACK message. 492
493
This field defines a one byte unsigned return code. The meanings of the values, shown in the tables 494 below, are specific to the message type. A return code of zero (0) usually indicates success. 495
496
Enumeration HEX Meaning
0 0x00 Connection Accepted
1 0x01 Connection Refused: unacceptable protocol version
2 0x02 Connection Refused: identifier rejected
3 0x03 Connection Refused: server unavailable
4 0x04 Connection Refused: bad user name or password
5 0x05 Connection Refused: not authorized
6-255 Reserved for future use
497
bit 7 5 5 4 3 2 1 0
Return Code
498
2.2.11 Topic name 499
The topic name is present in the variable header of an MQTT PUBLISH message. 500
501
The topic name is the key that identifies the information channel to which payload data is published. 502 Subscribers use the key to identify the information channels on which they want to receive published 503 information. 504
505
The topic name is a UTF-encoded string. See the section on MQTT and UTF-8 for more information. 506 Topic name has an upper length limit of 32,767 characters. 507
508
2.3 Payload 509
The following types of MQTT command message have a payload: 510
511
2.3.1 CONNECT 512
The payload contains one or more UTF-8 encoded strings. They specify a unique identifier for the client, 513 a Will topic and message and the User Name and Password to use. All but the first are optional and their 514 presence is determined based on flags in the variable header. 515
The payload contains a list of topic names to which the client can subscribe, and the QoS level. These 519 strings are UTF-encoded. 520
521
2.3.3 SUBACK 522
The payload contains a list of granted QoS levels. These are the QoS levels at which the administrators 523 for the server have permitted the client to subscribe to a particular Topic Name. Granted QoS levels are 524 listed in the same order as the topic names in the corresponding SUBSCRIBE message. 525
526
The payload part of a PUBLISH message contains application-specific data only. No assumptions are 527 made about the nature or content of the data, and this part of the message is treated as a BLOB. 528
529
If you want an application to apply compression to the payload data, you need to define in the application 530 the appropriate payload flag fields to handle the compression details. You cannot define application-531 specific flags in the fixed or variable headers. 532
533
2.4 Message identifiers 534
535
The message identifier is present in the variable header of the following MQTT messages: PUBLISH, 536 PUBACK, PUBREC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK. 537
538
The Message Identifier (Message ID) field is only present in messages where the QoS bits in the fixed 539 header indicate QoS levels 1 or 2. See section on Quality of Service levels and flows for more 540 information. 541
542
The Message ID is a 16-bit unsigned integer that must be unique amongst the set of "in flight" messages 543 in a particular direction of communication. It typically increases by exactly one from one message to the 544 next, but is not required to do so. 545
546
A client will maintain its own list of Message IDs separate to the Message IDs used by the server it is 547 connected to. It is possible for a client to send a PUBLISH with Message ID 1 at the same time as 548 receiving a PUBLISH with Message ID 1. 549
550
The ordering of the two bytes of the Message Identifier is MSB, then LSB (big-endian). 551
552
Do not use Message ID 0. It is reserved as an invalid Message ID. 553
UTF-8 is an efficient encoding of Unicode character-strings that optimizes the encoding of ASCII 558 characters in support of text-based communications. 559
560
In MQTT, strings are prefixed with two bytes to denote the length, as shown in the table below. 561
562
bit 7 6 5 4 3 2 1 0
byte 1 String length MSB
byte 2 String length LSB
byte 3 …. Encoded Character Data
563
String Length is the number of bytes of encoded string characters, not the number of characters. For 564 example, the string OTWP is encoded in UTF-8 as shown in the table below. 565
566
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 (0x04)
0 0 0 0 0 1 0 0
byte 3 'O' (0x4F)
0 1 0 0 1 1 1 1
byte 4 'T' (0x54)
0 1 0 1 0 1 0 0
byte 5 'W' (0x57)
0 1 0 1 0 1 1 1
byte 6 'P' (0x50)
0 1 0 1 0 0 0 0
567
The Java writeUTF() and readUTF() data stream methods use this format. 568
569
2.6 Unused bits 570
Any bits marked as unused should be set to zero (0). 571
The payload of the CONNECT message contains one or more UTF-8 encoded strings, based on the flags 613 in the variable header. The strings, if present, must appear in the following order: 614
The first UTF-encoded string. The Client Identifier (Client ID) is between 1 and 23 characters 619 long, and uniquely identifies the client to the server. It must be unique across all clients 620 connecting to a single server, and is the key in handling Message IDs messages with QoS levels 621 1 and 2. If the Client ID contains more than 23 characters, the server responds to the CONNECT 622 message with a CONNACK return code 2: Identifier Rejected. 623
3.1.3.2 Will Topic 624
If the Will Flag is set, this is the next UTF-8 encoded string. The Will Message is published to the 625 Will Topic. The QoS level is defined by the Will QoS field, and the RETAIN status is defined by 626 the Will RETAIN flag in the variable header. 627
3.1.3.3 Will Message 628
If the Will Flag is set, this is the next UTF-8 encoded string. The Will Message defines the content 629 of the message that is published to the Will Topic if the client is unexpectedly disconnected. This 630 may be a zero-length message. 631
632
Although the Will Message is UTF-8 encoded in the CONNECT message, when it is published to 633 the Will Topic only the bytes of the message are sent, not the first two length bytes. The message 634 must therefore only consist of 7-bit ASCII characters. 635
3.1.3.4 User Name 636
If the User Name flag is set, this is the next UTF-encoded string. The user name identifies the 637 name of the user who is connecting, which can be used for authentication. It is recommended 638 that user names are kept to 12 characters or fewer, but it is not required. 639
640
Note that, for compatibility with the original MQTT V3 specification, the Remaining Length field 641 from the fixed header takes precedence over the User Name flag. Server implementations must 642 allow for the possibility that the User Name flag is set, but the User Name string is missing. This 643 is valid, and connections should be allowed to continue. 644
645
3.1.3.5 Password 646
If the Password flag is set, this is the next UTF-encoded string. The password corresponding to 647 the user who is connecting, this can be used for authentication. It is recommended that 648 passwords are kept to 12 characters or fewer, but it is not required. 649
650
Note that, for compatibility with the original MQTT V3 specification, the Remaining Length field 651 from the fixed header takes precedence over the Password flag. Server implementations must 652 allow for the possibility that the Password flag is set, but the Password string is missing. This is 653 valid, and connections should be allowed to continue. 654
655
3.1.4 Response 656
The server sends a CONNACK message in response to a CONNECT message from a client. 657
658
If the server does not receive a CONNECT message within a reasonable amount of time after the TCP/IP 659 connection is established, the server should close the connection. 660
If the client does not receive a CONNACK message from the server within a reasonable amount of time, 662 the client should close the TCP/IP socket connection, and restart the session by opening a new socket to 663 the server and issuing a CONNECT message. 664
665
In both of these scenarios, a "reasonable" amount of time depends on the type of application and the 666 communications infrastructure. 667
668
If a client with the same Client ID is already connected to the server, the "older" client must be 669 disconnected by the server before completing the CONNECT flow of the new client. 670
671
If the client sends an invalid CONNECT message, the server should close the connection. This includes 672 CONNECT messages that provide invalid Protocol Name or Protocol Version Numbers. If the server can 673 parse enough of the CONNECT message to determine that an invalid protocol has been requested, it 674 may try to send a CONNACK containing the "Connection Refused: unacceptable protocol version" code 675 before dropping the connection. 676
677
3.2 CONNACK – Acknowledge connection request 678
679
The CONNACK message is the message sent by the server in response to a CONNECT request from a 680 client. 681
3.2.1 Fixed header 682
The fixed header format is shown in the table below. 683
684
bit 7 6 5 4 3 2 1 0
byte 1 Message Type (2) DUP flag QoS level RETAIN
0 0 1 0 X X X X
byte 2 Remaining Length (2)
0 0 0 0 0 0 1 0
685
The DUP, QoS and RETAIN flags are not used in the CONNACK message. 686
3.2.2 Variable header 687
The variable header format is shown in the table below. 688 689
The values for the one byte unsigned Connect return code field are shown in the table below. 691
692
Enumeration HEX Meaning
0 0X00 Connection Accepted
1 0X01 Connection Refused: unacceptable protocol version
2 0X02 Connection Refused: identifier rejected
3 0X03 Connection Refused: server unavailable
4 0X04 Connection Refused: bad user name or password
5 0X05 Connection Refused: not authorized
6-255 Reserved for future use
693
Return code 2 (identifier rejected) is sent if the unique client identifier is not between 1 and 23 characters 694 in length. 695
3.2.3 Payload 696
There is no payload. 697
698
3.3 PUBLISH – Publish message 699
700
A PUBLISH message is sent by a client to a server for distribution to interested subscribers. Each 701 PUBLISH message is associated with a topic name (also known as the Subject or Channel). This is a 702 hierarchical name space that defines taxonomy of information sources for which subscribers can register 703 an interest. A message that is published to a specific topic name is delivered to connected subscribers for 704 that topic. 705
706
If a client subscribes to one or more topics, any message published to those topics are sent by the server 707 to the client as a PUBLISH message. 708
709
3.3.1 Fixed header 710
The table below shows the fixed header format. 711
Set to zero (0). This means that the message is being sent for the first time. See DUP for more 718 details. 719
720
RETAIN flag 721
Set to zero. This means do not retain. See Retain for more details. 722
723
Remaining Length field 724
The length of the variable header plus the length of the payload. It can be a multibyte field. 725
726
3.3.2 Variable header 727
The variable header contains the following fields: 728
729
Topic name 730
731
A UTF-encoded string. 732
733
This must not contain Topic wildcard characters. 734
735
When received by a client that subscribed using wildcard characters, this string will be the absolute 736 topic specified by the originating publisher and not the subscription string used by the client. 737
738
Message ID 739
740
Present for messages with QoS level 1 and QoS level 2. See Message identifiers for more details. 741
742
The table below shows an example variable header for a PUBLISH message. 743
744
Field Value
Topic Name: “a/b”
QoS level 1
Message ID: 10
745
The format of the variable header in this case is shown in the table below. 746
Contains the data for publishing. The content and format of the data is application specific. The 755 Remaining Length field in the fixed header includes both the variable header length and the payload 756 length. As such, it is valid for a PUBLISH to contain a 0-length payload. 757
758
3.3.4 Response 759
The response to a PUBLISH message depends on the QoS level. The table below shows the expected 760 responses. 761
762
QoS Level Expected Response
QoS 0 None
QoS 1 PUBACK
QoS 2 PUBREC
763
3.3.5 Actions 764
PUBLISH messages can be sent either from a publisher to the server, or from the server to a subscriber. 765 The action of the recipient when it receives a message depends on the QoS level of the message: 766
767
QoS 0 768
Make the message available to any interested parties. 769
770
QoS 1 771
Log the message to persistent storage, make it available to any interested parties, and return a 772 PUBACK message to the sender. 773
Log the message to persistent storage, do not make it available to interested parties yet, and return 776 a PUBREC message to the sender. 777
778
If the server receives the message, interested parties means subscribers to the topic of the PUBLISH 779 message. If a subscriber receives the message, interested parties means the application on the client 780 which has subscribed to one or more topics, and is waiting for a message from the server. 781
782
See Quality of Service levels and flows for more details. 783
784
Note that if a server implementation does not authorize a PUBLISH to be made by a client, it has no way 785 of informing that client. It must therefore make a positive acknowledgement, according to the normal QoS 786 rules, and the client will not be informed that it was not authorized to publish the message. 787
788
3.4 PUBACK – Publish acknowledgement 789
790
A PUBACK message is the response to a PUBLISH message with QoS level 1. A PUBACK message is 791 sent by a server in response to a PUBLISH message from a publishing client, and by a subscriber in 792 response to a PUBLISH message from the server. 793
794
3.4.1 Fixed header 795
The table below shows the format of the fixed header. 796
797
bit 7 6 5 4 3 2 1 0
byte 1 Message Type (4) DUP flag QoS level RETAIN
0 1 0 0 X X X X
byte 2 Remaining Length (2)
0 0 0 0 0 0 1 0
798
QoS level 799
Not used. 800
801
DUP flag 802
Not used. 803
804
RETAIN flag 805
Not used. 806
807
Remaining Length field 808
This is the length of the variable header (2 bytes). It can be a multibyte field. 809
Contains the Message Identifier (Message ID) for the PUBLISH message that is being acknowledged. 813 The table below shows the format of the variable header. 814
815
bit 7 6 5 4 3 2 1 0
byte 1 Message ID MSB
byte 2 Message ID LSB
816
3.4.3 Payload 817
There is no payload. 818
819
3.4.4 Actions 820
When the client receives the PUBACK message, it discards the original message, because it is also 821 received (and logged) by the server. 822
823
3.5 PUBREC – Assured publish received (part 1) 824
A PUBREC message is the response to a PUBLISH message with QoS level 2. It is the second message 825 of the QoS level 2 protocol flow. A PUBREC message is sent by the server in response to a PUBLISH 826 message from a publishing client, or by a subscriber in response to a PUBLISH message from the server. 827
3.5.1 Fixed header 828
The table below shows the format of the fixed header. 829
This is the length of the variable header (2 bytes). It can be a multibyte field. 842
843
3.5.2 Variable header 844
845
The variable header contains the Message ID for the acknowledged PUBLISH. The table below shows 846 the format of the variable header. 847
848
bit 7 6 5 4 3 2 1 0
byte 1 Message ID MSB
byte 2 Message ID LSB
849
3.5.3 Payload 850
There is no payload. 851
852
3.5.4 Actions 853
When it receives a PUBREC message, the recipient sends a PUBREL message to the sender with the 854 same Message ID as the PUBREC message. 855
856
3.6 PUBREC – Assured publish received (part 2) 857
858
A PUBREL message is the response either from a publisher to a PUBREC message from the server, or 859 from the server to a PUBREC message from a subscriber. It is the third message in the QoS 2 protocol 860 flow. 861
3.6.1 Fixed header 862
The table below shows the format of the fixed header. 863
PUBREL messages use QoS level 1 as an acknowledgement is expected in the form of a 867 PUBCOMP. Retries are handled in the same way as PUBLISH messages. 868
DUP flag 869
Set to zero (0). This means that the message is being sent for the first time. See DUP for more 870 details. 871
872
RETAIN flag 873
Not used. 874
875
Remaining Length field 876
This is the length of the variable header (2 bytes). It can be a multibyte field. 877
878
3.6.2 Variable header 879
The variable header contains the same Message ID as the PUBREC message that is being 880 acknowledged. The table below shows the format of the variable header. 881
882
bit 7 6 5 4 3 2 1 0
byte 1 Message ID MSB
byte 2 Message ID LSB
883
3.6.3 Payload 884
There is no payload. 885
3.6.4 Actions 886
When the server receives a PUBREL message from a publisher, the server makes the original message 887 available to interested subscribers, and sends a PUBCOMP message with the same Message ID to the 888 publisher. When a subscriber receives a PUBREL message from the server, the subscriber makes the 889 message available to the subscribing application and sends a PUBCOMP message to the server. 890
891
3.7 PUBREC – Assured publish received (part 3) 892
893
This message is either the response from the server to a PUBREL message from a publisher, or the 894 response from a subscriber to a PUBREL message from the server. It is the fourth and last message in 895 the QoS 2 protocol flow. 896
3.7.1 Fixed header 897
The table below shows the format of the fixed header. 898
This is the length of the variable header (2 bytes). It can be a multibyte field. 911
912
3.7.2 Variable header 913
The variable header contains the same Message ID as the acknowledged PUBREL message. 914
915
bit 7 6 5 4 3 2 1 0
byte 1 Message ID MSB
byte 2 Message ID LSB
916
3.7.3 Payload 917
There is no payload. 918
919
3.7.4 Actions 920
When the client receives a PUBCOMP message, it discards the original message because it has been 921 delivered, exactly once, to the server. 922
923
3.8 SUBSCRIBE - Subscribe to named topics 924
The SUBSCRIBE message allows a client to register an interest in one or more topic names with the 925 server. Messages published to these topics are delivered from the server to the client as PUBLISH 926 messages. The SUBSCRIBE message also specifies the QoS level at which the subscriber wants to 927 receive published messages. 928
The table below shows the format of the fixed header. 931
932
bit 7 6 5 4 3 2 1 0
byte 1 Message Type (8) DUP flag QoS level RETAIN
1 0 0 0 0 0 1 X
byte 2 Remaining Length
933
QoS level 934
SUBSCRIBE messages use QoS level 1 to acknowledge multiple subscription requests. The 935 corresponding SUBACK message is identified by matching the Message ID. Retries are handled in 936 the same way as PUBLISH messages. 937
938
DUP flag 939
Set to zero (0). This means that the message is being sent for the first time. See DUP for more 940 details. 941
942
RETAIN flag 943
Not used. 944
945
Remaining Length field 946
The length of the payload. It can be a multibyte field. 947
948
3.8.2 Variable header 949
The variable header contains a Message ID because a SUBSCRIBE message has a QoS level of 1. See 950 Message identifiers for more details. 951
952
The table below shows an example format for the variable header with a Message ID of 10. 953
954
Description 7 6 5 4 3 2 1 0
Message Identifier
byte 1 Message ID MSB (0) 0 0 0 0 0 0 0 0
byte 2 Message ID LSB (10) 0 0 0 0 1 0 1 0
955
3.8.3 Payload 956
The payload of a SUBSCRIBE message contains a list of topic names to which the client wants to 957 subscribe, and the QoS level at which the client wants to receive the messages. The strings are UTF-958 encoded, and the QoS level occupies 2 bits of a single byte. The topic strings may contain special Topic 959 wildcard characters to represent a set of topics. These topic/QoS pairs are packed contiguously as shown 960 in the example payload in the table below. 961 Deleted: 4.0
Topic names in a SUBSCRIBE message are not compressed. 963
964
The format of the example payload is shown in the table below. 965
966
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 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) X X X X X X 0 1
Topic Name
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) X X X X X X 1 0
967
Assuming that the requested QoS level is granted, the client receives PUBLISH messages at less than or 968 equal to this level, depending on the QoS level of the original message from the publisher. For example, if 969 a client has a QoS level 1 subscription to a particular topic, then a QoS level 0 PUBLISH message to that 970 topic is delivered to the client at QoS level 0. A QoS level 2 PUBLISH message to the same topic is 971 downgraded to QoS level 1 for delivery to the client. 972
973
A corollary to this is that subscribing to a topic at QoS level 2 is equivalent to saying "I would like to 974 receive messages on this topic at the QoS at which they are published". 975
This means a publisher is responsible for determining the maximum QoS a message can be delivered at, 977 but a subscriber is able to downgrade the QoS to one more suitable for its usage. The QoS of a message 978 is never upgraded. 979
980
The Requested QoS field is encoded in the byte following each UTF-encoded topic name as shown in the 981 table below. 982
The upper 6 bits of this byte are not used in the current version of the protocol. They are reserved for 985 future use. 986
987
A request with both QoS level bits set should be considered an invalid packet and the connection closed. 988
3.8.4 Response 989
When it receives a SUBSCRIBE message from a client, the server responds with a SUBACK message. 990
991
A server may start sending PUBLISH messages due to the subscription before the client receives the 992 SUBACK message. 993
994
Note that if a server implementation does not authorize a SUBSCRIBE request to be made by a client, it 995 has no way of informing that client. It must therefore make a positive acknowledgement with a SUBACK, 996 and the client will not be informed that it was not authorized to subscribe. 997
998
A server may choose to grant a lower level of QoS than the client requested. This could happen if the 999 server is not able to provide the higher levels of QoS. For example, if the server does not provide a 1000 reliable persistence mechanism it may choose to only grant subscriptions at QoS 0. 1001
1002
3.9 SUBACK – Subscription acknowledgement 1003
1004
A SUBACK message is sent by the server to the client to confirm receipt of a SUBSCRIBE message. 1005
1006
A SUBACK message contains a list of granted QoS levels. The order of granted QoS levels in the 1007 SUBACK message matches the order of the topic names in the corresponding SUBSCRIBE message. 1008
1009
3.9.1 Fixed header 1010
The table below shows the fixed header format. 1011
The length of the payload. It can be a multibyte field. 1026
1027
3.9.2 Variable header 1028
The variable header contains the Message ID for the SUBSCRIBE message that is being acknowledged. 1029 The table below shows the format of the variable header. 1030
1031
7 6 5 4 3 2 1 0
byte 1 Message ID MSB
byte 2 Message ID LSB
1032
3.9.3 Payload 1033
The payload contains a vector of granted QoS levels. Each level corresponds to a topic name in the 1034 corresponding SUBSCRIBE message. The order of QoS levels in the SUBACK message matches the 1035 order of topic name and Requested QoS pairs in the SUBSCRIBE message. The Message ID in the 1036 variable header enables you to match SUBACK messages with the corresponding SUBSCRIBE 1037 messages. 1038
1039
The table below shows the Granted QoS field encoded in a byte. 1040
The upper 6 bits of this byte are not used in the current version of the protocol. They are reserved for 1043 future use. 1044
1045
The table below shows an example payload. 1046
1047
Granted QoS 1
Granted QoS 2
1048
The table below shows the format of this payload. 1049
1050
Description 7 6 5 4 3 2 1 0
byte 1 Granted QoS (0) X X X X X X 0 0
byte 2 Granted QoS (2) X X X X X X 1 0
1051
3.10 UNSUBSCRIBE – Unsubscribe from named topics 1052
1053
An UNSUBSCRIBE message is sent by the client to the server to unsubscribe from named topics. 1054
1055
3.10.1 Fixed header 1056
The table below shows an example fixed header format. 1057
1058
bit 7 6 5 4 3 2 1 0
byte 1 Message Type (10) DUP flag QoS level RETAIN
1 0 1 0 0 0 1 X
byte 2 Remaining Length
1059
QoS level 1060
UNSUBSCRIBE messages use QoS level 1 to acknowledge multiple unsubscribe requests. The 1061 corresponding UNSUBACK message is identified by the Message ID. Retries are handled in the 1062 same way as PUBLISH messages. 1063
1064
DUP flag 1065
Set to zero (0). This means that the message is being sent for the first time. See DUP for more 1066 details. 1067
This is the length of the Payload. It can be a multibyte field. 1073
1074
3.10.2 Variable header 1075
The variable header contains a Message ID because an UNSUBSCRIBE message has a QoS level of 1. 1076 See Message identifiers for more details. 1077
1078
The table below shows an example format for the variable header with a Message ID of 10. 1079
1080
Description 7 6 5 4 3 2 1 0
Message Identifier
byte 1 Message ID MSB (0) 0 0 0 0 0 0 0 0
byte 2 Message ID LSB (10) 0 0 0 0 1 0 1 0
1081
The client unsubscribes from the list of topics named in the payload. The strings are UTF-encoded and 1082 are packed contiguously. Topic names in a UNSUBSCRIBE message are not compressed. The table 1083 below shows an example payload. 1084
1085
Topic name “a/b”
Topic name “c/d”
1086
The table below shows the format of this payload. 1087
The server sends an UNSUBACK to a client in response to an UNSUBSCRIBE message. 1090
1091
3.11 UNSUBACK – Unsubscribe acknowledgement 1092
1093
The UNSUBACK message is sent by the server to the client to confirm receipt of an UNSUBSCRIBE 1094 message. 1095
1096
3.11.1 Fixed header 1097
The table below shows the fixed header format. 1098
1099
bit 7 6 5 4 3 2 1 0
byte 1 Message Type (11) DUP flag QoS level RETAIN
1 0 1 1 X X X X
byte 2 Remaining Length (2)
0 0 0 0 0 0 1 0
1100
QoS level 1101
Not used. 1102
1103
DUP flag 1104
Not used. 1105
1106
RETAIN flag 1107
Not used. 1108
1109
Remaining Length field 1110
The length of Variable Header (2 bytes). 1111
3.11.2 Variable header 1112
The variable header contains the Message ID for the UNSUBSCRIBE message that is being 1113 acknowledged. The table below shows the format of the variable header. 1114
The table below shows the fixed header format. 1148
1149
bit 7 6 5 4 3 2 1 0
byte 1 Message Type (13) DUP flag QoS level RETAIN
1 1 0 1 X X X X
byte 2 Remaining Length (0)
0 0 0 0 0 0 0 0
1150
The DUP, QoS, and RETAIN flags are not used. 1151
3.13.2 Variable header 1152
There is no variable header. 1153
3.13.3 Payload 1154
There is no payload. 1155
1156
3.14 DISCONNECT – Disconnect notification 1157
1158
The DISCONNECT message is sent from the client to the server to indicate that it is about to close its 1159 TCP/IP connection. This allows for a clean disconnection, rather than just dropping the line. 1160
1161
If the client had connected with the clean session flag set, then all previously maintained information 1162 about the client will be discarded. 1163
1164
A server should not rely on the client to close the TCP/IP connection after receiving a DISCONNECT. 1165
3.14.1 Fixed header 1166
The table below shows the fixed header format. 1167
1168
bit 7 6 5 4 3 2 1 0
byte 1 Message Type (14) DUP flag QoS level RETAIN
1 1 1 0 X X X X
byte 2 Remaining Length (0)
0 0 0 0 0 0 0 0
1169
The DUP, QoS, and RETAIN flags are not used in the DISCONNECT message. 1170
MQTT delivers messages according to the levels defined in a Quality of Service (QoS). The levels are 1216 described below: 1217
1218
4.1.1 QoS level 0: At most once delivery 1219
The message is delivered according to the best efforts of the underlying TCP/IP network. A response is 1220 not expected and no retry semantics are defined in the protocol. The message arrives at the server either 1221 once or not at all. 1222
1223
The table below shows the QoS level 0 protocol flow. 1224
1225
Client Message and direction Server
QoS = 0 PUBLISH
---------->
Action: Publish message to subscribers
1226
4.1.2 QoS level 1: At least once delivery 1227
The receipt of a message by the server is acknowledged by a PUBACK message. If there is an identified 1228 failure of either the communications link or the sending device, or the acknowledgement message is not 1229 received after a specified period of time, the sender resends the message with the DUP bit set in the 1230 message header. The message arrives at the server at least once. Both SUBSCRIBE and 1231 UNSUBSCRIBE messages use QoS level 1. 1232
1233
A message with QoS level 1 has a Message ID in the message header. 1234
1235
The table below shows the QoS level 1 protocol flow. 1236
If the client does not receive a PUBACK message (either within a time period defined in the application, 1238 or if a failure is detected and the communications session is restarted), the client may resend the 1239 PUBLISH message with the DUP flag set. 1240
1241
When it receives a duplicate message from the client, the server republishes the message to the 1242 subscribers, and sends another PUBACK message. 1243
1244
4.1.3 QoS level 2: Exactly once delivery 1245
Additional protocol flows above QoS level 1 ensure that duplicate messages are not delivered to the 1246 receiving application. This is the highest level of delivery, for use when duplicate messages are not 1247 acceptable. There is an increase in network traffic, but it is usually acceptable because of the importance 1248 of the message content. 1249
1250
A message with QoS level 2 has a Message ID in the message header. 1251
1252
The table below shows the QoS level 2 protocol flow. There are two semantics available for how a 1253 PUBLISH flow should be handled by the recipient. They affect the point within the flow that the message 1254 is made available to the subscribers. The choice of semantic is implementation specific and does not 1255 affect the guarantees of a QoS level 2 flow. 1256
1257
1258
Client Message and direction Server
QoS = 2
DUP = 0
Message ID = x
Action: Store message
PUBLISH
---------->
Action: Store message
or
Actions:
• Store message ID
• Publish message to
• subscribers
PUBREC
<----------
Message ID = x
Message ID = x PUBREL
---------->
Actions:
• Publish message to subscribers
• Delete message
or
Action: Delete message ID
Action: Discard message PUBCOMP
<----------
Message ID = x
1259
If a failure is detected, or after a defined time period, the protocol flow is retried from the last 1260 unacknowledged protocol message; either the PUBLISH or PUBREL. See Message delivery retry for 1261 more details. The additional protocol flows ensure that the message is delivered to subscribers once only. 1262
In any network, it is possible for devices or communication links to fail. If this happens, one end of the link 1264 might not know what is happening at the other end; these are known as in doubt windows. In these 1265 scenarios assumptions have to be made about the reliability of the devices and networks involved in 1266 message delivery. 1267
1268
MQTT assumes that the client and server are generally reliable, and that the communications channel is 1269 more likely to be unreliable. If the client device fails, it is typically a catastrophic failure, rather than a 1270 transient one. The possibility of recovering data from the device is low. Some devices have non-volatile 1271 storage, for example flash ROM. The provision of more persistent storage on the client device protects 1272 the most critical data from some modes of failure. 1273
1274
Beyond the basic failure of the communications link, the failure mode matrix becomes complex, resulting 1275 in more scenarios than the specification for MQTT can handle. 1276
1277
4.2 Message delivery retry 1278
1279
Although TCP normally guarantees delivery of packets, there are certain scenarios where an MQTT 1280 message may not be received. In the case of MQTT messages that expect a response (QoS >0 1281 PUBLISH, PUBREL, SUBSCRIBE, UNSUBSCRIBE), if the response is not received within a certain time 1282 period, the sender may retry delivery. The sender should set the DUP flag on the message. 1283
1284
The retry timeout should be a configurable option. However care must be taken to ensure message 1285 delivery does not timeout while it is still being sent. For example, sending a large message over a slow 1286 network will naturally take longer than a small message over a fast network. Repeatedly retrying a timed-1287 out message could often make matters worse so a strategy of increasing the timeout value across 1288 multiple retries should be used. 1289
1290
When a client reconnects, if it is not marked clean session, both the client and server should redeliver any 1291 previous in-flight messages. 1292
1293
Other than this "on reconnect" retry behavior, clients are not required to retry message delivery. Brokers, 1294 however, should retry any unacknowledged message. 1295
1296
4.3 Message ordering 1297
1298
Message ordering can be affected by a number of factors, including how many in-flight PUBLISH flows a 1299 client allows and whether the client is single- or multi-threaded. For purposes of discussion, clients are 1300 assumed to be single-threaded at the point packets are written to and read from the network. 1301
1302
For an implementation to provide any guarantees regarding the ordering of messages it must ensure 1303 each stage of the message delivery flows are completed in the order they were started. For example, in a 1304 series of QoS level 2 flows, the PUBREL flows must be sent in the same order as the original PUBLISH 1305 flows: 1306
The number of in-flight messages permitted also has an effect on the type of guarantees that can be 1310 made: 1311
• With an in-flight window of 1, each delivery flow is completed before the next one starts. This 1312 guarantees messages are delivered in the order they were submitted. 1313
• With an in-flight window greater than 1, message ordering can only be guaranteed within the QoS 1314 level. 1315
1316
4.4 Topic wildcards 1317
A subscription may contain special characters, which allow you to subscribe to multiple topics at once. 1318
1319
The topic level separator is used to introduce structure into the topic, and can therefore be specified 1320 within the topic for that purpose. The multi-level wildcard and single-level wildcard can be used for 1321 subscriptions, but they cannot be used within a topic by the publisher of a message. 1322
The forward slash (/) is used to separate each level within a topic tree and provide a hierarchical 1324 structure to the topic space. The use of the topic level separator is significant when the two 1325 wildcard characters are encountered in topics specified by subscribers. 1326
Multi-level wildcard 1327
The number sign (#) is a wildcard character that matches any number of levels within a topic. For 1328 example, if you subscribe to finance/stock/ibm/#, you receive messages on these topics: 1329
The multi-level wildcard can represent zero or more levels. Therefore, finance/# can also match the 1335 singular finance, where # represents zero levels. The topic level separator is meaningless in this context, 1336 because there are no levels to separate. 1337
1338
The multi-level wildcard can be specified only on its own or next to the topic level separator character. 1339 Therefore, # and finance/# are both valid, but finance# is not valid. The multi-level wildcard must be the 1340 last character used within the topic tree. For example, finance/# is valid but finance/#/closingprice is not 1341 valid. 1342
1343
Single level wildcard 1344
The plus sign (+) is a wildcard character that matches only one topic level. For example, finance/stock/+ 1345 matches finance/stock/ibm and finance/stock/xyz, but not finance/stock/ibm/closingprice. Also, because 1346 the single-level wildcard matches only a single level, finance/+ does not match finance. 1347
1348
The single-level wildcard can be used at any level in the topic tree, and in conjunction with the multilevel 1349 wildcard. It must be used next to the topic level separator, except when it is specified on its own. 1350 Therefore, + and finance/+ are both valid, but finance+ is not valid. The single-level wildcard can be used 1351 at the end of the topic tree or within the topic tree. For example, finance/+ and finance/+/ibm are both 1352 valid. 1353
1354
1355
1356
Topic semantic and usage 1357
1358
When you build an application, the design of the topic tree should take into account the following 1359 principles of topic name syntax and semantics: 1360
1361
• A topic must be at least one character long. 1362
• Topic names are case sensitive. For example, ACCOUNTS and Accounts are two different 1363 topics. 1364
• Topic names can include the space character. For example, Accounts payable is a valid topic. 1365 Deleted: 4.0
Deleted: <#>Topic wildcards¶A subscription may contain special characters, which allow you to subscribe to multiple topics at once.¶¶The topic level separator is used to introduce structure into the topic, and can therefore be specified within the topic for that purpose. The multi-level wildcard and single-level wildcard can be used for subscriptions, but they cannot be used within a topic by the publisher of a message.¶Topic level separator¶The forward slash (/) is used to separate each level within a topic tree and provide a hierarchical structure to the topic space. The use of the topic level separator is significant when the two wildcard characters are encountered in topics specified by subscribers.¶Multi-level wildcard¶The number sign (#) is a wildcard character that matches any number of levels within a topic. For example, if you subscribe to finance/stock/ibm/#, you receive messages on these topics:¶¶finance/stock/ibm¶finance/stock/ibm/closingprice¶finance/stock/ibm/currentprice¶
¶The multi-level wildcard can represent zero or more levels. Therefore, finance/# can also match the singular finance, where # represents zero levels. The topic level separator is meaningless in this context, because there are no levels to separate.¶¶The multi-level wildcard can be specified only on its own or next to the topic level separator character. Therefore, # and finance/# are both valid, but finance# is not valid. The multi-level wildcard must be the last character used within the topic tree. For example, finance/# is valid but finance/#/closingprice is not valid.¶¶Single level wildcard¶The plus sign (+) is a wildcard
The following are the changes between MQTT V3 and MQTT V3.1:
User name and password can now be sent with a CONNECT packet
New return codes on CONNACK packets, for security problems
Clarifications that clients are not informed of un-authorized PUBLISH or SUBSCRIBE commands, and that the normal MQTT flow should complete even though the command has not been performed
Strings in MQTT now support full UTF-8, instead of just the US-ASCII subset
The protocol version number passed with CONNECT packets, is unchanged for this revision, and remains as the "3". Existing MQTT V3 server implementations should be able to accept connections from clients that support this revision, as long as they correctly respect the "Remaining Length" field, and therefore ignore the extra security information.
A subscription may contain special characters, which allow you to subscribe to multiple topics at once.
The topic level separator is used to introduce structure into the topic, and can therefore be specified within the topic for that purpose. The multi-level wildcard and single-level wildcard can be used for subscriptions, but they cannot be used within a topic by the publisher of a message.
Topic level separator
The forward slash (/) is used to separate each level within a topic tree and provide a hierarchical structure to the topic space. The use of the topic level separator is significant when the two wildcard characters are encountered in topics specified by subscribers.
Multi-level wildcard
The number sign (#) is a wildcard character that matches any number of levels within a topic. For example, if you subscribe to finance/stock/ibm/#, you receive messages on these topics:
The multi-level wildcard can represent zero or more levels. Therefore, finance/# can also match the singular finance, where # represents zero levels. The topic level separator is meaningless in this context, because there are no levels to separate.
The multi-level wildcard can be specified only on its own or next to the topic level separator character. Therefore, # and finance/# are both valid, but finance# is not valid. The multi-level wildcard must be the last character used within the topic tree. For example, finance/# is valid but finance/#/closingprice is not valid.
Single level wildcard
The plus sign (+) is a wildcard character that matches only one topic level. For example, finance/stock/+ matches finance/stock/ibm and finance/stock/xyz, but not finance/stock/ibm/closingprice. Also, because the single-level wildcard matches only a single level, finance/+ does not match finance.
The single-level wildcard can be used at any level in the topic tree, and in conjunction with the multilevel wildcard. It must be used next to the topic level separator, except when it is specified on its own. Therefore, + and finance/+ are both valid, but finance+ is not valid. The single-level wildcard can be used at the end of the topic tree or within the topic tree. For example, finance/+ and finance/+/ibm are both valid.
Topic semantic and usage
When you build an application, the design of the topic tree should take into account the following principles of topic name syntax and semantics:
A topic must be at least one character long.
Topic names are case sensitive. For example, ACCOUNTS and Accounts are two different topics.
Topic names can include the space character. For example, Accounts payable is a valid topic.
A leading "/" creates a distinct topic. For example, /finance is different from finance. /finance matches "+/+" and "/+", but not "+".
Do not include the null character (Unicode \x0000) in any topic.
The following principles apply to the construction and content of a topic tree:
The length is limited to 64k but within that there are no limits to the number of levels in a topic tree.
There can be any number of root nodes; that is, there can be any number of topic trees.
