MQTT messages aren’t sent directly from one thing to another. Rather, they are assigned to “MQTT topics.” The MQTT broker then distributes the messages to any clients who have subscribed to them. The term topic in protocol refers to a UTF-8 string used by the broker to filter messages for each subscribed client. When someone subscribes to a topic and then publishes a message to that topic with the retained message set to True, the topics are established. When the last subscriber to that broker disconnects, a clean session is established. Clean session is set to True when a MQTT client connects. 

An MQTT topic’s structure

sensors/water_level/water_status – sensors, water_level & water_status are topic levels.

Forward slash ( / ) –   a topic level separator.

Topic level Separator

The topic is made up of one or more topic levels. A forward slash separates each topic level (topic level separator). The broker does not require that topic be pre-registered.

MQTT topics are very lightweight in compared to a message queue. Before publishing or subscribing to a topic, the client does not need to create topics. Without any prior initialization, the broker accepts any valid topic.

Here are a few examples to look at: 

A look at MQTT Topics used in Bevywise Broker.

Topic Semantic and Usage

Except for the length of a UTF-8 encoded string, there is no restriction to the number of levels in a Topic Name or Topic Filter. Topic Names and Topic Filters are subject to the following guidelines:

  • It is important to note that each topic must contain at least one character and that the topic string allows for empty spaces.

  • The null character cannot be used in topic names or topic filters.

  • The MQTT topics are case sensitive.

  • For example, sensor/temperature and Sensor/Temperature, are two distinct topics.

Topic WildCards

The Topic Filter of a subscription can contain special wildcard characters that allow you to subscribe to multiple topics at once. The wildcard characters can be used in Topic Filters but not in Topic Names. Wildcards are classified into two types:

  • Single-level wildcard and

  • Multi-level wildcard.

When one of the two wildcard characters is encountered in Topic Filters given by subscribing Clients, the use of the topic level separator is significant. Separators for topic levels can exist anywhere in a Topic Filter or a Topic Name. A zero length topic level is indicated by adjacent topic level separators.

Single-level wildcard

A single-level wildcard character in a topic is represented by the plus symbol “+.” The Topic Filter’s single-level wildcard can be used at any level, including the first and last. It must fill the entire level of the filter wherever it is utilized. It can be used in the Topic Filter at multiple levels and in conjunction with the multilevel wildcard.

For example,

  • “+”

  • “tank/+/water_level” – These are valid topics with single level wildcard.

Any topic like “tank/water_level/+” matches “tank/water_level/flow_rate1” and “tank/water_level/flow_rate2,” but not “tank/water_level/flow_rate1/increase.” Also, because the single-level wildcard matches only one level, “tank/+” does not match “tank,” but “tank/” does.

Multi-level wildcard

The wildcard character “#” is a multilevel wildcard that can be used to match any number of levels within a topic. The parent and any number of child levels are represented by the multi-level wildcard. The multi-level wildcard character must either be given alone or after a topic level separator. It must be the last character supplied in the Topic Filter in either scenario.

For example,

  • “tank/water_level/#” is a valid topic with multilevel wildcard.

If a Client subscribes to “tank/water_level/flow_rate1/#,” for example, it will get messages published under the following topic names:

  • “tank/water_level/flow_rate1”

  • “tank/water_level/flow_rate1/increasing”

  • “tank/water_level/flow_rate1/increasing/decreasing”

Reserved Topics 

Topics beginning with a dollar sign ($) are reserved topics. The $-symbol topics are for the broker’s internal statistics. Topic Filters that begin with a wildcard character (# or +) must not be matched with Topic Names that begin with a $ character. Clients should not be able to send messages to other Clients with such Topic Names, according to the Server. Topic Names that begin with a leading $ character may be used for additional purposes by server implementations. $SYS/ has become a prominent prefix for topics containing Server-specific data or control APIs. A topic containing a leading $ character cannot be used by applications for their own reasons. 

All of the following information is usually stored in $SYS/, however broker implementations differ. A few instances are shown below.

  • Any messages published on a topic beginning with a $ will not be received if you subscribe to “#.”

  • Any messages sent to “$SYS/broker/Clients” will not be received by a subscription to “+/broker/Clients.”

  • Messages published to subjects beginning with “$SYS/” will be received if you subscribe to “$SYS/#.”

  • Messages sent to “$SYS/monitor/Clients” will be received if you subscribe to “$SYS/broker/+.”

  • A Client must subscribe to both “#” and “$SYS/#” in order to receive messages from topics that begin with $SYS/ and subjects that do not begin with a $.

The above are the basics of message topics. MQTT topics, as you can see, are dynamic and offer a lot of flexibility. Keep using its extensibility without changing the whole topic hierarchy for the subsequent inclusion of new sensors by adding these to your topic tree.