Auf der Homematic CCU2 stehen für die Integration in Fremdsysteme drei APIs zur Verfügung:
- Eine Low-Level Schnittstelle zum Zugriff auf die verbundenen Geräte auf Basis des XML-RPC-Protokolls
- Eine Schnittstelle zum Empfangen von Real-Time Events aus dem Homematic System ebenfalls auf Basis des XML-RPC-Protokolls
- Eine High-Level Schnittstelle zum Zugriff auf die verbundenen Geräte mittels einer einfacheren XML-API (zusätzliches AddOn au der Community)
Die XML-RPC Schnittstelle zum Zugriff auf Geräte
Das XML-RPC Protokoll erlaubt über XML-kodierte Kommandos das Ausführen von Befehlen auf der CCU2. Diese Befehle schalten zum Beispiel einen Aktor oder lesen des Wert eines Sensors aus. Diese Low-Level Schnittstelle greift auf die Geräte mittels der Homematic Adressen zu. Sie kennt keine Meta-Daten wie Räume, Geräte-Namen oder Ähnliches. Die Beschreibung der Details findet man am Besten hier im Forum von Homematic. Die Spezifikation von eQ3 kann man hier herunterladen.
Die XML-RPC Schnittstelle zum Empfangen von Events
Die oben beschriebene Schnittstelle liefert auch die Werte von Geräten, wenn man sie aufruft. Möchte über den Zustand eines Gerätes proaktiv informiert werden, dann gibt es eine zweite Funktion in der XML-RPC API: Man kann die CCU2 über den XML-RPC Call init dazu auffordern, selbst XML-RPC-Calls abzusetzen. Dazu muß man dann selbst einen entsprechenden Server aufbauen, der dann diese Calls entgegen nimmt.
Die XML-API
Die XML-API ist keine XML-RPC Schnittstelle, sondern eine deutlich einfachere HTTP-Schnittstelle die ebenfalls auf XML basiert. Unter dem link hier findet man die offizielle Beschreibung des Entwicklers. Diese API stammt nämlich nicht von eQ3 selbst, sondern von einem freien Entwickler der die API als Addon für die CCU gebaut hat. Diese Schnittstelle benötigt viel mweniger Calls um an die Informationen der Geräte heranzukommen. Sie liefert auch die Meta-Daten wie Räume und Gewerke. Es gibt aber keine Event-Schnittstelle und man die XML-RPC Event-Schnittstelle auch nicht von hier aus aufrufen bzw. intialisieren.
Die Integration in den girder item Manager
Für die Integration in den girder item Manager benutze ich alle drei APIs. Dafür habe ich ein iM Modul geschrieben. Beim Starten eines Modulobjekts lese ich im ersten Schritt über die XML-API die Räume und Gewerke aus, damit ich die Geräte später zuordnen kann. Danach lese ich alle verfügbaren Geräte und dann deren Werte. Hier kommt jetzt die Grundstruktur meines item Managers zum Tragen: Die items orientieren sich nicht nach den Geräten, sondern nach den Einzeleigenschaften so wie es im Blog Beitrag zum item Manager beschrieben ist. Bei Homematic heißen die Eigenschaften Datanpunkte oder datapoints. Danach lege ich für jeden Datenpunkt das dazugehörige item an inkl. sämtlicher Methoden. diese Methoden zum Setzen oder Lesen der Werte benutzen wiederum die XML-API.
Erst im letzten Schritt ruft das Modulobjekt eine Routine auf, mit der über die XML-RPC API der Event Mechanismus gestartet wird. Ab dem Moment kommen die Events-Calls als XML-RPC Call herein und müssen vom Web-Server von girder beantwortet werden. Diese Antworten werden generiert von einer servercall-Funktion in girder. Bei der Formulierung der Antwort ist darauf zu achten, dass man XML-RPC-konform antwortet. der Event-Client auf der CCU2 ist nämlich sehr empfindlich. Wenn man die eingehenden Events und Calls nicht ordentlich beantwortet, dann stellt der Prozess auf der CCU2 das Senden der Events ohne Ankündigung ein.
Fazit
Durch die hier grob beschriebene Lösung kann ich nun über die generischen item Manager Methoden die Homematic-Geräte schalten, auslesen und Events empfangen. Die Schnittstellen sind komplex aber zuverlässig wenn es einmal läuft.
Ich erwarte jetzt nicht, dass die Erklärung dieses Beitrags für Laien genügend Informationen liefert um das nachzubauen. Es geht mir vielmehr darum darzulegen wie ich es gelöst habe und dass es grundsätzlich geht. Wer mehr Informationen haben will, der kann sich gerne melden.