FHEM/fhem-mirror
2
0
Fork 0
mirror of https://github.com/fhem/fhem-mirror.git synced 2025-04-06 18:28:44 +00:00
Code Issues Releases Wiki Activity

HMCCU: device and channel addressing reworked, prepared for upcoming RPC version

Browse Source 
git-svn-id: https://svn.fhem.de/fhem/trunk@9791 2b470e98-0d58-463d-a4d8-8e2adae1ed80
This commit is contained in:
fhemzap 2015-11-05 18:19:58 +00:00
parent dab49cd678
commit aadc423e77
1 changed files with 215 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

259
fhem/contrib/HMCCU/HMCCU_README.txt
View File

@ -1,12 +1,13 @@
=============================================================
*** HMCCU - Module for FHEM - Homematic CCU integration ***
=============================================================
=======================================================================
*** HMCCU/HMCCUDEV - Modules for FHEM - Homematic CCU integration ***
=======================================================================
* Document covers HMCCU/HMCCUDEV version 1.9.
* Please read carefully before using the modules.
------------------------------------
Content:
------------------------------------
Content
1 HMCCU Introduction
1.1 HMCCU Description
@ -18,7 +19,20 @@
2.3 HMCCU Attributes
2.4 HMCCU Parameter File
3 Executing FHEM commands on CCU
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
------------------------------------
------------------------------------
@ -30,18 +44,18 @@
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
in FHEM. You have to define an AT device to ensure a continuous update of CCU
values in FHEM.
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 package XML::Simple. Note: not all HMCCU commands use the
XML-API.
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.
------------------------------------
@ -54,6 +68,25 @@ 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:
[<interface>.]<device-address>:<channel-number>
The default value for <interface> is BidCoS-RF. A datapoint is identified by
[<interface>.]<device-address>:<channel-number>.<datapoint-name>
or
<channel-name>.<datapoint-name>
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
@ -65,24 +98,23 @@ 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 channel:
set <name> devstate <ccudev>:<channel> <value> [...]
set <name> devstate {<channel-name>|<channel-address>} <value> [...]
Parameter <ccudev> is the name of a device in CCU. <channel> specifies a
CCU device channel number. If more than one <value> is specified the
values are concatinated by blanks to one value.
Parameters <channel-name> or <channel-address> refer to the CCU device
channel with datapoint STATE. If more than one <value> is specified the
values are concatinated by blanks to a single value.
Set value of a CCU device datapoint (*):
Set value of a CCU device datapoint:
set <name> datapoint <ccudev>:<channel>.<datapoint> <value> [...]
set <name> datapoint {<channel-name>|<channel-address>.<datapoint> <value> [...]
Parameters are the same as with 'devstate' command. In addition the name
of a CCU device datapoint must be specified.
of a CCU channel datapoint must be specified.
Set value of a CCU system variable (*):
Set value of a CCU system variable:
set <name> var <variable> <value> [...]
@ -104,13 +136,15 @@ Clear CCU alarms:
------------------------------------
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.
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 <reading>. If this parameter
is specified the CCU value is stored using this reading name.
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
@ -120,22 +154,27 @@ in a client device.
Get values of channel datapoints:
get <name> channel <channel>[.<datapoint_exp>]
get <name> channel {<channel-name>|<channel-address>}[.<datapoint_exp>]
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 datapoint.
Get value of datapoint (*):
Get value of datapoint:
get <name> datapoint <ccudevice>:<channel>.<datapoint> [<reading>]
get <name> datapoint {<channel-name>|<channel-address>}.<datapoint>
Read list of devices and channels from CCU:
Get state of channel (*):
get <name> devicelist
get <name> devstate <ccudevice>:<channel> [<reading>]
Get state of channel:
Specified channel must contain a datapoint 'STATE'.
get <name> devstate {<channel-name>|<channel-address>} [<reading>]
Get multiple devices / channels / datapoints:
Specified channel must contain the datapoint 'STATE'.
Get multiple channels and datapoints:
get <name> parfile [<parfile>]
@ -154,6 +193,10 @@ Get CCU variable values:
2.3 HMCCU Attributes
------------------------------------
Set reading name format (default is 'name'):
attr <name> ccureadingformat { name | address }
Control reading creation (default is 1):
attr <name> ccureadings { 0 | 1 }
@ -174,7 +217,7 @@ Specify text substitutions for values in set commands:
attr <name> stateval <text1>:<subtext1>[,...]
Specify text substitutions for values returned by get commands:
Specify text substitutions for values returned by get commands:
attr <name> substitute <regexp1>:<text1>[,...]
@ -183,18 +226,146 @@ Specify text substitutions for values returned by get commands:
2.4 HMCCU Parameter files
------------------------------------
A parameter file contain a list of CCU device channel or datapoint
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:
<ccudevice>:<channel>[.<datapoint_exp>] [<regexp1>:<subtext1>[,...]]
<channel-name>|<channel-address>[.<datapoint_exp>] [<regexp1>:<subtext1>[,...]]
Empty lines and lines starting with a '#' are ignored.
First part corresponds to command 'get channel'. Empty lines and lines starting
with a '#' are ignored.
------------------------------------
3 Executing FHEM commands on CCU
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 <name> HMCCUDEV {<Device-Name>|<Device-Address>} [<StateChannel>] [readonly]
Parameter <Device-Address> 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 <StateChannel> 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 <name> datapoint <channel-number>.<datapoint-name> <value> [...]
Set state of device:
set <name> devstate <value>
set <name> <state-value>
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 <name> datapoint <channel-number>.<datapoint-name>
Get state of device:
get <name> 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 <name> ccureadingformat { name | address | datapoint }
If set to 'datapoint' the reading name is the datapoint name without channel.
Control reading creation (default is 1):
attr <name> ccureadings { 0 | 1 }
Specify IO device for client device:
attr <name> IODev <HMCCU-Device>
Normally this is set automatically during HMCCUDEV device definition.
Specify channel number of STATE datapoint:
attr <name> statechannel <channel-number>
If no statechannel is set the command set devstate fails.
Specify text substitutions for values in set commands:
attr <name> stateval <text1>:<subtext1>[,...]
The values <textn> 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 <name> substitute <regexp1>:<text1>[,...]
------------------------------------
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.
@ -203,7 +374,7 @@ 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).
--- Script ---
--- Start of script ---
#!/bin/sh
# Set name or IP address and port of FHEM server
@ -219,11 +390,11 @@ if [ $# -ne 1 ]; then
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.
If FHEM command contains blanks it should be enclosed in double quotes.
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 ***