Contents

Introduction
Fhem command types
Device specification
Attributes

Fhem commands
apptime   attr   backup   cancel   cmdalias   configdb   copy   count   createlog   CULflash   define   defmod   delete   deleteattr   deletefile   deletereading   displayattr   exportdevice   fheminfo   get   help   IF   include   inform   JsonList   JsonList2   list   modify   MSG   notice   quit   reload   rename   rereadcfg   restore   save   set   setdefaultattr   setreading   setstate   shutdown   sleep   trigger   update   usb   version   XmlList  

Devices
global
Alarm   ALL3076   ALL4000T   ALL4027   allergy   AMAD   BDKM   BOSEST   BRAVIA   BS   Calendar   CALVIEW   cloneDummy   CM11   CO20   ComfoAir   CUL   CUL_EM   CUL_FHTTK   CUL_HM   CUL_HOERMANN   CUL_IR   CUL_MAX   CUL_REDIRECT   CUL_RFR   CUL_TCM97001   CUL_TX   CUL_WS   DLNARenderer   DUOFERN   DUOFERNSTICK   EC3000   ECMD   ECMDDevice   EDIPLUG   EGPM   EGPM2LAN   EIB   EleroDrive   EleroStick   EM   EMEM   EMGZ   EMT7110   EMWZ   ENECSYSGW   ENECSYSINV   ENIGMA2   EnOcean   ESA2000   fakeRoku   FBAHA   FBAHAHTTP   FBDECT   FHT   FHT8V   FHZ   FRAMEBUFFER   FReplacer   FRITZBOX   FRM   FRM_AD   FRM_I2C   FRM_IN   FRM_LCD   FRM_OUT   FRM_PWM   FRM_RGB   FRM_ROTENC   FRM_SERVO   FRM_STEPPER   FS20   FTUISRV   GAEBUS   GHoma   harmony   HEATRONIC   Hideki   HMCCU   HMCCUCHN   HMCCUDEV   HMLAN   HMS   HMUARTLGW   HOMBOT   HP1000   HTTPMOD   HUEBridge   HUEDevice   HXB   HXBDevice   Hyperion   I2C_BH1750   I2C_BME280   I2C_BMP180   I2C_DS1307   I2C_EEPROM   I2C_HDC1008   I2C_K30   I2C_LCD   I2C_MCP23008   I2C_MCP23017   I2C_MCP342x   I2C_MMA845X   I2C_PCA9532   I2C_PCA9685   I2C_PCF8574   I2C_SHT21   I2C_SHT3x   I2C_TSL2561   IPCAM   IPWE   IT   Itach_IR   Itach_IRDevice   Itach_Relay   Jabber   JawboneUp   JeeLink   JSONMETER   KeyValueProtocol   km200   KM273   KNX   KOPP_FC   KOSTALPIKO   KS300   LaCrosse   LaCrosseGateway   Level   LGTV   LGTV_IP12   LIGHTIFY   LINDY_HDMI_SWITCH   LIRC   LUXTRONIK2   M232   M232Counter   M232Voltage   mailcheck   MAX   MAXLAN   MEDIAPORTAL   MilightBridge   MilightDevice   Modbus   ModbusAttr   ModbusSET   ModbusTrovis5576   MPD   MQTT   MQTT_BRIDGE   MQTT_DEVICE   MSGFile   MSGMail   MYSENSORS   MYSENSORS_DEVICE   netatmo   NetIO230B   Netzer   NetzerI2C   NUT   OBIS   ONKYO_AVR   ONKYO_AVR_ZONE   OPENWEATHER   OREGON   OWAD   OWCOUNT   OWDevice   OWFS   OWID   OWLCD   OWMULTI   OWServer   OWSWITCH   OWTEMP   OWTHERM   OWVAR   OWX   OWX_ASYNC   panStamp   PCA301   PHILIPS_AUDIO   PHTV   PID20   PIFACE   pilight   pilight_ctrl   pilight_dimmer   pilight_raw   pilight_smoke   pilight_switch   pilight_temp   ping   PIONEERAVR   PIONEERAVRZONE   plex   Plugwise   POKEYS   PROPLANTA   Pushalot   Pushbullet   PushNotifier   Pushover   PW_Circle   PW_Scan   PW_Sense   PW_Switch   PWM   PWMR   Revolt   RFXCOM   RFXMETER   RFXX10REC   Robonect   RPI_GPIO   RPII2C   rssFeed   S7   S7_ARead   S7_AWrite   S7_Client   S7_DRead   S7_DWrite   SCIVT   SD_WS07   SD_WS09   SHC   SHCdev   SIGNALduino   SIGNALduino_un   SIS_PMS   SISPM   SMAEM   SMARTMON   SMASTP   SML   SOMFY   SONOS   SONOSPLAYER   speedtest   SSCam   STACKABLE_CC   STOCKQUOTES   STV   SWAP   SWAP_0000002200000003   SWAP_0000002200000008   SYSMON   SYSSTAT   tahoma   TCM   TechemHKV   TechemWZ   TEK603   TelegramBot   TellStick   THZ   TPLinkHS110   TRX   TRX_ELSE   TRX_LIGHT   TRX_SECURITY   TRX_WEATHER   TUL   UbiquitiMP   UbiquitiOut   Unifi   UNIRoll   USBWX   USF1000   UWZ   VantagePro2   VCONTROL   VIERA   VolumeLink   Weather   WEBCOUNT   WEBIO   WEBIO_12DIGITAL   WifiLight   withings   WMBUS   WS2000   WS300   WS3600   WWO   X10   XBMC   xxLG7000   YAMAHA_AVR   YAMAHA_BD   YAMAHA_NP   yowsup   ZWave   ZWCUL   ZWDongle  

Helper modules
allowed   at   autocreate   average   configDB   CustomReadings   Dashboard   DbLog   DbRep   dewpoint   DOIF   dummy   ElectricityCalculator   eventTypes   FB_CALLLIST   FB_CALLMONITOR   FHEM2FHEM   FHEMWEB   FileLog   FLOORPLAN   GasCalculator   GEOFANCY   GUEST   HCS   Heating_Control   HMinfo   holiday   HourCounter   HTTPSRV   InfoPanel   KM271   LightScene   logProxy   MaxScanner   msgConfig   notify   PachLog   PRESENCE   rain   RandomTimer   readingsGroup   readingsHistory   readingsProxy   remotecontrol   RESIDENTS   ROOMMATE   RSS   sequence   statistics   structure   SUNRISE_EL   SVG   telnet   Text2Speech   THRESHOLD   Twilight   Utils   watchdog   weblink   WeekdayTimer   weekprofile   WOL  

Perl specials
gnuplot file syntax

Introduction

Fhem is mainly used for home automation, but it is suitable for other tasks too, where notification, timers and logging plays an important role.

It supports different hardware devices to interface with certain protocols (e.g. FHZ1000PC to interface FS20 and HMS, CM11 to access X10), and logical devices like FS20 or FHT to digest the messages for a certain device type using this protocol.

Fhem is modular. The different devices are represented through modules which implement certain functions (e.g. define, get, set). Even seemingly integral parts of fhem like triggers (notify) and timers (at) are implemented this way, giving the possibility to replace/extend this functionality.

Fhem is controlled through readable / ascii commands, which are specified in files (e.g. the configuration file), or issued over a TCP/IP connection, either directly in a telnet session, with a fhem.pl in client mode or from one of the web frontends.

When starting the server you have to specify a configuration file:

perl fhem.pl fhem.cfg

A minimal configuration file looks like:

    attr global logfile log/fhem.log
    attr global modpath .
    attr global statefile log/fhem.save
    attr global verbose 3
    define telnetPort telnet 7072 global
    define WEB FHEMWEB 8083 global

Note: the last two lines are optional and assume you wish to use the builtin telnet and WEB interface.

The web interface can be reached at
http://<fhemhost>:8083

TCP/IP communication with fhem can either happen in a "session" (via telnet) or single client command (via fhem.pl). Example:
telnet <fhemhost> 7072
<NL> (This newline switches into "prompt" mode)
<command>...
quit

or
fhem.pl <fhemhost>:7072 "<fhem-command>" "..."

Fhem command types

There are three types of commands: "fhem" commands (described in this document), shell commands (they must be enclosed in double quotes ") and perl expressions (enclosed in curly brackets {}). shell commands or perl expressions are needed for complex at or notify arguments, but can also issued as a "normal" command.

E.g. the following three commands all do the same when issued from a telnet prompt:

set lamp off
"fhem.pl 7072 "set lamp off""
{fhem("set lamp off")}


Shell commands will be executed in the background, perl expressions and fhem commands will be executed in the main "thread". In order to make perl expressions easier to write, some special functions and variables are available. See the section Perl special for a description. To trigger fhem commands from a shell script (this is the "other way round"), use the client form of fhem.pl (described above).

Multiple fhem commands are separated by semicolon (;). In order to use semicolon in perl code or shell programs, they have to be escaped by the double semicolon (;;). See the Notes section of the notify chapter on command parameters and escape rules.
E.g. the following first command switches Lamp1 off at 07:00 and Lamp2 immediately (at the point of definition), the second one switches both lamps off at 07:00.

define lampoff at 07:00 set Lamp1 off; set Lamp2 off
define lampoff at 07:00 set Lamp1 off;; set Lamp2 off

For every further indirection you need to double the semicolons:, e.g. to switch on every day 2 devices at 7:00 for 10 minutes you have to write:

define onAt at 07:00 set Lamp1 on;;set Lamp2 on;; define offAt at +00:10 set Lamp1 off;;;;set Lamp2 off
Don't dispair, the previous example can also be written as
define onAt at 07:00 set Lamp1,Lamp2 on-for-timer 600

Commands can be either typed in plain, or read from a file (e.g. the configuration file at startup). The commands are either executed directly, or later if they are arguments to the at and notify fhem commands.

A line ending with \ will be concatenated with the next one, so long lines (e.g. multiple perl commands) can be split in multiple lines. Some web fronteds (e.g. webpgm2) make editing of multiline commands transparent for you (i.e. there is no need for \) .

Device specification (devspec)

The commands attr, deleteattr, displayattr, delete, get, list, set, setreading, setstate, trigger can take a more complex device specification as argument, which will be expanded to a list of devices. A device specification (short devspec) can be:
• a single device name. This is the most common case.
• a list of devices, separated by comma (,)
• a regular expression
• a NAME=VALUE pair, where NAME can be an internal value like TYPE, a Reading-Name or an attribute. VALUE is a regexp. To negate the comparison, use NAME!=VALUE. To restrict the search, use i: as prefix for internal values, r: for readings and a: for attributes. See the example below.
• if the spec is followed by the expression :FILTER=NAME=VALUE, then the values found in the first round are filtered by the second expression.
Examples:
set lamp1 on
set lamp1,lamp2,lamp3 on
set lamp.* on
set room=kitchen off
set room=kitchen:FILTER=STATE=on off
set room=kitchen:FILTER=STATE!=off off
list disabled=
list TYPE=FS20 STATE
list i:TYPE=FS20 STATE

Notes:
• the spec may not contain space characters.
• if there is a device which exactly corresponds to the spec, then no special processing is done.
• first the spec is separated by comma, then the regular expression and filter operations are executed.
• the returned list can contain the same device more than once, so "set lamp3,lamp3 on" switches lamp3 twice.
• for more complex structuring demands see the structure device.

Attributes

There are global attributes that are used by all devices and local attributes that apply to individual device classes only.

Some devices (like FHEMWEB) automatically define new global attributes on the first definition of a device of such type.

You can use the command

attr global userattr <attributelist>

for the global device to declare new global attributes and

attr <devicespec> userattr <attributelist>

for individual devices according to devspec to declare new local attributes. <attributelist> is a space-separated list which contains the names of the additional attributes. See the documentation of the attr command for examples.

Be careful not to overwrite additional global attributes previously defined by yourself or a device. Use the attr global userattr <attributelist> as early in your configuration as possible.

Device specific attributes

Global attributes used by all devices

• alias
  Used by FHEMWEB to display a device with another name e.g. when using special characters/spaces not accepted by device definition.


• comment
  Add an arbitrary comment.


• eventMap
  Replace event names and set arguments. The value of this attribute consists of a list of space separated values, each value is a colon separated pair. The first part specifies the "old" value, the second the new/desired value. If the first character is slash(/) or comma(,) then split not by space but by this character, enabling to embed spaces. Examples:
  attr store eventMap on:open off:closed
attr store eventMap /on-for-timer 10:open/off:closed/
set store open
  The explicit variant of this attribute has the following syntax:
  attr store eventMap { dev=>{"on"=>"open"}, usr=>{"open"=>"on"} }
attr store eventMap { dev=>{"^on(-for-timer)?(.*)"=>"open$2"}, usr=>{"^open(.*)"=>"on$1"}, fw=>{"^open(.*)"=>"open"} }
  This variant must be used, if the mapping is not symmetrical, the first part (dev) representing the device to user mapping, i.e. if the device reports on 100 or on-for-timer 100, the user will see open 100. The second part (usr) is the other direction, if the user specified open 10, the device will receive on 10. On both occasions the key will be first compared directly with the text, and if it is not equal, then it will be tried to match it as a regexp. When using regexps in the usr part with wildcards, the fw part must be filled with the exact same keys to enable a correct display in the FHEMWEB set dropdown list in the detail view.


• genericDisplayType
  used by some frontends (but not FHEMWEB) to offer a default image or appropriate commands for this device. Currently the following values are supported: switch,outlet,light,blind,speaker,thermostat


• group
  Group devices. Recognized by web-pgm2 (module FHEMWEB), it makes devices in the same group appear in the same box). This is used to further group devices together. A device can appear in more than one group, in this case the groups have to be specified comma-separated.
  If this attribute is not set then the device type is used as the grouping attribute.


• room
  Filter/group devices. Recognized by web-pgm2 and web-pgm3. A device can appear in more than one room, in this case the rooms have to be specified comma-separated.
  Devices in the room hidden will not appear in the web output, or set the FHEMWEB attribute to selectively disable rooms for certain FHEMWEB instances.


• suppressReading
  Used to eliminate unwanted readings. The value is a regular expression, with ^ and $ added. Only necessary in exceptional cases.


• showtime
  Used in the webfrontend pgm2 to show the time of last activity instead of the state in the summary view. Useful e.g. for FS20 PIRI devices.


• verbose
  Set the verbosity level. Possible values:
  • 0 - server start/stop
  • 1 - error messages or unknown packets
  • 2 - major events/alarms.
  • 3 - commands sent out will be logged.
  • 4 - you'll see whats received by the different devices.
  • 5 - debugging.
  The value for the global device is a default for other devices without own verbose attribute set.

readingFnAttributes

The following global attributes are honored by the modules that make use of the standardized readings updating mechanism in fhem.pl. Check the module's attribute list if you want to know if a device supports these attributes.

• stateFormat
  Modifies the STATE of the device, shown by the list command or in the room overview in FHEMWEB. If not set, its value is taken from the state reading. If set, then every word in the argument is replaced by the value of the reading if such a reading for the current device exists. If the value of this attribute is enclused in {}, then it is evaluated. This attribute is evaluated each time a reading is updated.
• event-on-update-reading
  If not set, every update of any reading creates an event, which e.g. is handled by notify or FileLog. The attribute takes a comma-separated list of readings. You may use regular expressions in that list. If set, only updates of the listed readings create events.
• event-on-change-reading
  The attribute takes a comma-separated list of readings. You may use regular expressions in that list. If set, only changes of the listed readings create events. In other words, if a reading listed here is updated with the new value identical to the old value, no event is created. If an optional [:threshold] is given after a reading name events are only generated if the change is >= threshold.
The precedence of event-on-update-reading and event-on-change-reading is as follows:
1. If both attributes are not set, any update of any reading of the device creates an event.
2. If any of the attributes is set, no events occur for updates or changes of readings not listed in any of the attributes.
3. If a reading is listed in event-on-update-reading, an update of the reading creates an event no matter whether the reading is also listed in event-on-change-reading.
• timestamp-on-change-reading
  The attribute takes a comma-separated list of readings. You may use regular expressions in that list. If set, the timestamps of the listed readings will not be changed if event-on-change-reading is also set and it would not create an event for this reading.
• event-aggregator
The primary uses of this attribute are to calculate (time-weighted) averages of readings over time periods and to throttle the update rate of readings and thus the amount of data written to the logs.

This attribute takes a comma-separated list of reading:interval:method:function:holdTime quintuples. You may use regular expressions for reading. If set, updates for the listed readings are ignored and associated events are suppressed for a black-out period of at least interval seconds (downsampling). After the black-out period has expired, the reading is updated with a value that is calculated from the values and timestamps of the previously ignored updates within the black-out period as follows:

function	description
v	the last value encountered
v0	the first value encountered
min	the smallest value encountered
max	the largest value encountered
mean	the arithmetic mean of all values
sd	the standard deviation from the mean
median	the median of all values (requires holdTime and function none)
integral	the arithmetic sum (if not time-weighted) or integral area (if time-weighted) of all values
n	number of samples
t	timestamp of the last value
t0	timestamp of the first value

If method is none, then that's all there is. If method is const or linear, the time-weighted series of values is taken into account instead. The weight is the timespan between two subsequent updates. With the const method, the value is the value of the reading at the beginning of the timespan; with the linear method, the value is the arithmetic average of the values at the beginning and the end of the timespan. Rollovers of black-out periods are handled as one would expect it.

One would typically use the linear method with the mean function for quantities continuously varying over time like electric power consumption, temperature or speed. For cumulative quantities like energy consumed, rain fallen or distance covered, the none method with the v function is used. The constant method is for discrete quantities that stay constant until the corresponding reading is updated, e.g. counters, switches and the like.

If the holdTime in seconds is defined, the samples will be kept in memory allowing the calculation of floating statistics instead of blocked statistics. With holdTime defined the interval can be kept undefined so that the readings update rate is unchanged or it can be set to a value less then holdTime for downsampling as described above with a full history of the readings in memory. Note that the historic samples are not persistent and will be lost when restarting FHEM.

The event aggregator only takes into consideration those updates that remain after preprocessing according to the event-on-update-reading and event-on-change-reading directives. Besides which, any update of a reading that occurs within a timespan from the preceding update that is smaller than the resolution of FHEM's time granularity is ditched.

When more than one function should be calculated for the same reading, the original reading must be multiplied (e.g. by using a notify) before applying the event-aggregator to the derived readings.

Examples:
attr myPowerMeter event-aggregator EP_POWER_METER:300:linear:mean,EP_ENERGY_METER:300:none:v
attr myBadSensor event-aggregator TEMP::none:median:300
attr mySunMeter event-aggregator SUN_INTENSITY_24H::const:integral:86400

• event-min-interval
  This attribute takes a comma-separated list of reading:minInterval pairs. You may use regular expressions for reading. Events will only be generated, if at least minInterval seconds elapsed since the last reading of the matched type.
• userReadings
  A comma-separated list of definitions of user-defined readings. Each definition has the form:
  <reading>[:<trigger>] [<modifier>] { <perl code> }
  After a single or bulk readings update, the user-defined readings are set by evaluating the perl code { <perl code> } for all definitions and setting the value of the respective user-defined reading <reading> to the result. If <trigger> is given, then all processing for this specific user reading is only done if one of the just updated "reading: value" combinations matches <trigger>, which is treated as a regexp.
  Examples:
  
  attr myEnergyMeter userReadings energy { ReadingsVal("myEnergyMeter","counters.A",0)/1250.0;; }
attr myMultiMeter userReadings energy1:counters.A.* { ReadingsVal("myMultiMeter","counters.A",0)/1250.0;; }, energy2:counters.B.* { ReadingsVal("myMultiMeter","counters.B",0)/1250.0;; }
  <modifier> can take one of these values:
  • none: the same as it would not have been given at all.
  • difference: the reading is set to the difference between the current and the previously evaluated value.
  • differential: the reading is set to the difference between the current and the previously evaluated value divided by the time in seconds between the current and the previous evaluation. Granularity of time is one second. No value is calculated if the time past is below one second. Useful to calculate rates.
  • integral: reverse function of differential. The result is incremented by the product of the time difference between the last two readings and the avarage of the last two readings.
    result += (time - timeold) * (oldval + value) / 2
  • offset: if the current evaluated value is smaler than the previously evaluated value the reading is incremented by the previous value. the reading can then be used as an offset correct for a counter that is reset for example due to a power loss.
  • monotonic: if the difference between the current and the previously evaluated value is positive the reading is incremented by this difference. this allows to derive a monotonic growing counter from an original counter even if the original will be rest by a power loss
  Example:
  
  attr myPowerMeter userReadings power differential { ReadingsVal("myPowerMeter","counters.A",0)/1250.0;; }
  Notes:
  • user readings with modifiers difference and differential store the calculated values internally. The user reading is set earliest at the second evaluation. Beware of stale values when changing definitions!
  • the name of the defined Readings consists of alphanumeric characters with underscore (_) and the minus (-) sign.

Common attributes

• IODev
  Set the IO or physical device which should be used for sending signals for this "logical" device. An example for the physical device is an FHZ or a CUL. Note: Upon startup FHEM assigns each logical device (FS20/HMS/KS300/etc) the last physical device which can receive data for this type of device. The attribute IODev needs to be used only if you attached more than one physical device capable of receiving signals for this logical device.


• Special: attribute disable can be toggled
  Attribute "disable" can be toggled by issuing the following command:
  
  attr <device> disable toggle
  
  Attribute "disable" must be offered by the corresponding module

attr

attr <devspec> <attrname> [<value>]

Set an attribute for a device defined by define. You can define your own attributes too to use them in other applications. Use "attr <name> ?" to get a list of possible attributes. See the Device specification section for details on <devspec>. After setting the attribute, the global event "ATTR" will be generated.

Examples:
attr global verbose 3
attr lamp room kitchen
attr lamp group lights
attr lamp loglevel 6
attr weatherstation event-on-update-reading wind,temperature,humidity
attr weatherstation event-on-change-reading israining
attr weatherstation event-on-change-reading israining,state
attr heating stateFormat Temp:measured-temp, Valve:actuator


Notes:

• See deleteattr to delete attributes.

cancel

cancel [<id> [quiet]]

Cancels a named sleep.

define

define [option] <name> <type> <type-specific>

Define a device. You need devices if you want to manipulate them (e.g. set on/off), and the logfile is also more readable if it contains e.g. "lamp off" instead of "Device 5673, Button 00, Code 00 (off)".
After definition, the global event "DEFINED" will be generated, see the notify section for details.


Each device takes different additional arguments at definition, see the corresponding device section for details.

Options:

• -temporary
  Add the TEMPORARY flag to the definition, which will prevent saving the device to fhem.cfg.


• -ignoreErr
  Reduce the number of errors displayed when a certain FHEM-module cannot be loaded. Used by fhem.cfg.demo, as using the RSS example requires the installation of several uncommon perl modules.

defmod

defmod <name> <type> <type-specific>

Define a device or modify it, if it already exists. E.g. to switch off a lamp 10 Minutes after the last message from the motion detector, you may use
define mdNtfy notify motionDetector defmod mdOff at +00:10 set lamp off
Using define here for the mdOff will generate an error if the motion detector triggers within the 10 minutes after the first event, as the mdOff at definition still exists.

delete

delete <devspec>

Delete something created with the define command. See the Device specification section for details on <devspec>.
After deletion, the global event "DELETED" will be generated, see the notify section for details.
Examples:
delete lamp

deleteattr

deleteattr <devspec> [<attrname>]

Delete either a single attribute (see the attr command) or all attributes for a device (if no <attrname> is defined). See the Device specification section for details on <devspec>.
After deleting the attribute, the global event "DELETEATTR" will be generated.
Examples:
deleteattr lamp follow-on-for-timer
deleteattr lamp

deletereading

deletereading <devspec> <readingname>

Delete the reading <readingname> for a device. <readingname> is a perl regular expression that must match the whole name of the reading. Use with greatest care! FHEM might crash if you delete vital readings of a device. See the Device specification section for details on <devspec>.

Examples:
deletereading mySensor temp1
deletereading mySensor temp\d+

displayattr

displayattr <devspec> [<attrname>]

Display either the value of a single attribute (see the attr command) or all attributes for a device (if no <attrname> is defined). See the Device specification section for details on <devspec>.
If more then one device is specified, then the device name will also included in the output.
Examples:
fhem> di WEB
menuEntries AlarmOn,/fhem?cmd=set%20alarm%20on
room Misc.
fhem> di WEB room
Misc.


get

get <devspec> <type-specific>

Ask a value directly from the device, and wait for an answer. In general, you can get a list of possible parameters by
get <device> ?
See the Device specification section for details on <devspec>.

Each device has different get parameters, see the corresponding device section for details.

include

include <filename>

Read in the file, and process every line as a fhem command. Note: only experts should use this command.

inform

inform {on|off|timer|raw} [regexp]

If set to on, and a device state changes, send a notification to the current client. This command can be used by other programs/modules to receive a notification.
The option timer prepends a timerstamp to the line. Note: this command is a nice way to check which events are generated, to help you when creating notify or FileLog entries.

list

list [devspec] [value]

Output a list of all definitions, all notify settings and all at entries. This is one of the few commands which return a string in a normal case. See the Device specification section for details on <devspec>.
If value is specified, then output this property (like DEF, TYPE, etc) or reading (actuator, measured-temp) for all devices from the devspec.

Example:

  fhem> list

  Type list  for detailed info.

  Internal:
    global               (Internal)

  FHZ:
    FHZ                  (fhtbuf: 23)

  FS20:
    Btn4                 (on-old-for-timer)
    Roll1                (on)
    Stehlampe            (off)

  FHT:
    fl                   (measured-temp: 21.1 (Celsius))

  KS300:
    out1                 (T: 2.9  H: 74  W: 2.2  R: 8.2  IR: no)

  at:
    at_rollup            (Next: 07:00:00)

  notify:
    ntfy_btn4            (active)

  FileLog:
    avglog               (active)

  

If specifying name, then a detailed status for name will be displayed, e.g.:

  fhem> list fl

  Internals:
    CODE       5102
    DEF        5102
    NAME       fl
    NR         15
    STATE      measured-temp: 21.1 (Celsius)
    TYPE       FHT
    IODev      FHZ
  Attributes:
    room       Heizung
  Readings:
    2006-11-02 09:45:56   actuator        19%
    [...]
  

modify

modify <name> <type-dependent-options>

Used to modify some definitions. Useful for changing some at or notify definitions. If specifying one argument to an at type definition, only the time part will be changed. In case of a notify type definition, only the regex part will be changed. All other values (state, attributes, etc) will remain intact. After modify, the global event "MODIFIED" will be generated.

Example:
define lampon at 19:00 set lamp on
modify lampon *19:00
modify lampon 19:00 set lamp on-for-timer 16

quit

quit

If used in a TCP/IP session, terminate the client session.
If used in a script, terminate the parsing of the current script.

Example:
quit

reload

reload <module>

Reload the given module from the module directory. It is a convenient way to test modules whithout restarting the program.

Example:
reload 99_PRIV

rename

rename <oldname> <newname>

Rename a device from the <oldname> to <newname>, together with its attributes. The global event RENAMED will be generated, see the notify section for details.

Example:
rename FHT_1234 fht.kitchen

rereadcfg

rereadcfg [fhem-config-file]

Re-read the active configuration file, or the optionally specified file.
The sequence: the statefile will be saved first, then all devices will be deleted, then the currently active config file (or the specified file) will be read and at last the statefile will be reloaded.
Upon completion it triggers the global:REREADCFG event. All existing connections up to the one issuing the rereadcfg will be closed.

Example:
rereadcfg

save

save [<configfile>]

Save first the statefile, then the configfile information. If a parameter is specified, it will be used instead the global configfile attribute.

Notes:
• save only writes out definitions and attributes, but no (set/get) commands which were previously part of the config file. If you need such commands after the initialization (e.g. FHTcode), you should trigger them via notify, when receiving the INITIALIZED event.
• save tries to preserve comments (lines starting with #) and include structures, but it won't work correctly if some of these files are not writeable.

set

set <devspec> <type-specific>

Set parameters of a device / send signals to a device. You can get a list of possible parameters by
set <name> ?
See the Device specification section for details on <devspec>. The set command returns only a value on error.

Each device has different set parameters, see the corresponding device section for details.


From featurelevel 5.7 on the set and setreading command replaces:
• [device:reading] with the corresponding reading of device, if both device and reading exists.
• [device:reading:d] same as above, but only the number is retrieved, see ReadingsNum
• {(perlExpression)} with the result of perlExpression. The $DEV variable is additionally available, designating the set device name.


Some modules support a common list of set extensions, and point in their documentation to this section. If the module itself implements one of the following commands, then the module-implementation takes precedence.
• on-for-timer <seconds>
  Issue the on command for the device, and after <seconds> the off command. For issuing the off command an internal timer will be scheduled, which is deleted upon a restart. To delete this internal timer without restart specify 0 as argument.
• off-for-timer <seconds>
  see on-for-timer above.
• on-till <timedet>
  Issue the on command for the device, and create an at definition with <timedet> (in the form HH:MM[:SS]) to set it off. This definition is visible, and its name is deviceName+"_till". To cancel the scheduled off, delete the at definition. Note: on-till is not active, if the specified time is after the current time, in order to make things like
  define morningLight at *06:00 set Lamp on-till {sunrise()}
  easy.
• on-till-overnight <timedet>
  Like on-till, but wont compare the current time with the timespec, so following will work:
  define nightLight at *{sunset()} set Lamp on-till-overnight 01:00
• off-till <timedet>
  see on-till above.
• off-till-overnight <timedet>
  see on-till-overnight above.
• blink <number> <blink-period>
  set the device on for <blink-period> then off for <blink-period> and repeat this <number> times. To stop blinking specify "0 0" as argument.
• intervals <from1>-<till1> <from2>-<till2>...
  set the device on for the specified intervals, which are all timespecs in the form HH:MM[:SS]. The intervals are space separated.
Examples:
set switch on-for-timer 12.5
set switch on-till {sunset()}
set switch blink 3 1
set switch intervals 08:00-12:00 13:00-18:00


setdefaultattr

setdefaultattr [<attrname> [<value>]]

Add a default attribute. Each device defined from now on will receive this attribute.
If no attrname is specified, then the default attribute list will be deleted.

Example to set the attribute "room kitchen" and "loglevel 4" to each of the lamps:
setdefaultattr room kitchen
setdefaultattr loglevel 4
define lamp1 FS20 1234 11
define lamp2 FS20 1234 12
define lamp3 FS20 1234 13
setdefaultattr


Notes:

• There is no way to delete a single default-attribute from the list

setreading

setreading <devspec> <reading> <value>

Set the reading <reading> for the device <name> to <value> without sending out commands to the device, but triggering events and eventMap/stateFormat transformations as usual. See the set command documentation for replacement description.

Examples:
setreading lamp state on
Note: setreading won't generate an event for device X, if it is called from a notify for device X. Use "sleep 0.1; setreading X Y Z" in this case.

setstate

setstate <devspec> <value>

Set the STATE entry for the device specified by <devspec>, which is used for displaying the device state in different frontends. No signals will be sent to the device, no events will be generated, and no eventMap or stateFormat translation will be done either. This command is also used in the statefile. See the Device specification section for details on <devspec>.

Examples:
setstate lamp on

shutdown

shutdown [restart|exitValue]

Shut down the server (after saving the state information ). It triggers the global:SHUTDOWN event. If the optional restart parameter is specified, fhem tries to restart itself. exitValue may be important for start scripts.

Example:
shutdown
shutdown restart
shutdown 1

sleep

sleep <sec> [<id>] [quiet]

sleep followed by another command is comparable to a nameless at, it executes the following commands after waiting the specified time. The unit is seconds, with millisecond accuracy, as you can specify decimal places.

A sleep with an <id< will replace a sleep with the same <id< and can be canceled by cancel. When called in a notify/at/etc, then nonempty return values of the following commands are logged to the global logfile with loglevel 2.
If quiet is specified, then skip this logging.

Example:
define n3 notify btn3.* set lamp on;;sleep 1.5;;set lamp off
define a3 at +*00:05 set Windsensor 1w_measure;; sleep 2 quiet;; get Windsensor 1w_temp

Note: a sleep not followed by any command will block FHEM, is deprecated, and it issues a WARNING in the FHEM log.

trigger

trigger <devspec> <state>

Trigger a notify definition. See the Device specification section for details on <devspec>.

Example:
trigger btn3 on

global

The global device is used to set different global attributes. It will be automatically defined, it cannot be deleted or renamed and has no set or get parameters

Define
N/A

Set
N/A

Get
N/A

Attributes
• archivedir
• archivecmd
• nrarchive


• autoload_undefined_devices
  If set, automatically load the corresponding module when a message of this type is received. This is used by the autocreate device, to automatically create a fhem device upon receiving a corresponding message.


• autosave
  enable some modules to automatically trigger save after a configuration change, e.g. after a new device was created. Default is 1 (true), you can deactivate this feature by setting the value to 0.
• backupcmd
  You could pass the backup to your own command / script by using this attribute. If this attribute is specified, then it will be started as a shell command and passes a space separated list of files / directories as one argument to the command, like e.g.:
  
  "/etc/fhem.cfg /var/log/fhem/fhem.save /usr/share/fhem/contrib /usr/share/fhem/FHEM /usr/share/fhem/foo /usr/share/fhem/foobar /usr/share/fhem/www"
  Note: Your command / script has to return the string "backup done" or everything else to report errors, to work properly with updatefhem!
  This Attribute is used by the backup command.
  Example:
  
  attr global backupcmd /usr/local/bin/myBackupScript.sh


• backupdir
  A folder to store the compressed backup file. This Attribute is used by the backup command.
  Example:
  
  attr global backupdir /Volumes/BigHD


• backupsymlink
  If this attribute is set to everything else as "no", the archive command tar will support symlinks in your backup. Otherwise, if this attribute is set to "no" symlinks are ignored by tar. This Attribute is used by the backup command.
  Example:
  
  attr global backupsymlink yes


• blockingCallMax
  Limit the number of parallel running processes started by the BlockingCall FHEM helper routine. Useful on limited hardware.


• configfile
  Contains the name of the fhem configuration file. If save is called without argument, then the output will be written to this file.


• commandref
  If set to "full" (default), then a full commandref will be generated after each update. If set to modular, there is only a short description at the beginning, and the module documentation is loaded from FHEM dynamically.


• dnsServer
  Contains the IP address of the DNS Server. If some of the modules or user code calls the HttpUtils_NonblockingGet function, and this attribute is set, then FHEM specific nonblocking code will be used to resolve the given address. If this attribute is not set, the blocking OS implementation (inet_aton and gethostbyname) will be used.


• holiday2we
  If this attribute is set, then the $we variable will be true, if the value of the holiday variable referenced by this attribute is not none.
  Example:
  
  attr global holiday2we hessen


• featurelevel
  Enable/disable old or new features, based on FHEM version. E.g. the $value hash for notify is only set for featurelevel up to 5.6, as it is deprecated, use the Value() function instead.


• lastinclude
  If this attribute is set, then the last command of the generated configfile (see the save command) will be
  include <lastinclude-value>
  This attribute is DEPRECATED and valid for featurelevel up to 5.6, use notify, with the INITIALIZED event to execute commands after initialization.


• logfile
  Specify the logfile to write. You can use "-" for stdout, in this case the server won't background itself.
  The logfile name can also take wildcards for easier logfile rotation, see the FileLog section. Just apply the archivecmd / archivedir / nrarchive attributes to the global device as you would do for a FileLog device.
  You can access the current name of the logfile with { $currlogfile }.


• modpath
  Specify the path to the modules directory FHEM. The path does not contain the directory FHEM. Upon setting the attribute, the directory will be scanned for filenames of the form NN_<NAME>.pm, and make them available for device definition under <NAME>. If the first device of type <NAME> is defined, the module will be loaded, and its function with the name <NAME>_Initialize will be called. Exception to this rule are modules with NN=99, these are considered to be utility modules containing only perl helper functions, they are loaded at startup (i.e. modpath attribute definition time).


• motd
  Message Of The Day. Displayed on the homescreen of the FHEMWEB package, or directly after the telnet logon, before displaying the fhem> prompt. SecurityCheck is setting motd if it is not defined upon startup, to avoid this set the motd value to none. motd is also used to show collected error messages upon fhem start.


• mseclog
  If set, the timestamp in the logfile will contain a millisecond part.


• nofork
  If set and the logfile is not "-", do not try to background. Needed on some Fritzbox installations, and it will be set automatically for Windows.


• pidfilename
  Write the process id of the perl process to the specified file. The server runs as a daemon, and some distributions would like to check by the pid if we are still running. The file will be deleted upon shutdown.


• sendStatistics
  
• statefile
  Set the filename where the state and certain at information will be saved before shutdown. If it is not specified, then no information will be saved.


• title
  
• uniqueID
  
• userattr
  A space separated list which contains the names of additional attributes for all devices. Without specifying them you will not be able to set them (in order to prevent typos).
  userattr can also specified for other devices, in this case these additinal attribute names are only valid for this device.


• dupTimeout
  Define the timeout for which 2 identical events from two different receiver are considered a duplicate. Default is 0.5 seconds.


• showInternalValues
  Show data used for internal computations. If the name of an internal value, reading or attribute starts with dot (.), then it is normally hidden, and will only be visible, if this attribute is set to 1. The attribute is checked by the list command, by the FHEMWEB room overview and by xmllist.


• sslVersion
  Specifies the accepted cryptography algorithms by all modules using the TcpServices helper module. The current default TLSv12:!SSLv3 is thought to be more secure than the previously used SSLv23:!SSLv3:!SSLv2, but it causes problems with some not updated web services.


• stacktrace
  if set (to 1), dump a stacktrace to the log for each "PERL WARNING".


• restartDelay
  set the delay for shutdown restart, default is 2 (seconds).



Events:
• INITIALIZED
  after initialization is finished.
• REREADCFG
  after the configuration is reread.
• SAVE
  before the configuration is saved.
• SHUTDOWN
  before FHEM is shut down.
• DEFINED <devname>
  after a device is defined.
• DELETED <devname>
  after a device was deleted.
• RENAMED <old> <new>
  after a device was renamed.
• UNDEFINED <defspec>
  upon reception of a message for an undefined device.
• MODIFIED <defspec>
  after a device modification.
• UPDATE
  after an update is completed.

ALL3076

Note: this module needs the HTTP::Request and LWP::UserAgent perl modules.

Define
define <name> ALL3076 <ip-address>

Defines an Allnet 3076 device (Dimmable lightswitch) via its ip address or dns name

Examples:
define lamp1 ALL3076 192.168.1.200


Set
set <name> <value>

where value is one of:


    dimdown
    dim10%
    dim20%
    dim30%
    dim40%
    dim50%
    dim60%
    dim70%
    dim80%
    dim90%
    dim100%
    dim[0-100]%
    dimup
    off
    on
    toggle
    

Examples:
set lamp1 on
set lamp1 dim11%
set lamp2 toggle


Notes:
• Toggle is special implemented. List name returns "on" or "off" even after a toggle command

ALL4000T

Note: this module requires the following perl modules: XML::Simple LWP::UserAgent HTTP::Request.

Define
define <name> ALL4000T <ip-address> <port> <delay>

Defines a temperature sensor connected on an Allnet 4000 device via its ip address and port. Use the delay argument to define the delay between polls.

Examples:
define AUSSEN.POOL.TEMP.vorlauf ALL4000T 192.168.68.20 t2 120

ALL4027

Note: this module needs the HTTP::Request and LWP::UserAgent perl modules.

Define
define <name> ALL4027 <ip-address> <port> <relay_nr> <delay>

Defines an Allnet 4027 device (Box with 8 relays) connected to an ALL4000 via its ip address. The status of the device is also pooled (delay interval), because someone else is able to change the state via the webinterface of the device.

Examples:
define lamp1 ALL4027 192.168.8.200 0 7 60


Set
set <name> <value>

where value is one of:


    off
    on
    on-for-timer <Seconds>
    toggle
    

Examples:
set poolpump on


Notes:
• Toggle is special implemented. List name returns "on" or "off" even after a toggle command

AMAD

AMAD - Automagic Android Device
This module integrates Android devices into FHEM and displays several settings using the Android app "Automagic". Automagic is comparable to the "Tasker" app for automating tasks and configuration settings. But Automagic is more user-friendly. The "Automagic Premium" app currently costs EUR 2.90.
Any information retrievable by Automagic can be displayed in FHEM by this module. Just define your own Automagic-"flow" and send the data to the AMADCommBridge. One even can control several actions on Android devices.
To be able to make use of all these functions the Automagic app and additional flows need to be installed on the Android device. The flows can be retrieved from the FHEM directory, the app can be bought in Google Play Store.

How to use AMAD?
• install the "Automagic Premium" app from the Google Play store.
• install the flowset 74_AMADautomagicFlowset$VERSION.xml from the directory $INSTALLFHEM/FHEM/lib/ on your Android device and activate.

Now you need to define a device in FHEM.

Define

define <name> AMAD <IP-ADDRESS> <WLANAP-SSID(s)>

Example:

define WandTabletWohnzimmer AMAD 192.168.0.23 TuxNetAP,Opa@@Zu@@Hause


With this command two new AMAD devices in a room called AMAD are created. The parameter <IP-ADDRESS< defines the IP address of your Android device, parameter WLANAP-SSID defines the SSID(s) of the WLAN(s) from which the FHEM server can be reached. Multiple SSID can be defined. They need to be separated by a comma (,). If a SSID contains spaces replace these spaces by a double at-sign (@@). For Android devices connected by LAN use "usb-ethernet" as SSID. The second device created is the AMADCommBridge which serves as a communication device from each Android device to FHEM.
!!!Coming Soon!!! The communication port of each AMAD device may be set by the definition of the "port" attribute. One needs background knowledge of Automagic and HTTP requests as this port will be set in the HTTP request trigger of both flows, therefore the port also needs to be set there.
The communication port of the AMADCommBridge device can easily be changed within the attribut "port".

AMAD Communication Bridge
Creating your first AMAD device automatically creates the AMADCommBridge device in the room AMAD. With the help of the AMADCommBridge any Android device communicates initially to FHEM.To make the IP addresse of the FHEM server known to the Android device, the FHEM server IP address needs to be configured in the AMADCommBridge. WITHOUT THIS STEP THE AMADCommBridge WILL NOT WORK PROPERLY.
Please us the following command for configuration of the FHEM server IP address in the AMADCommBridge: set AMADCommBridge fhemServerIP <FHEM-IP>.
Additionally the expertMode may be configured. By this setting a direct communication with FHEM will be established without the restriction of needing to make use of a notify to execute set commands.


You are finished now! After 15 seconds latest the readings of your AMAD Android device should be updated. Consequently each 15 seconds a status request will be sent. If the state of your AMAD Android device does not change to "active" over a longer period of time one should take a look into the log file for error messages.


Readings
• airplanemode - on/off, state of the aeroplane mode
• androidVersion - currently installed version of Android
• automagicState - state of the Automagic App (prerequisite Android >4.3). In case you have Android >4.3 and the reading says "not supported", you need to enable Automagic inside Android / Settings / Sound & notification / Notification access
• batteryHealth - the health of the battery (1=unknown, 2=good, 3=overheat, 4=dead, 5=over voltage, 6=unspecified failure, 7=cold)
• batterytemperature - the temperature of the battery
• bluetooth - on/off, bluetooth state
• checkActiveTask - state of an app (needs to be defined beforehand). 0=not active or not active in foreground, 1=active in foreground, see note below
• connectedBTdevices - list of all devices connected via bluetooth
• connectedBTdevicesMAC - list of MAC addresses of all devices connected via bluetooth
• currentMusicAlbum - currently playing album of mediaplayer
• currentMusicApp - currently playing player app (Amazon Music, Google Play Music, Google Play Video, Spotify, YouTube, TuneIn Player, Aldi Life Music)
• currentMusicArtist - currently playing artist of mediaplayer
• currentMusicIcon - cover of currently play albumNoch nicht fertig implementiert
• currentMusicState - state of currently/last used mediaplayer
• currentMusicTrack - currently playing song title of mediaplayer
• daydream - on/off, daydream currently active
• deviceState - state of Android devices. unknown, online, offline.
• doNotDisturb - state of do not Disturb Mode
• dockingState - undocked/docked, Android device in docking station
• flow_SetCommands - active/inactive, state of SetCommands flow
• flow_informations - active/inactive, state of Informations flow
• flowsetVersionAtDevice - currently installed version of the flowsets on the Android device
• intentRadioName - name of the most-recent streamed intent radio
• intentRadioState - state of intent radio player
• keyguardSet - 0/1 keyguard set, 0=no 1=yes, does not indicate whether it is currently active
• lastSetCommandError - last error message of a set command
• lastSetCommandState - last state of a set command, command send successful/command send unsuccessful
• lastStatusRequestError - last error message of a statusRequest command
• lastStatusRequestState - ast state of a statusRequest command, command send successful/command send unsuccessful
• nextAlarmDay - currently set day of alarm
• nextAlarmState - alert/done, current state of "Clock" stock-app
• nextAlarmTime - currently set time of alarm
• powerLevel - state of battery in %
• powerPlugged - 0=no/1,2=yes, power supply connected
• screen - on locked,unlocked/off locked,unlocked, state of display
• screenBrightness - 0-255, level of screen-brightness
• screenFullscreen - on/off, full screen mode
• screenOrientation - Landscape/Portrait, screen orientation (horizontal,vertical)
• screenOrientationMode - auto/manual, mode for screen orientation
• state - current state of AMAD device
• userFlowState - current state of a Flow, established under setUserFlowState Attribut
• volume - media volume setting
• volumeNotification - notification volume setting

Prerequisite for using the reading checkActivTask the package name of the application to be checked needs to be defined in the attribute checkActiveTask. Example: attr Nexus10Wohnzimmer checkActiveTask com.android.chrome für den Chrome Browser.




Set
• activateVoiceInput - start voice input on Android device
• bluetooth - on/off, switch bluetooth on/off
• clearNotificationBar - All/Automagic, deletes all or only Automagic notifications in status bar
• currentFlowsetUpdate - start flowset update on Android device
• installFlowSource - install a Automagic flow on device, XML file must be stored in /tmp/ with extension xml. Example: set TabletWohnzimmer installFlowSource WlanUebwerwachen.xml
• doNotDisturb - sets the do not Disturb Mode, always Disturb, never Disturb, alarmClockOnly alarm Clock only, onlyImportant only important Disturbs
• mediaAmazonMusic - play/stop/next/back , controlling the amazon music media player
• mediaGoogleMusic - play/stop/next/back , controlling the google play music media player
• mediaSpotifyMusic - play/stop/next/back , controlling the spotify media player
• nextAlarmTime - sets the alarm time. Only valid for the next 24 hours.
• notifySndFile - plays a media-file which by default needs to be stored in the folder "/storage/emulated/0/Notifications/" of the Android device. You may use the attribute setNotifySndFilePath for defining a different folder.
• screenBrightness - 0-255, set screen brighness
• screenMsg - display message on screen of Android device
• sendintent - send intent string Example: set $AMADDEVICE sendIntent org.smblott.intentradio.PLAY url http://stream.klassikradio.de/live/mp3-192/stream.klassikradio.de/play.m3u name Klassikradio, first parameter contains the action, second parameter contains the extra. At most two extras can be used.
• statusRequest - Get a new status report of Android device. Not all readings can be updated using a statusRequest as some readings are only updated if the value of the reading changes.
• timer - set a countdown timer in the "Clock" stock app. Only seconds are allowed as parameter.
• ttsMsg - send a message which will be played as voice message
• userFlowState - set Flow/s active or inactive,set Nexus7Wohnzimmer Badezimmer:inactive vorheizen or set Nexus7Wohnzimmer Badezimmer vorheizen,Nachtlicht Steven:inactive
• vibrate - vibrate Android device
• volume - set media volume. Works on internal speaker or, if connected, bluetooth speaker or speaker connected via stereo jack
• volumeNotification - set notifications volume

Set (depending on attribute values)
• changetoBtDevice - switch to another bluetooth device. Attribute setBluetoothDevice needs to be set. See note below!
• openApp - start an app. attribute setOpenApp
• openURL - opens a URLS in the standard browser as long as no other browser is set by the attribute setOpenUrlBrowser.Example: attr Tablet setOpenUrlBrowser de.ozerov.fully|de.ozerov.fully.MainActivity, first parameter: package name, second parameter: Class Name
• screen - on/off/lock/unlock, switch screen on/off or lock/unlock screen. In Automagic "Preferences" the "Device admin functions" need to be enabled, otherwise "Screen off" does not work. attribute setScreenOnForTimer changes the time the display remains switched on!
• screenFullscreen - on/off, activates/deactivates full screen mode. attribute setFullscreen
• screenLock - Locks screen with request for PIN. attribute setScreenlockPIN - enter PIN here. Only use numbers, 4-16 numbers required.
• screenOrientation - Auto,Landscape,Portait, set screen orientation (automatic, horizontal, vertical). attribute setScreenOrientation
• system - issue system command (only with rooted Android devices). reboot,shutdown,airplanemodeON (can only be switched ON) attribute root, in Automagic "Preferences" "Root functions" need to be enabled.
• setNotifySndFilePath - set systempath to notifyfile (default /storage/emulated/0/Notifications/
• setTtsMsgSpeed - set speaking speed for TTS (Value between 0.5 - 4.0, 0.5 Step) default is 1.0

To be able to use "openApp" the corresponding attribute "setOpenApp" needs to contain the app package name.

To be able to switch between bluetooth devices the attribute "setBluetoothDevice" needs to contain (a list of) bluetooth devices defined as follows: attr <DEVICE> BTdeviceName1|MAC,BTDeviceName2|MAC No spaces are allowed in any BTdeviceName. Defining MAC please make sure to use the character : (colon) after each second digit/character.
Example: attr Nexus10Wohnzimmer setBluetoothDevice Logitech_BT_Adapter|AB:12:CD:34:EF:32,Anker_A3565|GH:56:IJ:78:KL:76


state
• initialized - shown after initial define.
• active - device is active.
• disabled - device is disabled by the attribute "disable".



Further examples and reading:

Wiki page for AMAD (german only)

Alarm

FHEM module to set up a House Alarm System with 8 different alarm levels

Define

define <name> Alarm
Defines the Alarm system.

Set

• set <name> canceled <level>
  cancels an alarm of level <level>, where <level> = 0..7
• set <name> armed <level>
set <name> disarmed <level>
  sets the alarm of level <level> to armed (i.e., active) or disarmed (i.e., inactive), where <level> = 0..7
• set <name> locked
set <name> unlocked
  sets the lockstate of the alarm module to locked (i.e., alarm setups may not be changed) resp. unlocked (i.e., alarm setups may be changed>)

Get

• get <name> version
  Display the version of the module

Attributes

• attr <name> hiddenroom <string>
  Room name for hidden alarm room (containing only the Alarm device), default: AlarmRoom
• attr <name> hiddenroom <string>
  Room name for public alarm room (containing sensor/actor devices), default: Alarm
• attr <name> lockstate locked|unlocked
  locked means that alarm setups may not be changed, unlocked means that alarm setups may be changed>
• attr <name> statedisplay simple,color,table,none
  defines how the state of all eight alarm levels is shown. Example for the case when only alarm no. 2 is raised:
  • simple=OOXOOOOO
  • color= 0 1 2 3 4 5 6 7
  • table (ATTENTION: TABLE MOMENTARILY REMOVED)
  • none=no state display
• attr <name> armdelay mm:ss
  time until the arming of an alarm becomes operative (0:00 - 9:59 allowed)
• attr <name> armwait action
  FHEM action to be carried out immediately after the arm event
• attr <name> armact action
  FHEM action to be carried out at the arme event after the delay time
• attr <name> disarmact action
  FHEM action to be carried out on the disarming of an alarm
• attr <name> cancelact action
  FHEM action to be carried out on the canceling of an alarm
• For each of the 8 alarm levels, several attributes hold the alarm setup. They should not be changed by hand, but through the web interface to avoid confusion: level<level>start, level<level>end, level<level>msg, level<level>xec, level<level>onact, level<level>offact
• Standard attributes alias, comment, event-on-update-reading, event-on-change-reading, room, eventMap, loglevel, webCmd

BDKM

BDKM is a module supporting Buderus Logamatic KM gateways similar to the km200 module. For installation of the gateway see fhem km200 internet wiki
Compared with the km200 module the code of the BDKM module is more compact and has some extra features. It has the ablility to define how often a gateway ID is polled, which FHEM reading (alias) is generated for a gateway ID and which minimum difference to the last reading must exist to generate a new reading (see attributes).
It determines value ranges, allowed values and writeability from the gateway supporting FHEMWEB and readingsGroup when setting Values (drop down value menues).
On definition of a BDKM device the gateway is connected and a full poll collecting all IDs is done. This takes about 20 to 30 seconds. After that the module knows all IDs reported by the gateway. To examine these IDs just type:
get myBDKM INFO
These IDs can be used with the PollIds attribute to define if and how the IDs are read during the poll cycle.
All IDs can be mapped to own short readings.

Define
define <name> BDKM <IP-address|hostname> <GatewayPassword> <PrivatePassword> <MD5-Salt>
or
define <name> BDKM <IP-address|hostname> <AES-Key>


<name> : Name of device
<IP-address> : The IP adress of your Buderus gateway
<GatewayPassword> : The gateway password as printed on case of the gateway s.th. of the form: xxxx-xxxx-xxxx-xxxx
<PrivatePassword> : The private password as set with the buderus App
<MD5-Salt> : MD5 salt for the crypt algorithm you want to use (hex string like 867845e9.....). Have a look for km200 salt 86 ...
AES-Key can be generated here:
https://ssl-account.com/km200.andreashahn.info


Set
set <name> <ID> <value> ...

where ID is a valid writeable gateway ID (See list command, or "get myBDKM INFO")
The set command first reads the the ID from the gateway and also triggers a FHEM readings if necessary. After that it is checked if the value is valid. Then the ID and value(s) are transfered to to the gateway. After waiting (attr ReadBackDelay milliseconds) the value is read back and checked against value to be set. If necessary again a FHEM reading may be triggered. The read back value or an error is returned by the command.
Examples:
set myBDKM /heatingCircuits/hc1/temporaryRoomSetpoint 22.0
or the aliased version of it (if /heatingCircuits/hc1/temporaryRoomSetpointee is aliased to RoomTemporaryDesiredTemp):
set myBDKM RoomTemporaryDesiredTemp 22.0
special to set time of gateway to the hosts date:
set myBDKM /gateway/DateTime now
aliased:
set myBDKM DateTime now




Get
get <name> <ID> <[raw|json]>...

where ID is a valid gateway ID or an alias to it. (See list command)
The get command reads the the ID from the gateway, triggeres readings if necessarry, and returns the value or an error if s.th. went wrong. While polling is done asychronously with a non blocking HTTP GET. The set and get functions use a blocking HTTP GET/POST to be able to return a value directly to the user. Normaly get and set are only used by command line or when setting values via web interface.
With the raw option the whole original decoded data of the ID (as read from the gateway) is returned as a string.
With the json option a perl hash reference pointing to the JSON data is returned (take a look into the module if you want to use that)

Examples:
get myBDKM /heatingCircuits/hc1/temporaryRoomGetpoint
or the aliased version of it (see attr below):
get myBDKM RoomTemporaryDesiredTemp
get myBDKM DateTime
get myBDKM /gateway/instAccess
Spacial to get Infos about IDs known by the gateway and own configurations:
get myBDKM INFO
Everything matching /temp/ get myBDKM INFO temp
Everything matching /Heaven/ or /Hell/ get myBDKM INFO Heaven Hell
Everything known: get myBDKM INFO .*
Arguments to INFO are reqular expressions which are matched against all IDs and all aliases.



Attributes
• BaseInterval
  The interval time in seconds between poll cycles. It defaults to 120 seconds. Which means that every 120 seconds a new poll collects values of IDs which turn it is.


• ReadBackDelay
  Read back delay for the set command in milliseconds. This value defaults to 500 (0.5s). After setting a value, the gateway need some time before the value can be read back. If this delay is too short after writing you will get back the old value and not the expected new one. The default should work in most cases.


• HttpTimeout
  Timeout for all HTTP requests in seconds (polling, set, get). This defaults to 10s. If there is no answer from the gateway for HttpTimeout time an error is returned. If a HTTP request expires while polling an error log (level 2) is generated and the request is automatically restarted after 60 seconds.


• PollIds
  Without this attribute FHEM readings are NOT generated automatically!
  This attribute defines how and when IDs are polled within a base interval (set by atrribute BaseInterval).
  The attribute contains list of space separated IDs and options written as
  GatewayID:Modulo:Delta:Alias
  Where Gateway is the real gateway ID like "/gateway/DateTime".
  Modulo is the value which defines how often the GatewayID is polled from the gateway and checked for FHEM readings update. E.g. a value of 4 means that the ID is polled only every 4th cycle.
  Delta defines the minimum difference a polled value must have to the previous reading, before a FHEM reading with the new value is generated.
  Alias defines a short name for the GatewayID under which the gateway ID can be accessed. Also readings (Logfile entries) are generated with this short alias if set. If not set, the original ID is used.
  In detail:
  ID:1:0:Alias - poll every cycle, when difference >= 0 to previous reading (means always, also for strings) trigger FHEM reading to "Alias"
  ID:1::Alias - poll every cycle, no Delta set => trigger FHEM reading to "Alias" on value change only
  ID:0::Alias - update reading on startup once if reading changed (to the one prevously saved in fhem.save)
  ID:1:0.5:Alias - poll every cycle, when difference => 0.5 trigger a FHEM reading to "Alias"
  ID:15::Alias - poll every 15th cylce, update reading only if changed
  ID:::Alias - update reading on (get/set) only and only if value changed
  ID::0:Alias - update reading on (get/set) only and trigger reading always on get/set
  ID - without colons ":", poll every cycle, update reading allways (same as ID:1:0:)
  Also some usefull defaults can be set by the special keyword RC300DEFAULTS, RC35DEFAULTS, RC30DEFAULTS.
  As I don't know anything about RC35 or RC30 the later keywords are currently empty (please send me some info with "get myBDKM INFO" :-)
  Definitions set by the special keywords (see the module code for it) are overwritten by definitions later set in the attribute definition
  Example:
  attr myBDKM PollIds \
RC300DEFAULTS \
/gateway/DateTime:0::Date \
/system/info:0:0:\
/dhwCircuits/dhw1/actualTemp:1:0.2:WaterTemp
  
  Which means: Use RC300DEFAULTS, trigger FHEM reading "Date" when date has changed on startup only. Trigger FHEM reading "/system/info" (no aliasing) always on startup, poll water temperature every cycle and trigger FHEM reading "WaterTemp" when difference to last reading was at least 0.2 degrees.
  

BOSEST

BOSEST is used to control a BOSE SoundTouch system (one or more SoundTouch 10, 20 or 30 devices)

Note: The followig libraries are required for this module:
• libwww-perl
• libmojolicious-perl
• libxml-simple-perl
• libnet-bonjour-perl
• libev-perl

Use sudo apt-get install libwww-perl libmojolicious-perl libxml-simple-perl libnet-bonjour-perl libev-perl to install this libraries.
Please note: libmojolicious-perl must be >=5.54, but under wheezy is only 2.x avaible.
Use sudo apt-get install cpanminus and sudo cpanm Mojolicious to update to the newest version

Define
define <name> BOSEST

Example:
define bosesystem BOSEST
Defines BOSE SoundTouch system. All devices/speakers will show up after 60s under "Unsorted" in FHEM.


Set
set <name> <command> [<parameter>]
The following commands are defined for the devices/speakers (execpt autoAddDLNAServers is for the "main" BOSEST) :


General commands
• on   -   power on the device
• off   -   turn the device off
• power   -   toggle on/off
• volume [0...100] [+x|-x]   -   set the volume level in percentage or change volume by ±x from current level
• channel 0...20   -   select present to play
• saveChannel 07...20   -   save current channel to channel 07 to 20
• play   -   start/resume to play
• pause   -   pause the playback
• stop   -   stop playback
• nextTrack   -   play next track
• prevTrack   -   play previous track
• mute on|off|toggle   -   control volume mute
• bass 0...10   -   set the bass level
• recent 0...15   -   set number of names in the recent list in readings
• source bluetooth,bt-discover,aux mode, airplay   -   select a local source


• addDLNAServer Name1 [Name2] [Namex]   -   add DLNA servers Name1 (and Name2 to Namex) to the BOSE library
• removeDLNAServer Name1 [Name2] [Namex]   -   remove DLNA servers Name1 (and Name2 to Namex) to the BOSE library

Example: set BOSE_1234567890AB volume 25  Set volume on device with the name BOSE_1234567890AB



Timer commands:
• on-for-timer 1...x   -   power on the device for x seconds
• off-for-timer 1...x   -   turn the device off and power on again after x seconds
• on-till hh:mm:ss   -   power on the device until defined time
• off-till hh:mm:ss   -   turn the device off and power on again at defined time
• on-till-overneight hh:mm:ss   -   power on the device until defined time on the next day
• off-till-overneight hh:mm:ss   -   turn the device off at defined time on the next day

Example: set BOSE_1234567890AB on-till 23:00:00  Switches device with the name BOSE_1234567890AB now on and at 23:00:00 off



Multiroom commands:
• createZone deviceID   -   create multiroom zone (defines <name> as zoneMaster)
• addToZone deviceID   -   add device <name> to multiroom zone
• removeFromZone deviceID   -   remove device <name> from multiroom zone
• playEverywhere   -   play sound of device <name> on all others devices
• stopPlayEverywhere   -   stop playing sound on all devices

Example: set BOSE_1234567890AB playEverywhere  Starts Multiroom with device with the name BOSE_1234567890AB as master



TextToSpeach commands (needs Google Translate):
• speak "message" [0...100] [+x|-x] [en|de|xx]   -   Text to speak, optional with volume adjustment and language to use. The message to speak may have up to 100 letters
• speakOff "message" [0...100] [+x|-x] [en|de|xx]   -   Text to speak, optional with volume adjustment and language to use. The message to speak may have up to 100 letters. Device is switched off after speak
• ttsVolume [0...100] [+x|-x]   -   set the TTS volume level in percentage or change volume by ±x from current level
• ttsDLNAServer "DLNA Server"   -   set DLNA TTS server, only needed if the DLNA server is not the FHEM server, a DLNA server running on the same server as FHEM is automatically added to the BOSE library
• ttsDirectory "directory"   -   set DLNA TTS directory. FHEM user needs permissions to write to that directory.
• ttsLanguage en|de|xx   -   set default TTS language (default: en)
• ttsSpeakOnError 0|1   -   0=disable to speak "not available" text
• autoAddDLNAServers 0|1   -   1=automatically add all DLNA servers to BOSE library. This command is only for "main" BOSEST, not for devices/speakers!



Example: set BOSE_1234567890AB speakOff "Music is going to switch off now. Good night." 30 en  Speaks message at volume 30 and then switches off device.




Get
n/a

BRAVIA

This module controls a Sony TV device over ethernet. Devices of series starting from 2011 are supported.

Define
define <name> BRAVIA <ip-or-hostname> [<poll-interval>]

With definition of a BRAVIA device an internal task will be scheduled. This task pulls frequently the status and other information from the TV.
The intervall can be defined in seconds by an optional parameter <poll-intervall>. The default value is 45 seconds.

After definition of a device using this module it has to be registered as a remote control (set register).

As long as readings are not among the usual AV readings they are clustered:

s_*	: status
ci_*	: content information



The module contains predefined layouts for remotecontrol using PNG and SVG.


Set
set <name> <option> <value>

Options:
• channel
  List of all known channels. The module collects all visited channels. Channels can be loaded automtically with modells from 2013 and newer. (number of channels, see channelsMax).
• channelDown
  Switches a channel back.
• channelUp
  Switches a channel forward.
• mute
  Set mute if Upnp is activated.
• off
  Switches TV to off. State of device will have been set to "set_off" for 60 seconds or until off-status is pulled from TV.
• on
  Switches TV to on, with modells from 2013 using WOL. State of device will have been set to "set_on" for 60 seconds or until on-status is pulled from TV.
• pause
  Pauses a playing of a recording, of an internal App, etc.
• play
  Starts playing of a recording, of an internal App, etc.
• record
  Starts recording of current content.
• register
  One-time registration of Fhem as remote control in the TV.
  With requestFormat = "xml" registration works without parameter.
  With requestFormat = "json" registration has to be executed twice.
  The register option offers an additional input field:
  1. Call with empty input. A PIN for registration has to be shown on the TV.
  2. Insert PIN into input field and register again.
• requestFormat
  "xml" for xml based communication (modells from 2011 and 2012)
  "json" for communication with modells from 2013 and newer
• remoteControl
  Sends command directly to TV.
• statusRequest
  Retrieves current status information from TV.
• stop
  Stops recording, playing of an internal App, etc.
• toggle
  Toggles power status of TV.
• tvpause
  Activates Timeshift mode.
• upnp
  Activates Upnp service used to control volume.
• volume
  Straight setting of volume. Upnp service has to be activated.
• volumeDown
  Decreases volume.
• volumeUp
  Increases volume.

Attributes
attr <name> <attribute> <value>

Attributes:
• channelsMax
  Maximum amount of channels to be displayed, default is 50.
• macaddr
  Enables power on of TV using WOL.

BS

The module BS allows to collect data from a brightness sensor through a FHZ device. For details on the brightness sensor see busware wiki. You can have at most nine different brightness sensors in range of your FHZ.

The state contains the brightness in % (reading brightness) and the brightness in lux (reading lux). The flags reading is always zero. The meaning of these readings is explained in more detail on the above mentioned wiki page.

Define
define <name> BS <sensor#> [<RExt>]

<sensor#> is the number of sensor in the brightness sensor address system that runs from 1 to 9.

<RExt> is the value of the resistor on your brightness sensor in Ω (Ohm). The brightness reading in % is proportional to the resistance, the lux reading is proportional to the resistance squared. The value is optional. The default resistance is RExt= 50.000Ω.

Example:

define bs1 BS 1 40000


Set
N/A

Get
N/A

Attributes
• do_not_notify
• showtime
• model (bs)
• ignore
• readingFnAttributes

CALVIEW

This module creates a device with deadlines based on calendar-devices of the 57_Calendar.pm module. You need to install the perl-modul Date::Parse!

Actually the module supports only the "get <> next" function of the CALENDAR-Modul.

define <Name> CALVIEW <calendarname(s) separate with ','> <0 next; 1 next 2 for next ; 3 for next ; next > <updateintervall in sec (default 43200)>

define myView CALVIEW Googlecalendar next

define myView CALVIEW Googlecalendar,holiday next 900

set <Name> update

set myView update

this will manually update all readings from the given CALENDAR Devices

CM11

Note: this module requires the Device::SerialPort or Win32::SerialPort module.

Define
define <name> CM11 <serial-device>

CM11 is the X10 module to interface X10 devices with the PC.

The current implementation can evaluate incoming data on the powerline of any kind. It can send on, off, dimdown and dimup commands.

The name of the serial-device depends on your distribution. If serial-device is none, then no device will be opened, so you can experiment without hardware attached.
If you experience problems (for verbose 4 you get a lot of "Bad CRC message" in the log), then try to define your device as
define <name> FHZ <serial-device> strangetty

Example:
define x10if CM11 /dev/ttyUSB3



Set
set <name> reopen

Reopens the serial port.

Get
get <name> fwrev

Reads the firmware revision of the CM11 device. Returns error if the serial connection to the device times out. Can be used for error detection.

get <name> time

Reads the internal time of the device which is the total uptime (modulo one year), since fhem sets the time to 0.00:00:00 if the device requests the time to be set after being powered on. Returns error if the serial connection to the device times out. Can be used for error detection.

Attributes
• do_not_notify
• dummy
• model (CM11)

CO20

Module for measuring air quality with usb sticks based on the AppliedSensor iAQ-Engine sensor. Products currently know to work are the VOLTCRAFT CO-20, the Sentinel Haus Institut RaumluftWächter and the VELUX Raumluftfühler.
Probably works with all devices recognized as iAQ Stick (0x03eb:0x2013).

Notes:
• Device::USB hast to be installed on the FHEM host.
  It can be installed with 'cpan install Device::USB'
  or on debian with 'sudo apt-get install libdevice-usb-perl''
• FHEM has to have permissions to open the device. To configure this with udev rules see here: Install_AirSensor_Linux usb-sensors-linux
• Advanced features are only available after setting the attribute advanced.
  Almost all the hidden settings from the Windows application are implemented in this mode.
  Readout of values gathered in standalone mode is not possible yet.

Define
define <name> CO20 [bus:device]

Defines a CO20 device. bus:device hast to be used if more than one sensor is connected to the same host.

Examples:
define CO20 CO20


Readings
• voc
  CO2 equivalents in ppm
• debug
  debug value
• pwm
  pwm value
• r_h
  resistance of heating element in Ohm (?)
• r_s
  resistance of sensor element in Ohm (?)

Get
• update / air_data
  trigger an update
• flag_data
  get internal flag values
• knob_data
  get internal knob values
• stick_data
  get stick information

Set
• KNOB_CO2_VOC_level_warn1
  sets threshold for yellow led
• KNOB_CO2_VOC_level_warn2
  sets threshold for red led
• KNOB_Reg_Set
  internal value, affects voc reading
• KNOB_Reg_P
  internal pid value
• KNOB_Reg_I
  internal pid value
• KNOB_Reg_D
  internal pid value
• KNOB_LogInterval
  log interval for standalone mode
• KNOB_ui16StartupBits
  set to 0 for no automatic calibration on startup
• FLAG_WARMUP
  warmup time left in minutes
• FLAG_BURN_IN
  burn in time left in minutes
• FLAG_RESET_BASELINE
  reset voc baseline value
• FLAG_CALIBRATE_HEATER
  trigger calibration / burn in
• FLAG_LOGGING
  value count from external logging

Attributes
• interval
  the interval in seconds used to read updates [10..]. the default ist 300.
• retries
  number of retries on USB read/write failures [0..20]. the default is 3.
• timeout
  the USB connection timeout in milliseconds [250..10000]. the default is 1000.
• advanced
  1 -> enables most of the advanced settings and readings described here
• disable
  1 -> disconnect and stop polling

CUL

The CUL/CUN(O) is a family of RF devices sold by busware.de. With the opensource firmware culfw they are capable to receive and send different 433/868 MHz protocols (FS20/FHT/S300/EM/HMS/MAX!). It is even possible to use these devices as range extenders/routers, see the CUL_RFR module for details. Some protocols (FS20, FHT and KS300) are converted by this module so that the same logical device can be used, irrespective if the radio telegram is received by a CUL or an FHZ device. Other protocols (S300/EM) need their own modules. E.g. S300 devices are processed by the CUL_WS module if the signals are received by the CUL, similarly EMWZ/EMGZ/EMEM is handled by the CUL_EM module. It is possible to attach more than one device in order to get better reception, FHEM will filter out duplicate messages. Note: This module may require the Device::SerialPort or Win32::SerialPort module if you attach the device via USB and the OS sets strange default parameters for serial devices.

Define
define <name> CUL <device> <FHTID>

USB-connected devices (CUL/CUN):

<device> specifies the serial port to communicate with the CUL. The name of the serial-device depends on your distribution, under linux the cdc_acm kernel module is responsible, and usually a /dev/ttyACM0 device will be created. If your distribution does not have a cdc_acm module, you can force usbserial to handle the CUL by the following command:
modprobe usbserial vendor=0x03eb product=0x204b
In this case the device is most probably /dev/ttyUSB0.

You can also specify a baudrate if the device name contains the @ character, e.g.: /dev/ttyACM0@38400

If the baudrate is "directio" (e.g.: /dev/ttyACM0@directio), then the perl module Device::SerialPort is not needed, and FHEM opens the device with simple file io. This might work if the operating system uses sane defaults for the serial parameters, e.g. some Linux distributions and OSX.


Network-connected devices (CUN(O)):

<device> specifies the host:port of the device, e.g. 192.168.0.244:2323

If the device is called none, then no device will be opened, so you can experiment without hardware attached.
The FHTID is a 4 digit hex number, and it is used when the CUL talks to FHT devices or when CUL requests data. Set it to 0000 to avoid answering any FHT80b request by the CUL.

Set
• reopen
  Reopens the connection to the device and reinitializes it.


• raw
  Issue a CUL firmware command. See the this document for details on CUL commands.


• freq / bWidth / rAmpl / sens
  SlowRF mode only.
  Set the CUL frequency / bandwidth / receiver-amplitude / sensitivity
  Use it with care, it may destroy your hardware and it even may be illegal to do so. Note: The parameters used for RFR transmission are not affected.
  
  • freq sets both the reception and transmission frequency. Note: Although the CC1101 can be set to frequencies between 315 and 915 MHz, the antenna interface and the antenna of the CUL is tuned for exactly one frequency. Default is 868.3 MHz (or 433 MHz)
  • bWidth can be set to values between 58 kHz and 812 kHz. Large values are susceptible to interference, but make possible to receive inaccurately calibrated transmitters. It affects tranmission too. Default is 325 kHz.
  • rAmpl is receiver amplification, with values between 24 and 42 dB. Bigger values allow reception of weak signals. Default is 42.
  • sens is the decision boundary between the on and off values, and it is 4, 8, 12 or 16 dB. Smaller values allow reception of less clear signals. Default is 4 dB.


• hmPairForSec
  HomeMatic mode only.
  Set the CUL in Pairing-Mode for the given seconds. Any HM device set into pairing mode in this time will be paired with FHEM.


• hmPairSerial
  HomeMatic mode only.
  Try to pair with the given device. The argument is a 10 character string, usually starting with letters and ending with digits, printed on the backside of the device. It is not necessary to put the given device in learning mode if it is a receiver.


• led
  Set the CUL led off (00), on (01) or blinking (02).


• ITClock
  Set the IT clock for Intertechno V1 protocol. Default 250.


Get
• version
  returns the CUL firmware version


• uptime
  returns the CUL uptime (time since CUL reset)


• raw
  Issues a CUL firmware command, and waits for one line of data returned by the CUL. See the CUL firmware README document for details on CUL commands.


• fhtbuf
  CUL has a message buffer for the FHT. If the buffer is full, then newly issued commands will be dropped, and an "EOB" message is issued to the FHEM log. fhtbuf returns the free memory in this buffer (in hex), an empty buffer in the CUL V2 is 74 bytes, in CUL V3/CUN(O) 200 Bytes. A message occupies 3 + 2x(number of FHT commands) bytes, this is the second reason why sending multiple FHT commands with one set is a good idea. The first reason is, that these FHT commands are sent at once to the FHT.


• ccconf
  Read some CUL radio-chip (cc1101) registers (frequency, bandwidth, etc.), and display them in human readable form.


• cmds
  Depending on the firmware installed, CULs have a different set of possible commands. Please refer to the README of the firmware of your CUL to interpret the response of this command. See also the raw command.


• credit10ms
  One may send for a duration of credit10ms*10 ms before the send limit is reached and a LOVF is generated.


Attributes
• addvaltrigger
  Create triggers for additional device values. Right now these are RSSI and RAWMSG for the CUL family and RAWMSG for the FHZ.


• connectCommand
  raw culfw command sent to the CUL after a (re-)connect of the USB device, and sending the usual initialization needed for the configured rfmode.
• do_not_notify
• dummy
• hmId
  Set the HomeMatic ID of this device. If this attribute is absent, the ID will be F1<FHTID>. Note 1: After setting or changing this attribute you have to relearn all your HomeMatic devices. Note 2: The value must be a 6 digit hex number, and 000000 is not valid. FHEM won't complain if it is not correct, but the communication won't work.


• hmProtocolEvents
  Generate events for HomeMatic protocol messages. These are normally used for debugging, by activating "inform timer" in a telnet session, or looking at the Event Monitor window in the FHEMWEB frontend.
  Example:
  2012-05-17 09:44:22.515 CUL CULHM RCV L:0B N:81 CMD:A258 SRC:...... DST:...... 0000 (TYPE=88,WAKEMEUP,BIDI,RPTEN)


• longids
  Comma separated list of device-types for CUL that should be handled using long IDs. This additional ID allows it to differentiate some weather sensors, if they are sending on the same channel. Therefore a random generated id is added. If you choose to use longids, then you'll have to define a different device after battery change. Default is not to use long IDs.
  Modules which are using this functionality are for e.g. : 14_Hideki, 41_OREGON, 14_CUL_TCM97001, 14_SD_WS07.
  Examples:
  
  # Do not use any long IDs for any devices (this is default):
attr cul longids 0
# Use long IDs for all devices:
attr cul longids 1
# Use longids for SD_WS07 devices.
# Will generate devices names like SD_WS07_TH_3 for channel 3.
attr cul longids SD_WS07


• model (CUL,CUN,etc)
• sendpool
  If using more than one CUL for covering a large area, sending different events by the different CUL's might disturb each other. This phenomenon is also known as the Palm-Beach-Resort effect. Putting them in a common sendpool will serialize sending the events. E.g. if you have three CUN's, you have to specify following attributes:
  attr CUN1 sendpool CUN1,CUN2,CUN3
attr CUN2 sendpool CUN1,CUN2,CUN3
attr CUN3 sendpool CUN1,CUN2,CUN3
  


• rfmode
  Configure the RF Transceiver of the CUL (the CC1101). Available arguments are:
  • SlowRF
    To communicate with FS20/FHT/HMS/EM1010/S300/Hoermann devices @1 kHz datarate. This is the default.
  • HomeMatic
    To communicate with HomeMatic type of devices @10 kHz datarate.
  • MAX
    To communicate with MAX! type of devices @10 kHz datarate.
  • WMBus_S
  • WMBus_T
    To communicate with Wireless M-Bus devices like water, gas or electrical meters. Wireless M-Bus uses two different communication modes, S-Mode and T-Mode. While in this mode, no reception of other protocols like SlowRF or HomeMatic is possible. See also the WMBUS FHEM Module.


• showtime
• readingFnAttributes

CUL_EM

The CUL_EM module interprets EM type of messages received by the CUL, notably from EMEM, EMWZ or EMGZ devices.

Define
define <name> CUL_EM <code> [corr1 corr2 CostPerUnit BasicFeePerMonth]

<code> is the code which must be set on the EM device. Valid values are 1 through 12. 1-4 denotes EMWZ, 5-8 EMEM and 9-12 EMGZ devices.

corr1 is used to correct the current number, corr2 for the total number.
• for EMWZ devices you should specify the rotation speed (R/kW) of your watt-meter (e.g. 150) for corr1 and 12 times this value for corr2
• for EMEM devices the corr1 value is 0.01, and the corr2 value is 0.001

CostPerUnit and BasicFeePerMonth are used to compute your daily and monthly fees. Your COST will appear in the log, generated once daily (without the basic fee) or month (with the bassic fee included). Your definition should look like e.g.:
define emwz 1 75 900 0.15 12.50

and the Log looks like:
CUM_DAY: 6.849 CUM: 60123.4 COST: 1.02
CUM_MONTH: 212.319 CUM: 60123.4 COST: 44.34

Tip: You can configure your EMWZ device to show in the CUM column of the STATE reading the current reading of your meter. For this purpose: multiply the current reading (from the real device) with the corr1 value (RperKW), and subtract the RAW CUM value from it. Now set the basis reading of your EMWZ device (named emwz) to this value.


Set
N/A

Get
N/A

Attributes
• ignore


• do_not_notify


• showtime


• model (EMEM,EMWZ,EMGZ)


• IODev


• eventMap


• readingFnAttributes


• maxPeak <number>
  Specifies the maximum possible peak value for the EM meter ("TOP:" value in logfile). Peak values greater than this value are considered as EM read errors and are ignored. For example if it's not possible to consume more than 40kW of power set maxPeak to 40 to make the readings of the power meter more robust.


• CounterOffset
  Specifies the difference between true (gas) meter value and value reported by the EMGZ.
  CounterOffset = true Value - Reading "total"
  Example:
  attr Gaszaehler CounterOffset 15427.434
  

CUL_FHTTK

This module handles messages from the FHT80 TF "Fenster-Tür-Kontakt" (Window-Door-Contact) which are normally only acted upon by the FHT80B. With this module, FHT80 TFs are in a limited way (see Wiki for detailed explanation of TF's mode of operation) usable similar to HMS100 TFK. The name of the module was chosen as a) only CUL will spill out the datagrams and b) "TF" designates usually temperature+humidity sensors (no clue, why ELV didn't label this one "TFK" like with FS20 and HMS).

As said before, FHEM can receive FHT80 TF radio (868.35 MHz) messages only through an CUL device, so this must be defined first.

With the latest build on SVN or next official version 1.62 or higher, it is possible to send out FHT80 TF data with a CUL or simular devices. So it can be simulate up to four window sensor with one device (see FHEM Wiki). To setup a window sensor, you have to add and/or change the attribute "model" to dummy. The 6 digit hex number must not equal to FHTID.

Define
define <name> CUL_FHTTK <devicecode>

<devicecode> is a six digit hex number, given to the FHT80 TF during production, i. e. it is not changeable. (Yes, it keeps this code after changing batteries as well.)
Examples:
define TK_TEST CUL_FHTTK 965AB0

Set
Only available, if model is set to dummy.

set <name> <value>

where value is one of:

Syncing # start the sync with FHT80B (activate FHT80B sync mode before) - state after syncing is Closed
Closed # set window state to Closed
Open # set window state to Open


Get
No get implemented yet ...

Attributes
• do_not_notify


• verbose


• model
  Possible values are: FHT80TF, FHT80TF-2, dummy (value, which allow to simulate a window sensor)


• showtime


• IODev


• ignore


• eventMap


• readingFnAttributes

CUL_HM

Support for eQ-3 HomeMatic devices via the CUL or the HMLAN.

Define
define <name> CUL_HM <6-digit-hex-code|8-digit-hex-code>

Correct device definition is the key for HM environment simple maintenance.
Background to define entities:
HM devices has a 3 byte (6 digit hex value) HMid - which is key for addressing. Each device hosts one or more channels. HMid for a channel is the device's HMid plus the channel number (1 byte, 2 digit) in hex. Channels should be defined for all multi-channel devices. Channel entities cannot be defined if the hosting device does not exist
Note: FHEM mappes channel 1 to the device if it is not defined explicitely. Therefore it does not need to be defined for single channel devices.
Note: if a device is deleted all assotiated channels will be removed as well.
An example for a full definition of a 2 channel switch is given below:

define livingRoomSwitch CUL_HM 123456
define LivingroomMainLight CUL_HM 12345601
define LivingroomBackLight CUL_HM 12345602


livingRoomSwitch is the device managing communication. This device is defined prior to channels to be able to setup references.
LivingroomMainLight is channel 01 dealing with status of light, channel peers and channel assotiated register. If not defined channel 01 is covered by the device entity.
LivingRoomBackLight is the second 'channel', channel 02. Its definition is mandatory to operate this function.

Sender specials: HM threats each button of remotes, push buttons and similar as channels. It is possible (not necessary) to define a channel per button. If all channels are defined access to pairing informatin is possible as well as access to channel related register. Furthermore names make the traces better readable.

define may also be invoked by the autocreate module, together with the necessary subType attribute. Usually you issue a hmPairForSec and press the corresponding button on the device to be paired, or issue a hmPairSerial set command if the device is a receiver and you know its serial number. Autocreate will then create a fhem device and set all necessary attributes. Without pairing the device will not accept messages from fhem. fhem may create the device even if the pairing is not successful. Upon a successful pairing you'll see a CommandAccepted entry in the details section of the CUL_HM device.

If you cannot use autocreate, then you have to specify:

• the <6-digit-hex-code>or HMid+ch <8-digit-hex-code>
  It is the unique, hardcoded device-address and cannot be changed (no, you cannot choose it arbitrarily like for FS20 devices). You may detect it by inspecting the fhem log.
• the subType attribute
  which is one of switch dimmer blindActuator remote sensor swi pushButton threeStateSensor motionDetector keyMatic winMatic smokeDetector
Without these attributes fhem won't be able to decode device messages appropriately.

Notes
• If the interface is a CUL device, the rfmode attribute of the corresponding CUL/CUN device must be set to HomeMatic. Note: this mode is BidCos/Homematic only, you will not receive FS20/HMS/EM/S300 messages via this device. Previously defined FS20/HMS etc devices must be assigned to a different input device (CUL/FHZ/etc).
• Currently supported device families: remote, switch, dimmer, blindActuator, motionDetector, smokeDetector, threeStateSensor, THSensor, winmatic. Special devices: KS550, HM-CC-TC and the KFM100.
• Device messages can only be interpreted correctly if the device type is known. fhem will extract the device type from a "pairing request" message, even if it won't respond to it (see hmPairSerial and hmPairForSec to enable pairing). As an alternative, set the correct subType and model attributes, for a list of possible subType values see "attr hmdevice ?".
• The so called "AES-Encryption" is in reality a signing request: if it is enabled, an actor device will only execute a received command, if a correct answer to a request generated by the actor is received. This means:
  • Reaction to commands is noticably slower, as 3 messages are sent instead of one before the action is processed by the actor.
  • Every command and its final ack from the device is sent in clear, so an outside observer will know the status of each device.
  • The firmware implementation is buggy: the "toggle" event is executed before the answer for the signing request is received, at least by some switches (HM-LC-Sw1-Pl and HM-LC-SW2-PB-FM).
  • The HMLAN configurator will answer signing requests by itself, and if it is configured with the 3-byte address of a foreign CCU which is still configurerd with the default password, it is able to answer signing requests correctly.
  • AES-Encryption is useable with a HMLAN or a CUL. When using a CUL, the perl-module Crypt::Rijndael needs to be installed. Due to the issues above I do not recommend using Homematic encryption at all.

Set
Note: devices which are normally send-only (remote/sensor/etc) must be set into pairing/learning mode in order to receive the following commands.

Universal commands (available to most hm devices):
• assignHmKey
  Initiates a key-exchange with the device, exchanging the old AES-key of the device with the key with the highest index defined by the attribute hmKey* in the HMLAN or VCCU. The old key is determined by the reading aesKeyNbr, which specifies the index of the old key when the reading is divided by 2.
• clear <[rssi|readings|register|msgEvents|attack|all]>
  A set of variables can be removed.
  
  readings: all readings will be deleted. Any new reading will be added usual. May be used to eliminate old data
  register: all captured register-readings in FHEM will be removed. This has NO impact to the values in the device.
  msgEvents: all message event counter will be removed. Also commandstack will be cleared.
  rssi: collected rssi values will be cleared.
  attack: information regarding an attack will be removed.
  all: all of the above.
  
• getConfig
  Will read major configuration items stored in the HM device. Executed on a channel it will read pair Inforamtion, List0, List1 and List3 of the 1st internal peer. Furthermore the peerlist will be retrieved for teh given channel. If executed on a device the command will get the above info or all assotated channels. Not included will be the configuration for additional peers.
  The command is a shortcut for a selection of other commands.
• getRegRaw [List0|List1|List2|List3|List4|List5|List6]<peerChannel>
  Read registerset in raw format. Description of the registers is beyond the scope of this documentation.
  Registers are structured in so called lists each containing a set of registers.
  List0: device-level settings e.g. CUL-pairing or dimmer thermal limit settings.
  List1: per channel settings e.g. time to drive the blind up and down.
  List3: per 'link' settings - means per peer-channel. This is a lot of data!. It controlls actions taken upon receive of a trigger from the peer.
  List4: settings for channel (button) of a remote
  
  <PeerChannel> paired HMid+ch, i.e. 4 byte (8 digit) value like '12345601'. It is mendatory for List 3 and 4 and can be left out for List 0 and 1.
  'all' can be used to get data of each paired link of the channel.
  'selfxx' can be used to address data for internal channels (associated with the build-in switches if any). xx is the number of the channel in decimal.
  Note1: execution depends on the entity. If List1 is requested on a device rather then a channel the command will retrieve List1 for all channels assotiated. List3 with peerChannel = all will get all link for all channel if executed on a device.
  Note2: for 'sender' see remote
  Note3: the information retrieval may take a while - especially for devices with a lot of channels and links. It may be necessary to refresh the web interface manually to view the results
  Note4: the direct buttons on a HM device are hidden by default. Nevertheless those are implemented as links as well. To get access to the 'internal links' it is necessary to issue
  'set <name> regSet intKeyVisib visib'
  or
  'set <name> regBulk RegL_0. 2:81'
  Reset it by replacing '81' with '01'
  example:
  
  set mydimmer getRegRaw List1
set mydimmer getRegRaw List3 all

• getSerial
  Read serial number from device and write it to attribute serialNr.
• inhibit [on|off]
  Block / unblock all changes to the actor channel, i.e. actor state is frozen until inhibit is set off again. Inhibit can be executed on any actor channel but obviously not on sensors - would not make any sense.
  Practically it can be used to suspend any notifies as well as peered channel action temporarily without the need to delete them.
  Examples:
  # Block operation
set keymatic inhibit on


• pair
  Pair the device with a known serialNumber (e.g. after a device reset) to FHEM Central unit. FHEM Central is usualy represented by CUL/CUNO, HMLAN,... If paired, devices will report status information to FHEM. If not paired, the device won't respond to some requests, and certain status information is also not reported. Paring is on device level. Channels cannot be paired to central separate from the device. See also getPair and unpair.
  Don't confuse pair (to a central) with peer (channel to channel) with peerChan.
  
• peerBulk <peerch1,peerch2,...> [set|unset]
  peerBulk will add peer channels to the channel. All peers in the list will be added.
  with unset option the peers in the list will be subtracted from the device's peerList.
  peering sets the configuration of this link to its defaults. As peers are not added in pairs default will be as defined for 'single' by HM for this device.
  More suffisticated funktionality is provided by peerChan.
  peerBulk will not delete existing peers, just handle the given peerlist. Other already installed peers will not be touched.
  peerBulk may be used to remove peers using unset option while default ist set.
  Main purpose of this command is to re-store data to a device. It is recommended to restore register configuration utilising regBulk subsequent.
  Example:
  
  set myChannel peerBulk 12345601,
set myChannel peerBulk self01,self02,FB_Btn_04,FB_Btn_03,
set myChannel peerBulk 12345601 unset # remove peer 123456 channel 01

• regBulk <reg List>:<peer> <addr1:data1> <addr2:data2>...
  This command will replace the former regRaw. It allows to set register in raw format. Its main purpose is to restore a complete register list to values secured before.
  Values may be read by getConfig. The resulting readings can be used directly for this command.
  <reg List> is the list data should be written to. Format could be '00', 'RegL_00', '01'...
  <peer> is an optional adder in case the list requires a peer. The peer can be given as channel name or the 4 byte (8 chars) HM channel ID.
  <addr1:data1> is the list of register to be written in hex format.
  Example:
  
  set myChannel regBulk RegL_00. 02:01 0A:17 0B:43 0C:BF 15:FF 00:00
RegL_03.FB_Btn_07 01:00 02:00 03:00 04:32 05:64 06:00 07:FF 08:00 09:FF 0A:01 0B:44 0C:54 0D:93 0E:00 0F:00 11:C8 12:00 13:00 14:00 15:00 16:00 17:00 18:00 19:00 1A:00 1B:00 1C:00 1D:FF 1E:93 1F:00 81:00 82:00 83:00 84:32 85:64 86:00 87:FF 88:00 89:FF 8A:21 8B:44 8C:54 8D:93 8E:00 8F:00 91:C8 92:00 93:00 94:00 95:00 96:00 97:00 98:00 99:00 9A:00 9B:00 9C:00 9D:05 9E:93 9F:00 00:00
set myblind regBulk 01 0B:10
set myblind regBulk 01 0C:00

  myblind will set the max drive time up for a blind actor to 25,6sec
• regSet [prep|exec] <regName> <value> <peerChannel>
  For some major register a readable version is implemented supporting register names <regName> and value conversionsing. Only a subset of register can be supproted.
  Optional parameter [prep|exec] allowes to pack the messages and therefore greatly improve data transmission. Usage is to send the commands with paramenter "prep". The data will be accumulated for send. The last command must have the parameter "exec" in order to transmitt the information.
  <value> is the data in human readable manner that will be written to the register.
  <peerChannel> is required if this register is defined on a per 'peerChan' base. It can be set to '0' other wise.See getRegRaw for full description
  Supported register for a device can be explored using
  
  set regSet ? 0 0
  Condensed register description will be printed using
  
  set regSet <regname> ? 0
• reset
  Factory reset the device. You need to pair it again to use it with fhem.
• sign [on|off]
  Activate or deactivate signing (also called AES encryption, see the note above). Warning: if the device is attached via a CUL, you need to install the perl-module Crypt::Rijndael to be able to switch it (or deactivate signing) from fhem.
• statusRequest
  Update device status. For multichannel devices it should be issued on an per channel base
• unpair
  "Unpair" the device, i.e. make it available to pair with other master devices. See pair for description.
• virtual <number of buttons>
  configures a defined curcuit as virtual remote controll. Then number of button being added is 1 to 255. If the command is issued a second time for the same entity additional buttons will be added.
  Example for usage:
  define vRemote CUL_HM 100000 # the selected HMid must not be in use
set vRemote virtual 20 # define 20 button remote controll
set vRemote_Btn4 peerChan 0 <actorchannel> # peers Button 4 and 5 to the given channel
set vRemote_Btn4 press
set vRemote_Btn5 press long

  see also press
• deviceRename <newName>
  rename the device and all its channels.
• fwUpdate [onlyEnterBootLoader] <filename> [<waitTime>]
  update Fw of the device. User must provide the appropriate file. waitTime can be given optionally. In case the device needs to be set to FW update mode manually this is the time the system will wait.
  "onlyEnterBootLoader" tells the device to enter the boot loader so it can be flashed using the eq3 firmware update tool. Mainly useful for flush-mounted devices in FHEM environments solely using HM-LAN adapters.

subType dependent commands:


• switch
  • on - set level to 100%
  • off - set level to 0%
  • on-for-timer <sec> - set the switch on for the given seconds [0-85825945].
    Note: off-for-timer like FS20 is not supported. It may to be programmed thru channel register.
  • on-till <time> - set the switch on for the given end time.
    
    set <name> on-till 20:32:10

    Currently a max of 24h is supported with endtime.
    
  • press <[short|long]> <[on|off|<peer>]> <btnNo>
    simulate a press of the local button or direct connected switch of the actor.
    [short|long] select simulation of short or long press of the button. Parameter is optional, short is default
    [on|off|<peer>] is relevant for devices with direct buttons per channel (blind or dimmer). Those are available for dimmer and blind-actor, usually not for switches
    <peer> allows to stimulate button-press of any peer of the actor. i.e. if the actor is peered to any remote, virtual or io (HMLAN/CUL) press can trigger the action defined.
    [noBurst] relevant for virtual only
    It will cause the command being added to the command queue of the peer. No burst is issued subsequent thus the command is pending until the peer wakes up. It therefore delays the button-press, but will cause less traffic and performance cost.
    Example: set actor press # trigger short of internal peer self assotiated to the channel
set actor press long # trigger long of internal peer self assotiated to the channel
set actor press on # trigger short of internal peer self related to 'on'
set actor press long off # trigger long of internal peer self related to 'of'
set actor press long FB_Btn01 # trigger long peer FB button 01
set actor press long FB_chn-8 # trigger long peer FB button 08
set actor press self01 # trigger short of internal peer 01
set actor press fhem02 # trigger short of FHEM channel 2

  • pressL <peer>
    simulates a long press for a given peer. See press for details
  • pressS <peer>
    simulates a long press for a given peer. See press for details
  • toggle - toggle the Actor. It will switch from any current level to off or from off to 100%
  
  
• dimmer, blindActuator
  Dimmer may support virtual channels. Those are autocrated if applicable. Usually there are 2 virtual channels in addition to the primary channel. Virtual dimmer channels are inactive by default but can be used in in parallel to the primay channel to control light.
  Virtual channels have default naming SW<channel>_V<no>. e.g. Dimmer_SW1_V1 and Dimmer_SW1_V2.
  Dimmer virtual channels are completely different from FHEM virtual buttons and actors but are part of the HM device. Documentation and capabilities for virtual channels is out of scope.
  
  • 0 - 100 [on-time] [ramp-time]
    set the actuator to the given value (in percent) with a resolution of 0.5.
    Optional for dimmer on-time and ramp time can be choosen, both in seconds with 0.1s granularity.
    On-time is analog "on-for-timer".
    Ramp-time default is 2.5s, 0 means instantanous
    
  • on
  • off
  • press <[short|long]><[on|off]>
  • toggle
  • toggleDir - toggled drive direction between up/stop/down/stop
  • on-for-timer <sec> - Dimmer only!
    
  • on-till <time> - Dimmer only!
    
  • stop - stop motion (blind) or dim ramp
  • pct <level> [<ontime>] [<ramptime>] - set actor to a desired absolut level.
    Optional ontime and ramptime could be given for dimmer.
    ontime may be time in seconds. It may also be entered as end-time in format hh:mm:ss
  • up [changeValue] [<ontime>] [<ramptime>] dim up one step
  • down [changeValue] [<ontime>] [<ramptime>] dim up one step
    changeValue is optional an gives the level to be changed up or down in percent. Granularity is 0.5%, default is 10%.
    ontime is optional an gives the duration of the level to be kept. '0' means forever and is default.
    ramptime is optional an defines the change speed to reach the new level. It is meaningful only for dimmer.
    
  
  
• remotes, pushButton
  This class of devices does not react on requests unless they are put to learn mode. FHEM obeys this behavior by stacking all requests until learn mode is detected. Manual interaction of the user is necessary to activate learn mode. Whether commands are pending is reported on device level with parameter 'protCmdPend'.
• peerIODev [IO] <btn_no> [set|unset]
  The command is similar to peerChan. While peerChan is executed on a remote and peers any remote to any actor channel peerIODev is executed on an actor channel and peer this to an channel of an FHEM IO device.
  An IO device according to eQ3 supports up to 50 virtual buttons. Those will be peered/unpeerd to the actor. press can be used to stimulate the related actions as defined in the actor register.
• peerChan <btn_no> <actChan> [single|dual|reverse][set|unset] [both|actor|remote]
  peerChan will establish a connection between a sender- channel and an actuator-channel called link in HM nomenclatur. Peering must not be confused with pairing.
  Pairing refers to assign a device to the central.
  Peering refers to virtally connect two channels.
  Peering allowes direkt interaction between sender and aktor without the necessity of a CCU
  Peering a sender-channel causes the sender to expect an ack from -each- of its peers after sending a trigger. It will give positive feedback (e.g. LED green) only if all peers acknowledged.
  Peering an aktor-channel will setup a parameter set which defines the action to be taken once a trigger from -this- peer arrived. In other words an aktor will
  - process trigger from peers only
  - define the action to be taken dedicated for each peer's trigger
  An actor channel will setup a default action upon peering - which is actor dependant. It may also depend whether one or 2 buttons are peered in one command. A swich may setup oen button for 'on' and the other for 'off' if 2 button are peered. If only one button is peered the funktion will likely be 'toggle'.
  The funtion can be modified by programming the register (aktor dependant).
  Even though the command is executed on a remote or push-button it will as well take effect on the actuator directly. Both sides' peering is virtually independant and has different impact on sender and receiver side.
  Peering of one actuator-channel to multiple sender-channel as well as one sender-channel to multiple Actuator-channel is possible.
  <actChan> is the actuator-channel to be peered.
  <btn_no> is the sender-channel (button) to be peered. If 'single' is choosen buttons are counted from 1. For 'dual' btn_no is the number of the Button-pair to be used. I.e. '3' in dual is the 3rd button pair correcponding to button 5 and 6 in single mode.
  If the command is executed on a channel the btn_no is ignored. It needs to be set, should be 0
  [single|dual]: this mode impacts the default behavior of the Actuator upon using this button. E.g. a dimmer can be learned to a single button or to a button pair.
  Defaults to dual.
  'dual' (default) Button pairs two buttons to one actuator. With a dimmer this means one button for dim-up and one for dim-down.
  'reverse' identical to dual - but button order is reverse.
  'single' uses only one button of the sender. It is useful for e.g. for simple switch actuator to toggle on/off. Nevertheless also dimmer can be learned to only one button.
  [set|unset]: selects either enter a peering or remove it.
  Defaults to set.
  'set' will setup peering for the channels
  'unset' will remove the peering for the channels
  [actor|remote|both] limits the execution to only actor or only remote. This gives the user the option to redo the peering on the remote channel while the settings in the actor will not be removed.
  Defaults to both.
  Example:
  set myRemote peerChan 2 mySwActChn single set #peer second button to an actuator channel
set myRmtBtn peerChan 0 mySwActChn single set #myRmtBtn is a button of the remote. '0' is not processed here
set myRemote peerChan 2 mySwActChn dual set #peer button 3 and 4
set myRemote peerChan 3 mySwActChn dual unset #remove peering for button 5 and 6
set myRemote peerChan 3 mySwActChn dual unset aktor #remove peering for button 5 and 6 in actor only
set myRemote peerChan 3 mySwActChn dual set remote #peer button 5 and 6 on remote only. Link settings il mySwActChn will be maintained

• virtual
  
  • peerChan see remote
  • press [long|short] [<peer>] [<repCount>] [<repDelay>]
    simulates button press for an actor from a peered sensor. will be sent of type "long".
    • [long|short] defines whether long or short press shall be simulated. Defaults to short
    • [<peer>] define which peer's trigger shall be simulated.Defaults to self(channelNo).
    • [<repCount>] Valid for long press only. How long shall the button be pressed? Number of repetition of the messages is defined. Defaults to 1
    • [<repDelay>] Valid for long press only. defines wait time between the single messages.
  • virtTemp <[off -10..50]> simulates a thermostat. If peered to a device it periodically sends the temperature until "off" is given. See also virtHum
    
  • virtHum <[off -10..50]> simulates the humidity part of a thermostat. If peered to a device it periodically sends the temperature and humidity until both are "off". See also virtTemp
    
  • valvePos <[off 0..100]> stimulates a VD
    
• smokeDetector
  Note: All these commands work right now only if you have more then one smoekDetector, and you peered them to form a group. For issuing the commands you have to use the master of this group, and currently you have to guess which of the detectors is the master.
  smokeDetector can be setup to teams using peerChan. You need to peer all team-members to the master. Don't forget to also peerChan the master itself to the team - i.e. peer it to itself! doing that you have full controll over the team and don't need to guess.
  
  • teamCall - execute a network test to all team members
  • alarmOn - initiate an alarm
  • alarmOff - switch off the alarm
• 4Dis (HM-PB-4DIS-WM|HM-RC-Dis-H-x-EU|ROTO_ZEL-STG-RM-DWT-10)
  • text <btn_no> [on|off] <text1> <text2>
    Set the text on the display of the device. To this purpose issue this set command first (or a number of them), and then choose from the teach-in menu of the 4Dis the "Central" to transmit the data.
    If used on a channel btn_no and on|off must not be given but only pure text.
    \_ will be replaced by blank character.
    Example:
    set 4Dis text 1 on On Lamp
set 4Dis text 1 off Kitchen Off

set 4Dis_chn4 text Kitchen Off

  
  
• Climate-Control (HM-CC-TC)
  • desired-temp <temp>
    Set different temperatures. <temp> must be between 6 and 30 Celsius, and precision is half a degree.
  • tempListSat [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListSun [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListMon [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListTue [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListThu [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListWed [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListFri [prep|exec] HH:MM temp ... 24:00 temp
    Specify a list of temperature intervals. Up to 24 intervals can be specified for each week day, the resolution is 10 Minutes. The last time spec must always be 24:00.
    Example: until 6:00 temperature shall be 19, from then until 23:00 temperature shall be 22.5, thereafter until midnight, 19 degrees celsius is desired.
    set th tempListSat 06:00 19 23:00 22.5 24:00 19

  
  
  • tempListTmpl =>"[verify|restore] [[ <file> :]templateName] ...
    The tempList for one or more devices can be stored in a file. User can compare the tempList in the file with the data read from the device.
    Restore will write the tempList to the device.
    Default opeartion is verify.
    Default file is tempList.cfg.
    Default templateName is the name of the actor
    Default for file and templateName can be set with attribut tempListTmpl
    Example for templist file. room1 and room2 are the names of the template:
    entities:room1 tempListSat>08:00 16.0 15:00 18.0 21:30 19.0 24:00 14.0 tempListSun>08:00 16.0 15:00 18.0 21:30 19.0 24:00 14.0 tempListMon>07:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListTue>07:00 16.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0 tempListWed>07:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListThu>07:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListFri>07:00 16.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0 entities:room2 tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0 tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0 tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0 tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0 tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0 Specials:
    
  • none: template will be ignored
  • defaultWeekplan: as default each day is set to 18.0 degree. useful if peered to a TC controller. Implicitely teh weekplan of TC will be used.
  • tempTmplSet =>"[[ <file> :]templateName]
    Set the attribut and apply the change to the device
  • templateDel =>" <template>
    Delete templateentry for this entity
  • partyMode <HH:MM><durationDays>
    set control mode to party and device ending time. Add the time it ends and the number of days it shall last. If it shall end next day '1' must be entered
    
  • sysTime
    set time in climate channel to system time
  
  
• Climate-Control (HM-CC-RT-DN|HM-CC-RT-DN-BoM)
  • controlMode <auto|boost|day|night>
    
  • controlManu <temp>
    
  • controlParty <temp><startDate><startTime><endDate><endTime>
    set control mode to party, define temp and timeframe.
    example:
    set controlParty 15 03.8.13 20:30 5.8.13 11:30
  • sysTime
    set time in climate channel to system time
  • desired-temp <temp>
    Set different temperatures. <temp> must be between 6 and 30 Celsius, and precision is half a degree.
  • tempListSat [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListSun [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListMon [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListTue [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListThu [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListWed [prep|exec] HH:MM temp ... 24:00 temp
    
  • tempListFri [prep|exec] HH:MM temp ... 24:00 temp
    Specify a list of temperature intervals. Up to 24 intervals can be specified for each week day, the resolution is 10 Minutes. The last time spec must always be 24:00.
    Optional parameter [prep|exec] allowes to pack the messages and therefore greatly improve data transmission. This is especially helpful if device is operated in wakeup mode. Usage is to send the commands with paramenter "prep". The data will be accumulated for send. The last command must have the parameter "exec" in order to transmitt the information.
    Example: until 6:00 temperature shall be 19, from then until 23:00 temperature shall be 22.5, thereafter until midnight, 19 degrees celsius is desired.
    set th tempListSat 06:00 19 23:00 22.5 24:00 19

set th tempListSat prep 06:00 19 23:00 22.5 24:00 19
set th tempListSun prep 06:00 19 23:00 22.5 24:00 19
set th tempListMon prep 06:00 19 23:00 22.5 24:00 19
set th tempListTue exec 06:00 19 23:00 22.5 24:00 19

  
  
• OutputUnit (HM-OU-LED16)
  • led [off|red|green|yellow]
    switches the LED of the channel to the color. If the command is executed on a device it will set all LEDs to the specified color.
    For Expert all LEDs can be set individual by providing a 8-digit hex number to the device.
    
  • ilum <brightness><duration>
    <brightness> [0-15] of backlight.
    <duration> [0-127] in sec. 0 is permanent 'on'.
    
  
  
• OutputUnit (HM-OU-CFM-PL)
  • led <color>[,<color>..] [<repeat>..]
    Possible colors are [redL|greenL|yellowL|redS|greenS|yellowS|pause]. A sequence of colors can be given separating the color entries by ','. White spaces must not be used in the list. 'S' indicates short and 'L' long ilumination.
    repeat defines how often the sequence shall be executed. Defaults to 1.
    
  • playTone <MP3No>[,<MP3No>..] [<repeat>] [<volume>]
    Play a series of tones. List is to be entered separated by ','. White spaces must not be used in the list.
    replay can be entered to repeat the last sound played once more.
    repeat defines how often the sequence shall be played. Defaults to 1.
    volume is defined between 0 and 10. 0 stops any sound currently playing. Defaults to 10 (100%).
    Example:
    # "hello" in display, symb bulb on, backlight, beep
set cfm_Mp3 playTone 3 # MP3 title 3 once
set cfm_Mp3 playTone 3 3 # MP3 title 3 3 times
set cfm_Mp3 playTone 3,6,8,3,4 # MP3 title list 3,6,8,3,4 once
set cfm_Mp3 playTone 3,6,8,3,4 255# MP3 title list 3,6,8,3,4 255 times
set cfm_Mp3 playTone replay # repeat last sequence

set cfm_Led led redL 4 # led red blink 3 times long
set cfm_Led led redS,redS,redS,redL,redL,redL,redS,redS,redS 255 # SOS 255 times

  
  
• HM-RC-19xxx
  • alarm <count>
    issue an alarm message to the remote
    
  • service <count>
    issue an service message to the remote
    
  • symbol <symbol> [set|unset]
    activate a symbol as available on the remote.
    
  • beep [off|1|2|3]
    activate tone
    
  • backlight [off|on|slow|fast]
    activate backlight
    
  • display <text> comma unit tone backlight <symbol(s)>
    control display of the remote
    <text> : up to 5 chars
    comma : 'comma' activates the comma, 'no' leaves it off
    [unit] : set the unit symbols. [off|Proz|Watt|x3|C|x5|x6|x7|F|x9|x10|x11|x12|x13|x14|x15]. Currently the x3..x15 display is not tested.
    tone : activate one of the 3 tones [off|1|2|3]
    backlight: activate backlight flash mode [off|on|slow|fast]
    <symbol(s)> activate symbol display. Multople symbols can be acticated at the same time, concatinating them comma separated. Don't use spaces here. Possiblesymbols are [bulb|switch|window|door|blind|scene|phone|bell|clock|arrowUp|arrowDown]
    
    Example:
    # "hello" in display, symb bulb on, backlight, beep
set FB1 display Hello no off 1 on bulb
# "1234,5" in display with unit 'W'. Symbols scene,phone,bell and # clock are active. Backlight flashing fast, Beep is second tone
set FB1 display 12345 comma Watt 2 fast scene,phone,bell,clock
  
  
• HM-Dis-WM55
  • displayWM help
    displayWM [long|short] <text1> <color1> <icon1> ... <text6> <color6> <icon6>
    displayWM [long|short] <lineX> <text> <color> <icon>
    up to 6 lines can be addressed.
    lineX line number that shall be changed. If this is set the 3 parameter of a line can be adapted.
    textNo is the text to be dispalyed in line No. The text is assotiated with the text defined for the buttons. txt<BtnNo>_<lineNo> references channel 1 to 10 and their lines 1 or 2. Alternaly a free text of up to 12 char can be used
    color is one white, red, orange, yellow, green, blue
    icon is one off, on, open, closed, error, ok, noIcon
    Example:
    set disp01 displayWM short txt02_2 green noIcon txt10_1 red error txt05_2 yellow closed txt02_2 orange open
set disp01 displayWM long line3 txt02_2 green noIcon
set disp01 displayWM long line2 nc yellow noIcon
set disp01 displayWM long line6 txt02_2
set disp01 displayWM long line1 nc nc closed

  
  
• HM-Dis-EP-WM55
  • displayEP help
    displayEP <text1,icon1:text2,icon2:text3,icon3> <sound> <repetition> <pause> <signal>
    up to 3 lines can be addressed.
    If help is given a help on the command is given. Options for all parameter will be given.
    textx 12 char text for the given line. If empty the value as per reading will be transmittet - i.e. typically no change. text0-9 will display predefined text of channels 4 to 8. 0xHH allows to display a single char in hex format.
    iconx Icon for this line. If empty the value as per reading will be transmittet - i.e. typically no change.
    sound sound to be played
    repetition 0..15
    pause 1..160
    signal signal color to be displayed
    
    Note: param reWriteDisplayxx
    
  • upon button press the device will overwrite the 3 middles lines. When set
    attr chan param reWriteDisplayxx
    the 3 lines will be rewritten to the latest value after xx seconds. xx is between 01 and 99
    
  
  
• keyMatic
  
  
  The Keymatic uses the AES signed communication. Control of the Keymatic is possible with the HM-LAN adapter and the CUL. To control the KeyMatic with a CUL, the perl-module Crypt::Rijndael needs to be installed.
  
  
  • lock
    The lock bolt moves to the locking position
    
  • unlock [sec]
    The lock bolt moves to the unlocking position.
    [sec]: Sets the delay in seconds after the lock automatically locked again.
    0 - 65535 seconds
  • open [sec]
    Unlocked the door so that the door can be opened.
    [sec]: Sets the delay in seconds after the lock automatically locked again.
    0 - 65535 seconds
• winMatic
  
  
  winMatic provides 2 channels, one for the window control and a second for the accumulator.
  
  
  • level <level> <relockDelay> <speed>
    set the level.
    <level>: range is 0 to 100%
    <relockDelay>: range 0 to 65535 sec. 'ignore' can be used to igneore the value alternaly
    <speed>: range is 0 to 100%
    
  • stop
    stop movement
    
• CCU_FHEM
  
  • defIgnUnknown
    define unknown devices which are present in the readings. set attr ignore and remove the readingfrom the list.
    
• HM-Sys-sRP-Pl
  
  setup the repeater's entries. Up to 36entries can be applied.
  • setRepeat <entry> <sender> <receiver> <broadcast>
    <entry> [1..36] entry number in repeater table. The repeater can handle up to 36 entries.
    <sender> name or HMID of the sender or source which shall be repeated
    <receiver> name or HMID of the receiver or destination which shall be repeated
    <broadcast> [yes|no] determines whether broadcast from this ID shall be repeated
    
    short application:
    setRepeat setAll 0 0 0
will rewrite the complete list to the deivce. Data will be taken from attribut repPeers.
    attribut repPeers is formated:
    src1:dst1:[y/n],src2:dst2:[y/n],src2:dst2:[y/n],...
    
    Reading repPeer is formated:
    
    Number src dst broadcast verify
    number: entry sequence number
    src: message source device - read from repeater
    dst: message destination device - assembled from attributes
    broadcast: shall broadcast be repeated for this source - read from repeater
    verify: do attributes and readings match?
    

Debugging:
• raw <data> ...
  Only needed for experimentation. send a list of "raw" commands. The first command will be immediately sent, the next one after the previous one is acked by the target. The length will be computed automatically, and the message counter will be incremented if the first two charcters are ++. Example (enable AES):

               set hm1 raw ++A001F100001234560105000000001\
                  ++A001F10000123456010802010AF10B000C00\
                  ++A001F1000012345601080801\
                  ++A001F100001234560106


Get

• configSave <filename>
  Saves the configuration of an entity into a file. Data is stored in a format to be executed from fhem command prompt.
  The file is located in the fhem home directory aside of fhem.cfg. Data will be stored cumulative - i.e. new data will be appended to the file. It is up to the user to avoid duplicate storage of the same entity.
  Target of the data is ONLY the HM-device information which is located IN the HM device. Explicitely this is the peer-list and the register. With the register also the peering is included.
  The file is readable and editable by the user. Additionaly timestamps are stored to help user to validate.
  Restrictions:
  Even though all data of the entity will be secured to the file FHEM stores the data that is avalilable to FHEM at time of save!. It is up to the user to read the data from the HM-hardware prior to execution. See recommended flow below.
  This command will not store any FHEM attributes o device definitions. This continues to remain in fhem.cfg.
  Furthermore the secured data will not automatically be reloaded to the HM-hardware. It is up to the user to perform a restore.
  
  As with other commands also 'configSave' is best executed on a device rather then on a channel. If executed on a device also the assotiated channel data will be secured.
  
  Recommended work-order for device 'HMdev':
set HMdev clear msgEvents # clear old events to better check flow
set HMdev getConfig # read device & channel inforamtion
# wait until operation is complete
# protState should be CMDs_done
# there shall be no warnings amongst prot... variables
get configSave myActorFile

• param <paramName>
  returns the content of the relevant parameter for the entity.
  Note: if this command is executed on a channel and 'model' is requested the content hosting device's 'model' will be returned.
• reg <addr> <list> <peerID>
  returns the value of a register. The data is taken from the storage in FHEM and not read directly outof the device. If register content is not present please use getConfig, getReg in advance.
  <addr> address in hex of the register. Registername can be used alternaly if decoded by FHEM. "all" will return all decoded register for this entity in one list.
  <list> list from which the register is taken. If rgistername is used list is ignored and can be set to 0.
  <peerID> identifies the registerbank in case of list3 and list4. It an be set to dummy if not used.
  
• regVal <addr> <list> <peerID>
  returns the value of a register. It does the same as reg but strips off units
  
• regList
  returns a list of register that are decoded by FHEM for this device.
  Note that there could be more register implemented for a device.
  
• saveConfig <file>
  stores peers and register to the file.
  Stored will be the data as available in fhem. It is necessary to read the information from the device prior to the save.
  The command supports device-level action. I.e. if executed on a device also all related channel entities will be stored implicitely.
  Storage to the file will be cumulative. If an entity is stored multiple times to the same file data will be appended. User can identify time of storage in the file if necessary.
  Content of the file can be used to restore device configuration. It will restore all peers and all register to the entity.
  Constrains/Restrictions:
  prior to rewrite data to an entity it is necessary to pair the device with FHEM.
  restore will not delete any peered channels, it will just add peer channels.
  
• listDevice
  
  • when used with ccu it returns a list of Devices using the ccu service to assign an IO.
    
  • when used with ActionDetector user will get a comma separated list of entities being assigned to the action detector
    get ActionDetector listDevice # returns all assigned entities
    get ActionDetector listDevice notActive# returns entities which habe not status alive
    get ActionDetector listDevice alive # returns entities with status alive
    get ActionDetector listDevice unknown # returns entities with status unknown
    get ActionDetector listDevice dead # returns entities with status dead
    
• info
  
  • provides information about entities using ActionDetector
    

Attributes
• eventMap
• do_not_notify
• ignore
• dummy
• showtime
• readingFnAttributes
• aesCommReq if set HMLAN/USB is forced to request AES signature before sending ACK to the device.
  This funktion strictly works with HMLAN/USB - it doesn't work for CUL type IOs.
  
• actAutoTry actAutoTry 0_off,1_on
  setting this option enables Action Detector to send a statusrequest in case of a device is going to be marked dead. The attribut may be useful in case a device is being checked that does not send messages regularely - e.g. an ordinary switch.
• actCycle actCycle <[hhh:mm]|off>
  Supports 'alive' or better 'not alive' detection for devices. [hhh:mm] is the maximum silent time for the device. Upon no message received in this period an event will be raised "<device> is dead". If the device sends again another notification is posted "<device> is alive".
  This actiondetect will be autocreated for each device with build in cyclic status report.
  Controlling entity is a pseudo device "ActionDetector" with HMId "000000".
  Due to performance considerations the report latency is set to 600sec (10min). It can be controlled by the attribute "actCycle" of "ActionDetector".
  Once entered to the supervision the HM device has 2 attributes:
  
  actStatus: activity status of the device
  actCycle: detection period [hhh:mm]
  
  The overall function can be viewed checking out the "ActionDetector" entity. The status of all entities is present in the READING section.
  Note: This function can be enabled for devices with non-cyclic messages as well. It is up to the user to enter a reasonable cycletime.
• autoReadReg
  '0' autoReadReg will be ignored.
  '1' will execute a getConfig for the device automatically after each reboot of FHEM.
  '2' like '1' plus execute after power_on.
  '3' includes '2' plus updates on writes to the device
  '4' includes '3' plus tries to request status if it seems to be missing
  '5' checks reglist and peerlist. If reading seems incomplete getConfig will be scheduled
  '8_stateOnly' will only update status information but not configuration data like register and peer
  Execution will be delayed in order to prevent congestion at startup. Therefore the update of the readings and the display will be delayed depending on the size of the database.
  Recommendations and constrains upon usage:
  
  use this attribute on the device or channel 01. Do not use it separate on each channel of a multi-channel device to avoid duplicate execution
  usage on devices which only react to 'config' mode is not recommended since executen will not start until config is triggered by the user
  usage on devices which support wakeup-mode is usefull. But consider that execution is delayed until the device "wakes up".
  
• burstAccess
  can be set for the device entity if the model allowes conditionalBurst. The attribut will switch off burst operations (0_off) which causes less message load on HMLAN and therefore reduces the chance of HMLAN overload.
  Setting it on (1_auto) allowes shorter reaction time of the device. User does not need to wait for the device to wake up.
  Note that also the register burstRx needs to be set in the device.
• expert
  This attribut controls the visibility of the register readings. This attibute controls the presentation of device parameter in the readings.
  it is a binary coded number with following presets:
  
  0_defReg : default register
  1_allReg : all register
  2_defReg+raw : default register and raw reading
  3_allReg+raw : all register and raw reading
  4_off : no register
  8_templ+default: templates and default register
  12_templOnly : templates only
  251_anything : anything available
  
  If expert is applied a device it is used for assotiated channels. It can be overruled if expert attibute is also applied to the channel device.
  Make sure to check out attribut showInternalValues in the global values as well. extert takes benefit of the implementation. Nevertheless - by definition - showInternalValues overrules expert.
• IOgrp
  can be given to devices and shall point to a virtual CCU. As a consequence the CCU will take care of the assignment to the best suitable IO. It is necessary that a virtual CCU is defined and all relevant IO devices are assigned to it. Upon sending the CCU will check which IO is operational and has the best RSSI performance for this device.
  Optional a prefered IO - perfIO can be given. In case this IO is operational it will be selected regardless of rssi values.
  Example:
  
  attr myDevice1 IOgrp vccu
attr myDevice2 IOgrp vccu:prefIO
attr myDevice2 IOgrp vccu:prefIO1,prefIO2,prefIO3

• levelRange
  can be used with dimmer only. It defines the dimmable range to be used with this dimmer-channel. It is meant to support e.g. LED light that starts at 10% and reaches maxbrightness at 40%. levelrange will normalize the level to this range. I.e. set to 100% will physically set the dimmer to 40%, 1% will set to 10% physically. 0% still switches physially off.
  Impacted are commands on, up, down, toggle and pct. Not effected is the off command which still set physically 0%.
  To be considered:
  dimmer level set by peers and buttons is not impacted. Those are controlled by device register
  Readings level may go to negative or above 100%. This simply results from the calculation and reflects physical level is above or below the given range.
  In case of virtual dimmer channels available present the attribut needs to be set for each channel
  User should be careful to set min level other then '0'
  Example:
  
  attr myChannel levelRange 0,40
attr myChannel levelRange 10,80

• model, subType
  These attributes are set automatically after a successful pairing. They are not supposed to be set by hand, and are necessary in order to correctly interpret device messages or to be able to send them.
• msgRepeat
  defines number of repetitions if a device doesn't answer in time.
  Devices which donly support config mode no repeat ist allowed.
  For devices with wakeup mode the device will wait for next wakeup. Lonng delay might be considered in this case.
  Repeat for burst devices will impact HMLAN transmission capacity.
• param
  param defines model specific behavior or functions. See available parameter for details
• rawToReadable
  Used to convert raw KFM100 values to readable data, based on measured values. E.g. fill slowly your container, while monitoring the values reported with inform. You'll see:
  10 (at 0%)
  50 (at 20%)
  79 (at 40%)
  270 (at 100%)
  
  Apply these values with: "attr KFM100 rawToReadable 10:0 50:20 79:40 270:100". fhem will do a linear interpolation for values between the bounderies.
• rssiLog
  can be given to devices, denied for channels. If switched '1' each RSSI entry will be written to a reading. User may use this to log and generate a graph of RSSI level.
  Due to amount of readings and events it is NOT RECOMMENDED to switch it on by default.
• tempListTmpl
  Sets the default template for a heating controller. If not given the detault template is taken from file tempList.cfg using the enitity name as template name (e.g. ./tempLict.cfg:RT1_Clima
  To avoid template usage set this attribut to '0'.
  Format is <file>:<templatename>. lt
• unit
  set the reported unit by the KFM100 if rawToReadable is active. E.g.
  attr KFM100 unit Liter

available parameter for attribut "param"
• HM-Sen-RD-O
  offAtPon heat channel only: force heating off after powerOn
  onAtRain heat channel only: force heating on while status changes to 'rain' and off when it changes to 'dry'
  
• virtuals
  noOnOff virtual entity will not toggle state when trigger is received. If this parameter is not given the entity will toggle its state between On and Off with each trigger
  msgReduce:<No> if channel is used for it skips every No message in order to reduce transmit load. Numbers from 0 (no skip) up to 9 can be given. VD will lose connection with more then 5 skips
  
• blind
  levelInverse while HM considers 100% as open and 0% as closed this may not be intuitive to all user. Ny default 100% is open and will be dislayed as 'on'. Setting this param the display will be inverted - 0% will be open and 100% is closed.
  NOTE: This will apply to readings and set commands. It does not apply to any register.
  ponRestoreSmart upon powerup of the device the Blind will drive to expected closest endposition followed by driving to the pre-PON level
  ponRestoreForce upon powerup of the device the Blind will drive to level 0, then to level 100 followed by driving to the pre-PON level
  
• sensRain
  siren
  powerMeter
  switch
  dimmer
  rgb
  showTimed if timmed is running -till will be added to state. This results eventually in state on-till which allowes better icon handling.
  

Generated events:
• general
  recentStateType:[ack|info] # cannot be used ti trigger notifies
  
  • ack indicates that some statusinfo is derived from an acknowledge
  • info indicates an autonomous message from the device
  • sabotageAttackId
    Alarming configuration access to the device from a unknown source
    
  • sabotageAttack
    Alarming configuration access to the device that was not issued by our system
    
  • trigDst_<name>: noConfig
    A sensor triggered a Device which is not present in its peerList. Obviously the peerList is not up to date
    
• HM-CC-TC,ROTO_ZEL-STG-RM-FWT
  T: $t H: $h
  battery:[low|ok]
  measured-temp $t
  humidity $h
  actuator $vp %
  desired-temp $dTemp
  desired-temp-manu $dTemp #temperature if switchen to manual mode
  desired-temp-cent $dTemp #temperature if switchen to central mode
  windowopen-temp-%d %.1f (sensor:%s)
  tempList$wd hh:mm $t hh:mm $t ...
  displayMode temp-[hum|only]
  displayTemp [setpoint|actual]
  displayTempUnit [fahrenheit|celsius]
  controlMode [auto|manual|central|party]
  tempValveMode [Auto|Closed|Open|unknown]
  param-change offset=$o1, value=$v1
  ValveErrorPosition_for_$dname $vep %
  ValveOffset_for_$dname : $of %
  ValveErrorPosition $vep %
  ValveOffset $of %
  time-request
  trig_<src> <value> #channel was triggered by <src> channel. This event relies on complete reading of channels configuration, otherwise Data can be incomplete or incorrect.
  trigLast <channel> #last receiced trigger
  
• HM-CC-RT-DN and HM-CC-RT-DN-BoM
  state:T: $actTemp desired: $setTemp valve: $vp %
  motorErr: [ok|ValveTight|adjustRangeTooLarge|adjustRangeTooSmall|communicationERR|unknown|lowBat|ValveErrorPosition] measured-temp $actTemp
  desired-temp $setTemp
  ValvePosition $vp %
  mode [auto|manual|party|boost]
  battery [low|ok]
  batteryLevel $bat V
  measured-temp $actTemp
  desired-temp $setTemp
  actuator $vp %
  time-request
  trig_<src> <value> #channel was triggered by <src> channel.
• HM-CC-VD,ROTO_ZEL-STG-RM-FSA
  $vp %
  battery:[critical|low|ok]
  motorErr:[ok|blocked|loose|adjusting range too small|opening|closing|stop]
  ValvePosition:$vp %
  ValveErrorPosition:$vep %
  ValveOffset:$of %
  ValveDesired:$vp % # set by TC
  operState:[errorTargetNotMet|onTarget|adjusting|changed] # operational condition
  operStateErrCnt:$cnt # number of failed settings
  
• HM-CC-SCD
  [normal|added|addedStrong]
  battery [low|ok]
  
• HM-SEC-SFA-SM
  powerError [on|off]
  sabotageError [on|off]
  battery: [critical|low|ok]
  
• HM-LC-BL1-PB-FM
  motor: [opening|closing]
  
• HM-LC-SW1-BA-PCB
  battery: [low|ok]
  
• HM-OU-LED16
  color $value # hex - for device only
  $value # hex - for device only
  color [off|red|green|orange] # for channel
  [off|red|green|orange] # for channel
  
• HM-OU-CFM-PL
  [on|off|$val]
  
• HM-Sen-Wa-Od
  $level%
  level $level%
  
• KFM100
  $v
  $cv,$unit
  rawValue:$v
  Sequence:$seq
  content:$cv,$unit
  
• KS550/HM-WDS100-C6-O
  T: $t H: $h W: $w R: $r IR: $ir WD: $wd WDR: $wdr S: $s B: $b
  temperature $t
  humidity $h
  windSpeed $w
  windDirection $wd
  windDirRange $wdr
  rain $r
  isRaining $ir
  sunshine $s
  brightness $b
  unknown $p
  
• HM-Sen-RD-O
  lastRain: timestamp # no trigger generated. Begin of previous Rain - timestamp of the reading is the end of rain.
  
• THSensor and HM-WDC7000
  T: $t H: $h AP: $ap
  temperature $t
  humidity $h
  airpress $ap #HM-WDC7000 only
  
• dimmer
  overload [on|off]
  overheat [on|off]
  reduced [on|off]
  dim: [up|down|stop]
  
• motionDetector
  brightness:$b
  alive
  motion on (to $dest)
  motionCount $cnt _next:$nextTr"-"[0x0|0x1|0x2|0x3|15|30|60|120|240|0x9|0xa|0xb|0xc|0xd|0xe|0xf]
  cover [closed|open] # not for HM-Sec-MDIR
  sabotageError [on|off] # only HM-Sec-MDIR
  battery [low|ok]
  devState_raw.$d1 $d2
  
• remote/pushButton/outputUnit
  
  (to $dest) is added if the button is peered and does not send to broadcast
  Release is provided for peered channels only
  Btn$x onShort
  Btn$x offShort
  Btn$x onLong $counter
  Btn$x offLong $counter
  Btn$x onLongRelease $counter
  Btn$x offLongRelease $counter
  Btn$x onShort (to $dest)
  Btn$x offShort (to $dest)
  Btn$x onLong $counter (to $dest)
  Btn$x offLong $counter (to $dest)
  Btn$x onLongRelease $counter (to $dest)
  Btn$x offLongRelease $counter (to $dest)
  
• remote/pushButton
  battery [low|ok]
  trigger [Long|Short]_$no trigger event from channel
  
• swi
  Btn$x Short
  Btn$x Short (to $dest)
  battery: [low|ok]
  
• switch/dimmer/blindActuator
  $val
  powerOn [on|off|$val]
  [unknown|motor|dim] [up|down|stop]:$val
  timedOn [running|off]
  # on is temporary - e.g. started with on-for-timer
• sensRain
  $val
  powerOn
  level <val≥
  timedOn [running|off]
  # on is temporary - e.g. started with on-for-timer trigger [Long|Short]_$no trigger event from channel
  
• smokeDetector
  [off|smoke-Alarm|alive] # for team leader
  [off|smoke-forward|smoke-alarm] # for team members
  [normal|added|addedStrong] #HM-CC-SCD
  SDteam [add|remove]_$dname
  battery [low|ok]
  smoke_detect [none|<src>]
  teamCall:from $src
  
• threeStateSensor
  [open|tilted|closed]
  [wet|damp|dry] #HM-SEC-WDS only
  cover [open|closed] #HM-SEC-WDS and HM-Sec-RHS
  alive yes
  battery [low|ok]
  contact [open|tilted|closed]
  contact [wet|damp|dry] #HM-SEC-WDS only
  sabotageError [on|off] #HM-SEC-SC only
  
• winMatic
  [locked|$value]
  motorErr [ok|TurnError|TiltError]
  direction [no|up|down|undefined]
  charge [trickleCharge|charge|dischange|unknown]
  airing [inactiv|$air]
  course [tilt|close]
  airing [inactiv|$value]
  contact tesed
  
• keyMatic
  unknown:40
  battery [low|ok]
  uncertain [yes|no]
  error [unknown|motor aborted|clutch failure|none']
  lock [unlocked|locked]
  [unlocked|locked|uncertain]
  
Internals
• aesCommToDev
  gives information about success or fail of AES communication between IO-device and HM-Device
  

CUL_HOERMANN

The CUL_HOERMANN module registers the 868MHz Hoermann Garage-Door-Opener signals received by the CUL. Note: As the structure of this signal is not understood, no checksum is verified, so it is likely to receive bogus messages.

Define
define <name> CUL_HOERMANNEM <10-digit-hex-code>


Set
N/A

Get
N/A

Attributes
• do_not_notify
• showtime

CUL_IR

The CUL_IR module interprets Infrared messages received by the CUN/CUNO/CUNOv2/TuxRadio. Those devices can receive Infrared Signals from basically any Remote controller and will transform that information in a so called Button-Code

Define
define <name> CUL_IR <IODev>

<IODev> is the devicename of the IR-receivung device, e.g. CUNO1.

Your definition should look like E.g.:

    define IR-Dev CUL_IR CUNO1

Set
• irLearnForSec
  Sets the CUL_IR device in an IR-Code Learning mode for the given seconds. Any received IR-Code will be stored as a Button attribute for this devices. The name of these attributes is dependent on the two attributes learncount and learnprefix.
  Attention: Before learning IR-Codes the CUL_IR device needs to be set in IR-Receiving mode by modifying the irReceive attribute.
• irSend
  Sends out IR-commands via the connected IODev. The IR-command can be specified as buttonname according to Button.* or as IR-Code directly. If a buttonname is specified, the corresponding IR-Code will be sent out.
  Example:
  

  set IR-Dev irSend ButtonA001 

  If defining an IR-Code directly the following Code-Syntax needs to be followed:
  

  IRCode: <PP><AAAA><CCCC><FF> 

  with P = Protocol; A = Address; C = Command; F = Flags
  With the Flags you can modify IR-Repetition. Flags between 00-0E will produce 0-15 IR-Repetitions. You can type the IR-Code as plain as above, or with a heading "I" as learnt for the buttons.
  Example:
  set IR-Dev irSend 0A07070F0F02
set IR-Dev irSend I0A07070F0F00
Get
N/A
Attributes
• do_not_notify


• showtime


• loglevel


• irReceive
  Configure the IR Transceiver of the <IODev> (the CUNO1). Available arguments are:
  • OFF
    Switching off the reception of IR signals. This is the default.
  • ON
    Switching on the reception of IR signals. This is WITHOUT filtering repetitions. This is not recommended as many remote controls do repeat their signals.
  • ON_NR
    Switching on the reception of IR signals with filtering of repetitions. This is the recommended modus operandi.


• Button.*
  Button.* is the wildcard for all learnt IR-Codes. IR-Codes are learnt as Button-Attributes. The name for a learnt Button - IR-Code is compiled out of three elements:
  

          Button<learnprefix><learncount>
          

  When the CUL_IR device is set into learning mode it will generate a new button-attribute for each new IR-Code received.This is done according to the following syntax:
  

          <Button-Attribute-Name> <IR-Code>

  Examples of learnt button-attributes with EMPTY <learnprefix> and <learncount> starting from 1:
  

          Button001   I02029A000000
          Button002   I02029A000001

  To make sure that something happens when this IR-code is received later on one has to modify the attribute and to add commands as attribute values. Examples:

          Button001   I02029A000000   set WZ_Lamp on
          Button002   I02029A000001   set Switch on

  The syntax for this is:

          attr <device-name> <attribute-name> <IR-Code> <command>
          

• Group.*
  Group.* is the wildcard for IR-Code groups. With these attributes one can define IR-Code parts, which may match to several Button-IR-Codes.
  This is done by defining group-attributes that contain only parts of the IR-Code. The syntax is:

          <Group-Attribute-Name> <IR-Code>

  Examples of a group-attribute is:
  

          Group001   I02029A

  With this all IR-Codes starting with I02029A will match the Group001.


• learncount
  learncount is used to store the next button-code-number that needs to be learned. By manually modifying this attribute new button sequences can be arranged.


• learnprefix
  learnprefix is a string which will be added to the button-attribute-name.
  A button-attribute-name is constructed by:

          Button<learnprefix><learncount>    

  If learnprefix is empty the button-attribute-name only contains the term "Button" and the actual number of learncount.

CUL_MAX

The CUL_MAX module interprets MAX! messages received by the CUL. It will be automatically created by autocreate, just make sure that you set the right rfmode like attr CUL0 rfmode MAX.


Define
define <name> CUL_MAX <addr>

Defines an CUL_MAX device of type <type> and rf address <addr>. The rf address must not be in use by any other MAX device.

Set
• pairmode
  Sets the CUL_MAX into pairing mode for 60 seconds where it can be paired with other devices (Thermostats, Buttons, etc.). You also have to set the other device into pairing mode manually. (For Thermostats, this is pressing the "Boost" button for 3 seconds, for example).
• fakeSC <device> <open>
  Sends a fake ShutterContactState message <open> must be 0 or 1 for "window closed" or "window opened". If the <device> has a non-zero groupId, the fake ShutterContactState message affects all devices with that groupId. Make sure you associate the target device(s) with fakeShutterContact beforehand.
• fakeWT <device> <desiredTemperature> <measuredTemperature>
  Sends a fake WallThermostatControl message (parameters both may have one digit after the decimal point, for desiredTemperature it may only by 0 or 5). If the <device> has a non-zero groupId, the fake WallThermostatControl message affects all devices with that groupId. Make sure you associate the target device with fakeWallThermostat beforehand.

Get
N/A

Attributes
• ignore


• do_not_notify


• showtime


• loglevel


• readingFnAttributes

Generated events:
N/A

CUL_REDIRECT

The CUL_REDIRECT modul receive additional protocols from CUL
and redirect them to other modules.

CUL_RFR

The CUL_RFR module is used to "attach" a second CUL to your base CUL, and use it as a repeater / range extender. RFR is shorthand for RF_ROUTER. Transmission of the data uses the CC1101 packet capabilities with GFSK modulation at 250kBaud after pinging the base CUL at the usual 1kBaud. When configured, the RFR device can be used like another CUL connected directly to fhem. Before you can use this feature in fhem, you have to enable/configure RF ROUTING in both CUL's: First give your base CUL (which remains connected to the PC) an RFR ID by issuing the fhem command "set MyCUL raw ui0100". With this command the base CUL will get the ID 01, and it will not relay messages to other CUL's (as the second number is 00). Now replace the base CUL with the RFR CUL, and set its id by issuing the fhem command "set MyCUL raw ui0201". Now remove this CUL and attach the original, base CUL again. The RFR CUL got the id 02, and will relay every message to the base CUL with id 01. Take the RFR CUL, and attach it to an USB power supply, as seen on the image. As the configured base id is not 00, it will activate RF reception on boot, and will start sending messages to the base CUL. Now you have to define this RFR cul as a fhem device:


Define
define <name> CUL_RFR <own-id> <base-id>

<own-id> is the id of the RFR CUL not connected to the PC, <base-id> is the id of the CUL connected to the PC. Both parameters have two characters, each representing a one byte hex number.
Example:
set MyCUL raw ui0100
# Now replace the base CUL with the RFR CUL
set MyCUL raw ui0201
# Reattach the base CUL to the PC and attach the RFR CUL to a USB power supply
define MyRFR CUL_RFR 02 01


Set
Same as for the CUL.

Get
Same as for the CUL.

Attributes
• ignore


• IODev

The rest of the attributes is the same as for the CUL.

CUL_TCM97001

The CUL_TCM97001 module interprets temperature sensor messages received by a Device like CUL, CUN, SIGNALduino etc.

Supported models:
• TCM97...
• ABS700
• TCM21....
• Prologue
• Rubicson
• NC_WS
• GT_WT_02
• AURIOL
• Eurochron
• KW9010

New received device packages are add in fhem category CUL_TCM97001 with autocreate.

Define
The received devices created automatically.
The ID of the defive are the first two Hex values of the package as dezimal.


Generated events:
• temperature: The temperature
• humidity: The humidity (if available)
• battery: The battery state: low or ok (if available)
• channel: The Channelnumber (if available)
• trend: The temperature trend (if available)

Attributes
• IODev Note: by setting this attribute you can define different sets of 8 devices in FHEM, each set belonging to a Device which is capable of receiving the signals. It is important, however, that a device is only received by the defined IO Device, e.g. by using different Frquencies (433MHz vs 868MHz)
• do_not_notify
• ignore
• model (TCM97..., ABS700, TCM21...., Prologue, Rubicson, NC_WS, GT_WT_02, AURIOL, KW9010, Unknown)
• showtime
• readingFnAttributes

CUL_TX

The CUL_TX module interprets TX2/TX3 type of messages received by the CUL, see also http://www.f6fbb.org/domo/sensors/tx3_th.php. This protocol is used by the La Crosse TX3-TH thermo/hygro sensor and other wireless themperature sensors. Please report the manufacturer/model of other working devices.

Define
define <name> CUL_TX <code> [corr] [minsecs]

<code> is the code of the autogenerated address of the TX device (0 to 127)
corr is a correction factor, which will be added to the value received from the device.
minsecs are the minimum seconds between two log entries or notifications from this device.
E.g. if set to 300, logs of the same type will occure with a minimum rate of one per 5 minutes even if the device sends a message every minute. (Reduces the log file size and reduces the time to display the plots)

Set
N/A

Get
N/A

Attributes
• ignore


• do_not_notify


• showtime


• readingFnAttributes

Generated events:
• temperature: $temp
• humidity: $hum

CUL_WS

The CUL_WS module interprets S300 type of messages received by the CUL.

Define
define <name> CUL_WS <code> [corr1...corr4]

<code> is the code which must be set on the S300 device. Valid values are 1 through 8.
corr1..corr4 are up to 4 numerical correction factors, which will be added to the respective value to calibrate the device. Note: rain-values will be multiplied and not added to the correction factor.

Set
N/A

Get
N/A

Attributes
• IODev Note: by setting this attribute you can define different sets of 8 devices in FHEM, each set belonging to a CUL. It is important, however, that a device is only received by the CUL defined, e.g. by using different Frquencies (433MHz vs 868MHz)
• do_not_notify
• eventMap
• ignore
• model (S300,KS300,ASH2200)
• showtime
• readingFnAttributes

CULflash

CULflash [fhem-device|none]; <TYPE>

Download the firmware from a nightly SVN chekout and flash the hardware. Currently the CUL is supported with its versions: CUL_V2, CUL_V2_HM, CUL_V3, CUL_V3_ZWAVE, CUL_V4.
If the fhem-device is none, than the inserted device must already be in the flash-mode.
Note:for flashing the CUL dfu-programmer has to be installed in the path, this is already the case with the Fritz!Box 7390 image from fhem.de
Example:
CULflash CUL CUL_V3
CULflash none CUL_V3
Note: the message "dfu-programmer: failed to release interface 0." is normal on the FB7390.

Calendar

Define


define <name> Calendar ical url <URL> [<interval>]
define <name> Calendar ical file <FILENAME> [<interval>]

Defines a calendar device.

A calendar device periodically gathers calendar events from the source calendar at the given URL or from a file. The file must be in ICal format.

If the URL starts with https://, the perl module IO::Socket::SSL must be installed (use cpan -i IO::Socket::SSL).

Note for users of Google Calendar: You can literally use the private ICal URL from your Google Calendar. If your Google Calendar URL starts with https:// and the perl module IO::Socket::SSL is not installed on your system, you can replace it by http:// if and only if there is no redirection to the https:// URL. Check with your browser first if unsure.

The optional parameter interval is the time between subsequent updates in seconds. It defaults to 3600 (1 hour).

Examples:

      define MyCalendar Calendar ical url https://www.google.com­/calendar/ical/john.doe%40example.com­/private-foo4711/basic.ics
      define YourCalendar Calendar ical url http://www.google.com­/calendar/ical/jane.doe%40example.com­/private-bar0815/basic.ics 86400
      define SomeCalendar Calendar ical file /home/johndoe/calendar.ics
      


Set


set <name> update
Forces the retrieval of the calendar from the URL. The next automatic retrieval is scheduled to occur interval seconds later.

set <name> reload
Same as update but all calendar events are removed first.



Get


get <name> update
Same as set <name> update

get <name> reload
Same as set <name> update

get <name> <format> <filter> [<max>]
Returns, line by line, information on the calendar events in the calendar <name>. The content depends on the <format> specifier:



<format>	content
uid	the UID of the event
text	a user-friendly textual representation, best suited for display
summary	the content of the summary field (subject, title)
location	the content of the location field
alarm	alarm time in human-readable format
start	start time in human-readable format
end	end time in human-readable format
full	the full state
debug	like full with additional information for debugging purposes


The <filter> specifier determines the selected subset of calendar events:



<filter>	selection
mode=<regex>	all calendar events with mode matching the regular expression <regex>
<mode>	all calendar events in the mode <mode>
uid=<regex>	all calendar events identified by UIDs that match the regular expression <regex>.
<uid>	all calendar events identified by the UID <uid>
<reading>	all calendar events listed in the reading <reading> (modeAlarm, modeAlarmed, modeStart, etc.) - this is deprecated and will be removed in a future version, use mode=<regex> instead.
all	all calendar events (past, current and future)
next	only calendar events that have not yet ended and among these only the first in a series, best suited for display


The mode=<regex> and uid=<regex> filters should be preferred over the <mode> and <uid> filters.

The optional parameter <max> limits the number of returned lines.

See attributes hideOlderThan and hideLaterThan for how to return events within a certain time window. Please remember that the global ±400 days limits apply.

Examples:
get MyCalendar text next
get MyCalendar summary uid:435kjhk435googlecom 1
get MyCalendar summary 435kjhk435googlecom 1
get MyCalendar full all
get MyCalendar text mode=alarm|start
get MyCalendar text uid=.*6286.*

get <name> find <regexp>
Returns, line by line, the UIDs of all calendar events whose summary matches the regular expression <regexp>.

get <name> vcalendar
Returns the calendar in ICal format as retrieved from the source.

get <name> vevents
Returns a list of all VEVENT entries in the calendar with additional information for debugging. Only properties that have been kept during processing of the source are shown. The list of calendar events created from each VEVENT entry is shown as well as the list of calendar events that have been omitted.

Attributes


• hideOlderThan <timespec>
hideLaterThan <timespec>
  

  These attributes limit the list of events shown by get <name> full|debug|text|summary|location|alarm|start|end ....

  The time is specified relative to the current time t. If hideOlderThan is set, calendar events that ended before t-hideOlderThan are not shown. If hideLaterThan is set, calendar events that will start after t+hideLaterThan are not shown.

  Please note that an action triggered by a change to mode "end" cannot access the calendar event if you set hideOlderThan to 0 because the calendar event will already be hidden at that time. Better set hideOlderThan to 10.

  <timespec> must have one of the following formats:
  

  format	description	example
  SSS	seconds	3600
  SSSs	seconds	3600s
  HH:MM	hours:minutes	02:30
  HH:MM:SS	hours:minutes:seconds	00:01:30
  D:HH:MM:SS	days:hours:minutes:seconds	122:10:00:00
  DDDd	days	100d

• onCreateEvent <perl-code>
  This attribute allows to run the Perl code <perl-code> for every calendar event that is created. See section Plug-ins below.
• readingFnAttributes

Description

A calendar is a set of calendar events. The calendar events are fetched from the source calendar at the given URL on a regular basis.

A calendar event has a summary (usually the title shown in a visual representation of the source calendar), a start time, an end time, and zero, one or more alarm times. In case of multiple alarm times for a calendar event, only the earliest alarm time is kept.

Recurring calendar events (series) are currently supported to an extent: FREQ INTERVAL UNTIL COUNT are interpreted, BYMONTHDAY BYMONTH WKST are recognized but not interpreted. BYDAY is only correctly interpreted for weekly events. The module will get it most likely wrong if you have recurring calendar events with unrecognized or uninterpreted keywords. Out-of-order events and events excluded from a series (EXDATE) are handled.

Calendar events are created when FHEM is started or when the respective entry in the source calendar has changed and the calendar is updated or when the calendar is reloaded with get <name> reload. Only calendar events within ±400 days around the event creation time are created. Consider reloading the calendar from time to time to avoid running out of upcoming events. You can use something like define reloadCalendar at +*240:00:00 set MyCalendar reload for that purpose.

Some dumb calendars do not use LAST-MODIFIED. This may result in modifications in the source calendar go unnoticed. Reload the calendar if you experience this issue.

A calendar event is identified by its UID. The UID is taken from the source calendar. All events in a series including out-of-order events habe the same UID. All non-alphanumerical characters are stripped off the original UID to make your life easier.

A calendar event can be in one of the following modes:

upcoming	Neither the alarm time nor the start time of the calendar event is reached.
alarm	The alarm time has passed but the start time of the calendar event is not yet reached.
start	The start time has passed but the end time of the calendar event is not yet reached.
end	The end time of the calendar event has passed.


A calendar event transitions from one mode to another immediately when the time for the change has come. This is done by waiting for the earliest future time among all alarm, start or end times of all calendar events.

A calendar device has several readings. Except for calname, each reading is a semicolon-separated list of UIDs of calendar events that satisfy certain conditions:

calname	name of the calendar
modeAlarm	events in alarm mode
modeAlarmOrStart	events in alarm or start mode
modeAlarmed	events that have just transitioned from upcoming to alarm mode
modeChanged	events that have just changed their mode somehow
modeEnd	events in end mode
modeEnded	events that have just transitioned from start to end mode
modeStart	events in start mode
modeStarted	events that have just transitioned to start mode
modeUpcoming	events in upcoming mode

For recurring events, usually several calendar events exists with the same UID. In such a case, the UID is only shown in the mode reading for the most interesting mode. The most interesting mode is the first applicable of start, alarm, upcoming, end.

In particular, you will never see the UID of a series in modeEnd or modeEnded as long as the series has not yet ended - the UID will be in one of the other mode... readings. This means that you better do not trigger FHEM events for series based on mode... readings. See below for a recommendation.

Events


When the calendar was reloaded or updated or when an alarm, start or end time was reached, one FHEM event is created:

triggered

When you receive this event, you can rely on the calendar's readings being in a consistent and most recent state.

When a calendar event has changed, two FHEM events are created:

changed: UID <mode>
<mode>: UID

<mode> is the current mode of the calendar event after the change. Note: there is a colon followed by a single space in the FHEM event specification.

The recommended way of reacting on mode changes of calendar events is to get notified on the aforementioned FHEM events and do not check for the FHEM events triggered by a change of a mode reading.

Plug-ins

This is experimental. Use with caution.

A plug-in is a piece of Perl code that modifies a calendar event on the fly. The Perl code operates on the hash reference $e. The most important elements are as follows:

code	description
$e->{start}	the start time of the calendar event, in seconds since the epoch
$e->{end}	the end time of the calendar event, in seconds since the epoch
$e->{alarm}	the alarm time of the calendar event, in seconds since the epoch
$e->{summary}	the summary (caption, title) of the calendar event
$e->{location}	the location of the calendar event


To add or change the alarm time of a calendar event for all events with the string "Tonne" in the summary, the following plug-in can be used:

attr MyCalendar onCreateEvent { $e->{alarm}= $e->{start}-86400 if($e->{summary} =~ /Tonne/);; }

The double semicolon masks the semicolon. Perl specials cannot be used.



Usage scenarios


Show all calendar events with details


get MyCalendar full all
2767324dsfretfvds7dsfn3e4­dsa234r234sdfds6bh874­googlecom alarm 31.05.2012 17:00:00 07.06.2012 16:30:00-07.06.2012 18:00:00 Erna for coffee
992hydf4y44awer5466lhfdsr­gl7tin6b6mckf8glmhui4­googlecom upcoming 08.06.2012 00:00:00-09.06.2012 00:00:00 Vacation


Show calendar events in your photo frame


Put a line in the layout description to show calendar events in alarm or start mode:

text 20 60 { fhem("get MyCalendar text next 2") }

This may look like:

07.06.12 16:30 Erna for coffee
08.06.12 00:00 Vacation


Switch the light on when Erna comes


First find the UID of the calendar event:

get MyCalendar find .*Erna.*
2767324dsfretfvds7dsfn3e4­dsa234r234sdfds6bh874­googlecom

Then define a notify (the dot after the second colon matches the space):

define ErnaComes notify MyCalendar:start:.2767324dsfretfvds7dsfn3e4­dsa234r234sdfds6bh874­googlecom set MyLight on

You can also do some logging:

define LogErna notify MyCalendar:alarm:.2767324dsfretfvds7dsfn3e4­dsa234r234sdfds6bh874­googlecom { Log3 $NAME, 1, "ALARM name=$NAME event=$EVENT part1=$EVTPART0 part2=$EVTPART1" }


Switch actors on and off


Think about a calendar with calendar events whose summaries (subjects, titles) are the names of devices in your fhem installation. You want the respective devices to switch on when the calendar event starts and to switch off when the calendar event ends.

define SwitchActorOn notify MyCalendar:start:.* { my $reading="$EVTPART0";; my $uid= "$EVTPART1";; my $actor= fhem("get MyCalendar summary $uid");; if(defined $actor) { fhem("set $actor on") } }

define SwitchActorOff notify MyCalendar:end:.* { my $reading="$EVTPART0";; my $uid= "$EVTPART1";; my $actor= fhem("get MyCalendar summary $uid");; if(defined $actor) { fhem("set $actor off") } }

You can also do some logging:

define LogActors notify MyCalendar:(start|end):.* { my $reading= "$EVTPART0";; my $uid= "$EVTPART1";; my $actor= fhem("get MyCalendar summary $uid");; Log 3 $NAME, 1, "Actor: $actor, Reading $reading" }


Embedded HTML

The module provides an additional function CalendarAsHtml(<name>,<options>). It returns the HTML code for a list of calendar events. <name> is the name of the Calendar device and <options> is what you would write after get <name> text ....

Example: define MyCalendarWeblink weblink htmlCode { CalendarAsHtml("MyCalendar","next 3") }

This is a rudimentary function which might be extended in a future version.

ComfoAir

ComfoAir provides a way to communicate with ComfoAir ventilation systems from Zehnder, especially the ComfoAir 350 (CA350). It seems that many other ventilation systems use the same communication device and protocol, e.g. WHR930 from StorkAir, G90-380 from Wernig and Santos 370 DC from Paul. They are connected via serial line to the fhem computer. This module is based on the protocol description at http://www.see-solutions.de/sonstiges/Protokollbeschreibung_ComfoAir.pdf and copies some ideas from earlier modules for the same devices that were posted in the fhem forum from danhauck(Santos) and Joachim (WHR962).
The module can be used in two ways depending on how fhem and / or a vendor supplied remote control device like CC Ease or CC Luxe are connected to the system. If a remote control device is connected it is strongly advised that fhem does not send data to the ventilation system as well and only listens to the communication betweem the vendor equipment. The RS232 interface used is not made to support more than two parties communicating and connecting fhem in parallel to a CC Ease or similar device can lead to collisions when sending data which can corrupt the ventilation system. If connected in parallel fhem should only passively listen and <Interval> is to be set to 0.
If no remote control device is connected to the ventilation systems then fhem has to take control and actively request data in the interval to be defined. Otherwiese fhem will not see any data. In this case fhem can also send commands to modify settings.

Prerequisites


• This module requires the Device::SerialPort or Win32::SerialPort module.

Define

define <name> ComfoAir <device> <Interval>

The module connects to the ventialation system through the given Device and either passively listens to data that is communicated between the ventialation system and its remote control device (e.g. CC Luxe) or it actively requests data from the ventilation system every <Interval> seconds

Example:


define ZL ComfoAir /dev/ttyUSB1@9600 60

Configuration of the module


apart from the serial connection and the interval which both are specified in the define command there are several attributes that can optionally be used to modify the behavior of the module.

The module internally gives names to all the protocol messages that are defined in the module and these names can be used in attributes to define which requests are periodically sent to the ventilation device. The same nams can also be used with set commands to manually send a request. Since all messages and readings are generically defined in a data structure in the module, it should be quite easy to add more protocol details if needed without programming.
The names currently defined are:

        Bootloader-Version
        Firmware-Version
        RS232-Modus
        Sensordaten
        KonPlatine-Version
        Verzoegerungen
        Ventilation-Levels
        Temperaturen
        Betriebsstunden
        Status-Bypass
        Status-Vorheizung
        

The attributes that control which messages are sent / which data is requested every <Interval> seconds are:

        poll-Bootloader-Version
        poll-Firmware-Version
        poll-RS232-Modus
        poll-Sensordaten
        poll-KonPlatine-Version
        poll-Verzoegerungen
        poll-Ventilation-Levels
        poll-Temperaturen
        poll-Betriebsstunden
        poll-Status-Bypass
        poll-Status-Vorheizung
        

if the attribute is set to 1, the corresponding data is requested every <Interval> seconds. If it is set to 0, then the data is not requested. by default Ventilation-Levels, Temperaturen and Status-Bypass are requested if no attributes are set.

Example:



        define ZL ComfoAir /dev/ttyUSB1@9600 60
        attr ZL poll-Status-Bypass 0
        define FileLog_Lueftung FileLog ./log/Lueftung-%Y.log ZL
        

Set-Commands

like with the attributes mentioned above, set commands can be used to send a request for data manually. The following set options are available for this:

        request-Status-Bypass 
        request-Bootloader-Version 
        request-Sensordaten
        request-Temperaturen 
        request-Firmware-Version 
        request-KonPlatine-Version 
        request-Ventilation-Levels 
        request-Verzoegerungen 
        request-Betriebsstunden 
        request-Status-Vorheizung 
        

additionally important fields can be set:

        Temp_Komfort (target temperature for comfort)
        Stufe (ventilation level)
        

Get-Commands

All readings that are derived from the responses to protocol requests are also available as Get commands. Internally a Get command triggers the corresponding request to the device and then interprets the data and returns the right field value. To avoid huge option lists in FHEMWEB, only the most important Get options are visible in FHEMWEB. However this can easily be changed since all the readings and protocol messages are internally defined in the modue in a data structure and to make a Reading visible as Get option only a little option (e.g. showget => 1 has to be added to this data structure
Attributes


• do_not_notify
• readingFnAttributes


• poll-Bootloader-Version
• poll-Firmware-Version
• poll-RS232-Modus
• poll-Sensordaten
• poll-KonPlatine-Version
• poll-Verzoegerungen
• poll-Ventilation-Levels
• poll-Temperaturen
• poll-Betriebsstunden
• poll-Status-Bypass
• poll-Status-Vorheizung
include a request for the data belonging to the named group when sending requests every interval seconds

• hide-Bootloader-Version
• hide-Firmware-Version
• hide-RS232-Modus
• hide-Sensordaten
• hide-KonPlatine-Version
• hide-Verzoegerungen
• hide-Ventilation-Levels
• hide-Temperaturen
• hide-Betriebsstunden
• hide-Status-Bypass
• hide-Status-Vorheizung
prevent readings of the named group from being created even if used passively without polling and an external remote control requests this data. please note that this attribute doesn't delete already existing readings.

• queueDelay
modify the delay used when sending requests to the device from the internal queue, defaults to 1 second

• queueMax
max length of the send queue, defaults to 50

• timeout
set the timeout for reads, defaults to 2 seconds

CustomReadings

FHEM module to define own readings.

This module allows to define own readings. The readings can be defined in an attribute so that they can get changed without changing the code of the module.
To use this module you should have some perl and linux knowledge
The examples presuppose that you run FHEM on a linux machine like a Raspberry Pi or a Cubietruck.
Note: the "bullshit" definition is an example to show what happens if you define bullshit :-)

Example (definition in fhem.cfg)
define myReadings CustomReadings
attr myReadings room 0-Test
attr myReadings group Readings
attr myReadings interval 2
attr myReadings readingDefinitions hdd_temperature:qx(hddtemp /dev/sda 2>&1),
ac_powersupply_voltage:qx(cat /sys/class/power_supply/ac/voltage_now 2>&1) / 1000000,
ac_powersupply_current:qx(cat /sys/class/power_supply/ac/current_now 2>&1) / 1000000,
perl_version:$],
timezone:qx(cat /etc/timezone 2>&1),
kernel:qx(uname -r 2>&1),
device_name:$hash->{NAME},
bullshit: $hash->{bullshit},
fhem_backup_folder_size:qx(du -ch /opt/fhem/backup | grep total | cut -d 't' -f1 2>&1)


Optionally, to display the readings:
define myReadingsDisplay weblink htmlCode {CustomReadings_GetHTML('myReadings')}
attr myReadingsDisplay group Readings
attr myReadingsDisplay room 0-Test

Resulting readings:


ac_powersupply_current	0.236	2014-08-09 15:40:21
ac_powersupply_voltage	5.028	2014-08-09 15:40:21
bullshit	ERROR	2014-08-09 15:40:21
device_name	myReadings	2014-08-09 15:40:21
fhem_backup_folder_size	20M	2014-08-09 15:40:21
hdd_temperature	/dev/sda: TS128GSSD320: 47°C	2014-08-09 15:40:21
kernel	3.4.103-sun7i+	2014-08-09 15:40:21
perl_version	5.014002	2014-08-09 15:40:21
timezone	Europe/Berlin	2014-08-09 15:40:21


Define
define <name> CustomReadings

Readings
As defined

Attributes
• interval
  Refresh interval in seconds


• readingDefinitions
  The definitions are separated by a comma. A definition consists of two parts, separated by a colon.
  The first part is the name of the reading and the second part the function.
  The function gets evaluated and must return a result.
  
  Example: kernel:qx(uname -r 2>&1)
  Defines a reading with the name "kernel" and evaluates the linux function uname -r
  Multiline output from commands, systemcall, scripts etc. can be use for more than one reading with
  the keyword COMBINED as reading (which wont appear itself) while its command output
  will be put line by line in the following readings defined (so they don't need a function defined
  after the colon (it would be ignored)).But the lines given must match the number and order of the
  following readings.
  
  COMBINED can be used together or lets say after or even in between normal expressions if the
  number of lines of the output matches exactly. Example: COMBINED:qx(cat /proc/sys/vm/dirty_background*),dirty_bytes:,dirty_ration:
  Defines two readings (dirty_bytes and dirty_ratio) which will get set by the lines of those
  two files the cat command will find in the kernel proc directory.
  In some cases this can give an noticeable performance boost as the readings are filled up all at once.

DLNARenderer

DLNARenderer automatically discovers all your MediaRenderer devices in your local network and allows you to fully control them.
It also supports multiroom audio for Caskeid and Bluetooth Caskeid speakers (e.g. MUNET).

Note: The followig libraries are required for this module:
• SOAP::Lite
• LWP::Simple
• XML::Simple
• XML::Parser::Lite
• LWP::UserAgent


Define
define <name> DLNARenderer

Example:
define dlnadevices DLNARenderer
After about 2 minutes you can find all automatically created DLNA devices under "Unsorted".


Set

set <name> stream <value>
Set any URL to play.

set <name> on
Starts playing the last stream (reading stream).

set <name> off
Sends stop command to device.

set <name> stop
Stop playback.

set <name> volume 0-100
set <name> volume +/-0-100
Set volume of the device.

set <name> channel 1-10
Start playing channel X which must be configured as channel_X attribute first.
You can specify your channel also in DIDL-Lite XML format if your player doesn't support plain URIs.

set <name> mute on/off
Mute the device.

set <name> pause
Pause playback of the device. No toggle.

set <name> pauseToggle
Toggle pause/play for the device.

set <name> play
Initiate play command. Only makes your player play if a stream was loaded (currentTrackURI is set).

set <name> next
Play next track.

set <name> previous
Play previous track.

set <name> seek <seconds>
Seek to position of track in seconds.

set <name> speak "This is a test. 1 2 3."
Speak the text followed after speak within quotes. Works with Google Translate.

set <name> playEverywhere
Only available for Caskeid players.
Play current track on all available Caskeid players in sync.

set <name> stopPlayEverywhere
Only available for Caskeid players.
Stops multiroom audio.

set <name> addUnit <unitName>
Only available for Caskeid players.
Adds unit to multiroom audio session.

set <name> removeUnit <unitName>
Only available for Caskeid players.
Removes unit from multiroom audio session.

set <name> multiRoomVolume 0-100
set <name> multiRoomVolume +/-0-100
Only available for Caskeid players.
Set volume of all devices within this session.

set <name> enableBTCaskeid
Only available for Caskeid players.
Activates Bluetooth Caskeid for this device.

set <name> disableBTCaskeid
Only available for Caskeid players.
Deactivates Bluetooth Caskeid for this device.

set <name> stereo <left> <right> <pairName>
Only available for Caskeid players.
Sets stereo mode for left/right speaker and defines the name of the stereo pair.

set <name> standalone
Only available for Caskeid players.
Puts the speaker into standalone mode if it was member of a stereo pair before.

set <name> saveGroupAs <groupName>
Only available for Caskeid players.
Saves the current group configuration (e.g. saveGroupAs LivingRoom).

set <name> loadGroup <groupName>
Only available for Caskeid players.
Loads the configuration previously saved (e.g. loadGroup LivingRoom).

Attributes

ignoreUDNs
Define list (comma or blank separated) of UDNs which should prevent automatic device creation.
It is important that uuid: is also part of the UDN and must be included.

DOIF

DOIF is a universal module. It works event- and time-controlled.

It combines the functionality of a notify, at-, watchdog command with logical queries.

Complex problems can be solved with this module, which would otherwise be solved only with several modules at different locations in FHEM. This leads to clear solutions and simplifies their maintenance.

Logical queries are created in conditions using Perl operators. These are combined with information from states, readings, internals of devices or times in square brackets. Arbitrary Perl functions can also be specified that are defined in FHEM. The module is triggered by time or by events information through the Devices specified in the condition. If a condition is true, the associated FHEM- or Perl commands are executed.

Syntax:

define <name> DOIF (<condition>) (<commands>) DOELSEIF (<condition>) (<commands>) DOELSEIF ... DOELSE (<commands>)

The commands are always processed from left to right. There is only one command executed, namely the first, for which the corresponding condition in the processed sequence is true. In addition, only the conditions are checked, which include a matching device of the trigger (in square brackets).

Features


+ intuitive syntax, as used in branches (if - elseif-....elseif - else) in higher-level languages
+ in the condition of any logical queries can be made as well as perl functions are used (full perl support)
+ it can be any FHEM commands and perl commands are executed
+ syntax checking at the time of definition are identified missing brackets
+ status is specified with [<devicename>], readings with [<devicename>:<readingname>] or internals with [<devicename>:&<internal>]
+ time information on the condition: [HH:MM:SS] or [HH:MM] or [<seconds>]
+ indirect time on the condition: [[<devicename>]] or [[<devicename>:<readingname>]] or [{<perl-function>}]
+ time calculation on the condition: [(<time calculation in Perl with time syntax specified above>)]
+ time intervals: [<begin>-<end>] for <begin> and <end>, the above time format can be selected.
+ relative times preceded by a plus sign [+<time>] or [+<begin>-+<end>] combined with Perl functions
+ weekday control: [<time>|012345678] or [<begin>-<end>|012345678] (0-6 corresponds to Sunday through Saturday) such as 7 for $we and 8 for !$we
+ statuses, readings, internals und time intervals for only queries without trigger with [?...]
+ DOELSEIF cases and DOELSE at the end are optional
+ delay specification with resetting is possible (watchdog function)
+ the execution part can be left out in each case. So that the module can be used for pure status display.
+ definition of the status display with use of any readings or statuses



Many examples with english identifiers - see german section.

DUOFERN

Support for DuoFern devices via the DuoFern USB Stick.


Define
define <name> DUOFERN <code>

<code> specifies the radio code of the DuoFern device

Example:

define myDuoFern DUOFERN 49ABCD


Set
Universal commands (available to most actors):


• remotePair
  Activates the pairing mode of the actor.
  Some actors accept this command in unpaired mode up to two hours afte power up.


• remoteUnpair
  Activates the unpairing mode of the actor.


• getStatus
  Sends a status request message to the DuoFern device.


• manualMode [on|off]
  Activates the manual mode. If manual mode is active all automatic functions will be ignored.


• timeAutomatic [on|off]
  Activates the timer automatic.


• sunAutomatic [on|off]
  Activates the sun automatic.


• dawnAutomatic [on|off]
  Activates the dawn automatic.


• duskAutomatic [on|off]
  Activates the dusk automatic.


• dusk
  Move roller shutter downwards or switch on switch/dimming actor if duskAutomatic is activated.


• dawn
  Move roller shutter upwards or switch off switch/dimming actor if dawnAutomatic is activated.


• sunMode [on|off]
  Activates the sun mode. If sun automatic is activated, the roller shutter will move to the sunPosition or a switch/dimming actor will shut off.


• reset [settings|full]
  settings: Clear all settings and endpoints of the actor.
  full: Complete reset of the actor including pairs.


Roller shutter actor commands:


• up [timer]
  Move the roller shutter upwards. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• down [timer]
  Move the roller shutter downwards. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• stop
  Stop motion.


• position <value> [timer]
  Set roller shutter to a desired absolut level. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• toggle
  Switch the roller shutter through the sequence up/stop/down/stop.


• rainAutomatic [on|off]
  Activates the rain automatic.


• windAutomatic [on|off]
  Activates the wind automatic.


• sunPosition <value>
  Set the sun position.


• ventilatingMode [on|off]
  Activates the ventilating mode. If activated, the roller shutter will stop on ventilatingPosition when moving down.


• ventilatingPosition <value>
  Set the ventilating position.


• windMode [on|off]
  Activates the wind mode. If wind automatic and wind mode is activated, the roller shutter moves in windDirection and ignore any automatic or manual command.
  The wind mode ends 15 minutes after last activation automatically.


• windDirection [up|down]
  Movemet direction for wind mode.


• rainMode [on|off]
  Activates the rain mode. If rain automatic and rain mode is activated, the roller shutter moves in rainDirection and ignore any automatic command.
  The rain mode ends 15 minutes after last activation automatically.


• rainDirection [up|down]
  Movemet direction for rain mode.


• runningTime <sec>
  Set the motor running time.


• motorDeadTime [off|short|long]
  Set the motor dead time.


• reversal [on|off]
  Reversal of direction of rotation.


Switch/dimming actor commands:


• on [timer]
  Switch on the actor. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• off [timer]
  Switch off the actor. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• set extensions are supported.


• level <value> [timer]
  Set actor to a desired absolut level. If parameter timer is used the command will only be executed if timeAutomatic is activated.


• modeChange [on|off]
  Inverts the on/off state of a switch actor or change then modus of a dimming actor.


• stairwellFunction [on|off]
  Activates the stairwell function of a switch/dimming actor.


• stairwellTime <sec>
  Set the stairwell time.


Blind actor commands:


• blindsMode [on|off]
  Activates the blinds mode.


• slatPosition <value>
  Set the slat to a desired absolut level.


• defaultSlatPos <value>
  Set the default slat position.


• slatRunTime <msec>
  Set the slat running time.


• tiltInSunPos [on|off]
  Tilt slat after blind moved to sun position.


• tiltInVentPos [on|off]
  Tilt slat after blind moved to ventilation position.


• tiltAfterMoveLevel [on|off]
  Tilt slat after blind moved to an absolute position.


• tiltAfterStopDown [on|off]
  Tilt slat after stopping blind while moving down.


SX5 commands:


• 10minuteAlarm [on|off]
  Activates the alarm sound of the SX5 when the door is left open for longer than 10 minutes.


• 2000cycleAlarm [on|off]
  Activates the alarm sounds of the SX5 when the SX5 has run 2000 cycles.


• automaticClosing [off|30|60|90|120|150|180|210|240]
  Set the automatic closing time of the SX5 (sec).


• openSpeed [11|15|19]
  Set the open speed of the SX5 (cm/sec).


• backJump [on|off]
  If activated the SX5 moves briefly in the respective opposite direction after reaching the end point.


• getConfig
  Sends a config request message to the weather sensor.


Weather sensor commands:


• getConfig
  Sends a configuration request message.


• getTime
  Sends a time request message.


• getWeather
  Sends a weather data request message.


• writeConfig
  Write the configuration back to the weather sensor.


• DCF [on|off]
  Switch the DCF receiver on or off.


• time
  Set the current system time to the weather sensor.


• interval <value>
  Set the interval time for automatic transmittion of the weather data.
  <value>: off or 1 to 100 minutes


• latitude <value>
  Set the latitude of the weather sensor position
  <value>: 0 to 90


• longitude <value>
  Set the longitude of the weather sensor position
  <value>: -90 to 90


• timezone <value>
  Set the time zone of the weather sensor
  <value>: 0 to 23


• triggerDawn <value1> ... [<value5>]
  Sets up to 5 trigger values for a dawn event.
  <value[n]>: off or 1 to 100 lux


• triggerDusk <value1> ... [<value5>]
  Sets up to 5 trigger values for a dusk event.
  <value[n]>: off or 1 to 100 Lux


• triggerRain [on|off]
  Switch the trigger of the rain event on or off.


• triggerSun <value1>:<sun1>:<shadow1>[:<temperature1>] ... [<value5>:<sun5>:<shadow5>[:<temperature5>]]
  Sets up to 5 trigger values for a sun event.
  <value[n]>: off or 1 to 100 kLux
  <sun[n]>: time to detect sun, 1 to 30 minutes
  <shadow[n]>: time to detect shadow, 1 to 30 minutes
  <temperature[n]>: optional minimum temperature, -5 to 26 °C


• triggerSunDirction <startangle1>:<width1> ... [<startangle5>:<width5>]
  If enabled, the respective sun event will only be triggered, if sunDirection is in the specified range.
  <startangle[n]>: off or 0 to 292.5 degrees (stepsize 22.5°)
  <width[n]>: 45 to 180 degrees (stepsize 45°)
  


• triggerSunHeight <startangle1>:<width1> ... [<startangle5>:<width5>]
  If enabled, the respective sun event will only be triggered, if sunHeight is in the specified range.
  <startangle[n]>: off or 0 to 65 degrees (stepsize 13°)
  <width[n]>: 26 or 52 degrees
  


• triggerTemperature <value1> ... [<value5>]
  Sets up to 5 trigger values for a temperature event.
  <value[n]>: off or -40 to 80 °C


• triggerWind <value1> ... [<value5>]
  Sets up to 5 trigger values for a wind event.
  <value[n]>: off or 1 to 31 m/s





Get
N/A

Attributes
• IODev


• timeout <sec>
  After sending a command to an actor, the actor must respond with its status within this time. If no status message is received, up to two getStatus commands are resend.
  Default 60s.


• toggleUpDown
  If attribute is set, a stop command is send instead of the up or down command if the roller shutter is moving.

DUOFERNSTICK

The DUOFERNSTICK is the fhem module for the Rademacher DuoFern USB stick.


Define
define <name> DUOFERNSTICK <device> <code>

<device> specifies the serial port to communicate with the DuoFern stick.
<code> specifies the radio code of the DuoFern stick.

The baud rate must be 115200 baud.
The code of the DuoFern stick must start with 6F.

Example:

define myDuoFernStick DUOFERNSTICK COM5@115200 6FEDCB
define myDuoFernStick DUOFERNSTICK /dev/serial/by-id/usb-Rademacher_DuoFern_USB-Stick_WR0455TN-if00-port0@115200 6FEDCB




Set

• pair
  Set the DuoFern stick in pairing mode for 60 seconds. Any DouFern device set into pairing mode in this time will be paired with the DuoFern stick.


• unpair
  Set the DuoFern stick in unpairing mode for 60 seconds. Any DouFern device set into unpairing mode in this time will be unpaired from the DuoFern stick.


• reopen
  Reopens the connection to the device and reinitializes it.


• statusBroadcast
  Sends a status request message to all DuoFern devices.


• remotePair <code>
  Activates the pairing mode on the device specified by the code.
  Some actors accept this command in unpaired mode up to two hours afte power up.


• raw <rawmsg>
  Sends a raw message.



Get
N/A

Attributes
N/A

Dashboard

Creates a Dashboard in any group can be arranged. The positioning may depend the Groups and column width are made
arbitrarily by drag'n drop. Also, the width and height of a Group can be increased beyond the minimum size.

Define
define <name> Dashboard

Example:

define anyViews Dashboard

Bestpractice beginner configuration

define anyViews Dashboard
attr anyViews dashboard_colcount 2
attr anyviews dashboard_rowcentercolwidth 30,70
attr anyViews dashboard_tab1groups <Group1>,<Group2>,<Group3>


Set
set <name> lock

locks the Dashboard so that no position changes can be made
set <name> unlock

unlock the Dashboard


Get
N/A

Attributes
• dashboard_tabcount
  Returns the number of displayed tabs. (Does not need to be set any more. It is read automatically from the configured tabs) Default: 1


• dashboard_activetab
  Specifies which tab is activated. Can be set manually, but is also set by the switch "Set" to the currently active tab. Default: 1


• dashboard_tabXname
  Title of Tab at position X.


• dashboard_tabXsorting
  Contains the position of each group in Tab X. Value is written by the "Set" button. It is not recommended to take manual changes.


• dashboard_row
  To select which rows are displayed. top only; center only; bottom only; top and center; center and bottom; top,center and bottom.
  Default: center


• dashboard_width
  To determine the Dashboardwidth. The value can be specified, or an absolute width value (eg 1200) in pixels in% (eg 80%).
  Default: 100%


• dashboard_rowcenterheight
  Height of the center row in which the groups may be positioned.
  Default: 400


• dashboard_rowcentercolwidth
  About this attribute, the width of each column of the middle Dashboardrow can be set. It can be stored for each column a separate value. The values ​​must be separated by a comma (no spaces). Each value determines the column width in%! The first value specifies the width of the first column, the second value of the width of the second column, etc. Is the sum of the width greater than 100 it is reduced. If more columns defined as widths the missing widths are determined by the difference to 100. However, are less columns are defined as the values ​​of ignores the excess values​​.
  Default: 100


• dashboard_rowtopheight
  Height of the top row in which the groups may be positioned.
  Default: 250


• "dashboard_rowbottomheight
  Height of the bottom row in which the groups may be positioned.
  Default: 250


• dashboard_tabXgroups
  Comma-separated list of the names of the groups to be displayed in Tab X.
  Each group can be given an icon for this purpose the group name, the following must be completed ":<icon>@<color>"
  Example: Light:Icon_Fisch@blue,AVIcon_Fisch@red,Single Lights:Icon_Fisch@yellow
  Additionally a group can contain a regular expression to show all groups matching a criteria. Example: .*Light.* to show all groups that contain the string "Light"


• dashboard_tabXdevices
  devspec list of devices that should appear in the tab. The format is:
  GROUPNAME:devspec1,devspec2,...,devspecN:ICONNAME
  THe icon name is optional. Also the group name is optional. In case of missing group name, the matching devices are not grouped but shown as separate widgets without titles. For further details on the devspec format see:
  Dev-Spec


• dashboard_tabXicon
  Set the icon for a Tab. There must exist an icon with the name ico.(png|svg) in the modpath directory. If the image is referencing an SVG icon, then you can use the @colorname suffix to color the image.


• dashboard_colcount
  Number of columns in which the groups can be displayed. Nevertheless, it is possible to have multiple groups
  to be positioned in a column next to each other. This is depend on the width of columns and groups.
  Default: 1


• dashboard_tabXcolcount
  Number of columns for a specific tab in which the groups can be displayed. Nevertheless, it is possible to have multiple groups
  to be positioned in a column next to each other. This depends on the width of columns and groups.
  Default:


• dashboard_tabXbackgroundimage
  Shows a background image for the X tab. The image is not stretched in any way, it should therefore match the tab size or extend it. Standard:


• dashboard_flexible
  If set to a value > 0, the widgets are not positioned in columns any more but can be moved freely to any position in the tab.
  The value for this parameter also defines the grid, in which the position "snaps in". Default: 0


• dashboard_showfullsize
  Hide FHEMWEB Roomliste (complete left side) and Page Header if Value is 1.
  Default: 0


• dashboard_showtabs
  Displays the Tabs/Buttonbar on top or bottom, or hides them. If the Buttonbar is hidden lockstate is "lock" is used.
  Default: tabs-and-buttonbar-at-the-top


• dashboard_showtogglebuttons
  Displays a Toogle Button on each Group do collapse.
  Default: 0


• dashboard_backgroundimage
  Displays a background image for the complete dashboard. The image is not stretched in any way so the size should match/extend the dashboard height/width. Default:


• dashboard_debug
  Show Hiddenfields. Only for Maintainer's use.
  Default: 0

DbLog

Define
define <name> DbLog <configfilename> <regexp>

Log events to a database. The database connection is defined in <configfilename> (see sample configuration file contrib/dblog/db.conf). The configuration is stored in a separate file to avoid storing the password in the main configuration file and to have it visible in the output of the list command.

The modules DBI and DBD::<dbtype> need to be installed (use cpan -i <module> if your distribution does not have it).

<regexp> is the same as in FileLog.

Sample code to create a MySQL/PostgreSQL database is in <DBType>_create.sql. The database contains two tables: current and history. The latter contains all events whereas the former only contains the last event for any given reading and device. The columns have the following meaning:
1. TIMESTAMP: timestamp of event, e.g. 2007-12-30 21:45:22
2. DEVICE: device name, e.g. Wetterstation
3. TYPE: device type, e.g. KS300
4. EVENT: event specification as full string, e.g. humidity: 71 (%)
5. READING: name of reading extracted from event, e.g. humidity
6. VALUE: actual reading extracted from event, e.g. 71
7. UNIT: unit extracted from event, e.g. %
The content of VALUE is optimized for automated post-processing, e.g. yes is translated to 1

The current values can be retrieved by the following code like FileLog:

get myDbLog - - 2012-11-10 2012-11-10 KS300:temperature::


Examples:
# log everything to database
define myDbLog DbLog /etc/fhem/db.conf .*:.*


Set
set <name> reopen


Perform a database disconnect and immediate reconnect to clear cache and flush journal file.

set <name> rereadcfg


Perform a database disconnect and immediate reconnect to clear cache and flush journal file.
Probably same behavior als reopen, but rereadcfg will read the configuration data before reconnect.

set <name> count


Count records in tables current and history and write results into readings countCurrent and countHistory.

set <name> deleteOldDays <n>


Delete records from history older than <n> days. Number of deleted record will be written into reading lastRowsDeleted.

set <name> reduceLog <n> [average[=day]] [exclude=deviceRegExp1:ReadingRegExp1,deviceRegExp2:ReadingRegExp2,...]


Reduce records older than <n> days to one record each hour (the 1st) per device & reading.
CAUTION: It is strongly recommended to check if the default INDEX 'Search_Idx' exists on the table 'history'!
The execution of this command may take (without INDEX) extremely long, FHEM will be completely blocked after issuing the command to completion!
With the optional argument 'average' not only the records will be reduced, but all numerical values of an hour will be reduced to a single average.
With the optional argument 'average=day' not only the records will be reduced, but all numerical values of a day will be reduced to a single average. (implies 'average')
You can optional set the last argument to "EXCLUDE=deviceRegExp1:ReadingRegExp1,deviceRegExp2:ReadingRegExp2,...." to exclude device/readings from reduceLog
You can optional set the last argument to "INCLUDE=Database-deviceRegExp:Database-ReadingRegExp" to delimit the SELECT statement which is executet on the database. This reduce the system RAM load and increase the performance. (Wildcards are % and _)


set <name> userCommand <validSqlStatement>


DO NOT USE THIS COMMAND UNLESS YOU REALLY (REALLY!) KNOW WHAT YOU ARE DOING!!!

Perform any (!!!) sql statement on connected database. Useercommand and result will be written into corresponding readings.




Get
get <name> ReadingsVal       <device> <reading> <default>
get <name> ReadingsTimestamp <device> <reading> <default>

Retrieve one single value, use and syntax are similar to ReadingsVal() and ReadingsTimestamp() functions.




get <name> <infile> <outfile> <from> <to> <column_spec>

Read data from the Database, used by frontends to plot data without direct access to the Database.

• <in>
  A dummy parameter for FileLog compatibility. Sessing by defaultto -
  
  • current: reading actual readings from table "current"
  • history: reading history readings from table "history"
  • -: identical to "history"
• <out>
  A dummy parameter for FileLog compatibility. Setting by default to - to check the output for plot-computing.
  Set it to the special keyword all to get all columns from Database.
  • ALL: get all colums from table, including a header
  • Array: get the columns as array of hashes
  • INT: internally used by generating plots
  • -: default
• <from> / <to>
  Used to select the data. Please use the following timeformat or an initial substring of it:
  
  YYYY-MM-DD_HH24:MI:SS
• <column_spec>
  For each column_spec return a set of data separated by a comment line on the current connection.
  Syntax: <device>:<reading>:<default>:<fn>:<regexp>
  
  • <device>
    The name of the device. Case sensitive. Using a the joker "%" is supported.
  • <reading>
    The reading of the given device to select. Case sensitive. Using a the joker "%" is supported.
  • <default>
    no implemented yet
  • <fn> One of the following:
    • int
      Extract the integer at the beginning of the string. Used e.g. for constructs like 10%
    • int<digit>
      Extract the decimal digits including negative character and decimal point at the beginning og the string. Used e.g. for constructs like 15.7°C
    • delta-h / delta-d
      Return the delta of the values for a given hour or a given day. Used if the column contains a counter, as is the case for the KS300 rain column.
    • delta-ts
      Replaced the original value with a measured value of seconds since the last and the actual logentry.
  • <regexp>
    The string is evaluated as a perl expression. The regexp is executed before <fn> parameter.
    Note: The string/perl expression cannot contain spaces, as the part after the space will be considered as the next column_spec.
    Keywords
  • $val is the current value returned from the Database.
  • $ts is the current timestamp returned from the Database.
  • This Logentry will not print out if $val contains th keyword "hide".
  • This Logentry will not print out and not used in the following processing if $val contains th keyword "ignore".


Examples:
• get myDbLog - - 2012-11-10 2012-11-20 KS300:temperature
• get myDbLog current ALL - - %:temperature

you will get all actual readings "temperature" from all logged devices. Be carful by using "history" as inputfile because a long execution time will be expected!
• get myDbLog - - 2012-11-10_10 2012-11-10_20 KS300:temperature::int1
  like from 10am until 08pm at 10.11.2012
• get myDbLog - all 2012-11-10 2012-11-20 KS300:temperature
• get myDbLog - - 2012-11-10 2012-11-20 KS300:temperature KS300:rain::delta-h KS300:rain::delta-d
• get myDbLog - - 2012-11-10 2012-11-20 MyFS20:data:::$val=~s/(on|off).*/$1eq"on"?1:0/eg
  return 1 for all occurance of on* (on|on-for-timer etc) and 0 for all off*
• get myDbLog - - 2012-11-10 2012-11-20 Bodenfeuchte:data:::$val=~s/.*B:\s([-\.\d]+).*/$1/eg
  Example of OWAD: value like this: "A: 49.527 % B: 66.647 % C: 9.797 % D: 0.097 V"
  and output for port B is like this: 2012-11-20_10:23:54 66.647
• get DbLog - - 2013-05-26 2013-05-28 Pumpe:data::delta-ts:$val=~s/on/hide/
  Setting up a "Counter of Uptime". The function delta-ts gets the seconds between the last and the actual logentry. The keyword "hide" will hide the logentry of "on" because this time is a "counter of Downtime"



Get when used for webcharts
get <name> <infile> <outfile> <from> <to> <device> <querytype> <xaxis> <yaxis> <savename>

Query the Database to retrieve JSON-Formatted Data, which is used by the charting frontend.

• <name>
  The name of the defined DbLog, like it is given in fhem.cfg.
• <in>
  A dummy parameter for FileLog compatibility. Always set to -
• <out>
  A dummy parameter for FileLog compatibility. Set it to webchart to use the charting related get function.
• <from> / <to>
  Used to select the data. Please use the following timeformat:
  
  YYYY-MM-DD_HH24:MI:SS
• <device>
  A string which represents the device to query.
• <querytype>
  A string which represents the method the query should use. Actually supported values are:
  getreadings to retrieve the possible readings for a given device
  getdevices to retrieve all available devices
  timerange to retrieve charting data, which requires a given xaxis, yaxis, device, to and from
  savechart to save a chart configuration in the database. Requires a given xaxis, yaxis, device, to and from, and a 'savename' used to save the chart
  deletechart to delete a saved chart. Requires a given id which was set on save of the chart
  getcharts to get a list of all saved charts.
  getTableData to get jsonformatted data from the database. Uses paging Parameters like start and limit.
  hourstats to get statistics for a given value (yaxis) for an hour.
  daystats to get statistics for a given value (yaxis) for a day.
  weekstats to get statistics for a given value (yaxis) for a week.
  monthstats to get statistics for a given value (yaxis) for a month.
  yearstats to get statistics for a given value (yaxis) for a year.
  
• <xaxis>
  A string which represents the xaxis
• <yaxis>
  A string which represents the yaxis
• <savename>
  A string which represents the name a chart will be saved with
• <chartconfig>
  A jsonstring which represents the chart to save
• <pagingstart>
  An integer used to determine the start for the sql used for query 'getTableData'
• <paginglimit>
  An integer used to set the limit for the sql used for query 'getTableData'


Examples:
• get logdb - webchart "" "" "" getcharts
  Retrieves all saved charts from the Database
• get logdb - webchart "" "" "" getdevices
  Retrieves all available devices from the Database
• get logdb - webchart "" "" ESA2000_LED_011e getreadings
  Retrieves all available Readings for a given device from the Database
• get logdb - webchart 2013-02-11_00:00:00 2013-02-12_00:00:00 ESA2000_LED_011e timerange TIMESTAMP day_kwh
  Retrieves charting data, which requires a given xaxis, yaxis, device, to and from
  Will ouput a JSON like this: [{'TIMESTAMP':'2013-02-11 00:10:10','VALUE':'0.22431388090756'},{'TIMESTAMP'.....}]
• get logdb - webchart 2013-02-11_00:00:00 2013-02-12_00:00:00 ESA2000_LED_011e savechart TIMESTAMP day_kwh tageskwh
  Will save a chart in the database with the given name and the chart configuration parameters
• get logdb - webchart "" "" "" deletechart "" "" 7
  Will delete a chart from the database with the given id



Attributes
shutdownWait
attr <device> shutdownWait
causes fhem shutdown to wait n seconds for pending database commit



DbLogSelectionMode
attr <device> DbLogSelectionMode
Thise DbLog-Device-Attribute specifies how the device specific Attributes DbLogExclude and DbLogInclude are handled. If this Attribute is missing it defaults to "Exclude".
• Exclude: DbLog behaves just as usual. This means everything specified in the regex in DEF will be logged by default and anything excluded via the DbLogExclude attribute will not be logged
• Include: Nothing will be logged, except the readings specified via regex in the DbLogInclude attribute
• Exclude/Include: Just almost the same as Exclude, but if the reading matches the DbLogExclude attribute, then it will further be checked against the regex in DbLogInclude whicht may possibly re-include the already excluded reading.



See also DbLogSelectionMode-Attribute of DbLog-Device which takes influence on on how DbLogExclude and DbLogInclude are handled
DbLogInclude

set <device> DbLogInclude regex:MinInterval [regex:MinInterval] ...
A new Attribute DbLogInclude will be propagated to all Devices if DBLog is used. DbLogInclude works just like DbLogExclude but to include matching readings. See also DbLogSelectionMode-Attribute of DbLog-Device which takes influence on on how DbLogExclude and DbLogInclude are handled
Example
attr MyDevice1 DbLogInclude .* attr MyDevice2 DbLogInclude state,(floorplantext|MyUserReading):300,battery:3600


DbLogExclude

set <device> DbLogExclude regex:MinInterval [regex:MinInterval] ...
A new Attribute DbLogExclude will be propagated to all Devices if DBLog is used. DbLogExclude will work as regexp to exclude defined readings to log. Each individual regexp-group are separated by comma. If a MinInterval is set, the logentry is dropped if the defined interval is not reached and value vs. lastvalue is eqal .
Example
attr MyDevice1 DbLogExclude .* attr MyDevice2 DbLogExclude state,(floorplantext|MyUserReading):300,battery:3600


suppressUndef
attr <device> ignoreUndef
suppresses all undef values when returning data from the DB via get

Example
#DbLog eMeter:power:::$val=($val>1500)?undef:$val

DbRep

The purpose of this module is browsing and managing the content of DbLog-databases. The searchresults can be evaluated concerning to various aggregations and the appropriate Readings will be filled. The data selection will been done by declaration of device, reading and the time settings of selection-begin and selection-end.

All database operations are implemented nonblocking. Optional the execution time of SQL-statements in background can also be determined and provided as reading. (refer to attributes).
All existing readings will be deleted when a new operation starts. By attribute "readingPreventFromDel" a comma separated list of readings which are should prevent from deletion can be provided.

Currently the following functions are provided:


• Selection of all datasets within adjustable time limits.
• Exposure of datasets of a Device/Reading-combination within adjustable time limits.
• Selecions of datasets by usage of dynamically calclated time limits at execution time.
• Calculation of quantity of datasets of a Device/Reading-combination within adjustable time limits and several aggregations.
• The calculation of summary- , difference- , maximal- and averageValues of numeric readings within adjustable time limits and several aggregations.
• The deletion of datasets. The containment of deletion can be done by Device and/or Reading as well as fix or dynamically calculated time limits at execution time.
• export of datasets to file (CSV-format).
• import of datasets from file (CSV-Format).

FHEM-Forum:
neues Modul 93_DbRep - Auswertungen und Reporting von Datenbankinhalten (DbLog).

Preparations

The module requires the usage of a DbLog instance and the credentials of the database definition will be used. (currently tested with MySQL and SQLite).
Only the content of table "history" will be included.

Overview which other Perl-modules DbRep is using:

POSIX
Time::HiRes
Time::Local
Scalar::Util
DBI
Blocking (FHEM-module)

Due to performance reason the following index should be created in addition:
ALTER TABLE 'fhem'.'history' ADD INDEX `Reading_Time_Idx` (`READING`, `TIMESTAMP`) USING BTREE;

define <name> DbRep <name of DbLog-instance>

(<name of DbLog-instance> - name of the database instance which is wanted to analyze needs to be inserted)

Currently following set-commands are included. They are used to trigger the evaluations and define the evaluation option option itself. The criteria of searching database content and determine aggregation is carried out by setting several attributes.


• averageValue - calculates the average value of readingvalues DB-column "VALUE") between period given by timestamp-attributes which are set. The reading to evaluate must be defined using attribute "reading".


• countEntries - provides the number of DB-entries between period given by timestamp-attributes which are set. If timestamp-attributes are not set, all entries in db will be count. The attributes "device" and "reading" can be used to limit the evaluation.


• exportToFile - exports DB-entries to a file in CSV-format between period given by timestamp. Limitations for selections can be set by attributes Device and/or Reading. The filename will be defined by attribute "expimpfile" .


• fetchrows - provides all DB-entries between period given by timestamp-attributes. An aggregation which would possibly be set attribute will not considered.


• insert - use it to insert data ito table "history" manually. Input values for Date, Time and Value are mandatory. The database fields for Type and Event will be filled in with "manual" automatically and the values of Device, Reading will be get from set attributes.
  
  
  input format: Date,Time,Value,[Unit]
  # Unit is optional, attributes of device, reading must be set !
  # If "Value=0" has to be inserted, use "Value = 0.0" to do it.
  
  example: 2016-08-01,23:00:09,TestValue,TestUnit
  # field lenth is maximum 32 (MYSQL) / 64 (POSTGRESQL) characters long, Spaces are NOT allowed in fieldvalues !
  
  
• importFromFile - imports datasets in CSV format from file into database. The filename will be set by attribute "expimpfile".
  
  
  dataset format: "TIMESTAMP","DEVICE","TYPE","EVENT","READING","VALUE","UNIT"
  
  # The fields "TIMESTAMP","DEVICE", "READING" have to be set. All other fields are optional. The file content will be imported transactional. That means all of the content will be imported or, in case of error, nothing of it. If an extensive file will be used, DON'T set verbose = 5 because of a lot of datas would be written to the logfile in this case. It could lead to blocking or overload FHEM !
  
  Example: "2016-09-25 08:53:56","STP_5000","SMAUTILS","etotal: 11859.573","etotal","11859.573",""
  
  
  
• sumValue - calculates the amount of readingvalues DB-column "VALUE") between period given by attributes "timestamp_begin", "timestamp_end" or "timeDiffToNow / timeOlderThan". The reading to evaluate must be defined using attribute "reading". Using this function is mostly reasonable if value-differences of readings are written to the database.


• maxValue - calculates the maximum value of readingvalues DB-column "VALUE") between period given by attributes "timestamp_begin", "timestamp_end" or "timeDiffToNow / timeOlderThan". The reading to evaluate must be defined using attribute "reading". The evaluation contains the timestamp of the identified max values within the given period.


• diffValue - calculates the defference of the readingvalues DB-column "VALUE") between period given by attributes "timestamp_begin", "timestamp_end" or "timeDiffToNow / timeOlderThan". The reading to evaluate must be defined using attribute "reading". This function is mostly reasonable if readingvalues are increasing permanently and don't write value-differences to the database. The difference will be generated from the first available dataset (VALUE-Field) to the last available dataset between the specified time linits/aggregation.


• delEntries - deletes all database entries or only the database entries specified by attributes Device and/or Reading and the entered time period between "timestamp_begin", "timestamp_end" (if set) or "timeDiffToNow/timeOlderThan".
  
  
  "timestamp_begin" is set: deletes db entries from this timestamp until current date/time
  "timestamp_end" is set : deletes db entries until this timestamp
  both Timestamps are set : deletes db entries between these timestamps
  
  
  
Due to security reasons the attribute "allowDeletion" needs to be set to unlock the delete-function.

For all evaluation variants applies:
In addition to the needed reading the device can be complemented to restrict the datasets for reporting / function. If the time limit attributes are not set, the period from '1970-01-01 01:00:00' to the current date/time will be used as selection criterion.

Note:
All database action will excuted in background. It could be necessary to refresh the browser to see the result of operation if you are in detail view once the "state = done" is shown.

Using the module specific attributes you are able to define the scope of evaluation and the aggregation.


• aggregation - Aggregation of Device/Reading-selections. Possible is hour, day, week, month or "no". Delivers e.g. the count of database entries for a day (countEntries), Summation of difference values of a reading (sumValue) and so on. Using aggregation "no" (default) an aggregation don't happens but the output contaims all values of Device/Reading in the defined time period.


• allowDeletion - unlocks the delete-function


• device - selection of a particular device


• disable - deactivates the module


• expimpfile - Path/filename for data export/import


• reading - selection of a particular reading


• readingNameMap - the name of the analyzed reading can be overwritten for output


• readingPreventFromDel - comma separated list of readings which are should prevent from deletion when a new operation starts


• showproctime - if set, the reading "sql_processing_time" shows the required execution time (in seconds) for the sql-requests. This is not calculated for a single sql-statement, but the summary of all sql-statements necessara for within an executed DbRep-function in background.


• timestamp_begin - begin of data selection (*)


• timestamp_end - end of data selection. If not set the current date/time combination will be used. (*)


• timeDiffToNow - the begin of data selection will be set to the timestamp "<current time> - <timeDiffToNow>" dynamically (in seconds). Thereby always the last <timeDiffToNow>-seconds will be considered (e.g. if set to 86400, always the last 24 hours should assumed). The Timestamp calculation will be done dynamically at execution time.


• timeOlderThan - the end of data selection will be set to the timestamp "<aktuelle Zeit> - <timeOlderThan>" dynamically (in seconds). Always the datasets up to timestamp "<current time> - <timeOlderThan>" will be considered (e.g. if set to 86400, all datasets older than one day will be considered). The Timestamp calculation will be done dynamically at execution time.


• timeout - sets the timeout-value for Blocking-Call Routines in background (default 60 seconds)



(*) The format of timestamp is as used with DbLog "YYYY-MM-DD HH:MM:SS". For the attributes "timestamp_begin", "timestamp_end" you can also use one of:


current_year_begin : set the timestamp-attribute to "<current year>-01-01 00:00:00" dynamically
current_year_end : set the timestamp-attribute to "<current year>-12-31 23:59:59" dynamically
previous_year_begin : set the timestamp-attribute to "<previous year>-01-01 00:00:00" dynamically
previous_year_end : set the timestamp-attribute to "<previous year>-12-31 23:59:59" dynamically


Make sure that timestamp_begin < timestamp_end is fulfilled.

Note
If the attribute "timeDiffToNow" will be set, the attributes "timestamp_begin" respectively "timestamp_end" will be deleted if they were set before. The setting of "timestamp_begin" respectively "timestamp_end" causes the deletion of attribute "timeDiffToNow" if it was set before as well.

Regarding to the selected operation the reasults will be shown as readings. At the beginning of a new operation all old readings will be deleted to avoid that unsuitable or invalid readings would remain.

In addition the following readings will be created:


• errortext - description about the reason of an error state


• background_processing_time - the processing time spent for operations in background/forked operation


• sql_processing_time - the processing time wasted for all sql-statements used for an operation

EC3000

The Energy Count 3000 is a AC mains plug with integrated power meter functionality from CONRAD.

It can be integrated in to FHEM via a JeeLink as the IODevice.

Define
define <name> EC3000 <addr>

addr is a 4 digit hex number to identify the EC3000 device. Note: devices are autocreated on reception of the first message.


Set

Get

Readings
• consumption
• consumptionMax
• consumptionNow

Attributes
• offLevel
  a power level less or equal offLevel is considered to be off

ECMD

Any physical device with request/response-like communication capabilities over a TCP connection can be defined as ECMD device. A practical example of such a device is the AVR microcontroller board AVR-NET-IO from Pollin with ECMD-enabled Ethersex firmware. The original NetServer firmware from Pollin works as well.

A physical ECMD device can host any number of logical ECMD devices. Logical devices are defined as ECMDDevices in fhem. ADC 0 to 3 and I/O port 0 to 3 of the above mentioned board are examples of such logical devices. ADC 0 to 3 all belong to the same device class ADC (analog/digital converter). I/O port 0 to 3 belong to the device class I/O port. By means of extension boards you can make your physical device drive as many logical devices as you can imagine, e.g. IR receivers, LC displays, RF receivers/transmitters, 1-wire devices, etc.

Defining one fhem module for any device class would create an unmanageable number of modules. Thus, an abstraction layer is used. You create a device class on the fly and assign it to a logical ECMD device. The class definition names the parameters of the logical device, e.g. a placeholder for the number of the ADC or port, as well as the get and set capabilities. Worked examples are to be found in the documentation of the ECMDDevice device.

Note: this module requires the Device::SerialPort or Win32::SerialPort module if the module is connected via serial Port or USB.

Define

define <name> ECMD telnet <IPAddress:Port>

or

define <name> ECMD serial <SerialDevice>[<@BaudRate>]

Defines a physical ECMD device. The keywords telnet or serial are fixed.

Examples:
define AVRNETIO ECMD telnet 192.168.0.91:2701
define AVRNETIO ECMD serial /dev/ttyS0
define AVRNETIO ECMD serial /sev/ttyUSB0@38400



Set
set <name> classdef <classname> <filename>

Creates a new device class <classname> for logical devices. The class definition is in the file <filename>. You must create the device class before you create a logical device that adheres to that definition.

Example:
define AVRNETIO classdef /etc/fhem/ADC.classdef


set <name> reopen

Closes and reopens the device. Could be handy if connection is lost and cannot be reestablished automatically.


Get
get <name> raw <command>

Sends the command <command> to the physical ECMD device <name> and reads the response. In the likely case that the command needs to be terminated by a newline character, you have to resort to a <perl special>.

Example:
get AVRNETIO raw { "ip\n" }



Attributes


• classdefs
  A colon-separated list of <classname>=<filename>. The list is automatically updated if a class definition is added. You can directly set the attribute.
• split
  Some devices send several readings in one transmission. The split attribute defines the separator to split such transmissions into separate messages. The regular expression for matching a reading is then applied to each message in turn. After splitting, the separator is not part of the single messages. Example: attr myECMD \n splits foo 12\nbar off into foo 12 and bar off.
• logTraffic <loglevel>
  Enables logging of sent and received datagrams with the given loglevel. Control characters in the logged datagrams are escaped, i.e. a double backslash is shown for a single backslash, \n is shown for a line feed character, etc.
• timeout <seconds>
  Time in seconds to wait for a reply from the physical ECMD device before FHEM assumes that something has gone wrong. The default is 3 seconds if this attribute is not set.
• partial <seconds>
  Some physical ECMD devices split readings and replies into several transmissions. If the partial attribute is set, this behavior is accounted for as follows: (a) If a reply is expected for a get or set command, FHEM collects transmissions from the physical ECMD device until either the reply matches the expected reply or the time in seconds given with the partial attribute has expired. (b) If a spontaneous transmission does not match the regular expression for any reading, the transmission is recorded and prepended to the next transmission. If the line is quiet for longer than the time in seconds given with the partial attribute, the recorded transmission is discarded. Use regular expressions that produce exact matches.
• requestSeparator
  A single request from FHEM to the device might need to be split in several datagrams. A command string is split at all occurrences of the requestSeparator. The requestSeparator itself is removed from the command string and thus not part of the request. This attribute is set by default. It defaults to the value \000 (octal representation of control char with code zero). To disable this feature, delete the attribute from the device's attribute list.
• responseSeparator
  In order to identify the single responses from the device to FHEM for each part of a split command, a responseSeparator can be appended to the response to each part. The responseSeparator is only appended to commands split by means of a requestSeparator. The default is to have no responseSeparator, i.e. responses are simply concatenated.
• verbose


Datagram monitoring and matching

Data to and from the physical device is processed as is. In particular, if you need to send a line feed you have to explicitely send a \n control character. On the other hand, control characters like line feeds are not stripped from the data received. This needs to be considered when defining a class definition.

For debugging purposes, especially when designing a class definition, it is advisable to turn traffic logging on. Use attr myECMD logTraffic 3 to log all data to and from the physical device at level 3. A typical response might look like 21.2\n, i.e. a floating point number followed by a newline.

Data received from the physical device is processed as it comes in chunks. If for some reason a datagram from the device is split in transit, pattern matching and processing will most likely fail. You can use the partial attribute to make FHEM collect and recombine the chunks.

Connection error handling

This modules handles unexpected disconnects of devices as follows (on Windows only for TCP connections):

Disconnects are detected if and only if data from the device in reply to data sent to the device cannot be received with at most two attempts. FHEM waits at most 3 seconds (or the time specified in the timeout attribute, see Attributes). After the first failed attempt, the connection to the device is closed and reopened again. The state of the device is failed. Then the data is sent again to the device. If still no reply is received, the state of the device is disconnected, otherwise opened. You will have to fix the problem and then use set myECMD reopen to reconnect to the device.

Please design your class definitions in such a way that the double sending of data does not bite you in any case.

Class definition

The class definition for a logical ECMD device class is contained in a text file. The text file is made up of single lines. Empty lines and text beginning with # (hash) are ignored. Therefore make sure not to use hashes in commands.
The following commands are recognized in the device class definition:



• params <parameter1> [<parameter2> [<parameter3> ... ]]
  
  Declares the names of the named parameters that must be present in the definition of the logical ECMD device.
  
  
• state <reading>
  
  Normally, the state reading is set to the latest command or reading name followed by the value, if any. This command sets the state reading to the value of the named reading if and only if the reading is updated.
  
  
• set <commandname> cmd { <perl special> }
get <commandname> cmd { <perl special> }
  
  Declares a new set or get command <commandname>. If the user invokes the set or get command <commandname>, the string that results from the execution of the <perl special> is sent to the physical device.

  A request separator (see Attributes) can be used to split the command into chunks. This is required for sending multiple Ethersex commands for one command in the class definition. The result string for the command is the concatenation of all responses received from the physical device, optionally with response separators (see Attributes) in between.
  
  

• set <commandname> expect "<regex>"
get <commandname> expect "<regex>"
  
  Declares what FHEM expects to receive after the execution of the get or set command <commandname>. <regex> is a Perl regular expression. The double quotes around the regular expression are mandatory and they are not part of the regular expression itself. <regex> must match the entire reply, as in m/^<regex>$/. Particularly, broken connections can only be detected if something is expected (see Connection error handling).
  
  
• set <commandname> postproc { <perl special> }
get <commandname> postproc { <perl special> }
  
  Declares a postprocessor for the command <commandname>. The data received from the physical device in reply to the get or set command <commandname> is processed by the Perl code <perl command>. The perl code operates on $_. Make sure to return the result in $_ as well. The result of the perl command is shown as the result of the get or set command.
  
  
• set <commandname> params <parameter1> [<parameter2> [<parameter3> ... ]]
get <commandname> params <parameter1> [<parameter2> [<parameter3> ... ]]
  
  Declares the names of the named parameters that must be present in the set or get command <commandname>. Be careful not to use a parameter name that is already used in the device definition (see params above).
  
  
• reading <reading> match "<regex>"
  
  Declares a new reading named <reading>. A spontaneous data transmission from the physical device that matches the Perl regular expression <regex> is evaluated to become the value of the named reading. All ECMDDevice devices belonging to the ECMD device with readings with matching regular expressions will receive an update of the said readings. <regex> must match the entire reply, as in m/^<regex>$/.
  
  
• reading <reading> postproc { <perl special> }
  
  Declares a postprocessor for the reading <reading>. The data received for the named reading is processed by the Perl code <perl command>. This works analogously to the postproc spec for set and get commands.
  
  
The perl specials in the definitions above can contain macros:


• The macro %NAME will expand to the device name.
• The macro %TYPE will expand to the device type.
• The macro %<parameter> will expand to the current value of the named parameter. This can be either a parameter from the device definition or a parameter from the set or get command.
• The macro substitution occurs before perl evaluates the expression. It is a plain text substitution. Be careful not to use parameters with overlapping names like %pin and %pin1.
• If in doubt what happens, run the commands with loglevel 5 and inspect the log file.


The rules outlined in the documentation of perl specials for the <perl command> in the postprocessor definitions apply. Note: Beware of undesired side effects from e.g. doubling of semicolons!

ECMDDevice

Define
define <name> ECMDDevice [<classname> [<parameter1> [<parameter2> [<parameter3> ... ]]]]

Defines a logical ECMD device. The number of given parameters must match those given in the class definition of the device class <classname>.

Normally, the logical ECMDDevice is attached to the latest previously defined physical ECMD device for I/O. Use the IODev attribute of the logical ECMDDevice to attach to any physical ECMD device, e.g. attr myRelais2 IODev myAVRNETIO. In such a case the correct reference to the class cannot be made at the time of definition of the device. Thus, you need to omit the <classname> and <parameter> references in the definition of the device and use the class attribute instead.

Examples:

define myADC ECMDDevice ADC
define myRelais1 ECMDDevice relais 8
define myRelais2 ECMDDevice
attr myRelais2 IODev myAVRNETIO
attr myRelais2 class relais 8


Set
set <name> <commandname> [<parameter1> [<parameter2> [<parameter3> ... ]]]

The number of given parameters must match those given for the set command <commandname> definition in the class definition.

If set <commandname> is invoked the perl special in curly brackets from the command definition is evaluated and the result is sent to the physical ECMD device.

Example:
set myRelais1 on
set myDisplay text This\x20text\x20has\x20blanks!



Get
get <name> <commandname> [<parameter1> [<parameter2> [<parameter3> ... ]]]

The number of given parameters must match those given for the get command <commandname> definition in the class definition.

If get <commandname> is invoked the perl special in curly brackets from the command definition is evaluated and the result is sent to the physical ECMD device. The response from the physical ECMD device is returned and the state of the logical ECMD device is updated accordingly.

Example:
get myADC value 3



Attributes
• class
  If you omit the <classname> and <parameter> references in the definition of the device, you have to add them separately as an attribute. Example: attr myRelais2 class relais 8.
• verbose
• eventMap
• IODev
• readingFnAttributes


Example 1


The following example shows how to access the ADC of the AVR-NET-IO board from Pollin with ECMD-enabled Ethersex firmware.

The class definition file /etc/fhem/ADC.classdef looks as follows:

get value cmd {"adc get %channel\n"}
get value params channel
get value expect "\d+\n"
get value postproc { s/^(\d+)\n$/$1/;; $_ }

In the fhem configuration file or on the fhem command line we do the following:

define AVRNETIO ECMD telnet 192.168.0.91:2701 # define the physical device
set AVRNETIO classdef ADC /etc/fhem/ADC.classdef # define the device class ADC
define myADC ECDMDevice ADC # define the logical device myADC with device class ADC
get myADC value 1 # retrieve the value of analog/digital converter number 1

The get command is evaluated as follows: get value has one named parameter channel. In the example the literal 1 is given and thus %channel is replaced by 1 to yield "adc get 1\n" after macro substitution. Perl evaluates this to a literal string which is send as a plain ethersex command to the AVR-NET-IO. The board returns something like 024\n for the current value of analog/digital converter number 1. The postprocessor keeps only the digits.


Example 2


The following example shows how to switch a relais driven by pin 3 (bit mask 0x08) of I/O port 2 on for one second and then off again.

The class definition file /etc/fhem/relais.classdef looks as follows:

params pinmask
set on cmd {"io set ddr 2 ff\n\000ioset port 2 0%pinmask\n\000wait 1000\n\000io set port 2 00\n"}
set on expect ".*"
set on postproc {s/^OK\nOK\nOK\nOK\n$/success/; "$_" eq "success" ? "ok" : "error"; }

In the fhem configuration file or on the fhem command line we do the following:

define AVRNETIO ECMD telnet 192.168.0.91:2701 # define the physical device
set AVRNETIO classdef relais /etc/fhem/relais.classdef # define the device class relais
define myRelais ECMDDevice 8 # define the logical device myRelais with pin mask 8
set myRelais on # execute the "on" command

The set command is evaluated as follows: %pinmask is replaced by 8 to yield "io set ddr 2 ff\n\000io set port 2 08\n\000wait 1000\n\000io set port 2 00\n\000" after macro substitution. Perl evaluates this to a literal string. This string is split into lines (with trailing newline characters)
• io set ddr 2 ff\n
• ioset port 2 08\n
• wait 1000\n
• io set port 2 00\n
These lines are sent as a plain ethersex commands to the AVR-NET-IO one by one. After each line the answer from the physical device is read back. They are concatenated with \000 chars and returned for further processing by the postproc command. For any of the four plain ethersex commands, the AVR-NET-IO returns the string OK\n. They are concatenated. The postprocessor takes the result from $_, substitutes it by the string success if it is OK\nOK\nOK\nOK\n, and then either returns the string ok or the string error.


Example 3


The following example shows how to implement a sandbox.

The class definition file /etc/fhem/DummyServer.classdef looks as follows:

reading foo match "\d+\n"
reading foo postproc { s/^(\d+).*$/$1/;; $_ }

In the fhem configuration file or on the fhem command line we do the following:

define myDummyServer ECMD telnet localhost:9999 # define the physical device
set myDummyServer classdef DummyServer /etc/fhem/DummyServer.classdef # define the device class DummyServer
define myDummyClient ECDMDevice DummyServer # define a logical device with device class DummyServer


On a Unix command line, run netcat -l 9999. This makes netcat listening on port 9999. Data received on that port are printed on stdout. Data input from stdin is sent to the other end of an incoming connection.

Start FHEM.

Then enter the number 4711 at the stdin of the running netcat server.

FHEM sees 4711\n coming in from the netcat dummy server. The incoming string matches the regular expression of the foo reading. The postprocessor is used to strip any trailing garbage from the digits. The result 4711 is used to update the foo reading.

EDIPLUG

Define
define <name> EDIPLUG < IP_EDIMAX_Device (or FQDN) >
Example:

• define myediplug EDIPLUG 192.168.0.99
• define myediplug EDIPLUG ediplug.myhome.net
Set
• on => switch power on
• off => switch power off
• list => set a new list for one day with one entry : DayOfWeek(0-6) Starttime(hh:mm) Endtime(hh:mm) Command(on/off) e.g. 1 10:00 11:30 on
  use (DayOfWeek) 00:00 24:00 on to switch the complete day on
• addlist => add a new on/off time : DayOfWeek(0-6) Starttime(hh:mm) Endtime(hh:mm) Command(on/off) e.g. 1 10:00 11:30 on
• dellist => remove a existing on/off time : DayOfWeek(0-6) Starttime(hh:mm) Endtime(hh:mm) e.g. 1 10:00 11:30
• delete => delete timelist of one day : DayOfWeek(0-6)
• day => enable/disable timeschedule for one day : DayOfWeek(0-6) on/off
Get
• info => shows MAC , Firmware Version , Model , Name
• power => shows all Power informations ( model SP-2101W only)
• schedule => show all internal on/off timetables
• status => show on/off state
Attributes
• interval => polling interval (default 60)
• timeout => max. time to wait in seconds (default 2)
• read-only => only read (Get) from device (default 0)
• user => username (default admin)
• password => password (default 1234)

Readings
• 0.So -> switching times Sunday
• 0.So.state -> Sunday switching on/off
• .
• .
• .
• 6.Sa -> switching times Saturday
• 6.Sa.state -> Saturday switching on/off ( model SP-2101W only )
• last_Toggle_Time ( model SP-2101W only )
• current ( model SP-2101W only )
• power_now ( model SP-2101W only )
• power_day ( model SP-2101W only )
• power_week ( model SP-2101W only )
• power_month ( model SP-2101W only )

EGPM Socket

Defines a Socket from EGPM2LAN Module. If the global Module AUTOCREATE is enabled, this device will be created automatically. For manual Setup, pls. see the description of EGPM2LAN.

Define
define <name> EGPM <device> <socket-nr>


Set
set <name> <[on|off|toggle]>
Switches the socket on or of.
set <name> <[on-for-timer|off-for-timer|on-till|off-till|blink|intervals]>
Switches the socket for a specified time+duration or n-times. For Details see set extensions

Example:
define lamp1 EGPM mainswitch 1
set lamp1 on


Get
N/A

Attributes
• loglevel
• readingFnAttributes

Generated events
• EGPM <name> <[on|off]>

EGPM2LAN

Define
define <name> EGPM2LAN <IP-Address> [<Password>]

Creates a Gembird ® Energenie EG-PM2-LAN device to switch up to 4 sockets over the network. If you have more than one device, it is helpful to connect and set names for your sockets over the web-interface first. The name settings will be adopted to FHEM and helps you to identify the sockets. Please make sure that you´re logged off from the Energenie web-interface otherwise you can´t control it with FHEM at the same time.
EG-PMS2-LAN with surge protector feature was not tested until now.

Set
set <name> <[on|off|toggle]> <socketnr.>
Switch the socket on or off.

set <name> <[on|off]> <all>
Switch all available sockets on or off.

set <name> <staterequest>
Update the device information and the state of all sockets.
If autocreate is enabled, an EGPM device will be created for each socket.

set <name> <clearreadings>
Removes all readings from the list to get rid of old socketnames.

Get
N/A

Attributes
• stateDisplay
Default: socketNumer changes between socketNumer and socketName in front of the current state. Call set statusrequest to update all states.
• autocreate
Default: on EGPM-devices will be created automatically with a set-command. Change this attribute to value off to avoid that mechanism.
• loglevel
• readingFnAttributes



Example:
define mainswitch EGPM2LAN 10.192.192.20 SecretGarden
set mainswitch on 1

EIB / KNX

      define lamp1 EIB 0/10/12
      define lamp1 EIB 0/10/12 0/0/5
      define lamp1 EIB 0A0C
      

      set lamp1 on
      set lamp1 off
      set lamp1 on-for-timer 10
      set lamp1 on-till 13:15:00
      set lamp1 raw 234578
      set lamp1 value 23.44
    

      define lamp1 EIB 0/10/01 0/10/02
      set lamp1 on g2 (will send "on" to 0/10/02)
	

      define dim1 EIB 0/0/5
      attr dim1 model percent
      attr dim1 webCmd value
	

      define timedev EIB 0/0/7
      attr timedev model time
      attr timedev eventMap /value now:now/
      attr timedev webCmd now
      
      define datedev EIB 0/0/8
      attr datedev model date
      attr datedev eventMap /value now:now/
      attr datedev webCmd now
      
      # send every midnight the new date
      define dateset at *00:00:00 set datedev value now
      
      # send every hour the current time
      define timeset at +*01:00:00 set timedev value now
	

      setGx will be updated on a SET command issued by FHEM. <x> stands for the groupnr. - see define statement
      getGx will be updated on reception of a message from EIB-bus.
      

      define myDimmer EIB 0/1/1 0/1/2
      attr myDimmer EIBreadingX 1
      attr myDimmer model dpt1 dpt5 # GA 0/1/1 will be interpreted as on/off, GA 0/1/2 will be handled as dpt5
      attr myDimmer stateFormat getG2 % # copies actual dim-level (as received from dimmer) into STATE 
      

sender

      sender will be updated any time a new telegram arrives at this group-adress
      

      define myDimmer EIB 0/1/1
      attr myDimmer EIBreadingSender 1
      

      define myValue EIB 0/1/1
      attr myValue EIBanswerReading 1
      

      define myLamp EIB 0/1/1 0/1/2 0/1/2
      attr myLamp EIBreadingRegex getG[1]:/steuern: getG[2]:/status: getG[3]:/sperre:
	  attr myLamp EIBreadingRegex devStateIcon status.on:general_an status.off:general_aus sperre.on:lock
      

      define myLockObject EIB 0/1/1
      attr myLamp EIBwritingRegex setG1:on/LOCKED setG1:/UNLOCKED
      

EM

Define
define <name> EM <em1010pc-device>

Define a EM1010PC USB device. As the EM1010PC was not designed to be used with a PC attached to it all the time, it won't transmit received signals automatically, fhem has to poll it every 5 minutes.
Currently there is no way to read the internal log of the EM1010PC with fhem, use the program em1010.pl in the contrib directory for this purpose.

Examples:
define em EM /dev/elv_em1010pc


Set
set EM <value>

where value is either time or reset.
If time has arguments of the form YYYY-MM-DD HH:MM:SS, then the specified time will be set, else the time from the host.
Note: after reset you should set the time.

Get
get EM <value>

where value is either version or time.
Attributes
• model (em1010pc)
• dummy

EMEM

Define
define <name> EMEM <device-number>

Define up to 4 EM1000EM attached to the EM1010PC. The device number must be between 5 and 8. Defining an EMEM will schedule an internal task, which reads the status of the device every 5 minutes, and triggers notify/filelog commands.
Note: Currently this device does not support a "set" function.

Example:
define emem EMEM 5


Set
N/A

Get
get EMEM status

This is the same command which is scheduled every 5 minutes internally.

Attributes
• model (EM1000EM)
• dummy
• IODev

EMGZ

Define
define <name> EMGZ <device-number>

Define up to 4 EM1000GZ attached to the EM1010PC. The device number must be between 9 and 12. Defining an EMGZ will schedule an internal task, which reads the status of the device every 5 minutes, and triggers notify/filelog commands.

Example:
define emgz EMGZ 9

Set
set EMGZdevice <param> <value>

where param is:
• price
  The price of one KW in EURO (use e.g. 0.20 for 20 Cents). It is used only on the EM1010PC display, it is of no interest for FHEM.

Get
get EMGZ status

This is the same command which is scheduled every 5 minutes internally.

Attributes
• model (EM1000GZ)
• dummy
• IODev

EMT7110

The EMT7110 is a plug with integrated power meter functionality.
It can be integrated into FHEM via a JeeLink as the IODevice.

The EMT7110 sends with 9.579 kbit/s. Therefore it is necessary to set the JeeLink to a mode where it recieves this data rate.
This can be done using the initCommands attribute of the JeeLink.

If you have only 9.579 kbit/s sensors use this setting:
attr myJeeLink initCommands 1r v

If you have also 17.241 kbit/s sensors (like TX29...) use this setting:
attr myJeeLink initCommands 30t v
30t means that the JeeLink toggles the data rate every 30 Seconds.

Define define <name> EMT7110 <addr>
addr is a 4 digit hex number to identify the EMT7110 device.
To enable autocreate for a certain time you must set LaCrossePairForSec in the JeeLink IODevice device.

Set
• resetAccumulatedPower
  Sets the accumulatedPowerOffset attribute to the current value of accumulatedPowerMeasured. Don't forget to call save to write the new value to fhem.cfg

Get

Readings
• accumulatedPowerMeasured
  The accumulated power sent by the EMT7110. The EMT7110 accumulates the power even if it was removed and reconnected to the power outlet. The only way to reset it is to remove and reinsert the batteries in the EMT7110.


• accumulatedPower
  Is accumulatedPowerMeasured minus the value of the accumulatedPowerOffset attribute value This reading is used for the A: part of state


• costs
  Is accumulatedPower * pricePerKWH attribute value


• current
  The measured current in mA


• power
  The measured power in Watt


• voltage
  The measured voltage in Volt


Attributes
• accumulatedPowerOffset
  See accumulatedPower reading


• pricePerKWH
  See costs reading

EMWZ

Define
define <name> EMWZ <device-number>

Define up to 4 EM1000WZ attached to the EM1010PC. The device number must be between 1 and 4. Defining an EMWZ will schedule an internal task, which reads the status of the device every 5 minutes, and triggers notify/filelog commands.

Example:
define emwz EMWZ 1


Set
set EMWZdevice <param> <value>

where param is one of:
• rperkw
  Number of rotations for a KiloWatt of the EM1000WZ device (actually of the device where the EM1000WZ is attached to). Without setting this correctly, all other readings will be incorrect.
• alarm
  Alarm in WATT. if you forget to set it, the default value is rediculously low (random), and if a value above this threshold is received, the EM1010PC will start beeping once every minute. It can be very annoying.
• price
  The price of one KW in EURO (use e.g. 0.20 for 20 Cents). It is used only on the EM1010PC display, it is of no interest for FHEM.

Get
get EMWZ status

This is the same command which is scheduled every 5 minutes internally.

Attributes
• model (EM1000WZ)
• dummy
• IODev

ENECSYSGW

Module to access the ENECSYS gateway (http://www.ENECSYS.com/products/gateway/).

The actual micro-inverter devices are defined as ENECSYSINV devices.

All newly found inverter devices are autocreated and added to the room ENECSYSINV.

Define
define <name> ENECSYSGW [<host>] [<interval>]

Defines an ENECSYSGW device with address <host>.

The gateway will be polled every <interval> seconds. The default is 10 and minimum is 5.

Examples:
define gateway ENECSYSGW 10.0.1.1

ENECSYSINV

Define
define <name> ENECSYSINV <id> [<interval>]

Defines an micro-inverter device connected to an ENECSYSGW.

Examples:
define SolarPanel1 ENECSYSINV 100123456


Readings
• acfrequency
  the alternating current frequency reported from the device. Should be around 50 Hz in Europe.
• acpower
  the alternating current power
• acvolt
  the alternating current voltage
• dccurrent
  the direct current
• dcpower
  the direct current power
• dcvolt
  the direct current voltage
• efficiency
  the efficiency of the inverter
• lifetime
  the sum of collected energy of the inverter
• temperature
  the temperature of the inverter
• state
  the current state (equal to dcpower)

ENIGMA2

Define
define <name> ENIGMA2 <ip-address-or-hostname> [[[[<port>] [<poll-interval>]] [<http-user>]] [<http-password>]]

This module controls ENIGMA2 based devices like Dreambox or VUplus receiver via network connection.

Defining an ENIGMA2 device will schedule an internal task (interval can be set with optional parameter <poll-interval> in seconds, if not set, the value is 45 seconds), which periodically reads the status of the device and triggers notify/filelog commands.

Example:

define SATReceiver ENIGMA2 192.168.0.10

# With custom port
define SATReceiver ENIGMA2 192.168.0.10 8080

# With custom interval of 20 seconds
define SATReceiver ENIGMA2 192.168.0.10 80 20

# With HTTP user credentials
define SATReceiver ENIGMA2 192.168.0.10 80 20 root secret


Set
set <name> <command> [<parameter>]

Currently, the following commands are defined.

• on   -   powers on the device and send a WoL magic package if needed
• off   -   turns the device in standby mode
• toggle   -   switch between on and off
• shutdown   -   turns the device in deepstandby mode
• reboot   -  reboots the device
• restartGui   -  restarts the GUI / ENIGMA2 process
• channel channel,0...999,sRef   -   zap to specific channel or service reference
• channelUp   -   zap to next channel
• channelDown   -   zap to previous channel
• volume 0...100   -   set the volume level in percentage
• volumeUp   -   increases the volume level
• volumeDown   -   decreases the volume level
• mute on,off,toggle   -   controls volume mute
• play   -   starts/resumes playback
• pause   -   pauses current playback or enables timeshift
• stop   -   stops current playback
• record   -   starts recording of current channel
• input tv,radio   -   switches between tv and radio mode
• statusRequest   -   requests the current status of the device
• remoteControl UP,DOWN,...   -   sends remote control commands; see remoteControl help for full command list
  Note: You may add the word "long" after the command to simulate a long key press.
• showText text   -   sends info message to screen to be displayed for 8 seconds
• msg yesno,info...   -   allows more complex messages as showText, see commands as listed below
Note: If you would like to restrict access to admin set-commands (-> statusRequest, reboot, restartGui, shutdown) you may set your FHEMWEB instance's attribute allowedCommands like 'set,set-user'. The string 'set-user' will ensure only non-admin set-commands can be executed when accessing FHEM using this FHEMWEB instance.



Messaging


showText has predefined settings. If you would like to send more individual messages to your TV screen, the function msg can be used. For this application the following commands are available:

Type Selection:

msg yesno
msg info
msg message
msg attention



The following parameter are essentially needed after type specification:
msg <TYPE> <TIMEOUT> <YOUR MESSAGETEXT>



Get
get <name> <what>

Currently, the following commands are defined:


channel
currentMedia
currentTitle
mute
nextTitle
power
providername
servicevideosize
input
streamUrl
volume



Attributes

• bouquet-tv - service reference address where the favorite television bouquet can be found (initially set automatically during define)
• bouquet-radio - service reference address where the favorite radio bouquet can be found (initially set automatically during define)
• disable - Disable polling (true/false)
• http-method - HTTP access method to be used; e.g. a FritzBox might need to use POST instead of GET (GET/POST)
• http-noshutdown - Set FHEM-internal HttpUtils connection close behaviour (defaults=1)
• https - Access box via secure HTTP (true/false)
• ignoreState - Do not check for available device before sending commands to it (true/false)
• lightMode - reduces regular queries (resulting in less functionality), e.g. for low performance devices. (true/false)
• macaddr - manually set specific MAC address for device; overwrites value from reading "lanmac". (true/false)
• remotecontrol - Explicitly set specific remote control unit format. This will only be considered for set-command remoteControl as of now.
• timeout - Set different polling timeout in seconds (default=6)
• wakeupCmd - Set a command to be executed when turning on an absent device. Can be an FHEM command or Perl command in {}. Available variables: ENIGMA2 device name -> $DEVICE, ENIGMA2 device MAC address -> $MACADDR (default=Wake-on-LAN)



Generated Readings/Events:

• acg - Shows Automatic Gain Control value in percent; reflects overall signal quality strength
• apid - Shows the audio process ID for current channel
• ber - Shows Bit Error Rate for current channel
• channel - Shows the service name of current channel or media file name; part of FHEM-4-AV-Devices compatibility
• currentMedia - The service reference ID of current channel; part of FHEM-4-AV-Devices compatibility
• currentTitle - Shows the title of the running event; part of FHEM-4-AV-Devices compatibility
• enigmaversion - Shows the installed version of ENIGMA2
• eventcurrenttime - Shows the current time of running event as UNIX timestamp
• eventcurrenttime_hr - Shows the current time of running event in human-readable format
• eventcurrenttime_next - Shows the current time of next event as UNIX timestamp
• eventcurrenttime_next_hr - Shows the current time of next event in human-readable format
• eventdescription - Shows the description of running event
• eventdescriptionextended - Shows the extended description of running event
• eventdescriptionextended_next - Shows the extended description of next event
• eventdescription_next - Shows the description of next event
• evenduration - Shows the total duration time of running event in seconds
• evenduration_hr - Shows the total duration time of running event in human-readable format
• evenduration_next - Shows the total duration time of next event in seconds
• evenduration_next_hr - Shows the total duration time of next event in human-readable format
• eventname - Shows the name of running event
• eventname_next - Shows the name of next event
• eventremaining - Shows the remaining duration time of running event in seconds
• eventremaining_hr - Shows the remaining duration time of running event in human-readable format
• eventremaining_next - Shows the remaining duration time of next event in seconds
• eventremaining_next_hr - Shows the remaining duration time of next event in human-readable format
• eventstart - Shows the starting time of running event as UNIX timestamp
• eventstart_hr - Shows the starting time of running event in human readable format
• eventstart_next - Shows the starting time of next event as UNIX timestamp
• eventstart_next_hr - Shows the starting time of next event in human readable format
• eventtitle - Shows the title of the running event
• eventtitle_next - Shows the title of the next event
• fpversion - Shows the firmware version for the front processor
• hddX_capacity - Shows the total capacity of the installed hard drive in GB
• hddX_free - Shows the free capacity of the installed hard drive in GB
• hddX_model - Shows hardware details for the installed hard drive
• imageversion - Shows the version for the installed software image
• input - Shows currently used input; part of FHEM-4-AV-Devices compatibility
• iswidescreen - Indicates widescreen format - 0=off 1=on
• lanmac - Shows the device MAC address
• model - Shows details about the device hardware
• mute - Reports the mute status of the device (can be "on" or "off")
• nextTitle - Shows the title of the next event; part of FHEM-4-AV-Devices compatibility
• onid - The ON ID
• pcrpid - The PCR process ID
• pmtpid - The PMT process ID
• power - Reports the power status of the device (can be "on" or "off")
• presence - Reports the presence status of the receiver (can be "absent" or "present"). In case of an absent device, control is basically limited to turn it on again. This will only work if the device supports Wake-On-LAN packages, otherwise command "on" will have no effect.
• providername - Service provider of current channel
• recordings - Number of active recordings
• recordingsX_name - name of active recording no. X
• recordingsX_servicename - servicename of active recording no. X
• recordings_next - Shows the time of next recording as UNIX timestamp
• recordings_next_hr - Shows the time of next recording as human-readable format
• recordings_next_counter - Shows the time until next recording starts in seconds
• recordings_next_counter_hr - Shows the time until next recording starts human-readable format
• recordings_next_name - name of next recording
• recordings_next_servicename - servicename of next recording
• recordings_error - counter for failed recordings in timerlist
• recordings_finished - counter for finished recordings in timerlist
• servicename - Name for current channel
• servicereference - The service reference ID of current channel
• servicevideosize - Video resolution for current channel
• sid - The S-ID
• snr - Shows Signal to Noise for current channel in percent
• snrdb - Shows Signal to Noise in dB
• state - Reports current power state and an absence of the device (can be "on", "off" or "absent")
• tsid - The TS ID
• tuner_X - Details about the used tuner hardware
• txtpid - The TXT process ID
• videoheight - Height of the video resolution for current channel
• videowidth - Width of the video resolution for current channel
• volume - Reports current volume level of the receiver in percentage values (between 0 and 100 %)
• vpid - The Video process ID
• webifversion - Type and version of the used web interface

ESA2000

The ESA2000 module interprets ESA1000 or ESA2000 type of messages received by the CUL.

Define
define <name> ESA2000 <code> [base1 base2]

<code> is the 4 digit HEX code identifying the devices.

base1/2 is added to the total kwh as a base (Hoch- und Niedertarifzählerstand).

Set
N/A

Get
N/A

Attributes
• ignore


• do_not_notify


• showtime


• model (esa2000-led, esa2000-wz, esa2000-s0, esa1000wz-ir, esa1000wz-s0, esa1000wz-led, esa1000gas)


• IODev


• readingFnAttributes