======================================================================= *** HMCCU/HMCCUDEV - Modules for FHEM - Homematic CCU integration *** ======================================================================= * Document covers HMCCU/HMCCUDEV version 1.9. * Please read carefully before using the modules. ------------------------------------ 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 HMCCUDEV Introduction 3.1 HMCCUDEV Description 3.2 HMCCUDEV Requirements 4 HMCCUDEV Usage 4.1 HMCCUDEV Set Commands 4.2 HMCCUDEV Get Commands 4.3 HMCCUDEV Attributes 5 Hints and Tips 5.1 Requesting information from CCU 5.2 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. The states and values of CCU channels and variables are not updated automatically in FHEM. You have to define an AT device with a HMCCU get command to ensure a continuous update of CCU readings in FHEM. ------------------------------------ 1.2 HMCCU Requirements ------------------------------------ The module HMCCU requires the XML-API CCU addon (version >= 1.10). The FHEM module requires the packages XML::Simple and File::Queue. The module 88_HMCCU.pm must be copied into folder FHEM under the FHEM installation directory. ------------------------------------ 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. Some commands use channel or datapoint addresses. A channel address has the following format: [.]: The default value for is BidCoS-RF. A datapoint is identified by [.]:. or . IMPORTANT NOTE: During device definition HMCCU reads the available CCU devices and channels via XML-API. After a reload of the module this must be repeated by using command 'get devicelist'. Otherwise HMCCU and HMCCUDEV won't work correctly. It's recommended to define an automatic device synchronization with AT and 'get devicelist'. ------------------------------------ 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. Set state of a CCU channel: set devstate {|} [...] Parameters or refer to the CCU device channel with datapoint STATE. If more than one is specified the values are concatinated by blanks to a single 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 channel 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 by default correspond to the CCU datapoints, including the channel-name. By setting the attribute 'ccureadingformat' reading names can be changed to channel-address and datapoint name. The attribute 'ccureadingformat' is ignored if the same attribute is defined in a client device. 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 in FHEM 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 {|}[.] Attention: There's no blank between channel and datapoint. 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 {|}. Read list of devices and channels from CCU: get devicelist Get state of channel: get devstate {|} [] Specified channel must contain the datapoint 'STATE'. Get multiple channels and 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 ------------------------------------ Set reading name format (default is 'name'): attr ccureadingformat { name | address } 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 contains a list of CCU 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: |[.] [:[,...]] First part corresponds to command 'get channel'. Empty lines and lines starting with a '#' are ignored. ------------------------------------ 3 HMCCUDEV Introduction ------------------------------------ ------------------------------------ 3.1 HMCCUDEV Description ------------------------------------ HMCCUDEV is used to define client devices. HMCCU can be used standalone (without defining client devices). ------------------------------------ 3.2 HMCCUDEV Requirements ------------------------------------ See 1.2 HMCCU Requirements. The module 88_HMCCUDEV.pm must be copied into folder FHEM under the FHEM installation directory. ------------------------------------ 4 HMCCUDEV Usage ------------------------------------ Define a new client device: define HMCCUDEV {|} [] [readonly] Parameter is the CCU device address without the channel number. The CCU device must be known by HMCCU. If the device can't be found the device list of the HMCCU device must be updated with command 'get devicelist'. The Parameter is the number of the channel which contains the datapoint 'STATE'. Because not every CCU device has a 'STATE' datapoint this parameter is optional. The state channel number can also be set with the attribute command. The keyword 'readonly' declares a device as read only (i.e. a sensor). For read only devices no set command is available. ------------------------------------ 4.1 HMCCUDEV Set Commands ------------------------------------ Set value of datapoint: set datapoint . [...] Set state of device: set devstate set If attribute 'statevals' is defined 'devstate' can be ommitted. The channel number which contains datapoint 'STATE' must be set during device definition or via attribute 'statechannel'. If no state channel is specified the command is not available. ------------------------------------ 4.2 HMCCUDEV Get Commands ------------------------------------ Get value of datapoint: get datapoint . Get state of device: get devstate Requires the specification of the channel number which contains datapoint 'STATE'. See also command 'set devstate'. ------------------------------------ 4.3 HMCCUDEV Attributes ------------------------------------ Client device attributes overwrite corresponding HMCCU attributes! Set reading name format (default is 'name'): attr ccureadingformat { name | address | datapoint } If set to 'datapoint' the reading name is the datapoint name without channel. Control reading creation (default is 1): attr ccureadings { 0 | 1 } Specify IO device for client device: attr IODev Normally this is set automatically during HMCCUDEV device definition. Specify channel number of STATE datapoint: attr statechannel If no statechannel is set the command set devstate fails. Specify text substitutions for values in set commands: attr stateval :[,...] The values are available as set commands, i.e. attr switch1 stateval on:true,off:false set switch1 on set switch1 off set switch1 devstate on Specify text substitutions for values returned by get commands: attr substitute :[,...] ------------------------------------ 5.2 Requesting information from CCU ------------------------------------ By using XML-API one can query device names, channel names, channel addresses and datapoint names from CCU. The following request queries device and channel information: http://ccuname-or-ip/config/xmlapi/devicelist.cgi?show_internal=1 The following request returns a list of datapoints with current values: http://ccuname-or-ip/config/xmlapi/statelist.cgi?show_internal=1 ------------------------------------ 5.1 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). --- Start of 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 (requires installation of CUxD). If FHEM command contains blanks it should be enclosed in double quotes. *** Have fun! zap ***