Beginners Guide To The Paho MQTT Python Client

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.

Tutorial Outline

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:

• test.mosquitto.org
• broker.hivemq.com
• iot.eclipse.org

Installing The Client

You can Install the MQTT client using PIP with the command:

I usually isn’t as straightforward as using the command

pip install paho-mqtt

as most machines have multiple version on 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:

pip --version

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.

Video- Installing The Mqtt Python Client and Other Modules Using PIP

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()
• publish()

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:

client =mqtt.Client(client_name)

See Working with Client objects for more details

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

client.connect(host_name)

See Working with Client Connections for more details.

Publishing Messages

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:

client.publish("house/light","ON")

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.

1. Create new client instance
2. Connect to broker
3. Subscribe to topic
4. 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.

However at this stage it may be better to just except them and proceed with the script.

To process callbacks you need to:

1. Create callback functions to Process any Messages
2. 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.

Useful Exercises

You should try commenting out, one by one, the lines:

• client.on_message=on_message
• client.loop_start()
• client.Loop_stop()

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:

client1.on_log=on_log

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:

• MQTT Subscribe-Python MQTT Client Examples
• MQTT Publish-Python MQTT Client Examples

Video – Using the Paho Python MQTT Client.

Common Problems

1. Not seeing any messages or not seeing all expected messages.

Possible causes

1. You haven’t started a network loop or called the loop() function. Or you haven’t registered or created the callback functions.
2. You haven’t subscribed to the correct topics or subscription has failed.
3. Access restrictions are in place.

2.- My messages don’t appear in the order I expected?

Possible causes

1. 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