MQTT basics

MQTT Publish/Subscribe with Mosquitto Pub/Sub Examples

Zakhar Yung16.05.202419.06.2024

Picture that you are getting back home from a vacation trip. What would cheer you up after a long road? A cup of freshly brewed coffee! And you can have it ready and waiting for you as soon as you open your entrance door. For this, you only need to launch your coffee maker using your smart home app. It will take just a few clicks to make it happen and get a cup of a tasty drink right up to your arrival. However, underneath this lies a complex MQTT publish-subscribe communication between your smartphone and the coffee maker in your smart home system. 

The same thing works in other IoTs such as security systems, factory equipment, wearable health monitors, etc. What does this look like? I’ll explain it in this article. So, buckle up to learn about the MQTT publish-subscribe model and how remote IoT devices use it to exchange information. 

MQTT publish-subscribe model explained

All in all, the concept of the MQTT publish-subscribe pattern or simply MQTT pub-sub includes three types of parties: 

• publisher – a client (device) that posts information on a self-chosen topic.
• MQTT broker – a party that receives packets from publishers, checks for settings, and then forwards them to subscribers. Learn more about all the steps that the broker has to complete.
• subscriber – a client (device) that is interested in the information on a certain topic.

At first glance, everything looks clear since one client publishes, and the other client receives. However, the publisher does not send information directly to the subscriber. 😳

In MQTT, clients talk to each other through an MQTT broker. We’ve already blogged about the MQTT client and broker connection.

So, in our coffee maker example, the MQTT communication looks as follows:

At the same time, your smartphone can be a subscriber if you get information about the temperature in your home from the temperature sensors. In this case, the MQTT pub-sub connection looks as follows:

An IoT system usually contains multiple devices. How can you understand which ones of them are publishers or subscribers? The MQTT broker comes into play here.

To test our Pro Mosquitto MQTT broker with advanced features like MQTT HA, multiple MQTT integrations and more, sign up for a free cloud or on-premises trial here!

MQTT pub-sub message flow

A publisher sends notifications (also called MQTT messages) on a specific topic to an MQTT broker, which forwards them to a client or clients that are subscribed to this topic. Each topic can only have one publisher but multiple subscribers.

What are MQTT topics?

Now, let’s delve into MQTT topics. These are essentially strings, with the caveat that only UTF-8 characters are allowed, and certain characters like “<”, “>”, “$” are not permitted. MQTT topics play a crucial role as they enable the MQTT broker to identify the appropriate publishers and subscribers for message transmission.

• The client that is interested in sending messages publishes them on a specific topic.
• The client subscribes to a certain topic and starts receiving messages published on it.

MQTT topics can contain one or several levels, separated by a forward slash, for example:

myhome/kitchen/coffeemaker
myhome/kitchen/sensor/temperature

MQTT topics prerequisites

• An MQTT topic must contain at least one character.
• An MQTT topic is case-sensitive. This means that myhome/kitchen/coffeemaker and myhome/Kitchen/Coffeemaker are different topics.
• Clients can use wildcards (special characters) in an MQTT topic to subscribe to multiple MQTT topics. We will deal with them later.

To learn more about MQTT topics and wildcards, check out this guide.

What are MQTT messages?

An MQTT message is the data sent from the publisher and received by the subscriber. The MQTT message format can be:

1. Fixed header, for example, CONNACK
2. Fixed header and variable header, for example, PUBACK
3. Fixed header, variable header, and payload, for example, PUBLISH

Note: The fixed header consists of two fields: the control field and the variable length message field. We won’t focus on this, but if you are interested in the MQTT protocol message structure, check out this Understanding an MQTT Packet guide.

So, what if a publisher sends a message for a topic to which no client is subscribed? The MQTT broker should resolve this. Actually, the role of the MQTT broker in the MQTT pub-sub model is crucial. Let’s talk more about this.

MQTT broker in MQTT publish and subscribe model

The MQTT broker is a hub for communication between clients. It obtains messages from publishers and distributes them to clients based on the topics to which they are subscribed. This allows us to keep the workload balanced and maintain the linear growth of the connection count if the number of clients increases. 

However, when choosing an MQTT broker, it’s not the number of clients you should consider but the traffic load, i.e., the volume of data the clients send per second. A hundred clients sending messages with large attached data (Payload) every few seconds would create a larger workload than a thousand clients sending smaller messages every minute.

Mosquitto™ MQTT broker is the most downloadable and efficient broker worldwide. With it, you can set up MQTT communication between apps, sensors, and versatile devices. The open-source version of the Mosquitto broker is a good choice for your pet projects. 

At the same time, for commercial purposes, it’s better to use an even more reliable and secure version of this popular MQTT broker – Pro Edition for Mosquitto. It embodies the best you can get with Mosquitto plus the MQTT High Availability, optimized performance, multiple MQTT integrations (with InfluxDB, Google pub/sub, MongoDB, Kafka, etc.), the Audit Trail logging feature, Persistent Queueing, Kubernetes deployment and OpenShift deployment possibilities, powerful MQTT broker management center interface, etc. 

I’ll use Mosquitto open source below to demonstrate the MQTT publish and subscribe examples. 

However, if you’re interested in exploring the advanced features of the Pro Edition, you can easily do so by signing up for a free cloud or on-premises trial. This allows you to experience the benefits of the Pro Edition without any commitment. 

Now, let’s see how all this MQTT pub-sub thing looks in action.

MQTT subscribe to a topic

I start with subscription since the MQTT broker must forward messages to clients that are subscribed to a topic or topics. To establish an MQTT connection between a client (both subscriber and publisher) and a broker, the client sends a CONNECT request and receives a CONNACK response packet. We’ve covered this in our MQTT Connection Beginners Guide.  

Once the connection is established, the client sends the broker a SUBSCRIBE MQTT packet with the topics of interest. The packet contains two values: 

• packetId – Unique packet identifier set by the client library and the MQTT broker
• subscription – a topic and a QoS level to subscribe for. The SUBSCRIBE packet can include multiple subscriptions.

Dive deeper into the essence of MQTT packets here.

MQTT subscribe example

packetID	0014
qos1	0
topic1	kitchen/sensor/temperature
qos2	1
topic2	kitchen/sensor/humidity
qos3	2
topic3	kitchen/coffeemaker

MQTT Quality of Service for the messages

The pub-sub message delivery process in MQTT has three levels of Quality of Service (QoS):

• QoS0 – the default level of quality of service that does not guarantee the delivery of the message. The publisher sends the message to the MQTT broker no more than once, and the broker does not acknowledge receipt. You can use this level when you accept message loss.
• QoS1 – the quality of service level that guarantees the delivery of the message. The publisher sends the message more than once until the MQTT broker acknowledges receipt. You can use this level when the message must be delivered and you don’t have a problem with the subscriber receiving the message more than once.
• QoS2 – the quality of service level that guarantees the processing of the message only once. The publisher sends and stores the message until a double handshake between the sender and receiver has been accomplished to acknowledge receipt. You can use this level when the message must be processed without duplicating.

To learn more about this topic, check out our article on MQTT QoS levels.

To test our Pro Mosquitto MQTT broker, sign up for a free 14-day cloud or 30-day on-premises trial here!

MQTT subscribe wildcards

In Mosquitto, two wild cards are available to enable the client’s subscription to multiple MQTT topics:

• + (plus sign) – to match a single level of hierarchy.
• # (number sign) – to match all hierarchy levels after #.

+/sensor/temperature

Supports	Does not support
kitchen/sensor/temperature bathroom/sensor/temperature bedroom/sensor/temperature	kitchen/sensor/humidity kitchen/coffeemaker kitchen/sensor/temperature/backup

kitchen/#

Supports	Does not support
kitchen/sensor/temperature kitchen/sensor/humidity kitchen/coffeemaker	bathroom/sensor/humidity bedroom/sensor/temperature

Wildcards can only be used in topic filters; hence, they are meant for subscribing to topics, not publishing messages.

MQTT subscribe – successful or not?

Since the MQTT broker is the first recipient of the published message, it acknowledges the SUBSCRIBE packets by responding with a SUBACK packet to the subscriber. The SUBACK packet contains the packetId and return codes:

• 0 – Success-Maximum for QoS0
• 1 – Success-Maximum for QoS1
• 2 – Success-Maximum for QoS2
• 128 – Failure

MQTT SUBACK packet example

packetID	0014
returnCode1	128
returnCode2	2
returnCode3	3

If the subscription is successful, the MQTT broker will forward the published messages to the clients subscribed to the topic.

MQTT unsubscribe from a topic

To unsubscribe from one or multiple topics, a client sends the UNSUBSCRIBE packet that contains a packetId and a list of topics.

MQTT unsubscribe example

packetID	0014
topic4	kitchen/sensor/temperature
topic4	kitchen/sensor/humidity
topic2	kitchen/coffeemaker

We’re done with subscribing our clients to topics. Now, we can publish messages to the MQTT broker and this is what it looks like.

MQTT publish a message

It’s important to note the flexibility of bidirectional publishing. Publishers can also act as subscribers, and vice versa. This means that a subscriber can also be a publisher for another topic. In our example, with a coffeemaker, your mobile app, acting as a publishing client, can send a message to the coffeemaker. The coffeemaker, in turn, becomes a publisher when it sends a message that your coffee is ready. This flexibility empowers developers to design dynamic communication setups.

Again, the information exchange between a publishing client and the MQTT broker starts with the connection. Once it’s successful, the publisher can send messages to the broker, which, in turn, forwards messages to the clients subscribed to the message topic. For this, the client sends a PUBLISH MQTT packet with the following values: 

• packetId – Unique packet identifier that is set by the client library and the MQTT broker.
• topicName – the topic string. 
• qos – the quality of service level for message delivery.
• retainFlag – if true, then the message will be retained. This makes sense when a subscribed device, for example, a car door sensor, cannot wait until the next message is published. To learn more about these messages, check out our MQTT retained messages guide.
• payload – encryption of application-specific data on the application level (a message).
• dupFlag – if true, then the message duplicate was resent.

MQTT publish example

Here is what the MQTT PUBLISH packet looks like in real life.

packetID	0014
topicName	kitchen/coffeemaker
qos	2
retainFlag	false
Payload	Hello, this is a message.
dupFlag	false

MQTT publish acknowledgement

Different levels of QoS have different acknowledgement mechanisms. For QoS0, the MQTT broker forwards the published message to the subscribers without any acknowledgement from their side. This is why the QoS0 is often called ‘fire and forget’.

QoS1 publish acknowledgement

For the messages with the QoS1 level, the subscribers send a publish acknowledge packet – PUBACK. If they don’t, the MQTT broker keeps sending PUBLISH packets with the dupFlag parameters set to TRUE.

QoS2 publish acknowledgement

For the highest level of MQTT quality of service, the publish acknowledgment is slightly trickier. Once the subscriber receives the published message, it replies with a PUBREC packet. Until the MQTT broker receives PUBREC, it keeps sending PUBLISH packets with the dupFlag parameters set to TRUE.

Simultaneously, once the broker gets the PUBREC and forwards it to the publisher, the latter responds with a PUBREL packet. Again, the broker gets the PUBREL and forwards it to the subscriber which replies with another packet – PUBCOMP. With the receipt of the PUBCOMP packet by the publisher, the packet id becomes available for reuse.

Can the MQTT publisher know whether the published topic has subscribers?

In the older version of MQTT messaging protocol (up to MQTT v. 5), the client never knows about the subscribers of the published messages. However, in MQTT 5, this is enabled for two QoS levels: QoS1 and QoS2. The MQTT broker sends a PUBACK or PUBREC packet with the information about no subscribers.

mosquitto_pub and mosquitto_sub examples

Let’s wrap up our MQTT pub-sub tutorial with a brief intro to the simple client utilities that you get within the Mosquito package:

• Mosquitto_pub – to publish a single message on a topic.
• Mosquitto_sub – to subscribe to topics.

These tools, mosquitto_pub and mosquitto_sub, are straightforward to use and are particularly useful for testing clients’ publishing and subscribing. While we won’t delve into their details here, you can easily learn about them in the comprehensive Mosquitto manual available on the Cedalo website. What we’re demonstrating here are practical examples of how they function. 

mosquitto_pub example

Since I’ve been talking about our coffee maker throughout the article, let’s check out how you can publish a message to turn it on:

mosquitto_pub -h localhost -t kitchen/coffeemaker -m "on" -q 1

• -h – the host to connect to
• -t – the topic of a message
• -m – the message
• -q – the quality of service

The coffeemaker example is not that widespread, so let’s see the more common one. We’ll publish temperature information:

mosquitto_pub -h localhost -t kitchen/sensor/temperature -m 22 -q 2

mosquitto_sub example

Let’s subscribe to the status of the coffee maker:

mosquitto_sub -h localhost -t kitchen/coffeemaker -q 1

Or, here is an example of subscribing to all sensors located in the kitchen:

mosquitto_sub -t kitchen/sensors/+ -q 2

To see more examples, check out this awesome guide on how to test MQTT broker setup using these Mosquitto client tools.

MQTT publish and subscribe key takeaways

Consequently, the MQTT publish/subscribe model may remind you of the traditional client-server communication pattern, where clients exchange information directly with the server. In MQTT, all devices are clients, and they talk to each other via the MQTT broker. So, this is the central element that the entire IoT system rests on. MQTT brokers filter the clients’ published messages by topics and distribute them to the clients that are subscribed to the respective topics. 

Eventually, the proper choice of the MQTT broker will let you optimize the communication of all devices in your system. So, choose wisely 🙂