Using MQTT on Raspberry Pi: A Comprehensive Guide

Raspberry Pi (https://www.raspberrypi.org/) is a microcomputer board developed by the Raspberry Pi Foundation in the UK, based on ARM architecture. This board provides USB and Ethernet interfaces, allowing connection to keyboards, mice, and network cables. It has the basic functions of a PC, and the Raspberry Pi integrates Wi-Fi, Bluetooth, and a large number of GPIO, making it widely used in education, home entertainment, and the Internet of Things.

MQTT (https://www.emqx.io/cn/mqtt) is a lightweight IoT messaging protocol based on a publish/subscribe model, providing real-time reliable messaging services for connected devices with minimal code and bandwidth. It is suitable for devices with limited hardware resources and networks with limited bandwidth. Therefore, the MQTT protocol is widely used in industries such as IoT, mobile internet, smart hardware, vehicle networking, and power energy.

In this project, we will write a simple MQTT client using Python on the Raspberry Pi and implement functions such as connecting to the MQTT server, subscribing, unsubscribing, and sending/receiving messages.

Installing Python3

This project uses Python3 for development. Generally, the Raspberry Pi system comes with Python3 pre-installed. If you are unsure whether it is installed, you can confirm with the command below.

python3 --version

If it shows Python 3.x.x (where x is a number), it means it is installed. Otherwise, please use the apt command to install it (or follow the Python3 installation guide (https://wiki.python.org/moin/BeginnersGuide/Download) instructions).

sudo apt install python3

Installing MQTT Client Library

To facilitate connection to the MQTT server, we need to install the paho-mqtt library. You can choose one of the following two methods for installation.

Install from Source

git clone https://github.com/eclipse/paho.mqtt.python cd paho.mqtt.python python3 setup.py install

Install using pip3

pip3 install paho-mqtt

Connecting to the MQTT Server

This article will use the free public MQTT server provided by EMQ X (https://www.emqx.io/cn/mqtt/public-mqtt5-broker) which is created based on the EMQ X MQTT IoT cloud platform (https://cloud.emqx.io). The server access information is as follows:

• Broker: broker.emqx.io

• TCP Port: 1883

• Websocket Port: 8083

If necessary, you can also quickly install the EMQ X server locally using Docker.

docker run -d --name emqx -p 1883:1883 -p 8083:8083 -p 8084:8084 -p 18083:18083 emqx/emqx

Example Connection Code

# test_connect.py import paho.mqtt.client as mqtt
# Callback function. This function is triggered when attempting to connect to the MQTT broker.
# client is the client instance for this connection.
# userdata is user information, usually empty. However, if needed, it can also be set through the user_data_set function.
# flags contains a dictionary of server response flags.
# rc is the response code.
# Generally, we only need to care if rc response code is 0.
def on_connect(client, userdata, flags, rc):    if rc == 0:        print("Connected success")    else:        print(f"Connected fail with code {rc}")
client = mqtt.Client() client.on_connect = on_connect client.connect("broker.emqx.io", 1883, 60) client.loop_forever()

Save the above code as test_connect.py and run it

python3 test_connect.py

In the on_connect function, we check the response code. If it is 0, we output Connected success indicating a successful connection. If another number is returned, we need to check the response code below.

0: Connection successful
1: Connection failed - incorrect protocol version
2: Connection failed - invalid client identifier
3: Connection failed - server unavailable
4: Connection failed - incorrect username or password
5: Connection failed - unauthorized
6-255: Undefined
If there are other issues, you can check the network status,
or confirm if `paho-mqtt` is installed.

In the concept of the MQTT protocol, messages are passed through topics. For example, if device A sends a message to topic T, only devices subscribed to topic T can receive it. Therefore, merely connecting to the MQTT server is not very meaningful; to fully use the MQTT service, we also need to know how to subscribe and publish messages.

Subscribing to Messages

Open any editor, input the code below, and save it as subscriber.py:

# subscriber.pyimport paho.mqtt.client as mqtt
def on_connect(client, userdata, flags, rc):    print(f"Connected with result code {rc}")    # Subscribe, needs to be placed in on_connect    # If the connection to the broker is lost and reconnects, it will still continue to subscribe to the raspberry/topic topic    client.subscribe("raspberry/topic")
# Callback function, triggered when a message is received
def on_message(client, userdata, msg):    print(f"{msg.topic} {msg.payload}")    client = mqtt.Client()client.on_connect = on_connectclient.on_message = on_message
# Set the will message, when the Raspberry Pi loses power or the network is interrupted, send the will message to other clientsclient.will_set('raspberry/status', {"status": "Off"})
# Create connection, the three parameters are broker address, broker port number, and keep-alive timeclient.connect("broker.emqx.io", 1883, 60)
# Set network loop blocking, will not actively end the program before calling disconnect() or crashingclient.loop_forever()

Calling the subscribe() function allows the Raspberry Pi to subscribe to a topic. In the above code, we used it to subscribe to the raspberry/topic topic and listen for messages.

Additionally, we used will_set() to set the will message. The will message is a feature of MQTT; when a device unexpectedly disconnects from the network, it sends a message to a specific topic. Through this feature, we can know whether the Raspberry Pi has lost power or encountered a network anomaly.

Publishing Messages

Open any editor, input the code below, and save it as publisher.py:

import paho.mqtt.client as mqttimport time
def on_connect(client, userdata, flags, rc):    print(f"Connected with result code {rc}")    client = mqtt.Client()client.on_connect = on_connectclient.connect("broker.emqx.io", 1883, 60)
# Every 1 second, send a message to raspberry/topic, sending 5 timesfor i in range(5):    # The four parameters are: topic, sent content, QoS, whether to retain the message    client.publish('raspberry/topic', payload=i, qos=0, retain=False)    print(f"send {i} to raspberry/topic")    time.sleep(1)
client.loop_forever()

Calling the publish() function allows sending messages to a topic. In the above code, we used it to send messages to the topic raspberry/topic. The QoS parameter is another MQTT feature; if you want to learn more about QoS, you can check out the introduction to MQTT QoS (https://www.emqx.io/cn/blog/introduction-to-mqtt-qos) for now we set it to 0.

We use the MQTT 5.0 client tool – MQTT X (https://mqttx.app/cn/) for the following tests.

Testing Message Subscription

Run the Python code and actively send a message.

1. Open the terminal, run the Python code to listen for messages.

   python3 subscriber.py
   

2. Use the MQTT X client to connect to the MQTT server and send a message to the topic raspberry/topic.

   

3. Check the Raspberry Pi terminal information, and you will see that the message published by MQTT X has been successfully received.

   

Testing Message Publishing

1. In the MQTT X client, subscribe to the raspberry/topic topic.

2. Run the Python code in the terminal.

3. In the MQTT X client, check the messages sent by the Raspberry Pi.

   

Testing Will Message

Next, test whether the will message is set successfully.

1. In the MQTT X client, subscribe to raspberry/status.

   

2. Interrupt the program or disconnect the Raspberry Pi’s network.

3. In the MQTT X client, check the messages received on the raspberry/status topic.

   

We have completed the testing client written using the Python MQTT client library paho-mqtt on the Raspberry Pi, and implemented functions such as connecting to the MQTT server, subscribing, unsubscribing, and sending/receiving messages.

By now, you have learned how to simply use the MQTT service. Although this is just a small part of the MQTT service, it is enough to accomplish many interesting things, such as:

1. Sending MQTT messages from a mobile phone to remotely control the Raspberry Pi.

2. Regularly sending device information from the Raspberry Pi to the MQTT server, receiving messages on your phone for round-the-clock monitoring.

3. Connecting the Raspberry Pi to the MQTT server and creating many interesting IoT applications with various sensors and ESP modules.

Next, we will continue to publish more articles related to IoT development and Raspberry Pi, stay tuned.