MQTT topics are [[byte strings]] with topic levels separated by a `/` and must contain at least 1 character. [[MQTT Topics]] are "light-weight" in the sense that the broker doesn't need to reserve a queue for a topic before a client publishes to that topic. Topics are use by the broker for filtering similar to how [[Sorted String Tables]] can filter [[byte strings |byte string]] keys for byte equality. ## Internal topics Topics that start with a ` are internal to a broker. ` topics can't be published to by clients and won't be subscribed to with a `#` general wildcard subscription. ``` $SYS/broker/clients/connected $SYS/broker/clients/disconnected $SYS/broker/clients/total $SYS/broker/messages/sent $SYS/broker/uptime ``` ## Best practices Topics are really all about who needs to subscribe to what topics. Specifically, if anyone needs to subscribe to multiple similar topics ### Keep consistency between topic layers Single level wildcards mean the number of levels needs to stay consistent across topic sub-trees that need to be observed in a general way. e.g. You can't easily observe all humidity topics ``` home/kitchen/generic/humidity home/livingroom/generic/humidity home/bathroom/shower/generic/humidity ``` ### Never use a leading forward slash It's not illegal but it ends up counting as a redundant topic level the broker must handle and another layer in the topic tree with zero-character name. ### Never use spaces in a topic It's allowed but it can make debugging hard e.g. multiple different types of Unicode white-space. This is a similar recommendation ### Keep topics short Embedded IoT devices have limited memory. While some brokers allow longer topics, others, like [[AWS IoT Core]] have strict topic length and level-depth requirements. ### Stick to lowercase Since topics are compared byte-wise (hence case sensitive), allowing the same topic name with lowercase and uppercase just leads to confusion ### Use only ASCII characters, avoid non-printable characters Different brokers have different levels of support. Some Unicode characters are error prone because they look visually similar and make debugging hard. ### Embed a unique identifier or the client id into the topic ... for topic that refer to specific entities. It can make the system easier to understand. You can also enforce authorization for clients to post only to their topics. ### Don't subscribe to `#` The simplicity of MQTT means you don't have read parallelization. On a high-throughput system, a client that subscribes to `#` would have to deal with that full volume of messages. If you *actually* need to process every message (e.g. persisting every message to a DB) you're better off implementing the behavior as an extension in the broker e.g. using the [HiveMQ plugin system](https://www.hivemq.com/extensions) to add an async routine for each incoming message. ### Don't forget extensibility Since publisher and subscriber both need to agree on the topic, make sure that adding new topics doesn't result in needing to change the whole topic tree. ### Use specific topics, not general ones Don't use topics in the same way you'd use a queue. Differentiate your topics as much as possible e.g. prefer `myhome/livingroom/temperature`, `myhome/livingroom/brightness`, and `myhome/livingroom/humidity` over `myhome/livingroom`. Using a single-topic for all messages is an anti-pattern. ## Example topic structures ``` myhome/groundfloor/livingroom/temperature USA/California/San Francisco/Silicon Valley 5ff4a2ce-e485-40f4-826c-b1a5d81be9b6/status Germany/Bavaria/car/2382340923453/latitude ``` ## Questions - should I put a version identifier in the topic - what to put in payloads ## Resources - [MQTT Topics & Best Practices - MQTT Essentials: Part 5](https://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices/) - [MQTT Design Best Practices - Designing MQTT Topics for AWSIoT Core](https://docs.aws.amazon.com/whitepapers/latest/designing-mqtt-topics-aws-iot-core/designing-mqtt-topics-aws-iot-core.pdf#mqtt-design-best-practices) #to-review - https://pi3g.com/2019/05/29/mqtt-topic-tree-design-best-practices-tips-examples/ - http://www.steves-internet-guide.com/mqtt-topic-payload-design-notes/ - http://www.steves-internet-guide.com/understanding-mqtt-topics/ - [A detailed guide to the world of MQTT | Hacker Noon](https://hackernoon.com/a-detailed-guide-to-the-world-of-mqtt-bo1d63cay) --- - Links: - Created at: [[2021-01-27]]