MQTT Topics

As a publish/subscribe messaging protocol, MQTT relies on a hierarchical topics. Clients can publish messages on specific topics, and clients can receive published messages that match their current topic subscriptions.

Note:  MQTT is supported from SolOS version 7.1.1 on.

MQTT topics are UTF-8 strings, which consist of one or more topic levels that are separated by forward slash “/” characters. Separating topic levels withslashes creates a hierarchy of information for organizing topics.

Note:  A Solace router supports topics with a maximum of 128 levels and a maximum length of 250 bytes. An MQTT client’s connection to the router will be closed if its topic filters exceed these limits.

The Solace Messaging Platform allows messages to be exchanged between MQTT clients and non-MQTT clients (for example, SMF and REST clients) if those clients use intersecting topic hierarchy. However, to deploy client applications that use different Solace-supported messaging protocols, architects and programmers should avoid conflicting special characters and use a common topic syntax subset to ensure that topic subscriptions are fulfilled in a consistent manner. For more information, refer to Publishing Recommendations When Using Consumers With Different Protocols.

Wildcard Characters in MQTT Topic Subscriptions

When the “+” or “#” characters are used in a topic subscription, they function as wildcards, which affects the topic matches that can occur from the subscription.

The “+” character, when used by itself as a topic level, matches any string for a single topic level at that position in the topic structure. For example, “home/+” matches the topics “home/kitchen” and “home/bedroom”, but it does not match the topic “home/kitchen/temperature”. Similarly, “home/+/humidity” matches “home/kitchen/humidity” and “home/bedroom/humidity”, but it does not match “home/kitchen”.

Note:  The Solace Messaging Platform allows the “+” character to be used as a wildcard to do prefix matching within a level in an MQTT topic subscription. For example, “sport/bas+” matches both “sport/basketball” and “sport/baseball”, but not “sport/badminton”. If any string follows the single-level wildcard it is treated as a literal “+” character.

The “#” character can be used as a multi-level wildcard when it is the last character in a topic subscription following a topic separator (“/”). When used in this way, the “#” character matches any string for one or more topic levels at the end of the topic structure. For example, “home/#” matches the topics “home/kitchen” and “home/bedroom/temperature”, but it does not match the topics “home” or “business/lobby”.

Note:  A Solace router automatically creates a topic subscription beginning with the prefix #P2P/ for each client, which enables messages to be sent directly to that client (for example, in request/reply scenarios). However, the leading “#” in “#P2P" is not valid MQTT syntax. Therefore, to make use of these special Solace subscriptions, MQTT clients may use the string “_P2P” instead of “#p2p” . The Solace Messaging Platform considers the two strings to be equivalents and handles a subscription with “_P2P” as “#P2P”.

Wildcard Usage Examples

The table below provides some examples of MQTT wildcard topic subscription matching.

MQTT “+” and “#” Wildcard Subscriptions

Topic with Wildcards Matches Does not Match
home/kitchen/+ home/kitchen/temperature
home/kitchen/humidity
home/bedroom/temperature
business/kitchen/humidity
home/+/temperature home/kitchen/temperature
home/bedroom/temperature
home/kitchen/humidity
business/lobby
+ home
business
home/kitchen
home/kitchen/temperature
business/lobby
home/# home/
home/kitchen/temperature
home/bedroom/humidity
home
business/lobby

Clients’ MQTT topic subscriptions should not begin with the “$” characters because they are commonly used for server-specific information. For the Solace Messaging Platform, the following well-known topics are exceptions to this general rule:

  • $SYS/client/client-name
  • $SYS/client/reply-to

Connecting SMF clients commonly use these two topics to determine their assigned client name and the reply-to topic that is reserved for them. MQTT clients connecting to a Solace router can also use these two well-known topics to determine the same information. For more information, refer to Requesting Session Information with Special Topics.

MQTT Topic Name Syntax

The “+” and “#” characters cannot be used as wildcards in the topic names used by MQTT publish messages. If a Solace router receives an MQTT publish message with the “+” and “#” characters in its topic name, the router will treat them as literal characters with no special meaning.

Publishing Recommendations When Using Consumers With Different Protocols

MQTT clients can receive messages published by non-MQTT clients (for example, SMF or REST clients), and non-MQTT clients can receive messages published by MQTT clients, when an intersecting topic hierarchy is used by the MQTT and non-MQTT clients. Applications which expect to communicate between protocols should avoid conflicting special characters and use a common topic syntax subset. Specifically this means applications must:

  1. Avoid using the “+” character. It is illegal in an MQTT topic name. Although SMF treats the “+” character in an MQTT topic name as a literal, an MQTT API may block it.
  2. Avoid using the “#” character. It is illegal in an MQTT topic name. Although SMF treats the “#” character in an MQTT topic name as a literal, an MQTT API may block it.
  3. The #P2P reply-to topic generated by a Solace API is not compatible with an MQTT client.
  4. Avoid using the “*” character. SMF treats “*” character as a wildcard, but MQTT treats it as a a literal. SMF clients will not necessarily be able to subscribe to topics which include this character.
  5. Avoid using the “>” character as a standalone final topic level. SMF treats the “>” character as a wildcard, but MQTT treats it is a literal. As a result, SMF clients that subscribe to such topics may attract additional traffic.
  6. Avoid using the “$” character at the start of a topic. In MQTT, topic names starting with “$” are reserved for use by server implementations and should not be used by clients. This makes such topics inappropriate for client-to-client messaging.
  7. Avoid empty topic levels. MQTT supports empty topic levels, but SMF only permits applications to publish to a topic with an empty level, they cannot not use topic subscriptions with an empty level.