Developing MQTT Clients – Guide

Introduction

This developing MQTT Clients guide will help you in developing MQTT Clients as per the Oasis Standard of MQTT Protocol. The developed MQTT clients can be connected to the MQTTRoute which follows the OASIS standard MQTT v3.1.1

The MQTTRoute is a Client Broker publish/subscribe messaging transport protocol orient. It is a lightweight protocol. This feature made MQTT suitable for Machine 2 Machine communication and the Internet of Things, where a small code footprint is required, and network bandwidth is precious. The protocol runs over TCP/IP. The publish/subscribe message pattern provides one too many message distribution and decoupling of MQTT clients.

Getting Started

Machine-to-Machine, Machine-to-User, Machine-to-Mobile communication cannot happen without a powerful central server. MQTT edge devices and applications communicate via the MQTT Broker which acts as the central server. You can download the Enterprise MQTT Broker which can be run on Windows, Linux, Mac & Raspberry Pi now and get started.

MQTT Packet Format

The Broker will respond to the following structured packet controls. The packet control consists of three parts in the following order.

    • Fixed header – presents on all MQTT control packets
    • Variable header – presents in some MQTT control packets
    • Payload – presents in some MQTT control packets

1.Fixed Header

x is the bit value variation for each packet. Example-connect packet
Bit76543210
Byte 1MQTT Control Packet type (1)Reserved
00010000
Byte 2Remaining length
Here,0001 will represent 1st packet type CONNECT The fixed header contains two-byte
    • 1st byte is split into two as 4 bit unsigned, one is for the control packet another one is for the flag
    • 2nd byte is for the remaining length

2.Variable Header

The Variable header must be defined inside the fixed header and payload. The content of a variable header will vary depending on the packet type. The common format of a packet identifier in the most packet is
Bit76543210
Byte 1Packet Identifier MSB
Byte 2Packet Identifier LSB
The following packets contains a Packet identifier
    • PUBLISH
    • PUBACK
    • PUBREC
    • PUBREL
    • PUBCOMP
    • SUBSCRIBE
    • SUBACK
    • UNSUBSCRIBE
    • UNSUBACK

3.Payload

The payload is the final part of a packet. It is the application message. The Control packets which contain a payload are

    • CONNECT
    • PUBLISH
    • SUBSCRIBE
    • SUBACK
    • UNSUBSCRIBE

CONNECT

After a connection establishment between an MQTT client and Broker, the first packet must be a CONNECT packet. The CONNECT packet must be sent only once over a network connection. The second CONNECT Packet sent from an MQTT Client will be ignored and disconnected.

Fixed Header

Bit 76543210
byte1MQTT control packet type (1)Reserved
00010000
byte2…Remaining length

Variable header

The variable header has to contain four parts

    1. Protocol name bytes
    2. Protocol level
    3. Connect flags
    4. Keepalive

Protocol name bytes

description76543210
Protocol Name
Byte 1Length MSB (0)00000000
Byte2Length LSB (4)00000100
Byte3M01001101
Byte4Q01010001
Byte5T01010100
Byte6T01010100
A incorrect protocol name will be disconnected by MQTTRoute

Protocol level

76543210
Protocol Level
Byte 7Leve(4)00000100
The protocol level for the MQTTRoute is 4, other values will lead to disconnection

Connect flags

Bit 76543210
User name flagPassword flagWill retainWill qosWill flagcleansessionreserved
Byte 8xxxxxxxX
This field has to mention the presence or absence of data in a payload.

Keepalive

Bit 76543210
Byte 9Keep Alive MSB
Byte 10Keep Alive LSB
The MQTT client must send the control packets not exceeding the value of defined keepalive. The keep-alive value will depend on the client’s control packet duration of one transmission.

Payload

The payload contains the MQTT Client identifiers for the client eg: username, password. The client id must be unique to each client the Broker will respond to the unique client id for each client. Sending client id with an empty field leads to rejection of the client. The following fields must be taken in the following order only Client Identifier, Will Topic, Will Message, User Name, Password. The above fields must be in string format. The packet which does not send CONNECT packet after a reasonable time will be rejected by the Broker. After the above validation success, the Broker will respond in 2 format

    1. Check whether the client is already present if present the Broker will respond with a disconnection.
    2. The Broker will send a CONNACK packet with zero value.
After a successful CONNACK, the Broker will do a keepalive monitoring.

CONNACK

The Broker will respond with a CONNACK for a successful connection. If a CONNACK packet is not received by an MQTT client within a reasonable time the client must close the connection the response time will depend on the infrastructure.

Fixed header

Bit76543210
Byte1MQTT Control PacketReserved
00100000
Byte2Remaining Length
00000010
The remaining value is the length of the variable header in CONNACK it has to be 2

Variable header

bit76543210
Connect Acknowledgement flag Reserved sp
Byte 10000000x
Connect Return code
Byte 2xxxxxxxx
Byte1 is the connection acknowledge flags and bits 7 to 1 are reserved. And bit 0 is for session present(sp) flag -it indicates the presence of a clientid in Broker.

PINGRESP

It is the response for PINGREQ from MQTT Route to show that the Broker is alive.

Fixed header

Bit76543210
Byte 1MQTT Control Packet type (13)Reserved
11010000
Byte 2Remaining length(0)
00000000
It does not have variable header.

PUBLISH

The client who wants to send a message to a specified topic can use the PUBLISH control packet and the broker will forward this message to the clients who subscribed to that same topic.

Fixed header

Bit 76543210
byte1MQTT control packet type (3)DUPQoSRetain
0011xxxx
byte2Remaining length

Flag section

3.DUP flag-fresh publish has to be set as 0 and redelivery has to be set as 1. 2,1. QoS level-this flag represents the level of assurance for an application message delivery. 0-at most one delivery 1-at least one delivery 2-exactly one delivery 0.retain-retain flag set as 1 application message must be stored retain flag set as 0 application message must not be stored.

Variable header

Bit76543210
Byte 3Topic Name Length(MSB)
Byte 4Topic Name Length (LSB)
Byte 5…nTopic name
Byte n+1Message Id(MSB)
Byte n+2Message Id (LSB)
It contains a topic name, a packet identifier

Topic name
The matching topic name is only sent to subscribers. It has to be the first field of the PUBLISH packet and must be a string.

Packet Identifier
The packet identifier must be present in QoS 1 and 2.

Payload

The payload contains the application message to be published after Byte n+2. The client can expect the following response after a PUBLISH

For QoS 0-none

For QoS 1-PUBACK packet

For QoS 2-PUBREC packet

SUBACK

The Broker will respond with a SUBACK for a Subscribe

Fixed Header

Bit76543210
Byte 1MQTT Control Packet type (9)Reserved
10010000
Byte 2Remaining length

Remaining length

It should have the length of the variable header plus the length of the payload. SUBACK will be a response to the SUBSCRIBE.

Variable header

Bit76543210
Byte 1Packet Identifier MSB
Byte 2Packet Identifier LSB

Payload

bit76543210
Return code
Byte 1x00000xx
Matching return code for a subscribe will be sent by the Broker. The Client has to expect the following return codes.

Bit 7Bit 1Bit 0
QoS 0000
QoS 1001
QoS 2002
For FailureNot 0Not 0Not 0,1,2

UNSUBSCRIBE

The client has to send this UNSUBSCRIBE packet when it wants to UNSUBSCRIBE from a particular topic.
Bit76543210
Byte 1MQTT Control Packet type (10)Reserved
10100010
Byte 2Remaining length
Bits 3,2,1,0 of the fixed header must be 0,0,0,1. Otherwise, the Broker will disconnect the client. The remaining length has to be the length of the variable header and the length of the payload.

Variable Header

Bit76543210
Byte 1Packet Identifier MSB
Byte 2Packet Identifier LSB

Payload

Byte N…Topic Name
The payload has to contain at least one topic name otherwise it will be discarded. The topic name must be a String. The unsubscribe must be done after the values on the buffer or the bending QoS 1 and QoS 2 messages have been sent.

UNSUBACK

The UNSUBACK is sent from the Broker to show the response for an UNSUBSCRIBE.

Fixed Header

Bit76543210
Byte 1MQTT Control Packet type (11)Reserved
10110000
Byte 2Remaining length(2)
00000010

Variable Header

The variable header will contain the Packet id of the UNSUBSCRIBE packet and returned from the Broker for the response of UNSUBSCRIBE.

Bit76543210
Byte 1Packet Identifier MSB
Byte 2Packet Identifier LSB

DISCONNECT

Fixed Header

Bit76543210
Byte 1MQTT Control Packet type (14)Reserved
11100000
Byte 2Remaining length(0)
00000000
There is no variable header and payload for Disconnect. The DISCONNECT packet is the final control packet to be sent from the client. The Broker will validate the reserved bits for 0 if not the client will be disconnected. After the DISCONNECT packet, the client must close the network connection and must not send any control packets.

PUBREL

It is the acknowledgment packet to the PUBREC.

Fixed header

Bit76543210
Byte 1MQTT Control Packet type (6)Reserved
01100010
Byte 2Remaining length(2)
00000010
The bits in fixed header 3,2,1,0 are to be set as 0,0,1,0 respectively otherwise the connection will be closed.

Variable header

Bit76543210
Byte 1Packet Identifier MSB
Byte 2Packet Identifier LSB
Contains the packet identifier for which the PUBLISH acknowledged.

MQTT Packet Types

The MQTT Control packet consists of 14 packets
  1. CONNECT – MQTT Client requests a connection to a Broker
  2. CONNACK – Acknowledge connection request
  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 – Subscribes to a topic
  9. SUBACK – Subscribe acknowledgment
  10. UNSUBSCRIBE – Unsubscribe from a topic
  11. UNSUBACK – Unsubscribe acknowledgement
  12. PINGREQ – PING request
  13. PINGRESP – PING response
  14. DISCONNECT – Disconnect notification

PUBACK

The PUBACK is a response to a publish.

Fixed header

Bit76543210
Byte1MQTT Control Packet(4)Reserved
01000000
Byte2Remaining Length
00000010
The remaining length of the fixed header will represent the length of the variable header.

Variable Header

Bit76543210
Byte 1Packet Identifier MSB
Byte 2Packet Identifier LSB
This contains the packet identifier from PUBLISH for which it is acknowledging.

PUBREC

It is the response of PUBLISH in QoS 2

Fixed header

Bit76543210
Byte 1MQTT Control Packet type (5)Reserved
01010000
Byte 2Remaining length(2)
00000010

Variable header

Bit76543210
Byte 1Packet Identifier MSB
Byte 2Packet Identifier LSB

PUBCOMP

It is the response to the PUBREL in QoS 2.

Fixed header

Bit76543210
Byte 1MQTT Control Packet type (7)Reserved
01110000
Byte 2Remaining length(2)
00000010

Variable header

Bit76543210
Byte 1Packet Identifier MSB
Byte 2Packet Identifier LSB

SUBSCRIBE

The MQTT Client has to send a SUBSCRIBE packet for subscriptions. The Broker will respond with the PUBLISH packet with its payload.

Fixed header

Bit76543210
Byte 1MQTT Control Packet type (5)Reserved
10000010
Byte 2Remaining length
Bits 3,2,1,0 has to be set as 0,0,1,0. It contains the topic to which the MQTT Client subscribing. The topic must be a string.

Variable header

Bit76543210
Byte 1Packet Identifier MSB
Byte 2Packet Identifier LSB

Payload

Description76543210
Topic filter
Byte1 Length MSB
Byte2 Length LSB
Byte3…NTopic filter
Requested QoS
ReservedQoS
Byte N+1000000xx
The Payload has to mention at least one topic/QoS mention otherwise it will be discarded. The subscriber with no payload is a violation of the structure and will be discarded. The topic Name must be a string. If any field in the reserved field is non-zero or the QoS is not 0,1,2 the client will be discarded.

PINGREQ

The MQTT Client must send a PINGREQ to the Broker to say it is alive on the network when it does not send any control packets and have to make a routine check to indicate it’s alive.
Bit76543210
Byte 1MQTT Control Packet type (12)Reserved
11000000
Byte 2Remaining length(0)
00000000
It should not have variable header and payload.