Topics in MQTT use a hierarchical structure with / separators. This chapter covers best practices for designing topic hierarchies that scale and support efficient wildcard subscriptions. A well-designed topic structure enables efficient message routing, simplifies access control, and scales gracefully as your IoT deployment grows.
By the end of this chapter, you will be able to:
{domain}/{location}/{device}/{metric} pattern+ or # wildcard for a given subscription scenario and justify the choiceCore Concept: MQTT uses two wildcards for subscriptions: + matches exactly one topic level (single-level), while # matches zero or more levels (multi-level) and must appear at the end. Topic hierarchies use / as separators.
Why It Matters: A poorly designed topic structure forces clients to subscribe individually to hundreds of topics, wasting bandwidth and broker memory. With a hierarchical design like factory/line_a/machine_001/temperature, a dashboard can subscribe to factory/# for everything, maintenance to factory/line_a/# for one line, or safety systems to factory/+/+/pressure for all pressure sensors. One wildcard subscription replaces potentially thousands of individual subscriptions.
Key Takeaway: Design topics with 3-5 levels following {domain}/{location}/{device}/{metric} pattern. Use + for specific level filtering and # for subtree subscriptions. Never start topics with / (wastes bandwidth) or use spaces (breaks parsing). Plan your topic structure before deployment - changing it later requires coordinated migration across all publishers and subscribers.
Before diving into this chapter, you should be familiar with:
Think of MQTT topics like a filing system for messages. Just as you organize files in folders like Documents/Work/Reports/2025, MQTT organizes messages in topics like home/bedroom/temperature.
Why does this matter?
Without topics, every subscriber would receive EVERY message from every device - imagine getting emails meant for everyone in your company! Topics let subscribers filter to receive only the messages they care about.
Topic Structure:
/ to separate levels: home/bedroom/temperaturehome → bedroom → temperatureHome/Bedroom ≠ home/bedroomWildcards - The Power Feature:
Instead of subscribing to each room individually: - home/bedroom/temperature - home/kitchen/temperature - home/bathroom/temperature
You can use a wildcard: - home/+/temperature - matches ALL rooms!
| Term | Simple Explanation |
|---|---|
| Topic | An address for messages, like a radio channel |
| Level | Each part between / separators |
+ Wildcard |
Matches any ONE level (single-level wildcard) |
# Wildcard |
Matches any NUMBER of levels (multi-level wildcard) |
| Subscribe | Tell the broker which topics you want to receive |
| Publish | Send a message to a specific topic |
Topics are like addresses for sensor messages!
Welcome to the MQTT Post Office, where Sammy and friends learn to sort sensor messages!
Postmaster Perry runs the MQTT broker - the smartest post office ever. “Every message needs an address,” Perry explains. “We call these addresses TOPICS. They help me know where to deliver each message.”
Sammy the Sensor sends temperature readings from the bedroom. “My messages go to home/bedroom/temperature. It’s like my mailing address! Home is my neighborhood, bedroom is my street, and temperature is my house number.”
Lila the Light Sensor works in the garden. “I send to home/garden/light. Same neighborhood (home), different street (garden), different house (light)!”
Dashboard Danny wants ALL the sensor data. “I can’t remember everyone’s address,” Danny sighs. “There are too many sensors!”
Postmaster Perry winks. “Use the magic wildcards! Subscribe to home/# and you’ll get messages from EVERY sensor in the home. The # means ‘everything from here onwards’!”
Max the Motion Detector has a challenge: “I only want to know about temperatures in ALL rooms, not lights or motion.”
Perry teaches him: “Use home/+/temperature. The + means ‘any single word here’. So you’ll get home/bedroom/temperature, home/kitchen/temperature, home/garden/temperature - but NOT home/bedroom/light!”
Bella the Battery Monitor learned an important lesson: “I accidentally named my topic home/ bedroom/temperature with a space. Nobody could find my messages! Spaces break the address system.”
| Word | What It Means |
|---|---|
| Topic | The address where sensor messages get delivered |
| Level | Each word in the address, separated by / |
+ Plus Wildcard |
Magic word meaning “any single word goes here” |
# Hash Wildcard |
Magic word meaning “everything from here to the end” |
| Subscribe | Telling the post office which addresses you want mail from |
Be a Topic Designer!
Design topics for a smart home with these devices: 1. Temperature sensor in the living room 2. Motion detector in the hallway 3. Light switch in the kitchen
Example: home/living_room/temperature
Now try to create ONE wildcard subscription that gets ALL motion sensors in the house! Answer: home/+/motion
MQTT topics form a tree-like hierarchy where each level is separated by /. This structure enables powerful wildcard subscriptions and logical organization of your IoT data.
Example Full Topic Paths:
home/living_room/thermostat/temperature - Living room temperature readinghome/bedroom/thermostat/humidity - Bedroom humidity readingfactory/line_a/machine_001/vibration - Machine vibration sensor dataBest Practices:
/MQTT provides two powerful wildcards for flexible subscriptions:
+ (Single-level wildcard): Matches any value at a single topic level
home/+/temperature matches home/bedroom/temperature and home/kitchen/temperaturehome/bedroom/sensor/temperature (too many levels)# (Multi-level wildcard): Matches zero or more levels
home/# matches everything under home/home/bedroom/# matches home/bedroom/temperature and home/bedroom/sensor/dataPerformance Tip: Specific subscriptions are faster than wildcards. Use home/bedroom/temperature instead of home/+/+ when possible.
How much network traffic can wildcard subscriptions save? Let’s quantify the benefits of using + and # versus individual subscriptions.
Scenario: Monitor 50 temperature sensors in 10 buildings.
Individual subscriptions approach (one SUBSCRIBE per sensor): \(\text{Subscriptions} = 50\text{ sensors} = 50\text{ SUBSCRIBE packets}\) \(\text{Packet overhead} \approx 2\text{ bytes (fixed header)} + 2\text{ bytes (packet ID)} + 2\text{ bytes (length field)} + 25\text{ bytes (topic)} + 1\text{ byte (QoS)} = 32\text{ bytes/packet}\) \(\text{Total traffic} = 50 \times 32 = 1{,}600\text{ bytes}\)
Single-level wildcard approach (building/+/temperature — one subscription for all buildings): \(\text{Subscriptions} = 1\text{ SUBSCRIBE packet}\) \(\text{Packet overhead} \approx 32\text{ bytes (same structure, slightly longer topic)}\) \(\text{Bandwidth savings} = \frac{1{,}600 - 32}{1{,}600} \times 100\% = 98\%\)
Multi-level wildcard approach (building/# — one subscription for all data): \(\text{Subscriptions} = 1\text{ SUBSCRIBE packet}\) \(\text{Traffic} \approx 32\text{ bytes (shorter topic string)}\) \(\text{Bandwidth savings} = \frac{1{,}600 - 32}{1{,}600} \times 100\% = 98\%\)
Broker memory impact: Each subscription entry consumes ~200 bytes of RAM (topic string + trie node metadata). Wildcard approach: \(200 \times 1 = 200\text{ bytes}\) vs individual: \(200 \times 50 = 10{,}000\text{ bytes}\) (98% memory reduction).
Key insight: A single wildcard subscription replaces all 50 individual subscriptions, reducing setup traffic by 98% and broker memory by 98%. New sensors are automatically covered without any client update.
Calculate the bandwidth and memory savings from using wildcard subscriptions:
Choosing the right topic structure involves balancing several competing concerns. Use this decision framework:
Designing your MQTT topic hierarchy is like designing a database schema-do it right at the start or suffer later.
Hierarchical Topic Structure:
{domain}/{location}/{device_type}/{device_id}/{metric}Good Examples:
factory/building_a/temperature/sensor_001/celsius
factory/building_a/temperature/sensor_001/humidity
factory/building_a/conveyor/motor_012/rpm
factory/building_a/conveyor/motor_012/current
home/living_room/thermostat/nest_01/temperature
home/living_room/thermostat/nest_01/target_tempWhy This Structure Works:
factory/building_a/#factory/+/temperature/#factory/building_a/temperature/sensor_001/#factory/building_a/temperature/sensor_001/#factory/#factory/building_a/#factory/building_b/... (no code changes)factory/building_a/temperature/sensor_001/battery (subscribers see it)Common Mistakes:
Starting with /:
BAD: /home/bedroom/temp
GOOD: home/bedroom/tempLeading / creates empty root level (wastes bandwidth)
Spaces and Special Characters:
BAD: home/Living Room/temp
BAD: home/bedroom/temp(celsius)
GOOD: home/living_room/temp_celsiusUse underscores, lowercase, avoid parentheses/spaces
Too Flat:
BAD: sensor_001_temp
BAD: sensor_002_temp
GOOD: sensors/001/temp
GOOD: sensors/002/tempCan’t use wildcards efficiently
Too Deep:
BAD: company/headquarters/building/floor/room/zone/device/sensor/metric
GOOD: hq/floor3/room_301/sensor_12/tempMax 5-7 levels recommended (broker performance)
Mixing Commands and State:
BAD: lights/living_room (used for both commands and state)
GOOD: lights/living_room/command (set desired state)
GOOD: lights/living_room/state (actual current state)Separate concerns for clarity
Advanced Patterns:
Command-State Pattern:
devices/{device_id}/command/set_temp -> Controller publishes
devices/{device_id}/state/current_temp -> Device publishes
devices/{device_id}/state/target_temp -> Device confirmsMetadata Topics:
devices/{device_id}/status -> "online"/"offline" (LWT)
devices/{device_id}/config -> Device configuration (retained)
devices/{device_id}/telemetry -> Battery, signal strength, uptimeReserved Topics:
$SYS/broker/clients/connected -> Broker publishes system info
$SYS/broker/messages/received -> Message statisticsTopics starting with $ are reserved for broker internal use.
Performance Considerations:
| Topic Depth | Wildcard Matching Speed | Memory Usage |
|---|---|---|
| 3 levels | Fast (microseconds) | Low |
| 5 levels | Moderate | Moderate |
| 10 levels | Slow (milliseconds) | High |
Real-World Example: AWS IoT Core Topics:
$aws/things/{thing-name}/shadow/update -> Device updates
$aws/things/{thing-name}/shadow/update/accepted -> Cloud confirms
$aws/things/{thing-name}/shadow/get -> Request current stateMigration Strategy:
If you need to change topic structure in production: 1. Publish to both old and new topics (6 months) 2. Update subscribers gradually 3. Monitor old topic usage (zero activity?) 4. Deprecate old topics (send final migration notice) 5. Remove old topic publishing
Topic Naming Conventions Document:
# MQTT Topic Standards v2.1
## Format
{domain}/{location}/{device_type}/{device_id}/{metric}
## Examples
- factory/building_a/temperature/sensor_001/celsius
- home/bedroom/light/bulb_12/state
## Wildcards
- `+` matches one level: `home/+/temperature`
- `#` matches all levels: `home/bedroom/#`
## Reserved Prefixes
- `$SYS/` - Broker system topics (read-only)
- `$aws/` - AWS IoT Core (if using AWS)
## ACL Template
- Devices: write to `{domain}/{location}/{device_type}/{device_id}/#`
- Dashboards: read from `{domain}/#`Invest time in topic design-changing it later is painful!
Understanding when to use each wildcard type is crucial for efficient subscription management:
Wildcard Selection Guide:
| Scenario | Recommended Pattern | Reason |
|---|---|---|
| All temperatures in building | building/+/temperature |
Filter to specific metric |
| All data from one room | home/bedroom/# |
Get entire subtree |
| All sensors, all rooms | home/+/+/data |
Two wildcards for 2 variable levels |
| Everything (debugging) | # |
Receives ALL messages |
Scenario: A manufacturing plant needs to deploy 500 sensors across 4 production lines, each with 25 machines containing 5 sensors (temperature, vibration, current, pressure, and status).
Given:
Steps:
Design hierarchical topic structure:
factory/{line}/{machine}/{sensor_type}Example: factory/line_a/machine_012/temperature
Calculate topic string overhead:
Define wildcard subscription patterns:
factory/# - single subscription, receives 500 msg/secfactory/line_a/# - receives 125 msg/sec (25 machines x 5 sensors)factory/+/+/pressure - receives 100 msg/sec (4 lines x 25 machines)factory/line_a/machine_012/# - receives 5 msg/secCalculate broker subscription table size:
Result: Topic hierarchy enables flexible subscriptions with 17.5 KB/sec topic overhead. Dashboard uses 1 subscription instead of 500 individual subscriptions. Maintenance team subscribes to 1 wildcard pattern instead of 125 topics. Safety system monitors 100 pressure sensors with single +/+/pressure pattern.
Key Insight: Hierarchical topic design with 3-5 levels balances flexibility against broker memory. Each wildcard level adds ~50 microseconds matching time - at 500 msg/sec, the factory’s 4 wildcard subscriptions add 100 microseconds total routing delay (negligible). Flatter hierarchies (line_a_machine_012_temp) prevent wildcard use and force explicit subscription lists.
Calculate the bandwidth consumed by topic names in your MQTT deployment:
Avoid these common mistakes that cause problems in production:
| Pitfall | Impact | Solution |
|---|---|---|
Leading / |
Creates empty root level, wastes 1 byte per message | Remove the leading slash |
| Spaces in topics | Breaks URL encoding, complicates client code | Use underscores: living_room |
| Flat structure | Cannot use wildcards efficiently | Add hierarchy: domain/location/device/metric |
| Too deep (>7 levels) | Broker performance degrades, topics hard to read | Flatten to 4-5 meaningful levels |
| Mixed commands/state | Ambiguous message direction, ACL complexity | Separate: /command and /state topics |
Test your understanding of MQTT topic concepts by matching terms to their definitions, then practice ordering the steps for deploying a topic hierarchy.
Master MQTT concepts through an interactive game where you act as an MQTT broker, routing messages from publishers to the correct subscribers. See the full MQTT Labs chapter for the complete interactive game with three difficulty levels.
In this chapter, you learned about MQTT topic design and wildcard subscriptions:
Topic Hierarchy Design:
/ as level separators: home/bedroom/temperature{domain}/{location}/{device}/{metric}/ (creates empty root level)device/command vs device/stateWildcard Subscriptions:
+ (single-level): Matches exactly one level - home/+/temperature# (multi-level): Matches zero or more levels - home/## must be the last character in a subscriptionPerformance Considerations:
Key Design Principles:
| Chapter | Focus | Why Read It |
|---|---|---|
| MQTT QoS Levels | Quality of Service 0, 1, and 2 | Understand how delivery guarantees interact with your topic design — retained messages and persistent sessions depend on QoS |
| MQTT Architecture | Broker internals and pub-sub pattern | See how the broker routes messages using the topic tree you designed in this chapter |
| MQTT Security | Authentication, TLS, and topic ACLs | Learn how to restrict publish/subscribe permissions to specific topic patterns using access control lists |
| MQTT Retained Messages | Retained message flags | Discover how retained messages combine with topic hierarchies to deliver the last known value to new subscribers |
| MQTT Last Will and Testament | Device offline detection | See how LWT topics are designed using the same hierarchy patterns covered here |
| MQTT Labs | Hands-on practice | Apply wildcard patterns in a live broker environment and play the MQTT broker routing game |