01 MQTT CLI.md

# Publish Subscribe

If you have been doing web development, up to this point you have probably been using the **HTTP Protocol**, which uses a _request-response_ process (the client requests a resource and the server responds with this resource). If this seems unfamiliar you should work through the HTTP Protocol worksheet.

Whilst this approach works fine for delivering content to a web browser it is not a useful approach for certain applications. Imagine a chat room where you had to refresh the page to view new messages.

In this worksheet you will learn how to use a different protocol called [MQTT](http://mqtt.org) that allows you to imlement a _push message_ system, technically called _publish-subscribe_. In this system, devices _subscribe_ to a _topic_. When a different device _publishes_ to this topic, the message is pushed to the subscribing device.

In this lab you will be using a commandline tool to both subscribe and publish to topics. In the next lab you will be applying this knowledge to allow a cheap WiFi-enabled microcontroller to also publish and subscribe. In this way you can develop a low-cost sensor network that can communicate with the outside world, something called the Internet of Things (IoT).

## 1 Set Up

Start by installing the [Mosquitto Tools](https://mosquitto.org/download). You will be communicating with a secure broker. You will need the following information before you attempt this:

1. The name of the broker, this is `mqtt.coventry.ac.uk`.
2. The port to connect over, since this is a secure broker you use port `8883`.
3. The server's public encryption key, this is called `mqtt.crt` and can be found in the `exercises/01_mqtt_cli/` directory. This file is zip compressed and will need to be unzipped before using.
4. A valid username which will be supplied to you by your lab supervisor (normally on piece of card in the kit box), this will be shared by all the students in your teaching group so don't send confidential information! In the sample code you should replace the `<USERNAME>` with this username.
5. The password for the supplied username, this is a random 10 character alphanumeric string. Replace the `<PASSWORD>` with this string.

You should only proceed once you have all this information.

### 1.1 MacOS

If you are using MacOS you should install the [Brew Package Manager](https://brew.sh) and use this to install Mosquitto using `brew install mosquitto`.

### 1.2 Ubuntu

If you are using Ubuntu you can install using the following commands:

```
sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa
sudo apt update
sudo apt install mosquitto-clients
```

### 1.3 Windows 10

If you are using Windows 10 you can download the 64 bit Binary exe and install. When you try running the commands you may need to include the **full path to the executable**.

If (when) you encounter issues using Windows we recommend you either dual boot your computer or install [Virtual Box](https://www.virtualbox.org/wiki/Downloads) and use this to install [Ubuntu](https://www.ubuntu.com/download/desktop). There are [detailed instructions](https://askubuntu.com/questions/142549/how-to-install-ubuntu-on-virtualbox) online.

## 2 The MQTT Protocol

Now we have the tools installed we can start using the protocol. You have installed 2 tools, `mosquitto_pub` is used to publish messages and `mosquitto_sub` subscribes to a channel. We will use the `test.mosquitto.org` broker.

Before connecting you will need to download the public key certificate that enables encryption between your computer and the broker. You can find this in the `exercises/MQTT` directory. Since the `mqtt.crt` file contains text this will display in the browser when selected rather than being downloaded. To solve this problem you should download the `mqtt.crt.zip` file and then unzip this to extract the key. Place this in a sensible directory on your computer such as documents.

Nowpening _two_ terminal windows and in both of these navigate to the directory you placed the certificate file in:

In the first window we will run the `mosquitto_sub` command  and subscribe to a _topic_ called `302CEM/XXX` where `XXX` is your university username. Make sure you are running the commands in the same directory as the `mqtt.crt`. The correct password will be given out in the lab session. The topic should include your team name and your own username (replace the xxx). Note that on Windows computers you will need to include the full path to the `mosquitto_sub` command.

_The broker is configured to only allow you to publish and subscribe to a topic that starts with your username. If you don't put this in it will fail silently._

```
$ mosquitto_sub -v -h mqtt.coventry.ac.uk --cafile mqtt.crt -p 8883  -u <USERNAME> -P <PASSWORD> -t 302CEM/<TEAMNAME>/#
```

1. The `-v` is the verbose flag and this will force the program to display both the topic and message (if this is omitted it will only print the message).
2. The `-h` flag allows us to specify the _host_, in this case `test.mosquitto.org`.
3. The `-p` flag allows us to set the port (`1883` for non-secure connections and `8883` if the connection is encrypted).
4. The `--cafile` flag is where we tell the tool where the _server's public key_ is located.
5. The `-u` and `-P` flags are used to supply the username and password needed to validate the subscription.
6. The `-t` flag allows us to specify the _topic_, in this case `<USERNAME>/#` (remember to substitute your team nane and username). The `#` is the _wildcard_ character and so we will be subscribing to any message who's topic starts with `<USERNAME>/`.

The terminal will sit there, subscribed to the chosen topic, waiting to be sent some data which we will send using the second terminal window.

In the second terminal we will run the `mosquitto_pub` command to publish messages to our topic. Replace `<NAME>` with your name.

```
$ mosquitto_pub -h mqtt.coventry.ac.uk --cafile mqtt.crt -p 8883 -u <USERNAME> -P xxx -t 302CEM/<TEAMNAME>/<NAME>  -m "hello world, my name is <NAME>"
```

1. The `-m` flag allows us to specify the _message_, in this case `hello world`.

If you look at the first terminal window (running `mosquitto_sub`) you should see your message displayed. Notice that you will also see messages from other people in the group as well! To the left of each message you will see the topic the message was sent to.

The first terminal will continue to wait for messages until the command is exited by pressing ctrl+c.

### 2.1 Test Your Understanding

Working in small groups of between 2 and 4 people:

1. Each member of the team should choose the same _topic name_ using the name of your team, such as `302CEM/<USERNAME>/elephant`, substite your team name.
2. Everyone runs the `mosquitto_sub` tool and subscribes to this same topic.
3. Each person launches a new terminal in a new pane (so you can see both terminal windows).
4. use the `mosquitto_pub` tool to send a message to your chosen _topic name_.
5. Look at the output of your `mosquitto_sub` command (in the first terminal window).

What have you produced? Can you think of any application for this...