Skip to content
Permalink
master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

arduino/01 MQTT CLI.md

Go to file
 
 
Cannot retrieve contributors at this time
Publish Subscribe 1 Set Up 1.1 MacOS 1.2 Ubuntu 1.3 Windows 10 2 The MQTT Protocol 2.1 Test Your Understanding
90 lines (56 sloc) 6.98 KB
Raw Blame
Open in GitHub Desktop

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 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. 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 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 and use this to install Ubuntu. There are detailed instructions 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...