diff --git a/fhem/contrib/HMCCU/HMCCU_README.txt b/fhem/contrib/HMCCU/HMCCU_README.txt index 64abac972..de660fca9 100644 --- a/fhem/contrib/HMCCU/HMCCU_README.txt +++ b/fhem/contrib/HMCCU/HMCCU_README.txt @@ -3,9 +3,9 @@ *** HMCCU/HMCCUDEV - Modules for FHEM - Homematic CCU integration *** ======================================================================= -* Document covers HMCCU/HMCCUDEV/HMCCUCHN version 2.6 +* Document covers HMCCU/HMCCUDEV/HMCCUCHN version 2.8 * Please read carefully before using the modules. -* Last modified: 25.01.2016 +* Last modified: 24.02.2016 ---------------------------------------------- Content @@ -20,6 +20,7 @@ 2.3 HMCCU Attributes 2.4 HMCCU Parameter File 2.5 RPC daemon +2.6 Events 3 HMCCUDEV Introduction 3.1 HMCCUDEV Description @@ -102,12 +103,14 @@ or A or a is the alias for an device or channel defined in the CCU. +If a command allows parameters or either name or address can +be used. + 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'. +an automatic daily device synchronization with AT and command 'get devicelist'. ------------------------------------ 2.1 HMCCU Set commands @@ -120,19 +123,28 @@ 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 configuration parameters of CCU device or channel: + + set config {|} [] = [...] + + Set configuration parameters via RPC set request. If is not specified + port 2001 (BidCos) is used. + NOTE: Some parameter sets (i.e. time schedules for thermostat devices) must + always be set completely (at least for one day). Otherwise command is not + executed. + Set state of a CCU channel: - set devstate {|} [...] + set devstate [...] - Parameters or refer to the CCU device - channel with datapoint STATE. This default datapoint can be changed by setting - attribute 'statedatapoint'. + Parameter refers to the CCU device 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 correspond to 'devstate' command. In addition the name of a CCU channel datapoint must be specified. @@ -153,8 +165,15 @@ Execute Homematic script: set hmscript - If script returns parameter=value pairs via standard output these values are - stored as readings. + If script returns parameter=value pairs separated by newlines via standard + output these values are stored as readings. + +Restart RPC server: + + set restartrpc + + The command will fail if RPC server is not running. The restart may take up + to 4 minutes. During this time HMCCU devices cannot be used. ------------------------------------ @@ -180,7 +199,7 @@ device states as "true" or "false" these values can be replaced by "open" or If substitutions should apply only to some datapoints the datapoint name can be added as a prefix to the substitution rules. Several rules can be separated by -a semicolon. For example define 2 datapoint related rules and 1 standard rule: +a semicolon. Example: define 2 datapoint related rules and 1 standard rule: STATE!(1|true):on,(0|false):off;LOWBAT!(1|true):yes,(0|false):no;true:ok,false:error @@ -190,19 +209,18 @@ true and false are subsituted by ok and error. Get values of channel datapoints (supports multiple channels): - get channel {|}[.] [...] + 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 . + Attention: There's no blank between channel and datapoint. If no regular + expression datapoint_exp is specified all datapoints will be read. Get value of datapoint: - get datapoint {|}. [] + get datapoint . [] Display list of channels and datapoints of a device: - get deviceinfo {|} + get deviceinfo Read list of devices and channels from CCU: @@ -215,7 +233,7 @@ Read list of devices and channels from CCU: Get state of channel: - get devstate {|} [] + get devstate [] Specified channel must contain the datapoint 'STATE'. This default datapoint can be modified by setting attribute 'statedatapoint'. @@ -225,7 +243,8 @@ Update all client device datapoints / readings: get update [ [{ State | Value }]] If parameter is specified only client devices with device name - matching regular expression will be updated. + matching regular expression will be updated. A client device is only updated + if its attribute 'ccureadings' is set to 1. For more information about 'State' and 'Value' see description of attribute 'ccuget' in HMCCU section. @@ -247,6 +266,8 @@ Check if RPC server process is running: get rpcstate + The state of the RPC process(es) is displayed in browser window. + ------------------------------------ 2.3 HMCCU Attributes @@ -254,11 +275,22 @@ Check if RPC server process is running: Set filter for datapoint readings (default is '.*'): - attr ccureadingfilter + attr ccureadingfilter [,...] Only datapoints matching the specified expression will be stored as readings. Filter is ignored by commands 'get datapoint' and 'get channel'. Filter is used by command 'get update' and for RPC server events. + The syntax of a filter rule is: + + [!] + + If a regular expression for channel name is specified the rule applies + only to datapoints of this channel. Example: A virtual device group contains + channels and datapoints of different devices. For channel G_Heat we want + to get datapoint CONTROL_MODE. For all channels starting with D_Heat we + want to get datapoints LOWBAT and every datapoint witch match TEMP: + + attr ccureadingfilter G_Heat!CONTROL_MODE,^D_Heat!(LOWBAT|TEMP) Set query method for CCU device datapoints (default is 'Value'): @@ -271,7 +303,8 @@ Set query method for CCU device datapoints (default is 'Value'): is established. But in some cases it can be necessary to use State(). In those cases one should set the 'ccuget' attribute in the affected client device. Setting this attribute in the IO device will slow down the - communication between FHEM and CCU. + communication between FHEM and CCU because this setting applies to all + client devices. Set commands always use State(). Set reading name format (default is 'name'): @@ -283,21 +316,29 @@ Enable tracing of get commands: Enable tracing (loglevel 1) for devices / channels where CCU device name or device address matches specified expression. Using '.*' as expression - is not a good idea ;-) + is not a good idea because it will generate a lot of log data ;-) Control reading update in IO and client devices (default is 'hmccu'): attr updatemode { hmccu | both | client } + NOTE: If one use client devices this attribute should be set to 'client'. + Otherwise all readings of client devices will be stored in the IO device + too. As an alternative one can set attribute 'ccureadings' to 0. + Control reading creation (default is 1): attr ccureadings { 0 | 1 } + If one uses the IO device only for communication of client devices with + CCU set this attribute to 0. + Set datapoint for "get/set devstate" commands (default is 'STATE'): attr statedatapoint - The value of this datapoint is stored in internal STATE of the FHEM device. + The value of this datapoint is stored in internal STATE of the FHEM device + and in reading 'state'. Remove character from CCU device or variable specification in set commands: @@ -314,39 +355,46 @@ Set interval for RPC event processing: attr rpcinterval { 3 | 5 | 10 } - Set interval in seconds for reading RPC events from RPC event queue. + Set interval in seconds for reading RPC events from RPC event queue. -Set port of CCU RPC interface (default is 2001): +Set port(s) of CCU RPC interface (default is 2001): - attr rpcport + attr rpcport [,...] + + For each port specified a separate instance of the RPC server process will + be started when setting attribute 'rpcserver' to 'on'. + Usual ports: 2000=Wired, 2001=BidCos-RF 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. + with extension .idx and .dat. The RPC port is part of the names too. 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. - + Stopping RPC server can take up to 30 seconds. + Specify text substitutions for values in set commands: - attr stateval :[,...] + attr statevals :[,...] - Note: Parameters are no regular expressions. + NOTE: Parameter is not a regular expression. Example: set datapoint to + true/false if on/off is specified in set command: + + attr statevals on:true,off:false Set format of readings with floating point numbers (default is 0): attr stripnumber { 0 | 1 | 2 } - 0 = Floating point numbers are stored as read from CCU (i.e. with trailing zeros). - 1 = Trailing zeros are stripped from floating point numbers except one digit. - 2 = All trailing zeros are stripped from floating point numbers. + 0 = Floating point numbers are stored as read from CCU. + 1 = Trailing zeros are stripped except one digit. + 2 = All trailing zeros and the decimal point are stripped. Specify text substitution rules for values returned by get commands: @@ -355,19 +403,18 @@ Specify text substitution rules for values returned by get commands: The substitution rules are applied to values read from CCU before they are stored as readings. The syntax of a substitution rule is: - [!]:[,...] + [!]:[,...] - If a datapoint is specified the rule is applied only for values of this - datapoint. + If a datapoint is specified the rule applies only to values of this datapoint. - Note: Floating point numbers are ignored. Integer numbers are only substituted + NOTE: Floating point numbers are ignored. Integer numbers are only substituted if they match the complete regular expression. Example: Substitute values of datapoints STATE and LOWBAT. STATE!(1|true):on,(0|false):off;LOWBAT!(1|true):yes,(0|false):no - Note: get commands return true/false for boolean values while RPC server + NOTE: get commands return true/false for boolean values while RPC server returns 1/0. @@ -379,7 +426,7 @@ 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. @@ -398,11 +445,13 @@ 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. +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 +The RPC process is started even if attribute 'rpcserver' is already set to +"on". +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 ;-) @@ -411,9 +460,35 @@ 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. +The current state of the RPC process is stored in the INTERNAL 'RPCState': + + starting = RPC server is starting. This phase can take 3 minutes. + running = RPC server is started an waiting for CCU events. + stopping = RPC server is shutting down. Signal SIGINT sent to process. + stopped = RPC server stopped. + restarting = RPC server is restarting. + For more information see attributes 'rpcport', 'rpcserver', 'rpcqueue' and 'rpcinterval'. +------------------------------------ + 2.6 Events +------------------------------------ + +In some situations HMCCU will trigger events: + + "RPC server restarting" + "RPC server starting" + "RPC server running" + "RPC server stopped" + "No events from CCU since 300 seconds" + "n devices deleted in CCU" + "n devices added in CCU" + +FHEM can react on these events by using command 'notify'. Example: If new +devices added in CCU the IO device should execute command 'get devicelist' +to enable the usage of the new devices in FHEM. + ==================================== 3 HMCCUDEV Introduction @@ -422,15 +497,17 @@ For more information see attributes 'rpcport', 'rpcserver', 'rpcqueue' and 3.1 HMCCUDEV Description ------------------------------------ -HMCCUDEV is used to define HMCCU client devices for CCU devices. Note: 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 but it's highly +recommended to use client devices because every Homematic device type has +its own functionality which must be handled different. ------------------------------------ 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. A IO device of type HMCCU must be +FHEM under the FHEM installation directory. An IO device of type HMCCU must be defined before defining any client devices. @@ -440,15 +517,32 @@ defined before defining any client devices. Define a new client device: - define HMCCUDEV {|} [] [readonly] + define HMCCUDEV [] [readonly] + +Define a new client device group: + + define HMCCUDEV [] [readonly] + {group={|}[,...]|groupexp=} + +Define a new virtual device: + + define HMCCUDEV virtual + {group={|}[,...]|groupexp=} -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 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. +The parameter is the CCU device name or address. 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 default 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. +HMCCUDEV also supports CCU group devices (i.e. groups of heating controls). The +member devices of a CCU group device must be specified with options 'group' or +'groupexp'. If readings of the member devices are updated the readings in the +group devices will be updated too. +Virtual devices are a special kind of group devices. A virtual device is a group +of client devices which only exists in FHEM. The only available command for +virtual devices is 'get update'. ------------------------------------ 4.1 HMCCUDEV Set Commands @@ -473,7 +567,14 @@ Set state of device: 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'. + +Toggle device state: + + set toggle + + This command requires that attribute 'statevals' contains at least 2 states. + ------------------------------------ 4.2 HMCCUDEV Get Commands ------------------------------------ @@ -522,6 +623,15 @@ Set query method for CCU device datapoints (default is 'Value'): For more information see description of attribute 'ccuget' in HMCCU section. +Force IO device to verify set commands by get commands (default is 0): + + attr ccuverify { 0 | 1 } + + Note: This won't work if set/get datapoints are different. i.e. auto operation + modes of thermostat devices is set with datapoint AUTO_MODE but for reading + the operation mode datapoint CONTROL_MODE must be used. In this case command + verification will fail. + Set filter for datapoint readings (default is '.*'): attr ccureadingfilter @@ -638,6 +748,13 @@ Set state of channel: If attribute 'statevals' is defined 'devstate' can be ommitted. The default datapoint "STATE" can be modified by setting attribute 'statedatapoint'. + +Toggle channel state: + + set toggle + + This command requires that attribute 'statevals' contains at least 2 states. + ------------------------------------ 4.2 HMCCUCHN Get Commands @@ -682,6 +799,15 @@ Set query method for CCU device datapoints (default is 'Value'): For more information see description of attribute 'ccuget' in HMCCU section. +Force IO device to verify set commands by get commands (default is 0): + + attr ccuverify { 0 | 1 } + + Note: This won't work if set/get datapoints are different. i.e. auto operation + modes of thermostat devices is set with datapoint AUTO_MODE but for reading + the operation mode datapoint CONTROL_MODE must be used. In this case command + verification will fail. + Set filter for datapoint readings (default is '.*'): attr ccureadingfilter