MQTT Publish, Subscribe & Unsubscribe - MQTT Essentials: Part 4

Written by The HiveMQ Team

Category: MQTT Essentials MQTT

Published: February 2, 2015


Welcome to the fourth part of MQTT Essentials. A ten-part blog series on the core features and concepts of the MQTT protocol. In this post, we focus on publish, subscribe, and unsubscribe in MQTT. Earlier in this series, we covered the basics of the publish/subscribe model. In this post we delve into the specifics of publish/subscribe in the MQTT protocol. If you haven’t read about the basics of the publish/subscribe pattern yet, we strongly encourage you to read that post first.

Last week, we looked at establishing a connection between the MQTT client and broker. This week, we’ll build on that information as we talk about sending and receiving messages.

Publish

An MQTT client can publish messages as soon as it connects to a broker. MQTT utilizes topic-based filtering of the messages on the broker (see part 2 for details). Each message must contain a topic that the broker can use to forward the message to interested clients. Typically, each message has a payload which contains the data to transmit in byte format. MQTT is data-agnostic. The use case of the client determines how the payload is structured. The sending client (publisher) decides whether it wants to send binary data, text data, or even full-fledged XML or JSON. A PUBLISH message in MQTT has several attributes that we want to discuss in detail:

MQTT Publish attributes

Topic Name The topic name is a simple string that is hierarchically structured with forward slashes as delimiters. For example, “myhome/livingroom/temperature” or “Germany/Munich/Octoberfest/people”. For details on topics, see part 5 of MQTT Essentials.

QoS This number indicates the Quality of Service Level (QoS) of the message. There are three levels: 0,1, and 2. The service level determines what kind of guarantee a message has for reaching the intended recipient (client or broker). For details on QoS, see part 6 of MQTT Essentials.

Retain Flag This flag defines whether the message is saved by the broker as the last known good value for a specified topic. When a new client subscribes to a topic, they receive the last message that is retained on that topic. For details on retained messages, see part 8 of MQTT Essentials.

Payload This is the actual content of the message. MQTT is data-agnostic. It is possible to send images, text in any encoding, encrypted data, and virtually every data in binary.

Packet Identifier The packet identifier uniquely identifies a message as it flows between the client and broker. The packet identifier is only relevant for QoS levels greater than zero. The client library and/or the broker is responsible for setting this internal MQTT identifier.

DUP flag The flag indicates that the message is a duplicate and was resent because the intended recipient (client or broker) did not acknowledge the original message. This is only relevant for QoS greater than 0. Usually, the resend/duplicate mechanism is handled by the MQTT client library or the broker as an implementation detail. For more information, part 6 of MQTT Essentials.

When a client sends a message to an MQTT broker for publication, the broker reads the message, acknowledges the message (according to the QoS Level), and processes the message. Processing by the broker includes determining which clients have subscribed to the topic and sending the message to them.

MQTT Publish Message Flow

The client that initially publishes the message is only concerned about delivering the PUBLISH message to the broker. Once the broker receives the PUBLISH message, it is the responsibility of the broker to deliver the message to all subscribers. The publishing client does not get any feedback about whether anyone is interested in the published message or how many clients received the message from the broker.

Subscribe

Publishing a message doesn’t make sense if no one ever receives it. In other words, if there are no clients to subscribe to the topics of the messages. To receive messages on topics of interest, the client sends a SUBSCRIBE message to the MQTT broker. This subscribe message is very simple, it contains a unique packet identifier and a list of subscriptions.

MQTT Subscribe attributes

Packet Identifier The packet identifier uniquely identifies a message as it flows between the client and broker. The client library and/or the broker is responsible for setting this internal MQTT identifier.

List of Subscriptions A SUBSCRIBE message can contain multiple subscriptions for a client. Each subscription is made up of a topic and a QoS level. The topic in the subscribe message can contain wildcards that make it possible to subscribe to a topic pattern rather than a specific topic. If there are overlapping subscriptions for one client, the broker delivers the message that has the highest QoS level for that topic.

Suback

To confirm each subscription, the broker sends a SUBACK acknowledgement message to the client. This message contains the packet identifier of the original Subscribe message (to clearly identify the message) and a list of return codes.

MQTT SUBACK attributes

Packet Identifier The packet identifier is a unique identifier used to identify a message. It is the same as in the SUBSCRIBE message.

Return Code The broker sends one return code for each topic/QoS-pair that it receives in the SUBSCRIBE message. For example, if the SUBSCRIBE message has five subscriptions, the SUBACK message contains five return codes. The return code acknowledges each topic and shows the QoS level that is granted by the broker. If the broker refuses a subscription, the SUBACK message conains a failure return code for that specific topic. For example, if the client has insufficient permission to subscribe to the topic or the topic is malformed.

Return Code Return Code Response
0 Success - Maximum QoS 0
1 Success - Maximum QoS 1
2 Success - Maximum QoS 2
128 Failure


MQTT Subscribe Flow

After a client successfully sends the SUBSCRIBE message and receives the SUBACK message, it gets every published message that matches a topic in the subscriptions that the SUBSCRIBE message contained.

Unsubscribe

The counterpart of the SUBSCRIBE message is the UNSUBSCRIBE message. This message deletes existing subscriptions of a client on the broker. The UNSUBSCRIBE message is similar to the SUBSCRIBE message and has a packet identifier and a list of topics.

MQTT Unsubscribe attributes

Packet Identifier The packet identifier uniquely identifies a message as it flows between the client and broker. The client library and/or the broker is responsible for setting this internal MQTT identifier.

List of Topic The list of topics can contain multiple topics from which the client wants to unsubscribe. It is only necessary to send the topic (without QoS). The broker unsubscribes the topic, regardless of the QoS level with which it was originally subscribed.

Unsuback

To confirm the unsubscribe, the broker sends an UNSUBACK acknowledgement message to the client. This message contains only the packet identifier of the original UNSUBSCRIBE message (to clearly identify the message).

MQTT UNSUBACK attributes

Packet Identifier The packet identifier uniquely identifies the message. As already mentioned, this is the same packet identifier that is in the UNSUBSCRIBE message.

Unsubscribe Flow

After receiving the UNSUBACK from the broker, the client can assume that the subscriptions in the UNSUBSCRIBE message are deleted.


That’s the end of part four in our MQTT Essentials series. We hope you enjoyed it. In our next post we dig deeper into how MQTT topics are used. We’ll cover topic basics, how to use wildcards, and provide plenty of practical examples.

Have a great week and we hope to see you on the next MQTT Monday!

If you still haven’t signed up for our newsletter, enter your email in the subscription form below to get posts as soon as they are published. If you prefer RSS, you can subscribe to our RSS feed here.

About The HiveMQ Team

We love writing about MQTT, IoT protocols and architecture in general. Our experts are here to help, so reach out to us if we can help!
Contact us
HiveMQ 2.2.1 released
Publish & Subscribe - MQTT Essentials: Part 2