02 MQTT CLI.md

# Publish Subscribe

Up to this point all the activities have 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 new HTML5 **websocket** protocol that allows a full duplex (2 way) communication over a single TCP connection. We will then explore the **MQTT** protocol which can be run over websockets and is used to implement a _push message_ system, technically called _publish-subscribe_.

## 1 Set Up

Start by installing the [Mosquitto Tools](https://mosquitto.org/download).

### 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.

```shell
$ mosquitto_sub -v -h mqtt.coventry.ac.uk -p 8883 --cafile mqtt.crt -u 302CEM -P xxx -t 302CEM/elephant/xxx
```

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 `302CEM/elephant/XXX` (remember to substitute your team nane and 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.

```shell
$ mosquitto_pub -h mqtt.coventry.ac.uk -p 8883 --cafile mqtt.crt -u 302CEM -P xxx -t 302CEM/elephant/xxx  -m "hello world"
```

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.

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_ `302CEM/elephant`, substituting 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).
6. What happens if you subscribe to the `302CEM/` topic?

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