HMCompanion - Schnittstelle zur CCU

[owagner]

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.

[Mediaman2000]

Top Arbeit - einfache intuitive Syntax, gerade getestet und genau das was mir schon lange gefehlt hat. Bin zwar sonst eher der Fan von Sachen die direkt auf der Zentrale ablaufen, aber da eh ein kleiner Server läuft macht der jetzt diesen Zwischendienst mit.

[ColdFireIce]

5. Bekannte Probleme
--------------------
Es existiert aktuell kein bekannter Mechanismus, um einen "init"-Befehl zu wiederrufen. Die CCU versucht
also auch nach dem Beenden von HMCompanion weiter, xmlrpc-Befehle an den Rechner abzusetzen, auf dem HMCompanion
lief.

Hast du mal hier geschaut:
http://homematic-forum.de/forum/viewtop ... =26&t=4458
Ich habs noch nicht probiert, da ich momentan mich gegen xmlrpc-init entschieden habe, es ist für meine Zwecke zu langsam. Komisch ist auch dass Aktor Schaltungen länger brauchen um gesendet zu werden, als zB ein Bewegungsmelder.
wegen dem deinit ist auch auch noch zu erwähnen, dass nach einem neustart der CCU alle inits wieder weg sind.

Grüße
Daniel

[owagner]

Hast du mal hier geschaut:
http://homematic-forum.de/forum/viewtop ... =26&t=4458

Ja, das ist eine Fehlinformation (von mir -- ich habe Sie mal richtiggestellt)

Einen schnelleren Weg als xmlrpc init, um an Events zu kommen, gibt es doch m.E. gar nicht? Die ReGa macht ja auch nur ein init, bei den tcpdump-Lösungen hängt man sich einfach in den xmlrpc-Verkehr zwischen ReGa und den Services. Oder habe ich was übersehen?

Wegen des CCU-Restarts wollte ich in HMC noch einbauen, dass der init erneut geschickt wird, wenn die TCP-Verbindung zu den xmlrpc-Servern abreisst.

Viele Grüße,
Olli

[ColdFireIce]

Ja, das ist eine Fehlinformation (von mir -- ich habe Sie mal richtiggestellt)

öhm ja, User lesen wäre manchmal hilfreich

naja xmlrpc mag ja irgendwie schnell sein, allerdings ist es für meine zwecke nicht ganz tauglich
Fachgeplapper ab hier:
Ich hab zwar nen php-xmlrpc aufgesetzt, und die events auch verarbeiten können, allerdings bringt mir dass wenig wenn ich einen Homepage client laufen lasse, da ich zwischen dem Server und den offenen Sites ja keine direkte Kommunikation herstellen kann. Habe es über die Session Vars probiert, aber das ist dann eben zu langsam da diese auch in Dateien abgelegt werden, außerdem muss ich dann busy-waiting betreiben was extrem dreckiger programier stiel ist. noch dazu benutze ich ja die CCU als Server die das ganze auch einbremst. So ist bei mir eine direkte Abfrage eines Status mit xmlrpc die schnellste Möglichkeit an einen zustand zu kommen. für viele aktoren ist jedoch der weg über TCL-ReGa der schnellste (also als Sammelanfrage). kann mir das auch nicht wirklich erklären, ist aber so. hab dass auch mal mit xmlrpc multicall ausprobiert und dass war extrem langsam, im prinzip so wie viele einzelne xmlrpc calls.
deswegen kann ich dich strucktur auch nicht ganz glauben, da es mir eben so vorkommt als würde das HM-Script nicht den weg über XMLRPC bzw ReGa suchen.

hab grad keine konkreten zahlen, aber aus Erinnerung war es so dass bei 12 aktoren die abfrage mit multicall etwa 4 sec. gedauert hat, und als sammel abfrage mit TCL-ReGa etwa 1.3 sec.

und dass ergibt irgendwie nicht so recht Sinn...

Grüße

Daniel

[owagner]

Das heisst, Du machst Abfragen mit getValue, um die Werte zu kriegen? Das ist in der Tat langsam (ich glaube, wenn man das macht, reden rfd/hs485 tatsächlich aktiv mit dem Gerät)

Die ReGaHss macht ja sowas wie HMCompanion, d.h. sie subscribed einmal per init und cached danach alle Attribut-Updates, die sie im weiteren Verlauf von den Servern sowieso bekommt, im Speicher. Wenn man sie dann per HMScript fragt, kriegt man die Antwort aus dem Cache (und so gesehen sind 1.3 Sekunden wieder sehr langsam). Genau aus dem Grund habe ich mir HMC gebaut.

Viele Grüße,
Olli

[ColdFireIce]

hmm.

dass würde das erklären. könnte man echt so aufbaun. Mein Problem ist halt dass ich alles auf der CCU laufen lassen will. aber ich könnte das caching auch bei mir mal miteinbaun. kann dein packet nicht wirklich nutzen, da der HP server der auf der CCU läuft ja das xmlrpc apache package nicht drin hat, bzw auch nicht die php erweiterung.
Das ändert jedoch wenig an der Zeit bis ne Aktualisierung ankommt. irgendwie dauert mir das trotzdem zulange. Ich muss mir da mal wieder bisschen Zeit nehmen und dass testen. Aber danke erst mal für den "insight".

Grüße
Daniel

[owagner]

HMC auf der CCU kann man, glaube ich vergessen, ich wüßte nicht, dass es eine J2SE-JVM für ARM gibt.

Ich habe das deswegen so implementiert, weil ich eh eine relativ schwere Kiste als Hausserver laufen habe, auf der sowieso java läuft und dadurch kein zusätzlicher Footprint für die JVM entsteht.

Man könnte das jetzt für die CCU mit C++ o.ä. neu implementieren, aber dann erfindet man schon ein wenig das Rad "ReGaHSS" neu; ich denke, Dein Ansatz mit HMScript ist eine gute Lösung für diesen Anwendungsfall.

BTW, falls noch nicht bekannt: wenn man beim init eine URL mit dem String "bin" im Pfad übergibt, schickt die CCU die Events auch in dem proprietären Binärformat. Das ist eventuell mit PHP einfacher zu parsen als das echte xmlrpc. Vielleicht baue ich HMC auch noch entsprechend um, dann kann die Apache-Bibliothek weg.

Viele Grüße,
Olli

[kaju74]

Hi...

BTW, falls noch nicht bekannt: wenn man beim init eine URL mit dem String "bin" im Pfad übergibt, schickt die CCU die Events auch in dem proprietären Binärformat

So macht's ja auch HCS und XMLRPCBIN...

Gruß,
kaju

[owagner]

Verwendet HCS-Tool nicht den tcpdump-Umweg statt die subscription via init?

Viele Grüße,
Olli