From d25d2d2a571f0724dee089d20b1f26520e1492d7 Mon Sep 17 00:00:00 2001 From: fhemzap <> Date: Thu, 26 Nov 2015 18:19:17 +0000 Subject: [PATCH] HMCCU: Example FHEM configuration git-svn-id: https://svn.fhem.de/fhem/trunk/fhem@10008 2b470e98-0d58-463d-a4d8-8e2adae1ed80 --- contrib/HMCCU/HMCCU_README.txt | 431 ++++++++++++++++++++++++--------- 1 file changed, 321 insertions(+), 110 deletions(-) diff --git a/contrib/HMCCU/HMCCU_README.txt b/contrib/HMCCU/HMCCU_README.txt index e30114102..1bef6a940 100644 --- a/contrib/HMCCU/HMCCU_README.txt +++ b/contrib/HMCCU/HMCCU_README.txt @@ -3,21 +3,23 @@ *** HMCCU/HMCCUDEV - Modules for FHEM - Homematic CCU integration *** ======================================================================= -* Document covers HMCCU/HMCCUDEV version 1.9. +* Document covers HMCCU/HMCCUDEV/HMCCUCHN version 2.0 (RPC server) * Please read carefully before using the modules. +* Last modified: 25.11.2015 ------------------------------------- +---------------------------------------------- Content - +---------------------------------------------- 1 HMCCU Introduction 1.1 HMCCU Description -1.2 HMCCU Requirements +1.2 HMCCU Requirements & Installation 2 HMCCU Usage 2.1 HMCCU Set Commands 2.2 HMCCU Get Commands 2.3 HMCCU Attributes 2.4 HMCCU Parameter File +2.5 RPC daemon 3 HMCCUDEV Introduction 3.1 HMCCUDEV Description @@ -28,39 +30,46 @@ 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 +5 HMCCUCHN Usage +5.1 HMCCUCHN Set Commands +5.2 HMCCUCHN Get Commands +5.3 HMCCUCHN Attributes ------------------------------------- +6 Hints and Tips +6.1 Requesting information from CCU +6.2 Executing FHEM commands on CCU +6.3 Use RAM disk for /tmp on Raspbian +---------------------------------------------- ------------------------------------- +==================================== 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 modules HMCCU, HMCCUDEV and HMCCUCHN 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. +in FHEM. You have to define AT devices with get commands to ensure a continuous +update of CCU readings in FHEM or use the external RPC server. ------------------------------------- - 1.2 HMCCU Requirements ------------------------------------- +-------------------------------------- + 1.2 HMCCU Requirements & Installation +-------------------------------------- -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. +The module HMCCU no longer requires the XML-API CCU addon. The FHEM module requires +the packages LWP::UserAgent, Time::HiRes and File::Queue. The RPC server ccurpcd.pl +requires the packages File::Queue, RPC::XML::Server, RPC::XML::Client, XML::Simple +and IO::Socket::INET. +All module files 88_HMCCU* and the RPC daemon ccurpcd.pl must be copied into the +folder FHEM under the FHEM installation directory. ------------------------------------- +==================================== 2 HMCCU Usage ------------------------------------- +==================================== Define a new IO device for communication with Homematic CCU: @@ -68,51 +77,57 @@ Define a new IO device for communication with Homematic CCU: 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: +Some commands use device, channel or datapoint addresses. A channel address has +the following format: [.]: - -The default value for is BidCoS-RF. A datapoint is identified by - [.]:. +A device address is a channel address without the channel number. 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'. +A or a is the alias for an device or channel defined +in the CCU. + +IMPORTANT NOTE: During device definition HMCCU reads the available CCU devices. +This request must be repeated by using command "get devicelist" after a reload +of the module or after modification or definition of devices in the CCU. Otherwise +HMCCU, HMCCUDEV and HMCCUCHN won't work correctly. It's recommended to define +an automatic device synchronization (i.e. daily) with AT and command +'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. +for values 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 i.e. 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. + channel with datapoint STATE. This default datapoint can be changed by setting + attribute 'statedatapoint'. + If more than one is specified the values are concatinated by blanks + to one text string. Set value of a CCU device datapoint: - set datapoint {|. [...] + set datapoint {|}. [...] - Parameters are the same as with 'devstate' command. In addition the name - of a CCU channel datapoint must be specified. + Parameters correspond to 'devstate' command. In addition the name of a CCU + channel datapoint must be specified. Set value of a CCU system variable: @@ -124,70 +139,78 @@ Execute CCU program: set execute - The program is executed even it's deactivated in CCU. - -Clear CCU alarms: - - set clearmsg + The program is executed even if it's deactivated in CCU. +Execute Homematic script: + set hmscript + + If script returns parameter=value pairs via standard output these values are + stored as readings. + + ------------------------------------ 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. +If attribute 'ccureadings' is set to 1 (default) the results of the get commands +are stored in readings. By default the reading names correspond to the CCU +datapoints, including the channel-name. This behaviour can be changed by setting +the attribute 'ccureadingformat'. 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. + +The attribute 'updatemode' controls wether readings are updated in the IO device, +in client devices only or both in IO device and client devices. + +With attribute 'substitute' one 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 by "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. + 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 . Get value of datapoint: - get datapoint {|}. + get datapoint {|}. [] Read list of devices and channels from CCU: - get devicelist + get devicelist [dump] + + This command must be executed after HMCCU is reloaded or after devices are + defined, modified or deleted in the CCU. Otherwise HMCCU does not know + the alias names of CCU devices and most of the get/set commands will fail. + With option 'dump' all devices/channels are displayed in browser window. Get state of channel: get devstate {|} [] - Specified channel must contain the datapoint 'STATE'. + Specified channel must contain the datapoint 'STATE'. This default datapoint + can be modified by setting attribute 'statedatapoint'. Get multiple channels and datapoints: get parfile [] - If attribute 'parfile' is set parameter can be omitted. - See parameter file description below. + 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. - + Variable name can be a regular expression. Variables are stored as readings + with same name as in CCU. ------------------------------------ 2.3 HMCCU Attributes @@ -196,80 +219,140 @@ Get CCU variable values: Set reading name format (default is 'name'): attr ccureadingformat { name | address } - + +Control reading update in IO and client devices (default is 'hmccu'): + + attr updatemode { hmccu | both | client } + Control reading creation (default is 1): attr ccureadings { 0 | 1 } -Remove character from CCU device or variable specification in set -commands: +Set datapoint for "get/set devstate" commands (default is 'STATE'): + + attr statedatapoint + +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. + If a variable name ends with the specified character this character will be + removed. -Specify name of parameter file for command 'get parfile': +Specify name of parameter file for command "get parfile": attr parfile +Set interval for RPC event processing: + + attr rpcinterval { 3 | 5 | 10 } + + Set interval in seconds for reading RPC events from RPC event queue. + +Set port of CCU RPC interface (default is 2001): + + attr rpcport + +Set RPC event queue file (default is /tmp/ccuqueue): + + attr rpcqueue + + Parameter is a prefix. The RPC event queue consists of two files + with extension .idx and .dat. + +Start/stop RPC server: + + attr rpcserver { on | off } + + After starting the RPC server it takes 3 minutes until events from CCU arrive. + Stopping RPC server can take a few seconds. + Specify text substitutions for values in set commands: attr stateval :[,...] + + Note: Parameters are no regular expressions. 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: +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. +------------------------------------ + 2.5 RPC daemon +------------------------------------ ------------------------------------- +Because of several restrictions of FHEM regarding socket communication and +forking external processes the RPC daemon is realized as a standalone process. +The communication between ccurpcd and FHEM happens by using a file based FIFO +queue. On systems running on SD cards like Raspberry PI it's recommended to +set the attribute 'rpcqueue' pointing to a file located on a RAM disk (see +section 6.3 for more information about setting up a RAM disk on Raspbian). + +ccurpcd is started under user 'fhem'. So this user must have the permission to +read and write data on from/into queue file and also write log file entries in +the standard FHEM log directory. The daemon writes error messages to file +ccurpcd.log in the FHEM log directory. + +The RPC daemon is controlled via attribute 'rpcserver'. After setting this +attribute to "on" the HMCCU module will start ccurpcd as a separate process. +The PID of ccurpcd is stored in the internal "RPCPID". After start of ccurpcd +it takes 3 minnutes until first events from CCU arrive in FHEM (don't know +why - ask EQ-3 ;-) + +The RPC daemon is stopped when setting 'rpcserver' to "off" or by sending a +signal "INT" to the process. Because ccurpcd will gracefully shutdown the +CCU interface it can take some time until process disappears. After process +has been terminated the internal "RPCPID" is deleted. + +For more information see attributes 'rpcport', 'rpcserver', 'rpcqueue' and +'rpcinterval'. + + +==================================== 3 HMCCUDEV Introduction ------------------------------------- +==================================== ------------------------------------ 3.1 HMCCUDEV Description ------------------------------------ -HMCCUDEV is used to define client devices. HMCCU can be used standalone (without -defining client devices). +HMCCUDEV is used to define HMCCU client devices for CCU devices. Note: 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. +FHEM under the FHEM installation directory. A IO device of type HMCCU must be +defined before defining any client devices. ------------------------------------- +==================================== 4 HMCCUDEV Usage ------------------------------------- +==================================== Define a new client device: - define HMCCUDEV {|} [] [readonly] + 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 channel number for devstate commands can be specified with parameter + or via attribute 'statechannel'. The keyword 'readonly' declares a device as read only (i.e. a sensor). For read only devices no set command is available. @@ -287,9 +370,9 @@ Set state of device: 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. + number which contains datapoint 'STATE' must be set via attribute 'statechannel'. + If no state channel is specified the command is not available. The default + datapoint 'STATE' can be modified by setting attribute 'statedatapoint'. ------------------------------------ 4.2 HMCCUDEV Get Commands @@ -297,14 +380,24 @@ Set state of device: Get value of datapoint: - get datapoint . + get datapoint [.] + + If no datapoibt is specified all datapoints for specified channel are read. + +Get multiple datapoints of channel: + + get channel [.] + + Parameter is a regular expression. Default is .* (query all + datapoints of a channel). Get state of device: get devstate Requires the specification of the channel number which contains datapoint - 'STATE'. See also command 'set devstate'. + "STATE" by using attribute 'statechannel'. The default datapoint "STATE" + can be modified by setting attribute 'statedatapoint'. ------------------------------------ 4.3 HMCCUDEV Attributes @@ -321,6 +414,10 @@ Set reading name format (default is 'name'): Control reading creation (default is 1): attr ccureadings { 0 | 1 } + +Set datapoint for 'devstate' command (default is "STATE"): + + attr statedatapoint Specify IO device for client device: @@ -332,7 +429,7 @@ Specify channel number of STATE datapoint: attr statechannel - If no statechannel is set the command set devstate fails. + If no statechannel is set the commands 'get/set devstate' are not available. Specify text substitutions for values in set commands: @@ -347,10 +444,108 @@ Specify text substitutions for values in set commands: Specify text substitutions for values returned by get commands: attr substitute :[,...] + + +==================================== + 5 HMCCUCHN Usage +==================================== + +Define a new client device: + + define HMCCUCHN {|} [readonly] + +Parameter is the CCU channel address including the channel +number. If is specified it must be known by HMCCU. If the channel +can't be found the device list of the HMCCU device must be updated with command +'get devicelist'. The keyword 'readonly' declares a channel as read only (i.e. +a sensor). For read only channels no set command is available. + +------------------------------------ + 5.1 HMCCUCHN Set Commands +------------------------------------ + +Set value of datapoint: + + set datapoint [...] + +Set state of channel: + + set devstate + set + + If attribute 'statevals' is defined 'devstate' can be ommitted. The default + datapoint "STATE" can be modified by setting attribute 'statedatapoint'. + +------------------------------------ + 4.2 HMCCUCHN Get Commands +------------------------------------ + +Get value of datapoint: + + get datapoint [] + + If no datapoint is specified all datapoints are read. + +Get multiple datapoints: + + get channel [] + + Parameter is a regular expression. Default is .* (query all + datapoints of a channel). + +Get state of device: + + get devstate + + The default datapoint "STATE" can be modified by setting attribute + 'statedatapoint'. + +------------------------------------ + 4.3 HMCCUCHN 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 } + +Set datapoint for "devstate" command (default is "STATE"): + + attr statedatapoint + +Specify IO device for client device: + + attr IODev + + Normally this is set automatically during HMCCUDEV device definition. + +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 :[,...] +==================================== + 6 Hints and tipps +==================================== ------------------------------------ - 5.2 Requesting information from CCU + 6.1 Requesting information from CCU ------------------------------------ By using XML-API one can query device names, channel names, channel addresses @@ -362,10 +557,9 @@ information: 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 + 6.2 Executing FHEM commands on CCU ------------------------------------ It's possible to execute FHEM commands from CCU via the FHEM telnet port. @@ -396,6 +590,23 @@ 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. +-------------------------------------- + 6.3 Use RAM disk for /tmp on Raspbian +-------------------------------------- + +By default ccurpcd creates the queue files in directory /tmp. On systems which +are running on a SD card like Raspbian this can shorten the lifetime of the +SD card. To avoid this /tmp can be moved to a RAM disk: + + 1) Edit file /etc/fstab as user 'root' and append the following line + + tmpfs /tmp tmpfs nodev,nosuid,relatime,size=100M 0 0 + + This will define /tmp as a RAM disk with a size of 100 MByte. + + 2) Restart the system. + + *** Have fun! zap ***