The paho MQTT python client from Eclipse supports MQTT v 3.1 and 3,1.1, and now MQTTv5 and works with Python 3.x.
In this tutorial we look at the main client object, and it’s methods.
We will then create a simple Python example script that subscribes to a topic and publishes messages on that topic.
If all goes well we should see the published messages.
The example scripts are kept simple, and I don’t include any error checking.
I use my own locally installed broker, but you will probably find it easier when starting to use a free online broker like:
Installing The Client
You can Install the MQTT client using PIP with the command:
It usually isn’t as straightforward as using the command
pip install paho-mqtt
as most machines have multiple versions of python installed and there are several versions of pip and the actual command depends on whether you are on Windows or Linux.
Therefore use the command:
before installing to find out where pip will install the files.
The screen shot below is taken from my Windows 10 machine where I have two versions of Python installed (3.4 and 3.6)
If I ran
pip install paho-mqtt
It would install the client in the 3.6 site packages. To install it for the 3.4 version I would need to run.
pip3.4 install paho-mqtt
On my Raspberry pi (linux) using the command
pip install paho-mqtt
would install the client for use my python version 2.7
To install for version 3.5 I would need to run:
pip3 install paho-mqtt
Note: if you have multiple versions of python on your machine then take a look at my Python Notes.
Note: On the PI and maybe other linux versions if you get an error on install then use sudo pip install paho-mqtt.
You will find the online client documentation here. and also the install files if you need them.
The Python MQTT Client
The core of the client library is the client class which provides all of the functions to publish messages and subscribe to topics.
If you want to look at the code for this class you should find the code in the client.py file in the mqtt directory. (windows machine)
This directory is located in python34\Lib\site-packages\paho\mqtt (windows see Python Notes.)
Where python34 is the root of my python install.
Main Client Methods
The paho mqtt client class has several methods.The main ones are:
- connect() and disconnect()
- subscribe() and unsubscribe()
Each of these methods is associated with a callback. See Later.
Importing The Client Class
To use the client class you need to import it. Use the following:
Import paho.mqtt.client as mqtt
Creating a Client Instance
The client constructor takes 4 optional parameters, as shown below .but only the client_id is necessary, and should be unique.
Client(client_id=””, clean_session=True, userdata=None, protocol=MQTTv311, transport=”tcp”)
To create a instance use:
Connecting To a Broker or Server
Before you can publish messages or subscribe to topics you need to establish a connection to a broker.
To do this use the connect method of the Python mqtt client.
The method can be called with 4 parameters. The connect method declaration is shown below with the default parameters.
connect(host, port=1883, keepalive=60, bind_address="")
Note: You only need to supply the broker name/IP address.
The general syntax is
See Working with Client Connections for more details.
Once you have a connection you can start to publish messages.
To do this we use the publish method.
The publish method accepts 4 parameters. The parameters are shown below with their default values.
publish(topic, payload=None, qos=0, retain=False)
The only parameters you must supply are the topic, and the payload.
The payload is the message you want to publish.
The general syntax is:
Example Python Script:
We are now in a position to create our first Python Script to Publish a message.
The script below publishes the message OFF to topic house/main-light
import paho.mqtt.client as mqtt #import the client1 broker_address="192.168.1.184" #broker_address="iot.eclipse.org" #use external broker client = mqtt.Client("P1") #create new instance client.connect(broker_address) #connect to broker client.publish("house/main-light","OFF")#publish
Note: I am using my own local broker but you can use an online broker like the one at iot.eclipse.org.
Subscribing To Topics
To subscribe to a topic you use the subscribe method of the Paho MQTT Class object.
The subscribe method accepts 2 parameters – A topic or topics and a QOS (quality of Service) as shown below with their default values.
We will now subscribe to topics and in this example we will subscribe to the topic house/bulb1 which is also the same topic that I’m publishing on.
Doing this lets us see the messages we are publishing but we will need to subscribe before we publish.
So our script outline becomes.
- Create new client instance
- Connect to broker
- Subscribe to topic
- Publish message
Our new example script is shown below, and I have inserted some print statements to keep track of what is being done.
import paho.mqtt.client as mqtt #import the client1 broker_address="192.168.1.184" #broker_address="iot.eclipse.org" print("creating new instance") client = mqtt.Client("P1") #create new instance print("connecting to broker") client.connect(broker_address) #connect to broker print("Subscribing to topic","house/bulbs/bulb1") client.subscribe("house/bulbs/bulb1") print("Publishing message to topic","house/bulbs/bulb1") client.publish("house/bulbs/bulb1","OFF")
If we run the script this is what we see:
So where is the message that I published?
When a client subscribes to a topic it is basically telling the broker to send messages to it that are sent to the broker on that topic.
When the client receives messages it generate the on_message callback.
To view those messages we need to activate and process the on_message callback.
Aside: Callbacks are an important part of the Python Client and are covered in more detail in Understanding Callbacks.
Callbacks also depend on the client loop which is covered in Understanding the Client Loop.
However at this stage it may be better to just accept them and proceed with the script.
To process callbacks you need to:
- Create callback functions to Process any Messages
- Start a loop to check for callback messages.
The client docs describe the on_message callback and the parameters it excepts.
Here is my callback function, which basically just prints the received messages:
def on_message(client, userdata, message): print("message received " ,str(message.payload.decode("utf-8"))) print("message topic=",message.topic) print("message qos=",message.qos) print("message retain flag=",message.retain)
Note the message parameter is a message class with members topic, qos, payload, retain.
I.e message.topic will give you the topic.
Now we need to attach our callback function to our client object as follows:
client.on_message=on_message #attach function to callback
and finally we need to run a loop otherwise we won’t see the callbacks. The simplest method is to use loop_start() as follows.
client.loop_start() #start the loop
We also need to stop the loop at the end of the script (loop_stop()), and in addition wait a little to give the script time to process the callback, which we accomplish using the time.sleep(4) function.
This what our completed example script now looks like:
import paho.mqtt.client as mqtt #import the client1 import time ############ def on_message(client, userdata, message): print("message received " ,str(message.payload.decode("utf-8"))) print("message topic=",message.topic) print("message qos=",message.qos) print("message retain flag=",message.retain) ######################################## broker_address="192.168.1.184" #broker_address="iot.eclipse.org" print("creating new instance") client = mqtt.Client("P1") #create new instance client.on_message=on_message #attach function to callback print("connecting to broker") client.connect(broker_address) #connect to broker client.loop_start() #start the loop print("Subscribing to topic","house/bulbs/bulb1") client.subscribe("house/bulbs/bulb1") print("Publishing message to topic","house/bulbs/bulb1") client.publish("house/bulbs/bulb1","OFF") time.sleep(4) # wait client.loop_stop() #stop the loop
If you run the script you should see the following
Note: logically you should be able to start the loop before you create a client connection, but it you do then you get unexpected results.
You should try commenting out, one by one, the lines:
and run the script to see the results.
Receiving Messages outside of the on_message Callback
A common question is how do you get received messages into the main script from the on-message callback. There are several ways of doing this as explained in Receiving Messages with the Paho MQTT Python Client
Troubleshoot using Logging
To help troubleshoot your applications you can use the built in client logging callback.
To use it you create a function to process the logging callback. My function is shown below and it simply prints the log message.
def on_log(client, userdata, level, buf): print("log: ",buf)
and then attach it to the callback:
You should then see details of connections,publish and subscribe messages like that shown below:
The above is a quick overview to get started you can find out more details in the tutorials below:
Video – Using the Paho Python MQTT Client.
1. Not seeing any messages or not seeing all expected messages.
- You haven’t started a network loop or called the loop() function. Or you haven’t registered or created the callback functions.
- You haven’t subscribed to the correct topics or subscription has failed.
- Access restrictions are in place.
2.- My messages don’t appear in the order I expected?
- The callback functions are async functions which can be called at any time. Use a queue to store the messages and print in one place. I use the Python logging module.
Important Changes for MQTTv5
Although you may not currently be working with MQTTv5 I would advise you to take a look at the Client changes for MQTTv5 tutorial as by making slight changes to your code you can make it future proof.
MQTT Python Kindle Book
If you prefer all of my MQTT pythons tutorials all in one place then you might be interested in my Kindle Book.
Working with the Paho Python MQTT Client
Related Tutorials and Resources