HMRPC -- XML-RPC-basiertes fhem-Modul
Verfasst: 05.10.2011, 00:13
HMRPC - xmlrpc-basierte Homematic-Integration fuer fhem
=======================================================
Von Oliver Wagner <owagner@vapor.com>
V0.1
Uebersicht
----------
HMRPC ist ein Modul zur Integration des Homematic-Systems der Firma EQ-3
mit fhem. Es verfolgt im Gegensatz zu den bereits vorhandenen CUL_HM/HMLAN-
Modulen einen anderen Ansatz: Statt direkt mit der Funk-Hardware zu
kommunizieren, verwendet es die offizielle bereitgestellte xmlrpc-basierte
API der EQ-3-Software (siehe [1]). Daraus ergeben sich Vorteile und
Nachteile: So sind implizit alle derzeitigen und auch zukuenftigen Geraete
vollumfaenglich unterstuetzt, auch die RS485 Wired-Module.
Der wesentliche Nachteil, oder zumindestens eine Vorraussetzung, ist, dass
man eine Instanz der xmlrpc-Server benoetigt. Dazu gibt es aktuell zwei
Moeglichkeiten:
1) auf der CCU1 selbst laufen "rfd" fuer die Funkkommunikation und
"hs485d" fuer die Wired-Kommunikaiton.
Eine Uebersicht der Softwarearchitektur der CCU1 findet sich unter [2]
2) als Teil der Verwaltungssoftware fuer den HM-LAN-Aadapter (siehe [3]) gibt
es einen xmlrpc-Dienst fuer Funkkommunikation als Windows-Service. Dieser
entspricht dem "rfd" auf der CCU1.
Es ist aber nicht auszuschliessen, das EQ-3 in Zukunft z.B. einen rfd fuer
Linux veroeffentlicht.
Geschichte und Status
---------------------
Diese Module sind aus der Middleware "HMCompanion" [4] entstanden, die ich mir
fuer die HM-Integration in meinen Haussteuerungswildwuchs geschrieben habe.
HMRPC hat aktuell eher experimentellen Charakter. Ohne genaue Kenntnisse
von fhem, perl und HM-Internas haben die Module nur eingeschraenkten Nutzwert,
die Veroeffentlichung dient erstmal nur dazu, fruehes Feedback zur
Implementierung zu bekommen.
Das ist im übrigen mein erstes nicht komplett triviales Stück perl-code -- über
Hinweise diesbezüglich würde ich mich ebenso freuen wie über allgemeines
Feedback zu HMRPC.
Benutzung
---------
Es gibt zwei Module:
00_HMRPC.pm ist der Provider fuer die Kommunikation mit eineml
xmlrpc-Service
01_HMDEV.pm ist jeweils die Abstraktion eines einzelnen Devices
Beispielkonfiguration fuer fhem:
# Wired-Schnittstelle auf einer CCU1 mit IP 192.168.5.2)
define hmw HMRPC 192.168.5.2 2000
# Ein Kanal eines Wired-Aktors
define light_buero_olli HMDEV GEQ0009019:3
Nutzung dann z.B. mit
set light_buero_olli STATE false
Ein putParamset (Konfigurationsupdate) wird dann durch zusätzliche Angabe
der Paramset-ID generiert:
set light_buero_olli MASTER LOGGING 0
Die Attribute eines Geraetes entsprechen den in dem Dokument unter [1]
"HomeMatic-Script Dokumentation: Teil 4 - Datenpunkte" beschriebenen.
Die Inhalte der Paramsets sind aktuell nicht dokumentiert, man muss diese
anhand des xmlrpc-Requests getParamsetDescription oder durch Browsen der
XML-Beschreibungen im /firmware-Verzeichnis der CCU-Software
ermitteln.
Weitergehende Funktionen wie synchrones Abfragen von Werten oder Paramsets
oder Statii des jeweiligen Service (Meldungen etc.) sind geplant, aber noch
nicht implementiert.
Design
------
Ich habe überlegt, ob HMRPC als Provider für CUL_HM dienen könnte, habe aber
keine praktikable Lösung dafür gefunden -- HMDEV ist aktuell im Vergleich zu
CUL_HM sehr dumm und dient mehr oder weniger nur als Cache für Adresse und
Readings.
HMRPC meldet sich beim jeweiligen Service per "init" an und erhält dann per
xmlrpc-Callback Mitteilungen über Zustandsänderungen. Wird der Service neu
gestartet (CCU Reboot o.ä.), ist diese Anmeldung hinfällig. Es gibt aktuell
keine gute Methode, dies festzustelle -- als Workaround meldet sich HMRPC
15 Minuten nach dem letzten empfangenen Callback neu an. Je nach Art der
verwendeten Aktoren in einer Installation kann diese Zeit sehr kurz sein
und daher unnötige re-inits verursachen. Diese scheinen aber grundsätzlich kein
Problem auf der Service-Seite darzustellen.
Anhang
------
[1] http://www.homematic.com/index.php?id=156
[2] http://www.homematic-wiki.info/mw/index ... c_Software
[3] http://www.homematic.com/index.php?id=644
[4] http://homematic-forum.de/forum/viewtop ... =26&t=4639
=========
Hinweis: Dateianhang entfernt, aktuelle Version ist jeweils im "Nightly CVS"-Tarball des fhem-Paketes enthalten, siehe http://fhem.de/fhem.html unter "Download"
=======================================================
Von Oliver Wagner <owagner@vapor.com>
V0.1
Uebersicht
----------
HMRPC ist ein Modul zur Integration des Homematic-Systems der Firma EQ-3
mit fhem. Es verfolgt im Gegensatz zu den bereits vorhandenen CUL_HM/HMLAN-
Modulen einen anderen Ansatz: Statt direkt mit der Funk-Hardware zu
kommunizieren, verwendet es die offizielle bereitgestellte xmlrpc-basierte
API der EQ-3-Software (siehe [1]). Daraus ergeben sich Vorteile und
Nachteile: So sind implizit alle derzeitigen und auch zukuenftigen Geraete
vollumfaenglich unterstuetzt, auch die RS485 Wired-Module.
Der wesentliche Nachteil, oder zumindestens eine Vorraussetzung, ist, dass
man eine Instanz der xmlrpc-Server benoetigt. Dazu gibt es aktuell zwei
Moeglichkeiten:
1) auf der CCU1 selbst laufen "rfd" fuer die Funkkommunikation und
"hs485d" fuer die Wired-Kommunikaiton.
Eine Uebersicht der Softwarearchitektur der CCU1 findet sich unter [2]
2) als Teil der Verwaltungssoftware fuer den HM-LAN-Aadapter (siehe [3]) gibt
es einen xmlrpc-Dienst fuer Funkkommunikation als Windows-Service. Dieser
entspricht dem "rfd" auf der CCU1.
Es ist aber nicht auszuschliessen, das EQ-3 in Zukunft z.B. einen rfd fuer
Linux veroeffentlicht.
Geschichte und Status
---------------------
Diese Module sind aus der Middleware "HMCompanion" [4] entstanden, die ich mir
fuer die HM-Integration in meinen Haussteuerungswildwuchs geschrieben habe.
HMRPC hat aktuell eher experimentellen Charakter. Ohne genaue Kenntnisse
von fhem, perl und HM-Internas haben die Module nur eingeschraenkten Nutzwert,
die Veroeffentlichung dient erstmal nur dazu, fruehes Feedback zur
Implementierung zu bekommen.
Das ist im übrigen mein erstes nicht komplett triviales Stück perl-code -- über
Hinweise diesbezüglich würde ich mich ebenso freuen wie über allgemeines
Feedback zu HMRPC.
Benutzung
---------
Es gibt zwei Module:
00_HMRPC.pm ist der Provider fuer die Kommunikation mit eineml
xmlrpc-Service
01_HMDEV.pm ist jeweils die Abstraktion eines einzelnen Devices
Beispielkonfiguration fuer fhem:
# Wired-Schnittstelle auf einer CCU1 mit IP 192.168.5.2)
define hmw HMRPC 192.168.5.2 2000
# Ein Kanal eines Wired-Aktors
define light_buero_olli HMDEV GEQ0009019:3
Nutzung dann z.B. mit
set light_buero_olli STATE false
Ein putParamset (Konfigurationsupdate) wird dann durch zusätzliche Angabe
der Paramset-ID generiert:
set light_buero_olli MASTER LOGGING 0
Die Attribute eines Geraetes entsprechen den in dem Dokument unter [1]
"HomeMatic-Script Dokumentation: Teil 4 - Datenpunkte" beschriebenen.
Die Inhalte der Paramsets sind aktuell nicht dokumentiert, man muss diese
anhand des xmlrpc-Requests getParamsetDescription oder durch Browsen der
XML-Beschreibungen im /firmware-Verzeichnis der CCU-Software
ermitteln.
Weitergehende Funktionen wie synchrones Abfragen von Werten oder Paramsets
oder Statii des jeweiligen Service (Meldungen etc.) sind geplant, aber noch
nicht implementiert.
Design
------
Ich habe überlegt, ob HMRPC als Provider für CUL_HM dienen könnte, habe aber
keine praktikable Lösung dafür gefunden -- HMDEV ist aktuell im Vergleich zu
CUL_HM sehr dumm und dient mehr oder weniger nur als Cache für Adresse und
Readings.
HMRPC meldet sich beim jeweiligen Service per "init" an und erhält dann per
xmlrpc-Callback Mitteilungen über Zustandsänderungen. Wird der Service neu
gestartet (CCU Reboot o.ä.), ist diese Anmeldung hinfällig. Es gibt aktuell
keine gute Methode, dies festzustelle -- als Workaround meldet sich HMRPC
15 Minuten nach dem letzten empfangenen Callback neu an. Je nach Art der
verwendeten Aktoren in einer Installation kann diese Zeit sehr kurz sein
und daher unnötige re-inits verursachen. Diese scheinen aber grundsätzlich kein
Problem auf der Service-Seite darzustellen.
Anhang
------
[1] http://www.homematic.com/index.php?id=156
[2] http://www.homematic-wiki.info/mw/index ... c_Software
[3] http://www.homematic.com/index.php?id=644
[4] http://homematic-forum.de/forum/viewtop ... =26&t=4639
=========
Hinweis: Dateianhang entfernt, aktuelle Version ist jeweils im "Nightly CVS"-Tarball des fhem-Paketes enthalten, siehe http://fhem.de/fhem.html unter "Download"