Übersicht

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:

Unterstützung der Protokolle BidCos, Wired und HM-IP
Unterstützung von CCU2 Gerätegruppen (Heizung, Rauchmelder)
Automatische Aktualisierung von Gerätezuständen in FHEM per RPC-Server
Automatische Konvertierung und Skalierung von Werten beim Lesen und Schreiben
Lesen und Schreiben von CCU2 Systemvariablen
Ausführen von CCU2 Programmen
Ausführen von Homematic Scripts auf der CCU2

Die einzelnen Module haben folgende Aufgaben:

HMCCU: Kommunikation zwischen FHEM und CCU2 (I/O Device)
HMCCUDEV: Definition von FHEM Devices für Homematic Geräte
HMCCUCHN: Definition von FHEM Devices für einzelne Kanäle von Homematic Geräten
HMCCUConf: Templates mit Default Attributen für bestimmte Homematic Gerätetypen

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 virtuelle Geräte wie z.B. Heizungsgruppen.

Inbetriebnahme

Zu beachten

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.
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.
Vor der Ausführung eines FHEM Updates oder vor der Installation eines CCU2 Firmware Updates muss der RPC-Server gestoppt werden.

Installation

Alle HMCCU Module sind Teil von FHEM. HMCCU benötigt die Perl Module RPC::XML::Server und RPC::XML::Client. Der 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.

Definition I/O Device

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“.

define d_ccu HMCCU 192.168.1.10

Im nächsten Schritt wird der RPC-Server konfiguriert und gestartet. Zunächst werden mit dem Attribut rpcport die Schnittstellen bzw. Ports festgelegt, für die sich der RPC-Server bei der CCU2 registrieren soll. Dabei gilt folgende Zuordnung:

2000 = Wired
2001 = BidCos-RF
2010 = HMIP-RF
9292 = CCU Device Groups

Optional kann mit dem Attribut rpcqueue das Verzeichnis 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:

attr d_ccu rpcport 2001,2010,9292
attr d_ccu rpcqueue /tmp/ccuqueue
attr d_ccu rpcinterval 5

Nun kann der RPC-Server gestartet werden. Dabei wird je RPC-Port (s.o.) ein separater fhem.pl Prozess gestartet. Diese Prozesse empfangen 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. Der eigentliche Startbefehl sieht so aus:

set d_ccu rpcserver on

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. Anschließend sollte man noch das Attribut rpcserver auf „on“ setzen, damit der RPC-Server beim Start von FHEM automatisch gestartet wird:

attr d_ccu rpcserver on

Funktionen des Moduls HMCCU

Lesen und Ändern von CCU2 Systemvariablen

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. 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.
Beispiel: Lesen aller Systemvariablen, die mit A beginnen:

get d_ccu vars A.*

Beispiel: Setzen der Systemvariablen „Temperatur“ auf den Wert 20.5:

set d_ccu var Temperatur 20.5

Ausführen von CCU2 Programmen

Ein in der CCU2 hinterlegtes Programm kann mit dem Befehl set execute ausgeführt werden. Einziger Parameter des Befehls ist der Name des Programms. Es spielt keine Rolle, ob das Programm in der CCU2 aktiv oder inaktiv ist.

Ausführen von Homematic Scripts

Mit dem Befehl set hmscript kann ein beliebiges Homematic Script an die CCU2 zur Ausführung gesendet werden. Wenn das Script zeilenweise Daten im Format "Parameter=Value" zurück gibt, werden diese als Readings mit dem Namen Parameter" im I/O Device gespeichert.
Beispiel: Das folgende Homematic Script wertet alle CCU2 Systemvariablen aus. Das Ergebnis wird als Readings gespeichert (äquivalent zu Befehl get vars):

object osysvar;
string ssysvarid;
foreach (ssysvarid, dom.GetObject(ID_SYSTEM_VARIABLES).EnumUsedIDs())
{
   osysvar = dom.GetObject(ssysvarid);
   WriteLine (osysvar.Name() # "=" # osysvar.Value());
}

Wenn das Script auf dem FHEM-Server unter /opt/fhem/sysvars.scr gespeichert wird, kann es wie folgt ausgeführt werden:

set d_ccu hmscript /opt/fhem/sysvars.scr