MQTT Topic-Namenskonventionen entscheiden darüber, ob Ihr System leicht abonnierbar, sicher und gut zu debuggen bleibt, während es von fünf auf fünftausend Geräte wächst. Dieser Leitfaden liefert Ihnen 12 konkrete Regeln mit guten und schlechten Beispielen, eine wiederverwendbare Vorlage und eine Checkliste, die Sie anwenden können, bevor das erste Gerät ausgeliefert wird.
Warum Topic-Namen eine Konvention verdienen
MQTT-Topics sind frei formulierbare UTF-8-Zeichenketten, getrennt durch /. Der Broker erzwingt keine Struktur, und Topics entstehen spontan, sobald jemand etwas veröffentlicht. Diese Freiheit ist am ersten Tag bequem und am Tag 300 schmerzhaft: wenn Subscriber sich auf Dutzende leicht unterschiedliche Schreibweisen verlassen, Wildcards die falschen Daten treffen und niemand mehr etwas umzubenennen wagt, weil unbekannte Consumer kaputtgehen könnten.
Topic-Namen sind faktisch die öffentliche API Ihres Systems. Jeder Subscriber, jedes Dashboard, jeder Node-RED-Flow und jede Zugriffsregel hängt von ihnen ab. Sich früh auf eine Konvention zu einigen, ist eine der günstigsten Verbesserungen der Zuverlässigkeit, die es gibt.
Die 12 MQTT Topic-Namenskonventionen
1. Nicht mit einem Schrägstrich beginnen
Ein führendes / erzeugt eine leere erste Ebene. /factory/line1 und factory/line1 sind verschiedene Topics, und die leere Ebene bringt nichts außer Verwirrung.
- Schlecht:
/factory/line1/temp - Gut:
factory/line1/temp
2. Nur Kleinbuchstaben verwenden
Topics unterscheiden Groß- und Kleinschreibung. Line1/Temp und line1/temp sind verschiedene Topics, und gemischte Schreibweise garantiert, dass jemand das falsche abonniert. Entscheiden Sie sich für Kleinschreibung und bleiben Sie dabei.
3. Leerzeichen und Sonderzeichen vermeiden
Leerzeichen, Akzente und Symbole sind zulässig, verursachen aber Escaping-Probleme in Shells, URLs, Logs und Konfigurationsdateien. Verwenden Sie a-z, 0-9, - und _. Verwenden Sie niemals + oder # in Namen; das sind Wildcard-Zeichen in Subscriptions.
- Schlecht:
Plant A/Pump #3/Pressure (bar) - Gut:
plant-a/pump-3/pressure
Für deutschsprachige Standort- und Anlagennamen heißt das: Umlaute und ß umschreiben, also werk-muenchen statt werk-münchen und strasse-2 statt straße-2. So bleiben Topics in SPS-Gateways, Skripten und Zugriffsregeln ohne Kodierungsprobleme nutzbar.
4. Vom Allgemeinen zum Speziellen
Ordnen Sie die Ebenen vom breitesten zum engsten Geltungsbereich, damit Wildcards ganze Zweige auswählen können. Eine gängige Form ist:
<namespace>/<site>/<area>/<line-or-group>/<device>/<category>/<measurement>
Mit dieser Reihenfolge wählt acme/berlin/# einen Standort aus und acme/+/+/+/+/telemetry/temperature jeden Temperaturwert. Die umgekehrte Reihenfolge macht solche Subscriptions unmöglich. Wie + und # matchen, erfahren Sie unter MQTT-Wildcards.
5. Mit einem Namespace beginnen
Eine erste Ebene wie Ihr Firmen-, Produkt- oder Anwendungsname trennt Ihren Verkehr von anderen Systemen auf demselben Broker und erleichtert spätere Bridges oder Migrationen. Auf dem öffentlichen MQTT-Broker, der für Tests und Prototypen gedacht ist, hält ein eindeutiges Präfix wie connectmq/demo/<random-id>/ Ihre Experimente von denen anderer fern.
6. Geräte-IDs nach dem Standort platzieren, nicht davor
Kennungen gehören auf die Ebene, die das Gerät repräsentiert, nach den Gruppierungsebenen, die beschreiben, wo es sich befindet. So können Sie einen Standort abonnieren, ohne jede Geräte-ID zu kennen, und ein einzelnes Gerät mit einem exakten Topic.
- Schlecht:
esp32-a4cf12/berlin/hall2/temperature - Gut:
acme/berlin/hall2/esp32-a4cf12/telemetry/temperature
7. Nachrichtenkategorien trennen
Halten Sie Telemetrie, Zustand, Befehle und Ereignisse in getrennten Zweigen. Subscriber und Zugriffsregeln können dann genau das ansprechen, was sie brauchen.
| Kategorie | Beispiel-Topic | Typischer QoS / Retain |
|---|---|---|
| Telemetrie | acme/berlin/hall2/pump-3/telemetry/pressure |
QoS 0, nicht retained |
| Zustand | acme/berlin/hall2/pump-3/state/running |
QoS 1, retained |
| Status | acme/berlin/hall2/pump-3/status |
QoS 1, retained, per Last Will gesetzt |
| Befehle | acme/berlin/hall2/pump-3/cmd/set-speed |
QoS 1, nicht retained |
| Ereignisse / Alarme | acme/berlin/hall2/pump-3/event/overpressure |
QoS 1, nicht retained |
8. Den Payload-Vertrag versionieren
Ändern sich Payload-Formate, gehen Consumer kaputt. Platzieren Sie eine Version dort, wo sich leicht danach routen lässt, entweder als Topic-Ebene (acme/v2/...) oder als Feld in jeder Payload. Eine Version im Topic erlaubt es, alte und neue Consumer während der Migration parallel zu betreiben.
9. Ausreichend flach bleiben
Jede Ebene sollte eine Bedeutung tragen. Sieben oder acht Ebenen reichen für die meisten Systeme, und manche Broker setzen ein Limit; der öffentliche MQTT-Broker von ConnectMQ erlaubt bis zu 8 Ebenen. Tiefe Bäume kosten außerdem Bandbreite, weil der vollständige Topic-String mit jeder Nachricht gesendet wird (Topic Aliases in MQTT 5 helfen, beheben aber kein schlechtes Design).
10. Keine Daten oder Geheimnisse ins Topic
Werte, Zeitstempel, Tokens und personenbezogene Daten gehören in die Payload. Ein Topic wie acme/pump-3/pressure/4.2 erzeugt für jeden Messwert ein neues Topic und macht Retained Messages und Subscriptions unbrauchbar. Topic-Namen erscheinen zudem in Logs und Monitoring-Tools, nehmen Sie also niemals Zugangsdaten oder persönliche Informationen auf.
11. Stabile Substantive im Singular verwenden
Wählen Sie ein Wort pro Konzept und dokumentieren Sie es: temperature, nicht an einer Stelle temp und an einer anderen Temperature_C. Einheiten gehören in die Payload oder die Dokumentation statt in den Topic-Namen, es sei denn, derselbe Messwert wird tatsächlich in mehreren Einheiten veröffentlicht.
12. $ dem Broker überlassen
Topics, die mit $ beginnen, sind für den internen Gebrauch des Brokers reserviert, etwa für $SYS/...-Statistiken, und werden von einer einfachen #-Subscription nicht erfasst. Legen Sie keine eigenen $-Topics an. Was Ihr Broker dort veröffentlicht, erfahren Sie unter MQTT $SYS Topics.
Gute und schlechte Topic-Bäume im Vergleich
# Schwer zu verwenden
/Factory1/Line 1/CNC#1/Temp
cnc1/factory1/temperature/71.3
Factory1/line1/CNC1/TEMP_C
# Leicht zu verwenden
acme/factory1/machining/line1/cnc1/telemetry/spindle-temperature
acme/factory1/machining/line1/cnc1/state/mode
acme/factory1/machining/line1/cnc1/status
acme/factory1/machining/line1/cnc1/cmd/start
Der zweite Baum folgt der ISA-95-Ausrüstungshierarchie aus Unternehmen, Standort, Bereich, Linie und Zelle (Enterprise → Site → Area → Line → Cell) und ist damit bereits die Topic-Struktur eines Unified Namespace (UNS). Im UNS wird diese Hierarchie auf dem MQTT-Broker zur gemeinsamen Adresse für alle Daten eines Unternehmens, etwa acme/werk-stuttgart/montage/linie-1/zelle-3/temperatur, sodass MES, SCADA und ERP dieselben Topics abonnieren. Eine Namenskonvention ist in Industrie-4.0-Projekten deshalb vor allem eine UNS-Konvention. Wenn Sie im industriellen Umfeld arbeiten, erklärt der Leitfaden zu Sparkplug B und Unified Namespace, wie diese Hierarchien standardisiert werden. Weitere fertige Bäume finden Sie in unseren Beispielen für MQTT-Topic-Hierarchien.
Ihre Konvention an einem Live-Broker testen
Veröffentlichen Sie einige Nachrichten mit Ihrer vorgeschlagenen Struktur auf dem kostenlosen öffentlichen MQTT-Broker und prüfen Sie, ob Wildcard-Subscriptions genau das auswählen, was Sie erwarten. Ersetzen Sie n8x4 durch eine eigene Zufallszeichenfolge; der öffentliche MQTT-Broker ist für alle lesbar und nicht für Produktionsdaten gedacht. Die Demo lässt die Bereichsebene weg, damit das vollständige Topic innerhalb des 8-Ebenen-Limits des öffentlichen Brokers bleibt.
P="connectmq/demo/n8x4/factory1/line1"
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-t "$P/cnc1/telemetry/spindle-temperature" -m '{"v":71.3,"unit":"C"}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-t "$P/cnc2/telemetry/spindle-temperature" -m '{"v":68.9,"unit":"C"}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-r -q 1 -t "$P/cnc1/status" -m 'online'
# Alle Telemetriedaten von line1, sonst nichts
mosquitto_sub -h broker.connectmq.com -p 1883 -i naming-sub-n8x4 -v \
-t "connectmq/demo/n8x4/factory1/line1/+/telemetry/#"
Nur die retained status-Nachricht wäre einem neuen Subscriber sofort zugestellt worden; die obigen Telemetriedaten wurden veröffentlicht, bevor sich der Subscriber verbunden hat, und waren nicht retained. Veröffentlichen Sie erneut, während der Subscriber läuft, um sie ankommen zu sehen.
Checkliste für Ihre Topic-Konvention
- Ein schriftliches Dokument listet jede Ebene, ihre Bedeutung und die erlaubten Werte auf.
- Alle Topics sind kleingeschrieben, ohne führenden Schrägstrich, Leerzeichen oder Wildcard-Zeichen.
- Die erste Ebene ist ein Namespace.
- Die Ebenen verlaufen vom Allgemeinen zum Speziellen, mit der Geräte-ID nach ihrem Standort.
- Telemetrie, Zustand, Status, Befehle und Ereignisse haben getrennte Zweige.
- Es gibt eine Versionierungsstrategie.
- In Topics stehen keine Werte, Zeitstempel oder Geheimnisse.
- Die Tiefe bleibt innerhalb der Broker-Limits.
- Wildcard-Subscriptions für jeden bekannten Consumer wurden getestet.
- Der Baum wurde in einem Topic-Browser mit realistischen Daten geprüft.
Wenn Sie ganz am Anfang stehen, behandelt das MQTT-Tutorial Topics, Subscriptions und QoS im Zusammenhang.
Ihren Topic-Baum in ConnectMQ sehen
ConnectMQ bietet für jeden Broker einen Live-Topic-Explorer, sodass Sie Ihre Hierarchie in Echtzeit wachsen sehen und abweichende Schreibweisen sofort erkennen. Er erkennt außerdem Topics im ISA-95- und UNS-Stil und zeigt Geräte nach ISA-95-Ebene an, was eine disziplinierte Konvention belohnt. Als verwalteter MQTT-Broker unterstützt ConnectMQ MQTT 3.1.1 und 5.0 über TCP, TLS und WebSockets. Erstellen Sie einen kostenlosen Serverless-Broker, ohne Kreditkarte, und testen Sie Ihre Topic-Konvention mit echten Geräten.
Häufig gestellte Fragen
Sollten MQTT-Topics mit einem Schrägstrich beginnen?
Nein. Ein führender Schrägstrich erzeugt eine leere erste Topic-Ebene, wodurch Topics schwerer lesbar werden und sich leicht vertippen lassen. Beginnen Sie direkt mit Ihrem Namespace, etwa acme/....
Unterscheiden MQTT-Topics Groß- und Kleinschreibung?
Ja. Sensor/Temp und sensor/temp sind völlig unterschiedliche Topics. Durchgängige Kleinschreibung vermeidet versehentliche Abweichungen.
Wie viele Ebenen sollte ein MQTT-Topic haben?
So viele, wie Bedeutung tragen, und nicht mehr; die meisten Systeme brauchen zwischen vier und acht. Prüfen Sie auch die Broker-Limits: Der öffentliche MQTT-Broker von ConnectMQ erlaubt bis zu 8 Ebenen.
Wo gehört die Geräte-ID in einem MQTT-Topic hin?
Hinter die Ebenen, die Standort oder Gruppierung beschreiben, und vor Nachrichtenkategorie und Messwert. Diese Reihenfolge erlaubt es Wildcards, einen Standort, eine Linie oder ein einzelnes Gerät sauber auszuwählen.
