MQTT Topics

As a publish/subscribe messaging protocol, MQTT relies on hierarchical topics. Clients can publish messages on specific topics, and clients can receive published messages that match their current topic subscriptions. MQTT topics are UTF-8 strings consisting of one or more topic levels that are separated by forward slash "/" characters, which creates a hierarchy of information for organizing topics. When creating topic strings it's important to note that Solace PubSub+ event brokers support topic strings with a maximum of 128 levels and a maximum length of 250 bytes, so an MQTT client connection that exceeds those limits will be closed.

The Solace PubSub+ allows messages to be exchanged between MQTT clients and non-MQTT clients (for example, SMF and REST clients) if those clients use an intersecting topic hierarchy. However, to deploy client applications that use different Solace-supported messaging protocols, architects and programmers should avoid using 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 topic subscriptions they function as wildcards, which affects the topic matches that can occur from the subscription.

The + Wildcard

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".

The Solace PubSub+ 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.

This capability is a Solace extension to the MQTT specification, and may be incompatible with other MQTT routers or blocked by certain MQTT client libraries.

The # Wildcard

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 zero or more topic levels at the end of the topic structure. For example, "home/#" matches the topics "home", "home/", "home/kitchen" and "home/bedroom/temperature".

The #P2P / Prefix

An event broker 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 PubSub+ considers the two strings to be equivalents and handles a subscription with "_P2P" as "#P2P".

Also, it should be noted that any messages published to #P2P/... will not be matched by wildcards at the first level in the topic.

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/
home/kitchen/temperature
home/bedroom/humidity
business/lobby

MQTT Topic Name Syntax

Consider the following when publishing or subscribing to MQTT topics on a Solace PubSub+ event broker:

  • The "+" and "#" characters cannot be used as wildcards in the topic names used by MQTT publish messages. If an event broker receives an MQTT publish message with the "+" and "#" characters in its topic name, the event broker will treat them as literal characters with no special meaning.
  • A leading "!" (for example "!a/b/c") used in a MQTT QoS 1 topic subscription indicates a subscription exception. For more information, refer to System-Level Subscription Exception Configuration. Leading "!" characters have no function in the topic names used by MQTT publish messages. If an event broker receives an MQTT publish message with a leading "!" character in its topic name, the event broker treats it as a literal character with no special meaning.

  • A MQTT QoS 0 topic subscription with the format $share/{ShareName}/{filter} indicates a shared subscription. For more information, refer to Shared Subscriptions. Each component of the shared subscription is described as follows:

    • $share is a literal string that marks the subscription as being shared.
    • {ShareName} is a character string that does not include any "/", "+" or "#" characters.
    • {filter} is the remainder of the string which has the same syntax and semantics as a non-shared subscription.

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:

  • 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.
  • 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.
  • The #P2P reply-to topic generated by a Solace API is not compatible with an MQTT client.
  • Avoid using the "*" character. SMF treats "*" character as a wildcard, but MQTT treats it as a literal. SMF clients will not necessarily be able to subscribe to topics which include this character.
  • 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.
  • 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.
  • Avoid empty topic levels. MQTT supports empty topic levels, and Solace PubSub+ event brokers Version 7.1.1 or greater allow empty topic levels in SMF topics. However, there are some limitations to using empty topic levels with SMF topics:
    • Client applications using Solace messaging APIs can publish to topics with empty levels, but they cannot use topic subscriptions with empty levels.
    • ACL profiles do not allow SMF publishing or subscribing topic exceptions that have empty topic levels.

Using Subscription Managers with MQTT Clients

Client applications that are configured as Subscription Managers on a Message VPN may add or remove topic subscriptions at QoS 0 on behalf of other clients within the same Message VPN.(For more information, refer to Managing Subscriptions on Behalf of Other Clients.)

Although you can use Subscription Manager clients to add or remove topic subscriptions for MQTT clients, those topic subscriptions may only use SMF syntax. Therefore, to avoid subscription parse errors for the MQTT clients, those topic subscriptions should be written with the following points in mind:

  • The ">" SMF wildcard is not allowed because there is no MQTT equivalent—in SMF ">" must match 1 or more topic levels, whereas in MQTT "#" must match 0 or more topic levels.
  • Instead of the MQTT "#" wildcard, the subscription must use the ASCII character 0x03.
  • Instead of the MQTT "+" wildcard, the subscription must use the SMF "*" wildcard for MQTT clients. The "*" and "+" wildcards are exact equivalents.

Special Solace MQTT Topics

Solace PubSub+ event brokers use a number of special topics to implement specific MQTT messaging features. Each of these topics begin with the $ character, which is then followed by a specific, reserved sequence of characters.

Topic Description

$share/{ShareName}/{filter}

Indicates a shared subscription. You can use shared subscriptions to load balance large volumes of client data across multiple instances of back end data center applications. Each instance of the data center application joins the shared subscription, and the volume of data matching the shared subscription is randomly distributed between the application instances. For more information, see Shared Subscriptions.

$noexport$share/{ShareName}/{filter}

In MNR or DMR deployments with subscription exporting enabled, shared subscriptions are exported by default. In these cases, the event broker treats each exported subscription as a separate entity. In other words, clients connected to different nodes are not load balanced as a single group. To prevent exportation, a shared subscription must start with $noexport.

$SYS/client/client-name

When an MQTT client subscribes to this special topic, the event broker responds with the client name for the MQTT session. For more information, see Requesting Session Info with Special Topics.

$SYS/client/reply-to

When an MQTT client subscribes to this special topic, the event broker responds with the reply-to destination for the MQTT client. In other words, the body of the message published to this topic provides the reply-to topic/destination that is reserved for the client. For more information, see Requesting Session Info with Special Topics.