HMCCU Best Practice

Dieser Artikel ist noch nicht an Version 5.0 angepasst

I/O Device anlegen

I/O Device definieren

Die Kommunikation zwischen FHEM und einer CCU2 erfolgt über ein Device vom Typ HMCCU. Der folgende Befehl legt ein solches I/O Device an. Dabei wird die IP-Adresse der CCU2 als Parameter angegeben:

define d_ccu HMCCU 192.168.1.100

Attribute setzen

Zunächst wird der RPC-Server konfiguriert. Im folgenden Beispiel werden BidCos, HM-IP, CUxD und Gerätegruppen (VirtualDevices) berücksichtigt. Es dürfen nur die Schnittstellen angegeben werden, die in der CCU2 auch verwendet werden.

#
# Schnittstellen
attr d_ccu rpcinterfaces BidCos-RF,CUxD,HmIP-RF,VirtualDevices
#
# Externen RPC Server verwenden
attr d_ccu ccuflags procrpc
#
# RPC-Server nach dem Start von FHEM automatisch starten
attr d_ccu rpcserver on
#
# Status anzeigen
attr d_ccu stateFormat rpcstate/state
#
# Buttons für das Starten und Stoppen des RPC-Servers anzeigen
attr d_ccu cmdIcon on:general_an off:general_aus
attr d_ccu eventMap /rpcserver on:on/rpcserver off:off/

Mit dem Befehl set d_ccu defaults werden weitere Attribute gesetzt, die das Handling von Readings in den später definierten Devices vom Typ HMCCUCHN und HMCCUDEV beeinflussen bzw. vereinfachen. Diese Attribute können natürlich auch einzeln gesetzt werden:

#
# Readings LOWBAT, LOW_BAT und UNREACH immer berücksichtigen
attr d_ccu ccudef-readingfilter ^(LOW_?BAT|UNREACH)$
#
# Readings LOWBAT und LOW_BAT in battery umbenennen, Reading UNREACH in activity umbenennen
attr d_ccu ccudef-readingname ^(.+\.)?LOW_?BAT$:battery;;^(.+\.)?UNREACH$:activity
#
# Werte von Readings durch sprechende Ausdrücke ersetzen
attr d_ccu ccudef-substitute AES_KEY!(0|false):off,(1|true):on;;LOWBAT,LOW_BAT!(0|false):ok,(1|true):low;;UNREACH!(0|false):alive,(1|true):dead;;MOTION!(0|false):noMotion,(1|true):motion;;DIRECTION!0:stop,1:up,2:down,3:undefined;;WORKING!0:false,1:true;;INHIBIT!(0|false):unlocked,(1|true):locked

Nun werden noch Aggregationen definiert. Mit dieser Funktion können bestimmte Status von Homematic Devices im I/O Device als Reading dargestellt werden (z.B. Liste der offenen Fenster, Geräte mit leerer Batterie). Um die Definition der Aggregationen bzw. der Filter einfach zu halten, sollte man sich ein Namensschema überlegen. Die folgenden Aggregationen gehen davon aus, dass alle Homematic Devices in FHEM mit "HM-" beginnen. Danach folgt die Funktion des Gerätes, z.B. KL für Klima und TF für TürFenster. Bei anderer Namensgebung sind die Filterangaben entsprechend anzupassen. Alternativ kann auch der Gerätetyp oder die Gruppe als Filter verwendet werden (s.a. Command Reference zu HMCCU). Das Attribut ccuaggregate unterstützt mehrzeilige Angaben. Im folgenden Beispiel ist nur der Attributwert angegeben. Eingabe am besten über Auswahl des Attributs ccuaggregate in der FHEM Oberfläche. Die Kommentarzeilen beginnend mit # weglassen.

#
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und bei denen das Reading battery den Wert low hat
name:battery,filter:name=^HM_.*,read:battery,if:any=low,else:ok,prefix:battery_,coll:comment!Batterien OK;
#
# Anzeige aller Geräte vom Typ HM-CC-RT-DN oder HM-TC-IT-WM-W-EU, deren Batteriespannung kleiner gleich 2.2 Volt ist
name:voltage,filter:type=(HM-CC-RT-DN|HM-TC-IT-WM-W-EU),read:BATTERY_STATE,if:le=2.2,else:0,prefix:voltage_,coll:comment!Batteriespannung OK;
#
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt und bei denen das Reading state den Wert open hat
name:lock,filter:name=^HM_TF.*,read:state,if:any=open,else:closed,prefix:lock_,coll:comment!Alle Fenster/Türen geschlossen;
#
# Anzeige aller Geräte der Gruppe Dachfenster, bei denen das Reading state den Wert open hat
name:lockroof,filter:group=Dachfenster,read:state,if:any=open,else:closed,prefix:lockroof_,coll:comment!Alle Dachfenster geschlossen;
#
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt aber nicht mit Haustuer endet und bei denen das Reading state den Wert open hat
name:lockwin,filter:name=^HM_TF.*!Haustuer$,read:state,if:any=open,else:closed,prefix:lockwin_,coll:comment!Alle Fenster/Türen geschlossen;
#
# Anzeige aller Geräte, deren Namen mit HM_KL beginnt und bei denen das Reading HUMIDITY größer gleich 60 ist
name:hummax,filter:name=^HM_KL.*,read:HUMIDITY,if:ge=60,else:0,prefix:hummax_,coll:alias!Luftfeuchte OK;
#
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und die nicht erreichbar sind
name:unreach,filter:name=^HM_.*,read:activity,if:any=dead,else:alive,prefix:unreach_,coll:comment!Alle Devices erreichbar

Mit den folgenden Attributen werden die Aggregations-Readings im I/O Device aktualisiert:

#
# Readings schreiben
attr d_ccu ccureadings 1
attr d_ccu event-on-change-reading .*
#
# Werte auf eine Nachkommastelle abschneiden
attr d_ccu stripnumber 1

Neue Geräte anlernen

Um ein neues Gerät an die CCU anzulernen und in FHEM zu nutzen, kann man wie folgt vorgehen:

1. Gerät in CCU2 anlernen
2. Im WebUI der CCU2 den Menübefehl Einstellungen → Geräte aufrufen. Das neu angelernte Gerät in der Liste suchen und nacheinander das Gerät selbst sowie die einzelnen Kanäle nach eigenen Wünschen umbenennen. Dabei sind folgende Regeln zu beachten:
   • CCU2 weit Keine Namen doppelt vergeben, z.B. darf ein Raum nicht den gleichen Namen haben wie ein Gerät.
   • Keine Umlaute verwenden.
   • Wenn möglich keine Leerzeichen verwenden (funktioniert zwar, erschwert aber das Handling in FHEM).
3. In FHEM für das I/O Device den Befehl get devicelist ausführen, um das neue Gerät in FHEM bekannt zu machen.
4. Für das I/O Device den Befehl get deviceinfo CCU2-Devicename ausführen. Die Ausgabe zeigt die für das Gerät verfügbaren Kanäle und Datenpunkte sowie die möglichen Operationen (R=Read, W=Write, E=Event) an, die ausgeführt werden können. Anhand dieser Informationen kann man entscheiden, ob man im nächsten Schritt besser HMCCUCHN oder HMCCUDEV für die weiteren Definitionen verwendet. Falls sich aus den Namen der Datenpunkte nicht ihr Verwendungszweck ergibt, findet man in der EQ3-Doku eine detaillierte Beschreibung der Datenpunkte aller Geräte.
5. Ein FHEM Device für das neue Gerät und/oder seine Kanäle definieren:
   • Das Modul HMCCUCHN verwenden, wenn lediglich ein Kanal des Geräts in FHEM eingebunden werden soll oder die Kanäle separat verwendet werden sollen (z.B. bei einem 4-fach Aktor).
   • Das Modul HMCCUDEV verwenden, wenn das komplette Gerät mit allen Kanälen in FHEM eingebunden werden soll oder bei Sonderfällen wie Rauchmeldergruppen oder virtuelle Gerätegruppen.
6. Für das neue Device in FHEM den Befehl set defaults ausführen, um einige Attribute zu setzen. Hinweis: Default-Attribute sind nicht für alle Gerätetypen verfügbar. Grundsätzlich sollten folgende Attribute gesetzt werden:
   • ccureadingfilter - Einschränkung auf die tatsächlich benötigten Datenpunkte bzw. Readings
   • ccureadingformat - Bessere Lesbarkeit der Readings durch das Format datapoint
   • event-on-change-reading bzw. event-on-update-reading - Wenn ein Schalter oder Taster über Datenpunkte wie PRESSED_xxx verfügt, sollte event-on-update-reading auf ".*" gesetzt werden. Bei allen anderen Geräten event-on-change-reading.
   • statedatapoint - Legt den Kanal und den Datenpunkt fest, über den ein Gerät oder ein Kanal geschaltet wird bzw. dessen Wert in STATE des FHEM Devices übernommen wird. Bei HMCCUCHN Devices wird nur der Datenpunkt angegeben.
   • statevals - Legt sprechende Namen für Schaltzustände fest. Die Angaben hier stehen dann als Set-Befehle zur Verfügung.
   • substitute - Ersetzt Datenpunktwerte durch Texte bevor sie in Readings gespeichert werden

Readingnames anpassen

Format von Readingnames

In HMCCUDEV und HMCCUCHN werden Readingnames aus den Kanalnamen oder den Kanaladressen sowie den Datenpunktnamen gebildet. Das Format der Readingnames kann über das Attribut ccureadingformat eingestellt werden. Die Vorgabe ist 'datapoint' Die folgende Tabelle enthält eine Übersicht der Formate:

Datenpunktname oder -adresse	ccureadingformat	Readingname
BidCos-RF.1234567:1.STATE	datapoint	1.STATE
BidCos-RF.1234567:1.STATE	datapointlc	1.state
BidCos-RF.1234567:1.LEVEL	name	MeinKanal.1.LEVEL
BidCos-RF.1234567:1.LEVEL	address	1234567.1.LEVEL

Readingnames ändern oder ergänzen

Mit dem Attribut ccureadingname können einzelne Readings umbenannt oder neue Readings als Kopie vorhandener Readings hinzugefügt werden. Die Syntax des Attributs sieht wie folgt aus:

ccureadingname Ausdruck:[+]NewReading[;...]

Der Parameter Ausdruck gibt den Teil eines Readingnames an, der ersetzt werden soll. Mit NewReading wird der Name des zusätzlichen Readings (führendes '+') oder der Ersetzungstext für den vorhandenen Readingname festgelegt. Beispiele:

Readingname alt	ccureadingname	Readingname(s) neu
1.LEVEL	LEVEL:pct	1.pct
1.LEVEL	[0-9]{1,2}\.LEVEL:pct	pct
1.LEVEL	1.LEVEL:+pct;1.LEVEL:level	pct, level
1.LEVEL	1.LEVEL:pct;1.LEVEL:level	pct

Wichtig! Die Regeln werden von links nach rechts abgearbeitet. Daher greift die 2. Regel in der letzten Zeile nicht mehr (1.LEVEL wurde zuvor durch pct ersetzt).

Readingnames zusammenfassen

Mit dem Attribut ccureadingname können auch mehrere Readings zu einem neuen Reading zusammengefasst werden. Beispiel: Ein Taster liefert je nach Dauer des Tastendrucks im Kanal 1 ein Event PRESS_SHORT oder PRESS_LONG. Normalerweise würden dabei auch zwei Readings "1.PRESS_SHORT" und "1.PRESS_LONG" entstehen. Diese beiden Readings können mit folgendem Befehl in einem Reading PRESSED zusammengefasst werden:

attr mydev ccureadingname ^1.PRESS_(SHORT|LONG)$:PRESSED

Wenn ein Taster über mehrere Kanäle (hier vier) verfügt, können auch diese zu einem einzigen Reading zusammengefasst werden:

attr mydev ccureadingname ^[1-4].PRESS_(SHORT|LONG)$:PRESSED

Readingwerte manipulieren

Readingwerte ersetzen

Mit dem Attribut substitute können Werte von Readings durch neue Werte bzw. Zeichenketten ersetzt werden. Die Veränderungen können sich auf bestimmte Datenpunkte oder alle Readings eines Devices beziehen. Die zu ersetzenden Werte werden dabei entweder durch reguläre Ausdrücke oder als Nummernbereiche angegeben.

Im folgenden Beispiel werden die Werte 1 oder true in allen Readings durch "yes" ersetzt, die Werte 0 oder false durch "no":

attr mydev substitute (1|true):yes,(0|false):no

Wenn sich mehrere Ersetzungsregeln auf den gleichen Datenpunkt beziehen oder wie im Beispiel oben für alle Datenpunkte gelten, werden sie einfach durch ein Komma getrennt aneinander gehängt. Eine Ersetzungsregel kann sich auch auf einen bestimmten Datenpunkt beziehen. Im folgenden Beispiel eines Fensterkontakts sollen die Werte des Datenpunktes STATE durch "open" bzw. "closed" ersetzt werden. Der Name des Datenpunktes wird in diesem Fall einfach durch ein Ausrufezeichen getrennt der Regel vorangestellt:

attr mydev substitute STATE!(1|true):open,(0|false):closed

Sollte ein Geräte in mehreren Kanälen identische Datenpunkte enthalten, kann dem Datenpunktnamen noch eine Kanalnummer mit einem Punkt vorangestellt werden:

attr mydev substitute 1.STATE!(1|true):open,(0|false):closed

Eine Ersetzungsregel kann sich auch auf mehrere Datenpunkte beziehen (im Beispiel ERROR und LOWBAT), die durch Komma getrennt vor dem '!' aufgelistet werden:

attr mydev substitute ERROR,LOWBAT!(1|true):yes,(0|false):no

Wenn mehrere Ersetzungsregeln definiert werden sollen, werden sie durch ein Semikolon getrennt. Im folgenden Beispiel sollen die Werte der Datenpunkte STATE und LOWBAT unterschiedlich interpretiert werden:

attr mydev substitute STATE!(1|true):open,(0|false):closed;;LOWBAT!(1|true):low,(0|false):ok

Bei Datenpunkten mit numerischen Werten wie z.B. dem Level eines Rollladenaktors kann es sinnvoll sein, Werte oder Wertebereiche zu ersetzen. Im folgenden Beispiel kann der Datenpunkt LEVEL Werte von 0-100 annehmen. Der Wert 0 soll als "closed" und der Wert 100 als "open" dargestellt werden. Alle anderen Werte als "partial":

attr mydev substitute LEVEL!#0-0:closed,#1-99:partial,#100-100:open

Zu ersetzende Nummernbereiche beginnen also immer mit einem #. Es müssen immer Bereiche angegeben werden.

In Ersetzungsregeln können auch Variablen verwendet werden. Eine Variable wird dabei im Format ${Datenpunkt} angegeben. Ein Sonderfall ist die Variable ${value}, die durch den Originalwert ersetzt wird. Beispiel: An den Wert der Luftfeuchte soll der Text "Prozent" angehängt werden:

attr mydev substitute HUMIDITY!.+:${value}%

Im zweiten Beispiel soll der Temperaturwert durch eine Ausgabe im Format T=Temperatur°, H=Luftfeuchte% ersetzt werden:

 attr mydev substitute TEMPERATURE!.+:T=${value}° H={1.HUMIDITY}%