HMCCUDEV: Unterschied zwischen den Versionen

Aus FHEMWiki
 
(43 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Baustelle}}
<div style="float:right">
{{Infobox Modul
|ModPurpose=HMCCU Client Device für Homematic Geräte
|ModType=d
|ModCmdRef=HMCCUDEV
|ModForumArea=HomeMatic
|ModTechName=88_HMCCUDEV.pm
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])
}}
{{Infobox Modul
|ModPurpose=HMCCU Client Device für Homematic Kanäle
|ModType=d
|ModCmdRef=HMCCUCHN
|ModForumArea=HomeMatic
|ModTechName=88_HMCCUCHN.pm
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])
}}
</div>
==Übersicht==
==Übersicht==
Mit den beiden Module HMCCUCHN und HMCCUDEV können in FHEM Devices für Homematic Geräte angelegt werden. Voraussetzung ist ein bereits existierendes I/O Device (Modul [[HMCCU]]) über das die Kommunikation mit der CCU2 erfolgt.
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 HMCCUCHN, wann HMCCUDEV?
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.
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) sowie Rauchmeldergruppen. Diese werden nur von HMCCUDEV unterstützt. Jedes Homematic Gerät stellt neben seinen Daten- und Steuerkanälen auch den Statuskanal 0 bereit, in dem z.B. Informationen über den Ladestand der Batterien abgelegt werden. Der Kanal 0 wird auch von HMCCUCHN Devices mitgeführt, d.h. es ist nicht erforderlich, für ein Gerät HMCCUDEV zu verwenden, nur um den Statuskanal nutzen zu können.


==Definition von FHEM Devices==
==Definition von FHEM Devices==
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):
===Basisdefintion===
Die Basissyntax für die Definition von FHEM Devices für Homematic Geräte und Kanäle unterscheidet sich lediglich in der Adressangabe des Homematic Geräts (auf die Besonderheit virtueller CCU2 Geräte wird später eingegangen):
<pre>
<pre>
define <name> HMCCUCHN <channel> [defaults] [readonly]
define <name> HMCCUCHN <channel> [defaults] [readonly]
define <name> HMCCUDEV <device>[defaults] [readonly]
define <name> HMCCUDEV <device> [defaults] [readonly]
</pre>
</pre>
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.<br/>
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.<br/>
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.
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:
<pre>define <name> HMCCUDEV <groupdevice> group=<device>[,...] [defaults] [readonly]</pre>
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==
==Datenpunkte und Readings==
===Arten von Datenpunkten===
===Arten von Datenpunkten===
Zeile 20: Zeile 52:
* Read – Lesen von Werten. Beim Auslesen wird der Wert in ein Reading des zugehörigen FHEM Devices geschrieben.
* 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.
* 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:
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 [http://www.eq-3.de/Downloads/eq3/download%20bereich/hm_web_ui_doku/hm_devices_Endkunden.pdf 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:
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 Client.Devices zur Verfügung steht. Für einen Dimmer sieht die Ausgabe z.B. wie folgt aus:


<pre>
<pre>
Zeile 50: Zeile 82:
   DPT {b} BidCos-RF.MEQ1117422:1.WORKING = false [RE]
   DPT {b} BidCos-RF.MEQ1117422:1.WORKING = false [RE]
</pre>
</pre>
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 Befehl '''set datapoint''' gesetzt (W=Write) bzw. per Befehl '''get datapoint''' 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===
===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. 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.
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). Alternativ kann der Befehl get configlist verwendet werden, um die aktuellen Einstellungen der Parameter eines Kanals oder eines Gerätes zu ermitteln. 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
Ä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-„. Damit Parameter als Readings dargestellt werden, müssen sie im Attribut  ''ccureadingfilter'' enthalten sein.
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:
===Darstellung von Datenpunkten in FHEM===
(LOWBAT|STATE|LEVEL)
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:
Ccureadingformat – Legt fest, wie aus dem Namen bzw. der Adresse eines Datenpunktes der Readingname in FHEM gebildet wird. Folgende Angaben sind möglich
 
Format Readingname
:'''''ccureadingfilter''''' – Legt mit einem regulären Ausdruck fest, welche Datenpunkte als Readings gespeichert werden. Die Angabe eines solche Filters reduziert die Last in FHEM und macht die Darstellung übersichtlicher. Beispiel: <code>(LOWBAT|STATE|LEVEL)</code>. Im I/O Device kann mit dem Attribut ''ccudef-readingfilter'' ein allgemein gültiger Filter festgelegt werden.
Datapoint Kanalnummer.Datenpunkt
 
:'''''ccureadingformat''''' – Legt fest, wie aus dem Namen bzw. der Adresse eines Datenpunktes der Readingname in FHEM gebildet wird. Folgende Formate werden unterstützt:
:*datapoint - Die Readingnames werden aus der Kanalnummer und dem Namen des Datenpunktes gebildet
:*name - Ein Readingname entspricht dem Kanalnamen in der CCU gefolgt vom Namen des Datenpunktes
:*address - Die Readingnames setzen sich aus der Kanaladresse und dem Namen des Datenpunktes zusammen
:Der Zusatz "lc" wandelt die Readingnames in Kleinbuchstaben um.
 
:'''''ccureadingname''''' – Erlaubt es, die Namen einzelner Readings zu ändern, mehrere Readings zu einem einzigen zusammen zu fassen oder einzelne Datenpunkte in mehreren Readings darzustellen. Beispiel: Readingname "1.LEVEL" durch "pct" ersetzen <code>1.LEVEL:pct</code>. Beispiel: Readingname "1.LEVEL" um "pct" ergänzen: <code>1.LEVEL:+pct</code>
 
:'''''ccuscaleval''''' – Skaliert und/oder verschiebt und/oder invertiert den Wert eines Datenpunkts beim Lesen und beim Schreiben. Ein Ausrufezeichen vor dem Datenpunktnamen bewirkt das Invertieren der Werte.<br/>
:Beispiel: Der Datenpunkt LEVEL soll statt Werte zwischen 0 und 1 Werte zwischen 0 und 100 liefern <code>LEVEL:0:1:0:100</code>.<br/>
:Beispiel: Der Datenpunkt LEVEL soll statt Werte zwischen 0 und 1 Werte zwischen 100 und 110 liefern <code>LEVEL:0:1:100:110</code><br/>
:Beispiel: Der Wert des Datenpunktes LEVEL soll invertiert und vom Bereich 0-1 auf den Bereich 0-100 skaliert werden <code>!LEVEL:0:1:0:100</code>
 
:'''''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===
 
==== Befehlssyntax ====
Mit dem Befehl '''set datapoint''' können Werte von Datenpunkten in der CCU2 geändert werden. Die Syntax des Befehls lautet:
<pre>set <device> datapoint <datapointSpec> <value> [...]
set <device> datapoint <datapointSpec>=<value> [...]</pre>
Der Parameter ''datapointSpec'' beschreibt den zu setzenden Datenpunkt in folgendem Format:
datapointSpec := [<seqNum>:][<channelNum>.]<datapointName>
''seqNum'' - Wenn mehrere Datenpunkte mit einem set-Befehl geändert werden sollen und dabei die Reihenfolge wichtig ist, in der diese Datenpunkte gesetzt werden, kann am Anfang einer Datenpunktspezifikation eine laufende Nummer angegeben werden.
 
''channelNum'' - Bei HMCCUDEV Devices muss die Nummer des Kanals angegeben werden, zu dem der Datenpunkt gehört. Diese Angabe ist bei HMCCUCHN Devices nicht erforderlich.
 
''datapointName'' - Der Name des Datenpunktes.
 
Bei Problemen mit dem Setzen von Datenpunkten ist es hilfreich, sich die Ausgabe des Befehls get deviceInfo anzuschauen. Dort werden die Datenpunkte inkl. Kanalzugehörigkeit aufgelistet. Außerdem kann man anhand der Flags ("RWE") erkennen, ob ein Datenpunkt überhaupt geändert werden kann ("W=Write").
 
==== Datenpunktwerte ====
Wenn als ''value'' ein "?" angegeben wird, zeigt HMCCU die möglichen Werte eines Datenpunktes an. Der Wert "oldVal" setzt den Datenpunkt auf den vorhergehenden Zustand. Dadurch wird eine Umschaltung zwischen 2 Werten ermöglicht (toggeln). Dies setzt allerdings voraus, dass der Datenpunkt seit dem letzten Starten von FHEM mindestens einmal geändert wurde. Andernfalls wird eine Fehlermeldung ausgegeben.
 
Wenn ein Datenpunkt die Einheit Prozent verwendet (z.B. LEVEL bei Dimmern oder Rollläden), erfolgt die Angabe beim Setzen in Prozent, d.h. der Wert muss zwischen 0 und 100 liegen. HMCCU skaliert diese Werte automatisch in den Bereich 0 bis 1.
 
Werte von Text-Datenpunkte sollten in doppelten Hochkomma eingeschlossen sein:
set myDev datapoint COMBINED="Das ist ein Text"
Einige Homematic Geräte unterstützen spezielle Werte, um z.B. einen vorherigen Zustand einzustellen oder auch, um einen Befehl zu ignorieren. Diese Werte können z.B. bei Jalousien 1.01 oder 1.005 sein, manchmal auch -0.5 (siehe auch Homematic Datenpunkt Beschreibung). Wichtig: Diese Werte werden ohne Skalierung eingegeben, z.B.
set myDev datapoint LEVEL 1.005


Ccureadingname – Erlaubt es, die Namen einzelner Readings zu ändern oder mehrere Readings zu einem einzigen zusammen zu fassen. Beispiel:
==== Beispiele ====
Ccuscaleval – Skaliert und/oder verschiebt Datenpunkt Werte.
Beispiel 1: Eine Steckdose ist als HMCCUDEV definiert. Sie wird über den Datenpunkt 1.STATE (Kanal = 1) und den Werten "1" und "0" ein- oder ausgeschaltet. Über den Datenpunkt 1.ON_TIME soll die Einschaltdauer auf 60 Sekunden gesetzt werden. Der entsprechende Befehl zum Einschalten lautet:
Beispiel: Datenpunkt LEVEL ccuscaleval LEVEL:0:1:0:100
<pre>set myDev datapoint 1:1.ON_TIME=60 2:1.STATE=1</pre>
Substitute – Ersetzt Datenpunkt-Werte durch Texte.
Bei diesem Beispiel wird durch Voranstellen von "1:" bzw. "2:" sichergestellt, dass zunächst die Einschaltdauer gesetzt wird. Dies ist in diesem Fall zwingend erforderlich, da die CCU sonst diesen Parameter ignoriert.
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_TEMPERATUR
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:
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
Beispiel 2: Umschalten eines Gerätes auf den vorherigen Wert:
X
set myDev datapoint 1.LEVEL oldVal
==Darstellung in der FHEM Oberfläche==






[[Kategorie:HomeMatic Components]]
[[Kategorie:HomeMatic Components]]

Aktuelle Version vom 10. Dezember 2023, 13:02 Uhr


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


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) sowie Rauchmeldergruppen. Diese werden nur von HMCCUDEV unterstützt. Jedes Homematic Gerät stellt neben seinen Daten- und Steuerkanälen auch den Statuskanal 0 bereit, in dem z.B. Informationen über den Ladestand der Batterien abgelegt werden. Der Kanal 0 wird auch von HMCCUCHN Devices mitgeführt, d.h. es ist nicht erforderlich, für ein Gerät HMCCUDEV zu verwenden, nur um den Statuskanal nutzen zu können.

Definition von FHEM Devices

Basisdefintion

Die Basissyntax für die Definition von FHEM Devices für Homematic Geräte und Kanäle 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 Client.Devices 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 Befehl set datapoint gesetzt (W=Write) bzw. per Befehl get datapoint 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). Alternativ kann der Befehl get configlist verwendet werden, um die aktuellen Einstellungen der Parameter eines Kanals oder eines Gerätes zu ermitteln. 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-„. Damit Parameter als Readings dargestellt werden, müssen sie im Attribut ccureadingfilter enthalten sein.

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 und macht die Darstellung übersichtlicher. Beispiel: (LOWBAT|STATE|LEVEL). Im I/O Device kann mit dem Attribut ccudef-readingfilter ein allgemein gültiger Filter festgelegt werden.
ccureadingformat – Legt fest, wie aus dem Namen bzw. der Adresse eines Datenpunktes der Readingname in FHEM gebildet wird. Folgende Formate werden unterstützt:
  • datapoint - Die Readingnames werden aus der Kanalnummer und dem Namen des Datenpunktes gebildet
  • name - Ein Readingname entspricht dem Kanalnamen in der CCU gefolgt vom Namen des Datenpunktes
  • address - Die Readingnames setzen sich aus der Kanaladresse und dem Namen des Datenpunktes zusammen
Der Zusatz "lc" wandelt die Readingnames in Kleinbuchstaben um.
ccureadingname – Erlaubt es, die Namen einzelner Readings zu ändern, mehrere Readings zu einem einzigen zusammen zu fassen oder einzelne Datenpunkte in mehreren Readings darzustellen. Beispiel: Readingname "1.LEVEL" durch "pct" ersetzen 1.LEVEL:pct. Beispiel: Readingname "1.LEVEL" um "pct" ergänzen: 1.LEVEL:+pct
ccuscaleval – Skaliert und/oder verschiebt und/oder invertiert den Wert eines Datenpunkts beim Lesen und beim Schreiben. Ein Ausrufezeichen vor dem Datenpunktnamen bewirkt das Invertieren der Werte.
Beispiel: Der Datenpunkt LEVEL soll statt Werte zwischen 0 und 1 Werte zwischen 0 und 100 liefern LEVEL:0:1:0:100.
Beispiel: Der Datenpunkt LEVEL soll statt Werte zwischen 0 und 1 Werte zwischen 100 und 110 liefern LEVEL:0:1:100:110
Beispiel: Der Wert des Datenpunktes LEVEL soll invertiert und vom Bereich 0-1 auf den Bereich 0-100 skaliert werden !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

Befehlssyntax

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

set <device> datapoint <datapointSpec> <value> [...]
set <device> datapoint <datapointSpec>=<value> [...]

Der Parameter datapointSpec beschreibt den zu setzenden Datenpunkt in folgendem Format: 

datapointSpec := [<seqNum>:][<channelNum>.]<datapointName>

seqNum - Wenn mehrere Datenpunkte mit einem set-Befehl geändert werden sollen und dabei die Reihenfolge wichtig ist, in der diese Datenpunkte gesetzt werden, kann am Anfang einer Datenpunktspezifikation eine laufende Nummer angegeben werden.

channelNum - Bei HMCCUDEV Devices muss die Nummer des Kanals angegeben werden, zu dem der Datenpunkt gehört. Diese Angabe ist bei HMCCUCHN Devices nicht erforderlich.

datapointName - Der Name des Datenpunktes.

Bei Problemen mit dem Setzen von Datenpunkten ist es hilfreich, sich die Ausgabe des Befehls get deviceInfo anzuschauen. Dort werden die Datenpunkte inkl. Kanalzugehörigkeit aufgelistet. Außerdem kann man anhand der Flags ("RWE") erkennen, ob ein Datenpunkt überhaupt geändert werden kann ("W=Write").

Datenpunktwerte

Wenn als value ein "?" angegeben wird, zeigt HMCCU die möglichen Werte eines Datenpunktes an. Der Wert "oldVal" setzt den Datenpunkt auf den vorhergehenden Zustand. Dadurch wird eine Umschaltung zwischen 2 Werten ermöglicht (toggeln). Dies setzt allerdings voraus, dass der Datenpunkt seit dem letzten Starten von FHEM mindestens einmal geändert wurde. Andernfalls wird eine Fehlermeldung ausgegeben.

Wenn ein Datenpunkt die Einheit Prozent verwendet (z.B. LEVEL bei Dimmern oder Rollläden), erfolgt die Angabe beim Setzen in Prozent, d.h. der Wert muss zwischen 0 und 100 liegen. HMCCU skaliert diese Werte automatisch in den Bereich 0 bis 1.

Werte von Text-Datenpunkte sollten in doppelten Hochkomma eingeschlossen sein: 

set myDev datapoint COMBINED="Das ist ein Text"

Einige Homematic Geräte unterstützen spezielle Werte, um z.B. einen vorherigen Zustand einzustellen oder auch, um einen Befehl zu ignorieren. Diese Werte können z.B. bei Jalousien 1.01 oder 1.005 sein, manchmal auch -0.5 (siehe auch Homematic Datenpunkt Beschreibung). Wichtig: Diese Werte werden ohne Skalierung eingegeben, z.B. 

set myDev datapoint LEVEL 1.005

Beispiele

Beispiel 1: Eine Steckdose ist als HMCCUDEV definiert. Sie wird über den Datenpunkt 1.STATE (Kanal = 1) und den Werten "1" und "0" ein- oder ausgeschaltet. Über den Datenpunkt 1.ON_TIME soll die Einschaltdauer auf 60 Sekunden gesetzt werden. Der entsprechende Befehl zum Einschalten lautet: 

set myDev datapoint 1:1.ON_TIME=60 2:1.STATE=1

Bei diesem Beispiel wird durch Voranstellen von "1:" bzw. "2:" sichergestellt, dass zunächst die Einschaltdauer gesetzt wird. Dies ist in diesem Fall zwingend erforderlich, da die CCU sonst diesen Parameter ignoriert.

Beispiel 2: Umschalten eines Gerätes auf den vorherigen Wert: 

set myDev datapoint 1.LEVEL oldVal

Darstellung in der FHEM Oberfläche

Abgerufen von „http://wiki.fhem.de/w/index.php?title=HMCCUDEV&oldid=38784“