Hallo liebe homee Gemeinde,
nachdem ich meinen Xiaomi Mi Robot Vacuum (Staubsauger) endlich bekommen habe, habe ich heute mal versucht ihn über Webhooks steuerbar zu machen.
Auslöser dazu war, dass trotz Aussagen von homee dieses Jahr ggf. einen Roboterstaubsauger einzubinden, nicht zu erwarten ist, dass der Xiaomi da erste Wahl ist (selbst wenn es erst nächstes Jahr soweit sein sollte)…
Vorab soviel: Ich war erfolgreich (über Umwege) 
Der selbe Weg kann Stand heute auch für Saugroboter von Dyson (Dyson 360 Eye) und iRobot (iRobot Roomba - das sollte bei den Modellen der Serie 980 auf jeden Fall funktionieren und könnte auch bei den Wifi-unterstützten Geräte der Reihen 690, 890 oder dem 960 laufen - zumindest laut Home Assistant).
Disclaimer:
Das hier ist ein Software-Bastelprojekt für Erfahrenere und die Umsetzung bedingt zusätzliche Hardware (z.B. einen Raspi Pi) und Software (Home Assistant - eine freie Heimautomatisierungssoftware) und einiges an Wissen rund um Konfiguration und Troubleshooting in diesem Umfeld. Ich kann hier leider keinen Support zu Home Assistant leisten - verweise aber gerne auf die hervorragende Homepage von Home Assistant, wo es ausführlichere Anleitungen zur Installation und Konfiguration gibt. Eine Empfehlung für Home Assistant gebe ich jedoch: Benutzt für Eure ersten Gehversuche die containerisierte Version Hass.io (Getting started - Home Assistant), die ist gerade für Home Assistant Newbies leichter zu installieren und am Laufen zu halten.
Keine offizielle Xiaomi API verfügbar, aber…
Xiaomi bietet derzeit keine eigene API an, allerdings haben einige findige Köpfe die API reverse engineered und andere Entwickler haben diese dann in ihre Plattformen (z.B. Home Assistant) eingebaut,. So ähnlich läuft es auch mit der Sonos API, die einige (u.a. Home Assistant) ja bereits anbieten, die aber Stand heute immer noch nicht offiziell verfügbar ist. Jede Änderung des Herstellers an einer so implementierten API führen dann ggf. zu Problemen, das sollte jedem bewusst sein, bevor auf solche APIs gesetzt wird.
Vorgehen zur Einrichtung
Das ganze bedingt deshalb eine funktionierende Home Assistant Instanz auf einem Server und beschreibt nur das Vorgehen für den Xiaomi Mi, andere Roboter-Staubsauger bitte gem. der Anleitung auf den jeweiligen Home Assistant Komonponentenseiten - rechts in der Auswahl - einrichten.
Zunächst müsst Ihr die Staubsaugerplattform auf Home Assistant aktivieren, gem. der Doku hier.
Dafür müsst Ihr jedoch zuvor den Token Eures Robots (eindeutige Identifikation Eures Gerätes in der Xiaomi Cloud) ausgelesen haben - das ist auf derselben Seite weiter unten hier beschrieben für alle möglichen Plattformen.
Ich habe das ganze unter Mac und iOS gemacht (zu anderen Plattformen kann ich nichts sagen) und will folgendes festhalten:
Die Anleitung für iOS ist präzise und sollte Punkt für Punkt befolgt werden, allerdings solltet Ihr folgendes beachten:
- Ihr benötigt auf einem Mac ein UNVERSCHLÜSSELTES Backup eines Gerätes auf dem die Mi Software installiert und für Euren User konfiguriert ist. Es funktioniert nicht mit Geräten, die irgendwelche Firmenzertifikate installiert haben. Mein Workaround: Die Software auf einem privaten iOS-Gerät installieren und den Cloud-User hinzufügen und dann noch schnell ein Backup mit iTunes machen.
- Wenn Ihr (wie ich) einen Mac habt und ihr OS X gerade upgedated habt, dann unterstützt iTunes keine lokalen Backups mehr. Dieser Artikel beschreibt was Ihr dann machen könnt - das hat bei mir geholfen. Den Artikel dazu unbedingt bis zum Ende lesen (ich will nicht schuld sein, wenn Eure iTunes-Bibliothek nicht mehr laufen sollte).
Wenn Eure Konfiguration erfolgreich war (wenn nicht, dann könnt Ihr die Fehlermeldung in den Logs von Home Assistant auswerten), erscheint auf der Home Assistant Web-GUI das nachfolgende Paneel.
Wenn Ihr das anklickt, dann öffnet sich der nachfolgende Layer und Ihr könnt im Erfolgsfall Euren Robot mit den „Vacuum cleaner commands“ bereits erstmals über eine Drittlösung steuern.
Ja, aber ich will homee und nicht Home Assistant…
Damit geben wir uns jedoch noch nicht zufrieden, wir wollen ja schliesslich unser Haus mit Hilfe von homee SMART machen und nicht mit anderen Platformen (mehr als nötig) herumspielen.
Wie bekommen wir jetzt also den Roboter in homee?
→ Via Webhooks.
Home Assistant bietet verschiedene APIs, u.a.
Die für uns einfachst zu nutzende ist die REST-API, für die Nutzung der anderen bin ich schlicht zu doof (selbst die REST-API kapiere ich nur in Bruchstücken).
Über Get- oder Post Operations - wie auf der REST-API Doku zu sehen - können mit Hilfe einer bestimmten URL-Syntax Services gestartet oder Konfigurationen ausgelesen werden. Die vorhandenen Services sind abhängig von Eurer Home Assistant Konfiguration.
Die Doku zu den vorhandenen Schnittstellen kann wie folgt abgerufen werden:
http://EureHomeAssistantIP:8123/api/services (der Port 8123 ist der Standard-Port und kann von Euch abweichend konfiguriert werden, nachfolgend benutze ich nur den Standard-Port)
Die zurückgelieferten Werte kann man in einem JSON-Parser (z.B. http://json.parser.online.fr) pasten, da sind sie besser lesbar.
Das sieht dann (zur Erhöhung der Übersichtlichkeit teilweise eingeklappt) in etwa so aus:
Da sieht man also, dass Vacuums u.a. den Service „turn_on“ (Starten des Reinigungsprogramms) und „turn_off“ (beenden des Programms und zurück zur Ladestation) anbieten. Diese Services werden wir noch brauchen. (Das hätten wir auch in der Doku zur jeweiligen Komponente nachlesen können, aber so ist es besser verständlich).
Jetzt müssen wir nur noch wissen wie unser Roboter denn eigentlich in Home Assistant intern heisst:
http://EureHomeAssistantIP:8123/api/config liefert u.a. die Antwort darauf. Meiner heisst intern: „vacuum.xiaomi_miio“, wobei „vacuum“ nur die Bezeichnung der Domain ist. Auch das merken wir uns, wir werden das gleich brauchen.
Die REST-API kann nämlich auch ohne JSON-Orgien direkt via URL angesprochen werden.
Die Logik dahinter ist wie folgt:
http://EureHomeAssistantIP:8123/api/services/DOMAIN/BEFEHL?entity_id=NameDesGerätes&api_pwassword=EuerSelbstGesetztesAPI-Passwort (sofern gesetzt)
Der Aufruf von
http://EureHomeAssistantIP:8123/api/services/vacuum/turn_on?entity_id=xiaomi_miio&api_password=EuerSelbstGesetztesAPI-Passwort in einem Browser sollte dann logischerweise dazu führen, dass der Roboter losfährt. EIGENTLICH ja, ABER…
An der REST-API nimmt Home Assistant für den Aufruf von Services nur Post-Requests an (ein einfacher URL-Aufruf ist aber ein Get-Request und wird deswegen NICHT funktionieren). Aber wozu haben wir die Webhooks in homee?
Wenn Ihr die o.g. URL in die URL einer Webhook-Aktion reinpastet (entsprechend auf Eure Gegebenheiten angepasst), bei der Methode explizit Post auswählt und den Content Type und den Body nicht anfasst, dann wird der Webhook (sofern er abspielbar ist oder eine Auslöser-Bedingung zutrifft) ausgelöst und Euer Roboter wird mit dem Reinigungsprogramm beginnen.
Analog könnt Ihr ihn wieder in die Station zurückschicken:
http://EureHomeAssistantIP:8123/api/services/vacuum/turn_off?entity_id=xiaomi_miio&api_password=EuerSelbstGesetztesAPI-Passwort
Ich plane für die Automatisierung meines Roboters als Auslöser das Zu- und Aufschliessen (für An und Aus) meines Türschlosses (Nuki) zwischen 08.00 Uhr und 12.00 Uhr zu benutzen, nachdem ich meine Königin darüber aufgeklärt habe.
Die heutigen Spielereien haben mich aber wieder etwas auf den Geschmack gebracht bestimmte DInge (z.B. Sprachausgabe auf Sonos und Präsenz) ebenfalls mal mit Hilfe von Home Assistant auszutesten. Mal gucken, vielleicht mache ich hier weiter…
Edit: Inzwischen ist auch ein englisches Sprachpaket für die Sprachausgabe des Roboters (via App) nachinstallierbar. Ich fand die Chinesischen Ansagen ja durchaus süss (meine Grosse hat sie geliebt), aber ich ziehe es vor zu verstehen, wenn der Roboter um Hilfe schreit, wenn er irgendwo feststeckt.
