HMCCU: Unterschied zwischen den Versionen
Zap (Diskussion | Beiträge) |
DR (Diskussion | Beiträge) K (→Inbetriebnahme) |
||
(32 dazwischenliegende Versionen von 9 Benutzern werden nicht angezeigt) | |||
Zeile 1: | Zeile 1: | ||
{{ | Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. | ||
{{Hinweis|Dieser Artikel bezieht sich auf die neue HMCCU Version 5.0}} | |||
{{Infobox Modul | {{Infobox Modul | ||
|ModPurpose=Anbindung | |ModPurpose=Anbindung HomeMatic CCU an FHEM | ||
|ModType=d | |ModType=d | ||
|ModCmdRef=HMCCU | |ModCmdRef=HMCCU | ||
|ModForumArea=HomeMatic | |ModForumArea=HomeMatic | ||
|ModTechName=88_HMCCU.pm | |ModTechName=88_HMCCU.pm | ||
|ModOwner=zap ( | |ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]]) | ||
}} | }} | ||
==Einführung== | ==Einführung== | ||
===Übersicht=== | ===Übersicht=== | ||
Das Modul HMCCU ermöglicht zusammen mit den | Das Modul [[HMCCU]] ermöglicht zusammen mit den Client Modulen → [[HMCCUDEV]], HMCCUCHN und HMCCUPROCRPC eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt: | ||
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic | |||
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]] | * Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]] | ||
* Unterstützung von | * Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU | ||
* Unterstützung von HVL (HomeMatic Virtual Layer) | |||
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder) | |||
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server | * Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server | ||
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben | * Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben | ||
* Lesen und Schreiben von | * Lesen und Schreiben von CCU Systemvariablen | ||
* Ausführen von | * Ausführen von CCU Programmen | ||
* Ausführen von | * Ausführen von HomeMatic Scripts auf der CCU | ||
Die einzelnen Module haben folgende Aufgaben: | Die einzelnen Module haben folgende Aufgaben: | ||
* HMCCU: Kommunikation zwischen FHEM und | * HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device) | ||
* | * HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU | ||
* HMCCUDEV: Definition von FHEM Devices für | * HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte | ||
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von | * HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten | ||
* HMCCUConf: Templates mit Default Attributen für bestimmte | * HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen | ||
===Geräte, Kanäle und Datenpunkte=== | ===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. | 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. | ||
Der oben beschriebene Aufbau lässt sich am Beispiel einer Steckdose veranschaulichen:<syntaxhighlight lang="Text"> | |||
DEV ST-WR-Waschmaschine KEQ0965669 interface=BidCos-RF type=HM-ES-PMSw1-Pl | |||
CHN KEQ0965669:0 ST-WR-Waschmaschine:0 | |||
0.UNREACH = false {b} [RE] | |||
0.STICKY_UNREACH = true {b} [RWE] | |||
0.CONFIG_PENDING = false {b} [RE] | |||
0.DUTYCYCLE = false {b} [RE] | |||
0.RSSI_DEVICE = 1 {n} [RE] | |||
0.RSSI_PEER = 214 {n} [RE] | |||
0.DEVICE_IN_BOOTLOADER = false {b} [RE] | |||
0.UPDATE_PENDING = false {b} [RE] | |||
0.AES_KEY = 0 {n} [R] | |||
CHN KEQ0965669:1 ST-WR-Waschmaschine:1 | |||
1.STATE = true {b} [RWE] | |||
1.ON_TIME = {f} [W] | |||
1.INHIBIT = false {b} [RWE] | |||
1.INSTALL_TEST = {b} [W] | |||
1.WORKING = false {b} [RE] | |||
CHN KEQ0965669:2 ST-WR-Waschmaschine:2 | |||
2.ENERGY_COUNTER = 59348.000000 {f} [RE] | |||
2.POWER = 0.120000 {f} [RE] | |||
2.CURRENT = 45.000000 {f} [RE] | |||
2.VOLTAGE = 233.000000 {f} [RE] | |||
2.FREQUENCY = 49.990000 {f} [RE] | |||
2.BOOT = true {b} [RE] | |||
</syntaxhighlight> | |||
Das Gerät in diesem Beispiel hat 3 nutzbare Kanäle: | |||
* Kanal 0 ist der Maintenance Kanal. Diesen Kanal hat jedes Gerät. Er ist sowohl bei HMCCUCHN als auch bei HMCCUDEV immer vorhanden. Die Datenpunkte werden automatisch auf gebräuchliche Readings wie z.B. "battery" gemappt. | |||
* Kanal 1 ist der Schaltkanal der Steckdose. Er besitzt einen Datenpunkt STATE, über den die Steckdose ein-/ausgeschaltet werden kann. Die Flags "RWE" stehen für '''R'''ead, '''W'''rite, '''E'''vent. Der Datenpunkt ist also beschreibbar, lesbar und wird von der CCU per Event automatisch aktualisiert | |||
* Kanal 2 ist ein reiner Statuskanal. Er besitzt keine beschreibbaren Datenpunkte (nur '''R'''ead und '''E'''vent). | |||
Wenn man das Gerät lediglich schalten möchte und auf die Anzeige der Energiewerte aus Kanal 2 verzichten kann, sollte man ein HMCCUCHN Device für Kanal 1 (KEQ0965669:1) definieren (enthält automatisch auch Kanal 0). Andernfalls definiert man ein HMCCUDEV Device für das Gerät KEQ0965669, das dann alle Kanäle (0-2) enthält. | |||
Es wird empfohlen, für die Definition von FHEM Devices die HMCCU-Befehle '''get createDev''' oder '''get create''' zu verwenden. Sofern ein Gerät von HMCCU unterstützt wird, wird automatisch das richtige Modul ausgewählt. | |||
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen (noch nicht an 5.0 angepasst).}} | |||
==Inbetriebnahme== | ==Inbetriebnahme== | ||
===Zu beachten=== | ===Zu beachten=== | ||
* In den | * In den CCU 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 | * Namen in der CCU 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 | * Nach dem Neustart der CCU 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 | * Nach Änderung von Attributen der RPC-Server Devices oder von RPC-Attributen im I/O Device müssen die RPC-Server neu gestartet werden, damit die Änderungen berücksichtigt werden. | ||
* Seit der | * Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden. | ||
* Seit der CCU 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=== | ===CCU Firewall Einstellungen=== | ||
Ab | Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen: | ||
* Menü "Einstellungen > Systemsteuerung" aufrufen | * Menü "Einstellungen > Systemsteuerung" aufrufen | ||
* Button "Firewall konfigurieren" anklicken | * Button "Firewall konfigurieren" anklicken | ||
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden | |||
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen. | * 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. | * 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. | ||
Wenn der Zugriff von FHEM auf die CCU ohne Anmeldung erfolgen soll, muss zusätzlich in der Systemsteuerung unter "Sicherheit" die Option "Authentifizierung" deaktiviert werden. Alternativ kann im I/O Device (HMCCU) mit dem Befehl set authentication Benutzername und Passwort der CCU angegeben werden. | |||
===Installation=== | ===Installation=== | ||
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/ | Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. | ||
Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden oder alternativ CPAN verwendet werden: | |||
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre> | <pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre> | ||
Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren | |||
<pre>cpan install RPC::XML</pre> | |||
Bei der Installation gemäß [[FHEM Installation Windows]] befindet sich cpan man unter <code><FHEM-Hauptverzeichis>\perl\bin</code> | |||
===Definition I/O Device=== | ===Definition I/O Device=== | ||
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der | Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“. | ||
<pre>define d_ccu HMCCU 192.168.1.10</pre> | <pre>define d_ccu HMCCU 192.168.1.10</pre> | ||
Falls die CCU als Software Service auf dem gleichen Rechner läuft wie FHEM, sollte bei der Definition der Parameter ''ccudelay'' angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM (bis zu 2 Minuten). Durch ''ccudelay'' wird das neu angelegte I/O Device verzögert um die angegebene Anzahl Sekunden initialisiert. Die Vorgabe sind 180 Sekunden. Je nach Installation kann auch ein höherer Wert notwendig sein: | |||
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre> | |||
Der Start von FHEM wird dadurch nicht verzögert. Lediglich HMCCU wird verzögert initialisiert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden, greift dann also auch, wenn die CCU beim Start von FHEM erreichbar ist | |||
''' | |||
===RPC Server starten=== | ===RPC Server konfigurieren und starten=== | ||
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 CCU registrieren soll. Das Attribut zeigt in einer Auswahlliste die möglichen Schnittstellen an. Nur für die hier ausgewählten Schnittstellen werden automatisch Readings aktualisiert. | |||
Beim ersten Start dieses RPC-Servers über das I/O Device wird automatisch je Schnittstelle ein Device vom Typ HMCCURPCPROC angelegt. Die Attribute "room" und "group" werden vom I/O Device übernommen. | |||
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess mit eigenem Listening-Port gestartet. Beim ersten Start legt HMCCU für jede unter ''rpcinterfaces'' angegebene Schnittstelle ein Device vom Typ HMCCURPCPROC an. Sofern auf dem FHEM-Server eine Firewall aktiv ist, müssen die Ports (s. Attribut ''rpcserverport'') für den Zugriff der CCU freigegeben werden. | |||
<pre>set d_ccu | |||
Während | Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet: | ||
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit | <pre>set d_ccu on</pre> | ||
Während des Starts der RPC-Server und der Registrierung bei der CCU kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem die RPC-Server gestartet wurden, 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 die RPC-Server beim Start von FHEM automatisch gestartet werden: | |||
<pre>attr d_ccu rpcserver on</pre> | <pre>attr d_ccu rpcserver on</pre> | ||
== | == Migration von HMCCU 4.3 == | ||
Nachdem FHEM auf HMCCU Version 5.0 aktualisiert und neu gestartet wurde, sollten die definierten Geräte (HMCCUCHN und HMCCUDEV Devices) wie unter Version 4.3 funktionieren. Da die Devices in Version 5.0 jedoch mit deutlich weniger Attributen auskommen bzw. einige Attribute wie z.B. "eventMap" sogar zu doppelten '''set''' Befehlen führen können, sollten die Attribute der Geräte jeweils mit dem Befehl '''set defaults reset''' zurückgesetzt werden. Beim Zurücksetzen der Attribute werden überflüssige Attribute gelöscht. | |||
Wichtig | Wichtig: Nach dem Zurücksetzen der Attribute mit '''set defaults reset''' die Konfiguration speichern und FHEM neu starten. | ||
Je nach Anzahl bereits definierter Devices kann es sinnvoll sein, alle Devices mit der Funktion '''get create''' oder '''get createDev''' neu anzulegen. Für die neu angelegten Geräte wird automatisch das passende Client-Modul (HMCCUDEV oder HMCCUCHN) verwendet. | |||
==Synchronisation mit der CCU== | ==Synchronisation mit der CCU== | ||
Der Befehl '''get | === Geräte synchronisieren === | ||
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get ccuConfig''' 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. ein Gerät oder Kanal wurde umbenannt, ein neues Gerät wurde angelernt, ein Gerät wurde gelöscht. Bei der Definition des I/O Device (z.B. beim Start von FHEM) wird der Befehl automatisch ausgeführt. | |||
Der Befehl '''get ccuDevices''' zeigt eine Liste der in der CCU bekannten Geräte an inklusive einer Liste der Kanalrollen, die von HMCCU automatisch erkannt werden. Daran kann man erkennen, welche CCU-Geräte von den Befehlen '''get create''' und '''get createDev''' unterstützt werden. | |||
== | === Datenpunkte (Readings) synchronisieren === | ||
Eine manuelle Aktualisierung der Datenpunkte sollte nicht notwendig sein. Die Aktualisierung erfolgt automatisch durch die CCU per RPC-Server Verbindung. 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 FHEM-Devices für CCU Geräte== | |||
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen, sofern HMCCU eine oder mehrere Kanalrollen des betreffenden Gerätetyps unterstützt. Dazu kann entweder der Befehl '''get createDev''' (für ein einzelnes CCU Gerät) oder der Befehl '''get create''' (für mehrere CCU Geräte) verwenden werden. | |||
{{Hinweis|Es wird dringend empfohlen, FHEM Devices für CCU Geräte mit den Befehlen get createDev oder get create anzulegen. Nur wenn Geräte dabei nicht erkannt werden, sollte man auf das klassische define zurückgreifen}} | |||
Die beiden Befehle zur automatischen Erzeugung von HMCCUDEV/HMCCUCHN Devices beziehen sich immer auf CCU-Geräte, nicht deren Kanäle. Bei der Erzeugung der FHEM-Devices entscheidet HMCCU selbständig, ob ein oder mehrere HMCCUDEV oder HMCCUCHN Devices angelegt werden. Nach Ausführung der Befehle werden in einem Fenster die angelegten oder auch nicht erkannten Geräte angezeigt. | |||
Beispiel: Für das CCU-Gerät "Heizung-Wohnzimmer" soll ein FHEM-Device angelegt werden: | |||
get d_ccu createDev Heizung-Wohnzimmer | |||
Beispiel: Für alle CCU-Geräte, deren Namen mit "Heizung" beginnt, sollen FHEM-Devices angelegt werden: | |||
get d_ccu | get d_ccu create Heizung.* room=Homematic group=Heizung | ||
Beim vorherigen Beispiel wird als Gerätename ein regulärer Ausdruck ("Heizung.*) angegeben. Jedes angelegte Gerät bekommt die Attribute "room" und "group" zugewiesen. | |||
. | Wenn ein CCU-Gerät mehrere identische Kanalrollen besitzt, erzeugt HMCCU für jeden Kanal ein HMCCUCHN-Device. Ein Beispiel für solche CCU-Geräte sind Fernbedienungen, die 2-16 Kanäle der Rolle "KEY" besitzen. | ||
Beispiel: Für die 2-Kanal-Fernbedienung FB-Rollladen werden 2 HMCCUCHN Devices angelegt. Die Namen der Devices werden aus den Kanalnamen der Fernbedienung in der CCU gebildet: | |||
get d_ccu createDev FB-Rollladen | |||
erzeugt die HMCCUCHN Devices: FB-Rollladen-Wohnzimmer, FB-Rollladen-Kueche. | |||
Die Attribute der automatisch angelegten Devices können über die I/O Device Attribute '''ccudef-attributes''' und '''createDeviceGroup''' beeinflusst werden. Um allen neu angelegten Devices das Attribut room=Homematic zuzuweisen, definiert man folgendes Attribut im I/O Device: | |||
Mit dem | <syntaxhighlight lang="Text"> | ||
attr d_ccu ccudef-attributes room=Homematic | |||
</syntaxhighlight> | |||
Mit dem Attribut '''createDeviceGroup''' können Einzel-Devices, die alle zu einem CCU-Gerät gehören, automatisch in einer FHEM-Gruppe zusammengefasst werden. Dieses Attribut kommt z.B. zur Anwendung, wenn man get createDev für eine Fernbedienung mit mehreren Kanälen ausführt. In diesem Fall legt HMCCU für jeden Kanal der Fernbedienung ein HMCCUCHN Device an. Mit dem folgenden Attribut im I/O Device werden diese HMCCUCHN Devices alle einer Gruppe zugeordnet, deren Name dem Gerätenamen in der CCU entspricht: | |||
<syntaxhighlight lang="Text"> | |||
attr d_ccu createDeviceGroup %n | |||
</syntaxhighlight> | |||
Die möglichen Platzhalter (wie z.B. %n) können der Commandref entnommen werden. | |||
==Weitere Funktionen des Moduls HMCCU== | ==Weitere Funktionen des Moduls HMCCU== | ||
===Lesen und Ändern von | ===Lesen und Ändern von CCU Systemvariablen=== | ||
Systemvariablen | Systemvariablen der CCU können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden. Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. | ||
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert | |||
Beispiel: Lesen aller Systemvariablen, die mit A beginnen: | Beispiel: Lesen aller Systemvariablen, die mit A beginnen: | ||
<pre>get d_ccu vars A.*</pre> | <pre>get d_ccu vars A.*</pre> | ||
Systemvariablen können in regelmäßigen Abständen gelesen werden. Dazu wird mit dem Attribut ccuGetVars ein Intervall und optional ein regulärer Ausdruck für die zu lesenden Systemvariablen festgelegt. | |||
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen: | |||
<pre>attr d_ccu ccuGetVars 60 | |||
attr d_ccu ccuGetVars 60:^A</pre> | |||
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden. | |||
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5: | Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5: | ||
<pre>set d_ccu var Temperatur 20.5</pre> | <pre>set d_ccu var Temperatur 20.5</pre> | ||
===Ausführen von | Mit dem Befehl '''set var''' kann auch eine neue Systemvariable in der CCU angelegt werden. Dazu wird als erster Parameter vor dem Variablennamen der Typ der neuen Variable angegeben. Mögliche Typen sind "bool", "list", "number" oder "text". | ||
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 | |||
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter": | |||
<pre>set d_ccu var text Wetter sonnig</pre> | |||
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt: | |||
* unit = Einheit | |||
* desc = Beschreibung | |||
* min = Kleinster erlaubter Wert bei numerischen Variablen | |||
* max = Größter erlaubter Wert bei numerischen Variablen | |||
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen | |||
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr" | |||
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch" | |||
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte: | |||
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre> | |||
===Ausführen von CCU 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 CCU aktiv oder inaktiv ist. | |||
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen: | Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen: | ||
<pre>set d_ccu execute Schalter_Ein</pre> | <pre>set d_ccu execute Schalter_Ein</pre> | ||
===Aggregation von Gerätezuständen | ===Aggregation von Gerätezuständen=== | ||
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind: | 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 Geräte haben einen niedrigen Batteriestand? | ||
Zeile 164: | Zeile 215: | ||
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: | 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''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden. | ||
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung | *''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen. | ||
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel 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). | *''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: | 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: | ||
<pre>get <io-dev> aggregation {all|<name>}</pre> | <pre>get <io-dev> aggregation {all|<name>}</pre> | ||
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 | 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 einen 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. | *'''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: | *'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden: | ||
Zeile 176: | Zeile 227: | ||
**group: FHEM Device ''group'' Attribut | **group: FHEM Device ''group'' Attribut | ||
**room: FHEM Device ''room'' Attribut | **room: FHEM Device ''room'' Attribut | ||
**type: | **type: HomeMatic Gerätetyp | ||
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT). | *'''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: | *'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift: | ||
Zeile 185: | Zeile 236: | ||
*'''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". | *'''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 | Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"): | ||
<pre> | <pre> | ||
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias | attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias | ||
Zeile 197: | Zeile 248: | ||
</pre> | </pre> | ||
===Ausführen von | ===Ausführen von HomeMatic Scripts=== | ||
Mit dem Befehl '''set hmscript''' kann ein beliebiges | 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 | Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''): | ||
<pre> | <pre> | ||
object osysvar; | object osysvar; | ||
Zeile 216: | Zeile 267: | ||
[[Kategorie:HomeMatic Components]] | [[Kategorie:HomeMatic Components]] | ||
[[Kategorie:Interfaces]] |
Aktuelle Version vom 9. August 2023, 07:22 Uhr
Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der HomeMatic CCU Zentrale sowie der dort angelernten Geräte in FHEM.
HMCCU | |
---|---|
Zweck / Funktion | |
Anbindung HomeMatic CCU 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 Client Modulen → HMCCUDEV, HMCCUCHN und HMCCUPROCRPC eine Integration der HomeMatic CCU Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:
- Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic
- Unterstützung der Protokolle BidCos, Wired und HM-IP
- Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU
- Unterstützung von HVL (HomeMatic Virtual Layer)
- Unterstützung von CCU 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 CCU Systemvariablen
- Ausführen von CCU Programmen
- Ausführen von HomeMatic Scripts auf der CCU
Die einzelnen Module haben folgende Aufgaben:
- HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)
- HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU
- 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.
Der oben beschriebene Aufbau lässt sich am Beispiel einer Steckdose veranschaulichen:
DEV ST-WR-Waschmaschine KEQ0965669 interface=BidCos-RF type=HM-ES-PMSw1-Pl
CHN KEQ0965669:0 ST-WR-Waschmaschine:0
0.UNREACH = false {b} [RE]
0.STICKY_UNREACH = true {b} [RWE]
0.CONFIG_PENDING = false {b} [RE]
0.DUTYCYCLE = false {b} [RE]
0.RSSI_DEVICE = 1 {n} [RE]
0.RSSI_PEER = 214 {n} [RE]
0.DEVICE_IN_BOOTLOADER = false {b} [RE]
0.UPDATE_PENDING = false {b} [RE]
0.AES_KEY = 0 {n} [R]
CHN KEQ0965669:1 ST-WR-Waschmaschine:1
1.STATE = true {b} [RWE]
1.ON_TIME = {f} [W]
1.INHIBIT = false {b} [RWE]
1.INSTALL_TEST = {b} [W]
1.WORKING = false {b} [RE]
CHN KEQ0965669:2 ST-WR-Waschmaschine:2
2.ENERGY_COUNTER = 59348.000000 {f} [RE]
2.POWER = 0.120000 {f} [RE]
2.CURRENT = 45.000000 {f} [RE]
2.VOLTAGE = 233.000000 {f} [RE]
2.FREQUENCY = 49.990000 {f} [RE]
2.BOOT = true {b} [RE]
Das Gerät in diesem Beispiel hat 3 nutzbare Kanäle:
- Kanal 0 ist der Maintenance Kanal. Diesen Kanal hat jedes Gerät. Er ist sowohl bei HMCCUCHN als auch bei HMCCUDEV immer vorhanden. Die Datenpunkte werden automatisch auf gebräuchliche Readings wie z.B. "battery" gemappt.
- Kanal 1 ist der Schaltkanal der Steckdose. Er besitzt einen Datenpunkt STATE, über den die Steckdose ein-/ausgeschaltet werden kann. Die Flags "RWE" stehen für Read, Write, Event. Der Datenpunkt ist also beschreibbar, lesbar und wird von der CCU per Event automatisch aktualisiert
- Kanal 2 ist ein reiner Statuskanal. Er besitzt keine beschreibbaren Datenpunkte (nur Read und Event).
Wenn man das Gerät lediglich schalten möchte und auf die Anzeige der Energiewerte aus Kanal 2 verzichten kann, sollte man ein HMCCUCHN Device für Kanal 1 (KEQ0965669:1) definieren (enthält automatisch auch Kanal 0). Andernfalls definiert man ein HMCCUDEV Device für das Gerät KEQ0965669, das dann alle Kanäle (0-2) enthält.
Es wird empfohlen, für die Definition von FHEM Devices die HMCCU-Befehle get createDev oder get create zu verwenden. Sofern ein Gerät von HMCCU unterstützt wird, wird automatisch das richtige Modul ausgewählt.
Inbetriebnahme
Zu beachten
- In den CCU 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 CCU 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 CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".
- Nach Änderung von Attributen der RPC-Server Devices oder von RPC-Attributen im I/O Device müssen die RPC-Server neu gestartet werden, damit die Änderungen berücksichtigt werden.
- Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.
- Seit der CCU 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 CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:
- Menü "Einstellungen > Systemsteuerung" aufrufen
- Button "Firewall konfigurieren" anklicken
- Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden
- 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.
Wenn der Zugriff von FHEM auf die CCU ohne Anmeldung erfolgen soll, muss zusätzlich in der Systemsteuerung unter "Sicherheit" die Option "Authentifizierung" deaktiviert werden. Alternativ kann im I/O Device (HMCCU) mit dem Befehl set authentication Benutzername und Passwort der CCU angegeben werden.
Installation
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client.
Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden oder alternativ CPAN verwendet werden:
sudo apt-get update && sudo apt-get install -y librpc-xml-perl
Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren
cpan install RPC::XML
Bei der Installation gemäß FHEM Installation Windows befindet sich cpan man unter <FHEM-Hauptverzeichis>\perl\bin
Definition I/O Device
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU 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 Parameter ccudelay angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM (bis zu 2 Minuten). Durch ccudelay wird das neu angelegte I/O Device verzögert um die angegebene Anzahl Sekunden initialisiert. Die Vorgabe sind 180 Sekunden. Je nach Installation kann auch ein höherer Wert notwendig sein:
define d_ccu HMCCU 192.168.1.10 ccudelay=180
Der Start von FHEM wird dadurch nicht verzögert. Lediglich HMCCU wird verzögert initialisiert. Die verzögerte Initialisierung kann mit dem Parameter delayedinit erzwungen werden, greift dann also auch, wenn die CCU beim Start von FHEM erreichbar ist
RPC Server konfigurieren und starten
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 CCU registrieren soll. Das Attribut zeigt in einer Auswahlliste die möglichen Schnittstellen an. Nur für die hier ausgewählten Schnittstellen werden automatisch Readings aktualisiert.
Beim ersten Start dieses RPC-Servers über das I/O Device wird automatisch je Schnittstelle ein Device vom Typ HMCCURPCPROC angelegt. Die Attribute "room" und "group" werden vom I/O Device übernommen.
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess mit eigenem Listening-Port gestartet. Beim ersten Start legt HMCCU für jede unter rpcinterfaces angegebene Schnittstelle ein Device vom Typ HMCCURPCPROC an. Sofern auf dem FHEM-Server eine Firewall aktiv ist, müssen die Ports (s. Attribut rpcserverport) für den Zugriff der CCU freigegeben werden.
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:
set d_ccu on
Während des Starts der RPC-Server und der Registrierung bei der CCU kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem die RPC-Server gestartet wurden, 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 die RPC-Server beim Start von FHEM automatisch gestartet werden:
attr d_ccu rpcserver on
Migration von HMCCU 4.3
Nachdem FHEM auf HMCCU Version 5.0 aktualisiert und neu gestartet wurde, sollten die definierten Geräte (HMCCUCHN und HMCCUDEV Devices) wie unter Version 4.3 funktionieren. Da die Devices in Version 5.0 jedoch mit deutlich weniger Attributen auskommen bzw. einige Attribute wie z.B. "eventMap" sogar zu doppelten set Befehlen führen können, sollten die Attribute der Geräte jeweils mit dem Befehl set defaults reset zurückgesetzt werden. Beim Zurücksetzen der Attribute werden überflüssige Attribute gelöscht.
Wichtig: Nach dem Zurücksetzen der Attribute mit set defaults reset die Konfiguration speichern und FHEM neu starten.
Je nach Anzahl bereits definierter Devices kann es sinnvoll sein, alle Devices mit der Funktion get create oder get createDev neu anzulegen. Für die neu angelegten Geräte wird automatisch das passende Client-Modul (HMCCUDEV oder HMCCUCHN) verwendet.
Synchronisation mit der CCU
Geräte synchronisieren
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl get ccuConfig 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. ein Gerät oder Kanal wurde umbenannt, ein neues Gerät wurde angelernt, ein Gerät wurde gelöscht. Bei der Definition des I/O Device (z.B. beim Start von FHEM) wird der Befehl automatisch ausgeführt.
Der Befehl get ccuDevices zeigt eine Liste der in der CCU bekannten Geräte an inklusive einer Liste der Kanalrollen, die von HMCCU automatisch erkannt werden. Daran kann man erkennen, welche CCU-Geräte von den Befehlen get create und get createDev unterstützt werden.
Datenpunkte (Readings) synchronisieren
Eine manuelle Aktualisierung der Datenpunkte sollte nicht notwendig sein. Die Aktualisierung erfolgt automatisch durch die CCU per RPC-Server Verbindung. 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 FHEM-Devices für CCU Geräte
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen, sofern HMCCU eine oder mehrere Kanalrollen des betreffenden Gerätetyps unterstützt. Dazu kann entweder der Befehl get createDev (für ein einzelnes CCU Gerät) oder der Befehl get create (für mehrere CCU Geräte) verwenden werden.
Die beiden Befehle zur automatischen Erzeugung von HMCCUDEV/HMCCUCHN Devices beziehen sich immer auf CCU-Geräte, nicht deren Kanäle. Bei der Erzeugung der FHEM-Devices entscheidet HMCCU selbständig, ob ein oder mehrere HMCCUDEV oder HMCCUCHN Devices angelegt werden. Nach Ausführung der Befehle werden in einem Fenster die angelegten oder auch nicht erkannten Geräte angezeigt.
Beispiel: Für das CCU-Gerät "Heizung-Wohnzimmer" soll ein FHEM-Device angelegt werden:
get d_ccu createDev Heizung-Wohnzimmer
Beispiel: Für alle CCU-Geräte, deren Namen mit "Heizung" beginnt, sollen FHEM-Devices angelegt werden:
get d_ccu create Heizung.* room=Homematic group=Heizung
Beim vorherigen Beispiel wird als Gerätename ein regulärer Ausdruck ("Heizung.*) angegeben. Jedes angelegte Gerät bekommt die Attribute "room" und "group" zugewiesen.
Wenn ein CCU-Gerät mehrere identische Kanalrollen besitzt, erzeugt HMCCU für jeden Kanal ein HMCCUCHN-Device. Ein Beispiel für solche CCU-Geräte sind Fernbedienungen, die 2-16 Kanäle der Rolle "KEY" besitzen.
Beispiel: Für die 2-Kanal-Fernbedienung FB-Rollladen werden 2 HMCCUCHN Devices angelegt. Die Namen der Devices werden aus den Kanalnamen der Fernbedienung in der CCU gebildet:
get d_ccu createDev FB-Rollladen
erzeugt die HMCCUCHN Devices: FB-Rollladen-Wohnzimmer, FB-Rollladen-Kueche.
Die Attribute der automatisch angelegten Devices können über die I/O Device Attribute ccudef-attributes und createDeviceGroup beeinflusst werden. Um allen neu angelegten Devices das Attribut room=Homematic zuzuweisen, definiert man folgendes Attribut im I/O Device:
attr d_ccu ccudef-attributes room=Homematic
Mit dem Attribut createDeviceGroup können Einzel-Devices, die alle zu einem CCU-Gerät gehören, automatisch in einer FHEM-Gruppe zusammengefasst werden. Dieses Attribut kommt z.B. zur Anwendung, wenn man get createDev für eine Fernbedienung mit mehreren Kanälen ausführt. In diesem Fall legt HMCCU für jeden Kanal der Fernbedienung ein HMCCUCHN Device an. Mit dem folgenden Attribut im I/O Device werden diese HMCCUCHN Devices alle einer Gruppe zugeordnet, deren Name dem Gerätenamen in der CCU entspricht:
attr d_ccu createDeviceGroup %n
Die möglichen Platzhalter (wie z.B. %n) können der Commandref entnommen werden.
Weitere Funktionen des Moduls HMCCU
Lesen und Ändern von CCU Systemvariablen
Systemvariablen der CCU können mit den Befehlen get vars und set var gelesen und geändert werden. Der Befehl get vars akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden. Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert.
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:
get d_ccu vars A.*
Systemvariablen können in regelmäßigen Abständen gelesen werden. Dazu wird mit dem Attribut ccuGetVars ein Intervall und optional ein regulärer Ausdruck für die zu lesenden Systemvariablen festgelegt.
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:
attr d_ccu ccuGetVars 60 attr d_ccu ccuGetVars 60:^A
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl set var geändert werden.
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:
set d_ccu var Temperatur 20.5
Mit dem Befehl set var kann auch eine neue Systemvariable in der CCU angelegt werden. Dazu wird als erster Parameter vor dem Variablennamen der Typ der neuen Variable angegeben. Mögliche Typen sind "bool", "list", "number" oder "text".
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":
set d_ccu var text Wetter sonnig
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:
- unit = Einheit
- desc = Beschreibung
- min = Kleinster erlaubter Wert bei numerischen Variablen
- max = Größter erlaubter Wert bei numerischen Variablen
- list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen
- valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"
- valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:
set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0
Ausführen von CCU 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 CCU aktiv oder inaktiv ist.
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:
set d_ccu execute Schalter_Ein
Aggregation von Gerätezuständen
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 Aggregationsregel 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 einen 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