MQTT Developer Guide

1. Introduction

MQTT (Message Queuing Telemetry Protocol) is a PUBLISH-SUBSCRIBE network protocol that would be used for the transport of telemetry data. It supports unreliable networks, bi-directional connections, low bandwidth resources, and reliable message delivery. The MQTT is based on two things that are the MQTT broker and the MQTT clients. An MQTT broker acts as an inter-mediator, it receives all the messages from the publishers (MQTT clients) and then routes the messages to the suitable subscribers (MQTT clients). An MQTT client is a device that runs an MQTT library and connects the MQTT broker over a TCP/IP.

2. MQTT Data Representation

MQTT is a binary-based protocol. The control elements are not text strings whereas binary bytes. In MQTT, all the commands have a related acknowledgment.

 

2.1 Bits

Bits in a byte are flagged 7 to 0. Bit number 0 is the least significant bit and Bit number 7 is the most significant bit.

2.2 Two Byte Integer

The 16-bit unsigned integers in big-endian order are the two Byte Integer data values. i.e, The higher-order byte (MSB-Most Significant B) is followed by the lower-order byte (LSB-Least Significant Bit).

higher-order byte (MSB-Most Significant Bit) is followed by the next higher-order byte (MSB-Most Significant Bit), followed by the next higher-order byte (MSB-Most Significant Byte), followed by the lower-order byte (LSB-Least Significant Bit).

2.3 Four Byte Integer

The 32-bit unsigned integers in big-endian order are the two Byte Integer data values. i.e, The higher-order byte (MSB-Most Significant Bit) is followed by the next higher-order byte (MSB-Most Significant Bit), followed by the next higher-order byte (MSB-Most Significant Byte), followed by the lower-order byte (LSB-Least Significant Bit).

2.4 UTF-8 Encoded String structure

UTF-8 is the encryption method for Unicode. It can translate any Unicode character to a unique binary string that can be matched and can translate the binary string back to Unicode characters. The UTF-8 encoded string maximum size is 65,535  bytes and also it ranges from 0 to 65,535 bytes. The text fields in the MQTT control packets described later are encrypted as UTF-8 strings. In specific, the character data should not include encryption of code points between U+D800 and U+DFFF, and the null character encryption of code points is U+0000. If the client or server receives an MQTT control packet containing incorrectly generated UTF-8, then it is considered a false packet.

  • U+0001..U+001F control characters

  • U+007F..U+009F control characters

  • Code points defined in the Unicode specification are non-characters (for example U+0FFFF)

Bit

7

6

5

4

3

2

1

0

byte 1

String length MSB

byte 2

String length LSB

byte 3 ….

UTF-8 encoded character data, if length > 0.

Bit

7

6

5

4

3

2

1

0

byte 1

String Length MSB (0x00)

0

0

0

0

0

0

0

0

byte 2

String 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

 

2.5 Variable Byte Integer size

It uses a single byte value up to 127. Using Encoding Scheme the variable byte integer is encoded. In LSB, the 7 bits of each byte encoded the data and the MSB is used to specify whether the bytes in the representation are as follows. Thus, each byte encodes 128 values and it is a “continuation bit”. In the Variable Byte Integer field, the maximum number of bytes is four. Use the minimum number of bytes required to denote the coded value.

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)

 

2.6 Binary Data

Binary data is denoted by the full length of two bytes, which refers to the number of bytes of data, followed by that number of bytes. Thus, the length of binary data is ranged from 0 to 65,535 bytes.

3.MQTT Control Packet Format

 

3.1 Packet Structure

The MQTT protocol works by exchanging consecutive MQTT control packets in a defined way. This section describes the format of these packets. An MQTT control packet structure consists of three parts, which are shown in the below table.

MQTT control packet structure

Fixed Header, present in all MQTT Control Packets

Variable Header, present in some MQTT Control Packets

Payload, present in some MQTT Control Packets

 

3.1.1 Fixed Header

The below table consists of the fixed header which could be contained in each MQTT control packet.

Fixed Header format

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

3.1.2 MQTT Control Packet Type

The bits [7-4] of byte 1 in the fixed header contain the control packet types. In MQTT control packet types are represented as a 4-bit Unsigned value, these values are shown in the below table.

MQTT control packet types

Name

Value

Direction of flow

Description

Reserved

0

Forbidden

Reserved

CONNECT

1

Client to Server

Connection request

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 (QoS 1)

PUBREC

5

Client to Server or

Server to Client

Publish received (QoS 2 delivery part 1)

PUBREL

6

Client to Server or

Server to Client

Publish release (QoS 2 delivery part 2)

PUBCOMP

7

Client to Server or

Server to Client

Publish complete (QoS 2 delivery part 3)

SUBSCRIBE

8

Client to Server

Subscribe request

SUBACK

9

Server to Client

Subscribe acknowledgment

UNSUBSCRIBE

10

Client to Server

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 or

Server to Client

Disconnect notification

AUTH

15

Client to Server or Server to Client

Authentication exchange

3.1.3 Flags

The bits [3-0] of byte 1 is the fixed header that contains specific flags for every MQTT control packet as shown below. If a flag bit is marked as “Reserved” it should be reserved for future use and set the listed value. If invalid flags are received, then it is considered a false packet.

Flag bits

MQTT 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 v5.0

DUP

        QoS

RETAIN

PUBACK

Reserved

0

0

0

0

PUBREC

Reserved

0

0

0

0

PUBREL

Reserved

0

0

1

0

PUBCOMP

Reserved

0

0

0

0

SUBSCRIBE

Reserved

0

0

1

0

SUBACK

Reserved

0

0

0

0

UNSUBSCRIBE

Reserved

0

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

AUTH

Reserved

0

0

0

0

 

3.1.4 Remaining Length

The position starts at byte 2. The remaining length is a  variable byte integer, which refers to the number of bytes remaining in the current control packet, including data in the variable header and payload. No bytes are used to encode the remaining length. The total number of bytes in an MQTT control packet is the packet size, which is equal to the length of the fixed header and the remaining length.

3.2 Variable Header

Some MQTT control packets have a variable header component. This is between the Fixed Header and the Payload. The content of the variable header will vary depending on the type of packet. The packet identifier field of the variable header is common to many packet types.

3.2.1 Packet Identifier

Two-byte integer packet identifier fields are included in the variable header component of many MQTT control packets. These MQTT control packets are PUBLISH, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK. MQTT control packets that contain a packet identifier shown in the below table.

MQTT Control Packet

Packet Identifier field

CONNECT

NO

CONNACK

NO

PUBLISH

YES (If QoS > 0)

PUBACK

YES

PUBREC

YES

PUBREL

YES

PUBCOMP

YES

SUBSCRIBE

YES

SUBACK

YES

UNSUBSCRIBE

YES

UNSUBACK

YES

PINGREQ

NO

PINGRESP

NO

DISCONNECT

NO

AUTH

NO

A publish packet should not have a packet identifier if its QOS value is set to 0. Each time a client sends a new SUBSCRIBE, UNSUBSCRIBE or PUBLISH MQTT control packet (QoS>0), it must assign the currently unused zero packet identifier. Each time a server sends a new PUBLISH MQTT control packet with (QoS>0), must assign it a currently unused zero packet identifier.

The packet identifier is available for reuse after the sender activates the corresponding approval packet defined as follows. In the case of QoS1 PUBLISH, it is the corresponding PUBACK; for QoS2 releases, it is either PUBCOMP or PUBREC with a reason code of 128 or higher. This is the SUBACK or UNSUBACK related to SUBSCRIBE and UNSUBSCRIBE. A PUBACK, PUBREL or PUBCOMP packet must have the same packet identifier as the original PUBLISH packet. A SUBACK and UNSUBACK must have a packet identifier used in the corresponding SUBSCRIBE and UNSUBSCRIBE.

                                                           Client                                                             Server

                       PUBLISH Packet Identifier=0x1234 ——>

                                                                                                                       <—— PUBLISH Packet Identifier=0x1234

                       PUBACK Packet Identifier=0x1234 ——>

                                                                                                                       <—— PUBACK Packet Identifier=0x1234

 

The packet identifiers used with the PUBLISH, SUBSCRIBE, and UNSUBSCRIBE packets generate separate and integrated identifiers for the client and server distinctly in one session. At any time, a packet identifier can not be used by more than one command. The client and the server assign packet identifiers to each other independently. As a result, client-server pairs can participate in simultaneous messaging using the same packet identifiers.

3.2.2 Properties

The property set is the last field in the variable header of the MQTT control packets such as CONNECT, CONNACK, PUBLISH, PUBACK, PUBREEC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK, DISCONNECT, and AUTH. In the CONNECT packet, there is a Will properties field with the payload, which is considered as an optional set of properties. The set of properties is made up of a property length, followed by properties.

 
3.2.2.1 Property Length

The property length variable is encoded as a byte integer. The property length does not contain the bytes used to encrypt itself but also the length of the attribute. If there are no properties it should be denoted by adding the property length of zero.

3.2.2.2 Property

Property has an identifier that defines its use and data type followed by a value. The identifier is encoded as a variable byte. A false packet is when a control packet has an invalid identifier for its packet type or does not have the value of a specific data type. If obtained, use a CONNACK or DISCONNECT packet with the Reason code (0X81) described as an invalid packet. There is no importance in the order of properties with different identifiers.

Properties

Identifier

Name (usage)

Type

Packet / Will Properties

Dec

Hex

1

0x01

Payload Format Indicator

Byte

PUBLISH, Will Properties

2

0x02

Message Expiry Interval

Four Byte Integer

PUBLISH, Will Properties

3

0x03

Content Type

UTF-8 Encoded String

PUBLISH, Will Properties

8

0x08

Response Topic

UTF-8 Encoded String

PUBLISH, Will Properties

9

0x09

Correlation Data

Binary Data

PUBLISH, Will Properties

11

0x0B

Subscription Identifier

Variable Byte Integer

PUBLISH, SUBSCRIBE

17

0x11

Session Expiry Interval

Four Byte Integer

CONNECT, CONNACK, DISCONNECT

18

0x12

Assigned Client Identifier

UTF-8 Encoded String

CONNACK

19

0x13

Server Keep Alive

Two Byte Integer

CONNACK

21

0x15

Authentication Method

UTF-8 Encoded String

CONNECT, CONNACK, AUTH

22

0x16

Authentication Data

Binary Data

CONNECT, CONNACK, AUTH

23

0x17

Request Problem Information

Byte

CONNECT

24

0x18

Will Delay Interval

Four Byte Integer

Will Properties

25

0x19

Request Response Information

Byte

CONNECT

26

0x1A

Response Information

UTF-8 Encoded String

CONNACK

28

0x1C

Server Reference

UTF-8 Encoded String

CONNACK, DISCONNECT

31

0x1F

Reason String

UTF-8 Encoded String

CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT, AUTH

33

0x21

Receive Maximum

Two Byte Integer

CONNECT, CONNACK

34

0x22

Topic Alias Maximum

Two Byte Integer

CONNECT, CONNACK

35

0x23

Topic Alias

Two Byte Integer

PUBLISH

36

0x24

Maximum QoS

Byte

CONNACK

37

0x25

Retain Available

Byte

CONNACK

38

0x26

User Property

UTF-8 String Pair

CONNECT, CONNACK, PUBLISH, Will Properties, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBSCRIBE, SUBACK, UNSUBSCRIBE, UNSUBACK, DISCONNECT, AUTH

39

0x27

Maximum Packet Size

Four Byte Integer

CONNECT, CONNACK

40

0x28

Wildcard Subscription Available

Byte

CONNACK

41

0x29

Subscription Identifier Available

Byte

CONNACK

42

0x2A

Shared Subscription Available

Byte

CONNACK

 

3.3 Payload

The payload is the final part of the packet in some of the MQTT control packets. In the PUBLISH packet, the payload is the application message. MQTT control packets that require a payload.

MQTT Control Packet

Payload

CONNECT

Required

CONNACK

None

PUBLISH

Optional

PUBACK

None

PUBREC

None

PUBREL

None

PUBCOMP

None

SUBSCRIBE

Required

SUBACK

Required

UNSUBSCRIBE

Required

UNSUBACK

Required

PINGREQ

None

PINGRESP

None

DISCONNECT

None

AUTH

None

 

3.4 Reason Codes

A Reason Code is a one-byte unsigned value. Reason code indicates the result of an operation. Reason codes less than 0x80 specifies the successful completion of an operation. The normal reason code for success is 0. Reason codes greater than 0x80 specifies failure. Some of the MQTT Control Packets have a single Reason Code as part of the Variable Header such as CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, DISCONNECT, and AUTH. The two MQTT control packets contain a list of one or more Reason Codes in the Payload, which are SUBACK and UNSUBACK.

 

Reason Code

Name

Packets

Decimal

Hex

0

0x00

Success

CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, UNSUBACK, AUTH

0

0x00

Normal disconnection

DISCONNECT

0

0x00

Granted QoS 0

SUBACK

1

0x01

Granted QoS 1

SUBACK

2

0x02

Granted QoS 2

SUBACK

4

0x04

Disconnect with Will Message

DISCONNECT

16

0x10

No matching subscribers

PUBACK, PUBREC

17

0x11

No subscription existed

UNSUBACK

24

0x18

Continue authentication

AUTH

25

0x19

Re-authenticate

AUTH

128

0x80

Unspecified error

CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT

129

0x81

Malformed Packet

CONNACK, DISCONNECT

130

0x82

Protocol Error

CONNACK, DISCONNECT

131

0x83

Implementation specific error

CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT

132

0x84

Unsupported Protocol Version

CONNACK

133

0x85

Client Identifier not valid

CONNACK

134

0x86

Bad User Name or Password

CONNACK

135

0x87

Not authorized

CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT

136

0x88

Server unavailable

CONNACK

137

0x89

Server busy

CONNACK, DISCONNECT

138

0x8A

Banned

CONNACK

139

0x8B

Server shutting down

DISCONNECT

140

0x8C

Bad authentication method

CONNACK, DISCONNECT

141

0x8D

Keep Alive timeout

DISCONNECT

142

0x8E

Session taken over

DISCONNECT

143

0x8F

Topic Filter invalid

SUBACK, UNSUBACK, DISCONNECT

144

0x90

Topic Name invalid

CONNACK, PUBACK, PUBREC, DISCONNECT

145

0x91

Packet Identifier in use

PUBACK, PUBREC, SUBACK, UNSUBACK

146

0x92

Packet Identifier not found

PUBREL, PUBCOMP

147

0x93

Receive Maximum exceeded

DISCONNECT

148

0x94

Topic Alias invalid

DISCONNECT

149

0x95

Packet large

CONNACK, DISCONNECT

150

0x96

Message rate too high

DISCONNECT

151

0x97

Quota exceeded

CONNACK, PUBACK, PUBREC, SUBACK, DISCONNECT

152

0x98

Administrative action

DISCONNECT

153

0x99

Payload format invalid

CONNACK, PUBACK, PUBREC, DISCONNECT

154

0x9A

Retain not supported

CONNACK, DISCONNECT

155

0x9B

QoS not supported

CONNACK, DISCONNECT

156

0x9C

Use another server

CONNACK, DISCONNECT

157

0x9D

Server moved

CONNACK, DISCONNECT

158

0x9E

Shared Subscriptions not supported

SUBACK, DISCONNECT

159

0x9F

Connection rate exceeded

CONNACK, DISCONNECT

160

0xA0

Maximum connect time

DISCONNECT

161

0xA1

Subscription Identifiers not supported

SUBACK, DISCONNECT

162

0xA2

Wildcard Subscriptions not supported

SUBACK, DISCONNECT

4. MQTT Control Packets

There are 15 MQTT Control packets in MQTTv5

 

1. CONNECT – Connection establishment between an MQTT Client and Broker

2. CONNACK – The connection request acknowledgement

3. PUBLISH – Publish message

4. PUBACK – Publish acknowledgement

5. PUBREC – Publish received(QoS 2 publish received)

6. PUBREL – Publish release(QoS 2 publish received)

7. PUBCOMP – Publish complete

8. SUBSCRIBE – Subscribe to topics

9. SUBACK – Subscribe acknowledgment

10. UNSUBSCRIBE – Unsubscribe from a topic

11. UNSUBACK – Unsubscribe acknowledgement

12. PINGREQ – PING request

13. PINGRESP – PING response

14. DISCONNECT – Disconnection between the MQTT Client and Broker

15. AUTH – Authentication exchange

 

4.1 CONNECT

After a client has established a network connection to a server, the first packet sent from the client to the server must be a connection packet. A client can send the CONNECT packet only once via a network connection.

4.1.1 CONNECT Fixed Header  

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

Remaining Length – This is the length of the variable header and the length of the payload. It is encoded as a variable byte Integer.

 

4.1.2 CONNECT Variable Header

The variable header for the connect packet contains the following fields: Protocol Name, Protocol Level, Connect Flags, Keep Alive, and Properties.

4.1.2.1 Protocol Name

 

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

A server that supports multiple protocols uses the protocol name to determine whether the data is MQTT. The Protocol Name must be the UTF-8 Encoded String that represents “MQTT”.

4.1.2.2 Protocol Version

Description

7

6

5

4

3

2

1

0

Protocol Level

byte 7

Version(5)

0

0

0

0

0

1

0

1

A server that supports multiple versions of the MQTT protocol uses the protocol version to determine which version is used by the MQTT client.

4.1.2.3 Connect Flags

Connect Flags specifies the presence or absence of the fields in the Payload.

Bit

7

6

5

4

3

2

1

0

User Name Flag

Password Flag

Will Retain

Will QoS

Will Flag

Clean Start

Reserved

byte 8

X

X

X

X

X

X

X

0

 

4.1.2.4 Clean Start

A clean start is in bit 1 of the Connect Flags byte. If a connection packet with clean start is set to 1, the client and server must reject any existing session and start a new session.

4.1.2.5 Will Flag

Will Flag is in bit 2 of the Connect Flags. If the Will Flag is set to 1, it indicates that a Will message should be stored on the server and core correlated with the session. The Will message contains the Will properties, Will topic, and Will payload fields in the CONNECT Payload. The will message is published in some situations, that is shown below,

  • Servers detected I / O error or network failure.

  • The client failed to communicate while Keep alive.

  • The client closes the network connection without first sending a disconnected packet with a Reason Code 0x00 (default disconnection).

  • The server closes the network connection without receiving a disconnected packet with Reason Code 0x00 (default disconnection).

4.1.2.6 Will QoS

Will QoS is in bits 4 and 3 of the Connect Flags. when the will message is published then the two bits that specify the QoS level are used. If the Will Flag is set to 1, then the value of the Will QoS maybe 0 (0x00), 1 (0x01), or 2 (0x02).

4.1.2.7 Will Retain

Will Retain is in bit 5 of the Connect Flags. If the Will Flag is set to 1 and the Will Retain is set to 1, the server will publish the Will message as a retained message.

4.1.2.8 User Name Flag

User Name Flag is in bit 7 of the Connect Flags. A Username must be in the payload when the User Name Flag is set to 1.

4.1.2.9 Password Flag

Password Flag is in bit 6 of the Connect Flags. The password must be in the payload when the Password Flag is set to 1.

4.1.2.10 Keep Alive

Bit

7

6

5

4

3

2

1

0

byte 9

Keep Alive MSB

byte 10

Keep Alive LSB

The MQTT client must send the control packets within the defined Keep Alive value. The Keep Alive value depends on the client’s control packet transaction duration.

4.1.2.11 CONNECT Properties:

Property Length – The length of the properties in the MQTT CONNECT control packet.

Session Expiry Interval – The indicator of Session Expiry Interval is 17(0X11) Byte. If the Session Expiry Interval is used more than once then it is considered to be a protocol error. If it is set to 0 then the session ends, when the network connection is closed or it is set to 0XFFFFFFFF then the session not expire.

Receive Maximum – The indicator of Receive Maximum is 33(0X21) Byte. It applies only in the network connection is open. If the Receive Maximum is 0 then it takes the defaults as 65,535.

Maximum Packet Size – The indicator of Maximum Packet Size is 39(0X27) Byte. There is no limit in the packet size when the maximum packet size is absent.

Topic Alias Maximum – The indicator of Topic Alias Maximum is 34(0X22) Byte. If the Topic Alias Maximum is used more than once then it is considered to be a protocol error.

Request Response Information – The indicator of Request Response Information is 25(0X29) Byte. The value 0 indicates that the Request Response Information is not present.

Request Problem Information – The indicator of Request Problem Information is 23(0X17) Byte. If the value is 1 then the packet is not present in the packet.

User property – The indicator of User property is 38(0X26) Byte. This property is allowed to used more than once in the same name also.

Authentication Method – The indicator of the Authentication Method is 21(0X15) Byte. If it is used more than once then it is considered to be a protocol error. The extended authentication does not perform when the authentication method value is 0.

Authentication Data – The indicator of the Authentication Data is 22(0X16) Byte. When the authentication data is used while there is no authentication method then it is to be considered as a protocol error. It does not use more than once in the packet.

Variable Header Example

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 Version
  Description 7 6 5 4 3 2 1 0
byte 7 Version (5) 0 0 0 0 0 1 0 1
Connect Flags

 

 

 

 

byte 8

User Name Flag (1)

Password Flag (1)

Will Retain (0)

Will QoS (01)

Will Flag (1)

Clean Start(1)

Reserved (0)

 

 

 

 

1

 

 

 

 

1

 

 

 

 

0

 

 

 

 

0

 

 

 

 

1

 

 

 

 

1

 

 

 

 

1

 

 

 

 

0

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
Properties
byte 11 Length (5) 0 0 0 0 0 1 0 1
byte 12 Session Expiry Interval identifier (17) 0 0 0 1 0 0 0 1
byte 13 Session Expiry Interval (10) 0 0 0 0 0 0 0 0
byte 14 0 0 0 0 0 0 0 0
byte 15 0 0 0 0 0 0 0 0
byte 16 0 0 0 0 1 0 1 0

 

4.1.3 CONNECT Payload

The payload of the CONNECT packet contains one or more length – prefixed fields, the existence of which is determined by the flags in the variable header. If these fields are present, the client identifies Will Properties, Will Topic, Will Payload, Username, and Password should appear.

Client Identifier (Client ID) – Client identifier must be a UTF-8 Encoded String. Each client that connects to the server has a unique Client ID. This MQTT session between the client and server should be used in MQTT clients to identify the position they hold.

Will Properties – The Will Properties are the next field in the payload, if it is set to 1.The Will properties fields defines the application message attributes that should be sent with a will message and the properties that define when the will message should be published.  A Will Property has the property length and properties.

Property length – It defines the length of the properties in the Will Properties field.

Will Delay Interval – The indicator of Will Delay Interval is 34(0X22) Byte. If the Will Delay Interval is used more than once then it is considered to be a protocol error. If the Will Delay interval is not present, then there is no delay.

Payload Format Indicator – The indicator of the payload format indicator is 1(0X01) Byte. 0(0X00) Byte is equivalent to not sending the payload format indicator that indicates the message is unspecified bytes. If it is used more than once then it is to be considered as a protocol error.

Message Expiry Interval – The Indicator of Message Expiry Interval is 2(0X02) Byte. It is used more than once in the packet considered to be a protocol error. If it is present the value of four bytes will be in the life time of the Will Message, and the output expires when the server releases the Will Message. If it is not present when the server releases the optional message, then the message expiration interval will not be sent.

Content Type – The indicator of the Content Type is 3(0X03) Byte. The content type is included more than once in the packet considered to be a protocol error. The sending and receiving application is the value of the content type.

Response Topic – The indicator of the Response Topic is 8(0X08) Byte. If the response topic is not absent then it identifies the Will message as the request.

Correlation Data – The indicator of the Correlation Data is the 9(0X09) Byte. Correlation data is used by the sender of the request message to identify which request was received when the response message was sent. The requester client does not require any Correlation data when it is absent.

User Property – The indicator of User property is 38(0X26) Byte. This property is allowed to used more than once in the same name also.

Will Topic – The Will Topic is the next field in the payload, if the Will flag is set to 1. It must be a UTF-8 Encoded String.

Will Payload – The Will Payload is the next field in the payload, if the Will flag is set to 1. The Will Payload defines the application message payload to be published for the Will Topic.

Username – The Username is the next field in the payload, if the Username flag is set to 1. This can be used for authentication by the server.

Password – The Password is the next field in the payload, if the password flag is set to 1. It can be used to carry any credentials.

 

4.2 CONNACK

CONNACK Packet is the packet sent by the server in response to a CONNECT packet received from the client. The Server must send a CONNACK with a 0X00 (Success) Reason Code before sending any other packet other than AUTH. The server should not send more than one connection acknowledgement over a network connection.

4.2.1 CONNACK Fixed Header

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

Remaining Length – length of the Variable Header

4.2.2 CONNACK Variable Header

CONNECT acknowledge flags, CONNECT reason code and properties are the field in the Variable Header of the CONNACK Packet.

CONNECT acknowledge flags – Set this field in byte 1. bits 7 to 1 are booked and set to zero.

Session Present  – The position of the session present is bit 0 of the CONNECT acknowledge flags. The session current flag informs the client whether the server is using server status from the previous connection of the clientID. This allows the client and server to have a consistent view of the session states. If the server accepts 1 with a clean start, the server most set the Reason Code 0X00(success) in the CONNACK packet and additionally set the session state 0 or 1 in the CONNACK packet.

CONNECT Reason Code – In the Variable Header, Byte 2 is the CONNECT Reason Code. If a server sends a CONNECT packet with a Reason Code of 128 or higher. it must close the network connection. The Server sending the CONNACK packet with one of the below CONNECT Reason Code.

 

Value

Hex

Reason Code name

Description

0

0x00

Success

The Connection is accepted.

128

0x80

Unspecified error

The Server does not wish to reveal the reason for the failure, or none of the other Reason Codes apply.

129

0x81

Malformed Packet

Data within the CONNECT packet could not be correctly parsed.

130

0x82

Protocol Error

Data in the CONNECT packet does not conform to this specification.

131

0x83

Implementation specific error

The CONNECT is valid but is not accepted by this Server.

132

0x84

Unsupported Protocol Version

The Server does not support the version of the MQTT protocol requested by the Client.

133

0x85

Client Identifier not valid

The Client Identifier is a valid string but is not allowed by the Server.

134

0x86

Bad User Name or Password

The Server does not accept the User Name or Password specified by the Client

135

0x87

Not authorized

The Client is not authorized to connect.

136

0x88

Server unavailable

The MQTT Server is not available.

137

0x89

Server busy

The Server is busy. Try again later.

138

0x8A

Banned

This Client has been banned by administrative action. Contact the server administrator.

140

0x8C

Bad authentication method

The authentication method is not supported or does not match the authentication method currently in use.

144

0x90

Topic Name invalid

The Will Topic Name is not malformed, but is not accepted by this Server.

149

0x95

Packet too large

The CONNECT packet exceeded the maximum permissible size.

151

0x97

Quota exceeded

An implementation or administrative imposed limit has been exceeded.

153

0x99

Payload format invalid

The Will Payload does not match the specified Payload Format Indicator.

154

0x9A

Retain not supported

The Server does not support retained messages, and Will Retain was set to 1.

155

0x9B

QoS not supported

The Server does not support the QoS set in Will QoS.

156

0x9C

Use another server

The Client should temporarily use another server.

157

0x9D

Server moved

The Client should permanently use another server.

159

0x9F

Connection rate exceeded

The connection rate limit has been exceeded.

4.2.3 CONNACK Properties

Some of the CONNACK properties are similar to the CONNECT properties which are property Length, Session Expiry Interval, Receive Maximum, Maximum Packet Size, Topic Alias Maximum, User property, Authentication method, and Authentication Data. For detailed information Refer to section- 4.1.2.11

Maximum QoS – The indicator of the Maximum QoS is 36(0X24) Byte. adding the error. if the Maximum QoS is not available, the client uses the Maximum QoS of 2. In PUBLISH packet, if a server does not support QoS 1 or QoS 2 it must send the Maximum QoS in the CONNACK packet indicates the highest QoS it can support. A Server that does not support QoS 1 or QoS 2 publish packets still accepts subscription packets containing the requested QoS of 0, 1, or 2.

Retain Available – The Indicator of the Retain Available is 37(0X25) Byte. If a server receives a connection packet containing a Will Message set with a will flag 1, the server must reflect the connection request if it does not support retained messages. It must send CONNACK with reason code 0X9A (Retain not available) then close the network connection.

Assigned Client Identifier – The indicator of the Assigned Client identifier is 18(0X12) Byte. if the Client connects using a zero-length Client identifier the server must respond with a connection and a designated client identifier. The assigned client identifier must be a new client identifier that is not currently used in any other session on the server.

Reason String – The indicator of the Reason String is 31 (0X1F) Byte. It is a UTF-8 encoded string. It is a human-readable string designed for detectable and should not be discriminated against by the client. The server uses this value to provide additional information to the client. the server should not send this asset if the client increases the size of the CONNACK packet beyond the specified maximum packet size.

Wildcard Subscription Available – The indicator of the Wildcard Subscription is 40(0X28) Byte. if the value is 0, then the wildcard subscriptions are not supported. If the value is 1, then it is supported. The wildcard subscription is included more than once in the packet and the value other than 0 or 1 is considered to be a protocol error.

Subscription Identifiers Available  – The indicator of the Subscription identifier is 41(0X19) Byte. If the value is 0 then the subscription identifiers are not supported. If the value is 1 then it is supported the subscription identifiers are included more than once and the value other than 0 or 1 is considered to be a protocol.

Shared Subscription Available – The indicator of the Shared Subscription Available is 42(0X2A) Byte. If the value is 0 then the subscription identifiers are not supported. If the value is 1 then it is supported the subscription identifiers are included more than once and the value other than 0 or 1 is considered to be a protocol.

Server Keep-Alive – The indicator of the Server Keep-Alive is 19(0X13) Byte. If the Server sends a Keep-Alive in the CONNACK packet, this value should be used instead of the Client Keep-Alive value sent on CONNECT Packet. If the server does not send the keep-alive, the Server uses the keep-alive value set by the Client on the CONNECT packet. If the Server Keep-Alive is included in the packet more than once then it is considered to be a protocol error.

Response Information – The indicator of the response information is 26(0X1A) Byte. It is a UTF-8 encoded string. It is mainly used for creating a response topic. If it is included more than once then it is to be considered as a protocol error.

Server Reference – The indicator of the Server Reference is 28(0X1C) Byte. It is a UTF-8 encoded string. If it is included more than once in the packet then it is to be considered as a protocol error. The Server uses the server reference in a connection or disconnection in the packet with Reason code 0X9C (use another server) or reason code 0X9D (server moved).

4.2.4 CONNACK Payload

The Control packet CONNACK has no payload.

4.3 PUBLISH

A PUBLISH packet is sent from the client to the server or vice versa to carry an Application Message.

4.3.1 PUBLISH Fixed Header

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

 

 

DUP – The position of the Duplicate flag is byte 1, bit 3. If the DUP flag is set to 0 indicates that this is the first time, the Client or Server has attempted to send the PUBLISH packet. If the DUP flag is set to 1, that indicates it may be a redistribution of the previous attempt to send the packet.

QoS – The position of the QoS is byte 1, bits 2-1. This field indicates the delivery assurance of an application message.

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

1

1

Reserved – must not be used

RETAIN – The position of the RETAIN Flag is byte 1, bit 0. If the RETAIN Flag is set to 1, in the publish packet sent by a client to a server, the server should replace any existing message for the topic and save the application message. If the RETAIN Flag is 0 in the PUBLISH packet sent b a client to the server, the server does not store the message as a retained and removes or replaces any existing retained message.

Remaining Length – It defines the variable header and payload length.

4.3.2 PUBLISH Variable Header

Topic Name, Packet Identifier, and Properties are the fields in the variable header of PUBLISH packet.

Topic Name – Payload data identifies the topic name of the published information channel. The Topic Name in the PUBLISH packet variable header should be the first field. This should be the UTF-8 encoded string. The Topic Name in the PUBLISh packet should not contain wildcard characters. The Topic Name in the PUBLISH packet sent by the server to the subscribing client must match the subscriber’s topic filter.

Packet Identifier – In PUBLISH packets the packet identifier field is present only where the QoS level 1 or 2.

PUBLISH Properties – The PUBLISH packet Properties are similar to the CONNECT and CONNACK. The Properties are Property Length, Payload Format Indicator, Message Expiry interval, Topic Alias, Response Topic, Correlation Data, User Property, Subscription identifier, and Content -Type. For detailed information Refer to sections –4.1.2.11, 4.2.3.

 

4.3.3 PUBLISH Payload

There is an application message that is published on the payload. The content and format of the data depending on the application. The difference between the Length of the variable header and the remaining length field in the fixed header is the length of the payload. It is valid to have a published packet with a zero-length payload.

 

4.3.4 PUBLISH Actions

The receiver of a PUBLISH packet must respond with the packet as specified.

QoS Level

Expected Response

QoS 0

None

QoS 1

PUBACK packet

QoS 2

PUBREC packet

4.4 PUBACK – PUBLISH Acknowledgment

The response of the PUBLISH packet with QoS 1 is the PUBACK packet.

4.4.1 PUBACK Fixed Header  

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

Remaining Length Field – length of the variable header.

4.4.2 PUBACK Variable Header

Packet Identifier from the PUBLISH packet, PUBACK Reason Code, property length, and the properties are the fields in the Variable Header of the PUBACK packet.

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

byte 3

PUBACK Reason Code

byte 4

Property Length

4.4.2.1 PUBACK Reason code

The PUBACK Reason code in the Byte 3. There is no reason code and the value of (0X00) (Success) is used when the remaining length is 2.

Value

Hex

Reason Code name

Description

0

0x00

Success

Message accepted. Publication of the QoS 1 message continues.

16

0x10

No matching subscribers

Message accepted but no subscribers. It is only sent by the Server. It can use this Reason Code instead of 0x00 (Success) if the Server knows that there are no matching subscribers.

128

0x80

Unspecified error

The receiver does not accept the publish but either do not want to reveal the reason, or it does not match one of the other values.

131

0x83

Implementation specific error

The PUBLISH is valid but the receiver is not willing to accept it.

135

0x87

Not authorized

The PUBLISH is not authorized.

144

0x90

Topic Name invalid

The Topic Name is not malformed but is not accepted by this Client or Server.

145

0x91

Packet identifier in use

The Packet Identifier is already in use. This might indicate a mismatch in the Session State between the Client and Server.

151

0x97

Quota exceeded

An implementation or administratively imposed limit has been exceeded.

153

0x99

Payload format invalid

The payload format does not match the specified Payload Format Indicator.

4.4.2.2 PUBACK Properties

Property Length – PUBACK packet variable header properties length is encoded as a variable byte integer. if the remaining length is less than 4, the property has no length and a value 0 is used.

User Property – The User Property is used to provide more additional information to the client. For more information Refer to section – 4.1.3

Reason string – It is used to provide all the information to the Client about why the network connection is closed. For more information about reason String Refer to section – 4.2.3

4.4.3 PUBACK payload

The PUBACK control packet has no payload.

4.4.4 PUBACK Actions

In the QoS 1 delivery protocol, the sender should handle the PUBLISH packet to be considered as “Un acknowledge” until the corresponding PUBACK packet is received from the receiver. In the QoS 1 delivery protocol, the client accepts the right of the application message and responds with a PUBACK packet containing the packet identifier from the incoming PUBLISH packet. After it sends a PUBACK packet the receiver should consider any incoming PUBLISH packet containing the same packet identifier as a utility message regardless of the structure of its DUP flag.

4.5 PUBREC – PUBLISH Received

The PUBLISH packet with QoS 2 is the response of the PUBREC packet. In QoS 2 protocol exchange PUBREC is the second packet.

4.5.1 PUBREC Fixed Header

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

Remaining Length Field – Length of the variable Header.

 

4.5.2 PUBREC Variable Header

The Packet identifier from the PUBLISH packet, PUBREC Reason Code, and Properties are the fields in the variable header of the PUBREC packet.

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

byte 3

PUBREC Reason Code

byte 4

Property Length

4.5.2.1 PUBREC Reason Code

The PUBREC Reason Code is Byte 3 of the variable Header. The value of 0X00 (Success) is used when the remaining length is 2. 

Value

Hex

Reason Code name

Description

0

0x00

Success

The message was accepted. Publication of the QoS 2 message proceeds.

16

0x10

No matching subscribers.

The message is accepted but there are no subscribers. This is sent only by the Server. If the server knows that there are no matching subscribers, it MAY use this Reason Code instead of 0x00 (Success).

128

0x80

Unspecified error

The receiver does not accept the PUBLISH or it does not match any other values but either does not want to reveal the reason.

131

0x83

Implementation specific error

The PUBLISH is valid but the receiver is not willing to accept it.

135

0x87

Not authorized

The PUBLISH is not authorized.

144

0x90

Topic Name invalid

The Topic Name is not malformed but is not accepted by this Client or Server.

145

0x91

Packet Identifier in use

The Packet Identifier is already in use.This can indicate a contradiction in the Session State between the Client and Server.

151

0x97

Quota exceeded

Execution or Administrative limits exceeded.

153

0x99

Payload format invalid

The payload format does not match the one specified in the Payload Format Indicator.

4.5.2.2 PUBREC Properties

Property Length – PUBACK packet variable header properties length is encoded as a variable byte integer. if the remaining length is less than 4, the property has no length and a value 0 is used.

User Property – User Property is used to provide more additional information to the client. For more information Refer to section – 4.1.3

Reason string – It is used to provide all the information to the Client about why the network connection is closed. For more information about reason String Refer to section- 4.2.3

4.5.3 PUBREC Payload

The control packet of the PUBREC packet has no payload.

4.5.4 PUBREC Actions

The receiver of a PUBREC packet must respond with the packet as specified.

QoS Level

Expected Response

QoS 0

None

QoS 1

PUBACK packet

QoS 2

PUBREC packet

 

4.6 PUBREL –  PUBLISH Release

The response of the PUBREC packet is the PUBREL packet. The QoS 2 protocol exchange’s third packet is the PUBLISH Release packet.

4.6.1 PUBREL Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (6)

Reserved

0

1

1

0

0

0

1

0

byte 2

Remaining Length

Bits 3,2,1 and 0 of the Fixed Header are assigned in the PUBREL packet, which must be set to 0,0,1 and 0 respectively. 

Remaining Length – length of the variable header.

 4.6.2 PUBREL Variable Header

The Packet identifier from the PUBREC packet, PUBREL Reason Code, and properties are the fields in the Variable Header of the PUBREL packet. 

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

byte 3

PUBREL Reason Code

 

byte 4

Property Length

4.6.2.1 PUBREL Reason Code

The PUBREL Reason code in the Byte 3. There is no reason code and the value of (0X00) (Success) is used when the remaining length is 2. The Client or Server must be sending the PUBREL packets with one of the values of the PUBREL Reason Code.

Value

Hex

Reason Code name

Description

0

0x00

Success

Message released.

146

0x92

Packet Identifier not found

The Packet Identifier is not known. This is not an error during recovery, but at other times indicates a mismatch between the Session State on the Client and Server.

4.6.2.2 PUBREL Properties

Property Length – PUBREL packet variable header properties length is encoded as a variable byte integer. if the remaining length is less than 4, the property has no length and a value 0 is used.

User Property – User Property is used to provide more additional information to the client. For more information Refer to section – 4.1.3

Reason string – It is used to provide all the information to the Client about why the network connection is closed. For more information about reason String Refer to section – 4.2.3

4.6.3 PUBREL Payload

The control packet of the PUBREL packet has no payload.

4.6.4 PUBREL Actions

 The receiver of a PUBREL packet must respond with the packet as specified.

QoS Level

Expected Response

QoS 0

None

QoS 1

PUBACK packet

QoS 2

PUBREC packet, PUBREL packet

 

4.7 PUBCOMP –  PUBLISH Complete

The response of the PUBREL packet is the PUBCOMP packet. The QoS 2 protocol exchange’s fourth and final packet is the PUBLISH Complete packet.

4.7.1 PUBCOMP Fixed Header

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

Remaining Length – length of the variable header.

4.7.2 PUBCOMP Variable Header

The Packet identifier from the PUBREl packet, PUBCOMP Reason Code, and properties are the fields in the Variable Header of the PUBCOMP packet.

Bit

7

6

5

4

3

2

1

0

byte 1

Packet Identifier MSB

byte 2

Packet Identifier LSB

byte 3

PUBCOMP Reason Code

byte 4

Property Length

 

4.7.2.1 PUBCOMP Reason Code

The PUBCOMP Reason code in the Byte 3. There is no reason code and the value of (0X00) (Success) is used when the remaining length is 2. The Client or Server must be sending the PUBCOMP packets with one of the values of the PUBCOMP Reason Code.

Value

Hex

Reason Code name

Description

0

0x00

Success

Packet Identifier released. Publication of QoS 2 message is complete.

146

0x92

Packet Identifier not found

The Packet Identifier is not known. This is not an error during recovery, but at other times indicates a mismatch between the Session State on the Client and Server.

4.7.2.2 PUBCOMP Properties

Property Length – PUBCOMP packet variable header properties length is encoded as a variable byte integer. if the remaining length is less than 4, the property has no length and a value 0 is used.

User Property – User Property is used to provide more additional information to the client. For more information Refer to section – 4.1.3

Reason string – It is used to provide all the information to the Client about why the network connection is closed. For more information about reason String Refer to section – 4.2.3

 

4.7.3 PUBCOMP Payload

The control packet of the PUBCOMP packet has no payload.

4.7.4 PUBCOMP Actions

The receiver of a PUBCOMP packet must respond with the packet as specified.

QoS Level

Expected Response

QoS 0

None

QoS 1

PUBACK packet

QoS 2

PUBREC packet, PUBREL packet, PUBCOMP packet

4.8 SUBSCRIBE

The SUBSCRIBE packet is sent to the server from the client to generate one or more subscriptions. Each subscription stores the client’s interest in one subscription or more subscription topics. The server sends the PUBLISH packets to the client to pass the application messages with maximum QoS to topics that are compatible with these subscriptions.

4.8.1 SUBSCRIBE Fixed Header

Bit

7

6

5

4

3

2

1

0

byte 1

MQTT Control Packet type (8)

Reserved

1

0

0

0

0

0

1

0

byte 2

Remaining Length

Bits 3,2,1 and 0 of the Fixed Header are assigned in the SUBSCRIBE packet, which must be set to 0,0,1 and 0 respectively.

Remaining Length – length of the variable header and the length of the payload.

4.8.2 SUBSCRIBE Variable Header

The Packet identifier and properties are the fields in the Variable Header of the SUBSCRIBE packet.

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

byte 3

Property Length (0)

0

0

0

0

0