MQTT (MQ Telemetry Transport) is one of the most popular IoT protocols because it is lightweight, scalable, has near real-time information delivery, and will work even in places with unreliable network connectivity.
Since a lot of IoT devices are battery-powered or have metered connections, they might not always be connected. With MQTT, messages can still be received or published when these devices reestablish the connection.
No matter the MQTT use case, data needs to be exchanged between and among devices. The MQTT protocol makes this exchange almost seamless.
The Eclipse Paho project is one of the implementations of the MQTT protocol by the Eclipse Foundation (the organization behind popular open-source tools like the Eclipse IDE, and Jarkata EE)
Our focus will be on MQTT’s Python implementation.
Eclipse Paho Client is a library that works with the MQTT publish-subscribe model to ensure that MQTT clients publish messages smoothly. It does this via helper functions and a client class. Supported MQTT versions include 5.0, 3.1.1, and 3.1
What features make the Paho MQTT Python Client a great option?
Last Will and Testament Messages (LWT)
For an MQTT client to connect to an MQTT broker, it needs to send a connection request. The connection request contains a CONNECT control packet with information that the broker will use for authorization and authentication, and to initiate a connection.
One of the flags in the CONNECT control packet is the Will. It determines whether the MQTT broker gets to store and publish the last will message associated with the last session. A will message is meant to be published once the MQTT client reestablishes a connection, in the event that the connection was interrupted or lost.
Security, even in IoT needs to be a priority. The SSL/TLS feature helps you ensure data confidentiality and integrity.
This feature ensures that the client can reconnect if the connection to the MQTT broker is severed.
This feature ‘stores’ messages when the recipient MQTT broker/client is disconnected.
This feature allows for communication with brokers that allow the connection between client and server to persist, depending on the KeepAlive flag value in the CONNECT control packet.
Standard TCP Support
This feature allows for communication with brokers with TCP support.
This feature means that when the publisher requests the broker to send messages to the clients subscribed to a topic, execution only continues after successful delivery.
This feature means that when the publisher requests the broker to send messages to the clients subscribed to a topic, execution can continue, and the clients can receive messages at different times.
Before looking at some paho mqtt examples, let’s understand MQTT’s origins and some basic concepts.
MQTT is an IoT protocol that enables the exchange of messages between devices. It uses a publish-subscribe model to achieve this.
MQTT works very similarly to the HTTP/HTTPS protocol (where a client sends in a request to a server and receives a response containing what they requested). MQTT is however extremely lightweight and has a low footprint.
MQTT was created by Andy Stanford-Clark (IBM) and Arlen Nipper (CTO at Cirrus Link) in 1999. It is now an OASIS standard, with v3.1.1 being an older ISO standard as well. Version 5 is the latest MQTT specification
It’s important to understand some MQTT basic concepts before you begin working with the paho mqtt examples. Let’s delve into them below:
The Publish-Subscribe Pattern/Model
It is also known as the pub-sub pattern. There are several devices that exchange data in this model which we will look at shortly.
In the pub-sub model, a publisher sends out messages to subscribers that have ‘subscribed’ to a particular topic.
The pub-sub model is decoupled (the publisher is not aware of the presence of the recipient subscribers).
The broker or server is at the heart of the pub-sub model. It is the server equivalent in the HTTP/HTTPS protocol. All clients must connect to the server.
The broker filters all incoming messages and sends them out to the subscribers who have subscribed to specific topics.
The publisher is an MQTT client who sends messages to the broker for distribution to the subscribers.
The subscriber is an MQTT client who receives messages from the broker for topics they are subscribed to.
Both publishers and subscribers need to establish a connection with the broker.
Sometimes an MQTT client can be both a publisher and a subscriber. For example, when a subscriber receives a message, it could send out a message to confirm the message’s receipt.This way, it becomes both a publisher and subscriber.
It is also known as a channel or subject. This is the area of interest that the subscriber subscribed to.
A Pub-Sub Pattern Demonstration
I will use a story from Richard Branson’s book, “Screw It, Let's Do It: Lessons in Life” to illustrate the pub-sub model.
In the book, Richard and his friend Per went on several hot air balloon adventures. They needed to know their altitude so as not to fly too high as to lack oxygen or too low so as to crash.
They used an altitude sensor (let’s call it sensor 1). For the sake of our demonstration, let’s assume that the altitude sensor had a Raspberry Pi 3 board.
The Raspberry Pi 3 board in the sensor will send out altitude information to various people:
- Richard and Per
- Air Traffic Control (in case of a crash)
- Maritime Patrol (in case of a crash)
- News station (in case of a crash)
The following diagram might make things even clearer:
Image source: "MQTT Essentials - A Lightweight IoT Protocol" by Gaston C. Hillar
The altitude sensor with the Raspberry Pi 3 board is the publisher (sensor1). It sends out messages to subscribers which could be anything from an Android tablet or iOS smartphone to a walkie-talkie in Richard’s or Per’s hand.
For the subscriber to receive information about the altitude, however, they need to have subscribed to the topic. In our example, the topic is ‘sensor1/altitude’.
The broker will receive the message and topic from the publisher and only send it to the subscribers subscribed to the ‘sensor1/altitude’ topic.
The news station will not receive the message because it is not subscribed to the ‘sensor1/altitude’ topic. The flying is a private event. The news station could be subscribed to another topic though, ‘sensor1/emergency’, and would only receive a message if there was an accident and Richard and Per’s flying had been made known to the public.
With that out of the way, then it will be easier for us to work with the MQTT protocol and the Paho Python MQTT Client.
There are several ways to install the Eclipse Paho Python MQTT Client.
Pip is Python’s package manager (Package Installer for Python in full)
Go to your terminal (Ctrl+Alt+T on Ubuntu) and enter the following command:
pip install paho-mqtt
You should see a ‘successfully installed’ message.
If you have any permission errors, you can use sudo
sudo pip install paho mqtt
You need to check the version to which Paho MQTT is attached if you have several Python versions.
In my case, it was installed under Python 3.9. I will make a mental note of this when running Python paho-mqtt. I may have to specify the Python version for it to run as intended.
A virtual environment allows you to confine your project to a folder with all the necessary dependencies for it to run effectively. This way, you avoid conflicts that would result from using different versions of a package, for example.
The official Python documentation recommends the creation of virtual environments using the venv module.
Choose the directory in which to create your virtual environment.
Create your virtual environment using the following command (make sure that your current working directory is the top-level directory containing the directory in which you wish to create your virtual environment)
python3 -m venv /path/to/directory/where/you/want/to/create/your/virtual/environment
Activate your virtual environment (the following command works on a bash or zsh shell)
Note that you don’t need to activate your virtual environment. Activation only allows you to run the installed scripts without using full paths.
Install Python paho-mqtt via pip
pip install paho-mqtt
After installing the Paho MQTT Client, we need to use a broker to distribute the messages to the correct subscribers. We are going to install the broker first and then connect to it.
There are several ways to install the Mosquitto MQTT broker.
In this case, you can use a package manager like pip (Linux) or brew (MacOS) depending on your Operating System and/or distro.
For our illustration, we will use Linux Ubuntu 20.04
Enter the following command to install the Mosquitto MQTT broker
sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa
Enter your password
Follow the prompts
sudo apt-get update
Install the Ubuntu broker package
sudo apt-get install mosquitto
Follow the prompts
Install the Mosquitto client packages that run the message publication commands and topic subscription via the following command:
sudo apt-get install mosquitto-clients
Check the recently installed mosquitto service status
sudo service mosquitto status
You should see a message like… ‘starting MQTT Broker…’
Confirm that the Mosquitto server is listening via the default port: 1883
netstat -an | grep 1883