Introduction to Eclipse Mosquitto

This post aims to cover the installation of the Eclipse Mosquitto program. It assumes a GNU/Linux system (specifically Ubuntu 18.10). It will also explore the fundamental concepts of the MQTT protocol used by Mosquitto.

What is MQTT?

MQTT stands for _Message Queuing Telemetry Transport_, a lightweight messaging protocol between M2M devices, devised by IBM and aimed primarily at resource-constrained devices such as Arduino boards with sensors.

MQTT uses the TCP transport protocol and has several reserved ports:

1. 1883: MQTT, unencrypted
2. 8883: MQTT, encrypted
3. 8884: MQTT, encrypted, client certificate required
4. 8080: MQTT over WebSockets, unencrypted
5. 8081: MQTT over WebSockets, encrypted

All information about the reservation of these ports can be found on the website of the _Internet Assigned Numbers Authority_.

It is useful to keep these ports in mind because Mosquitto will start on one of them by default, depending on how it is being run; the first is the most common. You can use another port with the _-p_ option.

There are primarily two types of hosts in this protocol, clients and the broker, each characterized as follows:

• Clients are the devices that collect information and send it to the broker for processing.
• The broker basically acts as a server. It receives and processes the data sent by the different types of clients and distributes those messages to the sensors that have subscribed to a particular _topic_.

As you can see in the image, it is common to have just one broker and several clients (in this case 4). The arrows represent the messages exchanged, where the dashed arrow is a message from the client to the broker (publishing) and the solid arrow is a message from the broker to the client (subscription).

The previous paragraph introduced two terms that probably did not go unnoticed (or should not have). These are publishing and subscription. They are the two types of messages accepted by MQTT. A client can *publish* a message whenever it wants. To do so, it must specify the _topic_, “the subject of conversation” . In addition, each client can *subscribe* to any _topic_ it wants; these _topic_ will be the only ones it receives.

The broker must (or usually does) have a known static IP address (the one in the image is fictitious), since clients must know whom to send messages to and whom to receive them from.

Quality of service (QOS)

Depending on the intended purpose of our messages, we can specify different quality levels based on the performance or reliability we want.
– QOS 0: does not guarantee that the message reaches its destination. The fastest and simplest. *Default*.
– QOS 1: guarantees that the message reaches its destination, but there may be duplicates of the same message.
– QOS 2: the message reaches its destination and there are no duplicates. This is the slowest method.

Installing Mosquitto

Eclipse Mosquitto is available for GNU/Linux as well as Windows and MacOS. Its download page provides the binaries and installation instructions. Only the instructions for Ubuntu will be explained here.

Mosquitto is not available in the official Ubuntu repositories, so you must add its PPA:

# apt-add-repository ppa:mosquitto-dev/mosquitto-ppa

Then we update the system and install:

# apt update && apt upgrade -y && apt install mosquitto -y && apt install mosquitto-clients -y

Messages

As explained in the _What is MQTT?_ section, the MQTT protocol uses messages to communicate between different devices. Now let's look at the commands to run to send messages and subscribe to a specific topic.

Publishing

To publish (send) a message, you must specify several required values:

• _-h_: specifies the broker's address. This can be either an alias name or an IP address. Example: `-h test.mosquitto.org`.
• _-t_: specifies the message's _topic_. It must be enclosed in quotation marks.
• _-m_: the message itself. It must also be enclosed in quotation marks.

There are some other options that may be useful, such as _-p_ to specify the port or _-q_ to choose the quality (QOS). You can see all the options by running `man mosquitto_pub`.

Therefore, an example of a power-on message from each of the living room light bulbs, assuming there are 3 light bulbs located at _/casa/salon/bombilla/i_, where i={1,2,3}, would be: `mosquitto_pub -h test.mosquitto.org -t “/casa/salon/bombilla/i” -m “Bombilla i: ON”`.

In the image, 3 different messages have been sent, the first ones to “turn on” and the last one to “turn off”.

Subscription

Each device receives only the messages it is subscribed to. As with publishing, there are several required values for it to work correctly:

• _-h_: broker from which we expect to receive messages.
• _-t_: _topic_ to which we want to subscribe.

Naturally, as with publishing, there are many more options available through `man mosquitto_sub`.

Following the example of the living room light bulbs, each light bulb will have its identification within the living room. Let's imagine we have 3 light bulbs, so each will subscribe to _/casa/salon/bombilla/i_ where i={1,2,3}.
The code for light bulb 1 will be: `mosquitto_sub -h test.mosquitto.org -t “/casa/salon/bombilla/1″`.

The image shows the messages from all the light bulbs in the living room, given the _topic_ subscribed to.

Ports

To allow traffic from our clients, we must configure the [Clouding.io](https://clouding.io/) Firewall to allow data traffic to certain ports. As explained in the _What is MQTT?_ section, this protocol uses certain ports by default. In this case, since we are not using WebSockets or an encrypted connection, the port we must open is 1883, using the TCP protocol, as shown in the following image:

Documentation

All the official Eclipse Mosquitto documentation can be found on its website. In addition to the `man` commands discussed throughout the article (also available on that website).

There is also documentation on the MQTT protocol at http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html.

CC-BY David Población