in Python Tutorials, Tutorials

Tutorial – Using MQTT with Python (Part 1): The Client class

MQTT (Message Queue Telemetry Transport) is an application level protocol that works on a TCP stack and is based on the publish/subscribe paradigm; we already talked a bit about MQTT in this article.

Here, we will mainly discuss about creating MQTT clients through which we will be able to send and receive MQTT messages; we will use Mosquitto as our broker: a small introduction to Mosquitto and to its installation is contained in the previously linked article, alongside an introduction to the MQTT protocol in general.

The Python library that implements the MQTT protocol is paho-mqtt; it can be easily installed using pip, the Python package installer, by executing the following command from a shell:

$ pip install paho-mqtt

In case you both have Python and Python3 installed on your machine, you should use the Python3 version of of pip to specify you’re installing paho-mqtt for Python3:

$ pip3 install paho-mqtt

The paho-mqtt library is structured in two modules:

  • The Publish module, which provides an interface to directly publish one or more messages in an MQTT network, which proves to be useful in situations in which you don’t have to send multiple messages in an interval of time or when you don’t need a fully functional client interface;
  • Client, which provides tools to implement our own MQTT Client and that will be the module used in this tutorial.

Inside the paho.mqtt.client module we can find the Client class; an instance of this class can be used to manager the connection to the broker, the sending and the receiving of messages. The client class comes with a set of already implemented functionalities that provide an interface to execute the standard operations that an MQTT client should be able to perform.

When creating an instance of the Client class, there is no mandatory parameter to be passed, since every possible aspect of the client has a well documented default behaviour: the aim of this tutorial is not to dive deep down in the exploration of each facet of th library, we’re more focused on using it to implement our applications in a fast and practical way. With that said, it’s in our interest to associate an identifier to our clients, so that we don’t have to use an automatically generated one; to do so, we use the following syntax:

from paho.mqtt.client import Client
client = Client(client_id = "client_1")

Now that we have a Client object, we can connect it to the chosen broker by calling the connect method, passing the IP address of the machine that hosts the broker and the TCP port used, which defaults to 1883. In this tutorial we will use a number of clients connected to the same broker, with everything on one machine, so we will refer to the local address of said machine:


Now that the client is connected to the broker, everything is fully set up. Yo start using the client in our application, we can invoke the subscribe and publish methods.

The first of the two is used to subscribe to a specific topic in the MQTT network, passing to it a string that identifies the chosen topic; it’s also possible to specify the desired quality of service through the input parameter qos, which defaults to 0: a qos of 0 means that we’re using a fire and forget approach, we don’t care if someone receives them or not.


The second method, publish, allows us to publish messages into the network on a specific topic. The content of the message will have to be specified via the payload input parameter:

client.publish(topic = "topic_2", payload = "test") 

In the next article we will continue exploring the topic, by introducing the concepts of callback and loop functions.

Callback e Loop →

Write a Comment