Paho Python MQTT Client Subscribe With Examples

To receive messages on a topic you will need to subscribe to the topic or topics.

To subscribe to a topic you use the subscribe method of the Paho MQTT Class object.

In this tutorial we will look at some examples of using the subscribe method.

The diagram below illustrates the subscribe message flow.

The subscribe method accepts 2 parameters – A topic or topics and a QOS (quality of Service) as shown below with their default values.

The documentation lists three ways of calling the subscribe method.

Method 1- Uses a single topic string This is an example function call.

Method 2- Uses single tuple for topic and QOS -(topic,qos)

Method 3- Used for subscribing to multiple topics and uses a list of tuples [(topic1,qos),(topic2,qos),(topic3,qos)]

The subscribe function returns a tuple to indicate success, and also a message id which is used as a tracking code.

Subscribe Acknowledgements

The MQTT broker/server will acknowledge subscriptions which will then generate an on_subscribe callback.

The format of the callback function is shown below:

The mid value can be compared with the one returned by the function call to check for successful subscription requests.

MQTT Subscribe Success and Failure Examples:

We will use a simple Python subscribe script to show:

1. Successful subscription
2. Failed subscription raising a value error -To make this fail I set the QOS to 5 which is invalid
3. Failed subscription with an MQTT_ERR_NO_CONN –To make this fail I didn’t connect to the broker before I tried to subscribe.

Notes:

In the screen shot above you can see in the successful subscribe that the mid (message ID) values that are printed match.

This shows that the subscribe was successful.

You would use the mid values when checking on multiple subscriptions as some might fail and others succeed

Also note the result value of 0 which is a success code (MQTT_ERR_SUCCESS)

The last example shows a fail due to a connection error the mid value is None. The (MQTT_ERR_NO_CONN) value is 4 which indicates a connection failure.

The table below taken from the client source show the other error codes and their meaning:

Subscribing to Multiple MQTT Topics

In this example we will look at the different ways of subscribing to multiple MQTT topics.

You can subscribe by:

• • Calling the subscribe function for each topic.
  • Calling the subscribe function with a topic list

The screen shot below illustrates both methods

Firstly we use single topic subscriptions to subscribe to 2 topics. Notice that two messages are sent and we would need to track two message ids.

In the second example we subscribe to 3 topics using a list. Notice that a single subscribe message is sent, and results in a single acknowledgement.

Notice also how the message ids match.

Setting The Quality of Service

If you want to try and ensure that the subscriber gets a message then you need to subscribe with a quality of service of 1 or 2. See

• Understanding MQTT QOS Levels- Part 2
• Understanding MQTT QOS Levels- Part 1

However even this doesn’t guarantee that they will receive the message, as you also need to have subscribed with a persistent connection (not the default). See Clean Sessions and QOS (quality of service) -Example.

When you subscribe the suback message will tell you what QOS the broker has assigned to the subscription.

Although it could be downgraded it is usually the same as what you set in the subscription request.

Subscribe Wait Loops

In my simple scripts demo scripts I don’t process the callbacks to check for successful subscriptions, but in real scripts you will need to.

Generally it will make no sense proceeding unless you have successfully subscribed.

Therefore I tend to use the following format:

1. Subscribe
2. Wait for success or quit
3. Proceed

Here is a snippet of code from my wait for function which I use to wait for connections and subscriptions

def wait_for(client,msgType,period=0.25):
 if msgType=="SUBACK":
  if client.on_subscribe:
    while not client.suback_flag:
      logging.info("waiting suback")
      client.loop()  #check for messages
      time.sleep(period)

Clean Session Flag and Remembering Subscriptions

If you connect using the clean session flag set to False then the next time you connect you won’t need to subscribe as the broker remembers your subscriptions.

You can use the unsubscribe method to cancel existing subscriptions.

Subscribing to Restricted Topics

Brokers like the Mosquitto broker allow you to control access to topics.

This means that some topics may be restricted, and you are unable to subscribe to them.

Unfortunately the client doesn’t receive any indication of this, and so it appears that the subscription has been successful but it has not. See Using the ACL to restrict topic access on the Mosquitto broker.

The only way to be sure that a subscribe has really succeeded is to receive messages on that topic.

Effects of Retained Messages

When you subscribe to a topic that has had messages published with the retain flag set then you will receive any retained messages.

The client can detect that is a retained messages by examining the message.retain flag in the on_message callback as shown in the code snippet below:

def on_message(client, userdata, message):
    print("message received  ",str(message.payload.decode("utf-8")),\
          "topic",message.topic,"retained ",message.retain)
    if message.retain==1:
        print("This is a retained message")

– See Understanding Retained messages

Unsubscribing

If you no longer need to receive messages on a topic you can unsubscribe from that topic using the unsubscribe method.

The method only accepts 1 argument the topic.

The call returns a return code and mid value like the subscribe method and is acknowledged by a UnSubAck response which triggers the on_unsubscribe callback function.

Again you can compare the mid values in the response code and on_unsubscribe callback to check for success or failure.

Subscribe Suggestions

• Use a try block on the subscribe call.
• Check the return code result value for a success
• Check that all subscriptions have been successful by examining the mid value in the callback.
• Use a wait loop to wait for successful subscriptions before proceeding.
• Consider publishing to the same topic to verify subscription.

Video

If you prefer a videos I’ve created a YouTube video that covers the subscribe process that you may enjoy watching.

There is another video that covers subscribe acknowledgements

Next—>MQTT Publish-Python Client Example

Common Questions and Answers

Q- I have subscribed to a topic when using a persistent connection. I’ve been disconnected for a few hours what happens when I re-connect?

A– When you reconnect you will see all messages that have been published on that topic while you were disconnected provided the messages were published with a QOS of 1 or 2 and that you originally subscribed with a QOS of 1 or 2.

Q- How do I subscribe to all topics?

A- Subscribe to #

Course Links

1. Introduction to the Paho Python MQTT Client
2. Introduction to the Client Class
3. Connecting to a Broker
4. Publishing Using The Paho Python MQTT Client
5. –Subscribing using The Paho Python Client
6.  Receiving Messages with the Paho MQTT Python Client
7. Understanding The Loop
8. Understanding Callbacks
9. Handling Multiple Client Connections

Related tutorials and Resources

• Understanding MQTT Topics
• MQTT Publish and Subscribe for Beginners
• Video –Checking MQTT Subscribe Acknowledgements