HMCompanion V0.19
=================
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 befand sich zwischenzeitlich auf der offiziellen Homematic-Webseite,
scheint aber derzeit nicht verfügbar zu sein.
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. 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