XML-API

Version 2.3

Dieses AddOn stellt Dir einige zusätzliche Skripte auf der HomeMatic-Zentrale zur Verfügung, die teilweise auch von 3rdParty-Apps benötigt werden. Über einfache HTTP-Aufrufe lassen sich z.B. sämtliche Raum- oder Gewerkenamen auslesen oder den Status eines Kanals lesen bzw. setzen.

Aufruf

Nach der Installation und dem Neustart der HomeMatic-Zentrale kann die alternative Web-Oberfläche mit folgender URL aufgerufen werden:

http://<IP-DEINER-CCU>/config/xmlapi/<Skript-Name>

Der Platzhalter <IP-DEINER-CCU> ist dabei durch die IP-Adresse Deiner HomeMatic-Zentrale zu ersetzen. Für <Skript-Name> ist einer der folgenden Werte einzusetzen:

Werte auslesen

Skript-Name Beschreibung
devicelist.cgi Liste aller Geräte mit Kanälen (Enthält u.a. die Namen, Seriennummern, Gerätetypen und ID's). Wird ?show_internal=1 angehängt, werden zudem alle internen Kanäle mit aufgelistet.
functionlist.cgi Liste aller Gewerke mit Kanälen (Enthält u.a. die Namen, Seriennummern (pro Kanal) und IDs)
favoritelist.cgi Liste aller Favoriten & Benutzer. Wird ?show_datapoint angehängt, werden zusätzlich die Eigenschaften "datapoint_id" und "datapoint_type" mit aufgelistet.
mastervalue.cgi Gibt ein oder mehrere Geräte mit den entsprechenden Namen und Werten zurück. Die IDs der gewünschten Geräte werden dabei über ?device_id= übergeben und ggf. via Komma getrennt. Über &requested_name= können die zurückgegebenen Werte zudem eingeschränkt werden (z.B. "TEMPERATURE_LOWERING").
programlist.cgi Liste aller Programme (Enthält u.a. die Namen, Beschreibungen und IDs)
protocol.cgi Gibt das System-Protokoll zurück. Wird der Parameter ?clear=1 übergeben, wird stattdessen das Protokoll gelöscht.
roomlist.cgi Liste aller Räume mit Kanälen (Enthält u.a. die Namen und IDs)
rssilist.cgi Liste aller Geräte mit den jeweils aktuellen Signalstärken.
scripterrors.cgi Gibt die letzten 10 Zeilen aus dem Error-Log für Skripte zurück. Die Logdatei ist unter "/var/log/messages" als Ganzes zu finden.
state.cgi Gibt die Kanäle und Stati eines oder mehrerer Geräte zurück. Die IDs der gewünschten Geräte werden dabei über ?device_id= übergeben und ggf. via Komma getrennt. Über &channel_id= kann optional der gewünschte Kanal und über &datapoint_id= optional der gewünschte Datenpunkt übergeben werden.
statelist.cgi Liste alle Geräte mit Kanälen und aktuellen Werten (enthält u.a. die Namen, Datenpunkte (z. B. LowBatt), aktuelle/alte Werte (Dimmer)). Über ?ise_id= können die gewünschten Geräte-IDs übergeben werden. Wird zudem &show_internal=1 übergeben, werden zudem die internen Eigenschaften mit aufgelistet.
systemNotification.cgi Liste aller aktuellen Servicemeldungen.
systemNotificationClear.cgi Löscht alle Servicemeldungen, deren Bestätigung auch möglich ist.
sysvarlist.cgi Liste aller Systemvariablen mit dazugehörigen Werten, Wird ?text=true übergeben, werden die Werte stattdessen in der Eigenschaft "value_text" zurückgegeben.
sysvar.cgi Liefert im Gegensatz zu der vorigen Funktion den Wert nur einer Systemvariable zurück. Diese ist mit ?ise_id= zu übergeben.

Werte schreiben

Skript-Name Beschreibung
mastervaluechange.cgi Setzt neue Werte für ein oder mehrere Geräte. Diese werden über ?device_id= ggf. via Komma getrennt übergeben. Über &name= wird der Name der Eigenschaft und über &value= der gewünschte Wert übergeben. (Beispiel: ?device_id=1234,5678&name=TEMPERATURE_LOWERING&value=17.0,22.5)
programactions.cgi Ermöglicht das Setzten der Programmeigenschaften "Aktiv" bzw. "Sichtbar". Die ID des entsprechenden Programms wird dabei mit ?program_id= übergeben. Die zusätzlichen Parameter "&active=" bzw. &visible=" setzen dann die gewünschten Eigenschaften. Hierbei sind die möglichen Werte entweder "true" oder "false".
statechange.cgi Ändert einen Wert bzw. mehrere Werte eines oder mehrerer Kanäle. Die Kanäle werden dabei ggf. durch Komma getrennt mittels ?ise_id= übergeben. Die zu ändernden Werte sind via "&new_value" ebenfalls durch Komma getrennt zu übergeben.

Sonstiges

Skript-Name Beschreibung
runprogram.cgi Startet ein Programm mit der angegebenen ID. Diese wird mit ?program_id= übergeben.
version.cgi Gibt die aktuelle Version des XML-API AddOns zurück.

Sämtliche Skripte erzeugen daraufhin eine XML-Struktur mit den entsprechenden Daten (Geräte, Gewerke, ...) die z. B. von einem externen Programm ausgewertet werden könnte. Jeder XML-Listeneintrag enthält zudem einen Timestamp der letzten Änderung sowie die CCU-interne ID (ise_id) des Geräts, Kanals, ...

Diese ID wird auch benötigt, wenn man über "statechange.cgi" z.B. einen Aktor ansteuern möchte:

http://192.168.178.200/config/xmlapi/statechange.cgi?ise_id=12345&new_value=0.20

Würde hinter der "ise_id=12345" ein Dimmer stehen, würde dieser jetzt auf 20% dimmen.

Bitte beachten:

Der Aufruf an eine der hier vorgestellten Routinen erfolgt ohne voherige Anmeldung. Ist die HomeMatic-Zentrale ohne besonderen Schutz über das Internet erreichbar, kann dies ein Sicherheitsrisiko darstellen und gilt entsprechend zu beachten!

Tipps zur Installation:

Um ein AddOn auf der CCU zu installieren, ist dieses zunächst lokal herunterzuladen und dann über den Punkt "Systemsteuerung -> Zusatzsoftware" hochzuladen.

Die heruntegeladene Datei darf vor dem Einspielen nicht(!) entpackt werden. Es gibt Browser (z.B. Safari), die gezippte Dateien automatisch entpacken. Diese Funktion muss daher evtl. zunächst deaktiviert werden.

Spezifikationen
Typ: Zusatzsoftware
Autor/en: hobbyquaker
Zielgruppe: Anwender (Bastler)
Einstiegshürde: Niedrig (Mittel)
Kompatibilität: CCU1, CCU2, CCU3, RaspberryMatic
Alle Angaben ohne Gewähr!
- Code scannen, um zur Orginalseite zu gelangen -