HMCCUDEV

Aus FHEMWiki
Zur Navigation springen Zur Suche springen


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