http://wiki.fhem.de/w/api.php?action=feedcontributions&user=Zap&feedformat=atomFHEMWiki - Benutzerbeiträge [de]2024-03-28T14:58:24ZBenutzerbeiträgeMediaWiki 1.39.3http://wiki.fhem.de/w/index.php?title=HMCCUDEV&diff=38784HMCCUDEV2023-12-10T12:02:03Z<p>Zap: /* Steuern von Homematic Geräten über Datenpunkte */</p>
<hr />
<div>{{Baustelle}}<br />
<div style="float:right"><br />
{{Infobox Modul<br />
|ModPurpose=HMCCU Client Device für Homematic Geräte<br />
|ModType=d<br />
|ModCmdRef=HMCCUDEV<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCUDEV.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
{{Infobox Modul<br />
|ModPurpose=HMCCU Client Device für Homematic Kanäle<br />
|ModType=d<br />
|ModCmdRef=HMCCUCHN<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCUCHN.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
</div><br />
==Übersicht==<br />
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.<br />
<br />
Wann verwendet man HMCCUCHN, wann HMCCUDEV?<br />
<br />
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.<br />
<br />
==Definition von FHEM Devices==<br />
===Basisdefintion===<br />
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):<br />
<pre><br />
define <name> HMCCUCHN <channel> [defaults] [readonly]<br />
define <name> HMCCUDEV <device> [defaults] [readonly]<br />
</pre><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/><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.<br />
<br />
===Virtuelle CCU Geräte===<br />
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.<br />
<br />
Das Modul HMCCUDEV unterstützt virtuelle Geräte. Bei der Definition in FHEM müssen einige zusätzliche Angaben gemacht werden:<br />
<br />
<pre>define <name> HMCCUDEV <groupdevice> group=<device>[,...] [defaults] [readonly]</pre><br />
<br />
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.<br />
<br />
Damit virtuelle Devices automatisch aktualisiert werden, muss im I/O Device ein RPC-Server für den Port 9292 gestartet werden (Attribut ''rpcport'').<br />
<br />
==Datenpunkte und Readings==<br />
===Arten von Datenpunkten===<br />
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:<br />
* Write – Schreiben von Werten (z.B. Setzen einer Zieltemperatur für einen Thermostaten, Einschalten einer Steckdose).<br />
* Read – Lesen von Werten. Beim Auslesen wird der Wert in ein Reading des zugehörigen FHEM Devices geschrieben.<br />
* 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.<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
CHN MEQ1117422:0 ST-WZ-Lampe2:0 <br />
DPT {b} BidCos-RF.MEQ1117422:0.UNREACH = true [RE] <br />
DPT {b} BidCos-RF.MEQ1117422:0.STICKY_UNREACH = true [RWE] <br />
DPT {b} BidCos-RF.MEQ1117422:0.CONFIG_PENDING = false [RE] <br />
DPT {b} BidCos-RF.MEQ1117422:0.DUTYCYCLE = false [RE] <br />
DPT {n} BidCos-RF.MEQ1117422:0.RSSI_DEVICE = 1 [RE] <br />
DPT {n} BidCos-RF.MEQ1117422:0.RSSI_PEER = 1 [RE] <br />
DPT {b} BidCos-RF.MEQ1117422:0.DEVICE_IN_BOOTLOADER = false [RE] <br />
DPT {b} BidCos-RF.MEQ1117422:0.UPDATE_PENDING = false [RE] <br />
DPT {n} BidCos-RF.MEQ1117422:0.AES_KEY = 0 [R] <br />
CHN MEQ1117422:1 ST-WZ-Lampe2:1 <br />
DPT {6} BidCos-RF.MEQ1117422:1.LEVEL = 0.000000 [RWE] <br />
DPT {b} BidCos-RF.MEQ1117422:1.OLD_LEVEL = [W] <br />
DPT {f} BidCos-RF.MEQ1117422:1.LEVEL_REAL = 0.000000 [RE] <br />
DPT {f} BidCos-RF.MEQ1117422:1.RAMP_TIME = [W] <br />
DPT {f} BidCos-RF.MEQ1117422:1.ON_TIME = [W] <br />
DPT {b} BidCos-RF.MEQ1117422:1.RAMP_STOP = [W] <br />
DPT {b} BidCos-RF.MEQ1117422:1.INHIBIT = false [RWE] <br />
DPT {b} BidCos-RF.MEQ1117422:1.ERROR_REDUCED = false [RE] <br />
DPT {b} BidCos-RF.MEQ1117422:1.ERROR_OVERLOAD = false [RE] <br />
DPT {b} BidCos-RF.MEQ1117422:1.ERROR_OVERHEAT = false [RE] <br />
DPT {i} BidCos-RF.MEQ1117422:1.DIRECTION = 0 [RE] <br />
DPT {b} BidCos-RF.MEQ1117422:1.INSTALL_TEST = [W] <br />
DPT {b} BidCos-RF.MEQ1117422:1.WORKING = false [RE]<br />
</pre><br />
<br />
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).<br />
<br />
===Konfigurationsparameter===<br />
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.<br />
<br />
Ä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.<br />
<br />
===Darstellung von Datenpunkten in FHEM===<br />
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:<br />
<br />
:'''''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.<br />
<br />
:'''''ccureadingformat''''' – Legt fest, wie aus dem Namen bzw. der Adresse eines Datenpunktes der Readingname in FHEM gebildet wird. Folgende Formate werden unterstützt:<br />
:*datapoint - Die Readingnames werden aus der Kanalnummer und dem Namen des Datenpunktes gebildet<br />
:*name - Ein Readingname entspricht dem Kanalnamen in der CCU gefolgt vom Namen des Datenpunktes<br />
:*address - Die Readingnames setzen sich aus der Kanaladresse und dem Namen des Datenpunktes zusammen<br />
:Der Zusatz "lc" wandelt die Readingnames in Kleinbuchstaben um.<br />
<br />
:'''''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><br />
<br />
:'''''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/><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/><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/><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><br />
<br />
:'''''substitute''''' – Ersetzt Datenpunkt-Werte durch Texte.<br />
<br />
:'''''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<br />
<br />
:'''''controldatapoint''''' – Legt den Datenpunkt fest, der im Reading „control“ eines FHEM Devices gespeichert wird. Beispiel: 1.LEVEL<br />
<br />
===Steuern von Homematic Geräten über Datenpunkte===<br />
<br />
==== Befehlssyntax ====<br />
Mit dem Befehl '''set datapoint''' können Werte von Datenpunkten in der CCU2 geändert werden. Die Syntax des Befehls lautet:<br />
<pre>set <device> datapoint <datapointSpec> <value> [...]<br />
set <device> datapoint <datapointSpec>=<value> [...]</pre><br />
Der Parameter ''datapointSpec'' beschreibt den zu setzenden Datenpunkt in folgendem Format:<br />
datapointSpec := [<seqNum>:][<channelNum>.]<datapointName><br />
''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.<br />
<br />
''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.<br />
<br />
''datapointName'' - Der Name des Datenpunktes.<br />
<br />
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").<br />
<br />
==== Datenpunktwerte ====<br />
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.<br />
<br />
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.<br />
<br />
Werte von Text-Datenpunkte sollten in doppelten Hochkomma eingeschlossen sein:<br />
set myDev datapoint COMBINED="Das ist ein Text"<br />
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.<br />
set myDev datapoint LEVEL 1.005<br />
<br />
==== Beispiele ====<br />
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:<br />
<pre>set myDev datapoint 1:1.ON_TIME=60 2:1.STATE=1</pre><br />
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.<br />
<br />
Beispiel 2: Umschalten eines Gerätes auf den vorherigen Wert:<br />
set myDev datapoint 1.LEVEL oldVal<br />
==Darstellung in der FHEM Oberfläche==<br />
<br />
<br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=AndroidDB&diff=37339AndroidDB2022-03-24T10:53:05Z<p>Zap: Erzeugung von Readings</p>
<hr />
<div>{{Infobox Modul|ModPurpose=Steuerung von Android Geräten|ModType=d|ModForumArea=Sonstiges|ModTechName=89_AndroidDB|ModOwner=zap}}<br />
<br />
== Allgemeines ==<br />
Die Module AndroidDB und AndroidDBHost erlauben die Steuerung von Android Geräten über die Android Debug Bridge (ADB). Man kann z.B. Befehle auf Android Geräten ausführen, Android Geräte neu starten oder Tastatur- und Touchscreen-Eingaben an Android Geräte senden und so eine Fernbedienung simulieren. Die Module wurden primär entwickelt, um Android TV Geräte zu steuern, sollten aber auch mit Tablets oder Telefonen funktionieren. Ein "rooten" der zu steuernden Geräte ist nicht erforderlich!<br />
<br />
Die Module wurden mit folgenden Geräten getestet:<br />
* Samsung Android Tablet<br />
* SONY Android TV AF9<br />
* Magenta TV Stick<br />
* Magenta One<br />
* NVidia Shield<br />
Einige mögliche Befehle als Anwendungsbeispiele:<br />
* Aufnahmetaste drücken: '''set myTVDev remoteControl RECORD'''<br />
* Neu starten: '''set myTVDev reboot'''<br />
* Installierte Apps anzeigen: '''set myTVDev shell pm list packages'''<br />
<br />
== Installation ==<br />
Voraussetzungen für die Nutzung der Module in FHEM:<br />
* Installation des Perl Moduls IPC::Open3<br />
* Installation der Android Plattform Tools<br />
Für die Installation des Perl Moduls verwendet man CPAN. Die Android Plattform Tools werden unter Debian/Raspbian mit dem folgenden Befehl installiert:<syntaxhighlight lang="shell"><br />
apt-get install android-sdk-platform-tools<br />
</syntaxhighlight>Für andere Plattformen (Windows, Linux x86, MacOS) findet man die Tools hier: https://developer.android.com/studio/releases/platform-tools<br />
<br />
Bei der manuellen Installation der Tools von developer.android.com (MacOs und Linux) muss man darauf achten, dass der Nutzer, unter dem der FHEM Prozess läuft, den Befehl 'adb' ausführen darf. Dazu ggf. die Rechte auf 'read' und 'execute' für alle setzen:<syntaxhighlight lang="shell"><br />
sudo chmod 755 adb<br />
</syntaxhighlight><br />
<br />
== Definition eines I/O Device (AndroidDBHost) ==<br />
Je FHEM Instanz gibt es nur 1 I/O Device. Die Syntax für die Definition sieht so aus:<br />
define ''Name'' AndroidDBHost [adb=''Pfadangabe'']<br />
Die Angabe des Parameters 'adb' ist nur erforderlich, wenn sich der Befehl 'adb' nicht im Suchpfad für ausführbare Programme befindet. Beispiel:<br />
define myADBServer AndroidDBHost adb=/usr/local/platform-tools/adb<br />
<br />
== Defintion von Android Devices in FHEM (AndroidDB) ==<br />
<br />
=== Android Gerät vorbereiten ===<br />
Auf jedem Android Device, das über AndroidDB gesteuert werden soll, muss der Entwicklermodus aktiviert und das USB Debugging eingeschaltet sein. Dies sollte auf jedem Android Gerät ohne "root" Berechtigung möglich sein.<br />
<br />
Die Aktivierung des Entwicklermodus kann sich von Gerät zu Gerät etwas unterscheiden, ist aber meist ähnlich. Bei Android TV Geräten geht man so vor (einmalige Aktion je Gerät):<br />
# Sollte das Android Gerät einen USB-Anschluss haben, sollte daran kein Gerät angeschlossen sein (z.B. LAN-Adapter bei TV Geräten)<br />
# Auf dem Android Gerät ''Geräteeinstellungen'' > ''Info'' auswählen<br />
# Ganz nach unten scrollen bis zu einer Angabe, die meistens "Build" oder "Version" heißt<br />
# Auf diese Angabe wiederholt drücken. Android zeigt dann irgendwann die Meldung "in X Schritten bist Du Entwickler" an. Dann noch X Mal drücken bis "Du bist jetzt Entwickler" angezeigt wird<br />
# Nun unter Geräteeinstellungen > Entwickleroptionen das USB-Debugging einschalten (heißt zwar USB, die Verbindung erfolgt aber über das Netzwerk)<br />
# Sollte sich das USB-Debugging nicht aktivieren lassen, das Android Gerät neu starten. Dies kann vorkommen, wenn ein Gerät per USB angeschlossen war (siehe 1)<br />
<br />
=== AndroidDB Device in FHEM definieren ===<br />
Nun kann man ein AndroidDB Device in FHEM definieren:<br />
define myTV AndroidDB 192.168.1.100<br />
Einziger Parameter ist die IP-Adresse des Android-Geräts (man sollte eine feste IP zuordnen). Beim ersten Zugriff auf das Gerät kann es sein, dass man auf dem Gerät einmal die Verbindung von FHEM zulassen muss. In dem Fall sollte man den Haken bei "Zugriff immer erlauben" setzen.<br />
<br />
== Steuerung von Android Devices in FHEM ==<br />
<br />
=== Tastatureingaben senden ===<br />
Eine der nützlichsten Funktionen dürfte das Senden von Tastendrücken sein. So kann man in FHEM eine Fernbedienung oder auch die Sprachsteuerung von Android Geräten realisieren.<br />
<br />
Beispiel: Home-Taste drücken<br />
set myTV sendKey KEYCODE_HOME<br />
Beispiel: Umschalten auf Programm 12 / mehrere Keycodes senden:<br />
set myTV sendkey KEYCODE_1 KEYCODE_2<br />
Eine Liste der Keycodes findet man hier: https://developer.android.com/reference/android/view/KeyEvent<br />
<br />
Weitere Befehle zum Senden von Tastatureingaben sind '''set sendNumKeys''' und '''set sendText'''.<br />
<br />
=== Makros ===<br />
Ein Makro fasst eine Folge von Tastatureingaben oder einen ADB-Befehl unter einem Befehl zusammen. Tastaturmakros können anschließend mit dem Befehl '''set remoteControl''' ausgeführt werden. Makros für ADB-Befehle stehen als set-Befehle zur Verfügung.<br />
<br />
Beispiel: Es wird ein Makro "DasErste" definiert, bei dessen Ausführung die Sequenz "0001" an ein Android TV Gerät gesendet wird:<br />
attr myTV macros DasErste:KEYCODE_0,KEYCODE_0,KEYCODE_0,KEYCODE_1<br />
set myTV remoteControl DasErste<br />
Beispiel: Es wird ein Makro "listPackages" zum Auflisten aller Apps definiert, die auf einem Android-Device installiert sind:<br />
attr myTV macros listPackages:shell pm list packages<br />
set myTV listPackages<br />
<br />
=== Presets ===<br />
Presets sind eine Liste von Makrodefinitionen. AndroidDB hat Presets bereits eingebaut für Magenta TV Stick, Magenta One. Man kann eigene Presets in einer Datei definieren und mit dem Attribut 'presetFile' laden. Eine solche Preset-Datei kann mehrere Preset-Definitionen enthalten. Ein Preset kann mit dem Attribut 'preset' ausgewählt werden.<br />
<br />
Eine Preset-Datei hat folgenden Aufbau:<syntaxhighlight lang="text"><br />
# Kommentar<br />
PresetName1<br />
MacroName1:MacroDef1[,...]<br />
MacroName2:MacroDef2[,...]<br />
...<br />
PresetName2<br />
...<br />
<br />
</syntaxhighlight>Ein ''MacroName'' darf keine Leerzeichen enthalten. Der Parameter ''MacroDef'' steht entweder für eine Liste von Keycodes oder einen ADB-Befehl. Siehe auch Abschnitt "Makros".<br />
<br />
Um eine eigene Preset-Datei zu erstellen, kann man die internen Definitionen von AndroidDB mit dem Befehl '''set exportPresets''' als Preset-Datei exportieren und diese Datei dann anpassen:<br />
set myTV exportPresets /home/fhem/android.dat<br />
Beispiel: Eine Preset-Datei wurde unter dem Namen "/home/fhem/android.dat" angelegt. Sie enthält 2 Presets mit den Namen "SonyTV" und "FireTV".<br />
<br />
Preset-Datei laden:<br />
attr myTV presetFile /home/fhem/android.dat<br />
Preset auswählen:<br />
attr myTV preset SonyTV <br />
<br />
=== Fernbedienungen ===<br />
AndroidDB unterstützt das Anlegen von Remotecontrol-Devices mit dem FHEM Modul remotecontrol. Für die eingebauten Presets kann eine Fernbedienung mit dem Befehl set createRemote angelegt werden:<br />
set myTV createRemote MagentaOne<br />
AndroidDB legt damit zwei neue FHEM devices an:<br />
* Ein Device vom Typ "remotecontrol" mit dem Namen "myTV_RC"<br />
* Ein Device vom Typ "notify" mit dem Namen "notify_myTV_RC" (Weiterleitung der Tastendrücke aus "myTV_RC" an "myTV")<br />
Beispiel:<br />
[[Datei:SampleRemote.png|links|Remote control created by set createRemote command|alternativtext=|512x512px]]<br />
<br />
[[Kategorie:Android]]<br />
<br />
== Erzeugen von Readings ==<br />
Die Ausgabe von "shell" Befehlen kann in FHEM Readings konvertiert werden. Voraussetzung ist, dass die Ausgabe eine oder mehrere Zeilen im Format "Parameter=Wert" enthält. Führende Leerzeichen werden dabei automatisch entfernt.<br />
<br />
Zunächst legt man mit dem Attribut createReadings fest, für welche Shell-Befehle Readings erzeugt werden sollen. Das Argument dieses Attributs ist ein regulärer Ausdruck.<br />
<br />
Beispiel: Die Ausgabe des Befehls "set shell dumpsys" soll in Readings gespeichert werden: <br />
attr myDev createReadings dumpsys<br />
Befehl ausführen:<br />
set myDev shell dumpsys power</div>Zaphttp://wiki.fhem.de/w/index.php?title=AndroidDB&diff=37287AndroidDB2022-03-10T18:03:10Z<p>Zap: Infobox hinzugefügt</p>
<hr />
<div>{{Infobox Modul|ModPurpose=Steuerung von Android Geräten|ModType=d|ModForumArea=Sonstiges|ModTechName=89_AndroidDB|ModOwner=zap}}<br />
<br />
== Allgemeines ==<br />
Die Module AndroidDB und AndroidDBHost erlauben die Steuerung von Android Geräten über die Android Debug Bridge (ADB). Man kann z.B. Befehle auf Android Geräten ausführen, Android Geräte neu starten oder Tastatur- und Touchscreen-Eingaben an Android Geräte senden und so eine Fernbedienung simulieren. Die Module wurden primär entwickelt, um Android TV Geräte zu steuern, sollten aber auch mit Tablets oder Telefonen funktionieren. Ein "rooten" der zu steuernden Geräte ist nicht erforderlich!<br />
<br />
Die Module wurden mit folgenden Geräten getestet:<br />
* Samsung Android Tablet<br />
* SONY Android TV AF9<br />
* Magenta TV Stick<br />
* Magenta One<br />
* NVidia Shield<br />
Einige mögliche Befehle als Anwendungsbeispiele:<br />
* Aufnahmetaste drücken: '''set myTVDev remoteControl RECORD'''<br />
* Neu starten: '''set myTVDev reboot'''<br />
* Installierte Apps anzeigen: '''set myTVDev shell pm list packages'''<br />
<br />
== Installation ==<br />
Voraussetzungen für die Nutzung der Module in FHEM:<br />
* Installation des Perl Moduls IPC::Open3<br />
* Installation der Android Plattform Tools<br />
Für die Installation des Perl Moduls verwendet man CPAN. Die Android Plattform Tools werden unter Debian/Raspbian mit dem folgenden Befehl installiert:<syntaxhighlight lang="shell"><br />
apt-get install android-sdk-platform-tools<br />
</syntaxhighlight>Für andere Plattformen (Windows, Linux x86, MacOS) findet man die Tools hier: https://developer.android.com/studio/releases/platform-tools<br />
<br />
Bei der manuellen Installation der Tools von developer.android.com (MacOs und Linux) muss man darauf achten, dass der Nutzer, unter dem der FHEM Prozess läuft, den Befehl 'adb' ausführen darf. Dazu ggf. die Rechte auf 'read' und 'execute' für alle setzen:<syntaxhighlight lang="shell"><br />
sudo chmod 755 adb<br />
</syntaxhighlight><br />
<br />
== Definition eines I/O Device (AndroidDBHost) ==<br />
Je FHEM Instanz gibt es nur 1 I/O Device. Die Syntax für die Definition sieht so aus:<br />
define ''Name'' AndroidDBHost [adb=''Pfadangabe'']<br />
Die Angabe des Parameters 'adb' ist nur erforderlich, wenn sich der Befehl 'adb' nicht im Suchpfad für ausführbare Programme befindet. Beispiel:<br />
define myADBServer AndroidDBHost adb=/usr/local/platform-tools/adb<br />
<br />
== Defintion von Android Devices in FHEM (AndroidDB) ==<br />
<br />
=== Android Gerät vorbereiten ===<br />
Auf jedem Android Device, das über AndroidDB gesteuert werden soll, muss der Entwicklermodus aktiviert und das USB Debugging eingeschaltet sein. Dies sollte auf jedem Android Gerät ohne "root" Berechtigung möglich sein.<br />
<br />
Die Aktivierung des Entwicklermodus kann sich von Gerät zu Gerät etwas unterscheiden, ist aber meist ähnlich. Bei Android TV Geräten geht man so vor (einmalige Aktion je Gerät):<br />
# Sollte das Android Gerät einen USB-Anschluss haben, sollte daran kein Gerät angeschlossen sein (z.B. LAN-Adapter bei TV Geräten)<br />
# Auf dem Android Gerät ''Geräteeinstellungen'' > ''Info'' auswählen<br />
# Ganz nach unten scrollen bis zu einer Angabe, die meistens "Build" oder "Version" heißt<br />
# Auf diese Angabe wiederholt drücken. Android zeigt dann irgendwann die Meldung "in X Schritten bist Du Entwickler" an. Dann noch X Mal drücken bis "Du bist jetzt Entwickler" angezeigt wird<br />
# Nun unter Geräteeinstellungen > Entwickleroptionen das USB-Debugging einschalten (heißt zwar USB, die Verbindung erfolgt aber über das Netzwerk)<br />
# Sollte sich das USB-Debugging nicht aktivieren lassen, das Android Gerät neu starten. Dies kann vorkommen, wenn ein Gerät per USB angeschlossen war (siehe 1)<br />
<br />
=== AndroidDB Device in FHEM definieren ===<br />
Nun kann man ein AndroidDB Device in FHEM definieren:<br />
define myTV AndroidDB 192.168.1.100<br />
Einziger Parameter ist die IP-Adresse des Android-Geräts (man sollte eine feste IP zuordnen). Beim ersten Zugriff auf das Gerät kann es sein, dass man auf dem Gerät einmal die Verbindung von FHEM zulassen muss. In dem Fall sollte man den Haken bei "Zugriff immer erlauben" setzen.<br />
<br />
== Steuerung von Android Devices in FHEM ==<br />
<br />
=== Tastatureingaben senden ===<br />
Eine der nützlichsten Funktionen dürfte das Senden von Tastendrücken sein. So kann man in FHEM eine Fernbedienung oder auch die Sprachsteuerung von Android Geräten realisieren.<br />
<br />
Beispiel: Home-Taste drücken<br />
set myTV sendKey KEYCODE_HOME<br />
Beispiel: Umschalten auf Programm 12 / mehrere Keycodes senden:<br />
set myTV sendkey KEYCODE_1 KEYCODE_2<br />
Eine Liste der Keycodes findet man hier: https://developer.android.com/reference/android/view/KeyEvent<br />
<br />
Weitere Befehle zum Senden von Tastatureingaben sind '''set sendNumKeys''' und '''set sendText'''.<br />
<br />
=== Makros ===<br />
Ein Makro fasst eine Folge von Tastatureingaben oder einen ADB-Befehl unter einem Befehl zusammen. Tastaturmakros können anschließend mit dem Befehl '''set remoteControl''' ausgeführt werden. Makros für ADB-Befehle stehen als set-Befehle zur Verfügung.<br />
<br />
Beispiel: Es wird ein Makro "DasErste" definiert, bei dessen Ausführung die Sequenz "0001" an ein Android TV Gerät gesendet wird:<br />
attr myTV macros DasErste:KEYCODE_0,KEYCODE_0,KEYCODE_0,KEYCODE_1<br />
set myTV remoteControl DasErste<br />
Beispiel: Es wird ein Makro "listPackages" zum Auflisten aller Apps definiert, die auf einem Android-Device installiert sind:<br />
attr myTV macros listPackages:shell pm list packages<br />
set myTV listPackages<br />
<br />
=== Presets ===<br />
Presets sind eine Liste von Makrodefinitionen. AndroidDB hat Presets bereits eingebaut für Magenta TV Stick, Magenta One. Man kann eigene Presets in einer Datei definieren und mit dem Attribut 'presetFile' laden. Eine solche Preset-Datei kann mehrere Preset-Definitionen enthalten. Ein Preset kann mit dem Attribut 'preset' ausgewählt werden.<br />
<br />
Eine Preset-Datei hat folgenden Aufbau:<syntaxhighlight lang="text"><br />
# Kommentar<br />
PresetName1<br />
MacroName1:MacroDef1[,...]<br />
MacroName2:MacroDef2[,...]<br />
...<br />
PresetName2<br />
...<br />
<br />
</syntaxhighlight>Ein ''MacroName'' darf keine Leerzeichen enthalten. Der Parameter ''MacroDef'' steht entweder für eine Liste von Keycodes oder einen ADB-Befehl. Siehe auch Abschnitt "Makros".<br />
<br />
Um eine eigene Preset-Datei zu erstellen, kann man die internen Definitionen von AndroidDB mit dem Befehl '''set exportPresets''' als Preset-Datei exportieren und diese Datei dann anpassen:<br />
set myTV exportPresets /home/fhem/android.dat<br />
Beispiel: Eine Preset-Datei wurde unter dem Namen "/home/fhem/android.dat" angelegt. Sie enthält 2 Presets mit den Namen "SonyTV" und "FireTV".<br />
<br />
Preset-Datei laden:<br />
attr myTV presetFile /home/fhem/android.dat<br />
Preset auswählen:<br />
attr myTV preset SonyTV <br />
<br />
=== Fernbedienungen ===<br />
AndroidDB unterstützt das Anlegen von Remotecontrol-Devices mit dem FHEM Modul remotecontrol. Für die eingebauten Presets kann eine Fernbedienung mit dem Befehl set createRemote angelegt werden:<br />
set myTV createRemote MagentaOne<br />
AndroidDB legt damit zwei neue FHEM devices an:<br />
* Ein Device vom Typ "remotecontrol" mit dem Namen "myTV_RC"<br />
* Ein Device vom Typ "notify" mit dem Namen "notify_myTV_RC" (Weiterleitung der Tastendrücke aus "myTV_RC" an "myTV")<br />
Beispiel:<br />
[[Datei:SampleRemote.png|links|Remote control created by set createRemote command|alternativtext=|512x512px]]<br />
<br />
[[Kategorie:Android]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=AndroidDB&diff=37264AndroidDB2022-02-24T12:40:16Z<p>Zap: </p>
<hr />
<div>== Allgemeines ==<br />
Die Module AndroidDB und AndroidDBHost erlauben die Steuerung von Android Geräten über die Android Debug Bridge (ADB). Man kann z.B. Befehle auf Android Geräten ausführen, Android Geräte neu starten oder Tastatur- und Touchscreen-Eingaben an Android Geräte senden und so eine Fernbedienung simulieren. Die Module wurden primär entwickelt, um Android TV Geräte zu steuern, sollten aber auch mit Tablets oder Telefonen funktionieren. Ein "rooten" der zu steuernden Geräte ist nicht erforderlich!<br />
<br />
Die Module wurden mit folgenden Geräten getestet:<br />
* Samsung Android Tablet<br />
* SONY Android TV AF9<br />
* Magenta TV Stick<br />
* Magenta One<br />
* NVidia Shield<br />
Einige mögliche Befehle als Anwendungsbeispiele:<br />
* Aufnahmetaste drücken: '''set myTVDev remoteControl RECORD'''<br />
* Neu starten: '''set myTVDev reboot'''<br />
* Installierte Apps anzeigen: '''set myTVDev shell pm list packages'''<br />
<br />
== Installation ==<br />
Voraussetzungen für die Nutzung der Module in FHEM:<br />
* Installation des Perl Moduls IPC::Open3<br />
* Installation der Android Plattform Tools<br />
Für die Installation des Perl Moduls verwendet man CPAN. Die Android Plattform Tools werden unter Debian/Raspbian mit dem folgenden Befehl installiert:<syntaxhighlight lang="shell"><br />
apt-get install android-sdk-platform-tools<br />
</syntaxhighlight>Für andere Plattformen (Windows, Linux x86, MacOS) findet man die Tools hier: https://developer.android.com/studio/releases/platform-tools<br />
<br />
Bei der manuellen Installation der Tools von developer.android.com (MacOs und Linux) muss man darauf achten, dass der Nutzer, unter dem der FHEM Prozess läuft, den Befehl 'adb' ausführen darf. Dazu ggf. die Rechte auf 'read' und 'execute' für alle setzen:<syntaxhighlight lang="shell"><br />
sudo chmod 755 adb<br />
</syntaxhighlight><br />
<br />
== Definition eines I/O Device (AndroidDBHost) ==<br />
Je FHEM Instanz gibt es nur 1 I/O Device. Die Syntax für die Definition sieht so aus:<br />
define ''Name'' AndroidDBHost [adb=''Pfadangabe'']<br />
Die Angabe des Parameters 'adb' ist nur erforderlich, wenn sich der Befehl 'adb' nicht im Suchpfad für ausführbare Programme befindet. Beispiel:<br />
define myADBServer AndroidDBHost adb=/usr/local/platform-tools/adb<br />
<br />
== Defintion von Android Devices in FHEM (AndroidDB) ==<br />
<br />
=== Android Gerät vorbereiten ===<br />
Auf jedem Android Device, das über AndroidDB gesteuert werden soll, muss der Entwicklermodus aktiviert und das USB Debugging eingeschaltet sein. Dies sollte auf jedem Android Gerät ohne "root" Berechtigung möglich sein.<br />
<br />
Die Aktivierung des Entwicklermodus kann sich von Gerät zu Gerät etwas unterscheiden, ist aber meist ähnlich. Bei Android TV Geräten geht man so vor (einmalige Aktion je Gerät):<br />
# Sollte das Android Gerät einen USB-Anschluss haben, sollte daran kein Gerät angeschlossen sein (z.B. LAN-Adapter bei TV Geräten)<br />
# Auf dem Android Gerät ''Geräteeinstellungen'' > ''Info'' auswählen<br />
# Ganz nach unten scrollen bis zu einer Angabe, die meistens "Build" oder "Version" heißt<br />
# Auf diese Angabe wiederholt drücken. Android zeigt dann irgendwann die Meldung "in X Schritten bist Du Entwickler" an. Dann noch X Mal drücken bis "Du bist jetzt Entwickler" angezeigt wird<br />
# Nun unter Geräteeinstellungen > Entwickleroptionen das USB-Debugging einschalten (heißt zwar USB, die Verbindung erfolgt aber über das Netzwerk)<br />
# Sollte sich das USB-Debugging nicht aktivieren lassen, das Android Gerät neu starten. Dies kann vorkommen, wenn ein Gerät per USB angeschlossen war (siehe 1)<br />
<br />
=== AndroidDB Device in FHEM definieren ===<br />
Nun kann man ein AndroidDB Device in FHEM definieren:<br />
define myTV AndroidDB 192.168.1.100<br />
Einziger Parameter ist die IP-Adresse des Android-Geräts (man sollte eine feste IP zuordnen). Beim ersten Zugriff auf das Gerät kann es sein, dass man auf dem Gerät einmal die Verbindung von FHEM zulassen muss. In dem Fall sollte man den Haken bei "Zugriff immer erlauben" setzen.<br />
<br />
== Steuerung von Android Devices in FHEM ==<br />
<br />
=== Tastatureingaben senden ===<br />
Eine der nützlichsten Funktionen dürfte das Senden von Tastendrücken sein. So kann man in FHEM eine Fernbedienung oder auch die Sprachsteuerung von Android Geräten realisieren.<br />
<br />
Beispiel: Home-Taste drücken<br />
set myTV sendKey KEYCODE_HOME<br />
Beispiel: Umschalten auf Programm 12 / mehrere Keycodes senden:<br />
set myTV sendkey KEYCODE_1 KEYCODE_2<br />
Eine Liste der Keycodes findet man hier: https://developer.android.com/reference/android/view/KeyEvent<br />
<br />
Weitere Befehle zum Senden von Tastatureingaben sind '''set sendNumKeys''' und '''set sendText'''.<br />
<br />
=== Makros ===<br />
Ein Makro fasst eine Folge von Tastatureingaben oder einen ADB-Befehl unter einem Befehl zusammen. Tastaturmakros können anschließend mit dem Befehl '''set remoteControl''' ausgeführt werden. Makros für ADB-Befehle stehen als set-Befehle zur Verfügung.<br />
<br />
Beispiel: Es wird ein Makro "DasErste" definiert, bei dessen Ausführung die Sequenz "0001" an ein Android TV Gerät gesendet wird:<br />
attr myTV macros DasErste:KEYCODE_0,KEYCODE_0,KEYCODE_0,KEYCODE_1<br />
set myTV remoteControl DasErste<br />
Beispiel: Es wird ein Makro "listPackages" zum Auflisten aller Apps definiert, die auf einem Android-Device installiert sind:<br />
attr myTV macros listPackages:shell pm list packages<br />
set myTV listPackages<br />
<br />
=== Presets ===<br />
Presets sind eine Liste von Makrodefinitionen. AndroidDB hat Presets bereits eingebaut für Magenta TV Stick, Magenta One. Man kann eigene Presets in einer Datei definieren und mit dem Attribut 'presetFile' laden. Eine solche Preset-Datei kann mehrere Preset-Definitionen enthalten. Ein Preset kann mit dem Attribut 'preset' ausgewählt werden.<br />
<br />
Eine Preset-Datei hat folgenden Aufbau:<syntaxhighlight lang="text"><br />
# Kommentar<br />
PresetName1<br />
MacroName1:MacroDef1[,...]<br />
MacroName2:MacroDef2[,...]<br />
...<br />
PresetName2<br />
...<br />
<br />
</syntaxhighlight>Ein ''MacroName'' darf keine Leerzeichen enthalten. Der Parameter ''MacroDef'' steht entweder für eine Liste von Keycodes oder einen ADB-Befehl. Siehe auch Abschnitt "Makros".<br />
<br />
Um eine eigene Preset-Datei zu erstellen, kann man die internen Definitionen von AndroidDB mit dem Befehl '''set exportPresets''' als Preset-Datei exportieren und diese Datei dann anpassen:<br />
set myTV exportPresets /home/fhem/android.dat<br />
Beispiel: Eine Preset-Datei wurde unter dem Namen "/home/fhem/android.dat" angelegt. Sie enthält 2 Presets mit den Namen "SonyTV" und "FireTV".<br />
<br />
Preset-Datei laden:<br />
attr myTV presetFile /home/fhem/android.dat<br />
Preset auswählen:<br />
attr myTV preset SonyTV <br />
<br />
=== Fernbedienungen ===<br />
AndroidDB unterstützt das Anlegen von Remotecontrol-Devices mit dem FHEM Modul remotecontrol. Für die eingebauten Presets kann eine Fernbedienung mit dem Befehl set createRemote angelegt werden:<br />
set myTV createRemote MagentaOne<br />
AndroidDB legt damit zwei neue FHEM devices an:<br />
* Ein Device vom Typ "remotecontrol" mit dem Namen "myTV_RC"<br />
* Ein Device vom Typ "notify" mit dem Namen "notify_myTV_RC" (Weiterleitung der Tastendrücke aus "myTV_RC" an "myTV")<br />
Beispiel:<br />
[[Datei:SampleRemote.png|links|Remote control created by set createRemote command|alternativtext=|512x512px]]<br />
<br />
[[Kategorie:Android]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=AndroidDB&diff=37263AndroidDB2022-02-24T12:39:14Z<p>Zap: </p>
<hr />
<div>== Allgemeines ==<br />
Die Module AndroidDB und AndroidDBHost erlauben die Steuerung von Android Geräten über die Android Debug Bridge (ADB). Man kann z.B. Befehle auf Android Geräten ausführen, Android Geräte neu starten oder Tastatur- und Touchscreen-Eingaben an Android Geräte senden und so eine Fernbedienung simulieren. Die Module wurden primär entwickelt, um Android TV Geräte zu steuern, sollten aber auch mit Tablets oder Telefonen funktionieren. Ein "rooten" der zu steuernden Geräte ist nicht erforderlich!<br />
<br />
Die Module wurden mit folgenden Geräten getestet:<br />
* Samsung Android Tablet<br />
* SONY Android TV AF9<br />
* Magenta TV Stick<br />
* Magenta One<br />
* NVidia Shield<br />
Einige mögliche Befehle als Anwendungsbeispiele:<br />
* Aufnahmetaste drücken: '''set myTVDev remoteControl RECORD'''<br />
* Neu starten: '''set myTVDev reboot'''<br />
* Installierte Apps anzeigen: '''set myTVDev shell pm list packages'''<br />
<br />
== Installation ==<br />
Voraussetzungen für die Nutzung der Module in FHEM:<br />
* Installation des Perl Moduls IPC::Open3<br />
* Installation der Android Plattform Tools<br />
Für die Installation des Perl Moduls verwendet man CPAN. Die Android Plattform Tools werden unter Debian/Raspbian mit dem folgenden Befehl installiert:<syntaxhighlight lang="shell"><br />
apt-get install android-sdk-platform-tools<br />
</syntaxhighlight>Für andere Plattformen (Windows, Linux x86, MacOS) findet man die Tools hier: https://developer.android.com/studio/releases/platform-tools<br />
<br />
Bei der manuellen Installation der Tools von developer.android.com (MacOs und Linux) muss man darauf achten, dass der Nutzer, unter dem der FHEM Prozess läuft, den Befehl 'adb' ausführen darf. Dazu ggf. die Rechte auf 'read' und 'execute' für alle setzen:<syntaxhighlight lang="shell"><br />
sudo chmod 755 adb<br />
</syntaxhighlight><br />
<br />
== Definition eines I/O Device (AndroidDBHost) ==<br />
Je FHEM Instanz gibt es nur 1 I/O Device. Die Syntax für die Definition sieht so aus:<br />
define ''Name'' AndroidDBHost [adb=''Pfadangabe'']<br />
Die Angabe des Parameters 'adb' ist nur erforderlich, wenn sich der Befehl 'adb' nicht im Suchpfad für ausführbare Programme befindet. Beispiel:<br />
define myADBServer AndroidDBHost adb=/usr/local/platform-tools/adb<br />
<br />
== Defintion von Android Devices in FHEM (AndroidDB) ==<br />
<br />
=== Android Gerät vorbereiten ===<br />
Auf jedem Android Device, das über AndroidDB gesteuert werden soll, muss der Entwicklermodus aktiviert und das USB Debugging eingeschaltet sein. Dies sollte auf jedem Android Gerät ohne "root" Berechtigung möglich sein.<br />
<br />
Die Aktivierung des Entwicklermodus kann sich von Gerät zu Gerät etwas unterscheiden, ist aber meist ähnlich. Bei Android TV Geräten geht man so vor (einmalige Aktion je Gerät):<br />
# Sollte das Android Gerät einen USB-Anschluss haben, sollte daran kein Gerät angeschlossen sein (z.B. LAN-Adapter bei TV Geräten)<br />
# Auf dem Android Gerät ''Geräteeinstellungen'' > ''Info'' auswählen<br />
# Ganz nach unten scrollen bis zu einer Angabe, die meistens "Build" oder "Version" heißt<br />
# Auf diese Angabe wiederholt drücken. Android zeigt dann irgendwann die Meldung "in X Schritten bist Du Entwickler" an. Dann noch X Mal drücken bis "Du bist jetzt Entwickler" angezeigt wird<br />
# Nun unter Geräteeinstellungen > Entwickleroptionen das USB-Debugging einschalten (heißt zwar USB, die Verbindung erfolgt aber über das Netzwerk)<br />
# Sollte sich das USB-Debugging nicht aktivieren lassen, das Android Gerät neu starten. Dies kann vorkommen, wenn ein Gerät per USB angeschlossen war (siehe 1)<br />
<br />
=== AndroidDB Device in FHEM definieren ===<br />
Nun kann man ein AndroidDB Device in FHEM definieren:<br />
define myTV AndroidDB 192.168.1.100<br />
Einziger Parameter ist die IP-Adresse des Android-Geräts (man sollte eine feste IP zuordnen). Beim ersten Zugriff auf das Gerät kann es sein, dass man auf dem Gerät einmal die Verbindung von FHEM zulassen muss. In dem Fall sollte man den Haken bei "Zugriff immer erlauben" setzen.<br />
<br />
== Steuerung von Android Devices in FHEM ==<br />
<br />
=== Tastatureingaben senden ===<br />
Eine der nützlichsten Funktionen dürfte das Senden von Tastendrücken sein. So kann man in FHEM eine Fernbedienung oder auch die Sprachsteuerung von Android Geräten realisieren.<br />
<br />
Beispiel: Home-Taste drücken<br />
set myTV sendKey KEYCODE_HOME<br />
Beispiel: Umschalten auf Programm 12 / mehrere Keycodes senden:<br />
set myTV sendkey KEYCODE_1 KEYCODE_2<br />
Eine Liste der Keycodes findet man hier: https://developer.android.com/reference/android/view/KeyEvent<br />
<br />
Weitere Befehle zum Senden von Tastatureingaben sind '''set sendNumKeys''' und '''set sendText'''.<br />
<br />
=== Makros ===<br />
Ein Makro fasst eine Folge von Tastatureingaben oder einen ADB-Befehl unter einem Befehl zusammen. Tastaturmakros können anschließend mit dem Befehl '''set remoteControl''' ausgeführt werden. Makros für ADB-Befehle stehen als set-Befehle zur Verfügung.<br />
<br />
Beispiel: Es wird ein Makro "DasErste" definiert, bei dessen Ausführung die Sequenz "0001" an ein Android TV Gerät gesendet wird:<br />
attr myTV macros DasErste:KEYCODE_0,KEYCODE_0,KEYCODE_0,KEYCODE_1<br />
set myTV remoteControl DasErste<br />
Beispiel: Es wird ein Makro "listPackages" zum Auflisten aller Apps definiert, die auf einem Android-Device installiert sind:<br />
attr myTV macros listPackages:shell pm list packages<br />
set myTV listPackages<br />
<br />
=== Presets ===<br />
Presets sind eine Liste von Makrodefinitionen. AndroidDB hat Presets bereits eingebaut für Magenta TV Stick, Magenta One. Man kann eigene Presets in einer Datei definieren und mit dem Attribut 'presetFile' laden. Eine solche Preset-Datei kann mehrere Preset-Definitionen enthalten. Ein Preset kann mit dem Attribut 'preset' ausgewählt werden.<br />
<br />
Eine Preset-Datei hat folgenden Aufbau:<syntaxhighlight lang="text"><br />
# Kommentar<br />
PresetName1<br />
MacroName1:MacroDef1[,...]<br />
MacroName2:MacroDef2[,...]<br />
...<br />
PresetName2<br />
...<br />
<br />
</syntaxhighlight>Ein ''MacroName'' darf keine Leerzeichen enthalten. Der Parameter ''MacroDef'' steht entweder für eine Liste von Keycodes oder einen ADB-Befehl. Siehe auch Abschnitt "Makros".<br />
<br />
Um eine eigene Preset-Datei zu erstellen, kann man die internen Definitionen von AndroidDB mit dem Befehl '''set exportPresets''' als Preset-Datei exportieren und diese Datei dann anpassen:<br />
set myTV exportPresets /home/fhem/android.dat<br />
Beispiel: Eine Preset-Datei wurde unter dem Namen "/home/fhem/android.dat" angelegt. Sie enthält 2 Presets mit den Namen "SonyTV" und "FireTV".<br />
<br />
Preset-Datei laden:<br />
attr myTV presetFile /home/fhem/android.dat<br />
Preset auswählen:<br />
attr myTV preset SonyTV <br />
<br />
=== Fernbedienungen ===<br />
AndroidDB unterstützt das Anlegen von Remotecontrol-Devices mit dem FHEM Modul remotecontrol. Für die eingebauten Presets kann eine Fernbedienung mit dem Befehl set createRemote angelegt werden:<br />
set myTV createRemote MagentaOne<br />
AndroidDB legt damit zwei neue FHEM devices an:<br />
* Ein Device vom Typ "remotecontrol" mit dem Namen "myTV_RC"<br />
* Ein Device vom Typ "notify" mit dem Namen "notify_myTV_RC" (Weiterleitung der Tastendrücke aus "myTV_RC" an "myTV")<br />
Beispiel:<br />
[[Datei:SampleRemote.png|links|mini|Remote control created by set createRemote command]]<br />
<br />
[[Kategorie:Android]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=Datei:SampleRemote.png&diff=37262Datei:SampleRemote.png2022-02-24T12:37:35Z<p>Zap: </p>
<hr />
<div>Sample remote control</div>Zaphttp://wiki.fhem.de/w/index.php?title=AndroidDB&diff=37261AndroidDB2022-02-24T12:31:28Z<p>Zap: /* Steuerung von Android Devices in FHEM */</p>
<hr />
<div>== Allgemeines ==<br />
Die Module AndroidDB und AndroidDBHost erlauben die Steuerung von Android Geräten über die Android Debug Bridge (ADB). Man kann z.B. Befehle auf Android Geräten ausführen, Android Geräte neu starten oder Tastatur- und Touchscreen-Eingaben an Android Geräte senden und so eine Fernbedienung simulieren. Die Module wurden primär entwickelt, um Android TV Geräte zu steuern, sollten aber auch mit Tablets oder Telefonen funktionieren. Ein "rooten" der zu steuernden Geräte ist nicht erforderlich!<br />
<br />
Die Module wurden mit folgenden Geräten getestet:<br />
* Samsung Android Tablet<br />
* SONY Android TV AF9<br />
* Magenta TV Stick<br />
* Magenta One<br />
* NVidia Shield<br />
Einige mögliche Befehle als Anwendungsbeispiele:<br />
* Aufnahmetaste drücken: '''set myTVDev remoteControl RECORD'''<br />
* Neu starten: '''set myTVDev reboot'''<br />
* Installierte Apps anzeigen: '''set myTVDev shell pm list packages'''<br />
<br />
== Installation ==<br />
Voraussetzungen für die Nutzung der Module in FHEM:<br />
* Installation des Perl Moduls IPC::Open3<br />
* Installation der Android Plattform Tools<br />
Für die Installation des Perl Moduls verwendet man CPAN. Die Android Plattform Tools werden unter Debian/Raspbian mit dem folgenden Befehl installiert:<syntaxhighlight lang="shell"><br />
apt-get install android-sdk-platform-tools<br />
</syntaxhighlight>Für andere Plattformen (Windows, Linux x86, MacOS) findet man die Tools hier: https://developer.android.com/studio/releases/platform-tools<br />
<br />
Bei der manuellen Installation der Tools von developer.android.com (MacOs und Linux) muss man darauf achten, dass der Nutzer, unter dem der FHEM Prozess läuft, den Befehl 'adb' ausführen darf. Dazu ggf. die Rechte auf 'read' und 'execute' für alle setzen:<syntaxhighlight lang="shell"><br />
sudo chmod 755 adb<br />
</syntaxhighlight><br />
<br />
== Definition eines I/O Device (AndroidDBHost) ==<br />
Je FHEM Instanz gibt es nur 1 I/O Device. Die Syntax für die Definition sieht so aus:<br />
define ''Name'' AndroidDBHost [adb=''Pfadangabe'']<br />
Die Angabe des Parameters 'adb' ist nur erforderlich, wenn sich der Befehl 'adb' nicht im Suchpfad für ausführbare Programme befindet. Beispiel:<br />
define myADBServer AndroidDBHost adb=/usr/local/platform-tools/adb<br />
<br />
== Defintion von Android Devices in FHEM (AndroidDB) ==<br />
<br />
=== Android Gerät vorbereiten ===<br />
Auf jedem Android Device, das über AndroidDB gesteuert werden soll, muss der Entwicklermodus aktiviert und das USB Debugging eingeschaltet sein. Dies sollte auf jedem Android Gerät ohne "root" Berechtigung möglich sein.<br />
<br />
Die Aktivierung des Entwicklermodus kann sich von Gerät zu Gerät etwas unterscheiden, ist aber meist ähnlich. Bei Android TV Geräten geht man so vor (einmalige Aktion je Gerät):<br />
# Sollte das Android Gerät einen USB-Anschluss haben, sollte daran kein Gerät angeschlossen sein (z.B. LAN-Adapter bei TV Geräten)<br />
# Auf dem Android Gerät ''Geräteeinstellungen'' > ''Info'' auswählen<br />
# Ganz nach unten scrollen bis zu einer Angabe, die meistens "Build" oder "Version" heißt<br />
# Auf diese Angabe wiederholt drücken. Android zeigt dann irgendwann die Meldung "in X Schritten bist Du Entwickler" an. Dann noch X Mal drücken bis "Du bist jetzt Entwickler" angezeigt wird<br />
# Nun unter Geräteeinstellungen > Entwickleroptionen das USB-Debugging einschalten (heißt zwar USB, die Verbindung erfolgt aber über das Netzwerk)<br />
# Sollte sich das USB-Debugging nicht aktivieren lassen, das Android Gerät neu starten. Dies kann vorkommen, wenn ein Gerät per USB angeschlossen war (siehe 1)<br />
<br />
=== AndroidDB Device in FHEM definieren ===<br />
Nun kann man ein AndroidDB Device in FHEM definieren:<br />
define myTV AndroidDB 192.168.1.100<br />
Einziger Parameter ist die IP-Adresse des Android-Geräts (man sollte eine feste IP zuordnen). Beim ersten Zugriff auf das Gerät kann es sein, dass man auf dem Gerät einmal die Verbindung von FHEM zulassen muss. In dem Fall sollte man den Haken bei "Zugriff immer erlauben" setzen.<br />
<br />
== Steuerung von Android Devices in FHEM ==<br />
<br />
=== Tastatureingaben senden ===<br />
Eine der nützlichsten Funktionen dürfte das Senden von Tastendrücken sein. So kann man in FHEM eine Fernbedienung oder auch die Sprachsteuerung von Android Geräten realisieren.<br />
<br />
Beispiel: Home-Taste drücken<br />
set myTV sendKey KEYCODE_HOME<br />
Beispiel: Umschalten auf Programm 12 / mehrere Keycodes senden:<br />
set myTV sendkey KEYCODE_1 KEYCODE_2<br />
Eine Liste der Keycodes findet man hier: https://developer.android.com/reference/android/view/KeyEvent<br />
<br />
Weitere Befehle zum Senden von Tastatureingaben sind '''set sendNumKeys''' und '''set sendText'''.<br />
<br />
=== Makros ===<br />
Ein Makro fasst eine Folge von Tastatureingaben oder einen ADB-Befehl unter einem Befehl zusammen. Tastaturmakros können anschließend mit dem Befehl '''set remoteControl''' ausgeführt werden. Makros für ADB-Befehle stehen als set-Befehle zur Verfügung.<br />
<br />
Beispiel: Es wird ein Makro "DasErste" definiert, bei dessen Ausführung die Sequenz "0001" an ein Android TV Gerät gesendet wird:<br />
attr myTV macros DasErste:KEYCODE_0,KEYCODE_0,KEYCODE_0,KEYCODE_1<br />
set myTV remoteControl DasErste<br />
Beispiel: Es wird ein Makro "listPackages" zum Auflisten aller Apps definiert, die auf einem Android-Device installiert sind:<br />
attr myTV macros listPackages:shell pm list packages<br />
set myTV listPackages<br />
<br />
=== Presets ===<br />
Presets sind eine Liste von Makrodefinitionen. AndroidDB hat Presets bereits eingebaut für Magenta TV Stick, Magenta One. Man kann eigene Presets in einer Datei definieren und mit dem Attribut 'presetFile' laden. Eine solche Preset-Datei kann mehrere Preset-Definitionen enthalten. Ein Preset kann mit dem Attribut 'preset' ausgewählt werden.<br />
<br />
Eine Preset-Datei hat folgenden Aufbau:<syntaxhighlight lang="text"><br />
# Kommentar<br />
PresetName1<br />
MacroName1:MacroDef1[,...]<br />
MacroName2:MacroDef2[,...]<br />
...<br />
PresetName2<br />
...<br />
<br />
</syntaxhighlight>Ein ''MacroName'' darf keine Leerzeichen enthalten. Der Parameter ''MacroDef'' steht entweder für eine Liste von Keycodes oder einen ADB-Befehl. Siehe auch Abschnitt "Makros".<br />
<br />
Um eine eigene Preset-Datei zu erstellen, kann man die internen Definitionen von AndroidDB mit dem Befehl '''set exportPresets''' als Preset-Datei exportieren und diese Datei dann anpassen:<br />
set myTV exportPresets /home/fhem/android.dat<br />
Beispiel: Eine Preset-Datei wurde unter dem Namen "/home/fhem/android.dat" angelegt. Sie enthält 2 Presets mit den Namen "SonyTV" und "FireTV".<br />
<br />
Preset-Datei laden:<br />
attr myTV presetFile /home/fhem/android.dat<br />
Preset auswählen:<br />
attr myTV preset SonyTV <br />
<br />
=== Fernbedienungen ===<br />
AndroidDB unterstützt das Anlegen von Remotecontrol-Devices mit dem FHEM Modul remotecontrol. Für die eingebauten Presets kann eine Fernbedienung mit dem Befehl set createRemote angelegt werden:<br />
set myTV createRemote MagentaOne<br />
AndroidDB legt damit zwei neue FHEM devices an:<br />
* Ein Device vom Typ "remotecontrol" mit dem Namen "myTV_RC"<br />
* Ein Device vom Typ "notify" mit dem Namen "notify_myTV_RC" (Weiterleitung der Tastendrücke aus "myTV_RC" an "myTV")<br />
Beispiel:<br />
<br />
[[Kategorie:Android]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=AndroidDB&diff=37260AndroidDB2022-02-24T12:17:40Z<p>Zap: /* Makros */</p>
<hr />
<div>== Allgemeines ==<br />
Die Module AndroidDB und AndroidDBHost erlauben die Steuerung von Android Geräten über die Android Debug Bridge (ADB). Man kann z.B. Befehle auf Android Geräten ausführen, Android Geräte neu starten oder Tastatur- und Touchscreen-Eingaben an Android Geräte senden und so eine Fernbedienung simulieren. Die Module wurden primär entwickelt, um Android TV Geräte zu steuern, sollten aber auch mit Tablets oder Telefonen funktionieren. Ein "rooten" der zu steuernden Geräte ist nicht erforderlich!<br />
<br />
Die Module wurden mit folgenden Geräten getestet:<br />
* Samsung Android Tablet<br />
* SONY Android TV AF9<br />
* Magenta TV Stick<br />
* Magenta One<br />
* NVidia Shield<br />
Einige mögliche Befehle als Anwendungsbeispiele:<br />
* Aufnahmetaste drücken: '''set myTVDev remoteControl RECORD'''<br />
* Neu starten: '''set myTVDev reboot'''<br />
* Installierte Apps anzeigen: '''set myTVDev shell pm list packages'''<br />
<br />
== Installation ==<br />
Voraussetzungen für die Nutzung der Module in FHEM:<br />
* Installation des Perl Moduls IPC::Open3<br />
* Installation der Android Plattform Tools<br />
Für die Installation des Perl Moduls verwendet man CPAN. Die Android Plattform Tools werden unter Debian/Raspbian mit dem folgenden Befehl installiert:<syntaxhighlight lang="shell"><br />
apt-get install android-sdk-platform-tools<br />
</syntaxhighlight>Für andere Plattformen (Windows, Linux x86, MacOS) findet man die Tools hier: https://developer.android.com/studio/releases/platform-tools<br />
<br />
Bei der manuellen Installation der Tools von developer.android.com (MacOs und Linux) muss man darauf achten, dass der Nutzer, unter dem der FHEM Prozess läuft, den Befehl 'adb' ausführen darf. Dazu ggf. die Rechte auf 'read' und 'execute' für alle setzen:<syntaxhighlight lang="shell"><br />
sudo chmod 755 adb<br />
</syntaxhighlight><br />
<br />
== Definition eines I/O Device (AndroidDBHost) ==<br />
Je FHEM Instanz gibt es nur 1 I/O Device. Die Syntax für die Definition sieht so aus:<br />
define ''Name'' AndroidDBHost [adb=''Pfadangabe'']<br />
Die Angabe des Parameters 'adb' ist nur erforderlich, wenn sich der Befehl 'adb' nicht im Suchpfad für ausführbare Programme befindet. Beispiel:<br />
define myADBServer AndroidDBHost adb=/usr/local/platform-tools/adb<br />
<br />
== Defintion von Android Devices in FHEM (AndroidDB) ==<br />
<br />
=== Android Gerät vorbereiten ===<br />
Auf jedem Android Device, das über AndroidDB gesteuert werden soll, muss der Entwicklermodus aktiviert und das USB Debugging eingeschaltet sein. Dies sollte auf jedem Android Gerät ohne "root" Berechtigung möglich sein.<br />
<br />
Die Aktivierung des Entwicklermodus kann sich von Gerät zu Gerät etwas unterscheiden, ist aber meist ähnlich. Bei Android TV Geräten geht man so vor (einmalige Aktion je Gerät):<br />
# Sollte das Android Gerät einen USB-Anschluss haben, sollte daran kein Gerät angeschlossen sein (z.B. LAN-Adapter bei TV Geräten)<br />
# Auf dem Android Gerät ''Geräteeinstellungen'' > ''Info'' auswählen<br />
# Ganz nach unten scrollen bis zu einer Angabe, die meistens "Build" oder "Version" heißt<br />
# Auf diese Angabe wiederholt drücken. Android zeigt dann irgendwann die Meldung "in X Schritten bist Du Entwickler" an. Dann noch X Mal drücken bis "Du bist jetzt Entwickler" angezeigt wird<br />
# Nun unter Geräteeinstellungen > Entwickleroptionen das USB-Debugging einschalten (heißt zwar USB, die Verbindung erfolgt aber über das Netzwerk)<br />
# Sollte sich das USB-Debugging nicht aktivieren lassen, das Android Gerät neu starten. Dies kann vorkommen, wenn ein Gerät per USB angeschlossen war (siehe 1)<br />
<br />
=== AndroidDB Device in FHEM definieren ===<br />
Nun kann man ein AndroidDB Device in FHEM definieren:<br />
define myTV AndroidDB 192.168.1.100<br />
Einziger Parameter ist die IP-Adresse des Android-Geräts (man sollte eine feste IP zuordnen). Beim ersten Zugriff auf das Gerät kann es sein, dass man auf dem Gerät einmal die Verbindung von FHEM zulassen muss. In dem Fall sollte man den Haken bei "Zugriff immer erlauben" setzen.<br />
<br />
== Steuerung von Android Devices in FHEM ==<br />
<br />
=== Tastatureingaben senden ===<br />
Eine der nützlichsten Funktionen dürfte das Senden von Tastendrücken sein. So kann man in FHEM eine Fernbedienung oder auch die Sprachsteuerung von Android Geräten realisieren.<br />
<br />
Beispiel: Home-Taste drücken<br />
set myTV sendKey KEYCODE_HOME<br />
Beispiel: Umschalten auf Programm 12 / mehrere Keycodes senden:<br />
set myTV sendkey KEYCODE_1 KEYCODE_2<br />
Eine Liste der Keycodes findet man hier: https://developer.android.com/reference/android/view/KeyEvent<br />
<br />
=== Makros ===<br />
Ein Makro fasst eine Folge von Tastatureingaben oder einen ADB-Befehl unter einem Befehl zusammen. Tastaturmakros können anschließend mit dem Befehl '''set remoteControl''' ausgeführt werden. Makros für ADB-Befehle stehen als set-Befehle zur Verfügung.<br />
<br />
Beispiel: Es wird ein Makro "DasErste" definiert, bei dessen Ausführung die Sequenz "0001" an ein Android TV Gerät gesendet wird:<br />
attr myTV macros DasErste:KEYCODE_0,KEYCODE_0,KEYCODE_0,KEYCODE_1<br />
set myTV remoteControl DasErste<br />
Beispiel: Es wird ein Makro "listPackages" zum Auflisten aller Apps definiert, die auf einem Android-Device installiert sind:<br />
attr myTV macros listPackages:shell pm list packages<br />
set myTV listPackages<br />
<br />
=== Presets ===<br />
Presets sind eine Liste von Macros. AndroidDB hat Presets bereits eingebaut für Magenta TV Stick, Magenta One. Man kann eigene Presets in einer Datei definieren und mit dem Attribut 'presetFile' laden. Eine solche Preset-Datei kann mehrere Preset-Definitionen enthalten. Ein Preset kann mit dem Attribut 'preset' ausgewählt werden.<br />
<br />
Eine Preset-Datei hat folgenden Aufbau:<syntaxhighlight lang="text"><br />
# Kommentar<br />
PresetName1<br />
MacroName1:KeyCode[,...]<br />
MacroName2:KeyCode[,...]<br />
...<br />
PresetName2<br />
...<br />
<br />
</syntaxhighlight>Beispiel: Eine Preset-Datei wurde unter dem Namen "/home/fhem/android.dat" angelegt. Sie enthält 2 Presets mit den Namen "SonyTV" und "FireTV".<br />
<br />
Preset-Datei laden:<br />
attr myTV presetFile /home/fhem/android.dat<br />
Preset auswählen:<br />
attr myTV preset SonyTV<br />
[[Kategorie:Android]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=AndroidDB&diff=37224AndroidDB2022-02-15T09:22:53Z<p>Zap: Makros und Presets</p>
<hr />
<div>== Allgemeines ==<br />
Die Module AndroidDB und AndroidDBHost erlauben die Steuerung von Android Geräten über die Android Debug Bridge (ADB). Man kann z.B. Befehle auf Android Geräten ausführen, Android Geräte neu starten oder Tastatur- und Touchscreen-Eingaben an Android Geräte senden und so eine Fernbedienung simulieren. Die Module wurden primär entwickelt, um Android TV Geräte zu steuern, sollten aber auch mit Tablets oder Telefonen funktionieren. Ein "rooten" der zu steuernden Geräte ist nicht erforderlich!<br />
<br />
Die Module wurden mit folgenden Geräten getestet:<br />
* Samsung Android Tablet<br />
* SONY Android TV AF9<br />
* Magenta TV Stick<br />
* Magenta One<br />
* NVidia Shield<br />
Einige mögliche Befehle als Anwendungsbeispiele:<br />
* Aufnahmetaste drücken: '''set myTVDev remoteControl RECORD'''<br />
* Neu starten: '''set myTVDev reboot'''<br />
* Installierte Apps anzeigen: '''set myTVDev shell pm list packages'''<br />
<br />
== Installation ==<br />
Voraussetzungen für die Nutzung der Module in FHEM:<br />
* Installation des Perl Moduls IPC::Open3<br />
* Installation der Android Plattform Tools<br />
Für die Installation des Perl Moduls verwendet man CPAN. Die Android Plattform Tools werden unter Debian/Raspbian mit dem folgenden Befehl installiert:<syntaxhighlight lang="shell"><br />
apt-get install android-sdk-platform-tools<br />
</syntaxhighlight>Für andere Plattformen (Windows, Linux x86, MacOS) findet man die Tools hier: https://developer.android.com/studio/releases/platform-tools<br />
<br />
Bei der manuellen Installation der Tools von developer.android.com (MacOs und Linux) muss man darauf achten, dass der Nutzer, unter dem der FHEM Prozess läuft, den Befehl 'adb' ausführen darf. Dazu ggf. die Rechte auf 'read' und 'execute' für alle setzen:<syntaxhighlight lang="shell"><br />
sudo chmod 755 adb<br />
</syntaxhighlight><br />
<br />
== Definition eines I/O Device (AndroidDBHost) ==<br />
Je FHEM Instanz gibt es nur 1 I/O Device. Die Syntax für die Definition sieht so aus:<br />
define ''Name'' AndroidDBHost [adb=''Pfadangabe'']<br />
Die Angabe des Parameters 'adb' ist nur erforderlich, wenn sich der Befehl 'adb' nicht im Suchpfad für ausführbare Programme befindet. Beispiel:<br />
define myADBServer AndroidDBHost adb=/usr/local/platform-tools/adb<br />
<br />
== Defintion von Android Devices in FHEM (AndroidDB) ==<br />
<br />
=== Android Gerät vorbereiten ===<br />
Auf jedem Android Device, das über AndroidDB gesteuert werden soll, muss der Entwicklermodus aktiviert und das USB Debugging eingeschaltet sein. Dies sollte auf jedem Android Gerät ohne "root" Berechtigung möglich sein.<br />
<br />
Die Aktivierung des Entwicklermodus kann sich von Gerät zu Gerät etwas unterscheiden, ist aber meist ähnlich. Bei Android TV Geräten geht man so vor (einmalige Aktion je Gerät):<br />
# Sollte das Android Gerät einen USB-Anschluss haben, sollte daran kein Gerät angeschlossen sein (z.B. LAN-Adapter bei TV Geräten)<br />
# Auf dem Android Gerät ''Geräteeinstellungen'' > ''Info'' auswählen<br />
# Ganz nach unten scrollen bis zu einer Angabe, die meistens "Build" oder "Version" heißt<br />
# Auf diese Angabe wiederholt drücken. Android zeigt dann irgendwann die Meldung "in X Schritten bist Du Entwickler" an. Dann noch X Mal drücken bis "Du bist jetzt Entwickler" angezeigt wird<br />
# Nun unter Geräteeinstellungen > Entwickleroptionen das USB-Debugging einschalten (heißt zwar USB, die Verbindung erfolgt aber über das Netzwerk)<br />
# Sollte sich das USB-Debugging nicht aktivieren lassen, das Android Gerät neu starten. Dies kann vorkommen, wenn ein Gerät per USB angeschlossen war (siehe 1)<br />
<br />
=== AndroidDB Device in FHEM definieren ===<br />
Nun kann man ein AndroidDB Device in FHEM definieren:<br />
define myTV AndroidDB 192.168.1.100<br />
Einziger Parameter ist die IP-Adresse des Android-Geräts (man sollte eine feste IP zuordnen). Beim ersten Zugriff auf das Gerät kann es sein, dass man auf dem Gerät einmal die Verbindung von FHEM zulassen muss. In dem Fall sollte man den Haken bei "Zugriff immer erlauben" setzen.<br />
<br />
== Steuerung von Android Devices in FHEM ==<br />
<br />
=== Tastatureingaben senden ===<br />
Eine der nützlichsten Funktionen dürfte das Senden von Tastendrücken sein. So kann man in FHEM eine Fernbedienung oder auch die Sprachsteuerung von Android Geräten realisieren.<br />
<br />
Beispiel: Home-Taste drücken<br />
set myTV sendKey KEYCODE_HOME<br />
Beispiel: Umschalten auf Programm 12 / mehrere Keycodes senden:<br />
set myTV sendkey KEYCODE_1 KEYCODE_2<br />
Eine Liste der Keycodes findet man hier: https://developer.android.com/reference/android/view/KeyEvent<br />
<br />
=== Makros ===<br />
Ein Makro fasst eine Folge von Tastatureingaben unter einem Befehl zusammen, der dann mit dem Befehl remoteControl ausgeführt wird.<br />
<br />
Beispiel: Es wird ein Makro "DasErste" definiert, bei dessen Ausführung die Sequenz "0001" an ein Android TV Gerät gesendet wird:<br />
attr myTV macros DasErste:KEYCODE_0,KEYCODE_0,KEYCODE_0,KEYCODE_1<br />
<br />
set myTV remoteControl DasErste<br />
<br />
=== Presets ===<br />
Presets sind eine Liste von Macros. AndroidDB hat Presets bereits eingebaut für Magenta TV Stick, Magenta One. Man kann eigene Presets in einer Datei definieren und mit dem Attribut 'presetFile' laden. Eine solche Preset-Datei kann mehrere Preset-Definitionen enthalten. Ein Preset kann mit dem Attribut 'preset' ausgewählt werden.<br />
<br />
Eine Preset-Datei hat folgenden Aufbau:<syntaxhighlight lang="text"><br />
# Kommentar<br />
PresetName1<br />
MacroName1:KeyCode[,...]<br />
MacroName2:KeyCode[,...]<br />
...<br />
PresetName2<br />
...<br />
<br />
</syntaxhighlight>Beispiel: Eine Preset-Datei wurde unter dem Namen "/home/fhem/android.dat" angelegt. Sie enthält 2 Presets mit den Namen "SonyTV" und "FireTV".<br />
<br />
Preset-Datei laden:<br />
attr myTV presetFile /home/fhem/android.dat<br />
Preset auswählen:<br />
attr myTV preset SonyTV<br />
[[Kategorie:Android]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=AndroidDB&diff=37223AndroidDB2022-02-15T08:57:52Z<p>Zap: </p>
<hr />
<div>== Allgemeines ==<br />
Die Module AndroidDB und AndroidDBHost erlauben die Steuerung von Android Geräten über die Android Debug Bridge (ADB). Man kann z.B. Befehle auf Android Geräten ausführen, Android Geräte neu starten oder Tastatur- und Touchscreen-Eingaben an Android Geräte senden und so eine Fernbedienung simulieren. Die Module wurden primär entwickelt, um Android TV Geräte zu steuern, sollten aber auch mit Tablets oder Telefonen funktionieren. Ein "rooten" der zu steuernden Geräte ist nicht erforderlich!<br />
<br />
Die Module wurden mit folgenden Geräten getestet:<br />
* Samsung Android Tablet<br />
* SONY Android TV AF9<br />
* Magenta TV Stick<br />
* Magenta One<br />
* NVidia Shield<br />
Einige mögliche Befehle als Anwendungsbeispiele:<br />
* Aufnahmetaste drücken: '''set myTVDev remoteControl RECORD'''<br />
* Neu starten: '''set myTVDev reboot'''<br />
* Installierte Apps anzeigen: '''set myTVDev shell pm list packages'''<br />
<br />
== Installation ==<br />
Voraussetzungen für die Nutzung der Module in FHEM:<br />
* Installation des Perl Moduls IPC::Open3<br />
* Installation der Android Plattform Tools<br />
Für die Installation des Perl Moduls verwendet man CPAN. Die Android Plattform Tools werden unter Debian/Raspbian mit dem folgenden Befehl installiert:<syntaxhighlight lang="shell"><br />
apt-get install android-sdk-platform-tools<br />
</syntaxhighlight>Für andere Plattformen (Windows, Linux x86, MacOS) findet man die Tools hier: https://developer.android.com/studio/releases/platform-tools<br />
<br />
Bei der manuellen Installation der Tools von developer.android.com (MacOs und Linux) muss man darauf achten, dass der Nutzer, unter dem der FHEM Prozess läuft, den Befehl 'adb' ausführen darf. Dazu ggf. die Rechte auf 'read' und 'execute' für alle setzen:<syntaxhighlight lang="shell"><br />
sudo chmod 755 adb<br />
</syntaxhighlight><br />
<br />
== Definition eines I/O Device (AndroidDBHost) ==<br />
Je FHEM Instanz gibt es nur 1 I/O Device. Die Syntax für die Definition sieht so aus:<br />
define ''Name'' AndroidDBHost [adb=''Pfadangabe'']<br />
Die Angabe des Parameters 'adb' ist nur erforderlich, wenn sich der Befehl 'adb' nicht im Suchpfad für ausführbare Programme befindet. Beispiel:<br />
define myADBServer AndroidDBHost adb=/usr/local/platform-tools/adb<br />
<br />
== Defintion von Android Devices in FHEM (AndroidDB) ==<br />
<br />
=== Android Gerät vorbereiten ===<br />
Auf jedem Android Device, das über AndroidDB gesteuert werden soll, muss der Entwicklermodus aktiviert und das USB Debugging eingeschaltet sein. Dies sollte auf jedem Android Gerät ohne "root" Berechtigung möglich sein.<br />
<br />
Die Aktivierung des Entwicklermodus kann sich von Gerät zu Gerät etwas unterscheiden, ist aber meist ähnlich. Bei Android TV Geräten geht man so vor (einmalige Aktion je Gerät):<br />
# Sollte das Android Gerät einen USB-Anschluss haben, sollte daran kein Gerät angeschlossen sein (z.B. LAN-Adapter bei TV Geräten)<br />
# Auf dem Android Gerät ''Geräteeinstellungen'' > ''Info'' auswählen<br />
# Ganz nach unten scrollen bis zu einer Angabe, die meistens "Build" oder "Version" heißt<br />
# Auf diese Angabe wiederholt drücken. Android zeigt dann irgendwann die Meldung "in X Schritten bist Du Entwickler" an. Dann noch X Mal drücken bis "Du bist jetzt Entwickler" angezeigt wird<br />
# Nun unter Geräteeinstellungen > Entwickleroptionen das USB-Debugging einschalten (heißt zwar USB, die Verbindung erfolgt aber über das Netzwerk)<br />
# Sollte sich das USB-Debugging nicht aktivieren lassen, das Android Gerät neu starten. Dies kann vorkommen, wenn ein Gerät per USB angeschlossen war (siehe 1)<br />
<br />
=== AndroidDB Device in FHEM definieren ===<br />
Nun kann man ein AndroidDB Device in FHEM definieren:<br />
define myTV AndroidDB 192.168.1.100<br />
Einziger Parameter ist die IP-Adresse des Android-Geräts (man sollte eine feste IP zuordnen). Beim ersten Zugriff auf das Gerät kann es sein, dass man auf dem Gerät einmal die Verbindung von FHEM zulassen muss. In dem Fall sollte man den Haken bei "Zugriff immer erlauben" setzen.<br />
<br />
== Steuerung von Android Devices in FHEM ==<br />
Nun kann man sein Android Gerät steuern. Eine der nützlichsten Funktionen dürfte das Senden von Tastendrücken sein. So kann man in FHEM eine Fernbedieung realisieren.<br />
<br />
Beispiel: Home-Taste drücken<br />
<br />
Code: [Auswählen]<br />
<br />
<code>set myTV sendKey KEYCODE_HOME</code><br />
<br />
Beispiel: Umschalten auf Programm 12<br />
<br />
Code: [Auswählen]<br />
<br />
<code>set myTV sendKey KEYCODE_0 KEYCODE_0 KEYCODE_1 KEYCODE_2</code>(die beiden führenden 0en könnte man weglassen, dann dauert das Umschalten aber länger, da das Gerät wartet, ob weitere Tasten kommen)<br />
<br />
Eine Liste der Keycodes findet man hier: <nowiki>https://developer.android.com/reference/android/view/KeyEvent</nowiki><br />
<br />
'''Presets'''<br />
<br />
Ich habe einige Presets hinterlegt (am Beispiel eines Magenta TV Sticks). Ein Preset kann mit dem Attribut 'preset' eingestellt werden. Alternativ kann man mit dem Attribut 'macro' eigene RemoteControl Befehle definieren. Ein solcher Befehl kann mehrere Tastendrücke senden.<br />
<br />
Nach der Auswahl eines Presets kann man Befehle etwas abkürzen, z.B.:<br />
<br />
Code: [Auswählen]<br />
<br />
<code>set myTVStick remoteControl APPS</code><br />
<br />
<code>set myTVStick remoteControl EPG</code><br />
<br />
Mit Macros:<br />
<br />
Code: [Auswählen]<br />
<br />
<code>attr myTV macros DasErste:KEYCODE_0,KEYCODE_0,KEYCODE_0,KEYCODE_1</code><br />
<br />
<code>set myTV remoteControl DasErste</code><br />
<br />
'''In Arbeit:'''<br />
[[Kategorie:Android]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=Kategorie:Android&diff=37222Kategorie:Android2022-02-15T08:57:04Z<p>Zap: </p>
<hr />
<div>Android Geräte<br />
[[Kategorie:Hardware]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=Kategorie:Android&diff=37221Kategorie:Android2022-02-15T08:53:52Z<p>Zap: Kategorie für Android Geräte angelegt</p>
<hr />
<div>Android Geräte</div>Zaphttp://wiki.fhem.de/w/index.php?title=AndroidDB&diff=37220AndroidDB2022-02-15T08:52:39Z<p>Zap: </p>
<hr />
<div>== Allgemeines ==<br />
Die Module AndroidDB und AndroidDBHost erlauben die Steuerung von Android Geräten über die Android Debug Bridge (ADB). Man kann z.B. Befehle auf Android Geräten ausführen, Android Geräte neu starten oder Tastatur- und Touchscreen-Eingaben an Android Geräte senden und so eine Fernbedienung simulieren. Die Module wurden primär entwickelt, um Android TV Geräte zu steuern, sollten aber auch mit Tablets oder Telefonen funktionieren. Ein "rooten" der zu steuernden Geräte ist nicht erforderlich!<br />
<br />
Die Module wurden mit folgenden Geräten getestet:<br />
* Samsung Android Tablet<br />
* SONY Android TV AF9<br />
* Magenta TV Stick<br />
* Magenta One<br />
* NVidia Shield<br />
Einige mögliche Befehle als Anwendungsbeispiele:<br />
* Aufnahmetaste drücken: '''set myTVDev remoteControl RECORD'''<br />
* Neu starten: '''set myTVDev reboot'''<br />
* Installierte Apps anzeigen: '''set myTVDev shell pm list packages'''<br />
<br />
== Installation ==<br />
Voraussetzungen für die Nutzung der Module in FHEM:<br />
* Installation des Perl Moduls IPC::Open3<br />
* Installation der Android Plattform Tools<br />
Für die Installation des Perl Moduls verwendet man CPAN. Die Android Plattform Tools werden unter Debian/Raspbian mit dem folgenden Befehl installiert:<syntaxhighlight lang="shell"><br />
apt-get install android-sdk-platform-tools<br />
</syntaxhighlight>Für andere Plattformen (Windows, Linux x86, MacOS) findet man die Tools hier: https://developer.android.com/studio/releases/platform-tools<br />
<br />
Bei der manuellen Installation der Tools von developer.android.com (MacOs und Linux) muss man darauf achten, dass der Nutzer, unter dem der FHEM Prozess läuft, den Befehl 'adb' ausführen darf. Dazu ggf. die Rechte auf 'read' und 'execute' für alle setzen:<syntaxhighlight lang="shell"><br />
sudo chmod 755 adb<br />
</syntaxhighlight><br />
<br />
== Definition eines I/O Device (AndroidDBHost) ==<br />
Je FHEM Instanz gibt es nur 1 I/O Device. Die Syntax für die Definition sieht so aus:<br />
define ''Name'' AndroidDBHost [adb=''Pfadangabe'']<br />
Die Angabe des Parameters 'adb' ist nur erforderlich, wenn sich der Befehl 'adb' nicht im Suchpfad für ausführbare Programme befindet. Beispiel:<br />
define myADBServer AndroidDBHost adb=/usr/local/platform-tools/adb<br />
<br />
== Defintion von Android Devices in FHEM (AndroidDB) ==<br />
<br />
=== Android Gerät vorbereiten ===<br />
Auf jedem Android Device, das über AndroidDB gesteuert werden soll, muss der Entwicklermodus aktiviert und das USB Debugging eingeschaltet sein. Dies sollte auf jedem Android Gerät ohne "root" Berechtigung möglich sein.<br />
<br />
Die Aktivierung des Entwicklermodus kann sich von Gerät zu Gerät etwas unterscheiden, ist aber meist ähnlich. Bei Android TV Geräten geht man so vor (einmalige Aktion je Gerät):<br />
# Sollte das Android Gerät einen USB-Anschluss haben, sollte daran kein Gerät angeschlossen sein (z.B. LAN-Adapter bei TV Geräten)<br />
# Auf dem Android Gerät ''Geräteeinstellungen'' > ''Info'' auswählen<br />
# Ganz nach unten scrollen bis zu einer Angabe, die meistens "Build" oder "Version" heißt<br />
# Auf diese Angabe wiederholt drücken. Android zeigt dann irgendwann die Meldung "in X Schritten bist Du Entwickler" an. Dann noch X Mal drücken bis "Du bist jetzt Entwickler" angezeigt wird<br />
# Nun unter Geräteeinstellungen > Entwickleroptionen das USB-Debugging einschalten (heißt zwar USB, die Verbindung erfolgt aber über das Netzwerk)<br />
# Sollte sich das USB-Debugging nicht aktivieren lassen, das Android Gerät neu starten. Dies kann vorkommen, wenn ein Gerät per USB angeschlossen war (siehe 1)<br />
<br />
=== AndroidDB Device in FHEM definieren ===<br />
Nun kann man ein AndroidDB Device in FHEM definieren:<br />
define myTV AndroidDB 192.168.1.100<br />
Einziger Parameter ist die IP-Adresse des Android-Geräts (man sollte eine feste IP zuordnen). Beim ersten Zugriff auf das Gerät kann es sein, dass man auf dem Gerät einmal die Verbindung von FHEM zulassen muss. In dem Fall sollte man den Haken bei "Zugriff immer erlauben" setzen.<br />
<br />
== Steuerung von Android Devices in FHEM ==<br />
Nun kann man sein Android Gerät steuern. Eine der nützlichsten Funktionen dürfte das Senden von Tastendrücken sein. So kann man in FHEM eine Fernbedieung realisieren.<br />
<br />
Beispiel: Home-Taste drücken<br />
<br />
Code: [Auswählen]<br />
<br />
<code>set myTV sendKey KEYCODE_HOME</code><br />
<br />
Beispiel: Umschalten auf Programm 12<br />
<br />
Code: [Auswählen]<br />
<br />
<code>set myTV sendKey KEYCODE_0 KEYCODE_0 KEYCODE_1 KEYCODE_2</code>(die beiden führenden 0en könnte man weglassen, dann dauert das Umschalten aber länger, da das Gerät wartet, ob weitere Tasten kommen)<br />
<br />
Eine Liste der Keycodes findet man hier: <nowiki>https://developer.android.com/reference/android/view/KeyEvent</nowiki><br />
<br />
'''Presets'''<br />
<br />
Ich habe einige Presets hinterlegt (am Beispiel eines Magenta TV Sticks). Ein Preset kann mit dem Attribut 'preset' eingestellt werden. Alternativ kann man mit dem Attribut 'macro' eigene RemoteControl Befehle definieren. Ein solcher Befehl kann mehrere Tastendrücke senden.<br />
<br />
Nach der Auswahl eines Presets kann man Befehle etwas abkürzen, z.B.:<br />
<br />
Code: [Auswählen]<br />
<br />
<code>set myTVStick remoteControl APPS</code><br />
<br />
<code>set myTVStick remoteControl EPG</code><br />
<br />
Mit Macros:<br />
<br />
Code: [Auswählen]<br />
<br />
<code>attr myTV macros DasErste:KEYCODE_0,KEYCODE_0,KEYCODE_0,KEYCODE_1</code><br />
<br />
<code>set myTV remoteControl DasErste</code><br />
<br />
'''In Arbeit:'''<br />
[[Kategorie:Hardware]]<br />
[[Kategorie:Android]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=AndroidDB&diff=37219AndroidDB2022-02-15T07:58:34Z<p>Zap: Beschreibung der Module AndroidDB und AndroidDBHost</p>
<hr />
<div>== Allgemeines ==<br />
Die Module AndroidDB und AndroidDBHost erlauben die Steuerung von Android Geräten über die Android Debug Bridge (ADB). Man kann z.B. Befehle auf Android Geräten ausführen, Android Geräte neu starten oder Tastatur- und Touchscreen-Eingaben an Android Geräte senden und so eine Fernbedienung simulieren. Die Module wurden primär entwickelt, um Android TV Geräte zu steuern, sollten aber auch mit Tablets oder Telefonen funktionieren. Ein "rooten" der zu steuernden Geräte ist nicht erforderlich!<br />
<br />
Die Module wurden mit folgenden Geräten getestet:<br />
* Samsung Android Tablet<br />
* SONY Android TV AF9<br />
* Magenta TV Stick<br />
* Magenta One<br />
* NVidia Shield<br />
Einige mögliche Befehle als Anwendungsbeispiele:<br />
* Aufnahmetaste drücken: '''set myTVDev remoteControl RECORD'''<br />
* Neu starten: '''set myTVDev reboot'''<br />
* Installierte Apps anzeigen: '''set myTVDev shell pm list packages'''<br />
<br />
== Installation ==<br />
Voraussetzungen für die Nutzung der Module in FHEM:<br />
* Installation des Perl Moduls IPC::Open3<br />
* Installation der Android Plattform Tools<br />
Für die Installation des Perl Moduls verwendet man CPAN. Die Android Plattform Tools werden unter Debian/Raspbian mit dem folgenden Befehl installiert:<syntaxhighlight lang="shell"><br />
apt-get install android-sdk-platform-tools<br />
</syntaxhighlight>Für andere Plattformen (Windows, Linux x86, MacOS) findet man die Tools hier: https://developer.android.com/studio/releases/platform-tools<br />
<br />
Bei der manuellen Installation der Tools von developer.android.com (MacOs und Linux) muss man darauf achten, dass der Nutzer, unter dem der FHEM Prozess läuft, den Befehl 'adb' ausführen darf. Dazu ggf. die Rechte auf 'read' und 'execute' für alle setzen:<syntaxhighlight lang="shell"><br />
sudo chmod 755 adb<br />
</syntaxhighlight><br />
<br />
== Definition eines I/O Device (AndroidDBHost) ==<br />
Je FHEM Instanz gibt es nur 1 I/O Device. Die Syntax für die Definition sieht so aus:<br />
<br />
define Name AndroidDBHost [adb=Pfadangabe]<br />
<br />
Die Angabe des Parameters 'adb' ist nur erforderlich, wenn sich der Befehl 'adb' nicht im Suchpfad für ausführbare Programme befindet. Beispiel:<syntaxhighlight><br />
define myADBServer AndroidDBHost adb=/usr/local/platform-tools/adb<br />
</syntaxhighlight><br />
<br />
'''Defintion von Android Devices in FHEM'''<br />
<br />
Voraussetzung: Auf jedem Android Device, das über AndroidDB gesteuert werden soll, muss der Entwicklermodus aktiviert und das USB Debugging eingeschaltet sein. Das Gerät muss nicht(!) gerootet sein.<br />
<br />
Die Aktivierung des Entwicklermodus kann sich von Gerät zu Gerät etwas unterscheiden, ist aber meist ähnlich. Bei Android TV Geräten geht man so vor (einmalige Aktion je Gerät):<br />
<br />
- Geräteeinstellungen > Info auswählen<br />
<br />
- Ganz nach unten scrollen bis zu einer Angabe, die meistens "Build" oder "Version" heißt<br />
<br />
- Auf diese Angabe wiederholt drücken. Android zeigt dann irgendwann "in X Schritten bist Du Entwickler" an. Dann noch X Mal drücken bis "Du bist jetzt Entwickler" angezeigt wird<br />
<br />
- Nun unter Geräteeinstellungen > Entwickleroptionen das USB-Debugging einschalten (heißt zwar USB, die Verbindung erfolgt aber über das Netzwerk)<br />
<br />
Nun kann man ein AndroidDB Gerät in FHEM definieren:<br />
<br />
Code: [Auswählen]<br />
<br />
<code>define myTV AndroidDB 192.168.1.100</code><br />
<br />
Einziger Parameter ist die IP-Adresse des Android-Geräts (man sollte eine feste IP zuordnen). Beim ersten Zugriff auf das Gerät kann es sein, dass man auf dem Gerät einmal die Verbindung von FHEM zulassen muss. In dem Fall sollte man den Haken bei "Zugriff immer erlauben" setzen.<br />
<br />
Nun kann man sein Android Gerät steuern. Eine der nützlichsten Funktionen dürfte das Senden von Tastendrücken sein. So kann man in FHEM eine Fernbedieung realisieren.<br />
<br />
Beispiel: Home-Taste drücken<br />
<br />
Code: [Auswählen]<br />
<br />
<code>set myTV sendKey KEYCODE_HOME</code><br />
<br />
Beispiel: Umschalten auf Programm 12<br />
<br />
Code: [Auswählen]<br />
<br />
<code>set myTV sendKey KEYCODE_0 KEYCODE_0 KEYCODE_1 KEYCODE_2</code>(die beiden führenden 0en könnte man weglassen, dann dauert das Umschalten aber länger, da das Gerät wartet, ob weitere Tasten kommen)<br />
<br />
Eine Liste der Keycodes findet man hier: <nowiki>https://developer.android.com/reference/android/view/KeyEvent</nowiki><br />
<br />
'''Presets'''<br />
<br />
Ich habe einige Presets hinterlegt (am Beispiel eines Magenta TV Sticks). Ein Preset kann mit dem Attribut 'preset' eingestellt werden. Alternativ kann man mit dem Attribut 'macro' eigene RemoteControl Befehle definieren. Ein solcher Befehl kann mehrere Tastendrücke senden.<br />
<br />
Nach der Auswahl eines Presets kann man Befehle etwas abkürzen, z.B.:<br />
<br />
Code: [Auswählen]<br />
<br />
<code>set myTVStick remoteControl APPS</code><br />
<br />
<code>set myTVStick remoteControl EPG</code><br />
<br />
Mit Macros:<br />
<br />
Code: [Auswählen]<br />
<br />
<code>attr myTV macros DasErste:KEYCODE_0,KEYCODE_0,KEYCODE_0,KEYCODE_1</code><br />
<br />
<code>set myTV remoteControl DasErste</code><br />
<br />
'''In Arbeit:'''</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Readings&diff=36777HMCCU Readings2021-12-31T15:46:44Z<p>Zap: Zap verschob die Seite HMCCU Readings nach HMCCU Reading Namen: Anpassung Seitentitel</p>
<hr />
<div>#WEITERLEITUNG [[HMCCU Reading Namen]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Reading_Namen&diff=36776HMCCU Reading Namen2021-12-31T15:46:44Z<p>Zap: Zap verschob die Seite HMCCU Readings nach HMCCU Reading Namen: Anpassung Seitentitel</p>
<hr />
<div>== Arten von Readings ==<br />
Die Module HMCCUDEV und HMCCUCHN kennen 6 verschiedene Arten von Readings. Einige werden immer, andere nur nach dem Setzen von Flags im Attribut ccuflags angezeigt. Die folgende Tabelle fasst die Reading Arten zusammen:<br />
{| class="wikitable"<br />
|+<br />
Anzeige der Reading Arten<br />
!Readings für<br />
!Default Anzeige<br />
!Anzeige aktivieren mit<br />
!Aktualisierung<br />
|-<br />
|Datenpunkte<br />
|ja (Kanäle > 0)<br />
|ccuflags = showDeviceReadings (Kanal 0)<br />
|automatisch<br />
|-<br />
|Konfigurationsparameter<br />
|nein<br />
|ccuflags = showMasterReadings<br />
|manuell<br />
|-<br />
|Verknüpfungen / Links<br />
|nein<br />
|ccuflags = showLinkReadings<br />
|manuell<br />
|-<br />
|Services<br />
|nein<br />
|ccuflags = showServiceReadings<br />
|manuell<br />
|-<br />
|Gerätefunktionen<br />
|ja<br />
|immer aktiv<br />
|automatisch<br />
|-<br />
|Gerätestati<br />
|ja<br />
|immer aktiv<br />
|automatisch<br />
|}<br />
<br />
=== Readings für Datenpunkte ===<br />
Readings für Datenpunkte, Gerätefunktionen und Gerätestati werden automatisch aktualisiert, sofern die RPC Server konfiguriert und gestartet sind.<br />
<br />
Readings für Datenpunkte werden per Voreinstellung immer angezeigt. Eine Ausnahme sind die Datenpunkte für den Statuskanal 0, über den jedes Homematic Device verfügt. Diese werden nur angezeigt, wenn im Attribut '''ccuflags''' das Flag "showDeviceReadings" gesetzt ist. Dies ist normalerweise nicht notwendig, da die wichtigsten Datenpunkte in Kanal 0 in den Gerätefunktions-Readings und den Gerätestatus-Reading "devstate" und "hmstate" angezeigt werden.<br />
{| class="wikitable"<br />
|+Gerätefunktions-Readings<br />
!Datenpunkt Kanal 0<br />
!Reading<br />
!Bedeutung<br />
!Werte<br />
!Wert in Reading devstate<br />
|-<br />
|AES_KEY<br />
|sign<br />
|Verschlüsselung<br />
|yes, no<br />
|<br />
|-<br />
|LOW_BAT<br />
LOWBAT<br />
|battery<br />
|Batteriestatus<br />
|low, ok<br />
|<br />
|-<br />
|OPERATING_VOLTAGE<br />
|voltage<br />
|Batteriespannung<br />
|Zahl<br />
|<br />
|-<br />
|SABOTAGE<br />
ERROR_SABOTAGE<br />
|sabotage<br />
|Manipulationsversuch<br />
|yes, no<br />
|"sabotage"<br />
|-<br />
|UNREACH<br />
|activity<br />
|Erreichbarkeit<br />
|active, dead<br />
|"unreach"<br />
|-<br />
|STICKY_UNREACH<br />
|<br />
|Gerät war nicht erreichbar<br />
|<br />
|"stickyUnreach"<br />
|-<br />
|RSSI_DEVICE<br />
|rssidevice<br />
|Signalstärke<br />
|Zahl<br />
|<br />
|-<br />
|RSSI_PEER<br />
|rssipeer<br />
|Signalstärke<br />
|Zahl<br />
|<br />
|-<br />
|CONFIG_PENDING<br />
|<br />
|Konfiguration steht zur Übertragung an<br />
|<br />
|"cfgPending"<br />
|-<br />
|UPDATE_PENDING<br />
|<br />
|Firmware-Update steht zur Übertragung an<br />
|<br />
|"updPending"<br />
|-<br />
|DEVICE_IN_BOOTLOADER<br />
|<br />
|Gerät startet neu<br />
|<br />
|"boot"<br />
|}<br />
Das Reading "devstate" enthält einen oder mehrere der angegebenen Werte (letzte Spalte), sofern der zugehörige Datenpunkt den Wert "true" annimmt. Mehrere Werte werden durch Komma getrennt. Beispiel: "stickyUnreach,cfgPending".<br />
<br />
=== Readings für Konfigrationsparameter ===<br />
Readings für Konfigurationsparameter, Verknüpfungen und Services werden nur angezeigt, sofern im Attribut '''ccuflags''' das entsprechende Flag "showXXXReadings" gesetzt ist (siehe Tabelle oben). Diese Readings müssen mit dem Befehl '''get config''' manuell abgefragt werden.<br />
<br />
== Namen von Readings ==<br />
Per Default entsprechen die Namen der Readings den Namen der Datenpunkte / Parameter. Bei HMCCUDEV Devices wird die Kanalnummer vorangestellt, um identische Datenpunkte in mehreren Kanälen unterscheiden zu können. Die Namen der Readings können mit den Attributen '''ccureadingformat''', '''ccureadingname''' und '''ccuReadingPrefix''' beeinflusst werden.<br />
<br />
=== Reading Name Format - Attribut ccureadingformat ===<br />
Die folgende Tabelle zeigt anhand des Datenpunktes "LEVEL" im Kanal 1 eines Gerätes "Thermostat-Bad", wie die Einstellung im Attribut '''ccureadingformat''' den Reading Namen beeinflusst:<br />
{| class="wikitable"<br />
|+Reading Name Formate<br />
!ccureadingformat<br />
!Zusammensetzung Reading Name<br />
!Reading HMCCUDEV<br />
!Reading HMCCUCHN<br />
|-<br />
|datapoint<br />
|Datenpunkt<br />
|1.LEVEL<br />
|LEVEL<br />
|-<br />
|name<br />
|Gerätename, Kanal, Datenpunkt<br />
|Thermostat-Bad.1.LEVEL<br />
|Thermostat-Bad.1.LEVEL<br />
|-<br />
|address<br />
|Interface, Adresse, Kanal, Datenpunkt<br />
|HmIP-RF.000393C99BFC08.1.LEVEL<br />
|HmIP-RF.000393C99BFC08.1.LEVEL<br />
|}<br />
Wenn an das Reading-Format das Kürzel "lc" angehängt wird, wird der Reading Name in Kleinbuchstaben umgewandelt. Zusätzlich zu den 3 fest vorgegebenen Formaten kann auch ein Reading-Format mit Platzhaltern definiert werden. Folgende Platzhalter sind möglich:<br />
* %a, %A - Adresse<br />
* %c - Kanal<br />
* %n, %N - Gerätename<br />
* %d, %D - Datenpunkt / Parameter<br />
Beispiel: "Wert_von_%c_%D" ergibt beim Datenpunkt 1.LEVEL den Reading Namen "Wert_von_1_LEVEL".<br />
<br />
=== Reading Name Präfixe - Attribut ccuReadingPrefix ===<br />
Um Readings für Datenpunkte und Konfigurationsparameter voneinander abzugrenzen, stellt HMCCU den Reading Namen für Konfigurationsparameter (einschließlich Verknüpfungen und Services) ein Präfix voran. Dieses Präfix kann mit dem Attribut '''ccuReadingPrefix''' beeinflusst werden. Folgende Präfixe sind voreingestellt:<br />
{| class="wikitable"<br />
|+Reading Präfixe<br />
!Parameter Art<br />
!Parameter Set<br />
!Präfix<br />
|-<br />
|Datenpunkt<br />
|VALUES<br />
|<br />
|-<br />
|Konfigurationsparameter<br />
|MASTER<br />
|R-<br />
|-<br />
|Links / Verknüpfungen<br />
|LINK<br />
|L-<br />
|-<br />
|Services<br />
|SERVICE<br />
|S-<br />
|}<br />
Das folgende Beispiel legt das Präfix "C-" für Konfigurationsparameter fest und entfernt das Präfix für Links:<syntaxhighlight><br />
attr myDev ccuReadingPrefix MASTER:C-,LINK:<br />
</syntaxhighlight><br />
<br />
=== Readings umbenennen und unterdrücken - Attribut ccureadingname ===<br />
Mit dem Attribut ccureadingname können Readings ersetzt, um ein zusätzliches Reading ergänzt oder mehrere Datenpunkte/Parameter zu einem Reading zusammengefasst werden.<br />
<br />
Syntax zum Ersetzen von Readings:<br />
<br />
ccureadingname [Kanal.]ReadingnameAlt:ReadingnameNeu<br />
<br />
Syntax zum Hinzufügen von Readings:<br />
<br />
ccureadingname [Kanal.]ReadingnameAlt:+ReadingnameNeu<br />
<br />
Syntax zum Hinzufügen und Ersetzen von Readings:<br />
<br />
ccureadingname [Kanal.]ReadingnameAlt:+ReadingnameNeu1,ReadingnameNeu2<br />
<br />
Die Parameter ''Kanal'' und ''ReadingnameAlt'' sind reguläre Ausdrücke. Um Readings aus mehreren Kanälen zu einem neuen Reading zusammen zu fassen, wählt man einfach passende Ausdrücke für ''Kanal'' und ''ReadingNameAlt''.<br />
<br />
Beispiel: Ein Reading "anyKeyPressed" soll anzeigen, ob auf einer Fernbedienung entweder die Taste 2 oder 4 (entsprechend Kanal 2 oder 4) gedrückt wurde. Ein Tastendruck wird über den Datenpunkt PRESS_SHORT signalisiert. Die Readings 2.PRESS_SHORT und 4.PRESS_SHORT sollen beibehalten werden ("+").<syntaxhighlight><br />
attr myDev ccureadingname [24].^PRESS_SHORT$:+anyKeyPressed<br />
</syntaxhighlight>Mehrere Ersetzungsregeln werden durch Semikolons getrennt. Beispiel:<syntaxhighlight><br />
attr myDev ccureadingname PRESS_SHORT:pressed;ACTUAL_TEMPERATURE:temperature<br />
</syntaxhighlight><br />
<br />
== Filterung von Readings ==<br />
Sofern keine Attribute zur Filterung von Readings definiert sind, werden in HMCCUDEV/HMCCUCHN Devices Readings für alle Datenpunkte (Parameter Set VALUES) angezeigt. Die Datenpunkte und Parameter, die als Reading angezeigt werden sollen, können mit dem Attribut '''ccureadingfilter''' festgelegt werden.<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Reading_Namen&diff=36775HMCCU Reading Namen2021-12-31T15:45:37Z<p>Zap: </p>
<hr />
<div>== Arten von Readings ==<br />
Die Module HMCCUDEV und HMCCUCHN kennen 6 verschiedene Arten von Readings. Einige werden immer, andere nur nach dem Setzen von Flags im Attribut ccuflags angezeigt. Die folgende Tabelle fasst die Reading Arten zusammen:<br />
{| class="wikitable"<br />
|+<br />
Anzeige der Reading Arten<br />
!Readings für<br />
!Default Anzeige<br />
!Anzeige aktivieren mit<br />
!Aktualisierung<br />
|-<br />
|Datenpunkte<br />
|ja (Kanäle > 0)<br />
|ccuflags = showDeviceReadings (Kanal 0)<br />
|automatisch<br />
|-<br />
|Konfigurationsparameter<br />
|nein<br />
|ccuflags = showMasterReadings<br />
|manuell<br />
|-<br />
|Verknüpfungen / Links<br />
|nein<br />
|ccuflags = showLinkReadings<br />
|manuell<br />
|-<br />
|Services<br />
|nein<br />
|ccuflags = showServiceReadings<br />
|manuell<br />
|-<br />
|Gerätefunktionen<br />
|ja<br />
|immer aktiv<br />
|automatisch<br />
|-<br />
|Gerätestati<br />
|ja<br />
|immer aktiv<br />
|automatisch<br />
|}<br />
<br />
=== Readings für Datenpunkte ===<br />
Readings für Datenpunkte, Gerätefunktionen und Gerätestati werden automatisch aktualisiert, sofern die RPC Server konfiguriert und gestartet sind.<br />
<br />
Readings für Datenpunkte werden per Voreinstellung immer angezeigt. Eine Ausnahme sind die Datenpunkte für den Statuskanal 0, über den jedes Homematic Device verfügt. Diese werden nur angezeigt, wenn im Attribut '''ccuflags''' das Flag "showDeviceReadings" gesetzt ist. Dies ist normalerweise nicht notwendig, da die wichtigsten Datenpunkte in Kanal 0 in den Gerätefunktions-Readings und den Gerätestatus-Reading "devstate" und "hmstate" angezeigt werden.<br />
{| class="wikitable"<br />
|+Gerätefunktions-Readings<br />
!Datenpunkt Kanal 0<br />
!Reading<br />
!Bedeutung<br />
!Werte<br />
!Wert in Reading devstate<br />
|-<br />
|AES_KEY<br />
|sign<br />
|Verschlüsselung<br />
|yes, no<br />
|<br />
|-<br />
|LOW_BAT<br />
LOWBAT<br />
|battery<br />
|Batteriestatus<br />
|low, ok<br />
|<br />
|-<br />
|OPERATING_VOLTAGE<br />
|voltage<br />
|Batteriespannung<br />
|Zahl<br />
|<br />
|-<br />
|SABOTAGE<br />
ERROR_SABOTAGE<br />
|sabotage<br />
|Manipulationsversuch<br />
|yes, no<br />
|"sabotage"<br />
|-<br />
|UNREACH<br />
|activity<br />
|Erreichbarkeit<br />
|active, dead<br />
|"unreach"<br />
|-<br />
|STICKY_UNREACH<br />
|<br />
|Gerät war nicht erreichbar<br />
|<br />
|"stickyUnreach"<br />
|-<br />
|RSSI_DEVICE<br />
|rssidevice<br />
|Signalstärke<br />
|Zahl<br />
|<br />
|-<br />
|RSSI_PEER<br />
|rssipeer<br />
|Signalstärke<br />
|Zahl<br />
|<br />
|-<br />
|CONFIG_PENDING<br />
|<br />
|Konfiguration steht zur Übertragung an<br />
|<br />
|"cfgPending"<br />
|-<br />
|UPDATE_PENDING<br />
|<br />
|Firmware-Update steht zur Übertragung an<br />
|<br />
|"updPending"<br />
|-<br />
|DEVICE_IN_BOOTLOADER<br />
|<br />
|Gerät startet neu<br />
|<br />
|"boot"<br />
|}<br />
Das Reading "devstate" enthält einen oder mehrere der angegebenen Werte (letzte Spalte), sofern der zugehörige Datenpunkt den Wert "true" annimmt. Mehrere Werte werden durch Komma getrennt. Beispiel: "stickyUnreach,cfgPending".<br />
<br />
=== Readings für Konfigrationsparameter ===<br />
Readings für Konfigurationsparameter, Verknüpfungen und Services werden nur angezeigt, sofern im Attribut '''ccuflags''' das entsprechende Flag "showXXXReadings" gesetzt ist (siehe Tabelle oben). Diese Readings müssen mit dem Befehl '''get config''' manuell abgefragt werden.<br />
<br />
== Namen von Readings ==<br />
Per Default entsprechen die Namen der Readings den Namen der Datenpunkte / Parameter. Bei HMCCUDEV Devices wird die Kanalnummer vorangestellt, um identische Datenpunkte in mehreren Kanälen unterscheiden zu können. Die Namen der Readings können mit den Attributen '''ccureadingformat''', '''ccureadingname''' und '''ccuReadingPrefix''' beeinflusst werden.<br />
<br />
=== Reading Name Format - Attribut ccureadingformat ===<br />
Die folgende Tabelle zeigt anhand des Datenpunktes "LEVEL" im Kanal 1 eines Gerätes "Thermostat-Bad", wie die Einstellung im Attribut '''ccureadingformat''' den Reading Namen beeinflusst:<br />
{| class="wikitable"<br />
|+Reading Name Formate<br />
!ccureadingformat<br />
!Zusammensetzung Reading Name<br />
!Reading HMCCUDEV<br />
!Reading HMCCUCHN<br />
|-<br />
|datapoint<br />
|Datenpunkt<br />
|1.LEVEL<br />
|LEVEL<br />
|-<br />
|name<br />
|Gerätename, Kanal, Datenpunkt<br />
|Thermostat-Bad.1.LEVEL<br />
|Thermostat-Bad.1.LEVEL<br />
|-<br />
|address<br />
|Interface, Adresse, Kanal, Datenpunkt<br />
|HmIP-RF.000393C99BFC08.1.LEVEL<br />
|HmIP-RF.000393C99BFC08.1.LEVEL<br />
|}<br />
Wenn an das Reading-Format das Kürzel "lc" angehängt wird, wird der Reading Name in Kleinbuchstaben umgewandelt. Zusätzlich zu den 3 fest vorgegebenen Formaten kann auch ein Reading-Format mit Platzhaltern definiert werden. Folgende Platzhalter sind möglich:<br />
* %a, %A - Adresse<br />
* %c - Kanal<br />
* %n, %N - Gerätename<br />
* %d, %D - Datenpunkt / Parameter<br />
Beispiel: "Wert_von_%c_%D" ergibt beim Datenpunkt 1.LEVEL den Reading Namen "Wert_von_1_LEVEL".<br />
<br />
=== Reading Name Präfixe - Attribut ccuReadingPrefix ===<br />
Um Readings für Datenpunkte und Konfigurationsparameter voneinander abzugrenzen, stellt HMCCU den Reading Namen für Konfigurationsparameter (einschließlich Verknüpfungen und Services) ein Präfix voran. Dieses Präfix kann mit dem Attribut '''ccuReadingPrefix''' beeinflusst werden. Folgende Präfixe sind voreingestellt:<br />
{| class="wikitable"<br />
|+Reading Präfixe<br />
!Parameter Art<br />
!Parameter Set<br />
!Präfix<br />
|-<br />
|Datenpunkt<br />
|VALUES<br />
|<br />
|-<br />
|Konfigurationsparameter<br />
|MASTER<br />
|R-<br />
|-<br />
|Links / Verknüpfungen<br />
|LINK<br />
|L-<br />
|-<br />
|Services<br />
|SERVICE<br />
|S-<br />
|}<br />
Das folgende Beispiel legt das Präfix "C-" für Konfigurationsparameter fest und entfernt das Präfix für Links:<syntaxhighlight><br />
attr myDev ccuReadingPrefix MASTER:C-,LINK:<br />
</syntaxhighlight><br />
<br />
=== Readings umbenennen und unterdrücken - Attribut ccureadingname ===<br />
Mit dem Attribut ccureadingname können Readings ersetzt, um ein zusätzliches Reading ergänzt oder mehrere Datenpunkte/Parameter zu einem Reading zusammengefasst werden.<br />
<br />
Syntax zum Ersetzen von Readings:<br />
<br />
ccureadingname [Kanal.]ReadingnameAlt:ReadingnameNeu<br />
<br />
Syntax zum Hinzufügen von Readings:<br />
<br />
ccureadingname [Kanal.]ReadingnameAlt:+ReadingnameNeu<br />
<br />
Syntax zum Hinzufügen und Ersetzen von Readings:<br />
<br />
ccureadingname [Kanal.]ReadingnameAlt:+ReadingnameNeu1,ReadingnameNeu2<br />
<br />
Die Parameter ''Kanal'' und ''ReadingnameAlt'' sind reguläre Ausdrücke. Um Readings aus mehreren Kanälen zu einem neuen Reading zusammen zu fassen, wählt man einfach passende Ausdrücke für ''Kanal'' und ''ReadingNameAlt''.<br />
<br />
Beispiel: Ein Reading "anyKeyPressed" soll anzeigen, ob auf einer Fernbedienung entweder die Taste 2 oder 4 (entsprechend Kanal 2 oder 4) gedrückt wurde. Ein Tastendruck wird über den Datenpunkt PRESS_SHORT signalisiert. Die Readings 2.PRESS_SHORT und 4.PRESS_SHORT sollen beibehalten werden ("+").<syntaxhighlight><br />
attr myDev ccureadingname [24].^PRESS_SHORT$:+anyKeyPressed<br />
</syntaxhighlight>Mehrere Ersetzungsregeln werden durch Semikolons getrennt. Beispiel:<syntaxhighlight><br />
attr myDev ccureadingname PRESS_SHORT:pressed;ACTUAL_TEMPERATURE:temperature<br />
</syntaxhighlight><br />
<br />
== Filterung von Readings ==<br />
Sofern keine Attribute zur Filterung von Readings definiert sind, werden in HMCCUDEV/HMCCUCHN Devices Readings für alle Datenpunkte (Parameter Set VALUES) angezeigt. Die Datenpunkte und Parameter, die als Reading angezeigt werden sollen, können mit dem Attribut '''ccureadingfilter''' festgelegt werden.<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Reading_Namen&diff=36774HMCCU Reading Namen2021-12-31T15:42:08Z<p>Zap: Beschreibung weiterer Attribute</p>
<hr />
<div>== Arten von Readings ==<br />
Die Module HMCCUDEV und HMCCUCHN kennen 6 verschiedene Arten von Readings. Einige werden immer, andere nur nach dem Setzen von Flags im Attribut ccuflags angezeigt. Die folgende Tabelle fasst die Reading Arten zusammen:<br />
{| class="wikitable"<br />
|+<br />
Anzeige der Reading Arten<br />
!Readings für<br />
!Default Anzeige<br />
!Anzeige aktivieren mit<br />
!Aktualisierung<br />
|-<br />
|Datenpunkte<br />
|ja (Kanäle > 0)<br />
|ccuflags = showDeviceReadings (Kanal 0)<br />
|automatisch<br />
|-<br />
|Konfigurationsparameter<br />
|nein<br />
|ccuflags = showMasterReadings<br />
|manuell<br />
|-<br />
|Verknüpfungen / Links<br />
|nein<br />
|ccuflags = showLinkReadings<br />
|manuell<br />
|-<br />
|Services<br />
|nein<br />
|ccuflags = showServiceReadings<br />
|manuell<br />
|-<br />
|Gerätefunktionen<br />
|ja<br />
|immer aktiv<br />
|automatisch<br />
|-<br />
|Gerätestati<br />
|ja<br />
|immer aktiv<br />
|automatisch<br />
|}<br />
<br />
=== Readings für Datenpunkte ===<br />
Readings für Datenpunkte, Gerätefunktionen und Gerätestati werden automatisch aktualisiert, sofern die RPC Server konfiguriert und gestartet sind.<br />
<br />
Readings für Datenpunkte werden per Voreinstellung immer angezeigt. Eine Ausnahme sind die Datenpunkte für den Statuskanal 0, über den jedes Homematic Device verfügt. Diese werden nur angezeigt, wenn im Attribut '''ccuflags''' das Flag "showDeviceReadings" gesetzt ist. Dies ist normalerweise nicht notwendig, da die wichtigsten Datenpunkte in Kanal 0 in den Gerätefunktions-Readings und den Gerätestatus-Reading "devstate" und "hmstate" angezeigt werden.<br />
{| class="wikitable"<br />
|+Gerätefunktions-Readings<br />
!Datenpunkt Kanal 0<br />
!Reading<br />
!Bedeutung<br />
!Werte<br />
!Wert in Reading devstate<br />
|-<br />
|AES_KEY<br />
|sign<br />
|Verschlüsselung<br />
|yes, no<br />
|<br />
|-<br />
|LOW_BAT<br />
LOWBAT<br />
|battery<br />
|Batteriestatus<br />
|low, ok<br />
|<br />
|-<br />
|OPERATING_VOLTAGE<br />
|voltage<br />
|Batteriespannung<br />
|Zahl<br />
|<br />
|-<br />
|SABOTAGE<br />
ERROR_SABOTAGE<br />
|sabotage<br />
|Manipulationsversuch<br />
|yes, no<br />
|"sabotage"<br />
|-<br />
|UNREACH<br />
|activity<br />
|Erreichbarkeit<br />
|active, dead<br />
|"unreach"<br />
|-<br />
|STICKY_UNREACH<br />
|<br />
|Gerät war nicht erreichbar<br />
|<br />
|"stickyUnreach"<br />
|-<br />
|RSSI_DEVICE<br />
|rssidevice<br />
|Signalstärke<br />
|Zahl<br />
|<br />
|-<br />
|RSSI_PEER<br />
|rssipeer<br />
|Signalstärke<br />
|Zahl<br />
|<br />
|-<br />
|CONFIG_PENDING<br />
|<br />
|Konfiguration steht zur Übertragung an<br />
|<br />
|"cfgPending"<br />
|-<br />
|UPDATE_PENDING<br />
|<br />
|Firmware-Update steht zur Übertragung an<br />
|<br />
|"updPending"<br />
|-<br />
|DEVICE_IN_BOOTLOADER<br />
|<br />
|Gerät startet neu<br />
|<br />
|"boot"<br />
|}<br />
Das Reading "devstate" enthält einen oder mehrere der angegebenen Werte (letzte Spalte), sofern der zugehörige Datenpunkt den Wert "true" annimmt. Mehrere Werte werden durch Komma getrennt. Beispiel: "stickyUnreach,cfgPending".<br />
<br />
=== Readings für Konfigrationsparameter ===<br />
Readings für Konfigurationsparameter, Verknüpfungen und Services werden nur angezeigt, sofern im Attribut '''ccuflags''' das entsprechende Flag "showXXXReadings" gesetzt ist (siehe Tabelle oben). Diese Readings müssen mit dem Befehl '''get config''' manuell abgefragt werden.<br />
<br />
== Namen von Readings ==<br />
Per Default entsprechen die Namen der Readings den Namen der Datenpunkte / Parameter. Bei HMCCUDEV Devices wird die Kanalnummer vorangestellt, um identische Datenpunkte in mehreren Kanälen unterscheiden zu können. Die Namen der Readings können mit den Attributen '''ccureadingformat''', '''ccureadingname''' und '''ccuReadingPrefix''' beeinflusst werden.<br />
<br />
=== Reading Name Format - Attribut ccureadingformat ===<br />
Die folgende Tabelle zeigt anhand des Datenpunktes "LEVEL" im Kanal 1 eines Gerätes "Thermostat-Bad", wie die Einstellung im Attribut '''ccureadingformat''' den Reading Namen beeinflusst:<br />
{| class="wikitable"<br />
|+Reading Name Formate<br />
!ccureadingformat<br />
!Zusammensetzung Reading Name<br />
!Reading HMCCUDEV<br />
!Reading HMCCUCHN<br />
|-<br />
|datapoint<br />
|Datenpunkt<br />
|1.LEVEL<br />
|LEVEL<br />
|-<br />
|name<br />
|Gerätename, Kanal, Datenpunkt<br />
|Thermostat-Bad.1.LEVEL<br />
|Thermostat-Bad.1.LEVEL<br />
|-<br />
|address<br />
|Interface, Adresse, Kanal, Datenpunkt<br />
|HmIP-RF.000393C99BFC08.1.LEVEL<br />
|HmIP-RF.000393C99BFC08.1.LEVEL<br />
|}<br />
Wenn an das Reading-Format das Kürzel "lc" angehängt wird, wird der Reading Name in Kleinbuchstaben umgewandelt. Zusätzlich zu den 3 fest vorgegebenen Formaten kann auch ein Reading-Format mit Platzhaltern definiert werden. Folgende Platzhalter sind möglich:<br />
* %a, %A - Adresse<br />
* %c - Kanal<br />
* %n, %N - Gerätename<br />
* %d, %D - Datenpunkt / Parameter<br />
Beispiel: "Wert_von_%c_%D" ergibt beim Datenpunkt 1.LEVEL den Reading Namen "Wert_von_1_LEVEL".<br />
<br />
=== Reading Name Präfixe - Attribut ccuReadingPrefix ===<br />
Um Readings für Datenpunkte und Konfigurationsparameter voneinander abzugrenzen, stellt HMCCU den Reading Namen für Konfigurationsparameter (einschließlich Verknüpfungen und Services) ein Präfix voran. Dieses Präfix kann mit dem Attribut '''ccuReadingPrefix''' beeinflusst werden. Folgende Präfixe sind voreingestellt:<br />
{| class="wikitable"<br />
|+Reading Präfixe<br />
!Parameter Art<br />
!Parameter Set<br />
!Präfix<br />
|-<br />
|Datenpunkt<br />
|VALUES<br />
|<br />
|-<br />
|Konfigurationsparameter<br />
|MASTER<br />
|R-<br />
|-<br />
|Links / Verknüpfungen<br />
|LINK<br />
|L-<br />
|-<br />
|Services<br />
|SERVICE<br />
|S-<br />
|}<br />
Das folgende Beispiel legt das Präfix "C-" für Konfigurationsparameter fest und entfernt das Präfix für Links:<syntaxhighlight><br />
attr myDev ccuReadingPrefix MASTER:C-,LINK:<br />
</syntaxhighlight><br />
<br />
=== Readings umbenennen und unterdrücken - Attribut ccureadingname ===<br />
Mit dem Attribut ccureadingname können Readings ersetzt, um ein zusätzliches Reading ergänzt oder mehrere Datenpunkte/Parameter zu einem Reading zusammengefasst werden.<br />
<br />
Syntax zum Ersetzen von Readings:<br />
<br />
ccureadingname [Kanal.]ReadingnameAlt:ReadingnameNeu<br />
<br />
Syntax zum Hinzufügen von Readings:<br />
<br />
ccureadingname [Kanal.]ReadingnameAlt:+ReadingnameNeu<br />
<br />
Syntax zum Hinzufügen und Ersetzen von Readings:<br />
<br />
ccureadingname [Kanal.]ReadingnameAlt:+ReadingnameNeu1,ReadingnameNeu2<br />
<br />
Die Parameter ''Kanal'' und ''ReadingnameAlt'' sind reguläre Ausdrücke. Um Readings aus mehreren Kanälen zu einem neuen Reading zusammen zu fassen, wählt man einfach passende Ausdrücke für ''Kanal'' und ''ReadingNameAlt''.<br />
<br />
Beispiel: Ein Reading "anyKeyPressed" soll anzeigen, ob auf einer Fernbedienung entweder die Taste 2 oder 4 (entsprechend Kanal 2 oder 4) gedrückt wurde. Ein Tastendruck wird über den Datenpunkt PRESS_SHORT signalisiert. Die Readings 2.PRESS_SHORT und 4.PRESS_SHORT sollen beibehalten werden ("+").<syntaxhighlight><br />
attr myDev ccureadingname [24].^PRESS_SHORT$:+anyKeyPressed<br />
</syntaxhighlight>Mehrere Ersetzungsregeln werden durch Semikolons getrennt. Beispiel:<syntaxhighlight><br />
attr myDev ccureadingname PRESS_SHORT:pressed;ACTUAL_TEMPERATURE:temperature<br />
</syntaxhighlight><br />
<br />
== Filterung von Readings ==<br />
Sofern keine Attribute zur Filterung von Readings definiert sind, werden in HMCCUDEV/HMCCUCHN Devices Readings für alle Datenpunkte (Parameter Set VALUES) angezeigt. Die Datenpunkte und Parameter, die als Reading angezeigt werden sollen, können mit dem Attribut '''ccureadingfilter''' festgelegt werden.</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Reading_Namen&diff=36739HMCCU Reading Namen2021-12-30T15:34:01Z<p>Zap: /* Namen von Readings */</p>
<hr />
<div>== Arten von Readings ==<br />
Die Module HMCCUDEV und HMCCUCHN kennen 6 verschiedene Arten von Readings. Einige werden immer, andere nur nach dem Setzen von Flags im Attribut ccuflags angezeigt. Die folgende Tabelle fasst die Reading Arten zusammen:<br />
{| class="wikitable"<br />
|+<br />
Anzeige der Reading Arten<br />
!Readings für<br />
!Default Anzeige<br />
!Anzeige aktivieren mit<br />
!Aktualisierung<br />
|-<br />
|Datenpunkte<br />
|ja (Kanäle > 0)<br />
|ccuflags = showDeviceReadings (Kanal 0)<br />
|automatisch<br />
|-<br />
|Konfigurationsparameter<br />
|nein<br />
|ccuflags = showMasterReadings<br />
|manuell<br />
|-<br />
|Verknüpfungen / Links<br />
|nein<br />
|ccuflags = showLinkReadings<br />
|manuell<br />
|-<br />
|Services<br />
|nein<br />
|ccuflags = showServiceReadings<br />
|manuell<br />
|-<br />
|Gerätefunktionen<br />
|ja<br />
|immer aktiv<br />
|automatisch<br />
|-<br />
|Gerätestati<br />
|ja<br />
|immer aktiv<br />
|automatisch<br />
|}<br />
<br />
=== Readings für Datenpunkte ===<br />
Readings für Datenpunkte, Gerätefunktionen und Gerätestati werden automatisch aktualisiert, sofern die RPC Server konfiguriert und gestartet sind.<br />
<br />
Readings für Datenpunkte werden per Voreinstellung immer angezeigt. Eine Ausnahme sind die Datenpunkte für den Statuskanal 0, über den jedes Homematic Device verfügt. Diese werden nur angezeigt, wenn im Attribut '''ccuflags''' das Flag "showDeviceReadings" gesetzt ist. Dies ist normalerweise nicht notwendig, da die wichtigsten Datenpunkte in Kanal 0 in den Gerätefunktions-Readings und den Gerätestatus-Reading "devstate" und "hmstate" angezeigt werden.<br />
{| class="wikitable"<br />
|+Gerätefunktions-Readings<br />
!Datenpunkt Kanal 0<br />
!Reading<br />
!Bedeutung<br />
!Werte<br />
!Wert in Reading devstate<br />
|-<br />
|AES_KEY<br />
|sign<br />
|Verschlüsselung<br />
|yes, no<br />
|<br />
|-<br />
|LOW_BAT<br />
LOWBAT<br />
|battery<br />
|Batteriestatus<br />
|low, ok<br />
|<br />
|-<br />
|OPERATING_VOLTAGE<br />
|voltage<br />
|Batteriespannung<br />
|Zahl<br />
|<br />
|-<br />
|SABOTAGE<br />
ERROR_SABOTAGE<br />
|sabotage<br />
|Manipulationsversuch<br />
|yes, no<br />
|"sabotage"<br />
|-<br />
|UNREACH<br />
|activity<br />
|Erreichbarkeit<br />
|active, dead<br />
|"unreach"<br />
|-<br />
|STICKY_UNREACH<br />
|<br />
|Gerät war nicht erreichbar<br />
|<br />
|"stickyUnreach"<br />
|-<br />
|RSSI_DEVICE<br />
|rssidevice<br />
|Signalstärke<br />
|Zahl<br />
|<br />
|-<br />
|RSSI_PEER<br />
|rssipeer<br />
|Signalstärke<br />
|Zahl<br />
|<br />
|-<br />
|CONFIG_PENDING<br />
|<br />
|Konfiguration steht zur Übertragung an<br />
|<br />
|"cfgPending"<br />
|-<br />
|UPDATE_PENDING<br />
|<br />
|Firmware-Update steht zur Übertragung an<br />
|<br />
|"updPending"<br />
|-<br />
|DEVICE_IN_BOOTLOADER<br />
|<br />
|Gerät startet neu<br />
|<br />
|"boot"<br />
|}<br />
Das Reading "devstate" enthält einen oder mehrere der angegebenen Werte (letzte Spalte), sofern der zugehörige Datenpunkt den Wert "true" annimmt. Mehrere Werte werden durch Komma getrennt. Beispiel: "stickyUnreach,cfgPending".<br />
<br />
=== Readings für Konfigrationsparameter ===<br />
Readings für Konfigurationsparameter, Verknüpfungen und Services werden nur angezeigt, sofern im Attribut '''ccuflags''' das entsprechende Flag "showXXXReadings" gesetzt ist (siehe Tabelle oben). Diese Readings müssen mit dem Befehl '''get config''' manuell abgefragt werden.<br />
<br />
== Namen von Readings ==<br />
Per Default entsprechen die Namen der Readings den Namen der Datenpunkte / Parameter. Bei HMCCUDEV Devices wird die Kanalnummer vorangestellt, um identische Datenpunkte in mehreren Kanälen unterscheiden zu können. Die Namen der Readings können mit den Attributen '''ccureadingformat''', '''ccureadingname''' und '''ccuReadingPrefix''' beeinflusst werden.<br />
<br />
=== Das Attribut ccureadingformat ===<br />
Die folgende Tabelle zeigt anhand des Datenpunktes "LEVEL" im Kanal 1 eines Gerätes "Thermostat-Bad", wie die Einstellung im Attribut '''ccureadingformat''' den Reading Namen beeinflusst:<br />
{| class="wikitable"<br />
|+Reading Name Formate<br />
!ccureadingformat<br />
!Zusammensetzung Reading Name<br />
!Reading HMCCUDEV<br />
!Reading HMCCUCHN<br />
|-<br />
|datapoint<br />
|Datenpunkt<br />
|1.LEVEL<br />
|LEVEL<br />
|-<br />
|name<br />
|Gerätename, Kanal, Datenpunkt<br />
|Thermostat-Bad.1.LEVEL<br />
|Thermostat-Bad.1.LEVEL<br />
|-<br />
|address<br />
|Interface, Adresse, Kanal, Datenpunkt<br />
|HmIP-RF.000393C99BFC08.1.LEVEL<br />
|HmIP-RF.000393C99BFC08.1.LEVEL<br />
|}<br />
Wenn an das Reading-Format das Kürzel "lc" angehängt wird, wird der Reading Name in Kleinbuchstaben umgewandelt. Zusätzlich zu den 3 fest vorgegebenen Formaten kann auch ein Reading-Format mit Platzhaltern definiert werden. Folgende Platzhalter sind möglich:<br />
* %a, %A - Adresse<br />
* %c - Kanal<br />
* %n, %N - Gerätename<br />
* %d, %D - Datenpunkt / Parameter<br />
Beispiel: "Wert_von_%c_%D" ergibt beim Datenpunkt 1.LEVEL den Reading Namen "Wert_von_1_LEVEL".<br />
<br />
=== Das Attribut ccuReadingPrefix ===<br />
Um Readings für Datenpunkte und Konfigurationsparameter voneinander abzugrenzen, stellt HMCCU den Reading Namen für Konfigurationsparameter (einschließlich Verknüpfungen und Services) ein Präfix voran. Dieses Präfix kann mit dem Attribut ccuReadingPrefix beeinflusst werden:<br />
<br />
== Filterung von Readings ==<br />
Sofern keine Attribute zur Filterung von Readings definiert sind, werden in HMCCUDEV/HMCCUCHN Device</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Reading_Namen&diff=36738HMCCU Reading Namen2021-12-30T15:30:10Z<p>Zap: Beschreibung von Readings in HMCCU</p>
<hr />
<div>== Arten von Readings ==<br />
Die Module HMCCUDEV und HMCCUCHN kennen 6 verschiedene Arten von Readings. Einige werden immer, andere nur nach dem Setzen von Flags im Attribut ccuflags angezeigt. Die folgende Tabelle fasst die Reading Arten zusammen:<br />
{| class="wikitable"<br />
|+<br />
Anzeige der Reading Arten<br />
!Readings für<br />
!Default Anzeige<br />
!Anzeige aktivieren mit<br />
!Aktualisierung<br />
|-<br />
|Datenpunkte<br />
|ja (Kanäle > 0)<br />
|ccuflags = showDeviceReadings (Kanal 0)<br />
|automatisch<br />
|-<br />
|Konfigurationsparameter<br />
|nein<br />
|ccuflags = showMasterReadings<br />
|manuell<br />
|-<br />
|Verknüpfungen / Links<br />
|nein<br />
|ccuflags = showLinkReadings<br />
|manuell<br />
|-<br />
|Services<br />
|nein<br />
|ccuflags = showServiceReadings<br />
|manuell<br />
|-<br />
|Gerätefunktionen<br />
|ja<br />
|immer aktiv<br />
|automatisch<br />
|-<br />
|Gerätestati<br />
|ja<br />
|immer aktiv<br />
|automatisch<br />
|}<br />
<br />
=== Readings für Datenpunkte ===<br />
Readings für Datenpunkte, Gerätefunktionen und Gerätestati werden automatisch aktualisiert, sofern die RPC Server konfiguriert und gestartet sind.<br />
<br />
Readings für Datenpunkte werden per Voreinstellung immer angezeigt. Eine Ausnahme sind die Datenpunkte für den Statuskanal 0, über den jedes Homematic Device verfügt. Diese werden nur angezeigt, wenn im Attribut '''ccuflags''' das Flag "showDeviceReadings" gesetzt ist. Dies ist normalerweise nicht notwendig, da die wichtigsten Datenpunkte in Kanal 0 in den Gerätefunktions-Readings und den Gerätestatus-Reading "devstate" und "hmstate" angezeigt werden.<br />
{| class="wikitable"<br />
|+Gerätefunktions-Readings<br />
!Datenpunkt Kanal 0<br />
!Reading<br />
!Bedeutung<br />
!Werte<br />
!Wert in Reading devstate<br />
|-<br />
|AES_KEY<br />
|sign<br />
|Verschlüsselung<br />
|yes, no<br />
|<br />
|-<br />
|LOW_BAT<br />
LOWBAT<br />
|battery<br />
|Batteriestatus<br />
|low, ok<br />
|<br />
|-<br />
|OPERATING_VOLTAGE<br />
|voltage<br />
|Batteriespannung<br />
|Zahl<br />
|<br />
|-<br />
|SABOTAGE<br />
ERROR_SABOTAGE<br />
|sabotage<br />
|Manipulationsversuch<br />
|yes, no<br />
|"sabotage"<br />
|-<br />
|UNREACH<br />
|activity<br />
|Erreichbarkeit<br />
|active, dead<br />
|"unreach"<br />
|-<br />
|STICKY_UNREACH<br />
|<br />
|Gerät war nicht erreichbar<br />
|<br />
|"stickyUnreach"<br />
|-<br />
|RSSI_DEVICE<br />
|rssidevice<br />
|Signalstärke<br />
|Zahl<br />
|<br />
|-<br />
|RSSI_PEER<br />
|rssipeer<br />
|Signalstärke<br />
|Zahl<br />
|<br />
|-<br />
|CONFIG_PENDING<br />
|<br />
|Konfiguration steht zur Übertragung an<br />
|<br />
|"cfgPending"<br />
|-<br />
|UPDATE_PENDING<br />
|<br />
|Firmware-Update steht zur Übertragung an<br />
|<br />
|"updPending"<br />
|-<br />
|DEVICE_IN_BOOTLOADER<br />
|<br />
|Gerät startet neu<br />
|<br />
|"boot"<br />
|}<br />
Das Reading "devstate" enthält einen oder mehrere der angegebenen Werte (letzte Spalte), sofern der zugehörige Datenpunkt den Wert "true" annimmt. Mehrere Werte werden durch Komma getrennt. Beispiel: "stickyUnreach,cfgPending".<br />
<br />
=== Readings für Konfigrationsparameter ===<br />
Readings für Konfigurationsparameter, Verknüpfungen und Services werden nur angezeigt, sofern im Attribut '''ccuflags''' das entsprechende Flag "showXXXReadings" gesetzt ist (siehe Tabelle oben). Diese Readings müssen mit dem Befehl '''get config''' manuell abgefragt werden.<br />
<br />
== Namen von Readings ==<br />
Per Default entsprechen die Namen der Readings den Namen der Datenpunkte / Parameter. Bei HMCCUDEV Devices wird die Kanalnummer vorangestellt, um identische Datenpunkte in mehreren Kanälen unterscheiden zu können. Die Namen der Readings können mit den Attributen '''ccureadingformat''', '''ccureadingname''' und '''ccuReadingPrefix''' beeinflusst werden.<br />
<br />
=== Das Attribut ccureadingformat ===<br />
Die folgende Tabelle zeigt anhand des Datenpunktes "LEVEL" im Kanal 1 eines Gerätes "Thermostat-Bad", wie die Einstellung im Attribut '''ccureadingformat''' den Reading Namen beeinflusst:<br />
{| class="wikitable"<br />
|+Reading Name Formate<br />
!ccureadingformat<br />
!Zusammensetzung Reading Name<br />
!Reading HMCCUDEV<br />
!Reading HMCCUCHN<br />
|-<br />
|datapoint<br />
|Datenpunkt<br />
|1.LEVEL<br />
|LEVEL<br />
|-<br />
|name<br />
|Gerätename, Kanal, Datenpunkt<br />
|Thermostat-Bad.1.LEVEL<br />
|Thermostat-Bad.1.LEVEL<br />
|-<br />
|address<br />
|Interface, Adresse, Kanal, Datenpunkt<br />
|HmIP-RF.000393C99BFC08.1.LEVEL<br />
|HmIP-RF.000393C99BFC08.1.LEVEL<br />
|}<br />
Wenn an das Reading-Format das Kürzel "lc" angehängt wird, wird der Reading Name in Kleinbuchstaben umgewandelt. Zusätzlich zu den 3 fest vorgegebenen Formaten kann auch ein Reading-Format mit Platzhaltern definiert werden. Folgende Platzhalter sind möglich:<br />
* %a, %A - Adresse<br />
* %c - Kanal<br />
* %n, %N - Gerätename<br />
* %d, %D - Datenpunkt / Parameter<br />
Beispiel: "Wert_von_%c_%D" ergibt beim Datenpunkt 1.LEVEL den Reading Namen "Wert_von_1_LEVEL".<br />
<br />
== Filterung von Readings ==<br />
Sofern keine Attribute zur Filterung von Readings definiert sind, werden in HMCCUDEV/HMCCUCHN Device</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Reading_Namen&diff=36737HMCCU Reading Namen2021-12-30T10:34:07Z<p>Zap: HMCCU Readings</p>
<hr />
<div>Arten von Readings in HMCCUDEV und HMCCUCHN Devices<br />
{| class="wikitable"<br />
|+<br />
!Readings für<br />
!Anzeige<br />
|-<br />
|Datenpunkte<br />
|immer für Kanäle > 0, sofern kein Filter definiert<br />
|-<br />
|Konfigurationsparameter<br />
|nur wenn Attribut ccuflags = showMasterReadings<br />
|-<br />
|Gerätefunktionen<br />
|immer<br />
|-<br />
|Gerätestati<br />
|<br />
|}<br />
* Readings für Datenpunkte (werden per Default angezeigt, Ausnahme: Datenpunkte von Kanal 0)<br />
* Readings für Konfigurationsparameter (<br />
* Alternative Readings für Datenpunkte (werden<br />
* Status Readings<br />
Filterung von Readings<br />
<br />
Sofern keine Attribute zur Filterung von Readings definiert sind, werden in HMCCUDEV/HMCCUCHN Device</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=36717HMCCU2021-12-29T14:12:35Z<p>Zap: /* RPC Server konfigurieren und starten */</p>
<hr />
<div>Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. <br />
{{Hinweis|Dieser Artikel bezieht sich auf die neue HMCCU Version 5.0}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung HomeMatic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (HomeMatic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von HomeMatic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Der oben beschriebene Aufbau lässt sich am Beispiel einer Steckdose veranschaulichen:<syntaxhighlight lang="Text"><br />
DEV ST-WR-Waschmaschine KEQ0965669 interface=BidCos-RF type=HM-ES-PMSw1-Pl<br />
CHN KEQ0965669:0 ST-WR-Waschmaschine:0<br />
0.UNREACH = false {b} [RE]<br />
0.STICKY_UNREACH = true {b} [RWE]<br />
0.CONFIG_PENDING = false {b} [RE]<br />
0.DUTYCYCLE = false {b} [RE]<br />
0.RSSI_DEVICE = 1 {n} [RE]<br />
0.RSSI_PEER = 214 {n} [RE]<br />
0.DEVICE_IN_BOOTLOADER = false {b} [RE]<br />
0.UPDATE_PENDING = false {b} [RE]<br />
0.AES_KEY = 0 {n} [R]<br />
CHN KEQ0965669:1 ST-WR-Waschmaschine:1<br />
1.STATE = true {b} [RWE]<br />
1.ON_TIME = {f} [W]<br />
1.INHIBIT = false {b} [RWE]<br />
1.INSTALL_TEST = {b} [W]<br />
1.WORKING = false {b} [RE]<br />
CHN KEQ0965669:2 ST-WR-Waschmaschine:2<br />
2.ENERGY_COUNTER = 59348.000000 {f} [RE]<br />
2.POWER = 0.120000 {f} [RE]<br />
2.CURRENT = 45.000000 {f} [RE]<br />
2.VOLTAGE = 233.000000 {f} [RE]<br />
2.FREQUENCY = 49.990000 {f} [RE]<br />
2.BOOT = true {b} [RE]<br />
</syntaxhighlight><br />
Das Gerät in diesem Beispiel hat 3 nutzbare Kanäle: <br />
* 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. <br />
* 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 <br />
* Kanal 2 ist ein reiner Statuskanal. Er besitzt keine beschreibbaren Datenpunkte (nur '''R'''ead und '''E'''vent). <br />
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. <br />
<br />
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. <br />
<br />
{{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).}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* 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.<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. <br />
<br />
Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden oder alternativ CPAN verwendet werden:<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren<br />
<syntaxhighlight lang="doscon"><br />
cpan install RPC::XML<br />
</syntaxhighlight><br />
Bei der Installation gemäß [[FHEM Installation Windows]] befindet sich cpan man unter <code><FHEM-Hauptverzeichis>\perl\bin</code><br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
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<br />
<br />
===RPC Server konfigurieren und starten===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
== Migration von HMCCU 4.3 ==<br />
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.<br />
<br />
Wichtig: Nach dem Zurücksetzen der Attribute mit '''set defaults reset''' die Konfiguration speichern und FHEM neu starten.<br />
<br />
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.<br />
<br />
==Synchronisation mit der CCU==<br />
<br />
=== Geräte synchronisieren ===<br />
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.<br />
<br />
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.<br />
<br />
=== Datenpunkte (Readings) synchronisieren ===<br />
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.<br />
<br />
==Autocreate von FHEM-Devices für CCU Geräte==<br />
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.<br />
<br />
{{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}}<br />
<br />
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.<br />
<br />
Beispiel: Für das CCU-Gerät "Heizung-Wohnzimmer" soll ein FHEM-Device angelegt werden:<br />
get d_ccu createDev Heizung-Wohnzimmer<br />
Beispiel: Für alle CCU-Geräte, deren Namen mit "Heizung" beginnt, sollen FHEM-Devices angelegt werden:<br />
get d_ccu create Heizung.* room=Homematic group=Heizung<br />
Beim vorherigen Beispiel wird als Gerätename ein regulärer Ausdruck ("Heizung.*) angegeben. Jedes angelegte Gerät bekommt die Attribute "room" und "group" zugewiesen.<br />
<br />
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.<br />
<br />
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:<br />
get d_ccu createDev FB-Rollladen<br />
erzeugt die HMCCUCHN Devices: FB-Rollladen-Wohnzimmer, FB-Rollladen-Kueche.<br />
<br />
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:<br />
<syntaxhighlight lang="Text"><br />
attr d_ccu ccudef-attributes room=Homematic<br />
</syntaxhighlight><br />
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:<br />
<syntaxhighlight lang="Text"><br />
attr d_ccu createDeviceGroup %n<br />
</syntaxhighlight><br />
Die möglichen Platzhalter (wie z.B. %n) können der Commandref entnommen werden.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
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. <br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
<br />
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.<br />
<br />
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:<br />
<pre>attr d_ccu ccuGetVars 60<br />
attr d_ccu ccuGetVars 60:^A</pre><br />
<br />
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.<br />
<br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
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".<br />
<br />
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":<br />
<pre>set d_ccu var text Wetter sonnig</pre><br />
<br />
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:<br />
<br />
* unit = Einheit<br />
* desc = Beschreibung<br />
* min = Kleinster erlaubter Wert bei numerischen Variablen<br />
* max = Größter erlaubter Wert bei numerischen Variablen<br />
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen<br />
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"<br />
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"<br />
<br />
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:<br />
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: HomeMatic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von HomeMatic Scripts===<br />
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.''<br />
<br />
Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]<br />
[[Kategorie:Interfaces]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=36252HMCCU2021-11-23T10:08:17Z<p>Zap: /* Autocreate von FHEM-Devices für CCU Geräte */</p>
<hr />
<div>Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. <br />
<br />
{{Hinweis|Dieser Artikel bezieht sich auf die neue HMCCU Version 5.0}}{{Infobox Modul<br />
|ModPurpose=Anbindung HomeMatic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (HomeMatic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von HomeMatic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Der oben beschriebene Aufbau lässt sich am Beispiel einer Steckdose veranschaulichen:<syntaxhighlight><br />
DEV ST-WR-Waschmaschine KEQ0965669 interface=BidCos-RF type=HM-ES-PMSw1-Pl<br />
CHN KEQ0965669:0 ST-WR-Waschmaschine:0<br />
0.UNREACH = false {b} [RE]<br />
0.STICKY_UNREACH = true {b} [RWE]<br />
0.CONFIG_PENDING = false {b} [RE]<br />
0.DUTYCYCLE = false {b} [RE]<br />
0.RSSI_DEVICE = 1 {n} [RE]<br />
0.RSSI_PEER = 214 {n} [RE]<br />
0.DEVICE_IN_BOOTLOADER = false {b} [RE]<br />
0.UPDATE_PENDING = false {b} [RE]<br />
0.AES_KEY = 0 {n} [R]<br />
CHN KEQ0965669:1 ST-WR-Waschmaschine:1<br />
1.STATE = true {b} [RWE]<br />
1.ON_TIME = {f} [W]<br />
1.INHIBIT = false {b} [RWE]<br />
1.INSTALL_TEST = {b} [W]<br />
1.WORKING = false {b} [RE]<br />
CHN KEQ0965669:2 ST-WR-Waschmaschine:2<br />
2.ENERGY_COUNTER = 59348.000000 {f} [RE]<br />
2.POWER = 0.120000 {f} [RE]<br />
2.CURRENT = 45.000000 {f} [RE]<br />
2.VOLTAGE = 233.000000 {f} [RE]<br />
2.FREQUENCY = 49.990000 {f} [RE]<br />
2.BOOT = true {b} [RE]<br />
</syntaxhighlight>Das Gerät in diesem Beispiel hat 3 nutzbare Kanäle: <br />
* 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. <br />
* 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 <br />
* Kanal 2 ist ein reiner Statuskanal. Er besitzt keine beschreibbaren Datenpunkte (nur '''R'''ead und '''E'''vent). <br />
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. <br />
<br />
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. <br />
<br />
{{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).}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* 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.<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. <br />
<br />
Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden oder alternativ CPAN verwendet werden:<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren<br />
<syntaxhighlight lang="doscon"><br />
cpan install RPC::XML<br />
</syntaxhighlight><br />
Bei der Installation gemäß [[FHEM Installation Windows]] befindet sich cpan man unter <code><FHEM-Hauptverzeichis>\perl\bin</code><br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
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<br />
<br />
===RPC Server konfigurieren und starten===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
== Migration von HMCCU 4.3 ==<br />
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.<br />
<br />
Wichtig: Nach dem Zurücksetzen der Attribute mit '''set defaults reset''' die Konfiguration speichern und FHEM neu starten.<br />
<br />
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.<br />
<br />
==Synchronisation mit der CCU==<br />
<br />
=== Geräte synchronisieren ===<br />
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.<br />
<br />
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.<br />
<br />
=== Datenpunkte (Readings) synchronisieren ===<br />
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.<br />
<br />
==Autocreate von FHEM-Devices für CCU Geräte==<br />
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.<br />
<br />
{{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}}<br />
<br />
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.<br />
<br />
Beispiel: Für das CCU-Gerät "Heizung-Wohnzimmer" soll ein FHEM-Device angelegt werden:<br />
get d_ccu createDev Heizung-Wohnzimmer<br />
Beispiel: Für alle CCU-Geräte, deren Namen mit "Heizung" beginnt, sollen FHEM-Devices angelegt werden:<br />
get d_ccu create Heizung.* room=Homematic group=Heizung<br />
Beim vorherigen Beispiel wird als Gerätename ein regulärer Ausdruck ("Heizung.*) angegeben. Jedes angelegte Gerät bekommt die Attribute "room" und "group" zugewiesen.<br />
<br />
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.<br />
<br />
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:<br />
get d_ccu createDev FB-Rollladen<br />
erzeugt die HMCCUCHN Devices: FB-Rollladen-Wohnzimmer, FB-Rollladen-Kueche.<br />
<br />
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 mal folgendes Attribut im I/O Device:<syntaxhighlight><br />
attr d_ccu ccudef-attributes room=Homematic<br />
</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><br />
attr d_ccu createDeviceGroup %n<br />
</syntaxhighlight>Die möglichen Platzhalter (wie z.B. %n) können der Commandref entnommen werden.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
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. <br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
<br />
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.<br />
<br />
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:<br />
<pre>attr d_ccu ccuGetVars 60<br />
attr d_ccu ccuGetVars 60:^A</pre><br />
<br />
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.<br />
<br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
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".<br />
<br />
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":<br />
<pre>set d_ccu var text Wetter sonnig</pre><br />
<br />
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:<br />
<br />
* unit = Einheit<br />
* desc = Beschreibung<br />
* min = Kleinster erlaubter Wert bei numerischen Variablen<br />
* max = Größter erlaubter Wert bei numerischen Variablen<br />
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen<br />
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"<br />
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"<br />
<br />
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:<br />
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: HomeMatic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von HomeMatic Scripts===<br />
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.''<br />
<br />
Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]<br />
[[Kategorie:Interfaces]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=36251HMCCU2021-11-23T09:48:39Z<p>Zap: /* Geräte, Kanäle und Datenpunkte */</p>
<hr />
<div>Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. <br />
<br />
{{Hinweis|Dieser Artikel bezieht sich auf die neue HMCCU Version 5.0}}{{Infobox Modul<br />
|ModPurpose=Anbindung HomeMatic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (HomeMatic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von HomeMatic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Der oben beschriebene Aufbau lässt sich am Beispiel einer Steckdose veranschaulichen:<syntaxhighlight><br />
DEV ST-WR-Waschmaschine KEQ0965669 interface=BidCos-RF type=HM-ES-PMSw1-Pl<br />
CHN KEQ0965669:0 ST-WR-Waschmaschine:0<br />
0.UNREACH = false {b} [RE]<br />
0.STICKY_UNREACH = true {b} [RWE]<br />
0.CONFIG_PENDING = false {b} [RE]<br />
0.DUTYCYCLE = false {b} [RE]<br />
0.RSSI_DEVICE = 1 {n} [RE]<br />
0.RSSI_PEER = 214 {n} [RE]<br />
0.DEVICE_IN_BOOTLOADER = false {b} [RE]<br />
0.UPDATE_PENDING = false {b} [RE]<br />
0.AES_KEY = 0 {n} [R]<br />
CHN KEQ0965669:1 ST-WR-Waschmaschine:1<br />
1.STATE = true {b} [RWE]<br />
1.ON_TIME = {f} [W]<br />
1.INHIBIT = false {b} [RWE]<br />
1.INSTALL_TEST = {b} [W]<br />
1.WORKING = false {b} [RE]<br />
CHN KEQ0965669:2 ST-WR-Waschmaschine:2<br />
2.ENERGY_COUNTER = 59348.000000 {f} [RE]<br />
2.POWER = 0.120000 {f} [RE]<br />
2.CURRENT = 45.000000 {f} [RE]<br />
2.VOLTAGE = 233.000000 {f} [RE]<br />
2.FREQUENCY = 49.990000 {f} [RE]<br />
2.BOOT = true {b} [RE]<br />
</syntaxhighlight>Das Gerät in diesem Beispiel hat 3 nutzbare Kanäle: <br />
* 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. <br />
* 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 <br />
* Kanal 2 ist ein reiner Statuskanal. Er besitzt keine beschreibbaren Datenpunkte (nur '''R'''ead und '''E'''vent). <br />
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. <br />
<br />
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. <br />
<br />
{{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).}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* 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.<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. <br />
<br />
Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden oder alternativ CPAN verwendet werden:<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren<br />
<syntaxhighlight lang="doscon"><br />
cpan install RPC::XML<br />
</syntaxhighlight><br />
Bei der Installation gemäß [[FHEM Installation Windows]] befindet sich cpan man unter <code><FHEM-Hauptverzeichis>\perl\bin</code><br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
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<br />
<br />
===RPC Server konfigurieren und starten===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
== Migration von HMCCU 4.3 ==<br />
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.<br />
<br />
Wichtig: Nach dem Zurücksetzen der Attribute mit '''set defaults reset''' die Konfiguration speichern und FHEM neu starten.<br />
<br />
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.<br />
<br />
==Synchronisation mit der CCU==<br />
<br />
=== Geräte synchronisieren ===<br />
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.<br />
<br />
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.<br />
<br />
=== Datenpunkte (Readings) synchronisieren ===<br />
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.<br />
<br />
==Autocreate von FHEM-Devices für CCU Geräte==<br />
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.<br />
<br />
{{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}}<br />
<br />
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.<br />
<br />
Beispiel: Für das CCU-Gerät "Heizung-Wohnzimmer" soll ein FHEM-Device angelegt werden:<br />
get d_ccu createDev Heizung-Wohnzimmer<br />
Beispiel: Für alle CCU-Geräte, deren Namen mit "Heizung" beginnt, sollen FHEM-Devices angelegt werden:<br />
get d_ccu create Heizung.* room=Homematic group=Heizung<br />
Beim vorherigen Beispiel wird als Gerätename ein regulärer Ausdruck ("Heizung.*) angegeben. Jedes angelegte Gerät bekommt die Attribute "room" und "group" zugewiesen.<br />
<br />
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.<br />
<br />
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:<br />
get d_ccu createDev FB-Rollladen<br />
erzeugt die HMCCUCHN Devices: FB-Rollladen-Wohnzimmer, FB-Rollladen-Kueche.<br />
<br />
Mit dem Attribut "createDeviceGroup" können solche Einzel-Devices, die alle zu einem CCU-Gerät gehören, automatisch in einer FHEM-Gruppe zusammengefasst werden. Das Attribut legt das Namensschema dieser Gruppe fest.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
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. <br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
<br />
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.<br />
<br />
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:<br />
<pre>attr d_ccu ccuGetVars 60<br />
attr d_ccu ccuGetVars 60:^A</pre><br />
<br />
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.<br />
<br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
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".<br />
<br />
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":<br />
<pre>set d_ccu var text Wetter sonnig</pre><br />
<br />
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:<br />
<br />
* unit = Einheit<br />
* desc = Beschreibung<br />
* min = Kleinster erlaubter Wert bei numerischen Variablen<br />
* max = Größter erlaubter Wert bei numerischen Variablen<br />
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen<br />
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"<br />
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"<br />
<br />
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:<br />
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: HomeMatic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von HomeMatic Scripts===<br />
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.''<br />
<br />
Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]<br />
[[Kategorie:Interfaces]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=36250HMCCU2021-11-23T09:46:23Z<p>Zap: /* Geräte, Kanäle und Datenpunkte */</p>
<hr />
<div>Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. <br />
<br />
{{Hinweis|Dieser Artikel bezieht sich auf die neue HMCCU Version 5.0}}{{Infobox Modul<br />
|ModPurpose=Anbindung HomeMatic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (HomeMatic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von HomeMatic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Der oben beschriebene Aufbau lässt sich am Beispiel einer Steckdose veranschaulichen:<syntaxhighlight><br />
CHN KEQ0965669:0 ST-WR-Waschmaschine:0<br />
0.UNREACH = false {b} [RE]<br />
0.STICKY_UNREACH = true {b} [RWE]<br />
0.CONFIG_PENDING = false {b} [RE]<br />
0.DUTYCYCLE = false {b} [RE]<br />
0.RSSI_DEVICE = 1 {n} [RE]<br />
0.RSSI_PEER = 214 {n} [RE]<br />
0.DEVICE_IN_BOOTLOADER = false {b} [RE]<br />
0.UPDATE_PENDING = false {b} [RE]<br />
0.AES_KEY = 0 {n} [R]<br />
CHN KEQ0965669:1 ST-WR-Waschmaschine:1<br />
1.STATE = true {b} [RWE]<br />
1.ON_TIME = {f} [W]<br />
1.INHIBIT = false {b} [RWE]<br />
1.INSTALL_TEST = {b} [W]<br />
1.WORKING = false {b} [RE]<br />
CHN KEQ0965669:2 ST-WR-Waschmaschine:2<br />
2.ENERGY_COUNTER = 59348.000000 {f} [RE]<br />
2.POWER = 0.120000 {f} [RE]<br />
2.CURRENT = 45.000000 {f} [RE]<br />
2.VOLTAGE = 233.000000 {f} [RE]<br />
2.FREQUENCY = 49.990000 {f} [RE]<br />
2.BOOT = true {b} [RE]<br />
</syntaxhighlight>Das Gerät in diesem Beispiel hat 3 nutzbare Kanäle: <br />
* 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. <br />
* 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 <br />
* Kanal 2 ist ein reiner Statuskanal. Er besitzt keine beschreibbaren Datenpunkte (nur '''R'''ead und '''E'''vent). <br />
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 definieren (enthält automatisch auch Kanal 0). Andernfalls definiert man ein HMCCUDEV Device für das Gerät, das dann alle Kanäle (0-2) enthält. <br />
<br />
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. <br />
<br />
{{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).}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* 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.<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. <br />
<br />
Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden oder alternativ CPAN verwendet werden:<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren<br />
<syntaxhighlight lang="doscon"><br />
cpan install RPC::XML<br />
</syntaxhighlight><br />
Bei der Installation gemäß [[FHEM Installation Windows]] befindet sich cpan man unter <code><FHEM-Hauptverzeichis>\perl\bin</code><br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
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<br />
<br />
===RPC Server konfigurieren und starten===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
== Migration von HMCCU 4.3 ==<br />
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.<br />
<br />
Wichtig: Nach dem Zurücksetzen der Attribute mit '''set defaults reset''' die Konfiguration speichern und FHEM neu starten.<br />
<br />
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.<br />
<br />
==Synchronisation mit der CCU==<br />
<br />
=== Geräte synchronisieren ===<br />
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.<br />
<br />
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.<br />
<br />
=== Datenpunkte (Readings) synchronisieren ===<br />
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.<br />
<br />
==Autocreate von FHEM-Devices für CCU Geräte==<br />
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.<br />
<br />
{{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}}<br />
<br />
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.<br />
<br />
Beispiel: Für das CCU-Gerät "Heizung-Wohnzimmer" soll ein FHEM-Device angelegt werden:<br />
get d_ccu createDev Heizung-Wohnzimmer<br />
Beispiel: Für alle CCU-Geräte, deren Namen mit "Heizung" beginnt, sollen FHEM-Devices angelegt werden:<br />
get d_ccu create Heizung.* room=Homematic group=Heizung<br />
Beim vorherigen Beispiel wird als Gerätename ein regulärer Ausdruck ("Heizung.*) angegeben. Jedes angelegte Gerät bekommt die Attribute "room" und "group" zugewiesen.<br />
<br />
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.<br />
<br />
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:<br />
get d_ccu createDev FB-Rollladen<br />
erzeugt die HMCCUCHN Devices: FB-Rollladen-Wohnzimmer, FB-Rollladen-Kueche.<br />
<br />
Mit dem Attribut "createDeviceGroup" können solche Einzel-Devices, die alle zu einem CCU-Gerät gehören, automatisch in einer FHEM-Gruppe zusammengefasst werden. Das Attribut legt das Namensschema dieser Gruppe fest.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
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. <br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
<br />
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.<br />
<br />
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:<br />
<pre>attr d_ccu ccuGetVars 60<br />
attr d_ccu ccuGetVars 60:^A</pre><br />
<br />
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.<br />
<br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
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".<br />
<br />
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":<br />
<pre>set d_ccu var text Wetter sonnig</pre><br />
<br />
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:<br />
<br />
* unit = Einheit<br />
* desc = Beschreibung<br />
* min = Kleinster erlaubter Wert bei numerischen Variablen<br />
* max = Größter erlaubter Wert bei numerischen Variablen<br />
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen<br />
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"<br />
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"<br />
<br />
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:<br />
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: HomeMatic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von HomeMatic Scripts===<br />
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.''<br />
<br />
Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]<br />
[[Kategorie:Interfaces]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Best_Practice&diff=36152HMCCU Best Practice2021-10-26T11:04:04Z<p>Zap: </p>
<hr />
<div>{{Hinweis|Dieser Artikel ist noch nicht an Version 5.0 angepasst}}<br />
<br />
==I/O Device anlegen==<br />
===I/O Device definieren===<br />
Die Kommunikation zwischen FHEM und einer CCU2 erfolgt über ein Device vom Typ HMCCU. Der folgende Befehl legt ein solches I/O Device an. Dabei wird die IP-Adresse der CCU2 als Parameter angegeben:<br />
<pre>define d_ccu HMCCU 192.168.1.100</pre><br />
<br />
===Attribute setzen===<br />
Zunächst wird der RPC-Server konfiguriert. Im folgenden Beispiel werden BidCos, HM-IP, CUxD und Gerätegruppen (VirtualDevices) berücksichtigt. Es dürfen nur die Schnittstellen angegeben werden, die in der CCU2 auch verwendet werden.<br />
<pre><br />
#<br />
# Schnittstellen<br />
attr d_ccu rpcinterfaces BidCos-RF,CUxD,HmIP-RF,VirtualDevices<br />
#<br />
# Externen RPC Server verwenden<br />
attr d_ccu ccuflags procrpc<br />
#<br />
# RPC-Server nach dem Start von FHEM automatisch starten<br />
attr d_ccu rpcserver on<br />
#<br />
# Status anzeigen<br />
attr d_ccu stateFormat rpcstate/state<br />
#<br />
# Buttons für das Starten und Stoppen des RPC-Servers anzeigen<br />
attr d_ccu cmdIcon on:general_an off:general_aus<br />
attr d_ccu eventMap /rpcserver on:on/rpcserver off:off/<br />
</pre><br />
<br />
Mit dem Befehl set d_ccu defaults werden weitere Attribute gesetzt, die das Handling von Readings in den später definierten Devices vom Typ HMCCUCHN und HMCCUDEV beeinflussen bzw. vereinfachen. Diese Attribute können natürlich auch einzeln gesetzt werden:<br />
<pre><br />
#<br />
# Readings LOWBAT, LOW_BAT und UNREACH immer berücksichtigen<br />
attr d_ccu ccudef-readingfilter ^(LOW_?BAT|UNREACH)$<br />
#<br />
# Readings LOWBAT und LOW_BAT in battery umbenennen, Reading UNREACH in activity umbenennen<br />
attr d_ccu ccudef-readingname ^(.+\.)?LOW_?BAT$:battery;;^(.+\.)?UNREACH$:activity<br />
#<br />
# Werte von Readings durch sprechende Ausdrücke ersetzen<br />
attr d_ccu ccudef-substitute AES_KEY!(0|false):off,(1|true):on;;LOWBAT,LOW_BAT!(0|false):ok,(1|true):low;;UNREACH!(0|false):alive,(1|true):dead;;MOTION!(0|false):noMotion,(1|true):motion;;DIRECTION!0:stop,1:up,2:down,3:undefined;;WORKING!0:false,1:true;;INHIBIT!(0|false):unlocked,(1|true):locked<br />
</pre><br />
<br />
Nun werden noch Aggregationen definiert. Mit dieser Funktion können bestimmte Stati von Homematic Devices im I/O Device als Reading dargestellt werden (z.B. Liste der offenen Fenster, Geräte mit leerer Batterie). Um die Definition der Aggregationen bzw. der Filter einfach zu halten, sollte man sich ein Namensschema überlegen. Die folgenden Aggregationen gehen davon aus, dass alle Homematic Devices in FHEM mit "HM-" beginnen. Danach folgt die Funktion des Gerätes, z.B. KL für Klima und TF für TürFenster. Bei anderer Namensgebung sind die Filterangaben entsprechend anzupassen. Alternativ kann auch der Gerätetyp oder die Gruppe als Filter verwendet werden (s.a. Command Reference zu HMCCU). Das Attribut ''ccuaggregate'' unterstützt mehrzeilige Angaben. Im folgenden Beispiel ist nur der Attributwert angegeben. Eingabe am besten über Auswahl des Attributs ''ccuaggregate'' in der FHEM Oberfläche. Die Kommentarzeilen beginnend mit # weglassen.<br />
<pre><br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und bei denen das Reading battery den Wert low hat<br />
name:battery,filter:name=^HM_.*,read:battery,if:any=low,else:ok,prefix:battery_,coll:comment!Batterien OK;<br />
#<br />
# Anzeige aller Geräte vom Typ HM-CC-RT-DN oder HM-TC-IT-WM-W-EU, deren Batteriespannung kleiner gleich 2.2 Volt ist<br />
name:voltage,filter:type=(HM-CC-RT-DN|HM-TC-IT-WM-W-EU),read:BATTERY_STATE,if:le=2.2,else:0,prefix:voltage_,coll:comment!Batteriespannung OK;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt und bei denen das Reading state den Wert open hat<br />
name:lock,filter:name=^HM_TF.*,read:state,if:any=open,else:closed,prefix:lock_,coll:comment!Alle Fenster/Türen geschlossen;<br />
#<br />
# Anzeige aller Geräte der Gruppe Dachfenster, bei denen das Reading state den Wert open hat<br />
name:lockroof,filter:group=Dachfenster,read:state,if:any=open,else:closed,prefix:lockroof_,coll:comment!Alle Dachfenster geschlossen;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt aber nicht mit Haustuer endet und bei denen das Reading state den Wert open hat<br />
name:lockwin,filter:name=^HM_TF.*!Haustuer$,read:state,if:any=open,else:closed,prefix:lockwin_,coll:comment!Alle Fenster/Türen geschlossen;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_KL beginnt und bei denen das Reading HUMIDITY größer gleich 60 ist<br />
name:hummax,filter:name=^HM_KL.*,read:HUMIDITY,if:ge=60,else:0,prefix:hummax_,coll:alias!Luftfeuchte OK;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und die nicht erreichbar sind<br />
name:unreach,filter:name=^HM_.*,read:activity,if:any=dead,else:alive,prefix:unreach_,coll:comment!Alle Devices erreichbar<br />
</pre><br />
<br />
Mit den folgenden Attributen werden die Aggregations-Readings im I/O Device aktualisiert:<br />
<pre><br />
#<br />
# Readings schreiben<br />
attr d_ccu ccureadings 1<br />
attr d_ccu event-on-change-reading .*<br />
#<br />
# Werte auf eine Nachkommastelle abschneiden<br />
attr d_ccu stripnumber 1<br />
</pre><br />
<br />
==Neue Geräte anlernen==<br />
Um ein neues Gerät an die CCU anzulernen und in FHEM zu nutzen, kann man wie folgt vorgehen:<br />
<br />
# Gerät in CCU2 anlernen<br />
# Im WebUI der CCU2 den Menübefehl ''Einstellungen → Geräte'' aufrufen. Das neu angelernte Gerät in der Liste suchen und nacheinander das Gerät selbst sowie die einzelnen Kanäle nach eigenen Wünschen umbenennen. Dabei sind folgende Regeln zu beachten:<br />
#* CCU2 weit Keine Namen doppelt vergeben, z.B. darf ein Raum nicht den gleichen Namen haben wie ein Gerät.<br />
#* Keine Umlaute verwenden.<br />
#* Wenn möglich keine Leerzeichen verwenden (funktioniert zwar, erschwert aber das Handling in FHEM).<br />
# In FHEM für das I/O Device den Befehl '''get devicelist''' ausführen, um das neue Gerät in FHEM bekannt zu machen.<br />
# Für das I/O Device den Befehl get deviceinfo CCU2-Devicename ausführen. Die Ausgabe zeigt die für das Gerät verfügbaren Kanäle und Datenpunkte sowie die möglichen Operationen (R=Read, W=Write, E=Event) an, die ausgeführt werden können. Anhand dieser Informationen kann man entscheiden, ob man im nächsten Schritt besser HMCCUCHN oder HMCCUDEV für die weiteren Definitionen verwendet. Falls sich aus den Namen der Datenpunkte nicht ihr Verwendungszweck ergibt, findet man in der [http://www.eq-3.de/Downloads/eq3/download%20bereich/hm_web_ui_doku/hm_devices_Endkunden.pdf EQ3-Doku] eine detaillierte Beschreibung der Datenpunkte aller Geräte.<br />
# Ein FHEM Device für das neue Gerät und/oder seine Kanäle definieren:<br />
#* Das Modul HMCCUCHN verwenden, wenn lediglich ein Kanal des Geräts in FHEM eingebunden werden soll oder die Kanäle separat verwendet werden sollen (z.B. bei einem 4-fach Aktor).<br />
#* Das Modul HMCCUDEV verwenden, wenn das komplette Gerät mit allen Kanälen in FHEM eingebunden werden soll oder bei Sonderfällen wie Rauchmeldergruppen oder virtuelle Gerätegruppen.<br />
# Für das neue Device in FHEM den Befehl set defaults ausführen, um einige Attribute zu setzen. Hinweis: Default-Attribute sind nicht für alle Gerätetypen verfügbar. Grundsätzlich sollten folgende Attribute gesetzt werden:<br />
#* ccureadingfilter - Einschränkung auf die tatsächlich benötigten Datenpunkte bzw. Readings<br />
#* ccureadingformat - Bessere Lesbarkeit der Readings durch das Format datapoint<br />
#* event-on-change-reading bzw. event-on-update-reading - Wenn ein Schalter oder Taster über Datenpunkte wie PRESSED_xxx verfügt, sollte event-on-update-reading auf ".*" gesetzt werden. Bei allen anderen Geräten event-on-change-reading.<br />
#* statedatapoint - Legt den Kanal und den Datenpunkt fest, über den ein Gerät oder ein Kanal geschaltet wird bzw. dessen Wert in STATE des FHEM Devices übernommen wird. Bei HMCCUCHN Devices wird nur der Datenpunkt angegeben.<br />
#* statevals - Legt sprechende Namen für Schaltzustände fest. Die Angaben hier stehen dann als Set-Befehle zur Verfügung.<br />
#* substitute - Ersetzt Datenpunktwerte durch Texte bevor sie in Readings gespeichert werden<br />
<br />
==Readingnames anpassen==<br />
===Format von Readingnames===<br />
In HMCCUDEV und HMCCUCHN werden Readingnames aus den Kanalnamen oder den Kanaladressen sowie den Datenpunktnamen gebildet. Das Format der Readingnames kann über das Attribut ''ccureadingformat'' eingestellt werden. Die Vorgabe ist 'datapoint' Die folgende Tabelle enthält eine Übersicht der Formate:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Datenpunktname oder -adresse !! ccureadingformat !! Readingname<br />
|-<br />
| BidCos-RF.1234567:1.STATE || datapoint || 1.STATE<br />
|- <br />
| BidCos-RF.1234567:1.STATE || datapointlc || 1.state<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || name || MeinKanal.1.LEVEL<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || address || 1234567.1.LEVEL<br />
|}<br />
<br />
===Readingnames ändern oder ergänzen===<br />
Mit dem Attribut ''ccureadingname'' können einzelne Readings umbenannt oder neue Readings als Kopie vorhandener Readings hinzugefügt werden. Die Syntax des Attributs sieht wie folgt aus:<br />
<br />
ccureadingname Ausdruck:[+]NewReading[;...]<br />
<br />
Der Parameter ''Ausdruck'' gibt den Teil eines Readingnames an, der ersetzt werden soll. Mit ''NewReading'' wird der Name des zusätzlichen Readings (führendes '+') oder der Ersetzungstext für den vorhandenen Readingname festgelegt. Beispiele:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Readingname alt !! ccureadingname !! Readingname(s) neu<br />
|-<br />
| 1.LEVEL || LEVEL:pct || 1.pct<br />
|- <br />
| 1.LEVEL || [0-9]{1,2}\.LEVEL:pct || pct<br />
|-<br />
| 1.LEVEL || 1.LEVEL:+pct;1.LEVEL:level || pct, level<br />
|-<br />
| 1.LEVEL || 1.LEVEL:pct;1.LEVEL:level || pct<br />
|}<br />
<br />
Wichtig! Die Regeln werden von links nach rechts abgearbeitet. Daher greift die 2. Regel in der letzten Zeile nicht mehr (1.LEVEL wurde zuvor durch pct ersetzt).<br />
<br />
=== Readingnames zusammenfassen===<br />
Mit dem Attribut ''ccureadingname'' können auch mehrere Readings zu einem neuen Reading zusammengefasst werden. Beispiel: Ein Taster liefert je nach Dauer des Tastendrucks im Kanal 1 ein Event PRESS_SHORT oder PRESS_LONG. Normalerweise würden dabei auch zwei Readings "1.PRESS_SHORT" und "1.PRESS_LONG" entstehen. Diese beiden Readings können mit folgendem Befehl in einem Reading PRESSED zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^1.PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
Wenn ein Taster über mehrere Kanäle (hier vier) verfügt, können auch diese zu einem einzigen Reading zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^[1-4].PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
==Readingwerte manipulieren==<br />
===Readingwerte ersetzen===<br />
Mit dem Attribut ''substitute'' können Werte von Readings durch neue Werte bzw. Zeichenketten ersetzt werden. Die Veränderungen können sich auf bestimmte Datenpunkte oder alle Readings eines Devices beziehen. Die zu ersetzenden Werte werden dabei entweder durch reguläre Ausdrücke oder als Nummernbereiche angegeben.<br />
<br />
Im folgenden Beispiel werden die Werte 1 oder true in allen Readings durch "yes" ersetzt, die Werte 0 oder false durch "no":<br />
<br />
<pre>attr mydev substitute (1|true):yes,(0|false):no</pre><br />
<br />
Wenn sich mehrere Ersetzungsregeln auf den gleichen Datenpunkt beziehen oder wie im Beispiel oben für alle Datenpunkte gelten, werden sie einfach durch ein Komma getrennt aneinander gehängt. Eine Ersetzungsregel kann sich auch auf einen bestimmten Datenpunkt beziehen. Im folgenden Beispiel eines Fensterkontakts sollen die Werte des Datenpunktes STATE durch "open" bzw. "closed" ersetzt werden. Der Name des Datenpunktes wird in diesem Fall einfach durch ein Ausrufezeichen getrennt der Regel vorangestellt: <br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Sollte ein Geräte in mehreren Kanälen identische Datenpunkte enthalten, kann dem Datenpunktnamen noch eine Kanalnummer mit einem Punkt vorangestellt werden:<br />
<br />
<pre>attr mydev substitute 1.STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Eine Ersetzungsregel kann sich auch auf mehrere Datenpunkte beziehen (im Beispiel ERROR und LOWBAT), die durch Komma getrennt vor dem '!' aufgelistet werden:<br />
<br />
<pre>attr mydev substitute ERROR,LOWBAT!(1|true):yes,(0|false):no</pre><br />
<br />
Wenn mehrere Ersetzungsregeln definiert werden sollen, werden sie durch ein Semikolon getrennt. Im folgenden Beispiel sollen die Werte der Datenpunkte STATE und LOWBAT unterschiedlich interpretiert werden:<br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed;;LOWBAT!(1|true):low,(0|false):ok</pre><br />
<br />
Bei Datenpunkten mit numerischen Werten wie z.B. dem Level eines Rollladenaktors kann es sinnvoll sein, Werte oder Wertebereiche zu ersetzen. Im folgenden Beispiel kann der Datenpunkt LEVEL Werte von 0-100 annehmen. Der Wert 0 soll als "closed" und der Wert 100 als "open" dargestellt werden. Alle anderen Werte als "partial":<br />
<br />
<pre>attr mydev substitute LEVEL!#0-0:closed,#1-99:partial,#100-100:open</pre><br />
<br />
Zu ersetzende Nummernbereiche beginnen also immer mit einem #. Es müssen immer Bereiche angegeben werden.<br />
<br />
In Ersetzungsregeln können auch Variablen verwendet werden. Eine Variable wird dabei im Format ${Datenpunkt} angegeben. Ein Sonderfall ist die Variable ${value}, die durch den Originalwert ersetzt wird. Beispiel: An den Wert der Luftfeuchte soll der Text "Prozent" angehängt werden:<br />
<br />
<pre>attr mydev substitute HUMIDITY!.+:${value}%</pre><br />
<br />
Im zweiten Beispiel soll der Temperaturwert durch eine Ausgabe im Format T=Temperatur°, H=Luftfeuchte% ersetzt werden:<br />
<br />
<pre> attr mydev substitute TEMPERATURE!.+:T=${value}° H={1.HUMIDITY}%</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=36151HMCCU2021-10-26T11:02:25Z<p>Zap: </p>
<hr />
<div>Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. <br />
<br />
{{Hinweis|Dieser Artikel bezieht sich auf die neue HMCCU Version 5.0}}{{Infobox Modul<br />
|ModPurpose=Anbindung HomeMatic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (HomeMatic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von HomeMatic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen. 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. <br />
<br />
Der Statuskanal 0 ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar!<br />
<br />
{{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).}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* 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.<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. <br />
<br />
Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden oder alternativ CPAN verwendet werden:<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren<br />
<syntaxhighlight lang="doscon"><br />
cpan install RPC::XML<br />
</syntaxhighlight><br />
Bei der Installation gemäß [[FHEM Installation Windows]] befindet sich cpan man unter <code><FHEM-Hauptverzeichis>\perl\bin</code><br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
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<br />
<br />
===RPC Server konfigurieren und starten===<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
== Migration von HMCCU 4.3 ==<br />
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.<br />
<br />
Wichtig: Nach dem Zurücksetzen der Attribute mit '''set defaults reset''' die Konfiguration speichern und FHEM neu starten.<br />
<br />
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.<br />
<br />
==Synchronisation mit der CCU==<br />
<br />
=== Geräte synchronisieren ===<br />
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.<br />
<br />
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.<br />
<br />
=== Datenpunkte (Readings) synchronisieren ===<br />
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.<br />
<br />
==Autocreate von FHEM-Devices für CCU Geräte==<br />
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.<br />
<br />
{{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}}<br />
<br />
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.<br />
<br />
Beispiel: Für das CCU-Gerät "Heizung-Wohnzimmer" soll ein FHEM-Device angelegt werden:<br />
get d_ccu createDev Heizung-Wohnzimmer<br />
Beispiel: Für alle CCU-Geräte, deren Namen mit "Heizung" beginnt, sollen FHEM-Devices angelegt werden:<br />
get d_ccu create Heizung.* room=Homematic group=Heizung<br />
Beim vorherigen Beispiel wird als Gerätename ein regulärer Ausdruck ("Heizung.*) angegeben. Jedes angelegte Gerät bekommt die Attribute "room" und "group" zugewiesen.<br />
<br />
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.<br />
<br />
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:<br />
get d_ccu createDev FB-Rollladen<br />
erzeugt die HMCCUCHN Devices: FB-Rollladen-Wohnzimmer, FB-Rollladen-Kueche.<br />
<br />
Mit dem Attribut "createDeviceGroup" können solche Einzel-Devices, die alle zu einem CCU-Gerät gehören, automatisch in einer FHEM-Gruppe zusammengefasst werden. Das Attribut legt das Namensschema dieser Gruppe fest.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
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. <br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
<br />
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.<br />
<br />
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:<br />
<pre>attr d_ccu ccuGetVars 60<br />
attr d_ccu ccuGetVars 60:^A</pre><br />
<br />
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.<br />
<br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
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".<br />
<br />
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":<br />
<pre>set d_ccu var text Wetter sonnig</pre><br />
<br />
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:<br />
<br />
* unit = Einheit<br />
* desc = Beschreibung<br />
* min = Kleinster erlaubter Wert bei numerischen Variablen<br />
* max = Größter erlaubter Wert bei numerischen Variablen<br />
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen<br />
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"<br />
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"<br />
<br />
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:<br />
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: HomeMatic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von HomeMatic Scripts===<br />
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.''<br />
<br />
Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]<br />
[[Kategorie:Interfaces]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=36144HMCCU2021-10-20T17:10:14Z<p>Zap: Beschreibung HMCCU 5.0</p>
<hr />
<div>Das Modul HMCCU ermöglicht zusammen mit weiteren Modulen eine Integration der [[HomeMatic]] CCU Zentrale sowie der dort angelernten Geräte in FHEM. <br />
<br />
{{Hinweis|Dieser Artikel bezieht sich auf die neue HMCCU Version 5.0}}{{Infobox Modul<br />
|ModPurpose=Anbindung HomeMatic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (HomeMatic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von HomeMatic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. <br />
<br />
Unter debian/raspbian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Unter Windows (Strawberry Perl) kann man das Paket RPC::XML mit cpan installieren<br />
<syntaxhighlight lang="doscon"><br />
cpan install RPC::XML<br />
</syntaxhighlight><br />
Bei der Installation gemäß [[FHEM Installation Windows]] befindet sich cpan man unter <code><FHEM-Hauptverzeichis>\perl\bin</code><br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPCPROC bereitgestellte externe RPC-Server verwendet keine temporären Dateien. Der interne RPC-Server wird ab Version 4.4 nicht mehr unterstützt.<br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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. 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:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
Der Start von FHEM wird dadurch nicht verzögert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden, greift dann also auch, wenn die CCU beim Start von FHEM erreichbar ist<br />
<br />
===RPC Server konfigurieren===<br />
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.<br />
<br />
'''Externer RPC-Server (HMCCURPCPROC)'''<br />
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.<br />
<br />
'''RPC-Server starten'''<br />
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.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
== Migration von HMCCU 4.3 ==<br />
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. Es wird jedoch dringend empfohlen, die Geräte jeweils mit dem Befehl '''set defaults reset''' zurückzusetzen. HMCCU 5.0 erkennt nun sehr viele Geräte und die notwendigen Attribute automatisch anhand der Kanalrollen. Dadurch sind nur noch sehr wenige Attribute erforderlich, was die Gerätedefinition deutlich vereinfacht. Beim Zurücksetzen der Defaults werden überflüssige Attribute gelöscht. Speziell das in 4.3 häufig verwendete Attribut "eventMap" kann bei der Version 5.0 zu Konflikten mit den eingebauten Befehlen führen.<br />
<br />
Wichtig: Nach dem Zurücksetzen der Attribute mit '''set defaults reset''' die Konfiguration speichern und FHEM neu starten.<br />
<br />
==Synchronisation mit der CCU==<br />
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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device (z.B. beim Start von FHEM) wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
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.<br />
<br />
==Autocreate von FHEM-Devices für CCU Geräte==<br />
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 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.<br />
<br />
{{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}}<br />
<br />
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.<br />
<br />
Beispiel: Für das CCU-Gerät "Heizung-Wohnzimmer" soll ein FHEM-Device angelegt werden:<br />
get d_ccu createDev Heizung-Wohnzimmer<br />
Beispiel: Für alle CCU-Geräte, deren Namen mit "Heizung" beginnt, sollen FHEM-Devices angelegt werden:<br />
get d_ccu create Heizung.* room=Homematic group=Heizung<br />
Beim vorherigen Beispiel wird als Gerätename ein regulärer Ausdruck ("Heizung.*) angegeben. Jedes angelegte Gerät bekommt die Attribute room und group zugewiesen.<br />
<br />
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.<br />
<br />
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:<br />
get d_ccu createDev FB-Rollladen<br />
erzeugt die HMCCUCHN Devices: FB-Rollladen-Wohnzimmer, FB-Rollladen-Kueche.<br />
<br />
Mit dem Attribut "createDeviceGroup" können solche Einzel-Devices, die alle zu einem CCU-Gerät gehören, automatisch in einer FHEM-Gruppe zusammengefasst werden. Das Attribut legt das Namensschema dieser Gruppe fest.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
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. <br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
<br />
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.<br />
<br />
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:<br />
<pre>attr d_ccu ccuGetVars 60<br />
attr d_ccu ccuGetVars 60:^A</pre><br />
<br />
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.<br />
<br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
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".<br />
<br />
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":<br />
<pre>set d_ccu var text Wetter sonnig</pre><br />
<br />
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:<br />
<br />
* unit = Einheit<br />
* desc = Beschreibung<br />
* min = Kleinster erlaubter Wert bei numerischen Variablen<br />
* max = Größter erlaubter Wert bei numerischen Variablen<br />
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen<br />
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"<br />
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"<br />
<br />
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:<br />
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: HomeMatic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von HomeMatic Scripts===<br />
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.''<br />
<br />
Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]<br />
[[Kategorie:Interfaces]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=32106HMCCU2019-12-23T17:22:41Z<p>Zap: /* Definition I/O Device */</p>
<hr />
<div>{{Infobox Modul<br />
|ModPurpose=Anbindung HomeMatic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ({{Link2FU|10980|Forum}} / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (HomeMatic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von HomeMatic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für HomeMatic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von HomeMatic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte HomeMatic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
Zusätzlich muss in der Systemsteuerung unter "Sicherheit" die Option "Authentifizierung" deaktiviert werden, da HMCCU den Zugriff per Username/Password noch nicht unterstützt.<br />
<br />
===Installation===<br />
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<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPCPROC bereitgestellte externe RPC-Server verwendet keine temporären Dateien. Der interne RPC-Server wird ab Version 4.4 nicht mehr unterstützt.<br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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. 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:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
Der Start von FHEM wird dadurch nicht verzögert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden, greift dann also auch, wenn die CCU beim Start von FHEM erreichbar ist<br />
<br />
===RPC Server konfigurieren===<br />
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. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* HVL<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet. Im Internal "ccuinterfaces" werden nach der Definition des I/O Device alle verfügbaren Schnittstellen angezeigt.<br />
<br />
Danach wird durch Setzen des Attributs ''ccuflags'' auf den Wert procrpc der externe RPC-Server aktiviert. Die Verwendung des internen RPC-Servers ist zwar noch möglich, wird jedoch nicht mehr offiziell unterstützt.<br />
<br />
'''Externer RPC-Server (HMCCURPCPROC)'''<br />
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.<br />
<br />
'''RPC-Server starten'''<br />
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. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Attributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel 1: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
Beispiel 2: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM" oder "Hm" (HmIP-Geräte) beginnt. Alle neuen FHEM Devices haben den Namen wie in der CCU und können dann mit dem Attribut "alias" verständlicher benannt werden. Sofern vorhanden, werden default Attribute gesetzt. Die Konfiguration wird gespeichert. Der Room "CCU_HM" ist angelehnt an "CUL_HM".<br />
<pre>get d_ccu devicelist create ^H[M|m].* t=dev f=%n defattr save room=CCU_HM</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten HomeMatic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attributen eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle HomeMatic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
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. <br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
<br />
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.<br />
<br />
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:<br />
<pre>attr d_ccu ccuGetVars 60<br />
attr d_ccu ccuGetVars 60 ^A</pre><br />
<br />
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.<br />
<br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
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".<br />
<br />
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":<br />
<pre>set d_ccu var text Wetter sonnig</pre><br />
<br />
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:<br />
<br />
* unit = Einheit<br />
* desc = Beschreibung<br />
* min = Kleinster erlaubter Wert bei numerischen Variablen<br />
* max = Größter erlaubter Wert bei numerischen Variablen<br />
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen<br />
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"<br />
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"<br />
<br />
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:<br />
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregationsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: HomeMatic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller HomeMatic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von HomeMatic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende HomeMatic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=29283HMCCU2019-01-28T15:36:38Z<p>Zap: /* RPC Server konfigurieren */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (Homematic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von Homematic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
Zusätzlich muss in der Systemsteuerung unter "Sicherheit" die Option "Authentifizierung" deaktiviert werden, da HMCCU den Zugriff per Username/Password noch nicht unterstützt.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPCPROC bereitgestellte externe RPC-Server verwendet keine temporären Dateien. Der interne RPC-Server wird ab Version 4.4 nicht mehr unterstützt.<br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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. Durch ''ccudelay'' wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die Vorgabe sind 180 Sekunden. Je nach Installation kann auch ein höherer Wert notwendig sein:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
Durch diese Angabe erfolgt eine verzögerte Initialisierung des I/O Device sowie der FHEM Homematic Devices, wenn die CCU beim Start von FHEM nicht erreichbar ist. Der Start von FHEM wird dadurch nicht verzögert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden.<br />
<br />
===RPC Server konfigurieren===<br />
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. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* HVL<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet. Im Internal "ccuinterfaces" werden nach der Definition des I/O Device alle verfügbaren Schnittstellen angezeigt.<br />
<br />
Danach wird durch setzen des Attributs ''ccuflags'' auf den Wert procrpc der externe RPC-Server aktiviert. Die Verwendung des internen RPC-Servers ist zwar noch möglich, wird jedoch nicht mehr offiziell unterstützt.<br />
<br />
'''Externer RPC-Server (HMCCURPCPROC)'''<br />
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.<br />
<br />
'''RPC-Server starten'''<br />
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. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
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. <br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
<br />
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.<br />
<br />
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:<br />
<pre>attr d_ccu ccuGetVars 60<br />
attr d_ccu ccuGetVars 60 ^A</pre><br />
<br />
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.<br />
<br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
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".<br />
<br />
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":<br />
<pre>set d_ccu var text Wetter sonnig</pre><br />
<br />
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:<br />
<br />
* unit = Einheit<br />
* desc = Beschreibung<br />
* min = Kleinster erlaubter Wert bei numerischen Variablen<br />
* max = Größter erlaubter Wert bei numerischen Variablen<br />
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen<br />
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"<br />
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"<br />
<br />
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:<br />
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=29281HMCCU2019-01-28T15:34:21Z<p>Zap: /* Lesen und Ändern von CCU Systemvariablen */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (Homematic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von Homematic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
Zusätzlich muss in der Systemsteuerung unter "Sicherheit" die Option "Authentifizierung" deaktiviert werden, da HMCCU den Zugriff per Username/Password noch nicht unterstützt.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPCPROC bereitgestellte externe RPC-Server verwendet keine temporären Dateien. Der interne RPC-Server wird ab Version 4.4 nicht mehr unterstützt.<br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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. Durch ''ccudelay'' wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die Vorgabe sind 180 Sekunden. Je nach Installation kann auch ein höherer Wert notwendig sein:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
Durch diese Angabe erfolgt eine verzögerte Initialisierung des I/O Device sowie der FHEM Homematic Devices, wenn die CCU beim Start von FHEM nicht erreichbar ist. Der Start von FHEM wird dadurch nicht verzögert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden.<br />
<br />
===RPC Server konfigurieren===<br />
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. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* HVL<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
Danach wird durch setzen des Attributs ''ccuflags'' auf den Wert procrpc der externe RPC-Server aktiviert. Die Verwendung des internen RPC-Servers ist zwar noch möglich, wird jedoch nicht mehr offiziell unterstützt.<br />
<br />
'''Externer RPC-Server (HMCCURPCPROC)'''<br />
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.<br />
<br />
'''RPC-Server starten'''<br />
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. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
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. <br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
<br />
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.<br />
<br />
Beispiel: Lesen aller Systemvariablen alle 60 Sekunden. Im zweiten Befehl werden nur Variablen gelesen, die mit "A" beginnen:<br />
<pre>attr d_ccu ccuGetVars 60<br />
attr d_ccu ccuGetVars 60 ^A</pre><br />
<br />
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.<br />
<br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
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".<br />
<br />
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":<br />
<pre>set d_ccu var text Wetter sonnig</pre><br />
<br />
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:<br />
<br />
* unit = Einheit<br />
* desc = Beschreibung<br />
* min = Kleinster erlaubter Wert bei numerischen Variablen<br />
* max = Größter erlaubter Wert bei numerischen Variablen<br />
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen<br />
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"<br />
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"<br />
<br />
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:<br />
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=29229HMCCU2019-01-25T17:31:38Z<p>Zap: /* Lesen und Ändern von CCU Systemvariablen */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (Homematic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von Homematic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
Zusätzlich muss in der Systemsteuerung unter "Sicherheit" die Option "Authentifizierung" deaktiviert werden, da HMCCU den Zugriff per Username/Password noch nicht unterstützt.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPCPROC bereitgestellte externe RPC-Server verwendet keine temporären Dateien. Der interne RPC-Server wird ab Version 4.4 nicht mehr unterstützt.<br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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. Durch ''ccudelay'' wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die Vorgabe sind 180 Sekunden. Je nach Installation kann auch ein höherer Wert notwendig sein:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
Durch diese Angabe erfolgt eine verzögerte Initialisierung des I/O Device sowie der FHEM Homematic Devices, wenn die CCU beim Start von FHEM nicht erreichbar ist. Der Start von FHEM wird dadurch nicht verzögert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden.<br />
<br />
===RPC Server konfigurieren===<br />
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. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* HVL<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
Danach wird durch setzen des Attributs ''ccuflags'' auf den Wert procrpc der externe RPC-Server aktiviert. Die Verwendung des internen RPC-Servers ist zwar noch möglich, wird jedoch nicht mehr offiziell unterstützt.<br />
<br />
'''Externer RPC-Server (HMCCURPCPROC)'''<br />
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.<br />
<br />
'''RPC-Server starten'''<br />
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. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
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. <br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
<br />
Wenn eine Systemvariable bereits in der CCU existiert, kann ihr Wert mit dem Befehl '''set var''' geändert werden.<br />
<br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
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".<br />
<br />
Beispiel: Anlegen einer Textvariablen mit dem Namen "Wetter":<br />
<pre>set d_ccu var text Wetter sonnig</pre><br />
<br />
Optional können noch Attribute für eine neue Systemvariable gesetzt werden. Folgende Attribute sind erlaubt:<br />
<br />
* unit = Einheit<br />
* desc = Beschreibung<br />
* min = Kleinster erlaubter Wert bei numerischen Variablen<br />
* max = Größter erlaubter Wert bei numerischen Variablen<br />
* list = Durch Komma getrennte Liste mit zulässigen Werten bei Listen-Variablen<br />
* valtrue = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist wahr"<br />
* valfalse = Angezeigter Wert bei Variablen vom Typ bool, Default = "ist falsch"<br />
<br />
Beispiel: Anlegen einer numerischen Variablen für Temperaturwerte:<br />
<pre>set d_ccu var number Temperatur 20.5 unit=Grad desc=Aussentemperatur min=-10.0 max=40.0</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Best_Practice&diff=29228HMCCU Best Practice2019-01-25T16:45:30Z<p>Zap: /* Attribute setzen */</p>
<hr />
<div>==I/O Device anlegen==<br />
===I/O Device definieren===<br />
Die Kommunikation zwischen FHEM und einer CCU2 erfolgt über ein Device vom Typ HMCCU. Der folgende Befehl legt ein solches I/O Device an. Dabei wird die IP-Adresse der CCU2 als Parameter angegeben:<br />
<pre>define d_ccu HMCCU 192.168.1.100</pre><br />
<br />
===Attribute setzen===<br />
Zunächst wird der RPC-Server konfiguriert. Im folgenden Beispiel werden BidCos, HM-IP, CUxD und Gerätegruppen (VirtualDevices) berücksichtigt. Es dürfen nur die Schnittstellen angegeben werden, die in der CCU2 auch verwendet werden.<br />
<pre><br />
#<br />
# Schnittstellen<br />
attr d_ccu rpcinterfaces BidCos-RF,CUxD,HmIP-RF,VirtualDevices<br />
#<br />
# Externen RPC Server verwenden<br />
attr d_ccu ccuflags procrpc<br />
#<br />
# RPC-Server nach dem Start von FHEM automatisch starten<br />
attr d_ccu rpcserver on<br />
#<br />
# Status anzeigen<br />
attr d_ccu stateFormat rpcstate/state<br />
#<br />
# Buttons für das Starten und Stoppen des RPC-Servers anzeigen<br />
attr d_ccu cmdIcon on:general_an off:general_aus<br />
attr d_ccu eventMap /rpcserver on:on/rpcserver off:off/<br />
</pre><br />
<br />
Mit dem Befehl set d_ccu defaults werden weitere Attribute gesetzt, die das Handling von Readings in den später definierten Devices vom Typ HMCCUCHN und HMCCUDEV beeinflussen bzw. vereinfachen. Diese Attribute können natürlich auch einzeln gesetzt werden:<br />
<pre><br />
#<br />
# Readings LOWBAT, LOW_BAT und UNREACH immer berücksichtigen<br />
attr d_ccu ccudef-readingfilter ^(LOW_?BAT|UNREACH)$<br />
#<br />
# Readings LOWBAT und LOW_BAT in battery umbenennen, Reading UNREACH in activity umbenennen<br />
attr d_ccu ccudef-readingname ^(.+\.)?LOW_?BAT$:battery;^(.+\.)?UNREACH$:activity<br />
#<br />
# Werte von Readings durch sprechende Ausdrücke ersetzen<br />
attr d_ccu ccudef-substitute AES_KEY!(0|false):off,(1|true):on;LOWBAT,LOW_BAT!(0|false):ok,(1|true):low;UNREACH!(0|false):alive,(1|true):dead;MOTION!(0|false):noMotion,(1|true):motion;DIRECTION!0:stop,1:up,2:down,3:undefined;WORKING!0:false,1:true;INHIBIT!(0|false):unlocked,(1|true):locked<br />
</pre><br />
<br />
Nun werden noch Aggregationen definiert. Mit dieser Funktion können bestimmte Stati von Homematic Devices im I/O Device als Reading dargestellt werden (z.B. Liste der offenen Fenster, Geräte mit leerer Batterie). Um die Definition der Aggregationen bzw. der Filter einfach zu halten, sollte man sich ein Namensschema überlegen. Die folgenden Aggregationen gehen davon aus, dass alle Homematic Devices in FHEM mit "HM-" beginnen. Danach folgt die Funktion des Gerätes, z.B. KL für Klima und TF für TürFenster. Bei anderer Namensgebung sind die Filterangaben entsprechend anzupassen. Alternativ kann auch der Gerätetyp oder die Gruppe als Filter verwendet werden (s.a. Command Reference zu HMCCU). Das Attribut ''ccuaggregate'' unterstützt mehrzeilige Angaben. Im folgenden Beispiel ist nur der Attributwert angegeben. Eingabe am besten über Auswahl des Attributs ''ccuaggregate'' in der FHEM Oberfläche. Die Kommentarzeilen beginnend mit # weglassen.<br />
<pre><br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und bei denen das Reading battery den Wert low hat<br />
name:battery,filter:name=^HM_.*,read:battery,if:any=low,else:ok,prefix:battery_,coll:comment!Batterien OK;<br />
#<br />
# Anzeige aller Geräte vom Typ HM-CC-RT-DN oder HM-TC-IT-WM-W-EU, deren Batteriespannung kleiner gleich 2.2 Volt ist<br />
name:voltage,filter:type=(HM-CC-RT-DN|HM-TC-IT-WM-W-EU),read:BATTERY_STATE,if:le=2.2,else:0,prefix:voltage_,coll:comment!Batteriespannung OK;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt und bei denen das Reading state den Wert open hat<br />
name:lock,filter:name=^HM_TF.*,read:state,if:any=open,else:closed,prefix:lock_,coll:comment!Alle Fenster/Türen geschlossen;<br />
#<br />
# Anzeige aller Geräte der Gruppe Dachfenster, bei denen das Reading state den Wert open hat<br />
name:lockroof,filter:group=Dachfenster,read:state,if:any=open,else:closed,prefix:lockroof_,coll:comment!Alle Dachfenster geschlossen;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt aber nicht mit Haustuer endet und bei denen das Reading state den Wert open hat<br />
name:lockwin,filter:name=^HM_TF.*!Haustuer$,read:state,if:any=open,else:closed,prefix:lockwin_,coll:comment!Alle Fenster/Türen geschlossen;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_KL beginnt und bei denen das Reading HUMIDITY größer gleich 60 ist<br />
name:hummax,filter:name=^HM_KL.*,read:HUMIDITY,if:ge=60,else:0,prefix:hummax_,coll:alias!Luftfeuchte OK;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und die nicht erreichbar sind<br />
name:unreach,filter:name=^HM_.*,read:activity,if:any=dead,else:alive,prefix:unreach_,coll:comment!Alle Devices erreichbar<br />
</pre><br />
<br />
Mit den folgenden Attributen werden die Aggregations-Readings im I/O Device aktualisiert:<br />
<pre><br />
#<br />
# Readings schreiben<br />
attr d_ccu ccureadings 1<br />
attr d_ccu event-on-change-reading .*<br />
#<br />
# Werte auf eine Nachkommastelle abschneiden<br />
attr d_ccu stripnumber 1<br />
</pre><br />
<br />
==Neue Geräte anlernen==<br />
Um ein neues Gerät an die CCU anzulernen und in FHEM zu nutzen, kann man wie folgt vorgehen:<br />
<br />
# Gerät in CCU2 anlernen<br />
# Im WebUI der CCU2 den Menübefehl ''Einstellungen → Geräte'' aufrufen. Das neu angelernte Gerät in der Liste suchen und nacheinander das Gerät selbst sowie die einzelnen Kanäle nach eigenen Wünschen umbenennen. Dabei sind folgende Regeln zu beachten:<br />
#* CCU2 weit Keine Namen doppelt vergeben, z.B. darf ein Raum nicht den gleichen Namen haben wie ein Gerät.<br />
#* Keine Umlaute verwenden.<br />
#* Wenn möglich keine Leerzeichen verwenden (funktioniert zwar, erschwert aber das Handling in FHEM).<br />
# In FHEM für das I/O Device den Befehl '''get devicelist''' ausführen, um das neue Gerät in FHEM bekannt zu machen.<br />
# Für das I/O Device den Befehl get deviceinfo CCU2-Devicename ausführen. Die Ausgabe zeigt die für das Gerät verfügbaren Kanäle und Datenpunkte sowie die möglichen Operationen (R=Read, W=Write, E=Event) an, die ausgeführt werden können. Anhand dieser Informationen kann man entscheiden, ob man im nächsten Schritt besser HMCCUCHN oder HMCCUDEV für die weiteren Definitionen verwendet. Falls sich aus den Namen der Datenpunkte nicht ihr Verwendungszweck ergibt, findet man in der [http://www.eq-3.de/Downloads/eq3/download%20bereich/hm_web_ui_doku/hm_devices_Endkunden.pdf EQ3-Doku] eine detaillierte Beschreibung der Datenpunkte aller Geräte.<br />
# Ein FHEM Device für das neue Gerät und/oder seine Kanäle definieren:<br />
#* Das Modul HMCCUCHN verwenden, wenn lediglich ein Kanal des Geräts in FHEM eingebunden werden soll oder die Kanäle separat verwendet werden sollen (z.B. bei einem 4-fach Aktor).<br />
#* Das Modul HMCCUDEV verwenden, wenn das komplette Gerät mit allen Kanälen in FHEM eingebunden werden soll oder bei Sonderfällen wie Rauchmeldergruppen oder virtuelle Gerätegruppen.<br />
# Für das neue Device in FHEM den Befehl set defaults ausführen, um einige Attribute zu setzen. Hinweis: Default-Attribute sind nicht für alle Gerätetypen verfügbar. Grundsätzlich sollten folgende Attribute gesetzt werden:<br />
#* ccureadingfilter - Einschränkung auf die tatsächlich benötigten Datenpunkte bzw. Readings<br />
#* ccureadingformat - Bessere Lesbarkeit der Readings durch das Format datapoint<br />
#* event-on-change-reading bzw. event-on-update-reading - Wenn ein Schalter oder Taster über Datenpunkte wie PRESSED_xxx verfügt, sollte event-on-update-reading auf ".*" gesetzt werden. Bei allen anderen Geräten event-on-change-reading.<br />
#* statedatapoint - Legt den Kanal und den Datenpunkt fest, über den ein Gerät oder ein Kanal geschaltet wird bzw. dessen Wert in STATE des FHEM Devices übernommen wird. Bei HMCCUCHN Devices wird nur der Datenpunkt angegeben.<br />
#* statevals - Legt sprechende Namen für Schaltzustände fest. Die Angaben hier stehen dann als Set-Befehle zur Verfügung.<br />
#* substitute - Ersetzt Datenpunktwerte durch Texte bevor sie in Readings gespeichert werden<br />
<br />
==Readingnames anpassen==<br />
===Format von Readingnames===<br />
In HMCCUDEV und HMCCUCHN werden Readingnames aus den Kanalnamen oder den Kanaladressen sowie den Datenpunktnamen gebildet. Das Format der Readingnames kann über das Attribut ''ccureadingformat'' eingestellt werden. Die Vorgabe ist 'datapoint' Die folgende Tabelle enthält eine Übersicht der Formate:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Datenpunktname oder -adresse !! ccureadingformat !! Readingname<br />
|-<br />
| BidCos-RF.1234567:1.STATE || datapoint || 1.STATE<br />
|- <br />
| BidCos-RF.1234567:1.STATE || datapointlc || 1.state<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || name || MeinKanal.1.LEVEL<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || address || 1234567.1.LEVEL<br />
|}<br />
<br />
===Readingnames ändern oder ergänzen===<br />
Mit dem Attribut ''ccureadingname'' können einzelne Readings umbenannt oder neue Readings als Kopie vorhandener Readings hinzugefügt werden. Die Syntax des Attributs sieht wie folgt aus:<br />
<br />
ccureadingname Ausdruck:[+]NewReading[;...]<br />
<br />
Der Parameter ''Ausdruck'' gibt den Teil eines Readingnames an, der ersetzt werden soll. Mit ''NewReading'' wird der Name des zusätzlichen Readings (führendes '+') oder der Ersetzungstext für den vorhandenen Readingname festgelegt. Beispiele:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Readingname alt !! ccureadingname !! Readingname(s) neu<br />
|-<br />
| 1.LEVEL || LEVEL:pct || 1.pct<br />
|- <br />
| 1.LEVEL || [0-9]{1,2}\.LEVEL:pct || pct<br />
|-<br />
| 1.LEVEL || 1.LEVEL:+pct;1.LEVEL:level || pct, level<br />
|-<br />
| 1.LEVEL || 1.LEVEL:pct;1.LEVEL:level || pct<br />
|}<br />
<br />
Wichtig! Die Regeln werden von links nach rechts abgearbeitet. Daher greift die 2. Regel in der letzten Zeile nicht mehr (1.LEVEL wurde zuvor durch pct ersetzt).<br />
<br />
=== Readingnames zusammenfassen===<br />
Mit dem Attribut ''ccureadingname'' können auch mehrere Readings zu einem neuen Reading zusammengefasst werden. Beispiel: Ein Taster liefert je nach Dauer des Tastendrucks im Kanal 1 ein Event PRESS_SHORT oder PRESS_LONG. Normalerweise würden dabei auch zwei Readings "1.PRESS_SHORT" und "1.PRESS_LONG" entstehen. Diese beiden Readings können mit folgendem Befehl in einem Reading PRESSED zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^1.PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
Wenn ein Taster über mehrere Kanäle (hier vier) verfügt, können auch diese zu einem einzigen Reading zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^[1-4].PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
==Readingwerte manipulieren==<br />
===Readingwerte ersetzen===<br />
Mit dem Attribut ''substitute'' können Werte von Readings durch neue Werte bzw. Zeichenketten ersetzt werden. Die Veränderungen können sich auf bestimmte Datenpunkte oder alle Readings eines Devices beziehen. Die zu ersetzenden Werte werden dabei entweder durch reguläre Ausdrücke oder als Nummernbereiche angegeben.<br />
<br />
Im folgenden Beispiel werden die Werte 1 oder true in allen Readings durch "yes" ersetzt, die Werte 0 oder false durch "no":<br />
<br />
<pre>attr mydev substitute (1|true):yes,(0|false):no</pre><br />
<br />
Wenn sich mehrere Ersetzungsregeln auf den gleichen Datenpunkt beziehen oder wie im Beispiel oben für alle Datenpunkte gelten, werden sie einfach durch ein Komma getrennt aneinander gehängt. Eine Ersetzungsregel kann sich auch auf einen bestimmten Datenpunkt beziehen. Im folgenden Beispiel eines Fensterkontakts sollen die Werte des Datenpunktes STATE durch "open" bzw. "closed" ersetzt werden. Der Name des Datenpunktes wird in diesem Fall einfach durch ein Ausrufezeichen getrennt der Regel vorangestellt: <br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Sollte ein Geräte in mehreren Kanälen identische Datenpunkte enthalten, kann dem Datenpunktnamen noch eine Kanalnummer mit einem Punkt vorangestellt werden:<br />
<br />
<pre>attr mydev substitute 1.STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Eine Ersetzungsregel kann sich auch auf mehrere Datenpunkte beziehen (im Beispiel ERROR und LOWBAT), die durch Komma getrennt vor dem '!' aufgelistet werden:<br />
<br />
<pre>attr mydev substitute ERROR,LOWBAT!(1|true):yes,(0|false):no</pre><br />
<br />
Wenn mehrere Ersetzungsregeln definiert werden sollen, werden sie durch ein Semikolon getrennt. Im folgenden Beispiel sollen die Werte der Datenpunkte STATE und LOWBAT unterschiedlich interpretiert werden:<br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed;LOWBAT!(1|true):low,(0|false):ok</pre><br />
<br />
Bei Datenpunkten mit numerischen Werten wie z.B. dem Level eines Rollladenaktors kann es sinnvoll sein, Werte oder Wertebereiche zu ersetzen. Im folgenden Beispiel kann der Datenpunkt LEVEL Werte von 0-100 annehmen. Der Wert 0 soll als "closed" und der Wert 100 als "open" dargestellt werden. Alle anderen Werte als "partial":<br />
<br />
<pre>attr mydev substitute LEVEL!#0-0:closed,#1-99:partial,#100-100:open</pre><br />
<br />
Zu ersetzende Nummernbereiche beginnen also immer mit einem #. Es müssen immer Bereiche angegeben werden.<br />
<br />
In Ersetzungsregeln können auch Variablen verwendet werden. Eine Variable wird dabei im Format ${Datenpunkt} angegeben. Ein Sonderfall ist die Variable ${value}, die durch den Originalwert ersetzt wird. Beispiel: An den Wert der Luftfeuchte soll der Text "Prozent" angehängt werden:<br />
<br />
<pre>attr mydev substitute HUMIDITY!.+:${value}%</pre><br />
<br />
Im zweiten Beispiel soll der Temperaturwert durch eine Ausgabe im Format T=Temperatur°, H=Luftfeuchte% ersetzt werden:<br />
<br />
<pre> attr mydev substitute TEMPERATURE!.+:T=${value}° H={1.HUMIDITY}%</pre><br />
<br />
<br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=29222HMCCU2019-01-25T14:35:55Z<p>Zap: /* CCU Firewall Einstellungen */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (Homematic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von Homematic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Bei "Firewall-Richtlinie" den Eintrag "Ports offen" auswählen, andernfalls müssen die notwendigen Ports im Feld "Port-Freigabe" explizit angegeben werden<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
Zusätzlich muss in der Systemsteuerung unter "Sicherheit" die Option "Authentifizierung" deaktiviert werden, da HMCCU den Zugriff per Username/Password noch nicht unterstützt.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPCPROC bereitgestellte externe RPC-Server verwendet keine temporären Dateien. Der interne RPC-Server wird ab Version 4.4 nicht mehr unterstützt.<br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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. Durch ''ccudelay'' wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die Vorgabe sind 180 Sekunden. Je nach Installation kann auch ein höherer Wert notwendig sein:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
Durch diese Angabe erfolgt eine verzögerte Initialisierung des I/O Device sowie der FHEM Homematic Devices, wenn die CCU beim Start von FHEM nicht erreichbar ist. Der Start von FHEM wird dadurch nicht verzögert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden.<br />
<br />
===RPC Server konfigurieren===<br />
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. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* HVL<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
Danach wird durch setzen des Attributs ''ccuflags'' auf den Wert procrpc der externe RPC-Server aktiviert. Die Verwendung des internen RPC-Servers ist zwar noch möglich, wird jedoch nicht mehr offiziell unterstützt.<br />
<br />
'''Externer RPC-Server (HMCCURPCPROC)'''<br />
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.<br />
<br />
'''RPC-Server starten'''<br />
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. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=27956HMCCU2018-10-02T16:25:01Z<p>Zap: Beschreibung komplett aktualisiert</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
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:<br />
<br />
* Unterstützt Hard- und Software CCUs inkl. CCU3, YAHM, piVCCU und RaspberryMatic<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CUxD, OSRAM und Philips Hue Devices in der CCU<br />
* Unterstützung von HVL (Homematic Virtual Layer)<br />
* Unterstützung von CCU Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU Systemvariablen<br />
* Ausführen von CCU Programmen<br />
* Ausführen von Homematic Scripts auf der CCU<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU (I/O Device)<br />
* HMCCURPCPROC: RPC-Server zum Empfang von Events der CCU<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* 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.<br />
* 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.<br />
* Nach dem Neustart der CCU muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU Firmware Updates muss der RPC-Server gestoppt werden.<br />
* 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPCPROC bereitgestellte externe RPC-Server verwendet keine temporären Dateien. Der interne RPC-Server wird ab Version 4.4 nicht mehr unterstützt.<br />
<br />
===Definition I/O Device===<br />
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“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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. Durch ''ccudelay'' wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die Vorgabe sind 180 Sekunden. Je nach Installation kann auch ein höherer Wert notwendig sein:<br />
<pre>define d_ccu HMCCU 192.168.1.10 ccudelay=180</pre><br />
Durch diese Angabe erfolgt eine verzögerte Initialisierung des I/O Device sowie der FHEM Homematic Devices, wenn die CCU beim Start von FHEM nicht erreichbar ist. Der Start von FHEM wird dadurch nicht verzögert. Die verzögerte Initialisierung kann mit dem Parameter ''delayedinit'' erzwungen werden.<br />
<br />
===RPC Server konfigurieren===<br />
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. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* HVL<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
Danach wird durch setzen des Attributs ''ccuflags'' auf den Wert procrpc der externe RPC-Server aktiviert. Die Verwendung des internen RPC-Servers ist zwar noch möglich, wird jedoch nicht mehr offiziell unterstützt.<br />
<br />
'''Externer RPC-Server (HMCCURPCPROC)'''<br />
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.<br />
<br />
'''RPC-Server starten'''<br />
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. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden.<br />
<br />
Alle RPC-Server werden über das I/O Device mit einem Befehl gestartet:<br />
<pre>set d_ccu rpcserver on</pre><br />
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.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit die RPC-Server beim Start von FHEM automatisch gestartet werden:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU Programmen===<br />
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.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=24827HMCCU2018-01-30T09:59:15Z<p>Zap: Beschreibung HMCCURPCPROC eingefügt</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU2 an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:<br />
<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU2 Systemvariablen<br />
* Ausführen von CCU2 Programmen<br />
* Ausführen von Homematic Scripts auf der CCU2<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)<br />
* HMCCURPC: Alternativer auf Threads basierender RPC-Server<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.<br />
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.<br />
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.<br />
* Seit der CCU2 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.<br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.<br />
<br />
===Definition I/O Device===<br />
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
Falls die CCU als Software Service auf dem gleichen Rechner läuft wie FHEM, sollte bei der Definition der Paramter waitforccu angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM. Durch waitfoccu wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die 180 Sekunden sind nur ein Beispiel. Je nach Installation kann auch ein höherer Wert notwendig sein:<br />
<pre>define d_ccu HMCCU 192.168.1.10 waitforccu=180</pre><br />
<br />
===RPC Server konfigurieren===<br />
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 CCU2 registrieren soll. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
Mit Version 4.2 stehen drei verschiedene RPC Server zur Verfügung. Der verwendete RPC Server wird im I/O Device mit dem Attribut ccuflags festgelegt:<br />
* intrpc = Interner RPC Server des Moduls HMCCU. Verwendet Filequeues für die Eventverarbeitung. Relativ langsame Reaktionszeit<br />
* extrpc = Externer RPC Server (Modul HMCCURPC). Verwendet Threads und ist teilweise inkompatibel mit Modulen, die JSON verwenden (s.u.)<br />
* procrpc = Externer RPC Server (Modul HMCCURPCPROC). Verwendet Subprozesse, hat eine sehr kurze Reaktionszeit und keine Probleme mit JSON.<br />
<br />
Ab Version 4.2 ist ccuflags=procrpc zu bevorzugen. Ab Version 4.3 werden die anderen beiden Varianten eingestellt.<br />
<br />
'''Interner RPC-Server'''<br />
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:<br />
<pre>attr d_ccu ccuflags intrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices<br />
attr d_ccu rpcqueue /tmp/ccuqueue<br />
attr d_ccu rpcinterval 5</pre><br />
<br />
'''Externer RPC-Server (HMCCURPC)'''<br />
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden. Beispiel:<br />
<pre>attr d_ccu ccuflags extrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre><br />
{{Hinweis|Beim externen RPC-Server kann es zu Inkompatibilitäten mit Modulen kommen, die JSON verwenden (z.B. HUEBridge). Falls im Log von FHEM JSON Fehlermeldungen auftauchen, muss entweder der interne RPC-Server verwendet oder das Perl Modul JSON::XS deinstalliert werden. Für die Nutzung von JSON ist es nicht zwingend erforderlich. Unter Raspbian kann das Modul mit folgendem Befehl entfernt werden:<br />
<pre>sudo dpkg --purge libjson-xs-perl</pre><br />
Für CPAN lautet der Befehl:<br />
<pre>sudo cpan --uninstall JSON::XS</pre><br />
}}<br />
<br />
'''Externer RPC-Server (HMCCURPCPROC)'''<br />
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.<br />
<br />
<br />
'''RPC-Server starten'''<br />
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.<br />
<br />
Der eigentliche Startbefehl sieht so aus:<br />
<pre>set d_ccu rpcserver on</pre><br />
Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU2 Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU2 Programmen===<br />
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 CCU2 aktiv oder inaktiv ist.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=23558HMCCU2017-12-13T11:53:50Z<p>Zap: /* Inbetriebnahme */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU2 an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:<br />
<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU2 Systemvariablen<br />
* Ausführen von CCU2 Programmen<br />
* Ausführen von Homematic Scripts auf der CCU2<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)<br />
* HMCCURPC: Alternativer auf Threads basierender RPC-Server<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.<br />
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.<br />
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.<br />
* Seit der CCU2 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.<br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.<br />
<br />
===Definition I/O Device===<br />
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
Falls die CCU als Software Service auf dem gleichen Rechner läuft wie FHEM, sollte bei der Definition der Paramter waitforccu angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM. Durch waitfoccu wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die 180 Sekunden sind nur ein Beispiel. Je nach Installation kann auch ein höherer Wert notwendig sein:<br />
<pre>define d_ccu HMCCU 192.168.1.10 waitforccu=180</pre><br />
<br />
===RPC Server konfigurieren===<br />
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 CCU2 registrieren soll. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
Nach den Schnittstellen wird festgelegt, ob der interne (Default) oder der externe RPC-Server verwendet werden soll. Der externe RPC-Server (Modul HMCCURPC) hat den Vorteil, dass er deutlich schneller auf CCU Ereignisse reagiert, daher ist diese Variante zu bevorzugen. Der verwendete RPC-Server wird mit dem Attribut ''ccuflags'' festgelegt.<br />
<br />
'''Interner RPC-Server'''<br />
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:<br />
<pre>attr d_ccu ccuflags intrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices<br />
attr d_ccu rpcqueue /tmp/ccuqueue<br />
attr d_ccu rpcinterval 5</pre><br />
<br />
'''Externer RPC-Server'''<br />
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden:<br />
<pre>attr d_ccu ccuflags extrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre><br />
{{Hinweis|Beim externen RPC-Server kann es zu Inkompatibilitäten mit Modulen kommen, die JSON verwenden (z.B. HUEBridge). Falls im Log von FHEM JSON Fehlermeldungen auftauchen, muss entweder der interne RPC-Server verwendet oder das Perl Modul JSON::XS deinstalliert werden. Für die Nutzung von JSON ist es nicht zwingend erforderlich. Unter Raspbian kann das Modul mit folgendem Befehl entfernt werden:<br />
<pre>sudo dpkg --purge libjson-xs-perl</pre><br />
Für CPAN lautet der Befehl:<br />
<pre>sudo cpan --uninstall JSON::XS</pre><br />
}}<br />
<br />
'''RPC-Server starten'''<br />
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.<br />
<br />
Der eigentliche Startbefehl sieht so aus:<br />
<pre>set d_ccu rpcserver on</pre><br />
Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU2 Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU2 Programmen===<br />
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 CCU2 aktiv oder inaktiv ist.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Best_Practice&diff=23126HMCCU Best Practice2017-10-31T09:44:29Z<p>Zap: Beschreibung von Substitute ergänzt</p>
<hr />
<div>==I/O Device anlegen==<br />
===I/O Device definieren===<br />
Die Kommunikation zwischen FHEM und einer CCU2 erfolgt über ein Device vom Typ HMCCU. Der folgende Befehl legt ein solches I/O Device an. Dabei wird die IP-Adresse der CCU2 als Parameter angegeben:<br />
<pre>define d_ccu HMCCU 192.168.1.100</pre><br />
<br />
===Attribute setzen===<br />
Zunächst wird der RPC-Server konfiguriert. Im folgenden Beispiel werden BidCos, HM-IP, CUxD und Gerätegruppen (VirtualDevices) berücksichtigt. Es dürfen nur die Schnittstellen angegeben werden, die in der CCU2 auch verwendet werden.<br />
<pre><br />
#<br />
# Schnittstellen<br />
attr d_ccu rpcinterfaces BidCos-RF,CUxD,HmIP-RF,VirtualDevices<br />
#<br />
# RPC-Server nach dem Start von FHEM automatisch starten<br />
attr d_ccu rpcserver on<br />
#<br />
# Status anzeigen<br />
attr d_ccu stateFormat rpcstate/state<br />
#<br />
# Buttons für das Starten und Stoppen des RPC-Servers anzeigen<br />
attr d_ccu cmdIcon on:general_an off:general_aus<br />
attr d_ccu eventMap /rpcserver on:on/rpcserver off:off/<br />
</pre><br />
<br />
Mit dem Befehl set d_ccu defaults werden weitere Attribute gesetzt, die das Handling von Readings in den später definierten Devices vom Typ HMCCUCHN und HMCCUDEV beeinflussen bzw. vereinfachen. Diese Attribute können natürlich auch einzeln gesetzt werden:<br />
<pre><br />
#<br />
# Readings LOWBAT, LOW_BAT und UNREACH immer berücksichtigen<br />
attr d_ccu ccudef-readingfilter ^(LOW_?BAT|UNREACH)$<br />
#<br />
# Readings LOWBAT und LOW_BAT in battery umbenennen, Reading UNREACH in activity umbenennen<br />
attr d_ccu ccudef-readingname ^(.+\.)?LOW_?BAT$:battery;^(.+\.)?UNREACH$:activity<br />
#<br />
# Werte von Readings durch sprechende Ausdrücke ersetzen<br />
attr d_ccu ccudef-substitute AES_KEY!(0|false):off,(1|true):on;LOWBAT,LOW_BAT!(0|false):ok,(1|true):low;UNREACH!(0|false):alive,(1|true):dead;MOTION!(0|false):noMotion,(1|true):motion;DIRECTION!0:stop,1:up,2:down,3:undefined;WORKING!0:false,1:true;INHIBIT!(0|false):unlocked,(1|true):locked<br />
</pre><br />
<br />
Nun werden noch Aggregationen definiert. Mit dieser Funktion können bestimmte Stati von Homematic Devices im I/O Device als Reading dargestellt werden (z.B. Liste der offenen Fenster, Geräte mit leerer Batterie). Um die Definition der Aggregationen bzw. der Filter einfach zu halten, sollte man sich ein Namensschema überlegen. Die folgenden Aggregationen gehen davon aus, dass alle Homematic Devices in FHEM mit "HM-" beginnen. Danach folgt die Funktion des Gerätes, z.B. KL für Klima und TF für TürFenster. Bei anderer Namensgebung sind die Filterangaben entsprechend anzupassen. Alternativ kann auch der Gerätetyp oder die Gruppe als Filter verwendet werden (s.a. Command Reference zu HMCCU). Das Attribut ''ccuaggregate'' unterstützt mehrzeilige Angaben. Im folgenden Beispiel ist nur der Attributwert angegeben. Eingabe am besten über Auswahl des Attributs ''ccuaggregate'' in der FHEM Oberfläche. Die Kommentarzeilen beginnend mit # weglassen.<br />
<pre><br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und bei denen das Reading battery den Wert low hat<br />
name:battery,filter:name=^HM_.*,read:battery,if:any=low,else:ok,prefix:battery_,coll:comment!Batterien OK;<br />
#<br />
# Anzeige aller Geräte vom Typ HM-CC-RT-DN oder HM-TC-IT-WM-W-EU, deren Batteriespannung kleiner gleich 2.2 Volt ist<br />
name:voltage,filter:type=(HM-CC-RT-DN|HM-TC-IT-WM-W-EU),read:BATTERY_STATE,if:le=2.2,else:0,prefix:voltage_,coll:comment!Batteriespannung OK;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt und bei denen das Reading state den Wert open hat<br />
name:lock,filter:name=^HM_TF.*,read:state,if:any=open,else:closed,prefix:lock_,coll:comment!Alle Fenster/Türen geschlossen;<br />
#<br />
# Anzeige aller Geräte der Gruppe Dachfenster, bei denen das Reading state den Wert open hat<br />
name:lockroof,filter:group=Dachfenster,read:state,if:any=open,else:closed,prefix:lockroof_,coll:comment!Alle Dachfenster geschlossen;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt aber nicht mit Haustuer endet und bei denen das Reading state den Wert open hat<br />
name:lockwin,filter:name=^HM_TF.*!Haustuer$,read:state,if:any=open,else:closed,prefix:lockwin_,coll:comment!Alle Fenster/Türen geschlossen;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_KL beginnt und bei denen das Reading HUMIDITY größer gleich 60 ist<br />
name:hummax,filter:name=^HM_KL.*,read:HUMIDITY,if:ge=60,else:0,prefix:hummax_,coll:alias!Luftfeuchte OK;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und die nicht erreichbar sind<br />
name:unreach,filter:name=^HM_.*,read:activity,if:any=dead,else:alive,prefix:unreach_,coll:comment!Alle Devices erreichbar<br />
</pre><br />
<br />
Mit den folgenden Attributen werden die Aggregations-Readings im I/O Device aktualisiert:<br />
<pre><br />
#<br />
# Readings schreiben<br />
attr d_ccu ccureadings 1<br />
attr d_ccu event-on-change-reading .*<br />
#<br />
# Werte auf eine Nachkommastelle abschneiden<br />
attr d_ccu stripnumber 1<br />
</pre><br />
<br />
==Neue Geräte anlernen==<br />
Um ein neues Gerät an die CCU anzulernen und in FHEM zu nutzen, kann man wie folgt vorgehen:<br />
<br />
# Gerät in CCU2 anlernen<br />
# Im WebUI der CCU2 den Menübefehl ''Einstellungen → Geräte'' aufrufen. Das neu angelernte Gerät in der Liste suchen und nacheinander das Gerät selbst sowie die einzelnen Kanäle nach eigenen Wünschen umbenennen. Dabei sind folgende Regeln zu beachten:<br />
#* CCU2 weit Keine Namen doppelt vergeben, z.B. darf ein Raum nicht den gleichen Namen haben wie ein Gerät.<br />
#* Keine Umlaute verwenden.<br />
#* Wenn möglich keine Leerzeichen verwenden (funktioniert zwar, erschwert aber das Handling in FHEM).<br />
# In FHEM für das I/O Device den Befehl '''get devicelist''' ausführen, um das neue Gerät in FHEM bekannt zu machen.<br />
# Für das I/O Device den Befehl get deviceinfo CCU2-Devicename ausführen. Die Ausgabe zeigt die für das Gerät verfügbaren Kanäle und Datenpunkte sowie die möglichen Operationen (R=Read, W=Write, E=Event) an, die ausgeführt werden können. Anhand dieser Informationen kann man entscheiden, ob man im nächsten Schritt besser HMCCUCHN oder HMCCUDEV für die weiteren Definitionen verwendet. Falls sich aus den Namen der Datenpunkte nicht ihr Verwendungszweck ergibt, findet man in der [http://www.eq-3.de/Downloads/eq3/download%20bereich/hm_web_ui_doku/hm_devices_Endkunden.pdf EQ3-Doku] eine detaillierte Beschreibung der Datenpunkte aller Geräte.<br />
# Ein FHEM Device für das neue Gerät und/oder seine Kanäle definieren:<br />
#* Das Modul HMCCUCHN verwenden, wenn lediglich ein Kanal des Geräts in FHEM eingebunden werden soll oder die Kanäle separat verwendet werden sollen (z.B. bei einem 4-fach Aktor).<br />
#* Das Modul HMCCUDEV verwenden, wenn das komplette Gerät mit allen Kanälen in FHEM eingebunden werden soll oder bei Sonderfällen wie Rauchmeldergruppen oder virtuelle Gerätegruppen.<br />
# Für das neue Device in FHEM den Befehl set defaults ausführen, um einige Attribute zu setzen. Hinweis: Default-Attribute sind nicht für alle Gerätetypen verfügbar. Grundsätzlich sollten folgende Attribute gesetzt werden:<br />
#* ccureadingfilter - Einschränkung auf die tatsächlich benötigten Datenpunkte bzw. Readings<br />
#* ccureadingformat - Bessere Lesbarkeit der Readings durch das Format datapoint<br />
#* event-on-change-reading bzw. event-on-update-reading - Wenn ein Schalter oder Taster über Datenpunkte wie PRESSED_xxx verfügt, sollte event-on-update-reading auf ".*" gesetzt werden. Bei allen anderen Geräten event-on-change-reading.<br />
#* statedatapoint - Legt den Kanal und den Datenpunkt fest, über den ein Gerät oder ein Kanal geschaltet wird bzw. dessen Wert in STATE des FHEM Devices übernommen wird. Bei HMCCUCHN Devices wird nur der Datenpunkt angegeben.<br />
#* statevals - Legt sprechende Namen für Schaltzustände fest. Die Angaben hier stehen dann als Set-Befehle zur Verfügung.<br />
#* substitute - Ersetzt Datenpunktwerte durch Texte bevor sie in Readings gespeichert werden<br />
<br />
==Readingnames anpassen==<br />
===Format von Readingnames===<br />
In HMCCUDEV und HMCCUCHN werdent Readingnames aus den Kanalnamen oder den Kanaladressen sowie den Datenpunktnamen gebildet. Das Format der Readingnames kann über das Attribut ''ccureadingformat'' eingestellt werden. Die Vorgabe ist 'datapoint' Die folgende Tabelle enthält eine Übersicht der Formate:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Datenpunktname oder -adresse !! ccureadingformat !! Readingname<br />
|-<br />
| BidCos-RF.1234567:1.STATE || datapoint || 1.STATE<br />
|- <br />
| BidCos-RF.1234567:1.STATE || datapointlc || 1.state<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || name || MeinKanal.1.LEVEL<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || address || 1234567.1.LEVEL<br />
|}<br />
<br />
===Readingnames ändern oder ergänzen===<br />
Mit dem Attribut ''ccureadingname'' können einzelne Readings umbenannt oder neue Readings als Kopie vorhandener Readings hinzugefügt werden. Die Syntax des Attributs sieht wie folgt aus:<br />
<br />
ccureadingname Ausdruck:[+]NewReading[;...]<br />
<br />
Der Parameter ''Ausdruck'' gibt den Teil eines Readingnames an, der ersetzt werden soll. Mit ''NewReading'' wird der Name des zusätzlichen Readings (führendes '+') oder der Ersetzungstext für den vorhandenen Readingname festgelegt. Beispiele:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Readingname alt !! ccureadingname !! Readingname(s) neu<br />
|-<br />
| 1.LEVEL || LEVEL:pct || 1.pct<br />
|- <br />
| 1.LEVEL || [0-9]{1,2}\.LEVEL:pct || pct<br />
|-<br />
| 1.LEVEL || 1.LEVEL:+pct;1.LEVEL:level || pct, level<br />
|-<br />
| 1.LEVEL || 1.LEVEL:pct;1.LEVEL:level || pct<br />
|}<br />
<br />
Wichtig! Die Regeln werden von links nach rechts abgearbeitet. Daher greift die 2. Regel in der letzten Zeile nicht mehr (1.LEVEL wurde zuvor durch pct ersetzt).<br />
<br />
=== Readingnames zusammenfassen===<br />
Mit dem Attribut ''ccureadingname'' können auch mehrere Readings zu einem neuen Reading zusammengefasst werden. Beispiel: Ein Taster liefert je nach Dauer des Tastendrucks im Kanal 1 ein Event PRESS_SHORT oder PRESS_LONG. Normalerweise würden dabei auch zwei Readings "1.PRESS_SHORT" und "1.PRESS_LONG" entstehen. Diese beiden Readings können mit folgendem Befehl in einem Reading PRESSED zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^1.PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
Wenn ein Taster über mehrere Kanäle (hier vier) verfügt, können auch diese zu einem einzigen Reading zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^[1-4].PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
==Readingwerte manipulieren==<br />
===Readingwerte ersetzen===<br />
Mit dem Attribut ''substitute'' können Werte von Readings durch neue Werte bzw. Zeichenketten ersetzt werden. Die Veränderungen können sich auf bestimmte Datenpunkte oder alle Readings eines Devices beziehen. Die zu ersetzenden Werte werden dabei entweder durch reguläre Ausdrücke oder als Nummernbereiche angegeben.<br />
<br />
Im folgenden Beispiel werden die Werte 1 oder true in allen Readings durch "yes" ersetzt, die Werte 0 oder false durch "no":<br />
<br />
<pre>attr mydev substitute (1|true):yes,(0|false):no</pre><br />
<br />
Wenn sich mehrere Ersetzungsregeln auf den gleichen Datenpunkt beziehen oder wie im Beispiel oben für alle Datenpunkte gelten, werden sie einfach durch ein Komma getrennt aneinander gehängt. Eine Ersetzungsregel kann sich auch auf einen bestimmten Datenpunkt beziehen. Im folgenden Beispiel eines Fensterkontakts sollen die Werte des Datenpunktes STATE durch "open" bzw. "closed" ersetzt werden. Der Name des Datenpunktes wird in diesem Fall einfach durch ein Ausrufezeichen getrennt der Regel vorangestellt: <br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Sollte ein Geräte in mehreren Kanälen identische Datenpunkte enthalten, kann dem Datenpunktnamen noch eine Kanalnummer mit einem Punkt vorangestellt werden:<br />
<br />
<pre>attr mydev substitute 1.STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Eine Ersetzungsregel kann sich auch auf mehrere Datenpunkte beziehen (im Beispiel ERROR und LOWBAT), die durch Komma getrennt vor dem '!' aufgelistet werden:<br />
<br />
<pre>attr mydev substitute ERROR,LOWBAT!(1|true):yes,(0|false):no</pre><br />
<br />
Wenn mehrere Ersetzungsregeln definiert werden sollen, werden sie durch ein Semikolon getrennt. Im folgenden Beispiel sollen die Werte der Datenpunkte STATE und LOWBAT unterschiedlich interpretiert werden:<br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed;LOWBAT!(1|true):low,(0|false):ok</pre><br />
<br />
Bei Datenpunkten mit numerischen Werten wie z.B. dem Level eines Rollladenaktors kann es sinnvoll sein, Werte oder Wertebereiche zu ersetzen. Im folgenden Beispiel kann der Datenpunkt LEVEL Werte von 0-100 annehmen. Der Wert 0 soll als "closed" und der Wert 100 als "open" dargestellt werden. Alle anderen Werte als "partial":<br />
<br />
<pre>attr mydev substitute LEVEL!#0-0:closed,#1-99:partial,#100-100:open</pre><br />
<br />
Zu ersetzende Nummernbereiche beginnen also immer mit einem #. Es müssen immer Bereiche angegeben werden.<br />
<br />
In Ersetzungsregeln können auch Variablen verwendet werden. Eine Variable wird dabei im Format ${Datenpunkt} angegeben. Ein Sonderfall ist die Variable ${value}, die durch den Originalwert ersetzt wird. Beispiel: An den Wert der Luftfeuchte soll der Text "Prozent" angehängt werden:<br />
<br />
<pre>attr mydev substitute HUMIDITY!.+:${value}%</pre><br />
<br />
Im zweiten Beispiel soll der Temperaturwert durch eine Ausgabe im Format T=Temperatur°, H=Luftfeuchte% ersetzt werden:<br />
<br />
<pre> attr mydev substitute TEMPERATURE!.+:T=${value}° H={1.HUMIDITY}%</pre><br />
<br />
<br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Best_Practice&diff=22908HMCCU Best Practice2017-10-13T18:06:09Z<p>Zap: /* Attribute setzen */</p>
<hr />
<div>==I/O Device anlegen==<br />
===I/O Device definieren===<br />
Die Kommunikation zwischen FHEM und einer CCU2 erfolgt über ein Device vom Typ HMCCU. Der folgende Befehl legt ein solches I/O Device an. Dabei wird die IP-Adresse der CCU2 als Parameter angegeben:<br />
<pre>define d_ccu HMCCU 192.168.1.100</pre><br />
<br />
===Attribute setzen===<br />
Zunächst wird der RPC-Server konfiguriert. Im folgenden Beispiel werden BidCos, HM-IP, CUxD und Gerätegruppen (VirtualDevices) berücksichtigt. Es dürfen nur die Schnittstellen angegeben werden, die in der CCU2 auch verwendet werden.<br />
<pre><br />
#<br />
# Schnittstellen<br />
attr d_ccu rpcinterfaces BidCos-RF,CUxD,HmIP-RF,VirtualDevices<br />
#<br />
# RPC-Server nach dem Start von FHEM automatisch starten<br />
attr d_ccu rpcserver on<br />
#<br />
# Status anzeigen<br />
attr d_ccu stateFormat rpcstate/state<br />
#<br />
# Buttons für das Starten und Stoppen des RPC-Servers anzeigen<br />
attr d_ccu cmdIcon on:general_an off:general_aus<br />
attr d_ccu eventMap /rpcserver on:on/rpcserver off:off/<br />
</pre><br />
<br />
Mit dem Befehl set d_ccu defaults werden weitere Attribute gesetzt, die das Handling von Readings in den später definierten Devices vom Typ HMCCUCHN und HMCCUDEV beeinflussen bzw. vereinfachen. Diese Attribute können natürlich auch einzeln gesetzt werden:<br />
<pre><br />
#<br />
# Readings LOWBAT, LOW_BAT und UNREACH immer berücksichtigen<br />
attr d_ccu ccudef-readingfilter ^(LOW_?BAT|UNREACH)$<br />
#<br />
# Readings LOWBAT und LOW_BAT in battery umbenennen, Reading UNREACH in activity umbenennen<br />
attr d_ccu ccudef-readingname ^(.+\.)?LOW_?BAT$:battery;^(.+\.)?UNREACH$:activity<br />
#<br />
# Werte von Readings durch sprechende Ausdrücke ersetzen<br />
attr d_ccu ccudef-substitute AES_KEY!(0|false):off,(1|true):on;LOWBAT,LOW_BAT!(0|false):ok,(1|true):low;UNREACH!(0|false):alive,(1|true):dead;MOTION!(0|false):noMotion,(1|true):motion;DIRECTION!0:stop,1:up,2:down,3:undefined;WORKING!0:false,1:true;INHIBIT!(0|false):unlocked,(1|true):locked<br />
</pre><br />
<br />
Nun werden noch Aggregationen definiert. Mit dieser Funktion können bestimmte Stati von Homematic Devices im I/O Device als Reading dargestellt werden (z.B. Liste der offenen Fenster, Geräte mit leerer Batterie). Um die Definition der Aggregationen bzw. der Filter einfach zu halten, sollte man sich ein Namensschema überlegen. Die folgenden Aggregationen gehen davon aus, dass alle Homematic Devices in FHEM mit "HM-" beginnen. Danach folgt die Funktion des Gerätes, z.B. KL für Klima und TF für TürFenster. Bei anderer Namensgebung sind die Filterangaben entsprechend anzupassen. Alternativ kann auch der Gerätetyp oder die Gruppe als Filter verwendet werden (s.a. Command Reference zu HMCCU). Das Attribut ''ccuaggregate'' unterstützt mehrzeilige Angaben. Im folgenden Beispiel ist nur der Attributwert angegeben. Eingabe am besten über Auswahl des Attributs ''ccuaggregate'' in der FHEM Oberfläche. Die Kommentarzeilen beginnend mit # weglassen.<br />
<pre><br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und bei denen das Reading battery den Wert low hat<br />
name:battery,filter:name=^HM_.*,read:battery,if:any=low,else:ok,prefix:battery_,coll:comment!Batterien OK;<br />
#<br />
# Anzeige aller Geräte vom Typ HM-CC-RT-DN oder HM-TC-IT-WM-W-EU, deren Batteriespannung kleiner gleich 2.2 Volt ist<br />
name:voltage,filter:type=(HM-CC-RT-DN|HM-TC-IT-WM-W-EU),read:BATTERY_STATE,if:le=2.2,else:0,prefix:voltage_,coll:comment!Batteriespannung OK;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt und bei denen das Reading state den Wert open hat<br />
name:lock,filter:name=^HM_TF.*,read:state,if:any=open,else:closed,prefix:lock_,coll:comment!Alle Fenster/Türen geschlossen;<br />
#<br />
# Anzeige aller Geräte der Gruppe Dachfenster, bei denen das Reading state den Wert open hat<br />
name:lockroof,filter:group=Dachfenster,read:state,if:any=open,else:closed,prefix:lockroof_,coll:comment!Alle Dachfenster geschlossen;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt aber nicht mit Haustuer endet und bei denen das Reading state den Wert open hat<br />
name:lockwin,filter:name=^HM_TF.*!Haustuer$,read:state,if:any=open,else:closed,prefix:lockwin_,coll:comment!Alle Fenster/Türen geschlossen;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_KL beginnt und bei denen das Reading HUMIDITY größer gleich 60 ist<br />
name:hummax,filter:name=^HM_KL.*,read:HUMIDITY,if:ge=60,else:0,prefix:hummax_,coll:alias!Luftfeuchte OK;<br />
#<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und die nicht erreichbar sind<br />
name:unreach,filter:name=^HM_.*,read:activity,if:any=dead,else:alive,prefix:unreach_,coll:comment!Alle Devices erreichbar<br />
</pre><br />
<br />
Mit den folgenden Attributen werden die Aggregations-Readings im I/O Device aktualisiert:<br />
<pre><br />
#<br />
# Readings schreiben<br />
attr d_ccu ccureadings 1<br />
attr d_ccu event-on-change-reading .*<br />
#<br />
# Werte auf eine Nachkommastelle abschneiden<br />
attr d_ccu stripnumber 1<br />
</pre><br />
<br />
==Neue Geräte anlernen==<br />
Um ein neues Gerät an die CCU anzulernen und in FHEM zu nutzen, kann man wie folgt vorgehen:<br />
<br />
# Gerät in CCU2 anlernen<br />
# Im WebUI der CCU2 den Menübefehl ''Einstellungen → Geräte'' aufrufen. Das neu angelernte Gerät in der Liste suchen und nacheinander das Gerät selbst sowie die einzelnen Kanäle nach eigenen Wünschen umbenennen. Dabei sind folgende Regeln zu beachten:<br />
#* CCU2 weit Keine Namen doppelt vergeben, z.B. darf ein Raum nicht den gleichen Namen haben wie ein Gerät.<br />
#* Keine Umlaute verwenden.<br />
#* Wenn möglich keine Leerzeichen verwenden (funktioniert zwar, erschwert aber das Handling in FHEM).<br />
# In FHEM für das I/O Device den Befehl '''get devicelist''' ausführen, um das neue Gerät in FHEM bekannt zu machen.<br />
# Für das I/O Device den Befehl get deviceinfo CCU2-Devicename ausführen. Die Ausgabe zeigt die für das Gerät verfügbaren Kanäle und Datenpunkte sowie die möglichen Operationen (R=Read, W=Write, E=Event) an, die ausgeführt werden können. Anhand dieser Informationen kann man entscheiden, ob man im nächsten Schritt besser HMCCUCHN oder HMCCUDEV für die weiteren Definitionen verwendet. Falls sich aus den Namen der Datenpunkte nicht ihr Verwendungszweck ergibt, findet man in der [http://www.eq-3.de/Downloads/eq3/download%20bereich/hm_web_ui_doku/hm_devices_Endkunden.pdf EQ3-Doku] eine detaillierte Beschreibung der Datenpunkte aller Geräte.<br />
# Ein FHEM Device für das neue Gerät und/oder seine Kanäle definieren:<br />
#* Das Modul HMCCUCHN verwenden, wenn lediglich ein Kanal des Geräts in FHEM eingebunden werden soll oder die Kanäle separat verwendet werden sollen (z.B. bei einem 4-fach Aktor).<br />
#* Das Modul HMCCUDEV verwenden, wenn das komplette Gerät mit allen Kanälen in FHEM eingebunden werden soll oder bei Sonderfällen wie Rauchmeldergruppen oder virtuelle Gerätegruppen.<br />
# Für das neue Device in FHEM den Befehl set defaults ausführen, um einige Attribute zu setzen. Hinweis: Default-Attribute sind nicht für alle Gerätetypen verfügbar. Grundsätzlich sollten folgende Attribute gesetzt werden:<br />
#* ccureadingfilter - Einschränkung auf die tatsächlich benötigten Datenpunkte bzw. Readings<br />
#* ccureadingformat - Bessere Lesbarkeit der Readings durch das Format datapoint<br />
#* event-on-change-reading bzw. event-on-update-reading - Wenn ein Schalter oder Taster über Datenpunkte wie PRESSED_xxx verfügt, sollte event-on-update-reading auf ".*" gesetzt werden. Bei allen anderen Geräten event-on-change-reading.<br />
#* statedatapoint - Legt den Kanal und den Datenpunkt fest, über den ein Gerät oder ein Kanal geschaltet wird bzw. dessen Wert in STATE des FHEM Devices übernommen wird. Bei HMCCUCHN Devices wird nur der Datenpunkt angegeben.<br />
#* statevals - Legt sprechende Namen für Schaltzustände fest. Die Angaben hier stehen dann als Set-Befehle zur Verfügung.<br />
#* substitute - Ersetzt Datenpunktwerte durch Texte bevor sie in Readings gespeichert werden<br />
<br />
==Readingnames anpassen==<br />
===Format von Readingnames===<br />
In HMCCUDEV und HMCCUCHN werdent Readingnames aus den Kanalnamen oder den Kanaladressen sowie den Datenpunktnamen gebildet. Das Format der Readingnames kann über das Attribut ''ccureadingformat'' eingestellt werden. Die Vorgabe ist 'datapoint' Die folgende Tabelle enthält eine Übersicht der Formate:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Datenpunktname oder -adresse !! ccureadingformat !! Readingname<br />
|-<br />
| BidCos-RF.1234567:1.STATE || datapoint || 1.STATE<br />
|- <br />
| BidCos-RF.1234567:1.STATE || datapointlc || 1.state<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || name || MeinKanal.1.LEVEL<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || address || 1234567.1.LEVEL<br />
|}<br />
<br />
===Readingnames ändern oder ergänzen===<br />
Mit dem Attribut ''ccureadingname'' können einzelne Readings umbenannt oder neue Readings als Kopie vorhandener Readings hinzugefügt werden. Die Syntax des Attributs sieht wie folgt aus:<br />
<br />
ccureadingname Ausdruck:[+]NewReading[;...]<br />
<br />
Der Parameter ''Ausdruck'' gibt den Teil eines Readingnames an, der ersetzt werden soll. Mit ''NewReading'' wird der Name des zusätzlichen Readings (führendes '+') oder der Ersetzungstext für den vorhandenen Readingname festgelegt. Beispiele:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Readingname alt !! ccureadingname !! Readingname(s) neu<br />
|-<br />
| 1.LEVEL || LEVEL:pct || 1.pct<br />
|- <br />
| 1.LEVEL || [0-9]{1,2}\.LEVEL:pct || pct<br />
|-<br />
| 1.LEVEL || 1.LEVEL:+pct;1.LEVEL:level || pct, level<br />
|-<br />
| 1.LEVEL || 1.LEVEL:pct;1.LEVEL:level || pct<br />
|}<br />
<br />
Wichtig! Die Regeln werden von links nach rechts abgearbeitet. Daher greift die 2. Regel in der letzten Zeile nicht mehr (1.LEVEL wurde zuvor durch pct ersetzt).<br />
<br />
=== Readingnames zusammenfassen===<br />
Mit dem Attribut ''ccureadingname'' können auch mehrere Readings zu einem neuen Reading zusammengefasst werden. Beispiel: Ein Taster liefert je nach Dauer des Tastendrucks im Kanal 1 ein Event PRESS_SHORT oder PRESS_LONG. Normalerweise würden dabei auch zwei Readings "1.PRESS_SHORT" und "1.PRESS_LONG" entstehen. Diese beiden Readings können mit folgendem Befehl in einem Reading PRESSED zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^1.PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
Wenn ein Taster über mehrere Kanäle (hier vier) verfügt, können auch diese zu einem einzigen Reading zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^[1-4].PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
==Readingwerte manipulieren==<br />
===Readingwerte ersetzen===<br />
Mit dem Attribut ''substitute'' können Werte von Readings durch neue Werte bzw. Zeichenketten ersetzt werden. Die Veränderungen können sich auf bestimmte Datenpunkte oder alle Readings eines Devices beziehen. Die zu ersetzenden Werte werden dabei entweder durch reguläre Ausdrücke oder als Nummernbereiche angegeben.<br />
<br />
Im folgenden Beispiel werden die Werte 1 oder true in allen Readings durch "yes" ersetzt, die Werte 0 oder false durch "no":<br />
<br />
<pre>attr mydev substitute (1|true):yes,(0|false):no</pre><br />
<br />
Wenn sich mehrere Ersetzungsregeln auf den gleichen Datenpunkt beziehen oder wie im Beispiel oben für alle Datenpunkte gelten, werden sie einfach durch ein Komma getrennt aneinander gehängt. Eine Ersetzungsregel kann sich auch auf einen bestimmten Datenpunkt beziehen. Im folgenden Beispiel eines Fensterkontakts sollen die Werte des Datenpunktes STATE durch "open" bzw. "closed" ersetzt werden. Der Name des Datenpunktes wird in diesem Fall einfach durch ein Ausrufezeichen getrennt der Regel vorangestellt: <br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Sollte ein Geräte in mehreren Kanälen identische Datenpunkte enthalten, kann dem Datenpunktnamen noch eine Kanalnummer mit einem Punkt vorangestellt werden:<br />
<br />
<pre>attr mydev substitute 1.STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Wenn mehrere Ersetzungsregeln definiert werden sollen, werden sie durch ein Semikolon getrennt. Im folgenden Beispiel sollen die Werte der Datenpunkte STATE und LOWBAT unterschiedlich interpretiert werden:<br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed;LOWBAT!(1|true):low,(0|false):ok</pre><br />
<br />
Bei Datenpunkten mit numerischen Werten wie z.B. dem Level eines Rollladenaktors kann es sinnvoll sein, Werte oder Wertebereiche zu ersetzen. Im folgenden Beispiel kann der Datenpunkt LEVEL Werte von 0-100 annehmen. Der Wert 0 soll als "closed" und der Wert 100 als "open" dargestellt werden. Alle anderen Werte als "partial":<br />
<br />
<pre>attr mydev substitute LEVEL!#0-0:closed,#1-99:partial,#100-100:open</pre><br />
<br />
Zu ersetzende Nummernbereiche beginnen also immer mit einem #. Es müssen immer Bereiche angegeben werden. Eine einzelne Zahl ist nicht zulässig.<br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=22907HMCCU2017-10-13T18:01:00Z<p>Zap: /* RPC Server konfigurieren */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU2 an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:<br />
<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU2 Systemvariablen<br />
* Ausführen von CCU2 Programmen<br />
* Ausführen von Homematic Scripts auf der CCU2<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)<br />
* HMCCURPC: Alternativer auf Threads basierender RPC-Server<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.<br />
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.<br />
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.<br />
* Seit der CCU2 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.<br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.<br />
<br />
===Definition I/O Device===<br />
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
Falls die CCU als Software Service auf dem gleichen Rechner läuft wie FHEM, sollte bei der Definition der Paramter waitforccu angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM. Durch waitfoccu wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die 180 Sekunden sind nur ein Beispiel. Je nach Installation kann auch ein höherer Wert notwendig sein:<br />
<pre>define d_ccu HMCCU 192.168.1.10 waitforccu=180</pre><br />
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 CCU2 registrieren soll. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
===RPC Server konfigurieren===<br />
Nach den Schnittstellen wird festgelegt, ob der interne (Default) oder der externe RPC-Server verwendet werden soll. Der externe RPC-Server (Modul HMCCURPC) hat den Vorteil, dass er deutlich schneller auf CCU Ereignisse reagiert, daher ist diese Variante zu bevorzugen. Der verwendete RPC-Server wird mit dem Attribut ''ccuflags'' festgelegt.<br />
<br />
'''Interner RPC-Server'''<br />
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:<br />
<pre>attr d_ccu ccuflags intrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices<br />
attr d_ccu rpcqueue /tmp/ccuqueue<br />
attr d_ccu rpcinterval 5</pre><br />
<br />
'''Externer RPC-Server'''<br />
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden:<br />
<pre>attr d_ccu ccuflags extrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre><br />
{{Hinweis|Beim externen RPC-Server kann es zu Inkompatibilitäten mit Modulen kommen, die JSON verwenden (z.B. HUEBridge). Falls im Log von FHEM JSON Fehlermeldungen auftauchen, muss entweder der interne RPC-Server verwendet oder das Perl Modul JSON::XS deinstalliert werden. Für die Nutzung von JSON ist es nicht zwingend erforderlich. Unter Raspbian kann das Modul mit folgendem Befehl entfernt werden:<br />
<pre>sudo dpkg --purge libjson-xs-perl</pre><br />
Für CPAN lautet der Befehl:<br />
<pre>sudo cpan --uninstall JSON::XS</pre><br />
}}<br />
<br />
'''RPC-Server starten'''<br />
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.<br />
<br />
Der eigentliche Startbefehl sieht so aus:<br />
<pre>set d_ccu rpcserver on</pre><br />
Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU2 Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU2 Programmen===<br />
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 CCU2 aktiv oder inaktiv ist.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=22906HMCCU2017-10-13T17:46:52Z<p>Zap: /* Definition I/O Device */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU2 an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:<br />
<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU2 Systemvariablen<br />
* Ausführen von CCU2 Programmen<br />
* Ausführen von Homematic Scripts auf der CCU2<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)<br />
* HMCCURPC: Alternativer auf Threads basierender RPC-Server<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.<br />
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.<br />
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.<br />
* Seit der CCU2 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.<br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.<br />
<br />
===Definition I/O Device===<br />
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
Falls die CCU als Software Service auf dem gleichen Rechner läuft wie FHEM, sollte bei der Definition der Paramter waitforccu angegeben werden. Die CCU Services brauchen beim Starten länger als FHEM. Durch waitfoccu wird der Start von FHEM für die angegebene Anzahl Sekunden verzögert. Die 180 Sekunden sind nur ein Beispiel. Je nach Installation kann auch ein höherer Wert notwendig sein:<br />
<pre>define d_ccu HMCCU 192.168.1.10 waitforccu=180</pre><br />
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 CCU2 registrieren soll. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
===RPC Server konfigurieren===<br />
Nach den Schnittstellen wird festgelegt, ob der interne (Default) oder der externe RPC-Server verwendet werden soll. Der externe RPC-Server (Modul HMCCURPC) hat den Vorteil, dass er deutlich schneller auf CCU Ereignisse reagiert, daher ist diese Variante zu bevorzugen. Der verwendete RPC-Server wird mit dem Attribut ''ccuflags'' festgelegt.<br />
<br />
'''Interner RPC-Server'''<br />
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:<br />
<pre>attr d_ccu ccuflags intrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices<br />
attr d_ccu rpcqueue /tmp/ccuqueue<br />
attr d_ccu rpcinterval 5</pre><br />
<br />
'''Externer RPC-Server'''<br />
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden:<br />
<pre>attr d_ccu ccuflags extrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre><br />
<br />
'''RPC-Server starten'''<br />
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.<br />
<br />
Der eigentliche Startbefehl sieht so aus:<br />
<pre>set d_ccu rpcserver on</pre><br />
Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU2 Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU2 Programmen===<br />
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 CCU2 aktiv oder inaktiv ist.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=22318HMCCU2017-08-23T12:23:35Z<p>Zap: /* Autocreate von Client Devices */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU2 an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:<br />
<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU2 Systemvariablen<br />
* Ausführen von CCU2 Programmen<br />
* Ausführen von Homematic Scripts auf der CCU2<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)<br />
* HMCCURPC: Alternativer auf Threads basierender RPC-Server<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.<br />
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.<br />
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.<br />
* Seit der CCU2 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.<br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.<br />
<br />
===Definition I/O Device===<br />
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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 CCU2 registrieren soll. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
===RPC Server konfigurieren===<br />
Nach den Schnittstellen wird festgelegt, ob der interne (Default) oder der externe RPC-Server verwendet werden soll. Der externe RPC-Server (Modul HMCCURPC) hat den Vorteil, dass er deutlich schneller auf CCU Ereignisse reagiert, daher ist diese Variante zu bevorzugen. Der verwendete RPC-Server wird mit dem Attribut ''ccuflags'' festgelegt.<br />
<br />
'''Interner RPC-Server'''<br />
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:<br />
<pre>attr d_ccu ccuflags intrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices<br />
attr d_ccu rpcqueue /tmp/ccuqueue<br />
attr d_ccu rpcinterval 5</pre><br />
<br />
'''Externer RPC-Server'''<br />
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden:<br />
<pre>attr d_ccu ccuflags extrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre><br />
<br />
'''RPC-Server starten'''<br />
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.<br />
<br />
Der eigentliche Startbefehl sieht so aus:<br />
<pre>set d_ccu rpcserver on</pre><br />
Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU2 Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU2 Programmen===<br />
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 CCU2 aktiv oder inaktiv ist.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=22317HMCCU2017-08-23T12:22:39Z<p>Zap: /* Autocreate von Client Devices */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU2 an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:<br />
<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU2 Systemvariablen<br />
* Ausführen von CCU2 Programmen<br />
* Ausführen von Homematic Scripts auf der CCU2<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)<br />
* HMCCURPC: Alternativer auf Threads basierender RPC-Server<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.<br />
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.<br />
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.<br />
* Seit der CCU2 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.<br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.<br />
<br />
===Definition I/O Device===<br />
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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 CCU2 registrieren soll. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
===RPC Server konfigurieren===<br />
Nach den Schnittstellen wird festgelegt, ob der interne (Default) oder der externe RPC-Server verwendet werden soll. Der externe RPC-Server (Modul HMCCURPC) hat den Vorteil, dass er deutlich schneller auf CCU Ereignisse reagiert, daher ist diese Variante zu bevorzugen. Der verwendete RPC-Server wird mit dem Attribut ''ccuflags'' festgelegt.<br />
<br />
'''Interner RPC-Server'''<br />
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:<br />
<pre>attr d_ccu ccuflags intrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices<br />
attr d_ccu rpcqueue /tmp/ccuqueue<br />
attr d_ccu rpcinterval 5</pre><br />
<br />
'''Externer RPC-Server'''<br />
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden:<br />
<pre>attr d_ccu ccuflags extrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre><br />
<br />
'''RPC-Server starten'''<br />
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.<br />
<br />
Der eigentliche Startbefehl sieht so aus:<br />
<pre>set d_ccu rpcserver on</pre><br />
Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [defattr] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
*defattr - Sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden.<br />
*duplicates - Erlaubt das Anlegen von doppelten Devices. Wenn diese Option fehlt, werden in FHEM vorhandene Geräte nicht neu angelegt.<br />
*save - Nach dem Anlegen der Geräte wird die neue FHEM Konfiguration gespeichert.<br />
An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_". Sofern vorhanden werden Default Attribute gesetzt. Die Konfiguration wird gespeichert.<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n defattr save room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU2 Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU2 Programmen===<br />
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 CCU2 aktiv oder inaktiv ist.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=22313HMCCU2017-08-23T10:47:30Z<p>Zap: /* Einführung */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU2 an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:<br />
<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU2 Systemvariablen<br />
* Ausführen von CCU2 Programmen<br />
* Ausführen von Homematic Scripts auf der CCU2<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)<br />
* HMCCURPC: Alternativer auf Threads basierender RPC-Server<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.<br />
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.<br />
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.<br />
* Seit der CCU2 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.<br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.<br />
<br />
===Definition I/O Device===<br />
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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 CCU2 registrieren soll. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
===RPC Server konfigurieren===<br />
Nach den Schnittstellen wird festgelegt, ob der interne (Default) oder der externe RPC-Server verwendet werden soll. Der externe RPC-Server (Modul HMCCURPC) hat den Vorteil, dass er deutlich schneller auf CCU Ereignisse reagiert, daher ist diese Variante zu bevorzugen. Der verwendete RPC-Server wird mit dem Attribut ''ccuflags'' festgelegt.<br />
<br />
'''Interner RPC-Server'''<br />
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:<br />
<pre>attr d_ccu ccuflags intrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices<br />
attr d_ccu rpcqueue /tmp/ccuqueue<br />
attr d_ccu rpcinterval 5</pre><br />
<br />
'''Externer RPC-Server'''<br />
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden:<br />
<pre>attr d_ccu ccuflags extrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre><br />
<br />
'''RPC-Server starten'''<br />
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.<br />
<br />
Der eigentliche Startbefehl sieht so aus:<br />
<pre>set d_ccu rpcserver on</pre><br />
Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [defattr] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
Die Option "defattr" sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden. An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_":<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU2 Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU2 Programmen===<br />
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 CCU2 aktiv oder inaktiv ist.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=22312HMCCU2017-08-23T10:46:56Z<p>Zap: /* Einführung */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU2 an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
===Übersicht===<br />
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:<br />
<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU2 Systemvariablen<br />
* Ausführen von CCU2 Programmen<br />
* Ausführen von Homematic Scripts auf der CCU2<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)<br />
* HMCCURPC: Alternativer auf Threads basierender RPC-Server<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.<br />
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.<br />
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.<br />
* Seit der CCU2 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.<br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.<br />
<br />
===Definition I/O Device===<br />
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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 CCU2 registrieren soll. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
===RPC Server konfigurieren===<br />
Nach den Schnittstellen wird festgelegt, ob der interne (Default) oder der externe RPC-Server verwendet werden soll. Der externe RPC-Server (Modul HMCCURPC) hat den Vorteil, dass er deutlich schneller auf CCU Ereignisse reagiert, daher ist diese Variante zu bevorzugen. Der verwendete RPC-Server wird mit dem Attribut ''ccuflags'' festgelegt.<br />
<br />
'''Interner RPC-Server'''<br />
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:<br />
<pre>attr d_ccu ccuflags intrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices<br />
attr d_ccu rpcqueue /tmp/ccuqueue<br />
attr d_ccu rpcinterval 5</pre><br />
<br />
'''Externer RPC-Server'''<br />
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden:<br />
<pre>attr d_ccu ccuflags extrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre><br />
<br />
'''RPC-Server starten'''<br />
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.<br />
<br />
Der eigentliche Startbefehl sieht so aus:<br />
<pre>set d_ccu rpcserver on</pre><br />
Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [defattr] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
Die Option "defattr" sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden. An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_":<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU2 Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU2 Programmen===<br />
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 CCU2 aktiv oder inaktiv ist.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=22311HMCCU2017-08-23T10:46:09Z<p>Zap: /* Übersicht */</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU2 an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:<br />
<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU2 Systemvariablen<br />
* Ausführen von CCU2 Programmen<br />
* Ausführen von Homematic Scripts auf der CCU2<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)<br />
* HMCCURPC: Alternativer auf Threads basierender RPC-Server<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
{{Hinweis|Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.}}<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.<br />
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.<br />
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.<br />
* Seit der CCU2 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.<br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.<br />
<br />
===Definition I/O Device===<br />
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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 CCU2 registrieren soll. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
===RPC Server konfigurieren===<br />
Nach den Schnittstellen wird festgelegt, ob der interne (Default) oder der externe RPC-Server verwendet werden soll. Der externe RPC-Server (Modul HMCCURPC) hat den Vorteil, dass er deutlich schneller auf CCU Ereignisse reagiert, daher ist diese Variante zu bevorzugen. Der verwendete RPC-Server wird mit dem Attribut ''ccuflags'' festgelegt.<br />
<br />
'''Interner RPC-Server'''<br />
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:<br />
<pre>attr d_ccu ccuflags intrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices<br />
attr d_ccu rpcqueue /tmp/ccuqueue<br />
attr d_ccu rpcinterval 5</pre><br />
<br />
'''Externer RPC-Server'''<br />
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden:<br />
<pre>attr d_ccu ccuflags extrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre><br />
<br />
'''RPC-Server starten'''<br />
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.<br />
<br />
Der eigentliche Startbefehl sieht so aus:<br />
<pre>set d_ccu rpcserver on</pre><br />
Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [defattr] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
Die Option "defattr" sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden. An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_":<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU2 Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU2 Programmen===<br />
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 CCU2 aktiv oder inaktiv ist.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU&diff=22310HMCCU2017-08-23T10:42:42Z<p>Zap: Verweis auf HMCCU Best Practice</p>
<hr />
<div>{{Baustelle}}<br />
{{Infobox Modul<br />
|ModPurpose=Anbindung Homematic CCU2 an FHEM<br />
|ModType=d<br />
|ModCmdRef=HMCCU<br />
|ModForumArea=HomeMatic<br />
|ModTechName=88_HMCCU.pm <br />
|ModOwner=zap ([https://forum.fhem.de/index.php?action=profile;u=10980 Forum] / [[Benutzer Diskussion:Zap|Wiki]])<br />
}}<br />
<br />
==Einführung==<br />
===Übersicht===<br />
Das Modul HMCCU ermöglicht zusammen mit den beiden Client Modulen → [[HMCCUDEV]] und HMCCUCHN eine Integration der Homematic CCU2 Zentrale sowie der dort angelernten Geräte in FHEM. Im Einzelnen werden folgende Funktionen unterstützt:<br />
<br />
* Unterstützung der Protokolle BidCos, Wired und [[HomeMatic IP|HM-IP]]<br />
* Unterstützung von CCU2 Gerätegruppen bzw. virtuellen Geräten (Heizung, Rauchmelder)<br />
* Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server<br />
* Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben<br />
* Lesen und Schreiben von CCU2 Systemvariablen<br />
* Ausführen von CCU2 Programmen<br />
* Ausführen von Homematic Scripts auf der CCU2<br />
<br />
Die einzelnen Module haben folgende Aufgaben:<br />
<br />
* HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)<br />
* HMCCURPC: Alternativer auf Threads basierender RPC-Server<br />
* HMCCUDEV: Definition von FHEM Devices für Homematic Geräte<br />
* HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten<br />
* HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen<br />
<br />
Im Artikel → [[HMCCU Best Practice]] gibt es einige Tipps für den Einstieg inklusive Schritt-für-Schritt Anleitungen.<br />
<br />
===Geräte, Kanäle und Datenpunkte===<br />
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.<br />
<br />
Wenn alle benötigten Datenpunkte eines Gerätes über einen Kanal angesprochen werden können, sollte HMCCUCHN verwendet werden. Mit HMCCUDEV werden alle Kanäle eines Gerätes eingebunden. Außerdem unterstützt HMCCUDEV Rauchmeldergruppen sowie virtuelle Geräte wie z.B. Heizungsgruppen.<br />
<br />
Ein Sonderfall ist der Statuskanal 0, der von allen HomeMatic Geräten bereitgestellt wird. Dieser Kanal ist inklusive seiner Datenpunkte sowohl in HMCCUCHN als auch in HMCCUDEV Devices verfügbar.<br />
<br />
==Inbetriebnahme==<br />
===Zu beachten===<br />
<br />
* In den CCU2 Gerätenamen dürfen keine Umlaute verwendet werden. Leerzeichen sind zulässig, können aber u.U. bei einigen Funktionen zu Problemen führen.<br />
* Namen in der CCU2 müssen über alle Objekttypen hinweg eindeutig sein. Beispiel: Ein Gerät und ein Raum dürfen nicht den gleichen Namen haben.<br />
* Nach dem Neustart der CCU2 muss auch der RPC-Server neu gestartet werden, da die CCU2 bei einem Neustart die registrierten RPC-Server "vergisst".<br />
* Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.<br />
* Seit der CCU2 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).<br />
<br />
===CCU Firewall Einstellungen===<br />
Ab CCU2 Firmware 2.27.7 sind auf der CCU über das WebGUI folgende Einstellungen vorzunehmen:<br />
* Menü "Einstellungen > Systemsteuerung" aufrufen<br />
* Button "Firewall konfigurieren" anklicken<br />
* Die Rechte für "HomeMatic XML-RPC API" und "Remote HomeMatic-Script API" auf "Vollzugriff" setzen.<br />
* 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.<br />
<br />
===Installation===<br />
Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Unter debian/raspian kann das Paket librpc-xml-perl installiert werden<br />
<pre>sudo apt-get update && sudo apt-get install -y librpc-xml-perl</pre><br />
Das RPC-Server Modul HMCCURPC benötigt zusätzlich die Module threads, Thread::Queue sowie Time::HiRes.<br />
<br />
Der interne RPC-Server legt für den Datenaustausch zwischen CCU2 und FHEM Dateien im Verzeichnis /tmp an. Der fhem Prozess benötigt daher Schreibrechte für dieses Verzeichnis. Das Verzeichnis kann mit dem Attribut ''rpcqueue'' geändert werden. Der mit dem Modul HMCCURPC bereitgestellte externe RPC-Server verwendet keine temporären Dateien.<br />
<br />
===Definition I/O Device===<br />
Im ersten Schritt wird ein I/O Device angelegt, das für die Kommunikation zwischen FHEM und der CCU2 verantwortlich ist. Im folgenden Beispiel wird davon ausgegangen, dass die CCU2 unter der IP-Adresse 192.168.1.10 erreichbar ist. Das FHEM Device bekommt den Namen „d_ccu“.<br />
<pre>define d_ccu HMCCU 192.168.1.10</pre><br />
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 CCU2 registrieren soll. Folgende Angaben sind möglich:<br />
* BidCos-RF<br />
* BidCos-Wired<br />
* HmIP-RF<br />
* CUxD<br />
* Homegear<br />
* VirtualDevices<br />
'''Wichtig'''! Die CCU2 stellt außer BidCos-RF nur die Schnittstellen bereit, für die auch Geräte vorhanden sind. Nicht verwendete Schnittstellen dürfen bei ''rpcinterfaces'' nicht angegeben werden, da sonst der RPC-Server nicht startet.<br />
<br />
===RPC Server konfigurieren===<br />
Nach den Schnittstellen wird festgelegt, ob der interne (Default) oder der externe RPC-Server verwendet werden soll. Der externe RPC-Server (Modul HMCCURPC) hat den Vorteil, dass er deutlich schneller auf CCU Ereignisse reagiert, daher ist diese Variante zu bevorzugen. Der verwendete RPC-Server wird mit dem Attribut ''ccuflags'' festgelegt.<br />
<br />
'''Interner RPC-Server'''<br />
Bei Verwendung des internen RPC-Servers kann mit dem Attribut ''rpcqueue'' das Verzeichnis und das Dateipräfix für die Filequeues des RPC-Servers festgelegt werden. Das Attribut ''rpcinterval'' legt fest, wie häufig HMCCU die Filequeues auswertet, d.h. wie schnell Änderungen in der CCU2 in FHEM synchronisiert werden. Im folgenden Beispiel werden vom RPC-Server BidCos-RF, HMIP-RF und CCU Device Groups behandelt. Die Filequeues werden in /tmp mit dem Präfix "ccuqueue" abgelegt und im Abstand von 5 Sekunden abgefragt. Der Wert für ''rpcinterval'' legt die maximale Reaktionszeit auf Änderungen in der CCU bzw. dort angelernter Geräte fest:<br />
<pre>attr d_ccu ccuflags intrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,VirtualDevices<br />
attr d_ccu rpcqueue /tmp/ccuqueue<br />
attr d_ccu rpcinterval 5</pre><br />
<br />
'''Externer RPC-Server'''<br />
Für den externen RPC-Server müssen lediglich die zu verwendenden Schnittstellen festgelegt werden:<br />
<pre>attr d_ccu ccuflags extrpc<br />
attr d_ccu rpcinterfaces BidCos-Wired,BidCos-RF,CUxD,VirtualDevices</pre><br />
<br />
'''RPC-Server starten'''<br />
Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Schnittstelle ein separater fhem.pl Prozess oder Thread mit eigenem Listening-Port gestartet. Beim externen RPC-Server legt HMCCU beim ersten Start ein Device vom Typ HMCCURPC an. Bei aktivierter Firewall müssen die Ports (s. Attribut ''rpcserverport'') geöffnet werden. Beim internen RPC-Server empfangen diese Prozesse Informationen von der CCU2 und schreiben sie in File-Queues im Verzeichnis /tmp. Dort werden sie vom I/O Device abgeholt und an die Client-Devices (HMCCUCHN, HMCCUDEV) verteilt. Beim externen RPC-Server läuft die Kommunikation über Threads und Shared Memory Queues.<br />
<br />
Der eigentliche Startbefehl sieht so aus:<br />
<pre>set d_ccu rpcserver on</pre><br />
Während dem Start des RPC-Servers und der Registrierung bei der CCU2 kann das I/O Device nur eingeschränkt verwendet werden. Dies wird durch den Status „starting/busy“ angezeigt. Nachdem der RPC-Server gestartet wurde, wechselt der Status zu „running/OK“. Zusätzlich werden im Internal RPCPID die Prozess-IDs der RPC-Server Prozesse gespeichert.<br />
Anschließend sollte man noch das Attribut ''rpcserver'' auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:<br />
<pre>attr d_ccu rpcserver on</pre><br />
<br />
===Vorgaben für Client Devices===<br />
Im I/O Device stehen einige Attribute zur Verfügung, über die Vorgaben für Attribute in Client-Devices eingestellt werden können:<br />
{| class="wikitable"<br />
|-<br />
! Attribut in HMCCU !! Vorgabe für Attribut in<br/>HMCCUDEV/HMCCUCHN !! Default !! Bedeutung<br />
|-<br />
| ccudef-hmstatevals || hmstatevals || '^UNREACH!(1|true):unreachable;^LOW_?BAT!(1|true):warn_battery' || Legt fest, wie der HomeMatic Status eines Client-Device ermittelt wird.<br />
|-<br />
| ccudef-readingfilter || ccureadingfilter || .* || Legt fest, welche Datenpunkte eines CCU Gerätes als Readings gespeichert werden<br />
|-<br />
| ccudef-readingname || ccureadingname || Kein Default || Ändert den Namen von Readings und/oder ergänzt neue Readings<br />
|-<br />
| ccudef-substitute || substitute || Kein Default || Ersetzt Datenpunktwerte vor der Speicherung in Readings.<br />
|}<br />
Der Inhalt der HMCCU Attribute wird an die Attribute im Client-Device angehängt. In der Datei HMCCUConf.pm ist ein Default-Template für ein HMCCU Device definiert, das über den Befehl '''set defaults''' für das I/O Device angewendet werden kann. Dabei werden die Attribute ''ccudef-*'' auf Werte gesetzt, die Readings und Werte analog zu CUL_HM erzeugen.<br />
<br />
Wichtig! Bei der Ausführung von '''set defaults''' für das I/O Device wird der Reading-Filter auf den Wert "^(LOW_?BAT|UNREACH)$" gesetzt. Dies hat zur Folge, dass in den Client-Devices nur diese beiden Datenpunkte als Readings gespeichert werden. Daher muss für jedes Client-Device über das lokale Attribut ''ccureadingfilter'' eine Liste der zusätzlich benötigten Datenpunkte definiert werden.<br />
<br />
==Synchronisation mit der CCU==<br />
Das Modul HMCCU bietet Befehle an, um Daten zwischen der CCU und FHEM zu synchronisieren. Der Befehl '''get devicelist''' 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. Gerät oder Kanal wurde umbenannt, neues Gerät wurde angelernt, Gerät wurde gelöscht. Bei der Definition des I/O Device wird der Befehl automatisch ausgeführt.<br />
<br />
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.<br />
<br />
==Autocreate von Client Devices==<br />
HMCCU bietet eine Möglichkeit, um automatisch Client Devices in FHEM für Geräte oder Kanäle in der CCU anzulegen. Dazu wird der Befehl '''get devicelist''' mit folgender Syntax aufgerufen:<br />
<pre>get <io-dev> devicelist create <dev-expr> [Options ...] [defattr] [<attr>=<value [...]]</pre><br />
Der Parameter ''dev-expr'' spezifiziert per regulärem Ausdruck, für welche CCU Geräte oder Kanäle ein Device in FHEM angelegt werden soll. Es ist davon abzuraten, an dieser Stelle ".*" zu verwenden, da so sehr viele (meist unnütze) FHEM Devices angelegt werden.<br />
Folgende ''Options'' sind möglich:<br />
*t={chn|dev|all} - Es werden nur Kanäle (chn) oder Geräte (dev) berücksichtigt (ab 3.6).<br />
*p=<prefix> - Der Text ''prefix'' wird den Namen der neuen FHEM Devices vorangestellt.<br />
*s=<suffix> - Der Text ''suffix'' wird an die Namen der neuen FHEM Devices angehängt.<br />
*f=<format> - Mit ''format'' kann ein Template für die FHEM Devicenamen festgelegt werden. In einem Template können folgende Platzhalter verwendet werden: %n = CCU Geräte- oder Kanalname, %d = CCU Gerätename, %a = CCU Geräte- oder Kanaladresse.<br />
Die Option "defattr" sorgt dafür, dass für die neu definierten FHEM Devices einige Defaultattribute gesetzt werden, sofern für den jeweiligen Gerätetyp vorhanden. An den Befehl kann eine Liste von Atributen angehängt werden, die den neuen FHEM-Devices zugewiesen werden sollen.<br />
<br />
Beispiel: In FHEM Devices für alle CCU Geräte anlegen, deren Namen mit "HM-KL" beginnt. Alle neuen FHEM Devices beginnen mit "HM_":<br />
<pre>get d_ccu devicelist create ^HM-KL.* t=dev f=HM_%n room=Homematic</pre><br />
<br />
==Verwaltung von Default Attributen==<br />
HMCCU bietet für FHEM Devices vom Typ HMCCUCHN und HMCCUDEV bei bestimmten Homamtic Gerätetypen Default Attribute an. Diese können in den Client Devices mit dem Befehl '''set defaults''' definiert werden. Der Befehl '''get defaults''' zeigt die für einen Gerätetyp vorhandenen Attribute an. HMCCU bietet jedem Benutzer die Möglichkeit, zusätzlich zu den in der Datei HMCCUConf.pm mitgelieferten Attribute eigene Vorlagendateien mit Default Attributen zu definieren.<br />
<br />
===Anzeigen der Gerätetypen mit Default Attributen===<br />
Mit dem Befehl '''get defaults''' im I/O Device werden alle Homematic Gerätetypen angezeigt, für die Default Attribute vorhanden sind. Dabei werden auch benutzerdefinierte Attribute berücksichtigt.<br />
<br />
===Default Attribute exportieren und importieren===<br />
Der Befehl '''get exportdefaults''' schreibt die mitgelieferten Default Attribute aus HMCCUConf.pm in eine Vorlagendatei. Diese Datei kann der Benutzer nach seinen Bedürfnissen anpassen und anschließend mit dem Befehl '''set importdefaults''' in FHEM importieren. Das Anlegen von eigenen Default Attributen könnte so aussehen:<br />
<pre><br />
get d_ccu exportdefaults /opt/fhem/hmccu_defattr.txt<br />
<br />
... Datei /opt/fhem/hmccu_defattr.txt editieren ...<br />
<br />
set d_ccu importdefaults /opt/fhem/hmccu_defattr.txt<br />
</pre><br />
Beim Ausführen des Befehls '''set defaults''' in einem Client Device haben die benutzerdefinierten Attribute Priorität.<br />
<br />
===Benutzerdefinierte Attribute löschen===<br />
Mit dem Befehl '''set cleardefaults''' werden alle mit '''set importdefaults''' importierten Default Attribute gelöscht. Danach sind wieder nur die in HMCCUConf.pm enthaltenen Default Attribute verfügbar.<br />
<br />
==Weitere Funktionen des Moduls HMCCU==<br />
===Lesen und Ändern von CCU2 Systemvariablen===<br />
Systemvariablen in der CCU2 können mit den Befehlen '''get vars''' und '''set var''' gelesen und geändert werden. Voraussetzung ist, dass die Variable in der CCU2 vorhanden ist, d.h. es ist nicht möglich, mit dem Befehl '''set var''' eine neue Variable in der CCU2 anzulegen.<br />
Nach dem Auslesen einer Systemvariable wird der Wert in einem Reading im I/O Device gespeichert. Der Befehl '''get vars''' akzeptiert als Parameter einen regulären Ausdruck. Dadurch können mehrere Systemvariablen auf einmal gelesen werden.<br />
<br />
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:<br />
<pre>get d_ccu vars A.*</pre><br />
Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:<br />
<pre>set d_ccu var Temperatur 20.5</pre><br />
<br />
===Ausführen von CCU2 Programmen===<br />
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 CCU2 aktiv oder inaktiv ist.<br />
<br />
Beispiel: Programm mit dem Namen "Schalter_Ein" ausführen:<br />
<pre>set d_ccu execute Schalter_Ein</pre><br />
<br />
===Aggregation von Gerätezuständen (ab 3.6)===<br />
Hinter diesem etwas kryptischen Begriff verbirgt sich die Zusammenfassung von Zuständen von Client-Devices. Anwendungsbeispiele sind:<br />
* Wieviele und welche Geräte haben einen niedrigen Batteriestand?<br />
* Wieviele und welche Fenster sind geöffnet?<br />
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:<br />
*''Präfix''_count = Anzahl der FHEM Devices, die für die Aggregation ausgewertet wurden.<br />
*''Präfix''_list = Liste der FHEM Devices, die der if Bedingung Aggregtaionsregel entsprechen.<br />
*''Präfix''_match - Anzahl der FHEM Devices, die der if Bedingung der Aggregationsregel entsprechen.<br />
*''Präfix''_state - Ergebnis der Aggregationsregel (if oder else Wert).<br />
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:<br />
<pre>get <io-dev> aggregation {all|<name>}</pre><br />
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 ein Zeilenumbruch getrennt. Eine Aggregationsregel enthält mehrere, durch Komma getrennte Parameter, die das Verhalten einer Aggregation festlegen:<br />
*'''name''':<Name> - Legt den Namen einer Aggregation fest.<br />
*'''filter''':{name|alias|group|room|type}=<Incl-Expr>[!<Excl-Expr>] - Legt fest, welche Geräte in die Aggregation einbezogen werden:<br />
**name: FHEM Device Name<br />
**alias: FHEM Device Alias<br />
**group: FHEM Device ''group'' Attribut<br />
**room: FHEM Device ''room'' Attribut<br />
**type: Homematic Gerätetyp<br />
*'''read''':<Read-Expr> - Legt fest, welche Readings für die Aggregation verwendet werden (z.B. state oder LOWBAT).<br />
*'''if''':{any|all}=<Value> - Legt die Bedingung fest, unter der die Aggregationsregel greift:<br />
**any: Regel greift, wenn das Reading mindestens eins der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' hat.<br />
**all: Regel greift, wenn die Readings aller der über ''Filter'' selektierten FHEM Devices den Wert ''Value'' haben.<br />
*'''else''':<Value><br />
*'''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.<br />
*'''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".<br />
<br />
Beispiel: Aggregation der Batteriezustände aller Homematic Geräte in FHEM (Annahme: Alle gehören zum Raum "Homematic"):<br />
<pre><br />
attr d_ccu ccuaggregate name:battery,filter:room=Homematic,read:(LOWBAT|LOW_BAT),if:any=yes,else:no,prefix=battery_,coll:alias<br />
</pre><br />
Diese Aggregationsregel könnte folgende Readings im I/O Device generieren (Annahme: Batterien von 2 Fenstersensoren leer):<br />
<pre><br />
battery_count: 50<br />
battery_list: Fenster Bad,Fenster Wohnzimmer<br />
battery_match: 2<br />
battery_state: yes<br />
</pre><br />
<br />
===Ausführen von Homematic Scripts===<br />
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.<br />
<br />
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl '''get vars'''):<br />
<pre><br />
object osysvar;<br />
string ssysvarid;<br />
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())<br />
{<br />
osysvar = dom.GetObject(ssysvarid);<br />
WriteLine (osysvar.Name() # "=" # osysvar.Value());<br />
}<br />
</pre><br />
<br />
Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:<br />
<br />
<pre>set d_ccu hmscript /opt/fhem/sysvars.scr</pre><br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Best_Practice&diff=22297HMCCU Best Practice2017-08-23T08:05:20Z<p>Zap: /* I/O Device definieren */</p>
<hr />
<div>==I/O Device anlegen==<br />
===I/O Device definieren===<br />
Die Kommunikation zwischen FHEM und einer CCU2 erfolgt über ein Device vom Typ HMCCU. Der folgende Befehl legt ein solches I/O Device an. Dabei wird die IP-Adresse der CCU2 als Parameter angegeben:<br />
<pre>define d_ccu HMCCU 192.168.1.100</pre><br />
<br />
===Attribute setzen===<br />
Zunächst wird der RPC-Server konfiguriert. Im folgenden Beispiel werden BidCos, HM-IP, CUxD und Gerätegruppen (VirtualDevices) berücksichtigt. Es dürfen nur die Schnittstellen angegeben werden, die in der CCU2 auch verwendet werden.<br />
<pre><br />
# Schnittstellen<br />
attr d_ccu rpcinterfaces BidCos-RF,CUxD,HmIP-RF,VirtualDevices<br />
# RPC-Server nach dem Start von FHEM automatisch starten<br />
attr d_ccu rpcserver on<br />
# Status anzeigen<br />
attr d_ccu stateFormat rpcstate/state<br />
# Buttons für das Starten und Stoppen des RPC-Servers anzeigen<br />
attr d_ccu cmdIcon on:general_an off:general_aus<br />
attr d_ccu eventMap /rpcserver on:on/rpcserver off:off/<br />
</pre><br />
<br />
Mit dem Befehl set d_ccu defaults werden weitere Attribute gesetzt, die das Handling von Readings in den später definierten Devices vom Typ HMCCUCHN und HMCCUDEV beeinflussen bzw. vereinfachen. Diese Attribute können natürlich auch einzeln gesetzt werden:<br />
<pre><br />
# Readings LOWBAT, LOW_BAT und UNREACH immer berücksichtigen<br />
attr d_ccu ccudef-readingfilter ^(LOW_?BAT|UNREACH)$<br />
# Readings LOWBAT und LOW_BAT in battery umbenennen, Reading UNREACH in activity umbenennen<br />
attr d_ccu ccudef-readingname ^(.+\.)?LOW_?BAT$:battery;^(.+\.)?UNREACH$:activity<br />
# Werte von Readings durch sprechende Ausdrücke ersetzen<br />
attr d_ccu ccudef-substitute AES_KEY!(0|false):off,(1|true):on;LOWBAT,LOW_BAT!(0|false):ok,(1|true):low;UNREACH!(0|false):alive,(1|true):dead;MOTION!(0|false):noMotion,(1|true):motion;DIRECTION!0:stop,1:up,2:down,3:undefined;WORKING!0:false,1:true;INHIBIT!(0|false):unlocked,(1|true):locked<br />
</pre><br />
<br />
Nun werden noch Aggregationen definiert. Mit dieser Funktion können bestimmte Stati von Homematic Devices im I/O Device als Reading dargestellt werden (z.B. Liste der offenen Fenster, Geräte mit leerer Batterie). Um die Definition der Aggregationen bzw. der Filter einfach zu halten, sollte man sich ein Namensschema überlegen. Die folgenden Aggregationen gehen davon aus, dass alle Homematic Devices in FHEM mit "HM-" beginnen. Danach folgt die Funktion des Gerätes, z.B. KL für Klima und TF für TürFenster. Bei anderer Namensgebung sind die Filterangaben entsprechend anzupassen. Alternativ kann auch der Gerätetyp oder die Gruppe als Filter verwendet werden (s.a. Command Reference zu HMCCU). Das Attribut ''ccuaggregate'' unterstützt mehrzeilige Angaben. Im folgenden Beispiel ist nur der Attributwert angegeben. Eingabe am besten über Auswahl des Attributs ''ccuaggregate'' in der FHEM Oberfläche. Die Kommentarzeilen beginnend mit # weglassen.<br />
<pre><br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und bei denen das Reading battery den Wert low hat<br />
name:battery,filter:name=^HM_.*,read:battery,if:any=low,else:ok,prefix:battery_,coll:comment!Batterien OK;<br />
# Anzeige aller Geräte vom Typ HM-CC-RT-DN oder HM-TC-IT-WM-W-EU, deren Batteriespannung kleiner gleich 2.2 Volt ist<br />
name:voltage,filter:type=(HM-CC-RT-DN|HM-TC-IT-WM-W-EU),read:BATTERY_STATE,if:le=2.2,else:0,prefix:voltage_,coll:comment!Batteriespannung OK;<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt und bei denen das Reading state den Wert open hat<br />
name:lock,filter:name=^HM_TF.*,read:state,if:any=open,else:closed,prefix:lock_,coll:comment!Alle Fenster/Türen geschlossen;<br />
# Anzeige aller Geräte der Gruppe Dachfenster, bei denen das Reading state den Wert open hat<br />
name:lockroof,filter:group=Dachfenster,read:state,if:any=open,else:closed,prefix:lockroof_,coll:comment!Alle Dachfenster geschlossen;<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt aber nicht mit Haustuer endet und bei denen das Reading state den Wert open hat<br />
name:lockwin,filter:name=^HM_TF.*!Haustuer$,read:state,if:any=open,else:closed,prefix:lockwin_,coll:comment!Alle Fenster/Türen geschlossen;<br />
# Anzeige aller Geräte, deren Namen mit HM_KL beginnt und bei denen das Reading HUMIDITY größer gleich 60 ist<br />
name:hummax,filter:name=^HM_KL.*,read:HUMIDITY,if:ge=60,else:0,prefix:hummax_,coll:alias!Luftfeuchte OK;<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und die nicht erreichbar sind<br />
name:unreach,filter:name=^HM_.*,read:activity,if:any=dead,else:alive,prefix:unreach_,coll:comment!Alle Devices erreichbar<br />
</pre><br />
<br />
Mit den folgenden Attributen werden die Aggregations-Readings im I/O Device aktualisiert:<br />
<pre><br />
# Readings schreieben<br />
attr d_ccu ccureadings 1<br />
attr d_ccu event-on-change-reading .*<br />
# Werte auf eine Nachkommastelle abschneiden<br />
attr d_ccu stripnumber 1<br />
</pre><br />
<br />
==Neue Geräte anlernen==<br />
Um ein neues Gerät an die CCU anzulernen und in FHEM zu nutzen, kann man wie folgt vorgehen:<br />
<br />
# Gerät in CCU2 anlernen<br />
# Im WebUI der CCU2 den Menübefehl ''Einstellungen → Geräte'' aufrufen. Das neu angelernte Gerät in der Liste suchen und nacheinander das Gerät selbst sowie die einzelnen Kanäle nach eigenen Wünschen umbenennen. Dabei sind folgende Regeln zu beachten:<br />
#* CCU2 weit Keine Namen doppelt vergeben, z.B. darf ein Raum nicht den gleichen Namen haben wie ein Gerät.<br />
#* Keine Umlaute verwenden.<br />
#* Wenn möglich keine Leerzeichen verwenden (funktioniert zwar, erschwert aber das Handling in FHEM).<br />
# In FHEM für das I/O Device den Befehl '''get devicelist''' ausführen, um das neue Gerät in FHEM bekannt zu machen.<br />
# Für das I/O Device den Befehl get deviceinfo CCU2-Devicename ausführen. Die Ausgabe zeigt die für das Gerät verfügbaren Kanäle und Datenpunkte sowie die möglichen Operationen (R=Read, W=Write, E=Event) an, die ausgeführt werden können. Anhand dieser Informationen kann man entscheiden, ob man im nächsten Schritt besser HMCCUCHN oder HMCCUDEV für die weiteren Definitionen verwendet. Falls sich aus den Namen der Datenpunkte nicht ihr Verwendungszweck ergibt, findet man in der [http://www.eq-3.de/Downloads/eq3/download%20bereich/hm_web_ui_doku/hm_devices_Endkunden.pdf EQ3-Doku] eine detaillierte Beschreibung der Datenpunkte aller Geräte.<br />
# Ein FHEM Device für das neue Gerät und/oder seine Kanäle definieren:<br />
#* Das Modul HMCCUCHN verwenden, wenn lediglich ein Kanal des Geräts in FHEM eingebunden werden soll oder die Kanäle separat verwendet werden sollen (z.B. bei einem 4-fach Aktor).<br />
#* Das Modul HMCCUDEV verwenden, wenn das komplette Gerät mit allen Kanälen in FHEM eingebunden werden soll oder bei Sonderfällen wie Rauchmeldergruppen oder virtuelle Gerätegruppen.<br />
# Für das neue Device in FHEM den Befehl set defaults ausführen, um einige Attribute zu setzen. Hinweis: Default-Attribute sind nicht für alle Gerätetypen verfügbar. Grundsätzlich sollten folgende Attribute gesetzt werden:<br />
#* ccureadingfilter - Einschränkung auf die tatsächlich benötigten Datenpunkte bzw. Readings<br />
#* ccureadingformat - Bessere Lesbarkeit der Readings durch das Format datapoint<br />
#* event-on-change-reading bzw. event-on-update-reading - Wenn ein Schalter oder Taster über Datenpunkte wie PRESSED_xxx verfügt, sollte event-on-update-reading auf ".*" gesetzt werden. Bei allen anderen Geräten event-on-change-reading.<br />
#* statedatapoint - Legt den Kanal und den Datenpunkt fest, über den ein Gerät oder ein Kanal geschaltet wird bzw. dessen Wert in STATE des FHEM Devices übernommen wird. Bei HMCCUCHN Devices wird nur der Datenpunkt angegeben.<br />
#* statevals - Legt sprechende Namen für Schaltzustände fest. Die Angaben hier stehen dann als Set-Befehle zur Verfügung.<br />
#* substitute - Ersetzt Datenpunktwerte durch Texte bevor sie in Readings gespeichert werden<br />
<br />
==Readingnames anpassen==<br />
===Format von Readingnames===<br />
In HMCCUDEV und HMCCUCHN werdent Readingnames aus den Kanalnamen oder den Kanaladressen sowie den Datenpunktnamen gebildet. Das Format der Readingnames kann über das Attribut ''ccureadingformat'' eingestellt werden. Die Vorgabe ist 'datapoint' Die folgende Tabelle enthält eine Übersicht der Formate:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Datenpunktname oder -adresse !! ccureadingformat !! Readingname<br />
|-<br />
| BidCos-RF.1234567:1.STATE || datapoint || 1.STATE<br />
|- <br />
| BidCos-RF.1234567:1.STATE || datapointlc || 1.state<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || name || MeinKanal.1.LEVEL<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || address || 1234567.1.LEVEL<br />
|}<br />
<br />
===Readingnames ändern oder ergänzen===<br />
Mit dem Attribut ''ccureadingname'' können einzelne Readings umbenannt oder neue Readings als Kopie vorhandener Readings hinzugefügt werden. Die Syntax des Attributs sieht wie folgt aus:<br />
<br />
ccureadingname Ausdruck:[+]NewReading[;...]<br />
<br />
Der Parameter ''Ausdruck'' gibt den Teil eines Readingnames an, der ersetzt werden soll. Mit ''NewReading'' wird der Name des zusätzlichen Readings (führendes '+') oder der Ersetzungstext für den vorhandenen Readingname festgelegt. Beispiele:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Readingname alt !! ccureadingname !! Readingname(s) neu<br />
|-<br />
| 1.LEVEL || LEVEL:pct || 1.pct<br />
|- <br />
| 1.LEVEL || [0-9]{1,2}\.LEVEL:pct || pct<br />
|-<br />
| 1.LEVEL || 1.LEVEL:+pct;1.LEVEL:level || pct, level<br />
|-<br />
| 1.LEVEL || 1.LEVEL:pct;1.LEVEL:level || pct<br />
|}<br />
<br />
Wichtig! Die Regeln werden von links nach rechts abgearbeitet. Daher greift die 2. Regel in der letzten Zeile nicht mehr (1.LEVEL wurde zuvor durch pct ersetzt).<br />
<br />
=== Readingnames zusammenfassen===<br />
Mit dem Attribut ''ccureadingname'' können auch mehrere Readings zu einem neuen Reading zusammengefasst werden. Beispiel: Ein Taster liefert je nach Dauer des Tastendrucks im Kanal 1 ein Event PRESS_SHORT oder PRESS_LONG. Normalerweise würden dabei auch zwei Readings "1.PRESS_SHORT" und "1.PRESS_LONG" entstehen. Diese beiden Readings können mit folgendem Befehl in einem Reading PRESSED zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^1.PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
Wenn ein Taster über mehrere Kanäle (hier vier) verfügt, können auch diese zu einem einzigen Reading zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^[1-4].PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
==Readingwerte manipulieren==<br />
===Readingwerte ersetzen===<br />
Mit dem Attribut ''substitute'' können Werte von Readings durch neue Werte bzw. Zeichenketten ersetzt werden. Die Veränderungen können sich auf bestimmte Datenpunkte oder alle Readings eines Devices beziehen. Die zu ersetzenden Werte werden dabei entweder durch reguläre Ausdrücke oder als Nummernbereiche angegeben.<br />
<br />
Im folgenden Beispiel werden die Werte 1 oder true in allen Readings durch "yes" ersetzt, die Werte 0 oder false durch "no":<br />
<br />
<pre>attr mydev substitute (1|true):yes,(0|false):no</pre><br />
<br />
Wenn sich mehrere Ersetzungsregeln auf den gleichen Datenpunkt beziehen oder wie im Beispiel oben für alle Datenpunkte gelten, werden sie einfach durch ein Komma getrennt aneinander gehängt. Eine Ersetzungsregel kann sich auch auf einen bestimmten Datenpunkt beziehen. Im folgenden Beispiel eines Fensterkontakts sollen die Werte des Datenpunktes STATE durch "open" bzw. "closed" ersetzt werden. Der Name des Datenpunktes wird in diesem Fall einfach durch ein Ausrufezeichen getrennt der Regel vorangestellt: <br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Sollte ein Geräte in mehreren Kanälen identische Datenpunkte enthalten, kann dem Datenpunktnamen noch eine Kanalnummer mit einem Punkt vorangestellt werden:<br />
<br />
<pre>attr mydev substitute 1.STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Wenn mehrere Ersetzungsregeln definiert werden sollen, werden sie durch ein Semikolon getrennt. Im folgenden Beispiel sollen die Werte der Datenpunkte STATE und LOWBAT unterschiedlich interpretiert werden:<br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed;LOWBAT!(1|true):low,(0|false):ok</pre><br />
<br />
Bei Datenpunkten mit numerischen Werten wie z.B. dem Level eines Rollladenaktors kann es sinnvoll sein, Werte oder Wertebereiche zu ersetzen. Im folgenden Beispiel kann der Datenpunkt LEVEL Werte von 0-100 annehmen. Der Wert 0 soll als "closed" und der Wert 100 als "open" dargestellt werden. Alle anderen Werte als "partial":<br />
<br />
<pre>attr mydev substitute LEVEL!#0-0:closed,#1-99:partial,#100-100:open</pre><br />
<br />
Zu ersetzende Nummernbereiche beginnen also immer mit einem #. Es müssen immer Bereiche angegeben werden. Eine einzelne Zahl ist nicht zulässig.<br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Best_Practice&diff=22296HMCCU Best Practice2017-08-23T08:00:29Z<p>Zap: </p>
<hr />
<div>==I/O Device anlegen==<br />
===I/O Device definieren===<br />
Die Kommunikation zwischen FHEM und einer CCU2 erfolgt über ein Device vom Typ HMCCU. Der folgende Befehl legt ein solches I/O Device an. Dabei wird die IP-Adresse der CCU2 als Parameter angegeben:<br />
<pre>defined d_ccu HMCCU 192.168.1.100</pre><br />
<br />
===Attribute setzen===<br />
Zunächst wird der RPC-Server konfiguriert. Im folgenden Beispiel werden BidCos, HM-IP, CUxD und Gerätegruppen (VirtualDevices) berücksichtigt. Es dürfen nur die Schnittstellen angegeben werden, die in der CCU2 auch verwendet werden.<br />
<pre><br />
# Schnittstellen<br />
attr d_ccu rpcinterfaces BidCos-RF,CUxD,HmIP-RF,VirtualDevices<br />
# RPC-Server nach dem Start von FHEM automatisch starten<br />
attr d_ccu rpcserver on<br />
# Status anzeigen<br />
attr d_ccu stateFormat rpcstate/state<br />
# Buttons für das Starten und Stoppen des RPC-Servers anzeigen<br />
attr d_ccu cmdIcon on:general_an off:general_aus<br />
attr d_ccu eventMap /rpcserver on:on/rpcserver off:off/<br />
</pre><br />
<br />
Mit dem Befehl set d_ccu defaults werden weitere Attribute gesetzt, die das Handling von Readings in den später definierten Devices vom Typ HMCCUCHN und HMCCUDEV beeinflussen bzw. vereinfachen. Diese Attribute können natürlich auch einzeln gesetzt werden:<br />
<pre><br />
# Readings LOWBAT, LOW_BAT und UNREACH immer berücksichtigen<br />
attr d_ccu ccudef-readingfilter ^(LOW_?BAT|UNREACH)$<br />
# Readings LOWBAT und LOW_BAT in battery umbenennen, Reading UNREACH in activity umbenennen<br />
attr d_ccu ccudef-readingname ^(.+\.)?LOW_?BAT$:battery;^(.+\.)?UNREACH$:activity<br />
# Werte von Readings durch sprechende Ausdrücke ersetzen<br />
attr d_ccu ccudef-substitute AES_KEY!(0|false):off,(1|true):on;LOWBAT,LOW_BAT!(0|false):ok,(1|true):low;UNREACH!(0|false):alive,(1|true):dead;MOTION!(0|false):noMotion,(1|true):motion;DIRECTION!0:stop,1:up,2:down,3:undefined;WORKING!0:false,1:true;INHIBIT!(0|false):unlocked,(1|true):locked<br />
</pre><br />
<br />
Nun werden noch Aggregationen definiert. Mit dieser Funktion können bestimmte Stati von Homematic Devices im I/O Device als Reading dargestellt werden (z.B. Liste der offenen Fenster, Geräte mit leerer Batterie). Um die Definition der Aggregationen bzw. der Filter einfach zu halten, sollte man sich ein Namensschema überlegen. Die folgenden Aggregationen gehen davon aus, dass alle Homematic Devices in FHEM mit "HM-" beginnen. Danach folgt die Funktion des Gerätes, z.B. KL für Klima und TF für TürFenster. Bei anderer Namensgebung sind die Filterangaben entsprechend anzupassen. Alternativ kann auch der Gerätetyp oder die Gruppe als Filter verwendet werden (s.a. Command Reference zu HMCCU). Das Attribut ''ccuaggregate'' unterstützt mehrzeilige Angaben. Im folgenden Beispiel ist nur der Attributwert angegeben. Eingabe am besten über Auswahl des Attributs ''ccuaggregate'' in der FHEM Oberfläche. Die Kommentarzeilen beginnend mit # weglassen.<br />
<pre><br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und bei denen das Reading battery den Wert low hat<br />
name:battery,filter:name=^HM_.*,read:battery,if:any=low,else:ok,prefix:battery_,coll:comment!Batterien OK;<br />
# Anzeige aller Geräte vom Typ HM-CC-RT-DN oder HM-TC-IT-WM-W-EU, deren Batteriespannung kleiner gleich 2.2 Volt ist<br />
name:voltage,filter:type=(HM-CC-RT-DN|HM-TC-IT-WM-W-EU),read:BATTERY_STATE,if:le=2.2,else:0,prefix:voltage_,coll:comment!Batteriespannung OK;<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt und bei denen das Reading state den Wert open hat<br />
name:lock,filter:name=^HM_TF.*,read:state,if:any=open,else:closed,prefix:lock_,coll:comment!Alle Fenster/Türen geschlossen;<br />
# Anzeige aller Geräte der Gruppe Dachfenster, bei denen das Reading state den Wert open hat<br />
name:lockroof,filter:group=Dachfenster,read:state,if:any=open,else:closed,prefix:lockroof_,coll:comment!Alle Dachfenster geschlossen;<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt aber nicht mit Haustuer endet und bei denen das Reading state den Wert open hat<br />
name:lockwin,filter:name=^HM_TF.*!Haustuer$,read:state,if:any=open,else:closed,prefix:lockwin_,coll:comment!Alle Fenster/Türen geschlossen;<br />
# Anzeige aller Geräte, deren Namen mit HM_KL beginnt und bei denen das Reading HUMIDITY größer gleich 60 ist<br />
name:hummax,filter:name=^HM_KL.*,read:HUMIDITY,if:ge=60,else:0,prefix:hummax_,coll:alias!Luftfeuchte OK;<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und die nicht erreichbar sind<br />
name:unreach,filter:name=^HM_.*,read:activity,if:any=dead,else:alive,prefix:unreach_,coll:comment!Alle Devices erreichbar<br />
</pre><br />
<br />
Mit den folgenden Attributen werden die Aggregations-Readings im I/O Device aktualisiert:<br />
<pre><br />
# Readings schreieben<br />
attr d_ccu ccureadings 1<br />
attr d_ccu event-on-change-reading .*<br />
# Werte auf eine Nachkommastelle abschneiden<br />
attr d_ccu stripnumber 1<br />
</pre><br />
<br />
==Neue Geräte anlernen==<br />
Um ein neues Gerät an die CCU anzulernen und in FHEM zu nutzen, kann man wie folgt vorgehen:<br />
<br />
# Gerät in CCU2 anlernen<br />
# Im WebUI der CCU2 den Menübefehl ''Einstellungen → Geräte'' aufrufen. Das neu angelernte Gerät in der Liste suchen und nacheinander das Gerät selbst sowie die einzelnen Kanäle nach eigenen Wünschen umbenennen. Dabei sind folgende Regeln zu beachten:<br />
#* CCU2 weit Keine Namen doppelt vergeben, z.B. darf ein Raum nicht den gleichen Namen haben wie ein Gerät.<br />
#* Keine Umlaute verwenden.<br />
#* Wenn möglich keine Leerzeichen verwenden (funktioniert zwar, erschwert aber das Handling in FHEM).<br />
# In FHEM für das I/O Device den Befehl '''get devicelist''' ausführen, um das neue Gerät in FHEM bekannt zu machen.<br />
# Für das I/O Device den Befehl get deviceinfo CCU2-Devicename ausführen. Die Ausgabe zeigt die für das Gerät verfügbaren Kanäle und Datenpunkte sowie die möglichen Operationen (R=Read, W=Write, E=Event) an, die ausgeführt werden können. Anhand dieser Informationen kann man entscheiden, ob man im nächsten Schritt besser HMCCUCHN oder HMCCUDEV für die weiteren Definitionen verwendet. Falls sich aus den Namen der Datenpunkte nicht ihr Verwendungszweck ergibt, findet man in der [http://www.eq-3.de/Downloads/eq3/download%20bereich/hm_web_ui_doku/hm_devices_Endkunden.pdf EQ3-Doku] eine detaillierte Beschreibung der Datenpunkte aller Geräte.<br />
# Ein FHEM Device für das neue Gerät und/oder seine Kanäle definieren:<br />
#* Das Modul HMCCUCHN verwenden, wenn lediglich ein Kanal des Geräts in FHEM eingebunden werden soll oder die Kanäle separat verwendet werden sollen (z.B. bei einem 4-fach Aktor).<br />
#* Das Modul HMCCUDEV verwenden, wenn das komplette Gerät mit allen Kanälen in FHEM eingebunden werden soll oder bei Sonderfällen wie Rauchmeldergruppen oder virtuelle Gerätegruppen.<br />
# Für das neue Device in FHEM den Befehl set defaults ausführen, um einige Attribute zu setzen. Hinweis: Default-Attribute sind nicht für alle Gerätetypen verfügbar. Grundsätzlich sollten folgende Attribute gesetzt werden:<br />
#* ccureadingfilter - Einschränkung auf die tatsächlich benötigten Datenpunkte bzw. Readings<br />
#* ccureadingformat - Bessere Lesbarkeit der Readings durch das Format datapoint<br />
#* event-on-change-reading bzw. event-on-update-reading - Wenn ein Schalter oder Taster über Datenpunkte wie PRESSED_xxx verfügt, sollte event-on-update-reading auf ".*" gesetzt werden. Bei allen anderen Geräten event-on-change-reading.<br />
#* statedatapoint - Legt den Kanal und den Datenpunkt fest, über den ein Gerät oder ein Kanal geschaltet wird bzw. dessen Wert in STATE des FHEM Devices übernommen wird. Bei HMCCUCHN Devices wird nur der Datenpunkt angegeben.<br />
#* statevals - Legt sprechende Namen für Schaltzustände fest. Die Angaben hier stehen dann als Set-Befehle zur Verfügung.<br />
#* substitute - Ersetzt Datenpunktwerte durch Texte bevor sie in Readings gespeichert werden<br />
<br />
==Readingnames anpassen==<br />
===Format von Readingnames===<br />
In HMCCUDEV und HMCCUCHN werdent Readingnames aus den Kanalnamen oder den Kanaladressen sowie den Datenpunktnamen gebildet. Das Format der Readingnames kann über das Attribut ''ccureadingformat'' eingestellt werden. Die Vorgabe ist 'datapoint' Die folgende Tabelle enthält eine Übersicht der Formate:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Datenpunktname oder -adresse !! ccureadingformat !! Readingname<br />
|-<br />
| BidCos-RF.1234567:1.STATE || datapoint || 1.STATE<br />
|- <br />
| BidCos-RF.1234567:1.STATE || datapointlc || 1.state<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || name || MeinKanal.1.LEVEL<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || address || 1234567.1.LEVEL<br />
|}<br />
<br />
===Readingnames ändern oder ergänzen===<br />
Mit dem Attribut ''ccureadingname'' können einzelne Readings umbenannt oder neue Readings als Kopie vorhandener Readings hinzugefügt werden. Die Syntax des Attributs sieht wie folgt aus:<br />
<br />
ccureadingname Ausdruck:[+]NewReading[;...]<br />
<br />
Der Parameter ''Ausdruck'' gibt den Teil eines Readingnames an, der ersetzt werden soll. Mit ''NewReading'' wird der Name des zusätzlichen Readings (führendes '+') oder der Ersetzungstext für den vorhandenen Readingname festgelegt. Beispiele:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Readingname alt !! ccureadingname !! Readingname(s) neu<br />
|-<br />
| 1.LEVEL || LEVEL:pct || 1.pct<br />
|- <br />
| 1.LEVEL || [0-9]{1,2}\.LEVEL:pct || pct<br />
|-<br />
| 1.LEVEL || 1.LEVEL:+pct;1.LEVEL:level || pct, level<br />
|-<br />
| 1.LEVEL || 1.LEVEL:pct;1.LEVEL:level || pct<br />
|}<br />
<br />
Wichtig! Die Regeln werden von links nach rechts abgearbeitet. Daher greift die 2. Regel in der letzten Zeile nicht mehr (1.LEVEL wurde zuvor durch pct ersetzt).<br />
<br />
=== Readingnames zusammenfassen===<br />
Mit dem Attribut ''ccureadingname'' können auch mehrere Readings zu einem neuen Reading zusammengefasst werden. Beispiel: Ein Taster liefert je nach Dauer des Tastendrucks im Kanal 1 ein Event PRESS_SHORT oder PRESS_LONG. Normalerweise würden dabei auch zwei Readings "1.PRESS_SHORT" und "1.PRESS_LONG" entstehen. Diese beiden Readings können mit folgendem Befehl in einem Reading PRESSED zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^1.PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
Wenn ein Taster über mehrere Kanäle (hier vier) verfügt, können auch diese zu einem einzigen Reading zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^[1-4].PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
==Readingwerte manipulieren==<br />
===Readingwerte ersetzen===<br />
Mit dem Attribut ''substitute'' können Werte von Readings durch neue Werte bzw. Zeichenketten ersetzt werden. Die Veränderungen können sich auf bestimmte Datenpunkte oder alle Readings eines Devices beziehen. Die zu ersetzenden Werte werden dabei entweder durch reguläre Ausdrücke oder als Nummernbereiche angegeben.<br />
<br />
Im folgenden Beispiel werden die Werte 1 oder true in allen Readings durch "yes" ersetzt, die Werte 0 oder false durch "no":<br />
<br />
<pre>attr mydev substitute (1|true):yes,(0|false):no</pre><br />
<br />
Wenn sich mehrere Ersetzungsregeln auf den gleichen Datenpunkt beziehen oder wie im Beispiel oben für alle Datenpunkte gelten, werden sie einfach durch ein Komma getrennt aneinander gehängt. Eine Ersetzungsregel kann sich auch auf einen bestimmten Datenpunkt beziehen. Im folgenden Beispiel eines Fensterkontakts sollen die Werte des Datenpunktes STATE durch "open" bzw. "closed" ersetzt werden. Der Name des Datenpunktes wird in diesem Fall einfach durch ein Ausrufezeichen getrennt der Regel vorangestellt: <br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Sollte ein Geräte in mehreren Kanälen identische Datenpunkte enthalten, kann dem Datenpunktnamen noch eine Kanalnummer mit einem Punkt vorangestellt werden:<br />
<br />
<pre>attr mydev substitute 1.STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Wenn mehrere Ersetzungsregeln definiert werden sollen, werden sie durch ein Semikolon getrennt. Im folgenden Beispiel sollen die Werte der Datenpunkte STATE und LOWBAT unterschiedlich interpretiert werden:<br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed;LOWBAT!(1|true):low,(0|false):ok</pre><br />
<br />
Bei Datenpunkten mit numerischen Werten wie z.B. dem Level eines Rollladenaktors kann es sinnvoll sein, Werte oder Wertebereiche zu ersetzen. Im folgenden Beispiel kann der Datenpunkt LEVEL Werte von 0-100 annehmen. Der Wert 0 soll als "closed" und der Wert 100 als "open" dargestellt werden. Alle anderen Werte als "partial":<br />
<br />
<pre>attr mydev substitute LEVEL!#0-0:closed,#1-99:partial,#100-100:open</pre><br />
<br />
Zu ersetzende Nummernbereiche beginnen also immer mit einem #. Es müssen immer Bereiche angegeben werden. Eine einzelne Zahl ist nicht zulässig.<br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zaphttp://wiki.fhem.de/w/index.php?title=HMCCU_Best_Practice&diff=22295HMCCU Best Practice2017-08-23T07:59:33Z<p>Zap: Beschreibung Einrichtung I/O Device</p>
<hr />
<div>==I/O Device anlegen==<br />
===I/O Device definieren==<br />
Die Kommunikation zwischen FHEM und einer CCU2 erfolgt über ein Device vom Typ HMCCU. Der folgende Befehl legt ein solches I/O Device an. Dabei wird die IP-Adresse der CCU2 als Parameter angegeben:<br />
<pre>defined d_ccu HMCCU 192.168.1.100</pre><br />
<br />
===Attribute setzen===<br />
Zunächst wird der RPC-Server konfiguriert. Im folgenden Beispiel werden BidCos, HM-IP, CUxD und Gerätegruppen (VirtualDevices) berücksichtigt. Es dürfen nur die Schnittstellen angegeben werden, die in der CCU2 auch verwendet werden.<br />
<pre><br />
# Schnittstellen<br />
attr d_ccu rpcinterfaces BidCos-RF,CUxD,HmIP-RF,VirtualDevices<br />
# RPC-Server nach dem Start von FHEM automatisch starten<br />
attr d_ccu rpcserver on<br />
# Status anzeigen<br />
attr d_ccu stateFormat rpcstate/state<br />
# Buttons für das Starten und Stoppen des RPC-Servers anzeigen<br />
attr d_ccu cmdIcon on:general_an off:general_aus<br />
attr d_ccu eventMap /rpcserver on:on/rpcserver off:off/<br />
</pre><br />
<br />
Mit dem Befehl set d_ccu defaults werden weitere Attribute gesetzt, die das Handling von Readings in den später definierten Devices vom Typ HMCCUCHN und HMCCUDEV beeinflussen bzw. vereinfachen. Diese Attribute können natürlich auch einzeln gesetzt werden:<br />
<pre><br />
# Readings LOWBAT, LOW_BAT und UNREACH immer berücksichtigen<br />
attr d_ccu ccudef-readingfilter ^(LOW_?BAT|UNREACH)$<br />
# Readings LOWBAT und LOW_BAT in battery umbenennen, Reading UNREACH in activity umbenennen<br />
attr d_ccu ccudef-readingname ^(.+\.)?LOW_?BAT$:battery;^(.+\.)?UNREACH$:activity<br />
# Werte von Readings durch sprechende Ausdrücke ersetzen<br />
attr d_ccu ccudef-substitute AES_KEY!(0|false):off,(1|true):on;LOWBAT,LOW_BAT!(0|false):ok,(1|true):low;UNREACH!(0|false):alive,(1|true):dead;MOTION!(0|false):noMotion,(1|true):motion;DIRECTION!0:stop,1:up,2:down,3:undefined;WORKING!0:false,1:true;INHIBIT!(0|false):unlocked,(1|true):locked<br />
</pre><br />
<br />
Nun werden noch Aggregationen definiert. Mit dieser Funktion können bestimmte Stati von Homematic Devices im I/O Device als Reading dargestellt werden (z.B. Liste der offenen Fenster, Geräte mit leerer Batterie). Um die Definition der Aggregationen bzw. der Filter einfach zu halten, sollte man sich ein Namensschema überlegen. Die folgenden Aggregationen gehen davon aus, dass alle Homematic Devices in FHEM mit "HM-" beginnen. Danach folgt die Funktion des Gerätes, z.B. KL für Klima und TF für TürFenster. Bei anderer Namensgebung sind die Filterangaben entsprechend anzupassen. Alternativ kann auch der Gerätetyp oder die Gruppe als Filter verwendet werden (s.a. Command Reference zu HMCCU). Das Attribut ''ccuaggregate'' unterstützt mehrzeilige Angaben. Im folgenden Beispiel ist nur der Attributwert angegeben. Eingabe am besten über Auswahl des Attributs ''ccuaggregate'' in der FHEM Oberfläche. Die Kommentarzeilen beginnend mit # weglassen.<br />
<pre><br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und bei denen das Reading battery den Wert low hat<br />
name:battery,filter:name=^HM_.*,read:battery,if:any=low,else:ok,prefix:battery_,coll:comment!Batterien OK;<br />
# Anzeige aller Geräte vom Typ HM-CC-RT-DN oder HM-TC-IT-WM-W-EU, deren Batteriespannung kleiner gleich 2.2 Volt ist<br />
name:voltage,filter:type=(HM-CC-RT-DN|HM-TC-IT-WM-W-EU),read:BATTERY_STATE,if:le=2.2,else:0,prefix:voltage_,coll:comment!Batteriespannung OK;<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt und bei denen das Reading state den Wert open hat<br />
name:lock,filter:name=^HM_TF.*,read:state,if:any=open,else:closed,prefix:lock_,coll:comment!Alle Fenster/Türen geschlossen;<br />
# Anzeige aller Geräte der Gruppe Dachfenster, bei denen das Reading state den Wert open hat<br />
name:lockroof,filter:group=Dachfenster,read:state,if:any=open,else:closed,prefix:lockroof_,coll:comment!Alle Dachfenster geschlossen;<br />
# Anzeige aller Geräte, deren Namen mit HM_TF beginnt aber nicht mit Haustuer endet und bei denen das Reading state den Wert open hat<br />
name:lockwin,filter:name=^HM_TF.*!Haustuer$,read:state,if:any=open,else:closed,prefix:lockwin_,coll:comment!Alle Fenster/Türen geschlossen;<br />
# Anzeige aller Geräte, deren Namen mit HM_KL beginnt und bei denen das Reading HUMIDITY größer gleich 60 ist<br />
name:hummax,filter:name=^HM_KL.*,read:HUMIDITY,if:ge=60,else:0,prefix:hummax_,coll:alias!Luftfeuchte OK;<br />
# Anzeige aller Geräte, deren Namen mit HM_ beginnt und die nicht erreichbar sind<br />
name:unreach,filter:name=^HM_.*,read:activity,if:any=dead,else:alive,prefix:unreach_,coll:comment!Alle Devices erreichbar<br />
</pre><br />
<br />
Mit den folgenden Attributen werden die Aggregations-Readings im I/O Device aktualisiert:<br />
<pre><br />
# Readings schreieben<br />
attr d_ccu ccureadings 1<br />
attr d_ccu event-on-change-reading .*<br />
# Werte auf eine Nachkommastelle abschneiden<br />
attr d_ccu stripnumber 1<br />
</pre><br />
<br />
==Neue Geräte anlernen==<br />
Um ein neues Gerät an die CCU anzulernen und in FHEM zu nutzen, kann man wie folgt vorgehen:<br />
<br />
# Gerät in CCU2 anlernen<br />
# Im WebUI der CCU2 den Menübefehl ''Einstellungen → Geräte'' aufrufen. Das neu angelernte Gerät in der Liste suchen und nacheinander das Gerät selbst sowie die einzelnen Kanäle nach eigenen Wünschen umbenennen. Dabei sind folgende Regeln zu beachten:<br />
#* CCU2 weit Keine Namen doppelt vergeben, z.B. darf ein Raum nicht den gleichen Namen haben wie ein Gerät.<br />
#* Keine Umlaute verwenden.<br />
#* Wenn möglich keine Leerzeichen verwenden (funktioniert zwar, erschwert aber das Handling in FHEM).<br />
# In FHEM für das I/O Device den Befehl '''get devicelist''' ausführen, um das neue Gerät in FHEM bekannt zu machen.<br />
# Für das I/O Device den Befehl get deviceinfo CCU2-Devicename ausführen. Die Ausgabe zeigt die für das Gerät verfügbaren Kanäle und Datenpunkte sowie die möglichen Operationen (R=Read, W=Write, E=Event) an, die ausgeführt werden können. Anhand dieser Informationen kann man entscheiden, ob man im nächsten Schritt besser HMCCUCHN oder HMCCUDEV für die weiteren Definitionen verwendet. Falls sich aus den Namen der Datenpunkte nicht ihr Verwendungszweck ergibt, findet man in der [http://www.eq-3.de/Downloads/eq3/download%20bereich/hm_web_ui_doku/hm_devices_Endkunden.pdf EQ3-Doku] eine detaillierte Beschreibung der Datenpunkte aller Geräte.<br />
# Ein FHEM Device für das neue Gerät und/oder seine Kanäle definieren:<br />
#* Das Modul HMCCUCHN verwenden, wenn lediglich ein Kanal des Geräts in FHEM eingebunden werden soll oder die Kanäle separat verwendet werden sollen (z.B. bei einem 4-fach Aktor).<br />
#* Das Modul HMCCUDEV verwenden, wenn das komplette Gerät mit allen Kanälen in FHEM eingebunden werden soll oder bei Sonderfällen wie Rauchmeldergruppen oder virtuelle Gerätegruppen.<br />
# Für das neue Device in FHEM den Befehl set defaults ausführen, um einige Attribute zu setzen. Hinweis: Default-Attribute sind nicht für alle Gerätetypen verfügbar. Grundsätzlich sollten folgende Attribute gesetzt werden:<br />
#* ccureadingfilter - Einschränkung auf die tatsächlich benötigten Datenpunkte bzw. Readings<br />
#* ccureadingformat - Bessere Lesbarkeit der Readings durch das Format datapoint<br />
#* event-on-change-reading bzw. event-on-update-reading - Wenn ein Schalter oder Taster über Datenpunkte wie PRESSED_xxx verfügt, sollte event-on-update-reading auf ".*" gesetzt werden. Bei allen anderen Geräten event-on-change-reading.<br />
#* statedatapoint - Legt den Kanal und den Datenpunkt fest, über den ein Gerät oder ein Kanal geschaltet wird bzw. dessen Wert in STATE des FHEM Devices übernommen wird. Bei HMCCUCHN Devices wird nur der Datenpunkt angegeben.<br />
#* statevals - Legt sprechende Namen für Schaltzustände fest. Die Angaben hier stehen dann als Set-Befehle zur Verfügung.<br />
#* substitute - Ersetzt Datenpunktwerte durch Texte bevor sie in Readings gespeichert werden<br />
<br />
==Readingnames anpassen==<br />
===Format von Readingnames===<br />
In HMCCUDEV und HMCCUCHN werdent Readingnames aus den Kanalnamen oder den Kanaladressen sowie den Datenpunktnamen gebildet. Das Format der Readingnames kann über das Attribut ''ccureadingformat'' eingestellt werden. Die Vorgabe ist 'datapoint' Die folgende Tabelle enthält eine Übersicht der Formate:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Datenpunktname oder -adresse !! ccureadingformat !! Readingname<br />
|-<br />
| BidCos-RF.1234567:1.STATE || datapoint || 1.STATE<br />
|- <br />
| BidCos-RF.1234567:1.STATE || datapointlc || 1.state<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || name || MeinKanal.1.LEVEL<br />
|-<br />
| BidCos-RF.1234567:1.LEVEL || address || 1234567.1.LEVEL<br />
|}<br />
<br />
===Readingnames ändern oder ergänzen===<br />
Mit dem Attribut ''ccureadingname'' können einzelne Readings umbenannt oder neue Readings als Kopie vorhandener Readings hinzugefügt werden. Die Syntax des Attributs sieht wie folgt aus:<br />
<br />
ccureadingname Ausdruck:[+]NewReading[;...]<br />
<br />
Der Parameter ''Ausdruck'' gibt den Teil eines Readingnames an, der ersetzt werden soll. Mit ''NewReading'' wird der Name des zusätzlichen Readings (führendes '+') oder der Ersetzungstext für den vorhandenen Readingname festgelegt. Beispiele:<br />
<br />
{| class="wikitable"<br />
|-<br />
! Readingname alt !! ccureadingname !! Readingname(s) neu<br />
|-<br />
| 1.LEVEL || LEVEL:pct || 1.pct<br />
|- <br />
| 1.LEVEL || [0-9]{1,2}\.LEVEL:pct || pct<br />
|-<br />
| 1.LEVEL || 1.LEVEL:+pct;1.LEVEL:level || pct, level<br />
|-<br />
| 1.LEVEL || 1.LEVEL:pct;1.LEVEL:level || pct<br />
|}<br />
<br />
Wichtig! Die Regeln werden von links nach rechts abgearbeitet. Daher greift die 2. Regel in der letzten Zeile nicht mehr (1.LEVEL wurde zuvor durch pct ersetzt).<br />
<br />
=== Readingnames zusammenfassen===<br />
Mit dem Attribut ''ccureadingname'' können auch mehrere Readings zu einem neuen Reading zusammengefasst werden. Beispiel: Ein Taster liefert je nach Dauer des Tastendrucks im Kanal 1 ein Event PRESS_SHORT oder PRESS_LONG. Normalerweise würden dabei auch zwei Readings "1.PRESS_SHORT" und "1.PRESS_LONG" entstehen. Diese beiden Readings können mit folgendem Befehl in einem Reading PRESSED zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^1.PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
Wenn ein Taster über mehrere Kanäle (hier vier) verfügt, können auch diese zu einem einzigen Reading zusammengefasst werden:<br />
<br />
<pre>attr mydev ccureadingname ^[1-4].PRESS_(SHORT|LONG)$:PRESSED</pre><br />
<br />
==Readingwerte manipulieren==<br />
===Readingwerte ersetzen===<br />
Mit dem Attribut ''substitute'' können Werte von Readings durch neue Werte bzw. Zeichenketten ersetzt werden. Die Veränderungen können sich auf bestimmte Datenpunkte oder alle Readings eines Devices beziehen. Die zu ersetzenden Werte werden dabei entweder durch reguläre Ausdrücke oder als Nummernbereiche angegeben.<br />
<br />
Im folgenden Beispiel werden die Werte 1 oder true in allen Readings durch "yes" ersetzt, die Werte 0 oder false durch "no":<br />
<br />
<pre>attr mydev substitute (1|true):yes,(0|false):no</pre><br />
<br />
Wenn sich mehrere Ersetzungsregeln auf den gleichen Datenpunkt beziehen oder wie im Beispiel oben für alle Datenpunkte gelten, werden sie einfach durch ein Komma getrennt aneinander gehängt. Eine Ersetzungsregel kann sich auch auf einen bestimmten Datenpunkt beziehen. Im folgenden Beispiel eines Fensterkontakts sollen die Werte des Datenpunktes STATE durch "open" bzw. "closed" ersetzt werden. Der Name des Datenpunktes wird in diesem Fall einfach durch ein Ausrufezeichen getrennt der Regel vorangestellt: <br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Sollte ein Geräte in mehreren Kanälen identische Datenpunkte enthalten, kann dem Datenpunktnamen noch eine Kanalnummer mit einem Punkt vorangestellt werden:<br />
<br />
<pre>attr mydev substitute 1.STATE!(1|true):open,(0|false):closed</pre><br />
<br />
Wenn mehrere Ersetzungsregeln definiert werden sollen, werden sie durch ein Semikolon getrennt. Im folgenden Beispiel sollen die Werte der Datenpunkte STATE und LOWBAT unterschiedlich interpretiert werden:<br />
<br />
<pre>attr mydev substitute STATE!(1|true):open,(0|false):closed;LOWBAT!(1|true):low,(0|false):ok</pre><br />
<br />
Bei Datenpunkten mit numerischen Werten wie z.B. dem Level eines Rollladenaktors kann es sinnvoll sein, Werte oder Wertebereiche zu ersetzen. Im folgenden Beispiel kann der Datenpunkt LEVEL Werte von 0-100 annehmen. Der Wert 0 soll als "closed" und der Wert 100 als "open" dargestellt werden. Alle anderen Werte als "partial":<br />
<br />
<pre>attr mydev substitute LEVEL!#0-0:closed,#1-99:partial,#100-100:open</pre><br />
<br />
Zu ersetzende Nummernbereiche beginnen also immer mit einem #. Es müssen immer Bereiche angegeben werden. Eine einzelne Zahl ist nicht zulässig.<br />
<br />
[[Kategorie:HomeMatic Components]]</div>Zap