[Please note: The middleware aspect of this software has been superseded by https://github.com/owagner/hm2mqtt] HMCompanion V0.22 ================= Geschrieben von Oliver Wagner <owagner@vapor.com> 1. Was ist HMCompanion? ----------------------- HMCompanion ist eine Middleware, welche ich gebaut habe, um mein Homematic-System via CCU besser in meine Hausautomation integrieren zu können. Es handelt sich um einen Server-Prozess, der auf der einen Seite mit der CCU kommuniziert und auf anderen Seite mittels einfacher TCP-Textkommandos ansteuerbar ist. Dies ermöglicht eine sehr einfache Integration in PHP, Bash-Scripte etc. Desweiteren arbeitet HMCompanion auch als sehr effizienter Cache für den Status aller Channel auf der CCU, so daß z.B. für Visualisierung auf diese Daten ohne Verzögerung zugegriffen werden kann. HMCompanion ist in Java geschrieben und funktioniert auf jeder Plattform mit mindestens einer Java-1.5-JRE (also NICHT direkt auf der CCU selbst) 2. Grobe Struktur der CCU-Software ----------------------------------- Um die Funktionsweise von HMCompanion zu verstehen, ist es sinnvoll, einen groben Überblick über die Struktur der CCU-Software zu haben. Die CCU-Software besteht aus mehreren Schichten: Auf der untersten Ebene liegen drei Daemon-Prozesse, welche die Kommunikation mit den Hardwarekomponenten vornehmen: rfd -- mit den BidCoS-Funk-Komponenten (direkt oder über HM-CFG-LAN) (Port 2001) hs485d -- mit den HomeMatic-Wired-Komponenten (Port 2000) pfmd -- mit der Hardware der CCU selbst (Port 2002) Der CUxD ist, wenn installiert, ein ebensolcher Daemon (Port 8701) Diese Prozesse besitzen jeweils eine xmlrpc-Schnittstelle, über welche sie angesteuert werden können und über welche Ereignisse (z.B. Status-Änderungen) gemeldet werden. Auf dieser Ebene existieren Geräte und Kanäle nur als Adressen. +--------+ | WebUI | +--------+ | JSON-RPC +---------+ |Webserver| +---------+ | HMScript (und xmlrpc) +--------+ |ReGa HSS| +--------+________ / xml | \ \ / rpc | \ \ +---+ +-------+ +----+ +----+ |rfd| |hs485d | |pfmd| |CuXD| +---| +-------+ +----+ +----+ | (TCP/IP) +----------+ |HM-CFG-LAN| +----------+ Über diesen Prozessen liegt die von EQ-3 als "Logikschicht" bezeichnete Ebene (ReGa, von "Residential Gateway"). Diese managt die Konfiguration der Hardwarekomponenten, führt WebUI-Programme aus, handhabt die Abarbeitung von HMScript und ähnliches. Auf dieser Ebene werden auch die Namen und Bezeichnungen der Geräte verwaltet (in der "homematic.regadom"-Datenbank). Diese Logikschicht wiederum besitzt zwei Schnittstellen: Zum einen die Möglichkeit, über eine TCL-Bibliothek HMScript-Befehle auszuführen zu lassen, zum anderen ist über einen Webserver damit ein JSON-RPC-API realisiert, welches wiederum von der WebUI verwendet wird. Das WebUI wiederum ist eine browserseitige AJAX-Applikation, welche die Daten der ReGa visualisiert und die ReGa (via JSON-RPC) ansteuert. Die JSON-API-Befehle kann man mittels http://homematic-ip/api/homematic.cgi einsehen. Wer telnet-Zugang auf die CCU hat, kann den TCL-Quelltext der einzelnen über das API verfügbaren Methoden im Verzeichnis /www/api/methods einsehen. Diese lassen auch interessante Rückschlüsse auf interne HMScript- und xmlrpc-Aufrufe zu. Eine Dokumentation der XML-RPC-Schnittstelle bfindet sich auf der Hersteller-Website unter http://www.eq-3.de/software.html 3. Kommunikation HMCompanion und CCU ------------------------------------ HMCompanion kommuniziert auf zwei Ebenen mit der CCU: a) Es benutzt xmlrpc, um direkt Befehle an rfd, hs485, pfmd und -- falls installiert, CUxD -- zu schicken. a.1) Es meldet sich mittels des xmlrpc-Befehls "init" als zusätzliche Logikschicht an den Daemonen an, um von diesen über Ereignisse informiert zu werden. Dies macht die Installation von tcpdump o.ä. auf der CCU selbst unnötig. Die xmlrpc-Kommunikation geht über die entsprechenden Schnittstellen der drei Serverdienste. Es wird das proprietäre binärkodierte Format der CCU-Komponenten verwendet. b) Es benutzt HMScript, um von der CCU eine Liste aller Geräte mit Namen zu erhalten, damit diese dann mittels GET, SET etc. per Namen angesprochen werden können. HMScript wird mittels eines HTTP POST an die URL http://<homematic>:8181/tclrega.exe ausgeführt. 4. Benutzung von HMCompanion ---------------------------- HMCompanion wird mit folgendem Befehl gestartet: java -jar hmcompanion.jar <ip oder hostname der CCU> -server <optionaler Port, ansonsten 6770> <optionales password> HMCompanion registriert sich dann zuerst per xmlrpc-API bei den vier Daemon-Prozessen, um Events zu erhalten, fordert danach per HMScript die ReGa-Geräteliste an und wartet dann auf TCP-Verbindungen zum angegebenen Port. Zum Beispiel mittels telnet localhost 6770 kann man sich dann mit dem HMCompanion verbinden und Befehle abschicken. Mittels "HELP" erhält man eine Auflistung aller verfügbaren Befehle. Ein Beispiel: Aktuellen Status eines Channel-Attributes abrufen: GET Wetterstation Attribut setzen: SET "Licht Kellerflur" STATE on Bei SET/GET können jeweils sowohl die BidCoS-Adressen der Channel als auch die im WebUI zugewiesene Namen verwendet werden. Bei Set/SetParam können auch Wildcards verwendet werden, z.B. SET "*Licht*" STATE on setzt alle Komponenten mit Namen, die "Licht" enthalten, auf ein. Das Auslesen von Attributen von mehreren Geräten ist mittels des Befehls "MGET" möglich. Da in den xmlrpc-Requests die Datentypen der Parameter eine Rolle spielen, rät HMCompanion anhand des Formats: on/true, off/false -> Boolean Integer-Zahl (nur 0-9) -> Integer Dezimalzahl (d.h. mit Dezimalpunkt) -> Dezimalzahl alles andere -> String Dies bedeutet, dass man Parameter, die als Dezimalzahl erwartet werden (z.B. LEVEL), immer auch als Dezimalzahl übergeben muss, also "0.0" statt "0" und "1.0" statt "1", ansonsten wird der Request vom jeweiligen Daemon ignoriert. HMCompanion speichert den aktuellen Stand aller Channel-Attribute beim Beenden in der Datei "hmc.cache" und lädt diesen beim Start wieder. Dies dient insbesondere für Geräte, die nur alle 24h o.ä. ein Update schicken. Wird HMCompanion auf einem Server-System betrieben, macht es Sinn, die Speicherzuteilung der JavaVM mittels "-Xmx64M" auf 64MB zu beschränken: java -Xmx64M -jar hmcompanion.jar <ip oder hostname der CCU> -server Hat ein System eine aktivierte, aber unvollständige IPv6-Konfiguration, kann es nötig sein, den Parameter "-Djava.net.preferIPv4Stack=true" zu setzen, um zu verhindern, dass eine fehlerhafte Callback-Adresse ermittelt wird. 5. Events --------- Es besteht die Möglichkeit, Events zu definieren, um beim Auftreten von bestimmten Zuständsänderungen Scripte auszuführen. Diese werden in der Form Kanalname_oder_adresse.Attribut.Wert=script definiert, zum Beispiel BidCoS-Wir:10.PRESS_SHORT.true=/pfad/zum/skript.sh Diese Events können entweder als Property beim Start von HMC mitgegeben (-DBidCoS-Wir:10.PRESS_SHORT.true=/pfad/zum/skript.sh) oder in der optionalen Datei "hmcompanion.cfg" definiert werden. 6. Interface zu Graphite/Carbon ------------------------------- HMC kann sämtliche Statusänderungen auch als Metric an einen carbon-Server des Graphite-Pakets (http://graphite.wikidot.com/) schicken. Hier muss die Netzwerkadresse des Carbon-Servers mittels der Property -Dhmc.carbon.host=<hostname oder IP> festgelegt werden. Die Namen der Metriken werden aus dem ReGaHSS-Gerätenamen und dem Attributnamen gebildet, mit dem zusätzlichen Präfix, welches per "-Dhmc.carbon.prefix=" festgelegt ist (Default ist "hm."). Dabei wird alles in Kleinbuchstaben verwandelt und alle unzulässigen Zeichen werden in "_" umgewandelt. Boolsche Werte werden dabei in numerisch 0 bzw. 1 umgesetzt. Beispiel: Das Attribut "RAINING" des Gerätes "Wetterstation Aussen" ergibt den Metriknamen hm.wetterstation_aussen.raining 7. History ---------- V0.2 - erste funktionale Version V0.3 - verwendet XMLRPC-BIN auch für eingehende Requests, kein Apache ws-xmlrpc mehr nötig - Dump-Format für strukturierte Antworten verbessert - Serialization-Fehler beim Cache-Schreiben behoben - Neues Kommando "CGET", um alle Attribute eines Kanals in einem für Cacti lesbarem Format auszugeben V0.4 - SET funktioniert nun auch wieder mit reinen BidCoS-Adressen anstatt nur mit ReGa-Namen - neuer Befehl "SETPARAM", um einen einzelnen Konfigurationsparameter via der xmlrpc-Methode "putParamset" zu setzen. Beispiel z.B. zum Setzen eines Temperaturreglers auf Automatik: SETPARAM GEQ00xxxxx:2 MASTER MODE_TEMPERATUR_REGULATOR 1 V0.5 - SET und SETPARAM akzeptieren nun Wildcards (*) für Channelnamen. Heissen z.B. alle Thermostat-Steuerkanäle "Thermostat <Raum> 1", kann man mit SETPARAM "Thermostat * 1" MASTER MODE_TEMPERATUR_REGULATOR 1 alle gleichzeitig auf Modus "Auto" setzen. V0.6 - Watchdog: Wird nun mehr als 180s kein Callback empfangen, werden die init-Requests erneut geschickt (z.B. nach einem Reboot der CCU) - Neuer Befehl "HMSet <variable> <wert>" als Shortcut zum Setzen einer HMScript-Variable - Neuer Befehl "HMGet <variable1> <variable2...>" als Shortcut zum Lesen einer HMScript-Variable - Neuer Befehl "HMRun <programm1> <programm2...>" als Shortcut zum Starten von HMScript-Programmen V0.7 - Mittels "HMGet -timestamp variable" (Textform) oder "HMGet -timestampts variable" (Sekunden seit 1970) kann nur die Last-Modification-Timestamp einer Variable abgefragt werden - "HMSet" benutzt nun .State(v) statt .Variable(v), damit eventuelle Events auf den Systemvariablen ausgelöst werden - Neues Kommando MGET um ein Attribut von einer Menge von Geräten abzufragen, z.B. "MGET PIR* motion". Das Ausgabeformat ist "Gerätename:Wert" V0.8 - Hinweis auf "undokumentierte Schnittstellen" entfernt, da nun durch EQ-3 offengelegt - Beim Beenden von HMC wird nun ein de-init an die xmlrpc-Server geschickt - Neuer Befehl "STATS" um Statistiken über von den xmlrpc-Servern erhaltene Nachrichten im Cacti-Format zu bekommen - QUIT hat nun eine Option "-exit", mit der HMC beendet werden kann V0.9 - Clientverbindungen setzen nun SO_KEEPALIVE - REQ unterstützt nun auch die Angabe von Arrays und Strukturen mit der [ Array ] bzw. { key1 value1 key2 value2 } Notation - GUI-Betriebsmodus zum Setzen der Interface/Roaming-Parameter (einfach ohne Parameter starten) V0.10 - GUI-Modus: Button zum schnellen Refresh der RSSI-Informationen hinzugefügt - GUI-Modus: Schnittstellen werden nun in der CCU-Reihenfolge angezeigt, mit dem Default-Interface zuerst V0.11 - GUI-Modus: Buttons zum Setzen aller Devices auf Roaming Off, auf Default == Interface mit dem besten RSSI-Wert und Roaming On für alle Fernbedienungen V0.12 - Synchronisationsproblem beim Request-Handling konnte dazu führen, das mehrere schnell hintereinander abgesendete "SET" (o.ä.)-Befehle zu einem Deadlock führten - Server-Sockets werden nun alle mit SO_REUSEADDR generiert, um schnellen Neustart möglich zu machen V0.13 - Client-Verbindungen benutzen nun unabhängig vom Systemzeichensatz immer UTF-8 V0.14 - Optionales Authentifizerungstoken für Client-Verbindungen: Wird HMC mit "homematicip -server 6770 <password>" gestartet, werden weitere Befehle nur nach Authentifizerung mit "AUTH <password>" angenommen. V0.15 - Möglichkeit, die lokale IP-Adresse für XML-RPC-Callbacks explizit zu setzen, falls diese falsch ermittelt wird (-Dhmc.localhost=192.168.47.11) V0.16 - Neue Option "-state" beim HMGet, um Alarmvariablen korrekt abzufragen (mit obj.State() statt obj.Variable()) V0.17 - RSSI GUI: Ist eine Interface-Description gesetzt (geht auf der CCU nur durch manuelle Ergänzung der rfd.conf durch Description=), wird diese im Spaltenkopf angezeigt - RSSI GUI: Der Checkboxbereich ist nun grün für das Interface, welches die beste Empfangs-RSSI-Werte für das Gerät hat - RSSI GUI: Ist das ausgewählte Default-Interface NICHT das mit dem besten RSSI-Empfangs-Wert, wird der Checkbox-Bereich rot dargestellt - RSSI GUI: Hinter dem Gerätetyp steht nun die Firmware-Revision V0.18 - unterstützt nun auch CUxD (ab V0.564) - Exec-Patch von "sircus" integriert - Properties können nun in einer Datei "hmcompanion.cfg" definiert werden V0.19 - experimentelle Funktion zum Setzen von Attributen im GUI-Modus V0.20 - Versionen ab 0.18 starteten nicht mehr korrekt, wenn kein CUxD auf der CCU installiert war. V0.21 - Interface zu Graphite/Carbon hinzugefügt V0.22 - Fix für CCU2 (implement nun system.listMethods)
marcoabreu/hmcompanion
Middleware to easily communicate with a Homematic XML-RPC-Server (e.g. CCU1)
JavaGPL-3.0