============================================================= *** HMCCU - Module for FHEM - Homematic CCU integration *** ============================================================= ------------------------------------ Content: ------------------------------------ 1 HMCCU Introduction 1.1 HMCCU Description 1.2 HMCCU Requirements 2 HMCCU Usage 2.1 HMCCU Set Commands 2.2 HMCCU Get Commands 2.3 HMCCU Attributes 2.4 HMCCU Parameter File 3 Executing FHEM commands on CCU ------------------------------------ 1 HMCCU Introduction ------------------------------------ ------------------------------------ 1.1 HMCCU Description ------------------------------------ The modules HMCCU and HMCCUDEV provide a simple interface between FHEM and a Homematic CCU2. HMCCU is the IO device for the communication with the CCU. HMCCUDEV is used to define client devices. The states and values of CCU devices and variables are not updated automatically in FHEM. You have to define an AT device to ensure a continuous update of CCU values in FHEM. ------------------------------------ 1.2 HMCCU Requirements ------------------------------------ The module HMCCU requires the XML-API CCU addon (version >= 1.10). The FHEM module requires the package XML::Simple. Note: not all HMCCU commands use the XML-API. ------------------------------------ 2 HMCCU Usage ------------------------------------ Define a new IO device for communication with Homematic CCU: define HMCCU The only parameter is the name or the IP address of the Homematic CCU. All other adjustments are done by setting attributes. ------------------------------------ 2.1 HMCCU Set commands ------------------------------------ If attribute 'stateval' is set the specified string substitutions are applied before setting the device state, a variable or a datapoint value. This is important because CCU states are often 'true' or 'false' while in FHEM one like to use 'on' or 'off'. So setting 'stateval' to 'on:true,off:false' will ensure that FHEM commands 'on' and 'off' are replaced by 'true' and 'false' before transmitting them to the CCU. The commands markes with a '*' don't use the XML-API of the CCU. Set state of a CCU device (*): set devstate : [...] Parameter is the name of a device in CCU. specifies a CCU device channel number. If more than one is specified the values are concatinated by blanks to one value. Set value of a CCU device datapoint (*): set datapoint :. [...] Parameters are the same as with 'devstate' command. In addition the name of a CCU device datapoint must be specified. Set value of a CCU system variable (*): set var [...] The variable must exist in CCU. It's not created automatically. Execute CCU program: set execute The program is executed even it's deactivated in CCU. Clear CCU alarms: set clearmsg ------------------------------------ 2.2 HMCCU Get commands ------------------------------------ If attribute 'ccureadings' is set to 1 (default) the results of the get commands are stored in readings. The reading names correspond to the CCU datapoints, including device and channel. The format of the reading names is device:channel.datapoint. If attribute 'ccureadings' is set to 0 the results of the get commands are displayed in the browser window. No readings will be set in this case. Some get commands allow an optional parameter . If this parameter is specified the CCU value is stored using this reading name. With attribute 'substitute' you can define expressions which are substituted by strings before CCU values are stored in readings. For example if CCU reports device states as 'true' or 'false' these values can be replaced with 'open' or 'closed' by setting 'substitute' to 'true:open,false:closed'. The attribute 'substitute' is ignored if the same attribute is defined in a client device. Get values of channel datapoints: get channel [.] If datapoint is not specified all datapoints will be read. The command accepts a regular expression as parameter datapoint. Get value of datapoint (*): get datapoint :. [] Get state of channel (*): get devstate : [] Specified channel must contain a datapoint 'STATE'. Get multiple devices / channels / datapoints: get parfile [] If attribute 'parfile' is set parameter can be omitted. See parameter file description below. Get CCU variable values: get vars Variable name can be a regular expression. Variables are stored as readings with same name as in CCU. ------------------------------------ 2.3 HMCCU Attributes ------------------------------------ Control reading creation (default is 1): attr ccureadings { 0 | 1 } Remove character from CCU device or variable specification in set commands: attr stripchar If a variable name ends with the specified character this character will be removed. Specify name of parameter file for command 'get parfile': attr parfile Specify text substitutions for values in set commands: attr stateval :[,...] Specify text substitutions for values returned by get commands: attr substitute :[,...] ------------------------------------ 2.4 HMCCU Parameter files ------------------------------------ A parameter file contain a list of CCU device channel or datapoint definitions. Each line can contain a text substitution rule. A parameter file is used by command 'get parfile'. The format of a parfile entry is: :[.] [:[,...]] Empty lines and lines starting with a '#' are ignored. ------------------------------------ 3 Executing FHEM commands on CCU ------------------------------------ It's possible to execute FHEM commands from CCU via the FHEM telnet port. The following shell script encapsulates the necessary commands. It can be placed somewhere under /etc/config/addons directory in CCU. The script requires the installation of the netcat command (nc) on CCU (search for the binary in google and install it somewhere in /etc/config/addons). --- Script --- #!/bin/sh # Set name or IP address and port of FHEM server FHEM_SERVER="myfhem" FHEM_PORT=7072 # Set path to nc command NCCMD="/etc/config/addons/scripts" if [ $# -ne 1 ]; then echo "Usage: $0 Command" exit 1 fi echo -e "$1\nquit\n" | $NCCMD/nc $FHEM_SERVER $FHEM_PORT --- End of script --- The script should be called from a CCU program by using the CUXD exec object. If FHEM command contains blanks it should be enclosed in double quotes. *** Have fun! zap ***