---
tags: iot
---
# An hands-on introduction to MQTT
This lab aims to offer you an hands-on experience with MQTT. You will perform experiments that will allow you to learn how to "publish" and "subscribe" to data. To this end you will use:
1. your own broker
1. a "sandbox" external broker
You will learn how to:
* install and configure an MQTT broker
* interchange data using MQTT clients based
* use MQTT to feed data to your own mobile
## Hardware
Each student will use your own computer and mobile.
# Block 0: Installing the MQTT broker on your computer
For our experiments we will use [**Mosquitto**](https://mosquitto.org/), which is part of the [Eclipse Foundation](http://www.eclipse.org/) and is an [iot.eclipse.org](https://projects.eclipse.org/projects/technology.mosquitto) project. The manual page can be found here [`man page`](https://mosquitto.org/man/mosquitto-8.html).
Detailed installation indications can be found here: https://mosquitto.org/download/
As a quick guide:
* Linux distros like Debian/UBUNTU/Raspian already have Mosquitto in their repositories... so it's enough with:
```shell=bash
sudo apt-get update
sudo apt-get install mosquitto mosquitto-clients
```
* with *Ubuntu MATE* maybe you'll need to add this before:
`sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa`
* with Macs, Mosquitto can be installed from the homebrew project. See http://brew.sh/ and then use “brew install mosquitto”
### Managing the broker
#### ... with Debian/UBUNTU/Raspian
To start and stop its execution use:
```shell=bash
sudo /etc/init.d/mosquitto start/stop
```
At thist moment, to run the broker execute:
```shell=bash
sudo mosquitto –v
```
> note: "-v" stands for "verbose mode" and can be useful at the beginning to see what is going on in the broker. Can be convenient to use a dedicated terminal for the broker to execute in, if the "-v" option is used.
To check if the broker is running you can use the command:
```shell=bash
sudo netstat -tanlp | grep 1883
```
> note: "-tanlp" stands for: tcp, all, numeric, listening, program
alternatively use:
```shell=bash
ps -ef | grep mosquitto
```
#### ... with Mac OS
To start and stop its execution use:
```shell=bash
/usr/local/sbin/mosquitto -v
```
> note: "-v" stands for "verbose mode" and can be useful at the beginning to see what is going on in the broker. Can be convenient to use a dedicated terminal for the broker to execute in, if the "-v" option is used.
or:
```shell=bash
/usr/local/sbin/mosquitto -c /usr/local/etc/mosquitto/mosquitto.conf
```
or:
```shell=bash
brew services start/stop mosquitto
```
To check if the broker is running you can use the command:
```shell=bash
sudo lsof -i -n -P | grep 1883
```
or:
```shell=bash
ps -ef | grep mosquitto
```
## Clients for testing
The broker comes with a couple of useful commands to quickly publish and subscribe to some topic. Their basic syntax is the following.
```shell
mosquitto_sub -h HOSTNAME -t TOPIC
mosquitto_pub -h HOSTNAME -t TOPIC -m MSG
```
More information can be found:
* https://mosquitto.org/man/mosquitto_sub-1.html
* https://mosquitto.org/man/mosquitto_pub-1.html
---
---
# Block 1: some basic example.
## Set-up
Open three terminals (e.g., `xterm`) in your computer, more or less like this:
The biggest terminal on the right will be used to see the execution of the broker, the two smaller terminals will be used to execute the publisher and the subscriber, respectively.
Now, run the broker with the `-v` flag in the biggest terminal.
## Exercises
Let's start with a easy one. In one of the small terminals write:
```shell
mosquitto_sub -t i/LOVE/Python
```
the broker terminal should show something like:
the broker registered the subscription request of the new client. Now in the other small terminal, execute:
```shell
mosquitto_pub -t i/LOVE/Python -m "Very well."
```
in the broker terminal, after the new registration messages, you'll also see something like:
meaning that the broker received the published message and that it forwarded it to the subscribed client. In the terminal where `mosquitto_sub` is executing you'll see the actual message appear.
Try now:
```shell
mosquitto_pub -t i/love/python -m "Not so well"
```
**What happened? Are topics case-sensitive?**
Another useful option of `mosquitto_pub` is `-l`. Execute the following command:
```shell
mosquitto_pub -t i/LOVE/Python -l
```
and start typing some line of text. It sends messages read from stdin, splitting separate lines into separate messages. Note that blank lines won't be sent. You basically obtained a MQTT based **"unidirectional chat"** channel...
### ... about Keepalive
By the way, if you kept the broker running with the `-v` option until now in a separate window, you can see various lines like:
```
1524673958: Sending PINGRESP to mosqpub|3592-iMac-de-Pi
1524673985: Received PINGREQ from mosqsub|3587-iMac-de-Pi
```
this simply shows that the broker and the client are interchanging these special messages to know whether they are still alive.
### QoS (Quality of Service):
Adding the `-q` option, for example to the `mosquitto_pub` you'll see the extra message that are now interchanged with the broker. For example, doing:
```shell
mosquitto_pub -t i/LOVE/Python -q 2 -m testing
```
you'll get:
compare this sequence of messages with the one obtained with `-q 0` or with `-q 1`.
### Retained messages:
Normally if a publisher publishes a message to a topic, and *no one is subscribed* to that topic the message is simply discarded by the broker. If you want your broker to remember the last published message, you'll have to use the ```retain``` option. Only one message is retained per topic. The next message published on that topic replaces the retained message for that topic.
> To set the retain message flag you have to add `-r` using the Mosquitto clients.
So try the following cases, but **remember now to always execute, for each test, the subscriber after** the publisher:
1. Publish a message with the retain message flag not set, like we did before. What happens?
1. Publish a message with the retain message flag set (`-r`). What happens?
1. Publish several (different) messages with the retain message flag set before starting the subscriber. What happens?
2. Publish a message with the retain message flag **not** set again. What happens?
Finally, how do I remove or delete a retained message? You have to publish a blank message(`-m ""`) with the retain flag set to true which clears the retained message. Try it.
### Public brokers
There are also various public brokers in Internet, also called `sandboxes`. For example:
* `test.mosquitto.org`
* more infos at: http://test.mosquitto.org/
* `iot.eclipse.org`
* more infos at: https://iot.eclipse.org/getting-started#sandboxes
* `broker.hivemq.com`
* more infos at: http://www.hivemq.com/try-out/
* http://www.mqtt-dashboard.com/
we will always access them through port `1883`.
**Repeat some of the exercise above with one of these sandboxes (remember to use the `-h` option). Any difference?**
# Block 2: A testbed on my mobile
> For this demo you have to use your own mobile and get installed two apps: A MQTT broker (any) and MQTT Dash.
## Enabling the MQTT (Broker) Server
You have to enable the MQTT Broker you have installed in your mobile
## Connecting MQTT Dash
Now you have to connect the MQTT Dash to the Broker that is running in your own mobile. You can either run the MQTT Dash in the same mobile or run it in another one. After getting the MQTT connected to the Broker you have to add some elements to the MQTT Dash environment and try to interact with the element you have created either via a terminal in your computer or via another mobile.
Material adapted from: https://hackmd.io/@pmanzoni/BJ9hwSfhG#
Sign in with Wallet
Connect another wallet