Xiaomi MIoT Smart-Home-Integration, kostenlos und Open Source
Xiaomi-Luftreiniger, Befeuchter, Ventilatoren, Steckdosen und Lampen lokal (MIoT).
Veröffentlicht von guim31
- Geräte
- Version 1.0.1
- Erfordert Gladys >=5.1.0
- ★ 0
Steuere deine WLAN-Geräte von Xiaomi, Mi Home und Mijia aus Gladys, in deinem lokalen Netzwerk: Luftreiniger, Luftbefeuchter, Luftentfeuchter, Ventilatoren, smarte Steckdosen, Schalter, Lampen, Luftqualitätsmonitore und die Sensoren darin. Die Integration liest die öffentliche MIoT-Spezifikation jedes Modells und übersetzt seine Standarddienste in Gladys-Funktionen: Kein Modell wird von Hand programmiert. Dazu kommen ein Dashboard-Widget, ein Wartungs-Auslöser und eine Szenen-Aktion.
Das Xiaomi-Konto wird nur einmal genutzt, um deine Geräte mit ihrer lokalen Adresse und ihrem Token (dem Schlüssel, den jedes Gerät braucht) aufzulisten. Danach bleibt alles in deinem Netzwerk: Gladys spricht direkt mit jedem Gerät, wie die Mi-Home-App in deinem WLAN.
Die Integration ergänzt die anderen im Store: Die Saugroboter der Mi-Home-App steuert die Integration Xiaomi Home, Roborock- und Dreame-Roboter die ihren. Diese Integration lässt die Saugroboter aus.
Developed without the hardware: feedback welcome. Diese Integration wurde mit echten MIoT-Spezifikationen (veröffentlicht von den Projekten homebridge-miot und hass-xiaomi-miot) und mit simulierten Geräten gebaut und getestet, nicht mit einem echten Luftreiniger oder einem echten Xiaomi-Konto. Wenn etwas nicht wie beschrieben funktioniert, sag es im Gladys-Forum oder in den Issues.
Nicht mit Xiaomi verbunden. Xiaomi, Mi Home und Mijia sind Marken ihrer Inhaber.
Was du brauchst
- Gladys Assistant 5.1.0 oder neuer.
- Xiaomi-WLAN-Geräte, die schon in der Mi-Home-App (Xiaomi Home) eingerichtet sind, im selben Netzwerk wie Gladys.
- Entweder die E-Mail-Adresse (oder Telefonnummer) und das Passwort des Mi-Home-Kontos und seine Region; oder für jedes Gerät seine IP-Adresse und sein Token (32 hexadezimale Zeichen), mit einem anderen Werkzeug ermittelt.
- Internetzugang für Gladys bei der Einrichtung: das Xiaomi-Konto (einmal) und miot-spec.org (einmal pro Modell, um seine Spezifikation zu laden).
Einrichtung
Mit dem Xiaomi-Konto
- Installiere die Integration aus dem Gladys-Katalog.
- Öffne ihre Konfiguration und gib ein:
- E-Mail-Adresse oder Telefonnummer und Passwort des Mi-Home-Kontos;
- Region des Kontos: die Serverregion aus der Mi-Home-App (Profil → Einstellungen → Region). Standardmäßig Europa; ein Gerät aus einer anderen Region wird nicht aufgelistet;
- Aktualisierungsintervall: wie oft jedes Gerät gelesen wird, 15 s bis 2 min (standardmäßig 30 s);
- Sprache der Funktionsnamen: Englisch, Französisch, Deutsch oder Spanisch (standardmäßig Französisch). Die Namen eines Geräts und seiner Funktionen werden beim Hinzufügen vergeben.
- Speichere. Die Integration meldet sich an und importiert die Geräte sofort; um es später erneut zu tun, klicke auf Geräte des Xiaomi-Kontos importieren: Die Meldung unter der Schaltfläche listet, was importiert und was ausgelassen wurde.
- Bestätigung in zwei Schritten: Wenn Xiaomi sie verlangt, enthält die Meldung einen Link. Öffne ihn in einem Browser, fordere dort den Code an (SMS oder E-Mail), gib ihn aber nicht auf dieser Seite ein. Zurück in Gladys tippst du den Code in das Feld Bestätigungscode und klickst innerhalb von 15 Minuten erneut auf Geräte des Xiaomi-Kontos importieren.
- Öffne den Reiter Entdecken: ein Gerät pro Xiaomi-Gerät. Klicke auf Hinzufügen, wähle einen Raum, speichere.
Das Passwort bleibt in der Konfiguration der Integration; die Tokens liegen in
ihrem privaten Volume (/data) und werden nie wieder angezeigt. Du kannst das
Passwort leeren, sobald die Geräte importiert sind: Die Geräte funktionieren weiter.
Mit IP-Adresse und Token
Kein Konto, oder ein Gerät, das das Konto nicht auflistet? Klicke in der Konfiguration auf Gerät mit IP-Adresse und Token hinzufügen, mit der Adresse des Geräts (dein Router zeigt sie) und seinem Token. Die Integration fragt das Gerät nach seinem Modell, was auch das Token bestätigt. Das Gerät erscheint im Reiter Entdecken.
Weitere Aktionen der Konfiguration
- Geräte diagnostizieren: für jedes Gerät sein Modell, seine Adresse, ob es antwortet, wie viele Funktionen übersetzt und welche Dienste ausgelassen wurden; und die miIO-Geräte im Netzwerk, die die Integration nicht kennt.
- Gerät und sein Token vergessen: entfernt ein Gerät aus der Integration (verkauft, ersetzt). Lösche es auch in Gladys.
Die Geräte in Gladys
Jedes Gerät wird ein Gladys-Gerät, benannt nach seinem Namen in Mi Home (oder seiner Art und dem Ende seiner Kennung). Nur was seine Spezifikation angibt, wird veröffentlicht:
| Funktion | Was es ist | Geräte |
|---|---|---|
| Ein/Aus | Ein / aus | Luftreiniger, Befeuchter, Ventilatoren, Steckdosen, Schalter |
| Licht | Ein / aus | Lampen |
| Modus | Die Modusliste des Geräts (Auto, Schlafen, Favorit…) | Luftreiniger, Befeuchter, Ventilatoren |
| Lüfterstufe | Eine Liste von Stufen oder ein Schieberegler | Luftreiniger, Befeuchter, Ventilatoren |
| Horizontale Oszillation | Oszillation ein / aus | Ventilatoren |
| Vertikale Oszillation | Oszillation ein / aus | Ventilatoren |
| Zielfeuchtigkeit | Eine Liste in 5-%-Schritten | Befeuchter, Entfeuchter |
| Wasserstand | Restwasser im Tank, in % | Befeuchter |
| Wassertank leer | Ja / nein | Manche Befeuchter |
| Solltemperatur | Der Sollwert, nur angezeigt | Heizgeräte |
| Störung | Was das Gerät meldet, oder Keine Störung | Die meisten Geräte |
| Temperatur | °C | Geräte mit Sensor |
| Luftfeuchtigkeit | % | Geräte mit Sensor |
| PM2,5 / PM10 | µg/m³ | Luftreiniger, Monitore |
| CO2 | ppm | Monitore |
| Beleuchtungsstärke | Lux | Geräte mit Lichtsensor |
| Filterlebensdauer | % übrig | Luftreiniger |
| Filter-Restzeit | Tage oder Stunden | Luftreiniger |
| Batterie | % | Monitore mit Akku |
| Kindersicherung | Sperrt die Tasten des Geräts | Die meisten Geräte |
| Leistungsaufnahme | Watt | Steckdosen mit Messung |
| Helligkeit | % | Lampen |
| Farbtemperatur | Kelvin, im Bereich des Modells | Lampen |
| Farbe | Die Farbe einer Farblampe | Farblampen |
- Ein Heizgerät wird angezeigt, nie gesteuert: Ein/Aus und Sollwert sind nur lesbar. Ein Heizgerät, das wie eine Lampe von einer Szene, einem Dashboard oder einem Sprachassistenten gesteuert wird, könnte einen leeren Raum heizen oder neben etwas anspringen; nutze seine Tasten oder die Mi-Home-App.
- Was die Übersetzung auslässt (Signalton, Display, Kontrollleuchte, Herstellereinstellungen), listet Geräte diagnostizieren; es bleibt mit der Szenen-Aktion MIoT-Eigenschaft setzen erreichbar.
- Wenn ein Gerät nicht mehr antwortet, zeigt sein Abzeichen es als nicht erreichbar; es kommt von selbst zurück.
Dashboard-Widget
Füge das Widget Luftqualität zu einem Dashboard hinzu und wähle in seinen Einstellungen ein Gerät. Es zeigt bis zu vier Live-Kacheln (PM2,5, CO2, Temperatur, Luftfeuchtigkeit, Wasserstand, Filterlebensdauer als Anzeige, in dieser Reihenfolge), den Zustand des Geräts (ein, aus oder antwortet nicht), seinen Modus und seine Lüfterstufe, eine Störung, falls vorhanden, und Schaltflächen:
- Einschalten / Ausschalten, schaltet das Gerät, egal was das Widget anzeigte (nicht bei einem Heizgerät);
- die ersten beiden Modi des Geräts (zum Beispiel Auto und Schlafen); der laufende trägt ein Häkchen.
Szenen
Auslöser
Xiaomi-Gerät braucht Aufmerksamkeit: löst einmal aus, wenn ein Grund beginnt, und erst wieder, nachdem er geendet hat. Filter:
- Xiaomi-Gerät: ein Gerät oder jedes;
- Grund: Filter wechseln (Filterlebensdauer bei 10 % oder weniger), Wassertank leer (der Tank-Alarm oder ein Wasserstand von 0 %), Störung (das Gerät meldet eine Störung); leer für alle.
Die Variablen geben den Namen des Geräts (device_name), den Grund (filter,
water oder fault) und ein Detail (die Filterlebensdauer, die gemeldete
Störung). Laufende Gründe bleiben über einen Neustart erhalten.
Aktion
MIoT-Eigenschaft setzen: schreibt jede änderbare Eigenschaft eines Geräts
über ihre Nummer auf miot-spec.org (siid.piid, zum Beispiel 6.1 für den
Signalton eines Mi Air Purifier 4), mit einem Wert, wie ihn die Spezifikation
erwartet (true / false, eine Zahl oder ein Text). Die Aktion lehnt eine
Eigenschaft ab, die es nicht gibt oder die nur lesbar ist, einen Wert
außerhalb des Bereichs und jedes Heizgerät. Die Aktion gibt den geschriebenen Wert an
die nächsten Aktionen weiter.
Um die Nummern zu finden: Öffne https://home.miot-spec.com/spec/<Modell>
(zum Beispiel zhimi.airp.mb5) oder starte Geräte diagnostizieren, das die
ausgelassenen Dienste mit ihrer Nummer nennt.
Szenen-Ideen
- Filter-Erinnerung: Xiaomi-Gerät braucht Aufmerksamkeit, Grund Filter wechseln → sende die Nachricht „{{device_name}}: Filter bei {{detail}}“.
- Ruhige Nächte: jeden Tag um 22 Uhr → setze den Modus des
Luftreinigers auf Schlafen, dann MIoT-Eigenschaft setzen
6.1=false, um seinen Signalton abzuschalten. - Besser atmen: wenn PM2,5 des Monitors über 35 steigt → schalte den Luftreiniger ein, Modus Auto.
- Befeuchter nachfüllen: Xiaomi-Gerät braucht Aufmerksamkeit, Grund Wassertank leer → sende eine Nachricht und schalte den Befeuchter aus.
Fehlerbehebung
- Kein Gerät importiert: Prüfe die Region des Kontos (ein Xiaomi-Konto gehört zu einer Region) und die Meldung unter der Schaltfläche: Saugroboter, Bluetooth- und Zigbee-Geräte werden absichtlich ausgelassen.
- „Xiaomi verlangt ein Captcha“: Melde dich einmal aus demselben Netzwerk in der Mi-Home-App an, warte ein paar Minuten, versuche es erneut; oder füge die Geräte von Hand hinzu.
- Ein Gerät antwortet nicht: Prüfe, ob es im selben Netzwerk wie Gladys ist (ein Gastnetz oder ein abgeschottetes IoT-VLAN blockiert es), und gib ihm in deinem Router eine feste Adresse. Ein Gerät, das seine Adresse wechselt, wird innerhalb von 15 Minuten durch einen Erkennungs-Broadcast von Gladys wiedergefunden (UDP-Port 54321, daher diese Berechtigung bei der Installation).
- „lehnt sein Token ab“: Das Gerät wurde zurückgesetzt oder in Mi Home neu gekoppelt, sein Token hat sich geändert: Klicke erneut auf Geräte des Xiaomi-Kontos importieren.
- „Spezifikation fehlt“: miot-spec.org hat nichts für dieses Modell oder war nicht erreichbar; die Integration versucht es alle 15 Minuten erneut. Alte reine miIO-Modelle (vor MIoT) werden nicht unterstützt.
- Die Integration protokolliert, was sie findet und was nicht antwortet (mehr
mit
LOG_LEVEL=debug): Öffne ihre Protokolle in der Gladys-Oberfläche.
Grenzen
- Nur WLAN-Geräte: Bluetooth- und Zigbee-Geräte hinter einem Xiaomi-Gateway haben keine eigene Adresse und werden ausgelassen.
- Saugroboter werden ausgelassen (siehe die Integrationen Xiaomi Home, Roborock und Dreame).
- Klimaanlagen, Thermostate, Wasserkocher, Kochgeräte und andere Arten werden noch nicht übersetzt: Diese erscheinen nur, wenn sie einen der Standarddienste oben haben (eine Steckdose, einen Sensor…).
- Keine Push-Meldungen: Jedes Gerät wird standardmäßig alle 30 Sekunden gelesen, eine gebündelte Anfrage pro Gerät; eine Änderung in Mi Home erscheint beim nächsten Lesen.
- Die Xiaomi-Server werden nur beim Import der Geräte aufgerufen (und wenn sich die Kontodaten ändern), miot-spec.org einmal pro Modell. Danach wird keines von beiden gebraucht.
- Ohne die Hardware entwickelt: Modellspezifische Unterschiede, die die Spezifikationen nicht nennen (eine Leistung in einer anderen Einheit), können Anpassungen brauchen; melde sie bitte.
Konfigurationseinstellungen
Diese Einstellungen fragt Xiaomi MIoT in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Xiaomi-Konto | section | Nein | Das Konto wird nur einmal genutzt, um deine WLAN-Geräte mit Adresse und Token aufzulisten; danach bleibt alles im lokalen Netzwerk. Speichere und starte dann unten „Geräte des Xiaomi-Kontos importieren“. Kein Konto? Füge ein Gerät mit IP-Adresse und Token hinzu. |
| E-Mail-Adresse oder Telefonnummer | string | Nein | Die Anmeldung deines Mi-Home-Kontos (Xiaomi Home). |
| Passwort | secret | Nein | |
| Region des Kontos | select | Nein | Die Serverregion aus der Mi-Home-App (Profil → Einstellungen → Region). |
| Aktualisierungsintervall | select | Nein | Wie oft jedes Gerät im lokalen Netzwerk gelesen wird. |
| Sprache der Funktionsnamen | select | Nein | Namen, die die Geräte beim Hinzufügen erhalten, und Texte der Integration. |
So installierst du Xiaomi MIoT in Gladys
- Öffne in Gladys Integrationen: Xiaomi MIoT erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/guim31/gladys-xiaomi-miot:1.0.1) 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-xiaomi-miot.
Xiaomi MIoT 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
Xiaomi MIoT 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 externen Integrationen durchsuchen
- Die nativen Integrationen entdecken, die in Gladys eingebaut sind
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation