Setting up MQTT on ESPRESSObin

In this tutorial we will show you how to setup a basic MQTT connection that sends a message from your Linux machine to your ESPRESSObin running Ubuntu 16.04. To follow this tutorial, it is required that you have successfully booted Ubuntu 16.04 distribution on your ESPRESSObin as instructed in Boot from removable storage - Ubuntu tutorial. Additionally, it is required that you have basic routing functioning on your ESPRESSObin as instructed in Ubuntu - initial network configuration page.

MQTT is an ISO standard publish-subscribe based light-weight messaging protocol for use on top of the TCP/IP protocol. It is perfect for exchanging small messages between several devices. A basic exchange can be seen below:

1. A message has a topic and a payload, like the subject and the content of an e-mail.
2. The Publisher sends a message to the network.
3. The Subscriber listens for messages with a particular topic.
4. The Broker is responsible for coordinating the communication between Publishers and Subscribers.

We will break down this tutorial into 4 simple steps.

Create Broker on Linux machine

We will host a Broker on our Linux machine, for which we will install the mosquitto package, an open source MQTT Broker. For more details on the packages used within this tutorial consult your distribution documentation. For Ubuntu, we install mosquitto with:

linux@machine:~$ sudo apt-get install mosquitto

This will install and start mosquitto daemon Broker on your Linux machine. Make sure to check that mosquitto is running with:

linux@machine:~$ systemctl status mosquitto

Create Publisher on Linux machine

We will be using python scripts to create a Publisher, so make sure to install python library paho-mqtt. This module can be installed via pip so install it first:

linux@machine:~$ sudo apt-get install python-pip

Using pip we are now able to install paho-mqtt:

linux@machine:~$ sudo pip install paho-mqtt

Next, we will create a simple Publisher python script which we will name publish.py. This script publishes "Hello, world!" message on "topic/test" to the Broker and then disconnects. So, open a new document:

linux@machine:~$ vi publish.py

and in there copy/paste:

#!/usr/bin/env python3
import paho.mqtt.client as mqtt

# This is the Publisher
client = mqtt.Client()
client.connect("IP ADDRESS OF BROKER (LINUX MACHINE)",1883,60)
client.publish("topic/test", "Hello world!");
client.disconnect();

Note that you must change the first argument of client.connect() to the IP address of your Linux machine since we are hosting the mosquitto daemon Broker on that machine.

Create Subscriber on ESPRESSObin

Now onto creating a Subscriber on our ESPRESSObin. The Subscriber will connect to our broker and subscribe to "topic/test" to listen for MQTT messages.

First we will install paho-mqtt using pip as we did before:

root@localhost:~# sudo apt-get install python-pip
root@localhost:~# sudo pip install paho-mqtt

root@localhost:~# vi /etc/apt/sources.list
# append the universe repository to the first line:
deb http://ports.ubuntu.com/ubuntu-ports/ xenial main universe
# save, exit and update your packages:
root@localhost:~# apt-get update

Next we will create a Subscriber python script which we will name subscriber.py. The script will listen for MQTT messages on "topic/test" and if it receives a "Hello, World!" message from the Publisher, it will print "Success!". To create the script, do:

root@localhost:~# vi subscribe.py

and there paste the following code:

#!/usr/bin/env python3
import paho.mqtt.client as mqtt

# This is the Subscriber
def on_connect(client, userdata, flags, rc):
	print("Connected with result code "+str(rc))
	client.subscribe("topic/test")

def on_message(client, userdata, msg):
  	if msg.payload.decode() == "Hello world!":
    		print("Success!")
    		client.disconnect()
    
client = mqtt.Client()
client.connect("IP ADDRESS OF BROKER (LINUX MACHINE)",1883,60)

client.on_connect = on_connect
client.on_message = on_message

client.loop_forever()

Again, note that you must change the first argument of client.connect() to the IP address of your Linux machine since that machine is hosting the mosquitto daemon Broker.

Testing the connection

To test the connection, first run the Subscriber script on ESPRESSObin:

root@localhost:~# python subscribe.py
Connected with result code 0

and then run the Publisher script on your Linux machine:

linux@machine:~$ python publish.py

If all went well, you should see the following message in your ESPRESSObin console:

root@localhost:~# python subscribe.py 
Connected with result code 0
Success!

This means that the ESPRESSObin Subscriber has received the message from the Linux machine Publisher over MQTT Broker, printed "Success!" and disconnected.

Now that you have learned and put in practice the basics of MQTT, you can create more practical and complex networking applications using MQTT.