MQTT Explorer¶

MQTT Explorer ist die Diagnose- und Analyse-App fuer MQTT im SmartHome. Die App stellt eine grafische Oberflaeche bereit, mit der MQTT-Topics, Payloads und Topic-Strukturen des Brokers uebersichtlich betrachtet werden koennen. Sie ist damit ein wichtiges Werkzeug, wenn MQTT-Geraete, Zigbee2MQTT, Sensoren oder eigene Clients kontrolliert werden muessen.

MQTT Explorer ist kein Broker. Der Broker ist der Mosquitto broker. MQTT Explorer verbindet sich als Client mit dem Broker und zeigt an, welche Nachrichten dort vorhanden sind oder gerade eintreffen.

Stand: 2026-07-04

Stammdaten¶

Feld	Wert
Name	MQTT Explorer
Slug	`9cf1ea8f_mqtt_explorer`
Hostname	`9cf1ea8f-mqtt-explorer`
DNS	`9cf1ea8f-mqtt-explorer.local.hass.io`
Version	`browser-1.0.3`
Neueste Version	`browser-1.0.3`
Status	gestartet
Stage	stable
Repository	`9cf1ea8f`
Startverhalten	automatisch
Startup-Typ	application
Zugriff	Home-Assistant-Ingress und Sidebar-Panel
Interner HTTP-Port	`4000`
Auto-Update	ein
Watchdog	ein
AppArmor	default
Geschuetzt	ja
Eigene Konfigurationsoptionen	keine
Update verfuegbar	nein

Zweck¶

MQTT Explorer macht die MQTT-Kommunikation sichtbar. Ohne ein solches Werkzeug sind MQTT-Nachrichten nur schwer nachzuvollziehen, weil sie in Topics veroeffentlicht und von Clients abonniert werden. Die App hilft dabei, die Struktur des Brokers zu verstehen, Geraetewerte zu pruefen und Fehler in Topic-Namen oder Payloads zu finden.

Typische Einsatzzwecke:

Pruefen, ob ein Geraet ueberhaupt MQTT-Nachrichten sendet.
Kontrollieren, welche Topics Zigbee2MQTT anlegt.
Payloads von Sensoren, Schaltern oder Zaehlern ansehen.
Topic-Strukturen fuer Automationen oder Dienste nachvollziehen.
Unterschied zwischen Status-Topics und Command-Topics erkennen.
Fehlerhafte, veraltete oder doppelte Topics finden.
Retained Messages erkennen, die nach einem Neustart weiter sichtbar bleiben.

Einordnung im MQTT-System¶

MQTT besteht in diesem SmartHome aus mehreren Rollen:

Mosquitto broker: zentrale MQTT-Vermittlungsstelle.
MQTT Explorer: grafischer Client zum Anzeigen und Pruefen der Topics.
Zigbee2MQTT: Bridge zwischen Zigbee-Netz und MQTT.
Home Assistant MQTT-Integration: bindet MQTT-Geraete und -Sensoren in Home Assistant ein.
Weitere MQTT-Clients: zum Beispiel Sensoren, SmartMeterReader, eigene Skripte oder externe Diagnosewerkzeuge.

MQTT Explorer nimmt selbst keine dauerhafte Steuerungsrolle ein. Die App ist vor allem fuer Wartung, Analyse und Fehlersuche gedacht.

Wichtige Begriffe¶

Broker: Server, der MQTT-Nachrichten annimmt und an abonnierte Clients verteilt.
Client: Geraet, App oder Dienst, der sich mit dem Broker verbindet.
Topic: hierarchischer Pfad einer MQTT-Nachricht, zum Beispiel zigbee2mqtt/geraet/state.
Payload: Inhalt der MQTT-Nachricht, haeufig Text oder JSON.
Publish: Veroeffentlichen einer Nachricht auf einem Topic.
Subscribe: Abonnieren eines Topics oder Topic-Bereichs.
Retained Message: Nachricht, die der Broker speichert und neuen Clients beim Verbinden erneut ausliefert.
Last Will: Nachricht, die der Broker sendet, wenn ein Client unerwartet getrennt wird.
QoS: Zustellqualitaet einer MQTT-Nachricht.

Funktionen¶

MQTT Explorer bietet eine strukturierte Sicht auf den Broker. Die wichtigsten Funktionen im Betrieb sind:

Topic-Baum anzeigen.
Aktuelle Payloads je Topic anzeigen.
JSON-Payloads lesbarer darstellen.
Topics filtern und durchsuchen.
Eingehende Nachrichten live beobachten.
Retained Topics sichtbar machen.
Verbindungsdaten eines Brokers speichern.
Einzelne Topics oder Topic-Gruppen fuer die Analyse aufklappen.
Bei Bedarf MQTT-Nachrichten manuell veroeffentlichen.

Der Lesezugriff ist im Alltag der wichtigste Teil. Schreibende Aktionen wie das manuelle Publishen koennen Geraete steuern oder Zustaende veraendern und werden deshalb nur bewusst genutzt.

Zugriff¶

Die App ist in Home Assistant als Sidebar-Panel eingebunden und kann ueber den Home-Assistant-Ingress geoeffnet werden. Der interne HTTP-Port der App ist 4000; fuer normale Nutzung wird dieser Port nicht direkt aufgerufen, sondern die Home-Assistant-Oberflaeche verwendet.

Zugriffswege:

Home Assistant oeffnen.
In der Seitenleiste MQTT Explorer auswaehlen.
Verbindung zum Mosquitto broker pruefen oder oeffnen.

Die App hat keine eigenen Supervisor-Konfigurationsoptionen. Betriebsparameter wie Startverhalten, Auto-Update und Watchdog werden ueber Home Assistant verwaltet.

Zusammenhang mit Mosquitto¶

Mosquitto ist der Broker und damit die zentrale technische Komponente. MQTT Explorer ist der Betrachter fuer diesen Broker. Wenn MQTT Explorer keine Daten zeigt, muss nicht MQTT Explorer die Ursache sein. Haefig liegt das Problem bei einem der folgenden Punkte:

Mosquitto broker laeuft nicht.
MQTT-Zugangsdaten sind falsch.
Ein Client sendet keine Nachrichten.
Das gesuchte Topic existiert nicht.
Eine Bridge wie Zigbee2MQTT ist getrennt.
Retained Messages vermitteln einen alten Zustand.

Fuer die technische Steuerung von MQTT in Home Assistant sind die Dienste unter Geraete und Dienste dokumentiert.

Zusammenhang mit Zigbee2MQTT¶

Zigbee2MQTT nutzt MQTT als Transportweg. Viele Zigbee-Geraete werden deshalb im Broker unter Topics von Zigbee2MQTT sichtbar. MQTT Explorer ist hier besonders hilfreich, um zu pruefen, ob ein Zigbee-Geraet wirklich Daten liefert oder ob ein Befehl im MQTT-System ankommt.

Typische Pruefpunkte:

Wird das Geraet im Zigbee2MQTT-Topic-Baum angezeigt?
Aendert sich die Payload, wenn der Sensor ausloest?
Wird bei Schaltern oder Tastern ein Aktionstopic geschrieben?
Gibt es ein availability-Topic fuer die Erreichbarkeit?
Sind Status- und Command-Topics klar getrennt?

Typische Nutzung¶

Sensor pruefen¶

MQTT Explorer oeffnen.
Topic-Baum aktualisieren.
Zum vermuteten Topic navigieren.
Sensor ausloesen oder Zustand aendern.
Pruefen, ob sich Payload oder Zeitstempel aendert.

Damit laesst sich schnell erkennen, ob der Sensor sendet oder ob das Problem erst spaeter in Home Assistant entsteht.

Zigbee2MQTT-Geraet pruefen¶

MQTT Explorer oeffnen.
Den Zigbee2MQTT-Bereich im Topic-Baum suchen.
Das betroffene Geraet aufklappen.
Status-, Availability- und Aktionswerte ansehen.
Die Werte mit Zigbee2MQTT und Home Assistant vergleichen.

Wenn die Daten im MQTT Explorer ankommen, aber in Home Assistant fehlen, liegt die Ursache eher in der MQTT-Integration, Discovery oder Entitaetszuordnung.

Retained Message erkennen¶

Topic im MQTT Explorer auswaehlen.
Payload und Eigenschaften pruefen.
Achten, ob der Wert sofort nach dem Verbinden angezeigt wird.
Bei unerwarteten alten Werten pruefen, ob eine retained Message gesetzt ist.

Retained Messages koennen hilfreich sein, aber auch alte Zustaende sichtbar halten. Deshalb sollten sie bei Diagnosefaellen immer mitgedacht werden.

Command-Topic vorsichtig testen¶

Vorher klaeren, welches Geraet das Topic steuert.
Payload-Format aus Dokumentation oder bestehendem Topic ableiten.
Nur unkritische Befehle testen.
Wirkung am Geraet und in Home Assistant kontrollieren.

Command-Topics koennen echte Aktionen ausloesen, zum Beispiel Schalten, Konfigurationsaenderungen oder Neustarts. Diese Funktion ist kein Spielplatz, sondern ein Werkzeug fuer gezielte Diagnose.

Zugehoerige Entitaeten¶

Home Assistant stellt fuer die App eigene Verwaltungsentitaeten bereit:

binary_sensor.mqtt_explorer_lauft - Laufstatus der App.
sensor.mqtt_explorer_version - installierte Version.
sensor.mqtt_explorer_neueste_version - neueste verfuegbare Version.
sensor.mqtt_explorer_cpu_prozent - CPU-Nutzung.
sensor.mqtt_explorer_arbeitsspeicher_in_prozent - Arbeitsspeichernutzung.
update.mqtt_explorer_update - Update-Status.
switch.mqtt_explorer - App ein- oder ausschalten.

Diese Entitaeten sind auch in der Entitaeten-Dokumentation unter MQTT Explorer aufgefuehrt.

Betriebs- und Wartungshinweise¶

MQTT Explorer ist fuer Diagnose gedacht und sollte nicht als dauerhafter Steuerungsweg verwendet werden.
Schreibende MQTT-Aktionen nur ausfuehren, wenn Topic und Payload sicher bekannt sind.
Bei MQTT-Problemen zuerst Mosquitto broker, Zigbee2MQTT und die Home-Assistant-MQTT-Integration pruefen.
Nach Updates der App Version und Funktion kurz kontrollieren.
Zugangsdaten, Broker-Passwoerter und interne Secrets werden nicht im Wiki dokumentiert.
Wenn die App haengt, zuerst den Watchdog-Status, die App-Entitaeten und die Supervisor-Logs pruefen.

Abgrenzung¶

Komponente	Aufgabe
Mosquitto broker	Nimmt MQTT-Nachrichten an und verteilt sie.
MQTT Explorer	Zeigt Topics und Payloads des Brokers grafisch an.
Zigbee2MQTT	Uebersetzt Zigbee-Geraete in MQTT-Topics.
Home Assistant MQTT	Macht MQTT-Daten als Entitaeten in Home Assistant nutzbar.

Kurz gesagt: Mosquitto transportiert, Zigbee2MQTT liefert viele Geraetedaten, Home Assistant nutzt sie, und MQTT Explorer macht den Nachrichtenfluss sichtbar.