The paho MQTT python client from Eclipse supports MQTT v 3.1 and 3,1.1, and works with Python 2.7 and 3.x.
Installing The Client
You can Install the client using PIP with the command:
- pip install paho-mqtt
You will find the online client documentation here. and also the install files if you need them.
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:
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
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 where sent to that topic.
The broker is ,in effect, publishing messages 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 except 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.
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:
Here is a video that covers the main points above- Using the Paho Python MQQT 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.
Related Tutorials and Resources
- MQTT overview for Beginners
- Understanding the MQTT Protocol Packet Structure
- Understanding MQTT Topics
- My Python Working Notes