HMCCU

Aus FHEMWiki


Clock - Under Construction.svg An dieser Seite wird momentan noch gearbeitet.


HMCCU
Zweck / Funktion
Anbindung Homematic CCU2 an FHEM
Allgemein
Typ Gerätemodul
Details
Dokumentation EN / DE
Support (Forum) HomeMatic
Modulname 88_HMCCU.pm
Ersteller zap (Forum / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!


Einführung

Übersicht

Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → HMCCUDEV und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:

  • Unterstützung der Protokolle BidCos, Wired und HM-IP
  • Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)
  • Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server
  • Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben
  • Lesen und Schreiben von CCU2 Systemvariablen
  • Ausführen von CCU2 Programmen
  • Ausführen von Homematic Scripts auf der CCU2

Die einzelnen Module haben folgende Aufgaben:

  • HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)
  • HMCCURPC: Alternativer auf Threads basierender RPC-Server
  • HMCCUDEV: Definition von FHEM Devices für Homematic Geräte
  • HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten
  • HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen

Geräte, Kanäle und Datenpunkte

Geräte in der HomeMatic CCU bestehen aus einem oder mehreren Kanälen. Ein Kanal wiederum hat einen oder mehrere Datenpunkte. Über diese Datenpunkte kann ein Gerät gesteuert oder Statusinformationen ausgelesen werden. Sofern ein Datenpunkt lesbar ist, kann er als Reading in einem HMCCUCHN oder HMCCUDEV Device dargestellt werden. Ausgehend von dieser Abbildung in der CCU kann man nun entscheiden, ob man ein CCU Gerät mit HMCCUCHN oder HMCCUDEV definiert.

Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.

Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.

Info blue.png
Im Artikel → HMCCU Best Practice gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.


Inbetriebnahme

Zu beachten

  • In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.
  • Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.
  • Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".
  • Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.
  • Seit der CCU2 Firmware 2.27.7 sind die Zugriffsmöglichkeiten auf die CCU durch eine Firewall abgesichert. Der Zugriff durch FHEM muss explizit freigeschaltet werden, da HMCCU sonst nicht korrekt funktioniert (s. nächster Abschnitt).

CCU Firewall Einstellungen

Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:

  • Menü "Einstellungen > Systemsteuerung" aufrufen
  • Button "Firewall konfigurieren" anklicken
  • Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.
  • Man kann die Rechte auf "Eingeschränkter Zugriff" belassen, muss dann aber im Feld "IP-Adressen für eingeschränkten Zugriff" die IP des FHEM-Servers oder das komplette Subnetz in Subnet-Notation angeben.

Installation

Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden 

sudo apt-get update && sudo apt-get install -y librpc-xml-perl

Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.

Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut rpcqueue geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.

Definition I/O Device

Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“. 

define d_ccu HMCCU 192.168.1.10

Falls die CCU als Software Service auf dem gleichen Rechner läuft wie FHEM, sollte bei der Definition der Paramter waitforccu angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM. Durch waitfoccu wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die 180 Sekunden sind nur ein Beispiel. Je nach Installation kann auch ein höherer Wert notwendig sein: 

define d_ccu HMCCU 192.168.1.10 waitforccu=180

Im nächsten Schritt wird der RPC-Server konfiguriert und gestartet. Zunächst werden mit dem Attribut rpcinterfaces die Schnittstellen bzw. Ports festgelegt, für die sich der RPC-Server bei der CCU2 registrieren soll. Folgende Angaben sind möglich:

  • BidCos-RF
  • BidCos-Wired
  • HmIP-RF
  • CUxD
  • Homegear
  • VirtualDevices

Wichtig! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei rpcinterfaces nicht angegeben werden, da sonst der RPC-Server nicht startet.

RPC Server konfigurieren

Nach den Schnittstellen wird festgelegt, ob der interne (Default) oder der externe RPC-Server verwendet werden soll. Der externe RPC-Server (Modul HMCCURPC) hat den Vorteil, dass er deutlich schneller auf CCU Ereignisse reagiert, daher ist diese Variante zu bevorzugen. Der verwendete RPC-Server wird mit dem Attribut ccuflags festgelegt.

Interner RPC-Server Bei Verwendung des internen RPC-Servers kann mit dem Attribut rpcqueue das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut rpcinterval legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für rpcinterval legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest: 

attr d_ccu ccuflags intrpc
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices
attr d_ccu rpcqueue /tmp/ccuqueue
attr d_ccu rpcinterval 5

Externer RPC-Server Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden: 

attr d_ccu ccuflags extrpc
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices

RPC-Server starten Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut rpcserverport) geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.

Der eigentliche Startbefehl sieht so aus: 

set d_ccu rpcserver on

Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert. Anschließend sollte man noch das Attribut rpcserver auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird: 

attr d_ccu rpcserver on

Vorgaben für Client Devices

Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:

Attribut in HMCCU Vorgabe für Attribut in
HMCCUDEV/HMCCUCHN		 Default Bedeutung
ccudef-hmstatevals hmstatevals true):unreachable;^LOW_?BAT!(1|true):warn_battery' Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.
ccudef-readingfilter ccureadingfilter .* Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden
ccudef-readingname ccureadingname Kein Default Ändert den Namen von Readings und/oder ergänzt neue Readings
ccudef-substitute substitute Kein Default Ersetzt Datenpunktwerte vor der Speicherung in Readings.

Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl set defaults für das I/O Device angewendet werden kann. Dabei werden die Attribute ccudef-* auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.

Wichtig! Bei der Ausführung von set defaults für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ccureadingfilter eine Liste der zusätzlich benötigten Datenpunkte definiert werden.

Synchronisation mit der CCU

Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl get devicelist liest alle Geräte aus der CCU. Er sollte immer ausgeführt werden, wenn sich an einer Gerätedefinition in der CCU etwas geändert hat, z.B. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.

Der Befehl get update liest die Datenpunkte aller in FHEM definierten HMCCUDEV und HMCCUCHN Devices aus der CCU und aktualisiert alle Readings aller Client Devices.

Autocreate von Client Devices

HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl get devicelist mit folgender Syntax aufgerufen: 

get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]

Der Parameter dev-expr spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden. Folgende Options sind möglich:

  • t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).
  • p=<prefix> - Der Text prefix wird den Namen der neuen FHEM Devices vorangestellt.
  • s=<suffix> - Der Text suffix wird an die Namen der neuen FHEM Devices angehängt.
  • f=<format> - Mit format kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.
  • defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.
  • duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.
  • save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.

An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.

Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert. 

get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic

Verwaltung von Default Attributen

HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl set defaults definiert werden. Der Befehl get defaults zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.

Anzeigen der Gerätetypen mit Default Attributen

Mit dem Befehl get defaults im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.

Default Attribute exportieren und importieren

Der Befehl get exportdefaults schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl set importdefaults in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen: 

get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt

... Datei /opt/fhem/hmccu_defattr.txt editieren ...

set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt

Beim Ausführen des Befehls set defaults in einem Client Device haben die benutzerdefinierten Attribute Priorität.

Benutzerdefinierte Attribute löschen

Mit dem Befehl set cleardefaults werden alle mit set importdefaults importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.

Weitere Funktionen des Moduls HMCCU

Lesen und Ändern von CCU2 Systemvariablen

Systemvariablen in der CCU2 können mit den Befehlen get vars und set var gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl set var eine neue Variable in der CCU2 anzulegen. Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl get vars akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.

Beispiel: Lesen aller Systemvariablen, die mit A beginnen: 

get d_ccu vars A.*

Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5: 

set d_ccu var Temperatur 20.5

Ausführen von CCU2 Programmen

Ein in der CCU2 hinterlegtes Programm kann mit dem Befehl set execute ausgeführt werden. Einziger Parameter des Befehls ist der Name des Programms. Es spielt keine Rolle, ob das Programm in der CCU2 aktiv oder inaktiv ist.

Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen: 

set d_ccu execute Schalter_Ein

Aggregation von Gerätezuständen (ab 3.6)

Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:

  • Wieviele und welche Geräte haben einen niedrigen Batteriestand?
  • Wieviele und welche Fenster sind geöffnet?

Für die Beantwortung dieser Fragen stellt HMCCU einige Befehle und Attribute bereit. Die Ergebnisse werden in Form von Readings im I/O Device bereitgestellt:

  • Präfix_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.
  • Präfix_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.
  • Präfix_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.
  • Präfix_state - Ergebnis der Aggregationsregel (if oder else Wert).

Aggregationen werden automatisch bei Änderung von Readings neu berechnet. Alternativ kann mit dem Befehl get aggregation eine Aggregation explizit durchgeführt werden. Als Parameter wird der Name der Aggregationsregel oder "all" für alle Aggregationen übergeben: 

get <io-dev> aggregation {all|<name>}

Die Konfiguration der Aggregationen erfolgt mit Hilfe von Regeln, die über das Attribut ccuaggregate definiert werden. Dabei werden mehrere Regeln durch ein Semikolon und optional ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:

  • name:<Name> - Legt den Namen einer Aggregation fest.
  • filter:{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:
    • name: FHEM Device Name
    • alias: FHEM Device Alias
    • group: FHEM Device group Attribut
    • room: FHEM Device room Attribut
    • type: Homematic Gerätetyp
  • read:<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).
  • if:{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:
    • any: Regel greift, wenn das Reading mindestens eins der über Filter selektierten FHEM Devices den Wert Value hat.
    • all: Regel greift, wenn die Readings aller der über Filter selektierten FHEM Devices den Wert Value haben.
  • else:<Value>
  • prefix:{RULE|<Text>} - Legt das Präfix für die Readings fest, die das Ergebnis einer Aggregation beinhalten wobei "RULE" für den Namen der Aggregationsregel steht.
  • coll:{NAME|<Attribute>}[!<Default>] - Legt fest, welches Attribut der FHEM Devices, die in die Aggregation einbezogen werden, in das _list Reading aufgenommen werden, sofern sie die if Bedingung erfüllen. Dabei entspricht "NAME" dem FHEM-Devicename. Der optionale Parameter Default legt den Inhalt des _list Readings fest, wenn keines der FHEM Devices die if Bedingung erfüllt. Voreingestellt ist "no match".

Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"): 

attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias

Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer): 

battery_count: 50
battery_list: Fenster Bad,Fenster Wohnzimmer
battery_match: 2
battery_state: yes

Ausführen von Homematic Scripts

Mit dem Befehl set hmscript kann ein beliebiges Homematic Script an die CCU2 zur Ausführung gesendet werden. Wenn das Script zeilenweise Daten im Format "Parameter=Value" zurück gibt, werden diese als Readings mit dem Namen Parameter" im I/O Device gespeichert.

Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl get vars): 

object osysvar;
string ssysvarid;
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())
{
   osysvar = dom.GetObject(ssysvarid);
   WriteLine (osysvar.Name() # "=" # osysvar.Value());
}

Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden: 

set d_ccu hmscript /opt/fhem/sysvars.scr
Abgerufen von „http://wiki.fhem.de/w/index.php?title=HMCCU&oldid=22906“