MQTT Topics are structured in a hierarchy similar to folders and files in a file system using the forward slash ( / )as a delimiter.
Using this system you can create a user friendly and self descriptive naming structures of you own choosing.
Topic names are:
- Case sensitive
- use UTF-8 strings.
- Must consist of at least one character to be valid.
Except for the $SYS topic there is no default or standard topic structure.
That is there are no topics created on a broker by default, except for the $SYS topic.
All topics are created by a subscribing or publishing client, and they are not permanent.
A topic only exists if a client has subscribed to it, or a broker has a retained or last will messages stored for that topic.
The $SYS topic
This is a reserved topic and is used by most MQTT brokers to publish information about the broker.
They are read-only topics for the MQTT clients. There is no standard for this topic structure but there is a guideline here that most broker implementations seem to follow.
Subscribing to Topics
A client can subscribe to individual or multiple topics.
When subscribing to multiple topics two wildcard characters can be used. The are:
- # (hash character) – multi level wildcard
- + (plus character) -single level wildcard
Wildcards can only be used to denote a level or multi-levels i.e /house/# and not as part of the name to denote multiple characters e.g. hou# is not valid
Topic naming Examples:
Valid Topic subscriptions
Single topic subscriptions
Subscribing to topic house/#
Subscribing to topic house/+/main-light
but doesn’t cover
Invalid Topic Subscriptions
- house+ – Reason- no topic level
- house# – Reason- no topic level
Publishing to Topics
A client can only publish to an individual topic. That is, using wildcards when publishing is not allowed.
E.G- To publish a message to two topics you need to publish the message twice
When are Topics Created
Topics are created dynamically when:
- Someone subscribes to a topic
- Someone publishes a message to a topic with the retained message set to True.
When are Topics Removed from a Broker
- When the last client that is subscribing to that broker disconnects, and clean session is true.
- When a client connects with clean session set to True.
Here is a video that covers the basics of MQTT topics.
Republishing Topic Data
This is likely to be done when changing or combining naming schemes.
The idea is that a client would subscribe to a topic, e.g.
hub1/sensor1 and republish the data using a new topic naming of house1/main-light.
Common Questions and Answers
Q- How do I subscribe to all topics?
A-Subscribe to #
Q- How Do I subscribe to all $SYS topics?
A-Subscribe to $SYS/#
Q- Should I start my Topic hierarchy with a /.
A- It is not necessary and just adds another level to the structure.
Q- Can I get list of all topics on a broker?
A- Not unless you subscribe to all topics and scan them.
Q- Can I tell who is subscribed to a topic?
Q- How do I discover topics?
A- There is currently no mechanism for that except as described in list all topics.
Related Tutorials and Resources:
- MQTT Topic and Payload Design Notes
- MQTT Sensors and Network Traffic Observations
- MQTT topic naming convention
- Gitihub architectural proposal for smart home