homeeUp

homeeUp erlaubt es Dir virtuelle Geräte in homee anzulegen und diese via homee direkt oder indirekt über die von homee unterstützten Sprachsysteme (Alexa, Google Home oder Siri) zu schalten. Der Schaltzustand dieser virtuellen Geräte ist dabei jeweils im homee abgebildet und lässt sich auch in Homeegrammen als Auslöser, Bedingung und Aktion verwenden.

Dazu wird von homeeUp eine Homematic CCU (die Steuerzentrale eines Homematic-System) simuliert. Du benötigst dazu keine physische CCU, allerdings werden auch nicht alle Funktionen der CCU simuliert, sondern es werden nur frei konfigurierbare "emulierte" Geräte an der definierten Schnittstelle für den homee bereitgestellt. Dem homee wird also vorgespielt er sei mit einer CCU verbunden, die in der simulierten CCU scheinbar vorhandenen Geräte existieren ebenfalls nicht physisch, sondern nur logisch in Form von Software.

Mit dieser simulierten / emulierten CCU können frei konfigurierbar virtuelle Geräte (u.a. ein HM-LC-Sw1-FM Switch und eine HM-RC-4-2 Remote Control stehen dazu derzeit als Gerätetypen bereit) über vorhandene Plugins in den homee geladen werden. Als Plugins stehen u.a. bereits ein HTTP-Switch (beliebige URL-Aufrufe können mit homeeUP für das Ein- und Ausschalten von Geräten konfiguriert werden) oder ein CMD-Switch (Command-Switch, der beliebige Befehle auf dem Linux-Rechner auf dem homeeUp installiert ist ausführen kann) bereit.

Damit lassen sich noch nicht direkt von homee unterstützte Geräte einfach in homee integrieren. mögliche Anwendungsfälle könnten sein:

  • Fernseher oder Lautsprecherboxen, welche über eine REST-API an- und ausschaltbar sind
  • Roboterstaubsauger oder andere Geräte die sich über einen URL-Aufruf oder bereits reverse engineerte Kommandozeilentools bzw. curl-Aufrufe starten und stoppen lassen
  • Lampen in einer Hue Bridge an- und ausschalten und dabei den Schaltzustand in homee vorhalten
  • Eurer Phantasie und Eurem Spieltrieb sind hier kaum Grenzen gesetzt

homeeUp unterstützt allerdings nur die Schaltungen von Geräten (vergleichbar der Schaltung von Aktoren), Sensoren (welche Werte an homee zurückliefern) werden (noch) nicht unterstützt.

homeeUp stellt ein Plugin-System bereit, welches es Entwicklern erlaubt einfach Erweiterungen zu programmieren. Solche existieren bereits für MQTT, den Vorwerk Kobold Staubsaugerroboter und die FritzBox (um das Gäste-WLAN bequem vom homee aus (z.B. via Homeegrammen Tageszeitabhängig) ein- und ausschalten zu können). Weitere werden sicherlich folgen.

In diesem Wiki-Artikel soll erklärt werden, wie das ganze im Zusammenspiel mit homee funktioniert. 

homee unterstützt von Haus aus bisher noch keine virtuellen Geräte, auch wenn es dazu bereits einige Gerätevorschläge oder Featurevorschläge in der homee Community gibt.

Indirekt lassen sich mit homeeUp auch einfache Variabeln (z.B. True / False via An / Aus) speichern, ohne dafür auf Tricks wie die Schaltung von unbenutzten oder extra dafür angeschafften Plugs oder Relais (z.B. ein nicht verdrahteter Schalter 2 eines Fibaro 223 Switch) zurückgreifen zu müssen.

Installation

Die API kann manuell installiert werden - siehe Zusatzinfos am Ende dieses Artikels - oder via homeean.

Die manuelle Installation ist nicht im Fokus dieses Artikels, wir konzentrieren uns auf die Installation und Konfiguration im Zusammenspiel mit homeean. Die manuelle Installation ist auf der Webseite von homeeUp ausreichend dokumentiert.

Die Installationsvoraussetzungen und die eigentliche Installation sind im nachfolgend verlinkten Wiki-Artikel ausführlich beschrieben:

Installation & Nutzung von homeean

Konfiguration

Nach der Installation von homeeUp via homeean läuft homeeUp bereits.

Im Homeverzeichnis des Users pi unter /home/pi/.homeeup findet sich das Konfigurationsfile config.json, welches Ihr via nano config.json wie gewohnt editieren könnt.

Bildschirmfoto-2018-04-12-um-00.04.06.png

Darin sind bereits zwei Demo-Geräte implementiert, welche wir testweise zunächst mal in homee importieren wollen, um das Vorgehen zu verstehen.

Geht dazu in einer beliebigen App (iOS/Android/Web) auf Geräte / Geräte hinzufügen und wählt dort WLAN aus (CCU-Geräte werden über WLAN an homee angebunden). Beim darauf erscheinenden Gerätetyp wählt Ihr Homematic CCU2 aus.

Daraufhin wird die folgende Maske erscheinen:

Bildschirmfoto-2018-04-11-um-23.42.35.png

Unter Hostname gebt Ihr jetzt die IP-Adresse des Raspberry Pis ein, auf dem homeeUp installiert wurde, z.B.:
192.168.178.111

Klickt danach oben rechts auf Weiter und die folgende Maske wird erscheinen:

Bildschirmfoto-2018-04-11-um-23.44.59.png

Wählt dort die beiden angebotenen Geräte aus und klickt wieder oben rechts auf Weiter.

Beide Geräte werden nun der Geräteliste hinzugefügt und sind ab dem Zeitpunkt wie "normale" Geräte im homee bedienbar und auch in Homeegrammen (als Auslöser, Bedingung und Aktion verwendbar). Ihr könnt diese beliebig umbenennen, den Alias-Namen für die Sprachsteuerungen wählen, sie Gruppen hinzufügen oder sie auch wieder löschen. Für homee sehen diese Geräte aus, wie normale via einer CCU integrierte Geräte.

Alle im oben genannten Konfigurationsfile fehlerfrei angelegten Geräte sind importierbar, allerdings müsst Ihr nach Änderungen an der config.json den homeeUp-Dienst noch mal neu starten via sudo systemctl restart homeeup, damit an der Schnittstelle die aktuellsten Geräte angeboten werden und homeeUp Veränderungen an der Konfiguration (z.B. eine andere URL für eines der Geräte) erkennt. Wie homeean-Services gestartet, gestoppt, neu gestartet oder deren Status abgefragt wird, ist auf der homeean Installationsseite unter Dienste Starten und Stoppen beschrieben.

Die Geräte lassen sich (ohne sie zu löschen) nicht noch mal importieren, der homee erkennt in dem Fall an der Schnittstelle keine neuen Geräte. Selbst wenn Ihr die Geräte in der config.json von homeeUp editiert, macht das für homee keinen Unterschied - Ihr müsst sie danach nicht noch einmal löschen und neu importieren, nur den homeeUp-Service auf dem Raspberry Pi neu starten. Die Logik der Schaltung läuft in homeeUp ab, welches für homee wie eine CCU aussieht.

Kommen wir wieder zurück zum Configfile (config.json im Verzeichnis .homeeup des Homeverzeichnisses des Users pi), das uneditiert wie folgt ausieht:

{
        "plugins": [{
                        "deviceName": "HTTPSwitch",
                        "type": "SimpleHTTPPlugin",
                        "pluginParams": {
                                "onUrl": "http://www.google.de/on",
                                "offUrl": "http://www.google.de/off"
                      }
                },
                {
                        "deviceName": "CMDSwitch",
                        "type": "SimpleCMDPlugin",
                        "pluginParams": {
                                "onCmd": "touch /tmp/file",
                                "offCmd": "rm /tmp/file",
                                "statusCmd": "ls /tmp/file >> /dev/null; echo 0",
                                "checkInterval": 2000
                        }
                }
        ],
        "hostAdress": "192.168.178.91 2001:16b8:2238:1100:7cd5:4c2d:f26b:5911 "
}

Das File liegt im JSON-Format vor. JSON ist ein Datenaustauschformat, dass sowohl für Menschen einfach zu lesen als auch für Computer einfach zu interpretieren ist.

Stark vereinfach gesagt (Details bitte hinter dem Link nachlesen) ist das Dateiformat sehr sensitiv was Formatierungen angeht. Bevor Ihr das File (z.B. mit nano) ändert/speichert, solltet Ihr deshalb den Inhalt immer in die Zwischenablage nehmen und auf einem Internetdienst wie http://json.parser.online.fr auf korrekte Syntax prüfen. Das spart viel Frust. Jede geschweifte Klammer auf   { bedingt am Ende immer eine Klammer zu }, eine Aufzählung von mehreren Werten in einem Array, begrenzt durch [ ], wird immer durch ein Komma , abgetrennt, dasselbe gilt auch für mehrere aufeinander folgende Name: Wert Paare. Einzig das letzte Objekt oder das letzte Name: Wert Paar in einer Aufzählung hat am Ende kein Kommazeichen.

Mit diesem Wissen liest sich das Standard-Konfigfile wie folgt:

  • Lege ein Array mit dem Namen Plugin (begrenzt durch [ ]) an.

  • In diesem Array befinden sich zwei Devices (jeweils durch {} begrenzt) mit den Namen HTTPSwitch und 
    CMDSwitch (diese Namen finden sich beim Import in den homee, siehe Grafik oben in Klammer wieder). 

  • Diese beiden Devices haben den Typ SimpleHTTPPlugin und SimpleCMDPlugin, welche individuelle Pluginparameter haben (wie im Programmcode der jeweiligen Plugins definiert).

  • Beim SimpleHTTPPlugin gibt es eine onUrl und eine offUrl - der definierte Wert der onUrl wird aufgerufen, wenn das Gerät im homee angeschalten wird, die offUrl, wenn das Gerät ausgeschalten wird. Hiermit können beliebige URL-Aufrufe mit einer Get-Operation aufgerufen werden. Eine Get-Operation führt Ihr normalerweise aus, wenn Ihr eine URL in einem Webbrowser ausführt, Variabeln-Werte können Get-Operations via anhängen von Parameten an die URL mitgegeben werden. Beispiel: http//www.api.url/api/starteRoboter?roboter=1&geschwindigkeit=2
    Post-Operations (Werte werden dabei im HTTP-Body (und nicht in der URL selbst) übergeben) werden vom SimpleHTTPPlugin derzeit (noch) nicht supportet. Dafür solltet ihr das nachfolgende Plugin nutzen.

  • Beim SimpleCMDPlugin gibt es einen onCmd und einen offCmd, also einen Command/Befehl, der auf der Kommandozeile des Rechners auf dem homeeUp installiert ist, beim Einschalten bzw. Ausschalten des Gerätes im homee ausgeführt wird. Dieses Plugin unterstützt mit dem statusCmd auch die Überwachung ob der Status des virtuellen Gerätes sich (ausserhalb des homee) geändert hat, dieses Überprüfung wird im definierten checkInterval (hier: alle 2000 Sekunden?) durchgeführt. Das bedingt aber einen Rückkanal des angebundenen Tools, was nicht immer gegeben ist.

    Mit diesem Plugin können beliebige (verkettete) Befehle ausgeführt werden, das macht dieses Plugin sehr variabel, bedingt aber u.U. einige Kommandozeilenerfahrung beim User. Dieses Plugin kann man z.B. auch mit einem curl-Aufruf dazu benutzen die Lichter in einer Hue Bridge zu schalten, wenn man seine Hue-Lampen (aus welchen Gründen auch immer) nicht in homee schalten will.
    Ein Beispiel dafür (Danke an Matthias):
    "onCmd": "curl -X PUT -H 'Content-Type: application/json' -d '{\"on\":true}' http://192.168.xxx.xxx/api/key/lights/8/state",
    "offCmd": "curl -X PUT -H 'Content-Type: application/json' -d '{\"on\":false}' http://192.168.xxx.xxx/api/key/lights/8/state",
    "statusCmd": "ls /home/pi/.homeeup >> /dev/null",
    "checkInterval": 2000
    Mit Hilfe des Komandozeilenbefehls curl lassen sich sowohl andere Operationstypen als das Get des SimpleHTTPPlugins (z.B. Post, Put, Delete - eben alle die von curl untersützt und ggf. von APIs verlangt werden) als auch JSON-Payloads (wie sie ebenfalls von manchen APIs verlangt werden) umsetzen.
    Mehr Infos zu curl finden sich hier.

  • Am Ende des Arrays hinterlegt homeean bei der Installation noch die IP-Adresse in der v4 und der v6 Variante (sofern lokal benutzt). Diesen Wert solltet Ihr in der Regel nur sachlogisch ändern müssen, wenn Ihr das Konfigfile auf einem anderen Server einsetzen wollt.

Selbstverständlich könnt Ihr die bestehenden Plugins ändern und neue Instanzen aller unterstützten Plugintypen dem Konfigfile hinzufügen oder vorhandene löschen. Ihr solltet diese allerdings mit einem eindeutigen deviceName benennen, die Syntax des JSON-Files beachten (vor dem Speichern UNBEDINGT TESTEN wie oben beschrieben) und diese Geräte dann erst nach einem Neustart von homeeUp in den homee importieren, wie ebenfalls oben bereits beschrieben.

Zum jetzigen Zeitpunkt existieren bereits weitere Plugins für homeeUp, welche aber leider noch nicht vollständig dokumentiert sind.

  • SimpleMQTTPlugin
    Steuerung von MQTT-fähigen Devices.
    Ein Beispiel dafür (hier die Steuerung eines über ioBroker integrierten Xiaomi Staubsaugers via MQTT was einen lokalen MQTT-Broker (homeean bietet die Möglichkeit dafür Mosquitto zu installieren) bedingt. Danke fürs Beispiel und das Plugin an Gido:
    "deviceName": "Xiaomi0",

               "type": "SimpleMQTTPlugin",

               "pluginParams": {

                   "mqttServer": "172.18.19.2",

                   "mqttUserName": "mqtt",

                   "mqttPassword": "mqtt",

                   "mqttMessageMode": "state",

                   "mqttPublishOnTopic": "mihome-vacuum/0/control/start/set",

                   "mqttPublishOffTopic": "mihome-vacuum/0/control/pause/set",

                   "mqttSubscribeOnTopic": "iobroker/mqtt.0/mihome-vacuum/0/control/start/set",

                   "mqttSubscribeOffTopic": "iobroker/mqtt.0/mihome-vacuum/0/control/pause/set"

  • FritzBoxPugin
    Eine Plugin um das Gäste-WLAN einer FritzBox via homee an- und ausschalten zu können.
    Ein Beispiel dafür (Danke ans kevdi):

    {

                      "deviceName": "FritzGastWifi",

                      "type": "FritzBoxPlugin",

                      "pluginParams": {

                          "ipAddress": "http://fritz.box/",

                          "user": "username",

                          "password": "passwort"

                      }

                  }

    Damit könnt Ihr das Gäste-WLAN zum Beispiel tageszeitabhängig oder via einem Taster an- und ausschalten. Der user muss allerdings erweiterte Berechtigungen haben, der von mir benutzte hat ALLE Berechtigungen.

  • VorwerkKoboldPlugin
    Ein Plugin um einen Vorwerk Kobold Roboterstaubsauger via homee an- und ausschalten zu können. Ein Beispiel dafür:

    {
       "deviceName": "VorwerkKobold",
       "type": "VorwerkKoboldPlugin",
       "pluginParams": {
            "email": "your@email.com",
            "password": "password"
      }
    }

    Ich kann es in Ermangelung eines Gerätes nicht testen, es scheint so, dass die Werte email und password (wahrscheinlich eines Cloud-Accounts bei Vorwerk) errwartet werden. Konkrete Beispielkonfigs sind willkommen.

Die Konfiguration aller Plugins lässt sich im Detail bereits aus dem Code (wer es kann und versteht) herauslesen. 

 So einfach integriert Ihr virtuelle Geräte in homee.


Zusatzinfos

Mehr Infos zu homeeUp (inkl. der offiziellen Dokumentation) gibt es hier:
https://github.com/kdietrich/homeeup

Thread zu homeeUp in der homee Community, wo Ihr weitere Fragen stellen könnt:
https://community.hom.ee/t/homeeup-virtuelle-geraete-in-homee/11352

No Comments
Back to top