PRTG und HomeMatic

Die HomeMatic-Serie von EQ3 ist für viele "Selbstbauer" eine oft genutzte Plattform zur Automatisierung von Aufgaben. Was liegt da näher, auch diese Sensoren z.B.: per PRTG auszulesen und zu visualisieren. Die Komponenten werden von EQ3 entwickelt und über verschiedene Versandhändler, (elv.de, Conrad.de, notebooksbilliger.de u.a.) versendet. Es gibt von EQ3 noch weitere Produkte wie die RWE SmartHome-Serie oder die Telekom als auch die FS20 Serie, die ähnlich aussehen aber leider nicht zueinander kompatibel sind.

Entsprechend kombiniert können Firmen mit einer CCU2 (ca. 100€) und ein paar verteilten Sensoren (ca. ca. 30€/Stück) sehr günstig und ohne weitere Verkabelung eine kleine Serverraumüberwachung (Temperatur, Feuchtigkeit, Energie, Zutrittsmeldung) aufbauen.

Zugang zur HomeMatic per XML-API

Ich beschränke mich hier auf die CCU2-Zentrale, welche per IP im Netzwerk zu erreichen ist. Die HomeMatic hat eine eingebaute XML-API, die von EQ3 auch dokumentiert und veröffentlicht ist:

HomeMatic XML-RPC-Schnittstelle
http://www.eq-3.de/Downloads/PDFs/Dokumentation_und_Tutorials/HM_XmlRpc_V1_502__2_.pdf
http://www.homematic-inside.de/software/xml-api

Allerdings sind das keine einfachen HTTP-Get, Befehle, sondern auf XMLRPC aufsetzende Kommunikationen, die mir aktuell etwas zu "schwer" sind. Interessanter ist da schon das Add-on XML-API, welches nachinstalliert werden kann und über einfache HTTP-GET die Daten liefert. Natürlich sind damit bestimmte Dinge im Gegensatz zur XMLRPC-API nicht möglich. Aber das Auslesen von Werten reicht mir für die Anbindung an PRTG. Auf http://www.homematic-inside.de/software/Add-ons/item/xmlapi wird die Installation kurz beschrieben. Sie müssen das Add-on manuell aus dem Internet herunterladen (http://www.homematic-inside.de/software/xml-api) und dann über die WebUI als Zusatzsoftware installieren. Nach einem Neustart der CCU können Sie dann mit einem HTTP-GET schon eine erste Datei bekommen.

Achtung: Die XML-API sieht keine Anmeldung oder andere Legitimation des Zugriffs vor. Stellen Sie die CCU also nie ungesichert ins Internet und selbst "intern" sollten Sie ein Auge darauf werfen, wer sich mit ihrem Netzwerk verbindet. Es ist immer wieder interessant z.B. auf einer Fritz!Box zu sehen, wie sorglos Kinder den WiFi-Key an Freunde weiter geben. Wohl dem dessen Wifi-Router ein Gäste-WLAN anbieten kann.

Wer sich die Mühe macht und das tar.gz-File z.B. mit 7-Zip extrahiert, sieht alle Dateien der API. Über "http://[CCU IP]/config/xmlapi/info.html" ist sogar eine kleine Beschreibung "an Bord".

Für die PRTG-Nutzung starten wir erst mal mit einem Überblick über alle Geräte. Das geht per Powershell recht einfach

Invoke-WebRequest http://CCU2/config/xmlapi/statelist.cgi

StatusCode        : 200
StatusDescription : OK
Content           : <?xml version="1.0" encoding="ISO-8859-1" ?><stateList><device name='HM-ES-PMSw1-Pl KEQ0970252'
                    ise_id='1238' unreach='false' sticky_unreach='false' config_pending='false' ><channel
                    name='HM-ES-PMSw1-...
RawContent        : HTTP/1.1 200 OK
                    Access-Control-Allow-Origin: *
                    Transfer-Encoding: chunked
                    Content-Type: text/xml
                    Date: Tue, 01 Jan 2019 18:30:06 GMT
                    Server: lighttpd/1.4.31

                    <?xml version="1.0" encoding="ISO-8...
Forms             : {}
Headers           : {[Access-Control-Allow-Origin, *], [Transfer-Encoding, chunked], [Content-Type, text/xml], [Date,
                    Tue, 01 Jan 2019 18:30:06 GMT]...}
Images            : {}
InputFields       : {}
Links             : {}
ParsedHtml        : mshtml.HTMLDocumentClass
RawContentLength  : 37976

Hier muss ein 200OK ankommen und im "RawContent" ist der Anfang der XML-Struktur zu sehen. Sie können natürlich auch direkt den Browser nehmen. In meinem Beispiel sehen Sie, dass ich an der CCU2 z.B. einen Funkschalter mit Energiemessung habe, der mit mehreren Kanälen präsent ist. Das Device ist einmal mit der ID "1237" vertreten, aber auch jeder Channel hat eine eigene ID. Hier die 1272, der weitere "Datapoints hat. Das gleiche gilt für den Raumsensor 1301 der als Channel 1331 die Werte Temperatur (ise_id=1333) und Feuchtigkeit (ise_id=1332) liefert.

Über die IDs der "Device" und "Channel" kann man auch direkt eine gefilterte Ansicht generieren, wenn etwas abweichende URLs genutzt werden.

http://192.168.178.9/config/xmlapi/state.cgi?device_id=1237
http://192.168.178.9/config/xmlapi/state.cgi?channel_id=1272
http://192.168.178.9/config/xmlapi/state.cgi?datapoint_id=1277

Die direkte Abfrage des Datapoint wäre zwar mit  http://192.168.178.9/config/xmlapi/state.cgi?datapoint_id=xxxx möglich, aber liefert dann nur den Wert:

Damit fehlen mir die anderen Angaben zum Typ, Beschreibung etc. Und wenn eine Gruppe mehrere Sensoren enthält, sind viel mehr HTTP-Anfragen erforderlich. für die Geschwindigkeit der Abfrage scheint es aber keinen unterschied zu machen, ob man sich die komplette XML holt und dann clientseitig filtert oder nur die gewünschten ID für eine Teilmenge. Im Hinblick darauf, dass man vielleicht die Werte verschiedener HomeMatic-Datapoints in einer PRTG-Grafik zusammenfassen will, werde ich wohl die komplette XML beziehen, z.B. eine Liste aller Geräte mit ihrem Batteriestatus oder eine Übersicht der Temperaturen verschiedener Räume.

Tiefere XML Analyse

Ehe man eine Dateninformation verarbeitet, sollte man möglichst genau wissen, was vorkommen kann und was man sinnvoll verarbeiten kann. Da das "Device" und der "Channel" als Gruppierung aufgefasst werden kann, ist der Blick auf den einzelnen "datapoint" interessant. Nicht jedes Gerät hat hier alle Werte und Daten. Hier ein Versuch die XML-Dateien, die ich bislang hatte zu parsen. Die Felder "ise_id" (eindeutige ID), "timestamp" und "name" lasse ich zur Übersichtlichkeit weg.

Gerät Type Vvalue Vvaluetype Vvalueunit

Heizungsregler

TEMPERATURE

19.200000

4

°C 

Heizungsregler

HUMIDITY 

53

16

%

Heizungsregler

LOWBAT 

false
true

2

 

Heizungsregler

CONFIG_PENDING 

false
true 

2

 

Heizungsregler

STICKY_UNREACH 

false
true 

2

 

Heizungsregler
Funksteckdose mit Messung 

UNREACH

false
true

2

 

Heizungsregler

SETPOINT

13.000000

4

°C  

Heizungsregler

ADJUSTING_COMMAND

0

16

 

Heizungsregler

ADJUSTING_DATA

0

16

 

Heizungsregler

RSSI_DEVICE

1

8

 

Heizungsregler

RSSI_PEER

187

8

 

Funksteckdose mit Messung

ENERGY_COUNTERENERGY_COUNTER

123123.200000

4

Wh

Funksteckdose mit Messung

POWER

194.000000

4

W

Funksteckdose mit Messung

CURRENT

974.000000

mA

Funksteckdose mit Messung

VOLTAGE

227.500000

V

Funksteckdose mit Messung

FREQUENCY

50.0300000

4

Hz

Funksteckdose mit Messung

UPDATE_PENDING

false

2

 

Funksteckdose mit Messung

DUTYCYCLE

false

2

 

weitere folgen

 

 

 

Die Parameter unreach="false" sticky_unreach="false" config_pending="false" gibt es auch am Device. Leider konnte ich noch nicht sehen ob diese Werte sich von den Werten am Datapoint unterscheiden. Der Value-Type scheint relativ klar zu sein:

2 = boolean
4 = Realzahl absolut
8 = integer absolut
16= integer relativ (?)

Andere Werte habe ich noch nicht ermittelt:

Wenn Sie mögen, können Sie mir ja ihre XML-Datei mit einer kurzen Beschreibung der Sensoren mal zusenden. Im Code des Add-on sieht man auch nur, dass es die Werte von der CCU übernimmt und einfach anders formatiert.

HomeMatic XML per PowerShell abholen

Leider stimmt das Format der HomeMatic-XML nun so gar nicht mit dem Format überein, welches ein PRTG:Custom Sensor erwartet. Aber ich nutze sowieso einen PRTG-Custom Sensor, um die Daten per HTTP-GET zu Laden, da ist das umbauen auch kein Hexenwerk mehr. Auf PS HTTPClient habe ich schon für PowerShell 2.0 die verschiedenen Optionen zum Abrufen einer Information per HTTP beschrieben. Der einfachste Weg ist folgender:

try {
  $webclient = new-object System.Net.WebClient
  [xml]$ccudata = $webclient.DownloadString("http://192.168.178.9/config/xmlapi/statelist.cgi")
}
catch {
  write-host "Unable to retrieve or parse data"
}

Die Ergebnisse muss ich dann natürlich parsen, filtern und im PRTG-konformen Format ausgeben. Als Programmierer muss ich nun überlegen, was ich machen will. Ich kann natürlich die komplette XML parsen und so umsetzen, dass PRTG in einem Abwasch alle Channels mit allen Datapoints erfasst. Das wäre dann hinsichtlich der PRTG-Lizenzen "optimiert" da man mit nur einem Sensor die komplette HomeMatic Umgebung erfassen könnte. Allerdings kann ein PRTG-Sensor nur bis zu 100 Channels haben. Und unübersichtlich wird es auch.

Seit 2015 kann die PRTG Freeware bis zu 100 Sensoren erfassen. Daher ist die Filterung nach Device für die meisten Installation aus meiner Sicht die beste Option. Man kann dann immer noch die Werte mehrere Channels unterschiedlicher Devices mit einem "Sensor Factory Sensor" zusammenfassen. Und wem es nicht reicht, kann das PowerShell-Script ja auch auf eigene Bedürfnisse anpassen.

PRTG Sensor für HomeMatic

Ich habe wieder mal per PowerShell ein Skript erstellt, welches per HTTP die Daten von der CCU (bei mir eine CCU2 mit installiertem XML-API Add-on) abholt und für PRTG entsprechend umformatiert. Wie üblich gibt das Script alle Debug-Ausgaben auf der Console aus. PRTG ist ja so geschickt erst ab dem "<prtg>" die Ergebnisse zu lesen. Einem Aufruf auf der Kommandozeile steht dem also nichts entgegen:

Ich hatte erst eine Version 1 entwickelt, die direkte die XML-Datei von der CCU eingelesen hat und in einem Sensor für jeden Datenpunkt einen "Channel" angelegt hat. Es hat sich aber schnell gezeigt, dass die Anzeige des Channel-Namens und vor allem die Anzahl der Channels auf einer CCU diesen Sensor unpraktisch werden lassen. Hier mal ein Beispile

Die Zahlen waren zwar da aber auf Dauer ist ein Sensor für alle Datenpunkte nicht elegant. Daher habe ich im April 2015 noch mal neu angefangen und die Konfiguration in eine XML-Datei ausgelagert. In einer XML-Datei kann ich die gewünschten Datenpunkte erfassen und über einen Parameter sehr einfach aufrufen. Die Konfigurationsdatei sieht z.B.so aus:

<prtg-homematic2>
  <ccuip>192.168.178.9</ccuip>
  <cachefile>.\prtg-homematic2.cache.xml</cachefile>
  <cacheage>120</cacheage>
  <sensor name="bad">
     <channel name="Temperatur" typ="absolute" ise_id="1333" />
     <channel name="Luftfeuchte" typ="absolute" ise_id="1332" />
  </sensor>
  <sensor name="Energie">
    <channel name="Leistung" typ="absolute" ise_id="1277" />
    <channel name="Strom" typ="absolute" ise_id="1274" />
    <channel name="Spannung" typ="absolute" ise_id="1278" />
    <channel name="Frequenz" typ="absolute" ise_id="1276" />
</prtg-homematic2>

Ob das nun ein Float, Integer, Boolean kann ich aus der HomeMatic-XML dem Feld "valuetype" entnehmen und die Einheit aus "valueunit". Insofern muss nur die Datapoint-ID und natürlich die Sensorbeschriftung angegeben werden. PRTG unterscheidet zudem noch "differenzielle" und "absolute" Sensoren. Per Default nutze ich "absolut". Der Custom Sensor kann zudem nur eine CCU abfragen. Wer mehrere CCUs abfragen muss, muss eine zweite Konfigurationsdatei nutzen, kann dann aber die Sensoren unterschiedlicher CCUs nicht in einem PRTG-Sensor zusammenfassen. Wer mit einer CCU2 nicht auskommt, kann gerne das Skript selbst besser machen.

PRTG ruft das Skript auf und über einen Parameter kann spezifiziert werden, welche Gruppe von Datapoints ausgewertet wird. Die Defaults sind im Skript vorgegeben:

param (
   [string]$sensorgroup="bad",      # Group of sensors from the XML File
   [string]$configfile = "C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors\EXEXML\prtg-homematic2.xml"
)

Achtung bei der Angabe der Config-Datei. Das "Arbeitsverzeichnis" von PRTG ist 'C:\Windows\system32\'. Wer also nur einen Dateinamen angibt, muss die Datei dort anlegen. Besser ist die Angabe des kompletten Pfades.

Achtung: XML-Abfragen sind "Case Sensibel". Entsprechend müssen Sie den Parameter "sensorgroup" genauso angeben wie dieser in der XML-Datei hinterlegt ist.

Skript verbindet sich dann wie die Version 1.0 mit der in der Konfigurations-XML hinterlegten CCU2, holt die komplette XML-Struktur und pickt die in der Konfigurations-XML ausgewählten Sensoren heraus. Der lädt Sensor immer die komplette Statelist und schreibt diese in eine Cache-Datei für folgende Aufrufe. Nach der konfigurierten Zeit wird der Cache beim nächsten Aufruf aktualisiert. So können mehrere Aufrufe mit unterschiedlichen Gruppen schneller ablaufen, da Sie keine gesonderte HTTP-Anfrage mehr stellen müssen. Sie können das Skript einfach in einer PowerShell aufrufen und die Ausgaben analysieren:

PRTG wertet die Ergebnisse erst ab dem ersten "<"-Zeichen aus, so dass eine Ausgabe von Debug Infos vor den Daten unkritisch ist. Die Daten übernimmt PRTG dann in seine Datenbank und erstellt Grafiken, hier z.B. der Stromzähler

Interessant ist hier auch einmal eine 2-Tages-Ansicht der Spannung und Frequenz, die durch den Sensor auch gemessen wird, wenn der Verbraucher abgeschaltet wurde.

Die nominell 230V schwanken schon zwischen 225,8 und 241 Volt und auch die Frequenz schwankt zwischen 49,9 und 50,07Hz. Aber das ist alles im Rahmen und wie genau die Messungen sind, steht eh noch auf einem anderen Blatt.

Aber auch das Auslesen von Thermostaten ist einfach möglich. Hier am Beispiel des HomeMatic 132030 Funk-Wandthermostat, den ich aber erst ein paar Stunden mit eingebunden habe. Man kann aber schon so sehen, dass Temperaturen nur auf 0,5 Grad und die Feuchtigkeit in 1%-Schritten übermittelt werden.

 

Weitere Sensoren habe ich noch nicht eingebunden. Vielleicht kommt ja noch mal eine Wetterstation, Helligkeitsmesser o.ä. dazu. Auch habe ich schon gesehen, dass man eigene Sensoren auch über IP an die CCU2 anbinden kann. Vielleicht gelingt es mir ja mal einen Arduino per Ethernet oder WiFi an die CCU zum Datensammeln anzubinden.

Das Skript

Wenn Sie bereits eine CCU2 mit installierter die XML-API, ein paar Sensoren mit numerischen Daten und einen PC mit PRTG haben, dann fehlt ihnen nur noch das Skript mit einer Muster-XML. Das gibt es hier:

prtg-homematic2-20150502.zip
Nach dem Download nach "C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors\EXEXML" auspacken.

Am besten fordern Sie per Browser einmal die statelist.xml von ihrer CCU2 an, z.B. von http://<IP-Adresse der CCU2>/config/xmlapi/statelist.cgi, und suchen die "ise_id" der gewünschten Sensoren. Diese übertragen Sie dann in die XML-Datei mit einer Beschreibung in die gewünschte Gruppe. Sie können gerne auch weitere Gruppen anlegen.

Rufen Sie dann einfach das Script mit den verschiedenen Parametern erst einmal in einer PowerShell auf, um die grundlegende Funktion (Tippfehler etc.) zu prüfen. Danach können Sie es als Custom-Script in PRTG einbinden.

Weiterentwicklung

Leider gibt es in PRTG aktuell keine Option auch eine Aktion auszulösen. Man kann über PRTG also nicht "Schalten" Aber auch als passive Auswertung mittels der XML-API der CCU2 eröffnen sich mit PRTG ganz neue Wege für die Auswertung der Daten. Aktuell fällt mir nichts mehr ein, was ich noch besser machen könnte.

Es gibt natürlich noch "Lücken" im  Angebotsspektrum von HomeMatic, z.B. ein Geräte der Takte (S0, Wasseruhr etc.) zählt oder direkt die neuen "SmartHome"-Zähler per IR-Koppler ausliest und an die CCU2 zur Auswertung sendet. Ich habe dazu schon gesehen, dass über eine weitere Schnittstelle an HomeMatic auch Daten per IP gesendet werden können. Es wird zeit für den nächsten Winter.

Weitere Links