HMCCUDEV

HMCCUDEV
Zweck / Funktion
HMCCU Client Device für Homematic Geräte
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE
Support (Forum)	HomeMatic
Modulname	88_HMCCUDEV.pm
Ersteller	zap (Forum / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

HMCCUCHN
Zweck / Funktion
HMCCU Client Device für Homematic Kanäle
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE
Support (Forum)	HomeMatic
Modulname	88_HMCCUCHN.pm
Ersteller	zap (Forum / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Übersicht

Mit den beiden Modulen HMCCUCHN und HMCCUDEV können in FHEM Devices für Homematic Geräte angelegt werden, die an einer CCU2 angelernt sind. Voraussetzung ist ein bereits existierendes I/O Device (Modul HMCCU) über das die Kommunikation mit der CCU2 erfolgt.

Wann verwendet man HMCCUCHN, wann HMCCUDEV?

Das Modul HMCCUCHN legt Devices für einzelne Kanäle an, während mit HMCCUDEV Devices für Homematic Geräte definiert werden, die alle Kanäle eines Geräts enthalten. Wenn also alle benötigten Datenpunkte eines Homematic Geräts in einem Kanal verfügbar sind, genügt HMCCUCHN. Sollen mehrere Kanäle genutzt bzw. ausgewertet werden, muss HMCCUDEV verwendet werden. Ein Sonderfall sind virtuelle CCU2 Geräte (Gruppen). Diese werden nur von HMCCUDEV unterstützt.

Definition von FHEM Devices

Basisdefintion

Die Basissyntax für die Definition von Devices unterscheidet sich lediglich in der Adressangabe des Homematic Geräts (auf die Besonderheit virtueller CCU2 Geräte wird später eingegangen):

define <name> HMCCUCHN <channel> [defaults] [readonly]
define <name> HMCCUDEV <device> [defaults] [readonly]

Der Parameter channel steht für den Namen oder die Adresse eines Homematic Gerätekanals, während device die Adresse oder der Name eines Homematic Geräts ist. Wenn die Option "defaults" angegeben wird, werden einige Attribute gesetzt, sofern der Gerätetyp in der Datei HMCCUConf.pm hinterlegt ist. Als "readonly" definierte Devices lassen lediglich Get-Befehle zu.
Hinweis: Devices vom Typ HMCCUCHN erhalten zusätzlich zum angegebenen Kanal auch Informationen aus dem Statuskanal 0, den die CCU2 für jedes Homematic Gerät anbietet.

Virtuelle CCU Geräte

In der CCU2 können virtuelle Geräte angelegt werden. Dabei handelt es sich um Gruppen einzelner Homematic Geräte. Der häufigste Anwendungsfall dürften Heizungsgruppen sein, die z.B. ein Heizkörperthermostat, ein Wandthermostat sowie einen Fenstersensor enthalten. Der Vorteil solcher Gruppen ist, dass sich die CCU2 automatisch um die Verknüpfung dieser Geräte untereinander kümmert.

Das Modul HMCCUDEV unterstützt virtuelle Geräte. Bei der Definition in FHEM müssen einige zusätzliche Angaben gemacht werden:

define <name> HMCCUDEV <groupdevice> group=<device>[,...] [defaults] [readonly]

Der Parameter groupdevice entspricht der Adresse oder dem Namen des virtuellen Devices in der CCU2. Hinter "group" wird eine Liste der Homematic Geräte angegeben, die zu dieser Gerätegruppe gehören.

Damit virtuelle Devices automatisch aktualisiert werden, muss im I/O Device ein RPC-Server für den Port 9292 gestartet werden (Attribut rpcport).

Datenpunkte und Readings

Arten von Datenpunkten

Jedes Homematic Gerät wird über Datenpunkte gesteuert und/oder gibt Informationen über Datenpunkte nach außen. Jeder Kanal eines Homematic Geräts verfügt über mindestens einen Datenpunkt. Datenpunkte haben einen Datentyp (z.B. Text oder Integer-Zahl) und bieten eine oder mehrere Zugriffsmethoden an:

• Write – Schreiben von Werten (z.B. Setzen einer Zieltemperatur für einen Thermostaten, Einschalten einer Steckdose).
• Read – Lesen von Werten. Beim Auslesen wird der Wert in ein Reading des zugehörigen FHEM Devices geschrieben.
• Event – Die CCU2 informiert FHEM automatisch über Änderungen eines Datenpunkts. Das I/O Device aktualisiert alle FHEM Client-Devices über die Änderung und schreibt die Werte in Readings.

Für die Nutzung in FHEM ist es essenziell, die Datenpunkte eines Homematic Geräts und ihre Funktion zu kennen. Die Firma EQ3 stellt auf ihrer Webseite eine Dokumentation aller Homematic Geräte und der Datenpunkte zur Verfügung:

Eine Übersicht der Datenpunkte eines Homematic Geräts inkl. der Datentypen und Schnittstellen liefert der Befehl get deviceinfo, der sowohl im I/O Device als auch für Devices vom Typ HMCCUDEV zur Verfügung steht. Für einen Dimmer sieht die Ausgabe z.B. wie folgt aus:

CHN MEQ1117422:0 ST-WZ-Lampe2:0 
  DPT {b} BidCos-RF.MEQ1117422:0.UNREACH = true [RE] 
  DPT {b} BidCos-RF.MEQ1117422:0.STICKY_UNREACH = true [RWE] 
  DPT {b} BidCos-RF.MEQ1117422:0.CONFIG_PENDING = false [RE] 
  DPT {b} BidCos-RF.MEQ1117422:0.DUTYCYCLE = false [RE] 
  DPT {n} BidCos-RF.MEQ1117422:0.RSSI_DEVICE = 1 [RE] 
  DPT {n} BidCos-RF.MEQ1117422:0.RSSI_PEER = 1 [RE] 
  DPT {b} BidCos-RF.MEQ1117422:0.DEVICE_IN_BOOTLOADER = false [RE] 
  DPT {b} BidCos-RF.MEQ1117422:0.UPDATE_PENDING = false [RE] 
  DPT {n} BidCos-RF.MEQ1117422:0.AES_KEY = 0 [R] 
CHN MEQ1117422:1 ST-WZ-Lampe2:1 
  DPT {6} BidCos-RF.MEQ1117422:1.LEVEL = 0.000000 [RWE] 
  DPT {b} BidCos-RF.MEQ1117422:1.OLD_LEVEL =  [W] 
  DPT {f} BidCos-RF.MEQ1117422:1.LEVEL_REAL = 0.000000 [RE] 
  DPT {f} BidCos-RF.MEQ1117422:1.RAMP_TIME =  [W] 
  DPT {f} BidCos-RF.MEQ1117422:1.ON_TIME =  [W] 
  DPT {b} BidCos-RF.MEQ1117422:1.RAMP_STOP =  [W] 
  DPT {b} BidCos-RF.MEQ1117422:1.INHIBIT = false [RWE] 
  DPT {b} BidCos-RF.MEQ1117422:1.ERROR_REDUCED = false [RE] 
  DPT {b} BidCos-RF.MEQ1117422:1.ERROR_OVERLOAD = false [RE] 
  DPT {b} BidCos-RF.MEQ1117422:1.ERROR_OVERHEAT = false [RE] 
  DPT {i} BidCos-RF.MEQ1117422:1.DIRECTION = 0 [RE] 
  DPT {b} BidCos-RF.MEQ1117422:1.INSTALL_TEST =  [W] 
  DPT {b} BidCos-RF.MEQ1117422:1.WORKING = false [RE]

Die Zeilen, die mit "CHN" beginnen, enthalten Adresse und Name des Gerätekanals. Die darauf folgenden eingerückten Zeilen beginnend mit "DPT" enthalten jeweils die Beschreibung eines Datenpunktes. Der Buchstaben in geschweiften Klammern enthält den Datentyp (b=bool,f=float,i=integer). Danach folgt die vollständige Adresse des Datenpunktes inkl. Namen. Am Ende einer Zeile steht der aktuelle Wert des Datenpunktes sowie die Flags mit den Zugriffsmöglichkeiten. Diese Flags sind sehr wichtig. Sie legen fest, ob ein Datenpunkt per Set-Befehl gesetzt (W=Write) bzw. per Get-Befehl ausgelesen werden kann (R=Read). Das Event-Flag (E=Event) zeigt an, dass ein Datenpunkt per RPC-Event automatisch aktualisiert wird (laufender RPC-Server vorausgesetzt).

Konfigurationsparameter

Neben den Datenpunkten stellen Homematic Geräte noch Konfigurationsparameter bereit. Mit diesen Parametern werden grundsätzliche Verhaltensweisen eingestellt (z.B. Wochenprofile für Thermostaten). Eine Liste der Konfigurationsparameter eines Geräts erhält man mit dem Befehl get configdesc, der in allen drei Modulen zu Verfügung steht. Der Befehl kann bezogen auf ein Gerät oder einen Kanal aufgerufen werden. Sofern verfügbar, liefert er eine Beschreibung der Konfigurationsparameter zurück (nicht alle Homematic Gerätetypen unterstützen diese Funktion). In der CCU2 kann unter dem Menü „Einstellungen – Geräte“ eingesehen werden, in welchen Kanälen eines Geräts bestimmte Parameter eingestellt werden können.

Änderungen an Geräteparameter werden nicht automatisch von der CCU2 an FHEM übermittelt. Sie müssen in HMCCUCHN bzw. HMCCUDEV mit dem Befehl get config abgefragt werden. Die Readingnames zu Geräteparametern beginnen immer mit dem Text „R-„.

Darstellung von Datenpunkten in FHEM

Werte von Datenpunkten mit den Zugriffsarten "Read" und "Event" werden in FHEM Devices als Readings gespeichert.Die Darstellung der Readings wird mit Hilfe von Attributen für jedes Client-Device individuell festgelegt. Die wichtigsten Attribute sind:

ccureadingfilter – Legt mit einem regulären Ausdruck fest, welche Datenpunkte als Readings gespeichert werden. Die Angabe eines solche Filters reduziert die Last in FHEM. Beispiel (LOWBAT|STATE|LEVEL)

ccureadingformat – Legt fest, wie aus dem Namen bzw. der Adresse eines Datenpunktes der Readingname in FHEM gebildet wird.

ccureadingname – Erlaubt es, die Namen einzelner Readings zu ändern oder mehrere Readings zu einem einzigen zusammen zu fassen. Beispiel:

ccuscaleval – Skaliert und/oder verschiebt Datenpunkt Werte. Beispiel: Datenpunkt LEVEL ccuscaleval LEVEL:0:1:0:100

substitute – Ersetzt Datenpunkt-Werte durch Texte.

statedatapoint – Legt den Kanal (nur bei HMCCUDEV) und den Datenpunkt fest, der im Reading „state“ bzw. dem Internal „STATE“ eines FHEM Devices gespeichert wird. Beispiel: 1.SET_TEMPERATURE

controldatapoint – Legt den Datenpunkt fest, der im Reading „control“ eines FHEM Devices gespeichert wird. Beispiel: 1.LEVEL

Steuern von Homematic Geräten über Datenpunkte

Mit dem Befehl set datapoint können Werte von Datenpunkten in der CCU2 geändert werden. Die Syntax des Befehls lautet:

set <device> datapoint <datapoint> <value>

Als Parameter wird bei HMCCUDEV Devices eine Kombination aus Kanalnummer und Datenpunkt angegeben (z.B. 1.STATE). Bei HMCCUCHN Devices nur der Datenpunkt. Zu beachten ist, dass der angegebene Wert dem Datentyp des Datenpunktes entspricht.

Beispiel: Eine Steckdose wird über den Datenpunkt 1.STATE (Kanal = 1) und den Werten "true" und "false" ein- oder ausgeschaltet. Der entsprechende Befehl zum einschalten lautet:

set mydev datapoint 1.STATE true

Das Setzen von Datenpunkten kann man mit Hilfe der Attribute statedatapoint und statevals vereinfachen. Zunächst wird mit statedatapoint der Datenpunkt festgelegt, der per Default geschaltet werden soll. Im vorherigen Beispiel wäre das „1.STATE“. Dann werden mit statevals sprechende Werte sowie ihre Übersetzung für die CCU2 festgelegt:

attr mydev statevals on:true,off:false

Nach diesen Festlegungen sind folgende Befehle möglich:

set mydev devstate on
set mydev on
set mydev toggle

Die Befehle set devstate und get devstate greifen immer auf den Datenpunkt zurück, der im Attribut statedatapoint angegeben ist. Der Befehl set toggle schaltet zwischen den Zuständen um, die im Attribut statevals angegeben sind. Letztere werden außerdem als direkte Set-Befehle (im Beispiel „on“ und „off“) bereitgestellt.

Beim Auslesen des State-Datenpunktes mit get devstate oder auch get datapoint wird das zugehörige Reading und zusätzlich das Reading state sowie das Internal STATE aktualisiert.

Automatisches Erkennen von Gerätefunktionen

Wenn ein Gerät über den Datenpunkt LEVEL oder ON_TIME verfügt, stellen HMCCUDEV und HMCCUCHN automatisch Befehle zum prozentualen und zeitgesteuerten Schalten zur Verfügung.

Darstellung in der FHEM Oberfläche X