HMCompanion - Schnittstelle zur CCU
Verfasst: 30.05.2010, 23:12
Hinweis: Als Nachfolger der Middleware-Funktionalität in HMC gibt es nun hm2mqtt -- siehe auch http://homematic-forum.de/forum/viewtop ... 18&t=24109
HMCompanion V0.14
=================
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)
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|
+---| +-------+ +----+
| (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 findet sich unter http://www.homematic.com/index.php?id=156
3. Kommunikation HMCompanion und CCU
------------------------------------
HMCompanion kommuniziert auf zwei Ebenen mit der CCU:
a) Es benutzt xmlrpc, um direkt Befehle an rfd, hs485 und pfmd 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 drei 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
5. 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 staten)
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.
HMCompanion V0.14
=================
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)
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|
+---| +-------+ +----+
| (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 findet sich unter http://www.homematic.com/index.php?id=156
3. Kommunikation HMCompanion und CCU
------------------------------------
HMCompanion kommuniziert auf zwei Ebenen mit der CCU:
a) Es benutzt xmlrpc, um direkt Befehle an rfd, hs485 und pfmd 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 drei 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
5. 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 staten)
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.