EMQX Smart-Home-Integration, kostenlos und Open Source
Der Zustand deines EMQX-MQTT-Brokers in Gladys: Clients, Nachrichtenrate, Alarme, Ausfälle.
Veröffentlicht von guim31
- Geräte
- Version 1.0.0
- Erfordert Gladys >=5.1.0
- ★ 0
Überwacht den Zustand deines MQTT-Brokers EMQX in Gladys: verbundene Clients, Abonnements, Nachrichtenrate, verworfene Nachrichten, aktive Alarme, laufende Knoten, Laufzeit und Ausfälle, dazu die MQTT-Clients, die du beobachten willst (Zigbee2MQTT, ein Shelly, eine Bridge…).
Diese Integration ist nicht mit EMQ Technologies verbunden.
Überblick
Gladys spricht schon MQTT: Die Integration MQTT verbindet sich mit einem Broker, um deine Geräte zu steuern. Über den Broker selbst zeigt sie nichts. Diese Integration schon: Alle 30 Sekunden liest sie die REST-API von EMQX (Version 5 oder 6) mit einem API-Schlüssel und macht daraus Gladys-Geräte, neun Szenen-Auslöser, eine Szenen-Aktion und ein Dashboard-Widget.
Die Integration liest nur: keine veröffentlichte Nachricht, keine Verbindung als MQTT-Client, nie eine Änderung an der Konfiguration von EMQX. Alles bleibt in deinem lokalen Netzwerk.
Für einen Broker Eclipse Mosquitto installiere lieber die Integration Mosquitto: EMQX veröffentlicht andere Statistiken.
Voraussetzungen
- Gladys 5.1 oder neuer.
- EMQX 5 oder 6 (getestet mit 5.8.6 und 6.3.2), der Port des Dashboards (standardmäßig 18083) von Gladys aus erreichbar.
- Ein API-Schlüssel von EMQX und sein geheimer Schlüssel.
EMQX 4 wird nicht unterstützt: Seine API ist anders.
Einen API-Schlüssel erstellen
- Öffne das Dashboard von EMQX (
http://<Adresse>:18083). - Gehe zu System → API Key und dann auf Create.
- Gib ihm einen Namen (zum Beispiel
gladys). Wenn EMQX eine Rolle anbietet, wähle Viewer: Lesezugriff genügt. - Kopiere den API Key und den Secret Key: EMQX zeigt das Secret nur einmal an.
Konfiguration
| Feld | Beschreibung |
|---|---|
| Adresse von EMQX | Die Adresse des Dashboards: http://192.168.1.20:18083, oder nur der Host (Port 18083 wird ergänzt). |
| API-Schlüssel | Der oben erstellte API Key. |
| Geheimer Schlüssel | Sein Secret Key. |
| Selbstsigniertes Zertifikat akzeptieren | Für eine https://-Adresse, deren Zertifikat Gladys nicht prüfen kann. |
| Zu beobachtende MQTT-Clients | Client-IDs durch Kommas getrennt, höchstens 20. Jeder wird ein Gerät. Leer: keiner. |
| Sprache der Texte | Namen der Funktionen beim Hinzufügen, Szenen-Sätze und Meldungen der Aktionen (standardmäßig Französisch). |
Die Schaltfläche Verbindung prüfen liest EMQX sofort und zeigt Version, Kennzahlen, aktive Alarme und wie viele beobachtete Clients verbunden sind.
Öffne danach den Tab Erkennung der Integration und füge den Broker und die gewünschten Clients hinzu.
Das Gerät des Brokers
| Funktion | Bedeutung |
|---|---|
| Erreichbar | 1, solange die API antwortet, 0 während eines Ausfalls. |
| Verbundene Clients | Gerade verbundene MQTT-Clients. |
| Abonnements | Abonnements aller Clients. |
| Topics | Topics mit mindestens einem Abonnenten. |
| Empfangene Nachrichten (/min) | An den Broker veröffentlichte Nachrichten, pro Minute. |
| Gesendete Nachrichten (/min) | An Abonnenten zugestellte Nachrichten, pro Minute. |
| Verworfene Nachrichten (/min) | Von EMQX verworfene Nachrichten (oft: niemand abonniert das Topic), pro Minute. |
| Gespeicherte Nachrichten | Vom Broker für neue Abonnenten aufbewahrte Nachrichten (retained). |
| Aktive Alarme | Aktive Alarme von EMQX (Speicher, CPU, Überlastung…). |
| Laufende Knoten | Laufende Knoten des Clusters (1 für einen einzelnen Broker). |
| Laufzeit | In Tagen, seit dem Start des jüngsten Knotens. |
| Version | Version von EMQX. |
Die Raten stammen von EMQX selbst, das sie alle 10 Sekunden misst. Während eines Ausfalls ändert sich nur Erreichbar: Die anderen Werte behalten ihren letzten Stand.
Beobachtete Clients
Jede Client-ID im Feld Zu beobachtende MQTT-Clients wird ein Gerät mit ihrem Namen und zwei Funktionen:
- Verbunden: 1, wenn der Client mit EMQX verbunden ist, sonst 0 (auch wenn EMQX ihn nicht mehr kennt).
- Letzte Verbindung: Datum und Uhrzeit seiner letzten Verbindung, in der Zeitzone von Gladys.
Die Client-IDs stehen auf der Seite Clients des Dashboards. Zigbee2MQTT zum Beispiel nimmt die
client_id seiner Konfiguration (mqttjs_…, wenn keine gesetzt ist: Gib ihm zuerst eine feste).
Dashboard-Widget
Das Widget EMQX-Broker zeigt den Zustand des Brokers, seine Version, seine Laufzeit, die Knoten eines Clusters, die aktiven Alarme (bis zu drei mit Namen) und vier Live-Kacheln: Clients, empfangene, gesendete und verworfene Nachrichten pro Minute. Wähle den Broker in seinen Einstellungen.
Szenen-Auslöser
| Auslöser | Wann |
|---|---|
| Broker nicht erreichbar | Die API antwortet seit 1, 5, 15, 30 oder 60 Minuten nicht (nach Wahl). |
| Broker wieder da | Die API antwortet wieder nach einem Ausfall von mindestens einer Minute. |
| Broker neu gestartet | Die Laufzeit eines Knotens ist auf null zurückgegangen, auch ohne sichtbaren Ausfall. |
| Alarm ausgelöst | EMQX hat einen Alarm ausgelöst. Variablen: Name des Alarms, Meldung, Knoten. |
| Alarm beendet | Ein Alarm ist nicht mehr aktiv. Variable: seine Dauer in Minuten. |
| Client getrennt | Ein beobachteter Client ist nicht mehr verbunden. |
| Client wieder verbunden | Ein beobachteter Client ist wieder verbunden. Variable: Minuten getrennt. |
| Weniger verbundene Clients | Weniger Clients als die gewählte Zahl während einer Minute. |
| Nachrichtenspitze | Mehr empfangene Nachrichten pro Minute als die gewählte Zahl; höchstens alle 30 Minuten. |
Nach einem Neustart der Integration dient die erste Messung als Referenz: Ein schon aktiver Alarm oder ein schon abwesender Client löst nichts aus.
Szenen-Aktion
Zustand des Brokers liefert einen Satz für eine Nachricht („EMQX 5.8.6 läuft seit 3 Tagen, 12 Clients verbunden, 64 Nachrichten empfangen und 87 gesendet pro Minute, kein Alarm.") und die Zahlen: erreichbar, verbundene Clients, empfangene, gesendete und verworfene Nachrichten pro Minute, aktive Alarme und ihre Namen, Laufzeit in Stunden, Version.
Szenen-Ideen
- Alarm ausgelöst → dir eine Nachricht „EMQX-Alarm: {{message}} auf {{node}}" schicken.
- Client getrennt für Zigbee2MQTT → warnen, dass die Zigbee-Geräte nicht mehr antworten.
- Jeden Morgen Zustand des Brokers → den Satz an Telegram schicken.
- Broker nicht erreichbar seit 5 Minuten → eine Lampe rot schalten.
Fehlerbehebung
- EMQX ist nicht erreichbar: Prüfe Adresse und Port (standardmäßig 18083, nicht der MQTT-Port 1883) und ob Gladys ihn erreicht (Firewall, Docker-Netzwerk).
- EMQX lehnt den API-Schlüssel ab: Prüfe Schlüssel und Secret, ob der Schlüssel aktiviert und nicht abgelaufen ist. Ein im Dashboard gelöschter Schlüssel muss neu erstellt werden.
- Keine EMQX-5-API unter dieser Adresse: Die Adresse führt woandershin (MQTT-Port, anderer Dienst) oder zu EMQX 4.
- Ein Client bleibt getrennt: Prüfe seine genaue Client-ID auf der Seite Clients des Dashboards (Groß- und Kleinschreibung zählen).
- Mehr Details: Setze
LOG_LEVEL=debugund lies die Protokolle der Integration.
Grenzen
- Messung alle 30 Sekunden: Eine kürzere Trennung kann unbemerkt bleiben.
- Die Raten sind Mittelwerte von EMQX über 10 Sekunden, pro Minute angezeigt.
- Höchstens 20 beobachtete Clients; eine Client-ID mit Leerzeichen kann nicht beobachtet werden.
- Nur die Alarme von EMQX werden gelesen, nicht die Regeln, Bridges oder Plugins selbst.
- EMQX 4 wird nicht unterstützt.
Konfigurationseinstellungen
Diese Einstellungen fragt EMQX in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| EMQX verbinden | section | Nein | Die Integration liest alle 30 Sekunden die REST-API von EMQX 5 oder 6 mit einem API-Schlüssel. Die Integration ändert nie etwas. Erstelle den Schlüssel im Dashboard: System → API Key. |
| Adresse von EMQX | string | Ja | Die Adresse des Dashboards, standardmäßig Port 18083 (http:// oder https://). |
| API-Schlüssel | string | Ja | Lesezugriff genügt: die Rolle Viewer, wenn EMQX sie anbietet. |
| Geheimer Schlüssel | secret | Ja | Wird von EMQX nur einmal beim Erstellen des Schlüssels angezeigt. |
| Selbstsigniertes Zertifikat akzeptieren | boolean | Nein | Nur https://: Das Zertifikat von EMQX wird dann nicht geprüft. |
| Zu beobachtende MQTT-Clients | string | Nein | Client-IDs durch Kommas getrennt, höchstens 20: Jeder wird ein Gerät (verbunden, letzte Verbindung). Die IDs stehen auf der Seite Clients des Dashboards. |
| Sprache der Texte | select | Nein | Namen der Funktionen der Geräte beim Hinzufügen, Szenen-Sätze und Meldungen der Aktionen. |
So installierst du EMQX in Gladys
- Öffne in Gladys Integrationen: EMQX erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/guim31/gladys-emqx:1.0.0) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/guim31/gladys-emqx.
EMQX benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
EMQX ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von guim31 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation