Paho MQTT C Client Library
Subscription wildcards

Every MQTT message includes a topic that classifies it. MQTT servers use topics to determine which subscribers should receive messages published to the server.

Consider the server receiving messages from several environmental sensors. Each sensor publishes its measurement data as a message with an associated topic. Subscribing applications need to know which sensor originally published each received message. A unique topic is thus used to identify each sensor and measurement type. Topics such as SENSOR1TEMP, SENSOR1HUMIDITY, SENSOR2TEMP and so on achieve this but are not very flexible. If additional sensors are added to the system at a later date, subscribing applications must be modified to receive them.

To provide more flexibility, MQTT supports a hierarchical topic namespace. This allows application designers to organize topics to simplify their management. Levels in the hierarchy are delimited by the '/' character, such as SENSOR/1/HUMIDITY. Publishers and subscribers use these hierarchical topics as already described.

For subscriptions, two wildcard characters are supported:

  • A '#' character represents a complete sub-tree of the hierarchy and thus must be the last character in a subscription topic string, such as SENSOR/#. This will match any topic starting with SENSOR/, such as SENSOR/1/TEMP and SENSOR/2/HUMIDITY.
  • A '+' character represents a single level of the hierarchy and is used between delimiters. For example, SENSOR/+/TEMP will match SENSOR/1/TEMP and SENSOR/2/TEMP.

Publishers are not allowed to use the wildcard characters in their topic names.

Deciding on your topic hierarchy is an important step in your system design.