HomeMatic CCU2 bei ELV bestellen

XML-RPC Interface-Beschreibung

Nutzung von XML RPC, Remote Script, JSON RPC, XMLAPI

Werbung


XML-RPC Interface-Beschreibung

Beitragvon ColdFireIce » 29.07.2010, 03:04

Hallo,

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>

man muss also bei einem Funktionsaufruf einen Methodennamen (<methodName>) angeben und eine Liste mit den erwartete Parametern und Typ.
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>

sollte ein Fehler auftreten, kommt eine Fehlermeldung zurück. Also etwa wenn ein Falscher Kanal angegeben wird:
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>

Man beachte den <fault> Tag in der Antwort der immer für einen Fehler steht. Es handelt sich hier sogar um die standard Struktur für einen XML-RPC Fehler. Es wird ein "struct" also ein Struktogramm, oder heute auch besser als Object bekannt, übergeben das 2 <member> enthält. den Fehlercode (faultCode) und die Fehlerbeschreibung (faultString).
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.multicall


Eine wirkliche Schnittstellenoffenlegung würde erklären welcher Befehl was macht (ergibt sich aber oft aus dem Namen) und viel wichtiger Welche Parameter und Typen dieser Befehl benötigt.
Ich 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>

benutze ich fast nie ist auch unglaublich was die CCU da alles ausspuckt. Viel nutzloses Zeug aber wers braucht kann sich ja mal ein Ergebnis anschaun.
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>

Hiermit lässt sich ein Datenpunkt eines Aktors auslesen. Welche Datenpunkte es gibt in den verschiedenen Geräten entnimmt man ambesten der "HM_Script_Teil_4_Datenpunkte" Dokumentation von Homematic (http://www.homematic.com/index.php?id=156). Einige Beispiele wären: STATE, LEVEL, TEMPERATURE, HUMIDITY, WORKING, ERROR, VALVE_STATE, WIND_SPEED, BRIGHTNESS, MOTION... usw. eben alle die in dem genannten Dokumment als lesend gekennzeichnet sind.
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>

zurück bekommt man den Wert den der Datenpunkt des Aktors gerade hält. Wichtig ist zu sagen dass dies nicht immer der aktuelle Wert sein muss! Es ist eine Zwischenspeicherung, wenn die CCU den Aktor nicht erreicht. Bspw. senden Tür Fensterkontakte wenn keine Änderung stattfindet nur alle 24 Stunden ihren aktuelle Status. es gibt auch keine Möglichkeit eine Abfrage zu erzwingen. So kann es sein dass die CCU grade nicht an war oder ein Signal verloren ging und dadurch nicht der wirkliche Wert in der CCU zwischengespeichert wird. Dies ist allerdings bei dem meisten Homematic-installationen eher selten der Fall. Sollte aber erwähnt werden.
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>

Ein anderes Beispiel als in der Einführung aber der gleiche Effekt. Man setz einen Datenpunkt auf einen speziellen Wert. Auch hier gilt wieder welche Datenpunkte es gibt entnimmt man am besten der Dokumentation. Der Datenpunkt muss schreibenden Zugriff erlauben. Wichtig ist jetzt noch dass man auch noch den richtigen Typ mit raussucht.
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>

1. Parameter: Die Seriennummer und der Kanal des Aktors (SN:Kanal) als <string>
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>

Dieser Befehl nimmt einem nämlich die ganze Arbeit ab. Kurz gesagt er initialisiert das Event System der CCU für einen beliebigen XML-RPC Server.
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>

Wie man sieht ist dass Spiel jetzt umgedreht. Wird sind jetzt der Server und empfangen die Funktionsaufrufe.
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] }]

$interface(URL) steht so weit ich dass glaube eben für Wired, RF oder System.
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
Zuletzt geändert von ColdFireIce am 07.09.2010, 02:48, insgesamt 5-mal geändert.
ColdFireIce
 
Beiträge: 407
Registriert: 06.03.2009, 16:38
Wohnort: Karlsruhe

Re: XML-RPC Interface-Beschreibung

Beitragvon kaju74 » 29.07.2010, 10:49

Hi..

VIelen Dank für Deine ausführliche Dokumentation. So ähnlich werde ich dass dann mit evtl. ergänzenden Informationen auf meine Seite stellen - hier warte ich halt noch das okay ab, um dass auch offiziell abzusegnen.

@Admin: Diesen Artikel vielleicht in den Bereich "Tipps & Tricks" verschieben?

Gruß,
kaju
Benutzeravatar
kaju74
 
Beiträge: 1996
Registriert: 06.03.2007, 14:14

Re: XML-RPC Interface-Beschreibung

Beitragvon owagner » 29.07.2010, 10:55

Hi,

paar Anmerkungen:

-- ich meine, das getValue sehr wohl eine Anfrage an das jeweilige Gerät auslöst und erst im Falle eines Timeouts der rfd/hs485d einen gecachten Wert ausspuckt
-- ich kriege nach init von rfd/hs485 (aber NICHT pfd) immer system.multicalls mit den ganzen events. Eventuell verwendest Du eine Bibliothek, die das in einzelne Calls auflöst?
-- setParamset ist wie setValue, nur halt für Konfigurationsparameter. Der Paramer ist eine Struktur mit allen neuen Parameterwerten (wobei man nicht alle Parameter setzen muss) Damit kann man z.B. einen Thermostat auf "Auto"-Mode stellen (falls ihn jemand per Hand aus Versehen auf "Cent" o.ä. verstellt hat)

Praktisch wäre ein Wiki, um so eine Doku dann kooperativ zu ergänzen :-)

Viele Grüße,
Olli
Benutzeravatar
owagner
 
Beiträge: 1193
Registriert: 13.05.2008, 19:49

Re: XML-RPC Interface-Beschreibung

Beitragvon ColdFireIce » 29.07.2010, 12:08

owagner hat geschrieben:-- ich meine, das getValue sehr wohl eine Anfrage an das jeweilige Gerät auslöst und erst im Falle eines Timeouts der rfd/hs485d einen gecachten Wert ausspuckt


Ah ok dass kann sein. Hab ich noch nie so richtig ausporbiert. wusste nur das mit den Fensterkontakten.

owagner hat geschrieben:-- ich kriege nach init von rfd/hs485 (aber NICHT pfd) immer system.multicalls mit den ganzen events. Eventuell verwendest Du eine Bibliothek, die das in einzelne Calls auflöst?


Das wäre wohl möglich muss ich mal checken Werde das oben ergänzen.

owagner hat geschrieben:raktisch wäre ein Wiki, um so eine Doku dann kooperativ zu ergänzen :-)


Du kannst das hier ja gerne rauskopieren und in das Wiki schreiben. Hab ja schon mal gesagt dass ich kein Freund von wikis bin ;P

Viel Grüße
Daniel
ColdFireIce
 
Beiträge: 407
Registriert: 06.03.2009, 16:38
Wohnort: Karlsruhe

Re: XML-RPC Interface-Beschreibung

Beitragvon ultrah » 29.07.2010, 17:51

Hi,

danke dass du dir die Mühe gemacht hast ! Ist teilwese um einiges schlüssiger als die Doku von eQ-3 :)

zwei fragen habe ich doch noch:

- nur damit ich das richtig verstehe, über init "abonniere" ich quasi events/statusmeldung bei der ccu für einen xml-rpc server der auf meiner seite laufen muss. Mein server bekommt dann von der CCU die events gepusht, Observer-Pattern halt. richtig ?

- wie kann ich vom Benutzer angelegte Räume auslesen ?
ultrah
 
Beiträge: 309
Registriert: 08.03.2010, 14:38

Re: XML-RPC Interface-Beschreibung

Beitragvon kaju74 » 29.07.2010, 17:55

Hi.

Richtig, Du registrierst quasi ein Callback, der u.a. bei folgenden Änderungen greift:

- Komplettes Auslesen der interenen Datenstruktur (listDevices)
- Neue Geräte erkannt (newDevices)
- Status eines Aktors/Sensors/....

Dein XML-RPC Server hat ja eine IP nebst Port, den Du dem Init-Befehl mitgeben musst.

Fortan bekommst Du dann entsprechende Packages, wenn was passiert, teils als multiCall,
teils als Einzel-Events.

Gruß,
kaju
Benutzeravatar
kaju74
 
Beiträge: 1996
Registriert: 06.03.2007, 14:14

Re: XML-RPC Interface-Beschreibung

Beitragvon ColdFireIce » 29.07.2010, 19:30

Hi,

kaju hat ja deine erste Frage schon beantwortet.

zur 2.
ultrah hat geschrieben:- wie kann ich vom Benutzer angelegte Räume auslesen ?

Das geht nicht mit XML-RPC, da diese Abstraktion auf einer höheren Schicht in der CCU abgelegt wird. Soll heißen die CCU nutzt zwar auf unterster Ebene die XML-RPC Schnittstelle aber die WebUI bspw. ist darauf aufgebaut und lässt sich nur über andere Schnittstellen ansprechen.
owagner hat in diesem Post: viewtopic.php?f=26&t=4639#p28188 unter 2. das ein bisschen erklärt.
Ich habe in der Doku aber was zu Teams gelesen. Was genau damit gemeint ist weiß ich aber nicht.

Viele Grüße
Daniel
ColdFireIce
 
Beiträge: 407
Registriert: 06.03.2009, 16:38
Wohnort: Karlsruhe

Re: XML-RPC Interface-Beschreibung

Beitragvon ultrah » 29.07.2010, 21:08

danke für den hinweis, hatte den thread zu HMCompanion bisher nur überflogen.

wirklich "nett" dass es so viele schnittstellen gibt :/

d.h. ich muss für gerätenamen,räume etc die ccu über HomeMatic-Script (HM-Script) ansprechen ?
ultrah
 
Beiträge: 309
Registriert: 08.03.2010, 14:38

Re: XML-RPC Interface-Beschreibung

Beitragvon ColdFireIce » 29.07.2010, 21:47

Jep.

Das geht dann über TCL ReGa-HSS musst einfach mal hier im Forum suchen da gibts einiges dazu oder einfach HMC nutzen ;)

Daniel
ColdFireIce
 
Beiträge: 407
Registriert: 06.03.2009, 16:38
Wohnort: Karlsruhe

Re: XML-RPC Interface-Beschreibung

Beitragvon owagner » 29.07.2010, 21:53

Mit Teams werden diese Alarmgruppen bei den Rauchmeldern realisiert (alle Melder eines Teams quaken gleichzeitig los). Ob das eine weitergehende Abstraktion ist und auch für andere Geräte verwendet werden kann, k.a...
Benutzeravatar
owagner
 
Beiträge: 1193
Registriert: 13.05.2008, 19:49

Nächste

Zurück zu Entwicklung von externen Applikationen

Wer ist online?

Mitglieder in diesem Forum: 0 Mitglieder und 0 Gäste







© homematic-forum.de & Lizenzgebern. Alle Rechte vorbehalten. Alle Bilder & Texte auf dieser Seite sind Eigentum
der jeweiligen Besitzer und dürfen ohne deren Einwilligung weder kopiert noch sonstwie weiter verwendet werden.