als aller erstes möchte ich allen danken die mich bei meinem Fragen in dem letzten Jahr unterstützt haben. Vorallem aus dem Forum möchte ich mich bei owagner, kaju74, dirch, chii und bei Alex Krypthul, Christoph Spielmann bedanken.
Zwischenzeitlich hat eQ-3 eine eigene Spezifikation veröffentlicht: http://www.homematic.com/index.php?id=156 ich denke aber das dieser Artikel besonders für Einsteiger gut ergänzend sein sollte.
Die CCU besitz intern ein XML-RPC Protokoll über das die Kommunikation geregelt wird. Es wird keine zusätzliche Software benötigt. Viel Programme von Hobby Entwicklern oder App-Resellern nutzen diese auch bereits. Allerdings wohl entweder auf basis einer NDA, oder auf Search-Try-and-Error. Ich gehöre zu den letzteren was es mir nicht verbietet meine Funde mit euch zu teilen. Ich schreibe nun schon eine Weile immer wieder an einer Homepage Integration aber das ist ein anderes Thema.
Wer keine Ahnung hat wovon ich eigentlich rede ist hier wohl falsch, allerdings will ich trotzdem kurz erklären worum es geht.
XML-RPC steht für XML(Extensible Markup Language) Remote Procedure Call. Was so viel bedeut wie, dass man mit einer XML Syntax einen Befehl auf einem anderen System ausführen kann. Es ist also möglich der CCU den Befehl zu schicken dass sie das Licht an einem bestimmten Aktor anschalten soll. Dieser Befehl wird mit einen Parametern in ein XML Konstrukt eingebettet. Der Befehl um den Schaltaktor mit der Seriennummer "EEQ0000123" und dem Kanal "1" aus zu (STATE=false) schalten wäre zB:
Code: Alles auswählen
<?xml version="1.0"?>
<methodCall>
<methodName>setValue</methodName>
<params>
<param><value><string>EEQ0000123:1</string></value></param>
<param><value><string>STATE</string></value></param>
<param><value><boolean>0</boolean></value></param>
</params>
</methodCall>also für die Adresse bspw. einen String (eine Zeichenkette) mit der Adresse und dem Kanal des gewünschten Aktors.
als Ergebnis schickt die CCU einem wenn alles funktioniert hat eine leere Nachricht zurück. Also soviel wie: "Es gab keinen Fehler":
Code: Alles auswählen
<?xml version="1.0"?>
<methodResponse>
<params>
<param><value></value></param>
</params>
</methodResponse>Code: Alles auswählen
<?xml version="1.0"?>
<methodResponse>
<fault>
<value>
<struct>
<member>
<name>faultCode</name>
<value><i4>-2</i4></value>
</member>
<member>
<name>faultString</name>
<value>Unknown instance</value>
</member>
</struct>
</value>
</fault>
</methodResponse>Das sollte als Einleitung erst einmal genügen. Wen das Thema XML-RPC mehr interessiert kann sich bei den einschlägigen Quellen belesen. (bspw. Wikipedia und Links oder die offiziele XML-RPC Seite)
PS. die CCU unterstütz auch den system.multicall in klassischer Implementierung.
zur Homematic CCU:
Die CCU stellt 3 Ports für die XML-RPCs zur Verfügung.
2000: Für die Wired Komponenten
2001: Für die RF Komponenten
2002: Für System interne Sachen (hab ich mir nicht genau angeschaut)
Wer dass ELV Magazin gekauft hat kennt die Befehle listDevices, getValue und setValue. Sicherlich mit die wichtigsten aber ein wirklich toller Befehl wurde vergessen: init
außerdem gibt es noch eine menge mehr Befehle (lassen sich mit system.listMethods anzeigen):
Code: Alles auswählen
activateLinkParamset, addDevice, addLink, changeKey, clearConfigCache, deleteDevice, determineParameter, getAllMetadata, getDeviceDescription, getInstallMode, getKeyMismatchDevice, getLinkInfo, getLinkPeers, getLinks, getMetadata, getParamset, getParamsetDescription, getParamsetId, getServiceMessages, getValue, init, listBidcosInterfaces, listDevices, listTeams, logLevel, putParamset, removeLink, reportValueUsage, restoreConfigToDevice, rssiInfo, setBidcosInterface, setInstallMode, setLinkInfo, setMetadata, setTeam, setTempKey, setValue, system.listMethods, system.methodHelp, system.multicallIch stelle jetzt kurz die XML-RPC Struktur der von mir genutzen Befehle vor.
listDevices
Code: Alles auswählen
<?xml version="1.0"?>
<methodCall>
<methodName>listDevices</methodName>
<params></params>
</methodCall>Es müssen keinen Parameter übergeben werden.
getValue
Code: Alles auswählen
<?xml version="1.0"?>
<methodCall>
<methodName>getValue</methodName>
<params>
<param><value><string>EEQ0000123:1</string></value></param>
<param><value><string>STATE</string></value></param>
</params>
</methodCall>
1. Parameter: Die Seriennummer und der Kanal des Aktors (SN:Kanal) als <string>
2. Parameter: Der Name des Datenpunkts als <string>
Da man hier tatsächlich etwas erwartet bekommt man auch eine nicht leere Antwort. Bspw.:
Code: Alles auswählen
<?xml version="1.0"?>
<methodResponse><params>
<param><value><boolean>1</boolean></value></param>
</params></methodResponse>
Der Typ des value Parameters entspricht dem des Datenpunkts. siehe setValue.
setValue
Code: Alles auswählen
<?xml version="1.0"?>
<methodCall>
<methodName>setValue</methodName>
<params>
<param><value><string>GEQ0000321:1</string></value></param>
<param><value><string>LEVEL</string></value></param>
<param><value><boolean>0.6</boolean></value></param>
</params>
</methodCall>Da die Dokumentation eigentlich für die WebUI Scriptsprache geschrieben ist, muss man die Typen noch in XML-RPC Typen umbenennen.
so wird aus:
Code: Alles auswählen
action -> <boolean></boolean>
boolean -> <boolean></boolean>
float -> <double></double>
integer -> <i4></i4>
option -> <i4></i4>2. Parameter: Der Name des Datenpunkts als <string>
3. Parameter: Der neue Wert des Datenpunkts in dem angegebenen Typ
der allerbeste Befehl ist aber
init
Code: Alles auswählen
<?xml version="1.0"?>
<methodCall>
<methodName>init</methodName>
<params>
<param><value><string>http://192.168.128.1:80/xmlrpc/demo/server/xmlrpc_server.php</string></value></param>
<param><value><string>123456</string></value></param>
</params>
</methodCall>Soll heißen: man kann sich an der CCU anmelden, mit einer speziellen ID und seiner eigenen Adresse. Jetzt meldet sich die CCU jedesmal selbst mit einem XML-RPC wenn sich etwas ändert, also wenn zB jemand das Licht einschaltet, eine Bewegung festgestellt wird oder sonst etwas passiert. Man muss also nicht die ganze Zeit nach einem Wert fragen sondern kann sich einfach darüber informieren lassen wenn sich selbiger ändert.
Es gibt XML-RPC Server für so ziemlich jede Programmiersprache und sogar als eigenständige Programme. Ich nutze hier im Beispiel den xmlrpc-php Server.
1. Parameter: Die Adresse des XML-RPC Servers bei dem sich die CCU melden soll. (IP:PORT/PFAD) PORT und PFAD sind optional sonst wird eber der Standard genutzt.
2. Parameter: Die ID mit der sich die CCU meldet. Werden wir gleich bei einem Event noch genauer sehen
Wird bspw. der Aktor mit der SN: eingeschaltet, also egal ob per angeschlossenem Taster, einem Script oder sonst irgendwie, bekommen wir (der angegebene Server) das zu geschickt:
Code: Alles auswählen
<?xml version="1.0"?>
<methodCall>
<methodName>event</methodName>
<params>
<param><value><string>123456</string></value></param>
<param><value><string>EEQ0000123:1</string></value></param>
<param><value><string>STATE</string></value></param>
<param><value><boolean>1</boolean></value></param>
</params>
</methodCall>Wichtig ist dass der Server natürlich die Methode "event" auch implementiert. Als Antwort sollten wir einfach einen leere Call zurück schicken (siehe standard Antwort in der Einleitung)
1. Parameter: Das ist die ID mit der wir uns mit init angemeldet haben
2. Parameter: Der Aktor (SN:Kanal) der eine Änderung mitteilt
3. Parameter: Der Datenpunkt den die Änderung betrifft
4. Parameter: Der neue Wert des Datenpunkts des Aktors
außer der "event" Methode ist es immer gut wenn der Server auch noch die Standardfunktionen implementiert. Es reicht ja auch einfach eine leere Antwort.
Diese "events" lassen sich natürlich wunderbar verarbeiten und zwischenspeichern, oder darauf reagieren oder ähnliches. Man sollte noch sagen das Events von unterschiedlichen Quellen unterschiedlich oft/schnell ankommen. Ein Dimmer schickt bspw. bei einer Wertänderung mehrmals wärend des dimmens seinen aktuellen Wert und stellt auch noch den WORKING Datenpunkt auf true. Außerdem schicken viele Aktoren ihren aktuellen ERROR staus mit.
owagner: bei der Wired und RF Schnittstelle (Port 2000 und 2001) bekommt man als Antwort system.multicall PRCs bei der System Schnittstelle (Port 2002) immer nur einzel Events.
So, dass war es erst mal. Ich hab mir sagen lassen dass getParamset und putParamset auch noch nützlich sind. habe diese aber selbst noch nicht genutzt. Allerdings lassen sich mit etwas coding Verstand die Funktionsbeschreibungen aus einem der Homematic Produkte lesen. Im "HomeMatic Konfigurator" den es auf der offiziellen Homepage gibt (http://www.homematic.com/index.php?id=644).
im Unterordner \www\api\interface liegen viele der XML-RPC Funktionen als tcl scripte. einfach aufmachen und mal ein bisschen lesen. bspw setvalue.tcl
in den Oberen Zeielen stehen die Parameter und ihre Bedeutung ein bisschen denken oder probieren muss man allerdings manchmal schon.
die interessante Zeile ist nach xmlrpc:
Code: Alles auswählen
checkXmlRpcStatus [catch { xmlrpc $interface(URL) setValue [list string $address] [list string $valueKey] [list $type $value] }]dann kommt die XML-RPC Funktion. hier: setValue
und danach kommen alle benötigten Parameter und deren Typen. also hier sind es 3 wie oben schon gezeigt.
bspw die adresse: [list string $address] also ein string in dem die adresse steht.
das sieht man auch beim wert: [list $type $value] der Typ ist hier eine Variable aus den bekannten Gründen (Datenpunkte haben unterschiedliche Typen).
So jetzt ist die Katze aus dem Sack. Nach dem ELV ja behauptet hat eine Schnittstellendefinition offen zu legen hatte ich mich ja darauf gefreut vielleicht noch etwas neues zu lernen und vielleicht mir diese Arbeit hier auch zu ersparen. Aber nach dem immer mehr Leute hier ins Forum strömen und nach Antworten suchen wollte ich gerne mal mein mir selbst angeeignetes Wissen mit euch teilen.
Ich hoffe dass diese sicherlich nicht vollständige Erklärung der Homematic XML-RPC Schnittstelle dem einen oder anderen helfen wird einige schöne Projekte auf die Beine zu stellen.
Ich bin natürlich für Kritik, Anregungen und Ergänzungen offen.
Viele Grüße
Daniel
