Paho Python MQTT Client – Publish With Examples

publishing-messagesIn this tutorial we will look at how you publish messages using the Paho Python MQTT client.

We will use an example python script to publish messages, process the publish acknowledgements and examine QOS (quality of service) settings.

To publish a messages you use the publish method of the Paho MQTT Class object.

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.

Publishing a Message

To publish a message you need to:

  1. Create a client object.
  2. Create a client connection.
  3. publish the message
  4. Examine the return code of the publish request
  5. Examine the publish acknowledgement using the on_publish callback
Example code:
import paho.mqtt.client as paho
def on_publish(client,userdata,result):             #create function for callback
    print("data published \n")
client1= paho.Client("control1")                           #create client object
client1.on_publish = on_publish                          #assign function to callback
client1.connect(broker,port)                                 #establish connection
ret= client1.publish("house/bulb1","on")                   #publish

Note 1: you don’t appear to need a client loop to process the on_publish callback.

Note2: When you publish a message the publish method returns a tuple (result, mid).

The result is the error code. A result of 0 indicates success.

The mid value is an integer that corresponds to the published message number as assigned by the client.

The mid value can be used with the on_publish callback to check that the messages was published.

On_publish Callback

When the message has been published to the Broker an acknowledgement is sent that results in the on_publish callback being called.

The on_publish callback function must receive three parameters

on_publish(client, userdata, mid)

The client is the client object, and is useful when you have multiple clients that are publishing data.

The userdata is user defined data which isn’t normally used.

The mid value is the message id and can be used with the mid value returned from the publish method to check that a particular message has been published.

In the screen shot below I have printed the mid value from the publish message and on publish callback.

You can see that the numbers match which indicated that both messages were published OK


Message Flow and Quality of Service Example

If you want to try and ensure that the subscriber gets a message even though they might not be online then you need to publish with a quality of service of 1 or 2.

The schematic below shows the message flow between client and broker for messages with QOS of 0, 1 and 2.


The  screen shot below shows the results of running a test Python script that publishes 3 messages with QOS of 0,1 and 2 respectively


Notice with QOS set to 2 there are more messages generated.

In addition messages sent with QOS of 0 are not acknowledged by the broker but instead by the sending client.

There is no guarantee that the broker received them. See:

Publishing on Restricted Topics

You may not be allowed to publish messages on certain topics.

This is controlled by the broker See Configuring Topic Restriction on Mosquitto.

However what happens if you do publish on a restricted topic?

Well as far as the client is concerned the publish succeeds, and if I run the previous script but restrict the topic then my client output would be identical to that shown above.

However this is what I would see on the Sever (broker)


Notice the denied publish message on the server console. Also notice the normal publish acknowledgement sequence.

Retain Message Flag

When publishing a message you can also set the retain message flag.

This flag tells the broker to store the last message that you sent.

This is very useful if you only publish messages at infrequent intervals- See Retained messages-Example’

Disconnecting After Publish

If you only publish messages at infrequent intervals then you will probably want to disconnect the client between publishing.

You can use the disconnect method along with the on_disconnect callback for this.

This type of disconnect does not result in a last will and testament message.

def on_disconnect(client, userdata, rc):
   print("client disconnected ok")
client1.on_disconnect = on_disconnect

Publishing and The Loop

Although you can publish messages without starting a loop (See the Loop) you will need to start a loop or call the loop to send automatic ping messages.

Therefore you may find that your client gets disconnected , and without the loop you don’t see the disconnect message.

Therefore if you do this you will need to consider setting the keepalive to a higher value (60 seconds by default).

Note: If you publish messages inside the keep alive value then the connection isn’t closed by the server/broker.

Publishing Using SSL

You will need to add a broker/server CA key to the client, See Configuring Mosquitto for SSL for details about keys.

You then use the client.tls_set function before you connect. E.G.


Depending on how you’ve configured the broker you may need to use the TLS version parameter (code below set client to use TLSv1.2.


Because SSL normally uses port 8883 you will also need to change the port when connecting.

Publishing Using WebSockets

You can also publish messages over webSockets. You need to tell the client to use Websockets when creating the client object as show below:

Use the command

client= paho.Client(“control1”,transport=’websockets’)

instead of simply

client= paho.Client(“control1”)

The publish uses the same procedure and process as standard MQTT. See My MQTT WebSockets Notes

Publishing Video

Here is a video that I created that covers the main points from above. Grateful of any feedback

Common Questions and Answers

Q- Do I know if and when my published messages have been received by a client?

A- No. You only know that the broker has received them, and then only if the QOS is set to 1 or above.

Q- What happens if I publish on the wrong topic?

A- Generally unless the topic has an invalid topic address you wont know.

Q- What happens if I publish on a restricted topic?

A- You wont know as it will appear to succeed.

Q- How do I know that no one else is using that topic?

A- You don’t. You could subscribe to the topic beforehand and look for activity.

Q- Can I publish on any topic that I want to?

A- Yes unless the broker administrator has configured topic restrictions.

Using The Paho Python MQTT Client Tutorials

Related tutorials and Resources

The Hive MQTT essentials series especially part 3 and part 4 for this tutorial.



  1. I’ve been unable to find out about publishing various payload types, like ‘comma seperated variable files’.

    I’m appending 4 integer variables to a CSV text file to be used as a payload.

    Have you any experience of this? I’m going to make a PayPal contribution from my company for all the help you’ve given me.

  2. I’m using the paho mqtt broker in Raspbian Linux, and the ESP8266 Arduino PubSubClient.h library.
    I’m getting a -2 result from the rc connection return code (connection refused due to bad client id).
    I’ve read about clientid being restricted to alpha-numeric characters, no symbols like dashes etc, and that they have to be utf-8 encoded.

    I see from your example in the line:
    client1= paho.Client(“control1”)
    that you’ve used a regular ascii string to create the clientID.

    I’ve tried creating random clientID’s, but that requires a clean session to be set to true, and from the pubsubclient.h source code I don’t see the ability to set that anywhere. So best to avoid random ID’s.

    I don’t know if my arduino client library and paho broker are even compatible, but for now I’ll assume it is and the clientID string just needs to be understood.

    In your tutorial: “Paho Python MQTT Client Objects” it says clientID’s will be auto generated if the clientID parameter is left blank when clean session is set to true on instantiating a new client object. I don’t know if pubsubclient.h sets a clean session to true by default, or if it even uses that parameter.

    What do you know about guidelines/restrictions etc on naming of clientID’s that aren’t rejected by the broker?

    1. Alan

      This is taken from the specification

      The payload of the CONNECT Packet contains one or more length-prefixed fields, whose presence is 557 determined by the flags in the variable header. These fields, if present, MUST appear in the order Client 558 Identifier, Will Topic, Will Message, User Name, Password
      [MQTT-3.1.3-1]. 559 Client Identifier 560 The Client Identifier (ClientId) identifies the Client to the Server. Each Client connecting to the Server has 561 a unique ClientId. The ClientId MUST be used by Clients and by Servers to identify state that they hold 562 relating to this MQTT Session between the Client and the Server
      [MQTT-3.1.3-2]. 563
      564 The Client Identifier (ClientId) MUST be present and MUST be the first field in the CONNECT packet 565 payload [MQTT-3.1.3-3]. 566
      567 The ClientId MUST be a UTF-8 encoded string as defined in Section 1.5.3
      [MQTT-3.1.3-4]. 568 569 The Server MUST allow ClientIds which are between 1 and 23 UTF-8 encoded bytes in length, and that 570 contain only the characters 571 “0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ”


Leave a Reply

Your email address will not be published. Required fields are marked *