fhem.pl reference

Contents

Introduction
Fhem command types
Device specification

fhem commands
attr   define   delete   deleteattr   get   getstate   ?,help   include   inform   list   modify   quit   reload   rereadcfg   save   set   setdefaultattr   setstate   shutdown   sleep   trigger   xmllist  

Devices
global
BS   CM11   CUL   CUL_EM   CUL_FHTTK   CUL_WS   CUL_RFR   DbLog   EM   EMEM   EMGZ   EMWZ   FHT   FHZ   FS20   HMS   FHEMWEB   IPWE   KS300   LIRC   M232   M232Counter   M232Voltage   OWFS   OWTEMP   DS18S20   SCIVT   structure   WS2000   WS300   Weather   USF1000   X10   FHEMRENDERER  

Helper modules
FileLog   PachLog   SUNRISE_EL   at   dummy   dumpdef   holiday   notify   watchdog   weblink  

Perl specials

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. FHZ1000 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:

fhem.pl ~/.fhem

A minimal configuration file:

    attr global logfile /tmp/fhem.log
    attr global statefile /tmp/fhem.save
    attr global verbose 3
    attr global port 7072
    attr global modpath /usr/local/lib
    define FHZ FHZ /dev/tts/USB0

    define lamp FS20 8765 01

For other configuration files see the examples subdirectory.

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

or
fhem.pl 7072 "set lamp off"

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


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, delete, get, list, set, 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 range of devices, separated by dash (-)
• a regular expression, if the the spec contains on e of the following characters: ^*[]$
• an attribute of the device, followed by an equal sign (=) and then a regexp for this attribute. As attribute you can specify either attributes set with the attr command or one of the "internal" attributes DEF, STATE and TYPE.
Example:
set lamp1 on
set lamp1,lamp2,lamp3 on
set lamp[1-3] on
set lamp.* on
set lamp1-lamp3 on
set lamp1-lamp3,lamp3 on
set room=kitchen off
list disabled=
list TYPE=FS20

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

?, help

?
help

Get a list of all commands and short description for each one

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>.

Attributes used by all devices:
• comment
  Add an arbitrary comment.
• room
  Filter/group devices. Recognized by web-pgm2 and web-pgm3. Devices in the room hidden will not appear in the web output.
• 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.

Device specific attributes are documented in the corresponding device section.
Examples:
attr global verbose 3
attr lamp room kitchen
attr lamp loglevel 6


Notes:

• See deleteattr to delete attributes.

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

define

define <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)".
Use "define <name> ?" to get a list of possible types.

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

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>.

Examples:
deleteattr lamp follow-on-for-timer
deleteattr lamp

delete

delete <devspec>

Delete something created with the define command. See the Device specification section for details on <devspec>.
Examples:
delete lamp

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.

getstate

getstate <devspec>

Output a short space seperated status for <devspec>. It is useful for monitoring the device in e.g. Cacti.
Examples:

  getstate lamp
  state:1

  getstate fl
  ack:0 actuator:2 day-temp:21.5 desired-temp:22.5 [...] measured-temp:22.9 [...]
    

Note: to use this command copy the file contrib/getstate/99_getstate.pm into your FHEM directory.

include

include <filename>

Read in the file, and process every line as a fhem command. Makes configuration files more modular and enables to reread them.

inform

inform [on|off|timer]

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:

  FHZ> 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.:

  FHZ> 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.

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

rereadcfg

rereadcfg

Re-read the configuration file. Note: The statefile will be saved first, then the config file will be read (all devices will be initialized again), and at last the statefile will be reloaded.

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 commands which were previously part of the config file. Put such commands in the lastinclude file.

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.

setstate

setstate <devspec> <value>

Set the "STATE" for <name> as shown in paranthesis in the list command to <value> without sending any signals to the device itself. This command is also used in the statefile. See the Device specification section for details on <devspec>.

Examples:
setstate lamp on
Note:
• The statefile uses another version of this command, don't be surprised.

shutdown

shutdown

Shut down the server (after saving the state information )

Example:
shutdown

trigger

trigger <devspec> <state>

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

Example:
trigger btn3 on

sleep

sleep <sec>

Sleep for a given amount, millisecond accuracy.

Example:
sleep 0.5
notify btn3 set lamp toggle;;sleep 0.5;;set lamp toggle

Note: As the server is not multithreaded, everything is blocked for the given amount.

xmllist

xmllist

Returns an XML tree of all definitions, all notify settings and all at entries. It is not intended for human consumption.

Example:

  FHZ> xmllist
  <FHZINFO>
          <internal_LIST>
                  <internal name="global" state="internal" sets="" attrs="room configfile logfile modpath pidfilename port statefile userattr verbose version">
                          <INT key="DEF" value="<no definition>"/>
                          <INT key="NR" value="0"/>
                          <INT key="STATE" value="internal"/>
      [...]

  

Devices

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
• allowfrom
  Comma (,) separated list of ip-addresses or hostnames. If set, only connections from these addresses are allowed.


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


• holday2we
  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


• lastinclude
  If this attribute is set, then the last command of the generated configfile (see the save command) will be
  include <lastinclude-value>
  This file is needed, as the save command will write only defines and attributes to the config file, any other commands / includes will be lost. E.g. it makes sense to set the FHTcode in this file.


• 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.


• 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).


• 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.


• 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.


• port
  Listen on the TCP/IP port <number> for incoming connections. To offer at least a little bit of security, the server will only listen for connections from the localhost per default. If there is a second value "global" then the server will listen for non-localhost connections too.


• 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
  Used by the web frontend fhemweb.pl (webpgm2) as a Page title.


• userattr
  A space separated list which contains the names of additional attributes. Without specifying them you will not be able to set them (in order to prevent typos).


• 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.
  Recommended level is 3 for normal use.

FHZ

Define
define <name> FHZ <serial-device>

Specifies the serial port to communicate with the FHZ1000PC or FHZ1300PC. The name(s) of the serial-device(s) depends on your distribution.
If the serial-device is called none, then no device will be opened, so you can experiment without hardware attached.
The program can service multiple devices, FS20 and FHT device commands will be sent out through the last FHZ device defined before the definition of the FS20/FHT device. To change the association, use the IODev attribute.

For GNU/Linux you may want to read our hints for GNU/Linux about multiple USB devices.
Note:The firmware of the FHZ1x00 will drop commands if the airtime for the last hour would exceed 1% (which corresponds roughly to 163 commands). For this purpose there is a command counter for the last hour (see list FHZDEVICE), which triggers with "TRANSMIT LIMIT EXCEEDED" if there were more than 163 commands in the last hour.

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


Set
set FHZ <variable> [<value>]

where value is one of:

FHTcode
initFS20
initHMS
initfull
raw
reopen
time

Notes:
• raw is used to send out "raw" FS20/FHT messages. See the doc directory for some examples
• In order to set the time of your FHT's, schedule this command every minute:
  define fhz_timer at +*00:01:00 set FHZ time
  See the loglevel to prevent logging of this command.
• FHTcode is a two digit hex number (from 00 to 63?) and sets the central FHT code, which is used by the FHT devices. After changing it, you must reprogram each FHT80b with: PROG (until Sond appears), then select CEnt, Prog, Select nA.
• If the FHT ceases to work for FHT devices whereas other devices (e.g. HMS, KS300) continue to work, a
  set FHZ initfull
  command could help. Try
  set FHZ reopen
  if the FHZ ceases to work completely. If all else fails, shutdown fhem, unplug and replug the FHZ device. Problems with FHZ may also be related to long USB cables or insufficient power on the USB - use a powered hub to avoid such issues.
• initfull issues the initialization sequence for the FHZ device:
  

              get FHZ init2
              get FHZ serial
              set FHZ initHMS
              set FHZ initFS20
              set FHZ time
              set FHZ raw 04 01010100010000

• reopen closes and reopens the serial device port. This implicitly initializes the FHZ and issues the initfull command sequence.

Get
get FHZ <value>

where value is one of:

init1
init2
init3
serial
fhtbuf

Notes:
• The mentioned codes are needed for initializing the FHZ1X00
• The answer for a command is also displayed by list FHZ
• The FHZ1x00PC has a message buffer for the FHT (see the FHT entry in the set section). If the buffer is full, then newly issued commands will be dropped, if the attribute fhtsoftbuffer is not set. fhtbuf returns the free memory in this buffer (in hex), an empty buffer in the FHZ1000 is 2c (42 bytes), in the FHZ1300 is 4a (74 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.

Attributes
• do_not_notify
  Disable FileLog/notify/inform notification for a device. This affects the received signal, the set and trigger commands.


• dummy


• showtime


• loglevel
  Set the device loglevel to e.g. 6 if you do not wish messages from a given device to appear in the global logfile (FHZ/FS20/FHT). E.g. to set the FHT time, you should schedule "set FHZ time" every minute, but this in turn makes your logfile unreadable. These messages will not be generated if the FHZ attribute loglevel is set to 6.


• model (fhz1000,fhz1300)


• fhtsoftbuffer
  Can be applied to FHZ devices.
  As the FHZ command buffer for FHT devices is limited (see fhtbuf), and commands are only sent to the FHT device every 120 seconds, the hardware buffer may overflow and FHT commands get lost. Setting this attribute implements an "unlimited" software buffer
  Default is disabled (i.e. not set or set to 0).

FS20

The FS20 protocol is used by a wide range of devices, which are either of the sender/sensor category or the receiver/actuator category. The radio (868.35 MHz) messages are either received through an FHZ or an CUL device, so this must be defined first.

Define
define <name> FS20 <housecode> <button> [fg <fgaddr>] [lm <lmaddr>] [gm FF]

The values of housecode, button, fg, lm, and gm can be either defined as hexadecimal value or as ELV-like "quad-decimal" value with digits 1-4. We will reference this ELV-like notation as ELV4 later in this document. You may even mix both hexadecimal and ELV4 notations, because FHEM can detect the used notation automatically by counting the digits.

• <housecode> is a 4 digit hex or 8 digit ELV4 number, corresponding to the housecode address.
• <button> is a 2 digit hex or 4 digit ELV4 number, corresponding to a button of the transmitter.
• The optional <fgaddr> specifies the function group. It is a 2 digit hex or 4 digit ELV address. The first digit of the hex adress must be F or the first 2 digits of the ELV4 address must be 44.
• The optional <lmaddr> specifies the local master. It is a 2 digit hex or 4 digit ELV address. The last digit of the hex address must be F or the last 2 digits of the ELV4 address must be 44.
• The optional gm specifies the global master, the adress must be FF if defined as hex value or 4444 if defined as ELV4 value.

Examples:
define lamp FS20 7777 00 fg F1 gm F
define roll1 FS20 7777 01
define otherlamp FS20 24242424 1111 fg 4412 gm 4444
define otherroll1 FS20 24242424 1114

Set
set <name> <value> [<time>]

where value is one of:


    dim06% dim12% dim18% dim25% dim31% dim37% dim43% dim50%
    dim56% dim62% dim68% dim75% dim81% dim87% dim93% dim100%
    dimdown
    dimup
    dimupdown
    off
    off-for-timer
    on                # dimmer: set to value before switching it off
    on-for-timer      # see the note
    on-old-for-timer  # set to previous (before switching it on)
    ramp-on-time      # time to reach the desired dim value on dimmers
    ramp-off-time     # time to reach the off state on dimmers
    reset
    sendstate
    timer
    toggle            # between off and previous dim val
    on-till           # Special, see the note

Examples:
set lamp on
set lamp1,lamp2,lamp3 on
set lamp1-lamp3 on
set lamp on-for-timer 12


Notes:
• Use reset with care: the device forgets even the housecode.
• As the FS20 protocol needs about 0.22 seconds to transmit a sequence, a pause of 0.22 seconds is inserted after each command.
• The FS20ST switches on for dim*%, dimup. It does not respond to sendstate.
• If the timer is set (i.e. it is not 0) then on, dim*, and *-for-timer will take it into account (at least by the FS20ST).
• The time argument ranges from 0.25sec to 4 hours and 16 minutes. As the time is encoded in one byte there are only 112 distinct values, the resolution gets coarse with larger values. The program will report the used timeout if the specified one cannot be set exactly. The resolution is 0.25 sec from 0 to 4 sec, 0.5 sec from 4 to 8 sec, 1 sec from 8 to 16 sec and so on. If you need better precision for large values, use at which has a 1 sec resolution.
• If the attribute follow-on-for-timer is set for the device and the on-for-timer command is sent to the device with a time parameter, the program automatically schedules a "setstate off" for the specified time.
• on-till requires an absolute time in the "at" format (HH:MM:SS, HH:MM or { <perl code> }, where the perl-code returns a time specification). If the current time is greater than the specified time, then the command is ignored, else an "on" command is generated, and for the given "till-time" an off command is scheduleld via the at command.

Get
N/A

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.


• do_not_notify


• dummy
  Set the device attribute dummy to define devices which should not output any radio signals. Associated notifys will be executed if the signal is received. Used e.g. to react to a code from a sender, but it will not emit radio signal if triggered in the web frontend.


• follow-on-for-timer
  the program automatically schedules a "setstate off" for the time specified as argument to the on-for-timer command (for the specified device only).


• loglevel


• showtime


• model
  The model attribute denotes the model type of the device. The attributes will (currently) not be used by the fhem.pl directly. It can be used by e.g. external programs or web interfaces to distinguish classes of devices and send the appropriate commands (e.g. "on" or "off" to a fs20st, "dim..%" to fs20du etc.). The spelling of the model names are as quoted on the printed documentation which comes which each device. This name is used without blanks in all lower-case letters. Valid characters should be a-z 0-9 and - (dash), other characters should be ommited. Here is a list of "official" devices:
  
  Sender/Sensor: fs20hgs fs20ls fs20pira fs20piri fs20s20 fs20s8 fs20s4 fs20s4a fs20s4m fs20s4u fs20s4ub fs20sd fs20sn fs20sr fs20ss fs20str fs20tfk fs20tk fs20uts fs20ze
  
  Receiver/Actor: fs20as1 fs20as4 fs20di fs20du fs20ms2 fs20rst fs20sa fs20sig fs20st fs20sv fs20sv fs20usr

FHT

Fhem can receive FHT radio (868.35 MHz) messages either through an FHZ or an CUL device, so this must be defined first.

Define
define <name> FHT <housecode>

<housecode> is a four digit hex number, corresponding to the adress of the FHT80b device.
Examples:
define wz FHT 3232


See the FHT section in set for more.

Set
set <name> <valuetype> <value>

where value is one of:


      desired-temp
      day-temp night-temp
      report1 report2
      mode
      holiday1 holiday2      # Not verified
      manu-temp              # No clue what it does.
      year month day hour minute
      lowtemp-offset         # Alarm-Temp.-Differenz
      windowopen-temp
      mon-from1 mon-to1 mon-from2 mon-to2
      tue-from1 tue-to1 tue-from2 tue-to2
      wed-from1 wed-to1 wed-from2 wed-to2
      thu-from1 thu-to1 thu-from2 thu-to2
      fri-from1 fri-to1 fri-from2 fri-to2
      sat-from1 sat-to1 sat-from2 sat-to2
      sun-from1 sun-to1 sun-from2 sun-to2

Examples:
set wz desired-temp 22.5
set fl desired-temp 20.5 day-temp 19.0 night-temp 16.0


Notes:
• Following events are reported (more or less regularly) by each FHT device: measured-temp actuator actuator1...actuator8 warnings
  You can use these strings for notify or FileLog definitions.
  • warnings can contain following strings: none, Battery low,Temperature too low, Window open, Fault on window sensor
  • actuator (without a suffix) stands for all actuators.
  • actuator or actuator1..8 can take following values:
    • <value>%
      This is the normal case, the actuator is instructed to open to this value.
    • offset <value>%
      The actuator is running with this offset.
    • lime-protection
      The actuator was instructed to execute the lime-protection procedure.
    • synctime
      If you select Sond/Sync on the FHT80B, you'll see a count down.
    • test
      The actuator was instructed by the FHT80b to emit a beep.
    • pair
      The the FHT80b sent a "you-belong-to-me" to this actuator.
    Note:
  
  
• The FHT is very economical (or lazy), it accepts one message from the FHZ1x00 every 115+x seconds, where x depends on the housecode. Don't be surprized if your command is only accepted 10 minutes later by the device. FHT commands are buffered in the FHZ1x00/CUL till they are sent to the FHT, see the related fhtbuf entry in the get section.
  You can send up to 8 commands in one message at once to the FHT if you specify them all as arguments to the same set command, see the example above.
  
  
• All *-temp values need a temperature as argument, which will be rounded to 0.5 Celsius.
  Temperature values must between 5.5 and 30.5 Celsius. Value 5.5 sets the actuator to OFF, value 30.5 set the actuator to ON
  
  
• mode is one of auto, manual, holiday or holiday_short.
  If the mode is holiday, then
  • holiday1 sets the end-day of the holiday
  • holiday2 sets the end-month of the holiday
  For holiday_short
  • holiday1 sets the time, in 10-minute steps
  • holiday2 sets number of days from now on.
  
  
• The *-from1/*-from2/*-to1/*-to2 valuetypes need a time spec as argument in the HH:MM format. They define the periods, where the day-temp is valid. The minute (MM) will be rounded to 10, and 24:00 means off.
  
  
• As the FHT stops sending the values every 5-10 days, it is adviseable to schedule following command regularly:
  define fht_report at +*06:00:00 set <name> report1 255 report2 255
  
  
• report1 with parameter 255 requests all settings for monday till sunday to be sent. The argument is a bitfield, to request unique values add up the following:
  • 1: monday
  • 2: tuesday
  • 4: thursday
  • 8: wednesday
  • 16: friday
  • 32: saturday
  • 64: sunday
  measured-temp and actuator is sent along if it is considered appropriate by the FHT.
  
  
• report2 with parameter 255 requests the following settings to be reported: day-temp night-temp windowopen-temp lowtemp-offset desired-temp measured-temp mode warnings. The argument is (more or less) a bitfield, to request unique values add up the following:
  • 1: warnings
  • 2: mode
  • 4: day-temp, night-temp, windowopen-temp
  • 64: lowtemp-offset
  measured-temp and actuator is sent along if it is considered appropriate by the FHT.
  
  
• lowtemp-offset needs a temperature as argument, valid values must be between 1.0 and 5.0 Celsius.
  It will trigger a warning if desired-temp - measured-temp > lowtemp-offset in a room for at least 1.5 hours after the last desired-temp change.
  
  
• FHEM optionally has an internal software buffer for FHT devices. This buffer should prevent transmission errors. If there is no confirmation for a given period, FHEM resends the command. You can see the queued commands with list <fht-device>. See the fhtsoftbuffer, retrycount and minfhtbuffer attributes for details.
  
  
• If a buffer is still in the softbuffer, it will be sent in the following order:
  desired-temp,mode,report1,report2, holiday1,holiday2,day-temp,night-temp, [all other commands]
  
  

Get
N/A

Attributes
• do_not_notify


• dummy
  Note:It makes sense to define an FHT device even for an FHT8b, else you will receive "unknown FHT device, please define one" message for each FHT8b as the CUL is reporting the 8b valve messages. But you should set the dummy attribute for these devices, else the internal FHT buffer of the CUL will be filled with data for the 8b's which is never consumed. If the buffer is full, you'll get "EOB" messages from the CUL, and you cannot transmit any data to the 80b's
• 
  
• loglevel


• model (fht80b)


• showtime


• IODev


• retrycount
  If the fhtsoftbuffer attribute is set, then resend commands retrycount times if after 240 seconds no confirmation message is received from the corresponding FHT device.
  Default is 3.


• minfhtbuffer
  FHEM won't send commands to the FHZ if its fhtbuffer is below this value, default is 0. If this value is low, then the ordering of fht commands (see the note in the FHT section of set) has little effect, as only commands in the softbuffer can be prioritized. The maximum value should be 7 below the hardware maximum (see fhtbuf).


• lazy
  If the lazy attribute is set, FHEM won't send commands to the FHT if the current reading and the value to be set are already identical. This may help avoiding conflicts with the max-1%-time-on-air rule in large installations. Not set per default.


• tmpcorr
  Correct the temperature reported by the FHT by the value specified. Note: only the measured-temp value reported by fhem (used for logging) will be modified.

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.

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
Nothing to set here yet ...

Get
No get implemented yet ...

Attributes
• do_not_notify


• dummy


• loglevel


• model (FHT80TF)


• showtime


• IODev

HMS

Define
define <name> HMS <housecode>

<housecode> is a four digit hex number, corresponding to the adress of the HMS device.
Examples:
define temp HMS 1234

Notes:

• There is _NO_ guarantee that the code will work as expected in all circumstances, the authors are not liable for any damage occuring as a result of incomplete or buggy code
• Currently supported devices are the HMS100-T HMS100-TF HMS100-WD HMS100-MG HMS100-TFK HMS100-CO HMS100-FIT RM100-2 RM100-3
• The housecode of the HMS devices may change if the battery is renewed. In order to make life easier, you can define a "wildcard" device for each type of HMS device. First the real device-id will be checked, then the wildcard device id. The wildcards are:
  • 1000 for the HMS100-TF
  • 1001 for the HMS100-T
  • 1002 for the HMS100-WD
  • 1003 for the RM100-2
  • 1004 for the HMS100-TFK/li>
  • 1006 for the HMS100-MG
  • 1008 for the HMS100-CO
  • 100e for the HMS100-FIT
• Some battery low notifications are not yet implemented (RM100, HMS100WD).
• Please test your installation before relying on the functionality.



Set
N/A

Get
N/A

Attributes
• do_not_notify


• loglevel


• showtime


• IODev


• model (hms100-t hms100-tf hms100-wd hms100-mg hms100-co hms100-tfk hms100-fit rm100-2)

CUL

The CUL/CUR/CUN is a family of RF devices sold by busware.de. With the opensource firmware (see this link) they are capable to receive and send different 868MHz protocols (FS20/FHT/S300/EM/HMS). 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.

Define
define <name> CUL <device> <housecode>

USB-connected devices (CUL/CUR/CUN):

<device> specifies the serial port to communicate with the CUL or CUR. 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.

Network-connected devices (CUN):

<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 housecode is a 4 digit hex number, and it is used when the CUL/CUR talks to FHT devices or when CUR requests data.

Set
• verbose
  Set a CUL "verbose" level. See the CUL firmware README document for details. Note: only X00/X01/X21/X25 is supported by the fhem CUL module, the other flags may crash fhem.


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


• freq / bWidth / rAmpl / sens
  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.


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


Get
• version
  return the CUL firmware version


• uptime
  return the CUL uptime (time since CUL reset).
• raw
  Issue a CUL firmware command, and wait for one line of data returned by the CUL. See the CUL firmware README document for details on CUL commands.


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


Attributes
• do_not_notify


• dummy


• showtime


• loglevel


• model (CUL,CUR)

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
• do_not_notify


• showtime


• loglevel


• model (S300,KS300,WS7000)


• IODev

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 mothly fees. Your COST will appear in the log, generated once daiy (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

Tipp: 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 substract 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
• do_not_notify


• showtime


• loglevel


• model (EMEM,EMWZ,EMGZ)


• IODev

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 u0100". 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 u0201". 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 u0100
# Now replace the base CUL with the RFR CUL
set MyCUL raw u0201
# 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
Same as for the CUL.

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
• loglevel

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
• loglevel
• 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
• loglevel
• IODev

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
• loglevel
• IODev

KS300

Fhem can receive the KS300 radio (868.35 MHz) messages through FHZ, WS300 or an CUL device, so one of them must be defined first.
This module services messages received by the FHZ device, if you use one of the other alternetives, see the WS300 or CUL_WS entries.
Note: The KS555 is also reported to work.

Define
define <name> KS300 <housecode> [ml/raincounter [wind-factor]]

<housecode> is a four digit hex number, corresponding to the adress of the KS300 device, right now it is ignored. The ml/raincounter defaults to 255 ml, but it must be specified if you wish to set the wind factor, which defaults to 1.0.
Examples:
define ks1 KS300 1234


Set
N/A

Get
N/A

Attributes
• do_not_notify
• showtime
• loglevel
• model (ks300)
• rainadjustment
  If this attribute is set, fhem automatically accounts for rain counter resets after a battery change and random counter switches as experienced by some users. The raw rain counter values are adjusted by an offset in order to flatten out the sudden large increases and decreases in the received rain counter values. Default is off.

CM11

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
• loglevel
• model (CM11)

X10

Define
define <name> X10 <model> <housecode> <unitcode>

Defines an X10 device via its model, housecode and unitcode.

Notes:
• <model> is one of
  • lm12: lamp module, dimmable
  • lm15: lamp module, not dimmable
  • am12: appliance module, not dimmable
  • tm12: tranceiver module, not dimmable. Its unitcode is 1.
  Model determines whether a dim command is reasonable to be sent or not.
• <housecode> ranges from A to P.
• <unitcode> ranges from 1 to 16.

Examples:
define lamp1 X10 lm12 N 10
define pump X10 am12 B 7
define lamp2 X10 lm15 N 11


Set
set <name> <value> [<argument>]

where value is one of:


    dimdown           # requires argument, see the note
    dimup             # requires argument, see the note
    off
    on
    on-till           # Special, see the note
    

Examples:
set lamp1 dimup 10
set lamp1,lamp2 off
set pump off
set lamp2 on-till 19:59


Notes:
• Only switching and dimming are supported by now.
• Dimming is valid only for a dimmable device as specified by the model argument in its define statement.
• An X10 device has 210 discrete brightness levels. If you use a X10 sender, e.g. a remote control or a wall switch to dim, a brightness step is 100%/210.
• dimdown and dimup take a number in the range from 0 to 22 as argument. It is assumed that argument 1 is a 1% brightness change (microdim) and arguments 2 to 22 are 10%..100% brightness changes. The meaning of argument 0 is unclear.
• This currently leads to some confusion in the logs as the dimdown and dimup codes are logged with different meaning of the arguments depending on whether the commands were sent from the PC or from a remote control or a wall switch.
• dimdown and dimup from on and off states may have unexpected results. This seems to be a feature of the X10 devices.
• on-till requires an absolute time in the "at" format (HH:MM:SS, HH:MM) or { <perl code> }, where the perl code returns a time specification). If the current time is greater than the specified time, then the command is ignored, else an "on" command is generated, and for the given "till-time" an off command is scheduleld via the at command.

Get
N/A

Attributes
• follow-on-for-timer


• do_not_notify


• dummy


• showtime


• model (lm12,lm15,am12,tm13)


• loglevel
• IODev

LIRC

Define
define <name> LIRC <device>

Set
N/A

Get
N/A

Attributes
N/A

WS300

Define
define WS300Device WS300 <serial device>
or
define <devname> WS300 [0-9]

The first line is mandatory if you have a WS300 device: it defines the input device with its USB port. The name of this device is fixed and must be WS300Device. It must be the first defined WS300 device.
For each additional device (with number 0 to 9) you have to define another WS300 device, with an arbitrary name. The WS300 device which reports the readings will be defined with the port number 9, an optional KS300 with the port number 8.

Examples:

      define WS300Device  WS300   /dev/ttyUSB1
      define ash2200.1    WS300   0
      define ks300        WS300   8
      define ws300        WS300   9
    


Set
set WS300Device <interval(min.)> <height(m)> <rainvalume(ml)>

Set some WS300 configuration parameters.
Get
N/A

Attributes
• do_not_notify
• loglevel
• model (ws300)

Weather

Define
define <name> Weather <location> [<interval>]

Defines a virtual device for weather forecasts. You need to have the perl module Weather::Google installed to use this device. If you do not have it, use cpan -i Weather::Google to install it.

A Weather device periodically gathers current and forecast weather conditions from the Google Weather API.

The parameter location is any string that is recognized as a location, either a town name or a zip code. Browse to the URL http://www.google.de/ig/api?weather=location&hl=en to see the raw output for your location.

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

Examples:

      define MyWeather Weather "Frankfurt,HE"
      define Forecast Weather "Amsterdam,NL" 1800
      define weather Weather "30000,France"
    


Set
N/A

Get
get <name> <reading>

Valid readings and their meaning (? can be one of 0, 1, 2, 3 and stands for today, tomorrow, ...):


city	name of town returned for location
condition	current condition, one of Sunny, Clear, Partly Cloudy, Mostly Cloudy, Overcast, Chance of Rain
current_date_time	last update of forecast on server
fc?_condition	forecast condition
fc?_day_of_week	day of week for day +?
fc?_high_c	forecasted daily high in degrees centigrade
fc?_icon	relative path for forecast icon, prefix with http://www.google.com to form a valid URL for display in web interfaces
fc?_low_c	forecasted daily low in degrees centigrade
humidity	current humidity
icon	relative path for current icon
postal_code	location sent to server
temp_c	current temperature in degrees centigrade
temp_f	current temperature in degrees Fahrenheit
wind_condition	wind direction and speed


Attributes
N/A

USF1000

Fhem can receive your tank's fill level from the USF1000S device through a FHZ device, so one must be defined first. The state contains the fill level in % (lower case v in the device state) and the current volume in liters (upper case V in the device state). Measured distance to the liquid's surface, fill level, volume and warnings (Test mode, Battery low) are available. Due to the design of the USF1000S protocol, you can have only one USF1000S in range of your FHZ as these devices cannot be distinguished.

Define
define <name> USF1000 <geometry>

<geometry> determines the form of the tank and the position of the sensor. The following geometries are currently supported:


• cub <length> <width> <height> <offset>
• cylv <diameter> <height> <offset>

cub stands for a cuboid whose base is <length> × <width>. cylv stands for a vertical cylinder whose diameter is <diameter>. <height> is the distance of the surface of the liquid from the ground if the tank is full. <offset> is the distance of the sensor relative to the surface of the liquid. All quantities are expressed in meters.

Example:

define MyTank USF1000 cylv 2 1 0.3: a cylindrical water tank with 2 meters diameter. The water stands 1 meter high if the tank is full. The sensor is fixed 1,3 meters above ground.


Set
N/A

Get
N/A

Attributes
• do_not_notify
• showtime
• loglevel
• model (usf1000s)

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
• loglevel
• model (bs)

SCIVT

Define
define <name> SCIVT <SCD-device>

Define a SCD series solar controler device. Details see here. You probably need a Serial to USB controller like the PL2303.
Defining an SCIVT device 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, only a single get function which reads the device status immediately.

Example:
define scd SCIVT /dev/ttyUSB2



Set
N/A

Get
get SCVIT data


Attributes
• loglevel
• model (SCD)

M232

Define
define <name> M232 <m232-device>

Define a M232 device. You can attach as many M232 devices as you like. A M232 device provides 6 analog inputs (voltage 0..5V with 10 bit resolution) and 8 bidirectional digital ports. The eighth digital port can be used as a 16 bit counter (maximum frequency 3kHz). The M232 device needs to be connected to a 25pin sub-d RS232 serial port. A USB-to-serial converter works fine if no serial port is available.

Examples:
define m232 M232 /dev/ttyUSB2



Set
set <name> stop

Stops the counter.

set <name> start

Resets the counter to zero and starts it.

set <name> octet

Sets the state of all digital ports at once, value is 0..255.

set <name> io0..io7 0|1

Turns digital port 0..7 off or on.


Get
get <name> [an0..an5]

Gets the reading of analog input 0..5 in volts.

get <name> [io0..io7]

Gets the state of digital ports 0..7, result is 0 or 1.

get <name> octet

Gets the state of all digital ports at once, result is 0..255.

get <name> counter

Gets the number of ticks of the counter since the last reset. The counter wraps around from 65,535 to 0 and then stops. See M232Counter for how we care about this.


Attributes
• loglevel
• model (m232)

M232Counter

Define
define <name> M232Counter [unit [factor [deltaunit [deltafactor]]]]

Define at most one M232Counter for a M232 device. Defining a M232Counter will schedule an internal task, which periodically reads the status of the counter, and triggers notify/filelog commands. unit is the unit name, factor is used to calculate the reading of the counter from the number of ticks. deltaunit is the unit name of the counter differential per second, deltafactor is used to calculate the counter differential per second from the number of ticks per second.

Default values:
• unit: ticks
• factor: 1.0
• deltaunit: ticks per second
• deltafactor: 1.0

Note: the parameters in square brackets are optional. If you wish to specify an optional parameter, all preceding parameters must be specified as well.

Examples:
define counter M232Counter turns
define counter M232Counter kWh 0.0008 kW 2.88 (one tick equals 1/1250th kWh)


Do not forget to start the counter (with set .. start for M232) or to start the counter and set the reading to a specified value (with set ... value for M232Counter).

To avoid issues with the tick count reaching the end point, the device's internal counter is automatically reset to 0 when the tick count is 64,000 or above and the reading basis is adjusted accordingly.


Set
set <name> value <value>

Sets the reading of the counter to the given value. The counter is reset and started and the offset is adjusted to value/unit.

set <name> interval <interval>

Sets the status polling interval in seconds to the given value. The default is 60 seconds.


Get
get <name> status

Gets the reading of the counter multiplied by the factor from the define statement. Wraparounds of the counter are accounted for by an offset (see reading basis in the output of the list statement for the device).


Attributes
• dummy


• loglevel
• model (M232Counter)

M232Voltage

Define
define <name> M232Voltage [an0..an5] [unit [factor]]

Define as many M232Voltages as you like for a M232 device. Defining a M232Voltage will schedule an internal task, which reads the status of the analog input every minute, and triggers notify/filelog commands. unit is the unit name, factor is used to calibrate the reading of the analog input.

Note: the unit defaults to the string "volts", but it must be specified if you wish to set the factor, which defaults to 1.0.

Example:
define volt M232Voltage an0
define brightness M232Voltage an5 lx 200.0



Set
N/A

Get
get <name> status


Attributes
• dummy


• loglevel
• model (M232Voltage)

OWFS

OWFS is a suite of programs that designed to make the 1-wire bus and its devices easily accessible. The underlying priciple is to create a virtual filesystem, with the unique ID being the directory, and the individual properties of the device are represented as simple files that can be read and written.

Note:
You need the owperl module from http://owfs.org/.

Define
define <name> OWFS <owserver-ip:port> <model> <id>

Define a 1-wire device to communicate with an OWFS-Server.

<owserver-ip:port>
IP-address:port from OW-Server.
<model>
Define the type of the input device. Currently supportet: DS1420
<id>
Corresponding to the id of the input device.


Note:
If the owserver-ip:port is called none, then no device will be opened, so you can experiment without hardware attached.

Example:
define DS9490R OWFS 127.0.0.1:4304 DS1420 93302D000000



Set
N/A

Get
get <name> <value>

where value is one of:

• address (read-only)
  The entire 64-bit unique ID. address starts with the family code.
  Given as upper case hexidecimal digits (0-9A-F).
• crc8 (read-only)
  The 8-bit error correction portion. Uses cyclic redundancy check. Computed from the preceeding 56 bits of the unique ID number.
  Given as upper case hexidecimal digits (0-9A-F).
• family (read-only)
  The 8-bit family code. Unique to each type of device.
  Given as upper case hexidecimal digits (0-9A-F).
• id (read-only)
  The 48-bit middle portion of the unique ID number. Does not include the family code or CRC.
  Given as upper case hexidecimal digits (0-9A-F).
• locator (read-only)
  Uses an extension of the 1-wire design from iButtonLink company that associated 1-wire physical connections with a unique 1-wire code. If the connection is behind a Link Locator the locator will show a unique 8-byte number (16 character hexidecimal) starting with family code FE.
  If no Link Locator is between the device and the master, the locator field will be all FF.
• present (read-only)
  Is the device currently present on the 1-wire bus?
• type (read-only)
  Part name assigned by Dallas Semi. E.g. DS2401 Alternative packaging (iButton vs chip) will not be distiguished.


Examples:
get DS9490R type
DS9490R type => DS1420

get DS9490R address
DS9490R address => 8193302D0000002B


Attributes
• dummy
• do_not_notify
• loglevel
• showtime
• temp-scale
  Specifies the temperature-scale unit:
  • C
    Celsius. This is the default.
  • F
    Fahrenheit
  • K
    Kelvin
  • R
    Rankine

OWTEMP

High-Precision 1-Wire Digital Thermometer.

Note:
Please define an OWFS device first.

Define
define <name> OWTEMP <id> [<interval>] [<alarminterval>]

Define a 1-wire Digital Thermometer device.

<id>
Corresponding to the id of the input device.
<interval>
Sets the status polling intervall in seconds to the given value. The default is 300 seconds.
<alarminterval>
Sets the alarm polling intervall in seconds to the given value. The default is 300 seconds.


Note:
Currently supported type: DS18S20.

Example:
define KG.hz.TF.01 OWTEMP 93302D000000 300 60



Set
set <name> <value>

where value is one of:

• templow (read-write)
  The upper limit for the low temperature alarm state.
• temphigh (read-write)
  The lower limit for the high temperature alarm state.
• ALARMINT (write-only)
  Sets the alarm polling intervall in seconds to the given value.
• INTERVAL (write-only)
  Sets the status polling intervall in seconds to the given value.

Get
get <name> <value>

where value is one of:

• address (read-only)
• crc8 (read-only)
• family (read-only)
• id (read-only)
• locator (read-only)
• present (read-only)
• temperature (read-only)
  Read by the chip at high resolution (~12 bits). Units are selected from the defined OWFS Device. See temp-scale for choices.
• templow (read-write)
• temphigh (read-write)
• type (read-only)


Examples:
get KG.hz.TF.01 type
KG.hz.TF.01 type => DS18S20

get KG.hz.TF.01 temperature
KG.hz.TF.01 temperature => 38.2500 (Celsius)


Attributes
• do_not_notify
• loglevel
• showtime

structure

Define
define <name> structure <struct_type> <dev1> <dev2> ...

The structure device is used to organize/structure a devices in order to set groups of them at once (e.g. switching everything off in a house).
The list of attached devices can be modified through the addstruct / delstruct commands. Each attached device will get the attribute <struct_type>=<name>
when it is added to the list, and the attribute will be deleted if the device is deleted from the structure. The structure devices can also be added to a structure, e.g. you can have a building consisting of levels which consists of rooms of devices.
Example:

• define kitchen structure room lamp1 lamp2
• addstruct kitchen TYPE=FS20
• delstruct kitchen lamp1
• define house structure building kitchen living
• set house off

Set
Every set command is propagated to the attached devices. Exception: if an attached devices has an attribute structexcluse, and the attribute value matches (as a regexp) the name of the current structure.

Get
get is not supported through a structure device.

Attributes
• structexclude
  exclude the device from set operations, see the set command above.

WS2000

Define
define <name> WS2000 <device_to_connect>

Define a WS2000 series raw receiver device sold by ELV. Details see here. Unlike 86_FS10.pm it will handle the complete device communication itself and doesnt require an external program. For this reason you can now use this also on windows.
This Device will be usually connect to a serial port, but you can also define a raw network redirector like lantronix XPORT(TM).
Note: Currently this device does not support a "set" function

Attributes:
• rain: factor for calculating amount of rain in ml/count
• altitude: height in meters to calculate pressure for NN (not used yet)

Example:
define WS2000 WS2000 /dev/ttyS0

define WS2000 WS2000 xport:10001

attr WS2000 rain 366 : use factor 366 ml/count for rain sensor S2000R



Set
N/A

Get
get <name> list
Gets the last reading of all received sensord

get <name> [TH0..TH7, T0..T7, I0..I7, R0..R7, W0..W7, L0..L7, P0..P7,LAST,RAW]
get the last reading for the name sensor,
LAST: Last received Sensor

RAW: original Data from interface


Attributes
• model (ws2000)
• loglevel
• rain
• altitude

IPWE

Define
define <name> IPWE <hostname> [<delay>]

Define a IPWE network attached weather data receiver device sold by ELV. Details see here. It's intended to receive the same sensors as WS300 (8 T/H-Sensors and one kombi sensor), but can be accessed via http and telnet.
For unknown reason, my try to use the telnet interface was not working neither with raw sockets nor with Net::Telnet module. Therefore i choosed here the "easy" way to simple readout the http page and extract all data from the offered table. For this reason this module doesnt contain any option to configure this device.

Note: You should give your sensors a name within the web interface, once they a received the first time.
To extract a single sensor simply match for this name or sensor id

Attributes:
• delay: seconds between read accesses(default 300s)

Example:
define ipwe IPWE ipwe1 120

attr ipwe delay 600 : 10min between readouts



Set
N/A

Get
get <name> status

Gets actual data from device for sensors with data

get <name> <sensorname>

will grep output from device for this sensorname


Attributes
• model (ipwe)
• delay
• loglevel

weblink

Define
define <name> weblink [link|fileplot] <argument>

This is a placeholder used with webpgm2 to be able to integrate links into it, and to be able to put more than one gnuplot/SVG picture on one page. It has no set or get methods. Examples:
define wl_1 weblink link http://www.fhem.de
define wl_2 weblink fileplot <logdevice>:<gnuplot-file>:<logfile>


Notes:
• Normally you won't have to define fileplot weblinks manually, as FHEMWEB makes it easy for you, just plot a logfile (see logtype) and convert it to weblink. Now you can group these weblinks by putting them into rooms. If you convert the current logfile to a weblink, it will always refer to the current file (and not the one you originally specified).
Set
N/A

Get
N/A

Attributes
• fixedrange
• plotsize
• plotmode
• label
  Colon separated list of values. The values will be used to replace <L#> type of strings in the .gplot file, with # beginning at 1 (<L1>, <L2>, etc.). Each value will be evaluated as a perl expression, so you have access e.g. to the $value hash.
  
  If the plotmode is gnuplot-scroll or SVG, you can also use the min, max, avg, cnt, lastv (last value) and lastd (last date) values of the individual curves, by accessing the corresponding values from the data hash, see the example below:
  
  • Fixed text for the right and left axis:
    
    • Fhem config:
      attr wl_1 label "Temperature":"Humidity"
    • .gplot file entry:
      set ylabel <L1>
      set y2label <L2>
  • Title with maximum and current values of the 1st curve (FileLog)
    • Fhem config:
      attr wl_1 label "Max $data{max1}, Current $data{lastv1}"
    • .gplot file entry:
      set title <L1>
      
• title
  A special form of label (see above), which replaces the string <TL> in the .gplot file. It defaults to the filename of the logfile.

FHEMWEB

FHEMWEB is the builtin web-frontend (webpgm2). It implements a simple web server, so no additional program is needed. However, if HTTPS is desired, FHEMWEB must be configured to run behind a webserver (e.g. apache) which translates the HTTPS from the outside to HTTP for FHEMWEB.

Define
define <name> FHEMWEB <tcp-portnr> [global]

Enable the webfrontend on port <tcp-portnr>. If global is specified, then requests from all interfaces (not only localhost / 127.0.0.1) are serviced.

Set
N/A

Get
N/A

Attributes
• webname
  Path after the http://hostname:port/ specification. Defaults to fhem, i.e the default http address is http://localhost:8083/fhem


• refresh
  If set, a http-equiv="refresh" entry will be genererated with the given argument (i.e. the browser will reload the page after the given seconds).


• plotmode
  Specifies how to generate the plots:
  • gnuplot
    Call the gnuplot script with each logfile. The filename specification of the FileLog device will determine what is in the plot. The data is converted into an image on the backend with gnuplot.
  • gnuplot-scroll
    Fhemweb will offer zoom and scroll buttons in order to navigate in the current logfile, i.e. you can select just a part of the data to be displayed. The more data is contained in a single logfile, the easier you can navigate. The recommendation is to store the data for a whole year in one logfile. The data is converted into an image on the backend with gnuplot.
  • SVG
    The same scrolling as with gnuplot scroll, but the data is sent as an SVG script to the frontend, which will compute the image: no need for gnuplot on the backend.
  See also the attribute fixedrange. Note: for gnuplot & gnuplot-scroll mode the gnuplot output is redirected to the file gnuplot.err in the /tmp directory


• plotsize
  the default size of the plot, in pixels, separated by comma: width,height. You can set individual sizes by setting the plotsize of the weblink.


• fixedrange
  Can be applied to weblink devices (FHEMWEB).
  Contains two time specs in the form YYYY-MM-DD separated by a space. In plotmode gnuplot-scroll or SVG the given time-range will be used, and no scrolling for this weblinks will be possible. Needed e.g. for looking at last-years data without scrolling.

at

Start an arbitrary fhem.pl command at a later time.

Define
define <name> at <timespec> <command>

<timespec> format: [+][*{N}]<timedet>

The optional + indicates that the specification is relative(i.e. it will be added to the current time).
The optional * indicates that the command should be executed repeatedly.
The optional {N} after the * indicates,that the command should be repeated N-times only.
<timedet> is either HH:MM, HH:MM:SS or {perlfunc()}, where perlfunc must return a HH:MM or HH:MM:SS date.

Examples:

    # absolute ones:
    define a1 at 17:00:00 set lamp on                            # fhem command
    define a2 at 17:00:00 { Log 1, "Teatime" }                   # Perl command
    define a3 at 17:00:00 "/bin/echo "Teatime" > /dev/console"   # shell command
    define a4 at *17:00:00 set lamp on                           # every day

    # relative ones
    define a5 at +00:00:10 set lamp on                  # switch the lamp on in 10 seconds
    define a6 at +00:00:02 set lamp on-for-timer 1      # Blink once in 2 seconds
    define a7 at +*{3}00:00:02 set lamp on-for-timer 1  # Blink 3 times

    # Blink 3 times if the piri sends a command
    define n1 notify piri:on.* define a8 at +*{3}00:00:02 set lamp on-for-timer 1

    # Switch the lamp on from sunset to 11 PM
    define a9 at +*{sunset_rel()} set lamp on
    define a10 at *23:00:00 set lamp off

    # More elegant version, works for sunset > 23:00 too
    define a11 at +*{sunset_rel()} set lamp on-till 23:00

    # Only do this on weekend
    define a12 at +*{sunset_rel()} { fhem("set lamp on-till 23:00") if($we) }

    # Switch lamp1 and lamp2 on from 7:00 till 10 minutes after sunrise
    define a13 at *07:00 set lamp1,lamp2 on-till {sunrise(+600)}

    # Switch the lamp off 2 minutes after sunrise each day
    define a14 at +{sunrise(+120)} set lamp on

    # Switch lamp1 on at sunset, not before 18:00 and not after 21:00
    define a15 at *{sunset(0,"18:00","21:00")} set lamp1 on

    

Notes:

• if no * is specified, then a command will be executed only once, and then the at entry will be deleted. In this case the command will be saved to the statefile (as it considered volatile, i.e. entered by cronjob) and not to the configfile (see the save command.)
• if the current time is greater than the time specified, then the command will be executed tomorrow.
• For even more complex date handling you either have to call fhem from cron or filter the date in a perl expression, see the last example and the section Perl special.


Set
N/A

Get
N/A

Attributes
• disable
  Can be applied to at/watchdog/notify/FileLog devices.
  Disables the corresponding at/notify or FileLog device. Note: If applied to an at, the command will not be executed, but the next time will be computed.


• skip_next
  Used for at commands: skip the execution of the command the next time.

holiday

Define
define <name> holiday

Define a set of holidays. The module will try to open the file <name>.holiday in the modpath/FHEM directory. If an entry in the holiday file matches the current day, then the STATE of this holiday instance displayed in the list command will be set to the holiday, else the state is set to the text none. Most probably you'll want to query this value in some perl script: see $value in the perl section or the global attribute holiday2we.
The file will be reread once every night, to compute the value for the current day, and by each get command (see below).

Holiday file definition:
The file may contain comments (beginning with #) or empty lines. Significant lines begin with a number (type) and contain some space separated words, depending on the type. The different types are:

• 1
  Exact date. Arguments: <MM-DD> <holiday-name>
  Exampe: 1 12-24 Christmas
• 2
  Easter-dependent date. Arguments: <day-offset> <holiday-name>. The offset is counted from Easter-Sunday. Note: the perl module DateTime::Event::Easter must be installed to use this type of holiday.
  Exampe: 2 1 Easter-Monday
• 3
  Month dependent date. Arguments: <nth> <weekday> <month <holiday-name>.
  Examples:
  
  3 1 Mon 05 First Monday In May
  3 2 Mon 05 Second Monday In May
  3 -1 Mon 05 Last Monday In May
  3 0 Mon 05 Each Monday In May
  
• 4
  Interval. Arguments: <MM-DD> <MM-DD> <holiday-name> .
  Example:
  
  4 01-06 31-06 Summer holiday
  
• 5
  Date relative, weekday fixed holiday. Arguments: <nth> <weekday> <month> <day> < holiday-name>
  Note that while +0 or -0 as offsets are not forbidden, their behaviour is undefined in the sense that it might change without notice.
  Examples:
  
  5 -1 Wed 11 23 Buss und Bettag (first Wednesday before Nov, 23rd)
  5 1 Mon 01 31 First Monday after Jan, 31st (1st Monday in February)
  
See also he.holiday in the contrib directory for official holidays in the german country of Hessen, and by.holiday for the Bavarian definition.

Set
N/A

Get
get <name> <MM-DD>

Return the holiday name of the specified date or the text none.



Attributes
N/A

notify

Define
define <name> notify <pattern> <command>

Execute a command when received an event for the definition <pattern>. If <command> is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). See the trigger command for testing it. Examples:
define b3lampV1 notify btn3 set lamp %
define b3lampV2 notify btn3 { fhem "set lamp %" }
define b3lampV3 notify btn3 "/usr/local/bin/setlamp "%""
define b3lampV3 notify btn3 set lamp1 %;;set lamp2 %
define wzMessLg notify wz:measured.* "/usr/local/bin/logfht @ "%""
define LogUndef notify UNDEFINED "send-me-mail.sh "%""


Notes:
• The character % will be replaced with the received event, e.g. with on or off or measured-temp: 21.7 (Celsius)
  It is advisable to put the % into double quotes, else the shell may get a syntax error.
• The character @ will be replaced with the device name.
• To use % or @ in the text itself, use the double mode (%% or @@).
• Instead of % and @, the parameters %EVENT (same as %), %NAME (same as @) and %TYPE (contains the device type, e.g. FHT) can be used. A single % looses its special meaning if any of these parameters appears in the definition.
• <pattern> may also be a compound of definition:event to filter for events.
• <pattern> must completely (!) match either the device name, or the compound of the device name and the event. The event is either the string you see in the list output in paranthesis after the device name, or the string you see when you do a detailed list of the device.
• To use database logging, copy the file contrib/91_DbLog.pm into your modules directory, and change the $dbconn parameter in the file.
• Each undefined device (FS20, HMS, FHT) will be reported with the device name "UNDEFINED". The % parameter will contain the type (FS20, HMS100T, etc) and device number, separated by a space.

Set
N/A

Get
N/A

Attributes
• disable

watchdog

Define
define <name> watchdog <regexp1> <timespec> <regexp2> <command>

Start an arbitrary fhem.pl command if after <timespec> receiving an event matching <regexp1> no event matching <regexp2> is received.
The syntax for <regexp1> and <regexp2> is the same as the regexp for notify.
<timespec> is HH:MM[:SS]
<command> is a usual fhem command like used int the at or notify

Examples:

    # "Reset" the FHT80 if we do not receive any message for 15 Minutes
    define w watchdog FHT80 00:15:00 SAME set FHT80 refreshvalues
    # Shout if the HMS100-FIT is not alive
    define w watchdog HMS100-FIT 01:00:00 SAME "alarm-fit.sh"
    

Notes:

• if <regexp1> is . (dot), then activate the watchdog at definition time. Else it will be activated when the first matching event is received.
• if <regexp2> is SAME, then it will be the same as the first regexp, and it will be reactivated, when it is received. This is probably the normal operation.


Set
N/A

Get
N/A

Attributes
• disable

DbLog

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

Log events to a database. The database connection is defined in <configfilename> (see sample configuration file 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.

You must have 93_DbLog.pm in the FHEM subdirectory to make this work. Additionally, 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 database is in fhemdb_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 means of the perl script fhemdb_get.pl. Its output is adapted to what a Cacti data input method expects. Call fhemdb_get.pl without parameters to see the usage information.

Examples:
# log everything to database
define logdb DbLog /etc/fhem/db.conf .*:.*
Set
N/A

Get
N/A

Attributes
N/A

FileLog

Define
define <name> FileLog <filename> <regexp>

Log events to <filename>. The log format is

      YYYY:MM:DD_HH:MM:SS <device> <event>

The regexp will be checked against the (complete!) device name or against the (complete!) devicename:event combination.
<filename> may contain one or more of the following wildcards (a subset of the Unix date command arguments):
• %d day of month (01..31)
• %m month (01..12)
• %Y year (1970...)
• %w day of week (0..6); 0 represents Sunday
• %j day of year (001..366)
• %U week number of year with Sunday as first day of week (00..53)
• %V week number of year with Monday as first day of week (01..53)
Examples:
define lamplog FileLog /var/tmp/lamp.log lamp
define wzlog FileLog /var/tmp/wz-%Y-%U.log wz:(measured-temp|actuator).*



Set
set <name> reopen
Used to reopen a FileLog after making some manual changes to the logfile.

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

Read data from the logfile.
• <infile>
  Name of the logfile to grep. "-" is the current logfile, or you can specify an older file (or a file from the archive).
• <outfile>
  If it is "-", you get the data back on the current connection, else it is the prefix for the output file. If more than one file is specified, the data is separated by a comment line for "-", else it is written in separate files, numerated from 0.
• <from> <to>
  Used to grep the data. The elements should correspond to the timeformat or be an initial substring of it.
• <column_spec>
  For each column_spec return a set of data in a separate file or separated by a comment line on the current connection.
  Syntax: <col>:<regexp>:<default>:<fn>
  
  • <col> The column number to return, starting at 1 with the date. If the column is enclosed in double quotes, then it is a fix text, not a column nuber.
  • <regexp> If present, return only lines containing the regexp. Case sensitive.
  • <default>
    If no values were found and the default value is set, then return one line containing the from value and this default. We need this feature as gnuplot aborts if a dataset has no value at all.
  • <fn> One of the following:
    • int
      Extract the integer at the beginning og the string. Used e.g. for constructs like 10%
    • delta-h or 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.
    • everything else
      The string is evaluated as a perl expression. @fld is the current line splitted by spaces. Note: The string/perl expression cannot contain spaces, as the part after the space will be considered as the next column_spec.


Example:

get outlog out-2008.log - 2008-01-01 2008-01-08 4:IR:int: 9:IR::




Attributes
• archivecmd / archivedir / nrarchive
  When a new FileLog file is opened, the FileLog archiver wil be called. This happens only, if the name of the logfile has changed (due to time-specific wildcards, see the FileLog section), and there is a new entry to be written into the file.
  If the attribute archivecmd is specified, then it will be started as a shell command (no enclosing " is needed), and each % in the command will be replaced with the name of the old logfile.
  If this attribute is not set, but nrarchive and/or archivecmd is set, then all superfluous logfiles will be moved to archivedir (or deleted if archivedir is not set).


• disable
• logtype
  Used by the pgm2 webfrontend to offer gnuplot/SVG images made from the logs. The string is made up of tokens separated by comma (,), each token specifies a different gnuplot program. The token may contain a colon (:), the part before the colon defines the name of the program, the part after is the string displayed in the web frontend. Currently following types of gnuplot programs are implemented:
  
  • fs20
    Plots on as 1 and off as 0. The corresponding filelog definition for the device fs20dev is:
    define FileLog fslog fs20dev /var/log/fs20dev-%Y-%U.log
  • fht
    Plots the measured-temp/desired-temp/actuator lines. The corresponding filelog definitions (for the FHT device named fht1) looks like:
    define FileLog fhtlog1 fht1:.*(temp|actuator).* /var/log/fht1-%Y-%U.log
  • ks300_1
    Plots the temperature and rain (per hour and per day) of a ks300. The corresponding filelog definitions (for the KS300 device named ks300) looks like:
    define FileLog ks300log ks300:.*H:.* /var/log/ks300-%Y-%U.log
  • ks300_2
    Plots the humidity and wind values of a ks300. The corresponding filelog definition is the same as above, both programs evaluate the same log.
  • text
    Shows the logfile as it is (plain text). Not gnuplot definition is needed.
  Example:
  attr fhtlog1 logtype ks300_1:Temp/Rain,ks300_2:Hum/Wind,text:Raw-data

dummy

Define a dummy. A dummy can take via set any values. Used for programming.

Define
define <name> dummy

Example:
define myvar dummy
set myvar 7


Set
set <name> <value>
Set any value.

Get
N/A

Attributes
• loglevel

SUNRISE_EL

This module is used to define the functions

sunrise, sunset,
sunrise_rel, sunset_rel
sunrise_abs, sunset_abs
isday

perl functions, to be used in at or FS20 on-till commands.
First you should edit SUNRISE_EL.pm, and set long and lat to the exact longitude and latitude values (see e.g. maps.google.com for the exact values, which should be in the form of a floating point value). The default value is Frankfurt am Main, Germany.

The default altitude ($altit in SUNRISE_EL.pm) defines the sunrise/sunset for Civil twilight (i.e. one can no longer read outside without artificial illumination), which differs from sunrise/sunset times found on different websites. See perldoc "DateTime::Event::Sunrise" for alternatives.

sunrise()/sunset() returns the absolute time of the next sunrise/sunset, adding 24 hours if the next event is tomorrow, to use it in the timespec of an at device or for the on-till command for FS20 devices.
sunrise_rel()/sunset_rel() returns the relative time to the next sunrise/sunset.
sunrise_abs()/sunset_abs() return the absolute time of the corresponding event today (no 24 hours added).
All functions take up to three arguments:

• The first specifies an offset (in seconds), which will be added to the event.
• The second and third specify min and max values (format: "HH:MM").

isday() can be used in some notify or at commands to check if the sun is up or down.

Define
N/A

Set
N/A

Get
N/A

Attributes
N/A

FHEMRENDERER

The FHEMRENDERER module is intended to render (draw) graphics based on the FHEM Log-Files. This can be done either based on a timer (used in the module) or based on a direct call of GET. The rendered graphics will be stored in a pre-defined directory with a predefined prefix of the files.

Define
define <name> FHEMRENDERER [global]

This defines a new "device", that is of type FHEMRENDERER. The option 'global' can be used if needed for sorting reasons. Otherwise this option has no real meaning for FHEMRENDERER.

As a side-effect of defining this "device" the following attributes will be set for this "device":
  plotmode gnuplot
  plotsize 800,200
  refresh 00:10:00
  room Unsorted
  status off
  tmpfile /tmp/

NOTE: The Logfile will report (with LogLevel 2) that the FHEMRENDERER has been defined.

Set
set <name> <value>
Set either on or off.

This switches the timer-based rendering on/off. The attribute 'status' will be modified accordingly.
NOTE: only WebLink based graphics will be rendered.

Get
get <name> <[[file-name] device type logfile [pos=zoom=XX&off=YY]]>

The get function supports different sets of arguments:
Arguments:
   NONE: all WebLink based FilePlots will be rerendered
     The resulting filename will be '.png'
   THREE: device type logfile
     In this case only one specific graphic will be rendered:
     A graphic will be rendered for 'device', where device is a FileLog, based on the type 'type' based on the given 'logfile'
     The resulting filename will be 'attr-tmpfile logfile.png'
   FOUR: file-name device type logfile
     In this case only one specific graphic will be rendered:
     A graphic will be rendered for 'device', where device is a FileLog, based on the type 'type' based on the given 'logfile'
     The resulting filename will be 'attr-tmpfile file-name.png'
   FIVE: file-name device type logfile pos=zoom=XX&off=YYY
     In this case only one specific graphic will be rendered assuming that plotmode is 'gnuplot-scroll':
     A graphic will be rendered for 'device', where device is a FileLog, based on the type 'type' based on the given 'logfile'
     The 'zoom' will be either qday/day/week/month/year (same as used in FHEMWEB).
     The offset 'off' is either 0 (then the second part can be omitted, or -1/-2.... to jump back in time.
     The resulting filename will be 'attr-tmpfile file-name.png'

NOTE: If you want to use zoom AND offset then you have to concatenate via '&' !!

NOTE: combinations are possible in limited ranges:
meaning: you can add the 'pos=zoom=XX&off=YY' to any of the first three sets.
This may e.g. result in rendering all WebLinks with a specific zoom or offset
(if you just pass the 'pos=zoom=xx&off=yy' parameter);

Any rendered image (one or all WebLinks) will be stored in 'attr-tmpfile' followed by a 'filename.png'. The filename will be either derived (from weblink-name or logfile-name) or, for single files, can be assigend.


Attributes
• plotmode
  Specifies how to generate the plots:
  • gnuplot
    Call the gnuplot script with each logfile. The filename specification of the FileLog device will determine what is in the plot. The data is converted into an image on the backend with gnuplot.
  • gnuplot-scroll
    FHEMRENDERER will offer zoom and offset possibilities in order to navigate in the current logfile, i.e. you can select just a part of the data to be displayed. The more data is contained in a single logfile, the easier you can navigate. The recommendation is to store the data for a whole year in one logfile. The data is converted into an image on the backend with gnuplot.


• plotsize
  the default size of the plot, in pixels, separated by comma: width,height. You can set individual sizes by setting the plotsize of the weblink.


• status
  Reflects the status, if the renderer timer has been set to ON or OFF. By reading the status, you can detect, if the timer is running, or not.


• refresh
  This defines the time-interval in which a new rendering of the defined WebLinks will be done.


• tmpfile
  This gives the path and a possible prefix for the rendered filenames.
  You can specify a path to which the files will be rendered. If you also specify a prefix, this will be used to build the resulting filename.

PachLog

The PachLog module logs sensor data like temperature and humidity to www.pachube.com.

Define

define <name> PachLog <Pachube-API-Key>

<Pachube-API-Key>:
You need the Pachube-API-Key to authenticate your application to the Pachube service.
Don't share this with anyone: it's just like a password.


Set

Add a new device for logging to www.pachube.com

set <NAME> ADD <FHEM-DEVICENAME> FEED-NR:ID:READING:ID:READING

Example: KS300 weather data

READING: temperature humidity wind rain

1. Generate input feed on www.pachube.com => You get your FEED-NR: 1234
2. Add datastreams to the feed:


ID	0	temperature
ID	1	humidity
ID	2	wind
ID	3	rain



3. Add the KS300 to your PachLog device

set <NAME> ADD <My-KS300> 1234:0temperature:1:humidity:2:wind:3:rain

Delete a device form logging to www.pachube.com

set <NAME> DEL <FHEM-DEVICENAME>



Get
N/A

Attributes
N/A

dumpdef

dumpdef <options>

Data::Dumper for FHEM-Devices/Hashes

Dumps the content of <options> to FHEMWEB

Options:



FHEM-DEVICENAME	=>	%defs{FHEM-DEVICENAME}+%attr{FHEM-DEVICENAME}
MOD	=>	%modules
SEL	=>	%selectlist
DAT	=>	%data
CMD	=>	%cmd



Example:

dumpdef TEST


CALLER => main: /opt/fhz/FHEM/01_FHEMWEB.pm LINE: 194 SUB: main::FW_AnswerCall
SUB-NAME: main::Commanddumpdef
DUMP-DEVICE: TEST
$VAR1 = {
'IODev' => {},
'NAME' => 'TEST',
'NR' => 64,
'STATE' => '???',
'TYPE' => 'dummy'
};
DUMP-DEVICE-ATTR
$VAR1 = {
'room' => 'DEF_DUMMY,GRP.TEST'
};

Perl specials

• To use fhem commands from the perl expression, use the function "fhem", which takes a string argument, this string will be evaluated as a fhem command chain.
  Example:
  define n1 notify piri:on { fhem "set light on" }
• To make date and time handling easier, before evaluating a perl expression the variables $sec, $min, $hour, $mday, $month, $year, $wday, $yday, $isdst are set (see perldoc -f localtime), with the exception that $month is in the range of 1 to 12, and $year is also corrected by 1900 (as one would normally expect). Additionally $we is 1 if it is weekend (i.e $wday == 0 || $wday == 6), and 0 otherwise. If the holida2we global attribute is set, $we is 1 for holidays too. Example:
  define n2 notify piri:on { if($hour > 18 || $hour < 5) { fhem "set light on" } }
• The following small helper functions are defined in 99_Util.pm (which will be loaded automatically):
  • min(a,b), max(a,b)
  • time_str2num("YYYY-MM-DD HH:MM:SS") returns a numerical value, which makes computation of time differences easier
  • abstime2rel("HH:MM:SS") converts an absolute time to a relative one, to compare it with the sunrise commands in the following example:
    # Switch lamp1 on at sunrise, but not before 07:00
    define a13 at +*{max(abstime2rel("07:00"),sunrise_rel())} set lamp1 on
• Note: do not forget to escape the semicolon (;) with two semicolons (;;), else your perl code will be interpreted as an fhem command and you most certainly get syntax errors.
• The current value (the string you see in paranthesis in the output of the list command) is available in the value hash; to access it use $value{<devicename>}
  If you need the old value (and time) of the currently triggered device, then you can access it with $oldvalue{$dev}{TIME} and $oldvalue{$dev}{VAL}.
  
• To access the numerical value of an FS20 command (e.g. toggle), use the hash fs20_c2b. E.g. { Log 2, $fs20_c2b{"toggle"} }
• By using the 99_SUNRISE_EL.pm module, you have access to the following functions:
  
  sunset_rel()
  sunset_abs()
  sunrise_rel()
  sunrise_abs()
  isday()
  
  The _rel functions should be used as "at" spec, and the _abs functions as argument to the on-till argument of the set command.
  isday returns 1 if the sun is visible, and 0 else.