Smart-Home-MQTT-Topic-Struktur: Best Practices

Eine gute Smart-Home-MQTT-Topic-Struktur macht den Unterschied zwischen Automatisierungen, die Sie auf einen Blick verstehen, und einem Wirrwarr aus sensor1/temp2-Topics, an die sich niemand mehr erinnert. In diesem Leitfaden erhalten Sie ein sofort einsetzbares Raum/Gerät/Eigenschaft-Layout, erfahren, warum Befehls- und Zustands-Topics getrennt sein müssen, und sehen, wie Retained Messages, Verfügbarkeit und Wildcards auf einem echten Broker zusammenspielen.

Warum Topic-Design vor dem zehnten Gerät zählt

Bei drei Geräten funktioniert jede Benennung. Sobald Sie dreißig haben, entscheiden die Topic-Namen darüber, wie leicht es ist,

mit einer einzigen Wildcard „alles in der Küche“ oder „jede Temperatur im Haus“ zu abonnieren,
ein neues Gerät hinzuzufügen, ohne jede Automatisierung anzupassen,
zu erkennen, ob eine Nachricht eine Anfrage oder eine Tatsache ist,
in einem Topic-Explorer zu sehen, was tatsächlich passiert.

MQTT erzwingt keine Struktur. Topics sind einfach UTF-8-Strings, die durch / getrennt sind, und der Broker gleicht Abonnements mit ihnen ab. Genau diese Freiheit ist der Grund, warum Sie eine Konvention brauchen. Falls Ihnen die Grundlagen, wie der Broker diese Nachrichten weiterleitet, neu sind, beginnen Sie mit was ein MQTT-Broker tut.

Das empfohlene Layout: Zuhause, Raum, Gerät, Eigenschaft

Ein Layout, das für die meisten Haushalte gut skaliert, ist:

<home>/<room>/<device>/<property>[/set]

Beispiele:

home1/kitchen/ceiling-light/power            state: "ON" or "OFF" (retained)
home1/kitchen/ceiling-light/power/set        command: "ON", "OFF", "TOGGLE"
home1/kitchen/ceiling-light/brightness       state: 0-100 (retained)
home1/kitchen/ceiling-light/brightness/set   command: 0-100
home1/livingroom/climate/temperature         state: 21.6 (retained)
home1/livingroom/climate/humidity            state: 48 (retained)
home1/garage/door/state                      state: "open", "closed", "opening" (retained)
home1/garage/door/state/set                  command: "OPEN", "CLOSE"
home1/garage/door/availability               "online" or "offline" (retained, last will)

Warum diese Reihenfolge funktioniert:

Ebene	Zweck	Wildcard-Beispiel
`home`	Trennt Standorte (Haus, Ferienwohnung, Elternhaus)	`home1/#`
`room`	Entspricht der Art, wie Menschen denken und sprechen	`home1/kitchen/#`
`device`	Ein physisches oder logisches Gerät	`home1/+/climate/#`
`property`	Ein Wert oder eine Fähigkeit	`home1/+/+/temperature`
Suffix `set`	Kennzeichnet einen Befehl, keine Tatsache	`home1/+/+/+/set`

Halten Sie die Tiefe bei höchstens fünf Ebenen. Tiefe Bäume sind mühsamer zu tippen, und der öffentliche MQTT-Broker begrenzt Topics ohnehin auf acht Ebenen – eine sinnvolle Obergrenze für ein Zuhause.

Dasselbe Prinzip „vom Groben zum Feinen“ nutzt die Industrie in größerem Maßstab: In einem Unified Namespace (UNS) wird die ISA-95-Hierarchie (Enterprise → Site → Area → Line → Cell) zur Topic-Struktur, etwa acme/werk-stuttgart/montage/linie-1/zelle-3/temperatur. Wer zu Hause mit Standort, Raum und Gerät denkt, hat das Grundmuster also bereits verinnerlicht; mehr dazu im Beitrag Sparkplug B und Unified Namespace.

Befehls- vs. Zustands-Topics in einer Smart-Home-MQTT-Topic-Struktur

Die wichtigste Regel überhaupt: Verwenden Sie niemals dasselbe Topic für Befehle und Zustand.

Lauscht und meldet eine Leuchte auf home1/kitchen/ceiling-light/power, sieht ein Dashboard, das ON veröffentlicht, seine eigene Nachricht als Echo zurück, kann nicht erkennen, ob die Leuchte tatsächlich geschaltet hat, und ein retained ON-Befehl schaltet die Leuchte bei jedem erneuten Verbinden des Geräts wieder ein – selbst nachdem jemand sie am Wandschalter ausgeschaltet hat.

Mit getrennten Topics ist der Ablauf eindeutig:

Das Dashboard veröffentlicht ON auf .../power/set (nicht retained).
Das Gerät schaltet das Relais.
Das Gerät veröffentlicht ON mit Retain-Flag auf .../power.
Jeder Subscriber, einschließlich des Dashboards, aktualisiert sich über das Zustands-Topic.

Das Zustands-Topic wird zur einzigen verbindlichen Quelle. Befehle sind Anfragen, die scheitern können; Zustände sind Tatsachen, die das Gerät bestätigt.

Zustände retainen, Befehle niemals

Retained Messages lassen einen neu verbundenen Client den aktuellen Zustand sofort sehen. Das ist genau das, was Sie für Zustände und Verfügbarkeit wollen, und genau das, was Sie für Befehle nicht wollen. Ein retained OPEN auf dem Befehls-Topic eines Garagentors bedeutet ein Tor, das sich nach jedem Stromausfall von selbst öffnet. Unser Tutorial zum MQTT-Garagentoröffner zeigt dieses Muster in einem Projekt, in dem Fehler echte Folgen haben.

QoS pro Topic-Typ wählen

Zustände von Sensoren sind mit QoS 0 oder 1 in Ordnung; eine verpasste Temperatur wird durch die nächste ersetzt. Befehle sollten QoS 1 verwenden, damit sie mindestens einmal zugestellt werden, und Geräte sollten wiederholte Befehle idempotent behandeln (zweimal ON ist immer noch an). Zu den Abwägungen lesen Sie MQTT-QoS-Stufen erklärt.

Verfügbarkeit und Last Will

Jedes Gerät sollte ein availability-Topic veröffentlichen. Setzen Sie es nach dem Verbinden auf online (retained) und konfigurieren Sie auf demselben Topic eine Last-Will-Nachricht offline (retained). Verliert das Gerät Strom oder WLAN, veröffentlicht der Broker den Last Will dafür, und Dashboards können das Gerät ausgrauen, statt einen veralteten Wert als aktuell anzuzeigen.

// ESP32 mit PubSubClient: Last Will beim Verbinden, dann online melden
const char* AVAIL = "home1/garage/door/availability";
if (mqtt.connect(clientId, user, pass, AVAIL, 1, true, "offline")) {
  mqtt.publish(AVAIL, "online", true);
  mqtt.subscribe("home1/garage/door/state/set", 1);
}

Payload-Konventionen

Topic-Struktur und Payload-Format gehören zusammen. Wählen Sie einen Ansatz und verwenden Sie ihn überall:

Ein Wert pro Topic (.../temperature = 21.6) ist einfach, funktioniert mit jedem Tool und macht Wildcards mächtig.
JSON pro Gerät (.../climate = {"temperature":21.6,"humidity":48}) reduziert die Zahl der Nachrichten und hält zusammengehörige Werte konsistent.

Viele Haushalte nutzen beides: JSON für Multisensor-Geräte aus Zigbee2MQTT oder ESPHome, Einzelwerte für selbst gebaute Geräte. Wenn Sie JSON verwenden, dokumentieren Sie die Schlüssel und nennen Sie Einheiten entweder im Schlüsselnamen (temp_c) oder in einer Schema-Notiz. Vermeiden Sie es, 21.6, "21.6" und "21.6 C" über verschiedene Geräte zu mischen.

Benennungsregeln, die Ärger ersparen

Verwenden Sie Kleinbuchstaben und Bindestriche: ceiling-light, nicht Ceiling Light.
Keine Leerzeichen, kein # oder + in Namen, kein führendes / (es erzeugt eine leere erste Ebene).
Benennen Sie Räume so, wie Menschen es tun, aber vermeiden Sie Namen, die sich ändern (toms-room wird unpassend, wenn Tom auszieht; bedroom-2 bleibt).
Benennen Sie Geräte nach Funktion, nicht nach Marke oder Modell, damit Sie Hardware ohne Umbenennung austauschen können.
Reservieren Sie ein Präfix auf oberster Ebene für Systemtopics wie home1/system/backup-status.
Legen Sie niemals Geheimnisse, Türcodes oder personenbezogene Daten in Topic-Namen ab; Topics sind für jeden Subscriber mit passenden Wildcards sichtbar.

Topics von Ökosystemen integrieren

Nicht jeden Topic-Namen haben Sie selbst in der Hand. Zigbee2MQTT veröffentlicht unter zigbee2mqtt/<friendly_name>, Tasmota verwendet die Präfixe stat/, tele/ und cmnd/, und Home Assistant Discovery nutzt homeassistant/<component>/<id>/config. Kämpfen Sie nicht gegen diese Konventionen. Stattdessen:

Geben Sie Geräten Anzeigenamen, die Ihrem Raum/Gerät-Muster folgen, zum Beispiel kitchen/ceiling-light in Zigbee2MQTT, sodass die Topics zu zigbee2mqtt/kitchen/ceiling-light werden.
Halten Sie Ihre eigenen selbst gebauten Geräte unter Ihrem Root home1/.
Lassen Sie Home Assistant alles über MQTT Discovery in Entitäten abbilden.

Unsere Anleitung zur Einrichtung von Zigbee2MQTT zeigt, wie Anzeigenamen in Topics übersetzt werden.

Das Layout auf einem öffentlichen MQTT-Broker ausprobieren

Sie können die Struktur ohne Hardware testen. Verwenden Sie ein zufälliges Präfix, damit Ihre Topics nicht mit denen anderer kollidieren:

# Terminal 1: das ganze Haus beobachten
mosquitto_sub -h broker.connectmq.com -p 1883 -i watch-h7q2 -t "connectmq/demo/h7q2/home1/#" -v

# Terminal 2: eine Leuchte meldet retained Zustand, dann sendet ein Dashboard einen Befehl
mosquitto_pub -h broker.connectmq.com -p 1883 -i light-h7q2 -r -q 1 \
  -t connectmq/demo/h7q2/home1/kitchen/ceiling-light/power -m ON
mosquitto_pub -h broker.connectmq.com -p 1883 -i dash-h7q2 -q 1 \
  -t connectmq/demo/h7q2/home1/kitchen/ceiling-light/power/set -m OFF

# Jede Temperatur im Haus, beliebiger Raum, beliebiges Gerät
mosquitto_sub -h broker.connectmq.com -p 1883 -i temps-h7q2 -t "connectmq/demo/h7q2/home1/+/+/temperature" -v

Das Demo-Präfix fügt drei Ebenen hinzu – ein Grund mehr, Ihren eigenen Baum flach zu halten. Der öffentliche MQTT-Broker ist für jeden lesbar und für Tests und Prototypen gedacht; nutzen Sie ihn also nur für Strukturexperimente, nicht für die echten Daten Ihres Zuhauses. Wenn Sie zu einem privaten Broker wechseln, können Sie das Demo-Präfix weglassen und bei home1/ beginnen.

Checkliste für die Smart-Home-Topic-Struktur

Jedes Gerät folgt <home>/<room>/<device>/<property>.
Befehle verwenden das Suffix /set und werden niemals retained.
Zustände werden retained und vom Gerät veröffentlicht, nachdem es gehandelt hat.
Jedes Gerät hat ein availability-Topic mit Last Will.
Namen sind kleingeschrieben, mit Bindestrichen und funktionsbasiert.
Das Payload-Format ist dokumentiert und einheitlich.
Die Topic-Tiefe bleibt bei höchstens fünf Ebenen.

Ihr Zuhause auf einem privaten Broker betreiben

Eine Topic-Struktur bleibt nur sauber, wenn der Broker, auf dem sie lebt, sicher und zuverlässig ist. ConnectMQ bietet einen verwalteten MQTT-Broker mit TLS auf Port 8883, generierten Zugangsdaten und einem Live-Topic-Explorer, in dem sich Ihr Raum/Gerät-Baum bequem durchsuchen lässt. Wenn Sie zwischen Selbsthosting und einem Cloud-MQTT-Broker abwägen, denken Sie an Fernzugriff, Zertifikate und Updates. Weitere Projekte für Haus und Gebäude finden Sie im Leitfaden zur IoT-Automatisierung.

Starten Sie mit ConnectMQ

Erstellen Sie einen kostenlosen Serverless-Broker unter app.connectmq.com, ohne Kreditkarte, kopieren Sie Ihre generierten Zugangsdaten und veröffentlichen Sie Ihre ersten home1/-Topics. Der Live-Topic-Explorer von ConnectMQ zeigt Ihr ganzes Haus innerhalb von Sekunden als Baum.

Häufig gestellte Fragen

Sollten Topics mit einem Schrägstrich beginnen?

Nein. Ein führender Schrägstrich erzeugt eine leere erste Ebene, was zwar zulässig, aber verwirrend und fehleranfällig beim Tippen ist. Beginnen Sie mit dem Namen Ihres Zuhauses oder Standorts.

Ist ein JSON-Topic pro Gerät oder ein Topic pro Wert besser?

Beides funktioniert. Ein Wert pro Topic ist am einfachsten für Wildcards und selbst gebaute Geräte; JSON pro Gerät passt zu Multisensor-Geräten. Wählen Sie eine Variante pro Gerätetyp und dokumentieren Sie sie.

Warum schaltet sich meine Leuchte nach einem Neustart von selbst ein?

Wahrscheinlich haben Sie eine Befehlsnachricht retained. Löschen Sie sie, indem Sie eine leere retained Message auf das Befehls-Topic veröffentlichen, und retainen Sie ab sofort nur noch Zustands-Topics.

Wie viele Topic-Ebenen sollte ein Smart Home verwenden?

Vier oder fünf reichen völlig: Zuhause, Raum, Gerät, Eigenschaft und ein optionales Suffix set. Tiefere Bäume bedeuten mehr Tipparbeit bei wenig Mehrwert.

Smart-Home-MQTT-Topic-Struktur: Best Practices für Räume, Geräte und Befehle