diff --git a/fhem/contrib/HMCCU/HMCCU_README.txt b/fhem/contrib/HMCCU/HMCCU_README.txt index cdfcf17f6..2f7f1d91e 100644 --- a/fhem/contrib/HMCCU/HMCCU_README.txt +++ b/fhem/contrib/HMCCU/HMCCU_README.txt @@ -1,65 +1,88 @@ -Content: -------- + + ============================================================= + *** 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 +2.1 HMCCU Set Commands +2.2 HMCCU Get Commands +2.3 HMCCU Attributes +2.4 HMCCU Parameter File ------------------------------------ -1 HMCCU Introduction + 1 HMCCU Introduction ------------------------------------ ------------------------------------ -1.1 HMCCU Description + 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. -You have to define an AT device to update the values. +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 + 1.2 HMCCU Requirements ------------------------------------ The module HMCCU requires the XML-API CCU addon (version >= 1.10). The FHEM -Perl module requires the package XML::Simple. +module requires the package XML::Simple. Note: not all HMCCU commands use the +XML-API. ------------------------------------ -2 HMCCU Usage + 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. --------------------- - HMCCU Set commands --------------------- +------------------------------------ + 2.1 HMCCU Set commands +------------------------------------ -If attribute stateval is set the specified string substitutions are applied -before setting the device state or variable or datapoint values. +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 state of a CCU device (*): - set devstate : + set devstate : [...] -Set value of a CCU device datapoint: + 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 datapoint :. +Set value of a CCU device datapoint (*): -Set value of a CCU system variable: + set datapoint :. [...] - set var + Parameters are the same as with 'devstate' command. In addition the name + of a CCU device datapoint must be specified. - The variable must exist in CCU. +Set value of a CCU system variable (*): + + set var [...] + + The variable must exist in CCU. It's not created automatically. Execute CCU program: @@ -72,33 +95,37 @@ Clear CCU alarms: set clearmsg --------------------- - HMCCU Get commands --------------------- +------------------------------------ + 2.2 HMCCU Get commands +------------------------------------ -If attribute ccureadings is set to 1 the results of the get commands -are stored in readings. The reading names correspond to the CCU data- -points, including device and channel. The format of the reading names +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. -Some get commands allow an optional parameter reading. If this para- -meter is specified the CCU value is stored using this reading name. -With attribute 'substitute' you can define expression which are sub- -stitute by strings before CCU values are stored in readings. +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 - commands accepts a regular expression as parameter datapoint. + command accepts a regular expression as parameter datapoint. -Get value of datapoint: +Get value of datapoint (*): get datapoint :. [] -Get state of channel: +Get state of channel (*): get devstate : [] @@ -115,12 +142,13 @@ Get CCU variable values: get vars - Variable name can be a regular expression. + Variable name can be a regular expression. Variables are stored + as readings with same name as in CCU. ------------------- - HMCCU Attributes ------------------- +------------------------------------ + 2.3 HMCCU Attributes +------------------------------------ Control reading creation (default is 1): @@ -131,6 +159,9 @@ 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 @@ -144,13 +175,14 @@ Specify text substitutions for values returned by get commands: attr substitute :[,...] ------------------------ - HMCCU Parameter files ------------------------ +------------------------------------ + 2.4 HMCCU Parameter files +------------------------------------ -A parameter file contain a list of CCU datapoint channel or datapoint -definitions. Each line can contain a text substitution rule. The format -is: +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: :[.] [:[,...]]