HMCCU: Fixed RPC server start/stop

git-svn-id: https://svn.fhem.de/fhem/trunk@11058 2b470e98-0d58-463d-a4d8-8e2adae1ed80

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 <channel-name> or a <device-name> is the alias for an device or channel defined
 in the CCU.
 
+If a command allows parameters <device> or <channel> 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
+an automatic daily device synchronization with AT and command 'get <name> devicelist'.
-'get <name> 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 <name> config {<device>|<channel>} [<rpcport>] <parameter>=<value> [...]
+
+   Set configuration parameters via RPC set request. If <rpcport> 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 <name> devstate {<channel-name>|<channel-address>} <value> [...]
+   set <name> devstate <channel> <value> [...]
 
-   Parameters <channel-name> or <channel-address> refer to the CCU device
+   Parameter <channel> refers to the CCU device channel with datapoint STATE.
-   channel with datapoint STATE. This default datapoint can be changed by setting
+   This default datapoint can be changed by setting attribute 'statedatapoint'.
-   attribute 'statedatapoint'.
    If more than one <value> is specified the values are concatinated by blanks
    to one text string.
 
 Set value of a CCU device datapoint:
 
-   set <name> datapoint {<channel-name>|<channel-address>}.<datapoint> <value> [...]
+   set <name> datapoint <channel>.<datapoint> <value> [...]
 
    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 <name> hmscript <script-file>
    
-   If script returns parameter=value pairs via standard output these values are
+   If script returns parameter=value pairs separated by newlines via standard
-   stored as readings.
+   output these values are stored as readings.
+
+Restart RPC server:
+
+   set <name> 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 <name> channel {<channel-name>|<channel-address>}[.<datapoint_exp>] [...]
+   get <name> channel <channel>[.<datapoint_exp>] [...]
 
-   Attention: There's no blank between channel and datapoint. If datapoint is
+   Attention: There's no blank between channel and datapoint. If no regular
-   not specified all datapoints will be read. The command accepts a regular
+   expression datapoint_exp is specified all datapoints will be read.
-   expression as parameter <datapoint_exp>.
 
 Get value of datapoint:
 
-   get <name> datapoint {<channel-name>|<channel-address>}.<datapoint> [<reading>]
+   get <name> datapoint <channel>.<datapoint> [<reading>]
    
 Display list of channels and datapoints of a device:
 
-   get <name> deviceinfo {<device-name>|<device-address>}
+   get <name> deviceinfo <device>
 
 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 <name> devstate {<channel-name>|<channel-address>} [<reading>]
+   get <name> devstate <channel> [<reading>]
 
    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 <name> update [<devexp> [{ State | Value }]]
 
    If parameter <devexp> 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 <name> 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 <name> ccureadingfilter <datapoint-expr>
+   attr <name> ccureadingfilter <rule>[,...]
 
    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:
+
+   [<channel-name-exp>!]<datapoint-exp>
+
+   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 <name> 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 <name> 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 <name> 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 <name> statedatapoint <datapoint>
 
-   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:
 
@@ -316,37 +357,44 @@ Set interval for RPC event processing:
    
    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 <name> rpcport <port>
+   attr <name> rpcport <port>[,...]
+
+   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 <name> rpcqueue <filename>
    
    Parameter <filename> 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 <name> 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 <name> stateval <text1>:<subtext1>[,...]
+   attr <name> statevals <text>:<subtext>[,...]
    
-   Note: Parameters <textn> are no regular expressions.
+   NOTE: Parameter <text> is not a regular expression. Example: set datapoint to
+   true/false if on/off is specified in set command:
+
+   attr <name> statevals on:true,off:false
 
 Set format of readings with floating point numbers (default is 0):
 
    attr <name> stripnumber { 0 | 1 | 2 }
 
-   0 = Floating point numbers are stored as read from CCU (i.e. with trailing zeros).
+   0 = Floating point numbers are stored as read from CCU.
-   1 = Trailing zeros are stripped from floating point numbers except one digit.
+   1 = Trailing zeros are stripped except one digit.
-   2 = All trailing zeros are stripped from floating point numbers.
+   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:
 
-   [<datapoint>!]<regexp1>:<subtext1>[,...]
+   [<datapoint>!]<regexp>:<subtext>[,...]
 
-   If a datapoint is specified the rule is applied only for values of this 
+   If a datapoint is specified the rule applies only to values of this datapoint.
-   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:
 
-  {<channel-name>|<channel-address>}[.<datapoint_exp>] [<substitution_rule[;...]]
+  <channel>[.<datapoint_exp>] [<substitution_rule>[;...]]
 
 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_<port>.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
+HMCCUDEV is used to define HMCCU client devices for CCU devices. NOTE: HMCCU
-can be used standalone without defining client devices.
+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 <name> HMCCUDEV {<Device-Name>|<Device-Address>} [<channel-number>] [readonly]
+   define <name> HMCCUDEV <device> [<state-channel>] [readonly]
 
-Parameter <Device-Address> is the CCU device address without the channel number.
+Define a new client device group:
-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'.
+   define <name> HMCCUDEV <ccu-group-device> [<state-channel>] [readonly]
-The channel number for devstate commands can be specified with parameter
+      {group={<device>|<channel>}[,...]|groupexp=<expression>}
-<channel-number> or via attribute 'statechannel'.
+
-The keyword 'readonly' declares a device as read only (i.e. a sensor). For read
+Define a new virtual device:
-only devices no set command is available.
+
+   define <name> HMCCUDEV virtual
+      {group={<device>|<channel>}[,...]|groupexp=<expression>}
+   
+The parameter <device> 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
+<state-channel> 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
@@ -474,6 +568,13 @@ Set state of device:
    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 <name> 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 <name> 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 <name> ccureadingfilter <datapoint-expr>
@@ -639,6 +749,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 <name> 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 <name> 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 <name> ccureadingfilter <datapoint-expr>