What are Topics and how to use them correctly in MQTT

We have been seeing the messaging services in IoT for a few entries. In this post we will delve into the Topics in MQTT, seeing what they are and how to use them correctly in our projects.

In the first entry we saw different communication protocols for IoT. In the previous one we introduced MQTT, the popular M2M protocol especially suitable for IoT applications due to its simplicity and lightness.

We remember that MQTT is a message service with a publisher/subscriber pattern (pub-sub) that works over TCP/IP. That is, a central server, which in MQTT is called Broker, receives the messages, filters them and distributes them to the clients.

We also remember that in MQTT the transmitted messages are formed by a header that contains, among others, the type of command sent. The other important part of the message is the content or Payload.

We had to see the Topic, a fundamental component of the MQTT protocol. In this post we will see what they are, how to use them, and how to correctly organize their structure in an IoT system.

What are Topics in MQTT?

As we said, MQTT Brokers apply filtering to the messages that are received from the publishers, to discriminate which subscribed clients they are delivered to.

In MQTT this filter is called a Topic, and it simply consists of a UTF-8 text string, and a maximum length of 65536 characters (although it is usually much smaller). It is case-sensitive.

Topics are formed by one or more “levels” separated by a forward slash ’/‘. Each level must be formed by one or more characters.

For example, valid examples of Topics could be,

Casa/Cocina/Temperatura

Casa/Salon/Temperatura

Casa/Salon/Persiana

How Topics work in MQTT

The operation of Topics in MQTT is simple and transparent. On the one hand the Broker accepts all Topics. It is not necessary to create it explicitly before publishing or subscribing to the Broker.

For its part, clients can subscribe to one or more Topics. To do this, the client can establish several subscriptions and/or use Wildcards, as we will see in the next section.

Finally, clients publish messages indicating a single Topic. The Broker receives the message and, if it finds a subscription that matches the Topic filter, it transmits the message to the subscribed clients.

Wildcards

When a client establishes a subscription, it can subscribe to a specific Topic, or use Wildcards to subscribe to multiple Topics. There are two Wildcards that we can use,

Single-level Wildcard

The + character can be used to replace a single level anywhere in the Topic.

For example:

# pattern
Casa/+/Temperatura

# YES matches
Casa/Salon/Temperatura
Casa/Cocina/Temperatura

# NO matches
Casa/Salon/Nevera/Temperatura

While:

# pattern
Casa/Salon/+

# YES matches
Casa/Salon/Temperatura
Casa/Salon/Persiana

# NO matches
Casa/Salon/Nevera/Temperatura
Casa/Salon/Persiana/Motor

Multi-level Wildcard

The # character can be used to replace any number of levels and can only be used at the end of the Topic.

For example:

Casa/Salon/#

# YES matches
Casa/Salon/Temperatura
Casa/Salon/Persiana

# NO matches
Casa/Dormitorio/Temperatura
Casa/Comedor

Recommendations for organizing Topics

The success of an IoT system depends greatly on the architecture we design for messaging. In the case of MQTT it is essential to plan and organize the Topics that we are going to use in the project. There are several tips we can follow.

The main one is to design the Topic system to be expandable and maintainable. We want to be able to add more devices to our network or new functionalities, and avoid realizing in the future that the system we chose is insufficient.

Otherwise, we may face the nightmare of having to reprogram all the devices (something we probably won’t be able to do), or have to fix it with “patches”.

Another tip is to keep the Topics as small and clear as possible. Similarly, it is advisable to use Topics as specific as possible, avoiding sending messages to multiple devices and discriminating by the content of the message.

Thus, for example, if you have several sensors, use /Salon/Humedad/1/, /Salon/Humedad/2/, /Salon/Temperatura/1/ instead of using /Salon/ for all devices

Finally, another small tip is to use only standard ASCII characters, avoiding special characters and even spaces. This will make it easier to interpret Topics, and interoperability between programming languages and devices.

Thus, for example, it is preferable to use /Salon/ instead of /Salón/ and /Humedad/ instead of /Sensor humedad/.

How to organize an API with Topics in MQTT

Now that we have seen what Topics are, how they work and some recommendations and tips, we can consider an example of how to correctly organize a Topics system in MQTT so that it is expandable, versatile, and maintainable.

Of course, there is not a single way and each person has their own way. One tendency, in my opinion appropriate, is to approach it similarly to a REST API. Thus, we will have levels in the Topic to identify each Endpoint, and the last level will correspond to the actions offered by the Endpoint.

For example, in the common case of wanting to control the home automation of a series of buildings, a possible design of Topics for MQTT would be as follows.

You will see that we have left specific roots for Building (center) and Room. Each of them follows an identifier, in this case numerical, although for simplicity you can replace it with a text (HouseA, HouseB, Living Room, Kitchen).

By putting a root we are free to add new “families”, such as a common infrastructure like lighting, which is not associated with any building.

Later, we define the different “subfamilies” of devices (temperature, light, etc). Finally, we end with the possible actions on each device. For example, a hypothetical temperature device could allow reading the temperature, or setting it.

It is one of many possible structures, and you are free to modify it according to your needs. For example, it might be interesting to add a new level of “Floor”. But the concept of dedicating some time to planning the Topics system before distributing devices “crazily” is understood.

So far this post dedicated to Topics in MQTT and its use. In the next entry of this IoT section we will see some of the main Brokers for MQTT. See you soon!