Via Netzwerk auf Homematic zugreifen – XML-RPC-Schnittstelle/Homematic®

0,00
Aus ELVjournal 04/2010     0 Kommentare
 Via Netzwerk auf Homematic zugreifen – XML-RPC-Schnittstelle/Homematic®

Inhalt des Fachbeitrags

PDF- / Onlineversion herunterladen

Mittels XML-RPC-Schnittstelle kann über ein Netzwerk auf Homematic Geräte zugegriffen werden. Damit lässt sich die Hausautomation in eigene Anwendungen integrieren. Dieser Artikel beschreibt die Grundlagen im Umgang mit dieser Schnittstelle.

Die Homematic®-Zentrale

Die Homematic Zentrale stellt zur Steuerung von Aktoren und Sensoren eine Kommunikationsschnittstelle bereit, die auf XML-RPC basiert. Damit ist es möglich, Funktionen der Hausautomation in eigene Anwendungen zu integrieren. Dieser Artikel beschreibt die Grundlagen und zeigt anhand zweier Beispiele die Integration von Homematic in eigene Anwendungen. Die Spezifi kation dieser Schnittstelle wurde von eQ-3 veröffentlicht und steht jetzt auf der Homematic Homepage zur Verfügung.

Grundlagen

Bild 1: Schematischer Aufbau der Homematic Zentrale
Bild 1: Schematischer Aufbau der Homematic Zentrale

Bevor die Verwendung der XML-RPC-Schnittstelle anhand von Beispielen demonstriert wird, soll beschrieben werden, was mit dieser Schnittstelle möglich ist und wie man diese einsetzen kann. Abbildung 1 zeigt den schematischen Aufbau der Homematic Zentrale. Im unteren Bereich sind die drei Schnittstellen zu sehen, über die Homematic Geräte gebundene Homematic Geräte über Port 2000 erreichen, funk basierte Komponenten über Port 2001 und die internen Geräte der Homematic Zentrale über Port 2002. Die nächste Software-Schicht innerhalb der Homematic Zentrale ist die sogenannte Logikschicht. Hier werden die Programmlogik und die Zeitsteuerung ausgeführt. Außerdem verwaltet die Logikschicht Metadaten wie die Namen von Geräten, Räume, Gewerke sowie die Favoriten. Über XML-RPC lassen sich Aktoren steuern und die Zustände von Sensoren überwachen. Einen Zugriff auf die Logikschicht erlaubt diese Schnittstelle dagegen nicht.

BidCoS-Service

Neben der Homematic Zentrale gibt es noch ein zweites Einsatzgebiet der XML-RPC Schnittstelle. Bei dem BidCoSService handelt es sich um einen Windows-Dienst, der die XML-RPC-Schnittstelle auf einem Windows-PC bereitstellt. Dadurch lassen sich Homematic Geräte auch über die Home- Matic-Konfigurations-Adapter HM-CFG-LAN bzw. HM-CFGUSB ansprechen. Der BidCoS-Service ist Bestandteil der User-Software zum Homematic Konfigurations-Adater und kann von der Home-Matic-Homepage in der Rubrik Updates heruntergeladen werden.

Bild 2: Konfigurationsdatei des BidCoS-Service
Bild 2: Konfigurationsdatei des BidCoS-Service

Bevor der BidCoS-Service verwendet werden kann, muss dieser konfiguriert werden. Das geschieht über die Datei bidcos.conf, die sich nach erfolgreicher Installation im Anwendungsdaten- Verzeichnis befindet. Unter Windows XP ist das meist „C:\Dokumente und Einstellungen\All Users\ Anwendungsdaten\Bidcos-Service“, bei Windows Vista und Windows 7 ist dies „C:\ProgramData\BidCoS-Service“. Abbildung 2 zeigt den Aufbau der Datei bidcos.conf. Der Parameter „Listen Port“ legt fest, über welchen Port der Bid- CoS-Service die XML-RPC-Schnittstelle bereitstellt. Üblicherweise ist hier derselbe Port wie das BidCoS-RF-Interface auf der Homematic Zentrale eingestellt. Für jeden Homematic Konfigurations-Adapter, der vom Bid- CoS-Service verwaltet werden soll, existiert in der Konfigurationsdatei ein Interface-Abschnitt. Dabei sind diese Abschnitte von 0 beginnend durchnummeriert. Sie enthalten die Seriennummer, den Zugriffscode, eine kurze Beschreibung sowie die IP-Adresse des jeweiligen Homematic Konfigurations-Adapters. Dabei ist die Angabe der IP-Adresse optional und kann weggelassen werden.

Beispiel-Programme

Im Folgenden wird die Verwendung der XML-RPC-Schnittstelle anhand zweier Beispiele demonstriert. Als Plattform für die Implementation wurde dabei .Net gewählt. Beide Beispiele sind komplett in C# geschrieben. Sie stehen jeweils als Visual-Studio-2008-Projekt mit vollständigem Quelltext im Downloadbereich zur Verfügung. Als XML-RPC-Bibliothek wurde XML-RPC.NET von Charles Cook gewählt. Diese Bibliothek steht unter der MIT-X11-Lizenz und darf somit auch in kommerziellen Projekten verwendet werden. Mit dieser Bibliothek können XML-RPC-Clients besonders elegant implementiert werden. Wie später gezeigt wird, ist für die Generierung eines Proxy-Objekts lediglich die Angabe einer Schnittstelle nötig. Schließlich zeichnet sich XML-RPC.NET durch eine sehr gute Dokumentation aus. Eine ausführliche Liste verfügbarer XML-RPC-Bibliotheken für eine Vielzahl anderer Programmiersprachen ist auf der XML-RPC-Homepage zu finden.

Homematic Geräte auflisten

Bild 3: Beispielprogramm zum Auflisten der Homematic Geräte
Bild 3: Beispielprogramm zum Auflisten der Homematic Geräte

In diesem Beispiel geht es darum, alle verfügbaren Homematic Geräte aufzulisten (Abbildung 3). Der vollständige Quelltext des Programms steht im Downloadbereich zur Verfügung. Nachdem die URL zur Home- Matic-Zentrale oder zum BidCoS-Service eingegeben wurde und der „Verbinden“-Button aktiviert wird, listet die Anwendung alle verfügbaren Homematic Geräte in einer baumartigen Ansicht auf. Wählt der Anwender ein Gerät aus, werden ihm in der Detailansicht nähere Informationen über das Gerät und seine Kanäle angezeigt. Dazu stellt die XML-RPCSchnittstelle die Methode listDevices zur Verfügung:


Die Methode listDevices liefert ein Array von Gerätebeschreibungen. Dabei unterscheidet die XML-RPC-Schnittstelle nicht zwischen Geräten und Kanälen, wie es beispielsweise innerhalb der Homematic Web-UI der Fall ist. Innerhalb der XML-RPC-Schnittstelle wird daher von logischen Geräten gesprochen, die entweder physische Geräte oder Kanäle sein können. Eine Gerätebeschreibung wird durch die Klasse Device- Description abgebildet. In der Beispielanwendung werden nicht alle Elemente dieser Struktur verwendet. Eine vollständige Liste aller Strukturelemente ist in der Spezifikation der XML-RPC-Schnittstelle zu finden. Die wichtigsten Elemente in der DeviceDescription sind „ADDRESS“ und „TYPE“. Dabei enthält „ADDRESS“ die Seriennummer des logischen Geräts. Dieser Wert wird bei jeder Kommunikation benötigt. Das Element „TYPE“ enthält für physische Geräte deren Kurzbezeichnung und für Kanäle den Kanaltyp. Damit in der Beispielanwendung die Kommunikation mit der XML-RPC-Schnittstelle realisiert werden kann, wird ein geeigneter Proxy benötigt. Wie zuvor erwähnt, reicht hierfür die Definition einer Schnittstelle aus. Diese ist in Abbildung 4 dargestellt.

Bild 4: Signatur der XML-RPC-Methode listDevices
Bild 4: Signatur der XML-RPC-Methode listDevices

In der baumartigen Ansicht werden nur physische Geräte dargestellt. Kanäle sollen dort nicht zu finden sein, sondern nur in der Detailansicht auftauchen. Um die Unterscheidung zwischen Gerät und Kanal treffen zu können, wird das Element „PARENT“ verwendet (Abbildung 5).

Bild 5: Die Klasse DeviceDescription
Bild 5: Die Klasse DeviceDescription
Bild 6: Proxy-Objekt instanziieren und Geräteliste abrufen
Bild 6: Proxy-Objekt instanziieren und Geräteliste abrufen

Dies gehört zu den obligatorischen Elementen, die in jeder DeviceDescription enthalten sein müssen. Bei Kanälen enthält „PARENT“ die Seriennummer des übergeordneten Geräts, bei Geräten ist das Element jedoch leer. Abbildung 6 zeigt die Verwendung des Proxys und das Auflisten der Homematic Geräte. Im Gegensatz zu Abbildung 6 verwendet die Beispielanwendung ein Text-Eingabefeld für die URL des Proxys.

Homematic Geräte schalten

Bild 7: Homematic Geräte schalten
Bild 7: Homematic Geräte schalten

In diesem Beispiel geht es darum, Homematic Geräte zu schalten und deren Zustand abzufragen (Abbildung 7). Wie im vorangegangenen Beispiel muss zunächst die URL zur Homematic Zentrale bzw. dem BidCoS-Service eingegeben werden. Nach dem Verbinden werden jedoch nicht alle Geräte in der baumartigen Ansicht dargestellt. Lediglich schaltbare Kanäle sind dort zu finden. Wählt der Anwender einen dieser Kanäle aus, wird dessen Zustand durch eine Glühbirne symbolisiert. Er hat nun die Möglichkeit, den ausgewählten Kanal zu schalten. Zusätzlich wird der aktuelle Zustand des ausgewählten Kanals mit Hilfe eines Intervall- Timers überwacht. Im Gegensatz zur Auflistung der Homematic Geräte werden hier ausschließlich schaltbare Kanäle dargestellt. Um diese zu erkennen, werden die Elemente „TYPE“ sowie „PARENT_ TYPE“ ausgewertet. Das Element „PARENT_TYPE“ enthält die Kurzbezeichnung des übergeordneten Homematic Geräts. Bei Schaltaktoren ist das zum Beispiel „HM-LC-Sw1- Pl“ oder „HM-LC-Sw4-Pl“. Über das Element „TYPE“ werden nun die schaltbaren Kanäle identifiziert. Diese sind vom Typ „SWITCH“. Im nächsten Schritt wird das IHomematicProxy-Interface um die Methoden GetValue und SetValue erweitert (siehe Abbildung 8).

Bild 8: Die Schnittstelle IHomematicProxy, erweitert um die Methoden GetValue und SetValue
Bild 8: Die Schnittstelle IHomematicProxy, erweitert um die Methoden GetValue und SetValue
Bild 9: Funk-Schaltaktor schalten
Bild 9: Funk-Schaltaktor schalten

Mit diesen Methoden können Datenpunkte eines Kanals gelesen bzw. beschrieben werden. Eine vollständige Auflistung aller Datenpunkte kann auf der Homematic Homepage heruntergeladen werden. Der Zustand des Homematic Schaltaktors verbirgt sich hinter dem Datenpunkt „STATE“. Abbildung 9 demonstriert, wie der Zustand eines solchen Schaltaktors gelesen bzw. geschrieben wird. Dabei ist „DEQ0010755:1“ die Seriennummer des betreffenden Kanals.

Fazit

In diesem Artikel wurde die XML-RPC-Schnittstelle zur Steuerung von Homematic Geräten vorgestellt. Es wurde gezeigt, wie mit Hilfe dieser Schnittstelle einfache Aufgaben, wie das Auflisten sowie das Schalten von Geräten, realisiert werden können. Hiermit stehen dem versierten Anwender viele Möglichkeiten offen, um Homematic in eigene Anwendungen zu integrieren.

Links:

Homematic Homepage
www.homematic.com

Usersoftware zum Homematic Konfigurations-Adapter
www.homematic.com/index.php?id=644&L=0

Technische Dokumentationen zu Homematic
www.homematic.com/index.php?id=156

XML-RPC-Homepage www.xmlrpc.com

Liste verschiedener XML-RPC-Bibliotheken
www.xmlrpc.com/directory/1568/implementations

XML-RPC.NET-Bibliothek www.xml-rpc.net

Projekte im Downloadbereich
www.elv.de/output/controller.aspx?cid=588

Fachbeitrag als PDF-Download herunterladen

Inhalt

Sie erhalten den Artikel in 1 Version:

pdf  als PDF (5 Seiten)

Sie erhalten folgende Artikel:
  • Via Netzwerk auf Homematic zugreifen – XML-RPC-Schnittstelle/Homematic®


Hinterlassen Sie einen Kommentar:
(Anmeldung erforderlich)
  Name
  E-Mail