Contents
Introduction
Fhem is mainly used for home automation, but it is suitable for other tasks
too, where notification, timers and logging plays an important role.
It supports different hardware devices to interface with certain protocols
(e.g. FHZ1000PC to interface FS20 and HMS, CM11 to access X10), and logical
devices like FS20 or FHT to digest the messages for a certain device type using
this protocol.
Fhem is modular. The different devices are represented through modules which
implement certain functions (e.g. define, get, set). Even seemingly integral
parts of fhem like triggers (notify) and timers (at) are implemented this way, giving the possibility to
replace/extend this functionality.
Fhem is controlled through readable / ascii commands, which are specified in
files (e.g. the configuration file), or issued over a TCP/IP connection, either
directly in a telnet session, with a fhem.pl in client mode or from one of the
web frontends.
When starting the server you have to specify a configuration file:
A minimal configuration file looks like:
attr global logfile log/fhem.log
attr global modpath .
attr global statefile log/fhem.save
attr global verbose 3
define telnetPort telnet 7072 global
define WEB FHEMWEB 8083 global
Note: the last two lines are optional and assume you wish to use the
builtin telnet and WEB interface.
The web interface can be reached at
TCP/IP communication with fhem can either happen in a "session" (via
telnet) or single client command (via fhem.pl). Example:
telnet <fhemhost> 7072
<NL> (This newline switches into "prompt" mode)
<command>...
quit
or
fhem.pl <fhemhost>:7072 "<fhem-command>" "..."
Fhem command types
There are three types of commands: "fhem" commands (described in this
document), shell commands (they must be enclosed in double quotes ") and perl
expressions (enclosed in curly brackets {}). shell commands or perl expressions
are needed for complex at or notify
arguments, but can also issued as a "normal" command.
E.g. the following three commands all do the same when issued from a telnet
prompt:
set lamp off
"fhem.pl 7072 "set lamp off""
{fhem("set lamp off")}
Shell commands will be executed in the background, perl expressions and
fhem commands will be executed in the main "thread". In order to make perl
expressions easier to write, some special functions and variables are
available. See the section Perl special for a description.
To trigger fhem commands from a shell script (this is the "other way round"),
use the client form of fhem.pl (described above).
Multiple fhem commands are separated by semicolon (;). In order to use semicolon
in perl code or shell programs, they have to be escaped by the double semicolon
(;;). See the Notes section of the notify
chapter on command parameters and escape rules.
E.g. the following first command switches Lamp1 off at 07:00 and Lamp2
immediately (at the point of definition), the second one switches both lamps
off at 07:00.
define lampoff at 07:00 set Lamp1 off; set Lamp2 off
define lampoff at 07:00 set Lamp1 off;; set Lamp2 off
For every further indirection you need to double the semicolons:, e.g. to
switch on every day 2 devices at 7:00 for 10 minutes you have to write:
define onAt at 07:00 set Lamp1 on;;set Lamp2 on;; define offAt at +00:10 set Lamp1 off;;;;set Lamp2 off
Don't dispair, the previous example can also be written as
define onAt at 07:00 set Lamp1,Lamp2 on-for-timer 600
Commands can be either typed in plain, or read from a file (e.g. the
configuration file at startup). The commands are either executed directly, or
later if they are arguments to the at and notify fhem commands.
A line ending with \ will be concatenated with the next one, so long lines
(e.g. multiple perl commands) can be split in multiple lines. Some web fronteds
(e.g. webpgm2) make editing of multiline commands transparent for you (i.e. there is no need for \) .
Device specification (devspec)
The commands
attr,
deleteattr,
displayattr,
delete,
get,
list,
set,
setreading,
setstate,
trigger
can take a more complex device specification as argument, which will be
expanded to a list of devices. A device specification (short devspec) can be:
- a single device name. This is the most common case.
- a list of devices, separated by comma (,)
- a regular expression
- a NAME=VALUE pair, where NAME can be an Internal value like TYPE, a
Reading-Name or an attribute. VALUE is a regexp. To negate the
comparison, use NAME!=VALUE
- if the spec is followed by the expression :FILTER=NAME=VALUE, then the
values found in the first round are filtered by the second expression.
Examples:
set lamp1 on
set lamp1,lamp2,lamp3 on
set lamp.* on
set room=kitchen off
set room=kitchen:FILTER=STATE=on off
set room=kitchen:FILTER=STATE!=off off
list disabled=
list TYPE=FS20 STATE
Notes:
- the spec may not contain space characters.
- if there is a device which exactly corresponds to the spec, then
no special processing is done.
- first the spec is separated by comma, then the regular expression and
filter operations are executed.
- the returned list can contain the same device more than once, so
"set lamp3,lamp3 on" switches lamp3 twice.
- for more complex structuring demands see the
structure device.
Attributes
All devices have attributes. These can be set by means of the
attr command, displayed with the
displayattr command, and deleted by the
deleteattr command.
There are global attributes that are used by all devices and local attributes
that apply to individual device classes only.
Some devices (like FHEMWEB) automatically define new
global attributes on the first definition of a device of such type.
You can use the command
attr global userattr
<attributelist>
for the global device to
declare new global attributes and
attr <devicespec> userattr
<attributelist>
for individual devices according to devspec to declare new local attributes.
<attributelist> is a space-separated list which contains the
names of the additional attributes. See the documentation of the attr command for examples.
Be careful not to overwrite additional global attributes previously defined by
yourself or a device. Use the attr global userattr
<attributelist> as early in your configuration as possible.
Device specific attributes
Device specific attributes are documented in the corresponding device section.
Global attributes used by all devices
- verbose
Set the verbosity level. Possible values:
- 0 - server start/stop
- 1 - error messages or unknown packets
- 2 - major events/alarms.
- 3 - commands sent out will be logged.
- 4 - you'll see whats received by the different devices.
- 5 - debugging.
The value for the global device is a default for
other devices without own verbose attribute set.
- comment
Add an arbitrary comment.
- alias
Used by FHEMWEB to display a device with another name e.g. when using
special characters/spaces not accepted by device definition.
- room
Filter/group devices. Recognized by web-pgm2 and web-pgm3. A device
can appear in more than one room, in this case the rooms have to be
specified comma-separated.
Devices in the room hidden will not appear in the web output, or set
the FHEMWEB attribute to selectively disable
rooms for certain FHEMWEB instances.
- group
Group devices. Recognized by web-pgm2 (module FHEMWEB), it makes
devices in the same group appear in the same box).
This is used to further group
devices together. A device can appear in more than one group, in this
case the groups have to be specified comma-separated.
If this attribute is not set then the device type is used as the
grouping attribute.
- 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.
- eventMap
Replace event names and set arguments. The value of this attribute
consists of a list of space separated values, each value is a colon
separated pair. The first part specifies the "old" value, the second
the new/desired value. If the first character is slash(/) or comma(,)
then split not by space but by this character, enabling to embed spaces.
Examples:
attr store eventMap on:open off:closed
attr store eventMap /on-for-timer 10:open/off:closed/
set store open
readingFnAttributes
The following global attributes are honored by the modules that make use of the
standardized readings updating mechanism in fhem.pl. Check the module's
attribute list if you want to know if a device supports these attributes.
- stateFormat
Modifies the STATE of the device, shown by the list command or in the room
overview in FHEMWEB. If not set, its value is taken from the state reading.
If set, then every word in the argument is replaced by the value of the
reading if such a reading for the current device exists. If the value of
this attribute is enclused in {}, then it is evaluated. This attribute is
evaluated each time a reading is updated.
- event-on-update-reading
If not set, every update of any reading creates an event, which e.g. is
handled by notify or FileLog.
The attribute takes a comma-separated list of readings. You may use regular
expressions in that list. If set, only updates of the listed readings
create events.
- event-on-change-reading
The attribute takes a comma-separated list of readings. You may use regular
expressions in that list. If set, only changes of the listed readings
create events. In other words, if a reading listed here is updated with the
new value identical to the old value, no event is created. If an optional [:threshold]
is given after a reading name events are only generated if the change is >= threshold.
The precedence of event-on-update-reading and event-on-change-reading is as
follows:
- If both attributes are not set, any update of any reading of the device
creates an event.
- If any of the attributes is set, no events occur for updates or changes
of readings not listed in any of the attributes.
- If a reading is listed in event-on-update-reading, an update of the
reading creates an event no matter whether the reading is also listed
in event-on-change-reading.
- event-min-interval
This attribute takes a comma-separated list of reading:minInterval pairs.
You may use regular expressions for reading. Events will only be
generated, if at least minInterval seconds elapsed since the last reading
of the matched type.
- userReadings
A comma-separated list of definitions of user-defined readings. Each
definition has the form:
<reading>[:<trigger>] [<modifier>] { <perl code> }
After a single or bulk readings update, the user-defined readings are set
by evaluating the perl code { <perl code>
} for all definitions and setting the value of the respective
user-defined reading <reading> to the result. If
<trigger> is given, then all processing for this specific user
reading is only done if one of the just updated "reading: value"
combinations matches <trigger>, which is treated as a regexp.
Examples:
attr myEnergyMeter userReadings energy
{ ReadingsVal("myEnergyMeter","counters.A",0)/1250.0;; }
attr myMultiMeter userReadings
energy1:counters.A { ReadingsVal("myMultiMeter","counters.A",0)/1250.0;; },
energy2:counters.B { ReadingsVal("myMultiMeter","counters.B",0)/1250.0;; }
<modifier> can take one of these values:
- none: the same as it would not have been given at all.
- difference: the reading is set to the difference between the current
and the previously evaluated value.
- differential: the reading is set to the difference between the
current and the previously evaluated value divided by the time in
seconds between the current and the previous evaluation. Granularity
of time is one second. No value is calculated if the time past is
below one second. Useful to calculate rates.
- integral: reverse function of differential. The result is incremented
by the product of the time difference between the last two readings
and the avarage of the last two readings.
result += (time - timeold) * (oldval + value) / 2
- offset: if the current evaluated value is smaler than the previously
evaluated value the reading is incremented by the previous value.
the reading can then be used as an offset correct for a counter that
is reset for example due to a power loss.
- monotonic: if the difference between the current and the previously
evaluated value is positive the reading is incremented by this difference.
this allows to derive a monotonic growing counter from an original counter
even if the original will be rest by a power loss
Example:
attr myPowerMeter userReadings power
differential { ReadingsVal("myPowerMeter","counters.A",0)/1250.0;; }
Notes:
- user readings with modifiers difference and differential store the
calculated values internally. The user reading is set earliest at the
second evaluation. Beware of stale values when changing
definitions!
- the name of the defined Readings consists of alphanumeric characters
with underscore (_) and the minus (-) sign.
Common attributes
The following local attributes are used by a wider range of devices:
- 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.
?, 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>.
After setting the attribute, the global event "ATTR" will be generated.
Examples:
attr global verbose 3
attr lamp room kitchen
attr lamp group lights
attr lamp loglevel 6
attr weatherstation event-on-update-reading wind,temperature,humidity
attr weatherstation event-on-change-reading israining
attr weatherstation event-on-change-reading israining,state
attr heating stateFormat Temp:measured-temp, Valve:actuator
Notes:
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.
After definition, the global event "DEFINED" will be generated, see the
notify section for details.
Each device takes different additional arguments at definition, see the
corresponding device section for details.
delete
delete <devspec>
Delete something created with the define command.
See the Device specification section for details on
<devspec>.
After deletion, the global event "DELETED" will be generated, see the notify
section for details.
Examples:
deleteattr
deleteattr <devspec> [<attrname>]
Delete either a single attribute (see the attr command)
or all attributes for a device (if no <attrname> is defined).
See the Device specification section for details on
<devspec>.
After deleting the attribute, the global event "DELETEATTR" will be generated.
Examples:
deleteattr lamp follow-on-for-timer
deleteattr lamp
deletereading
deletereading <devspec> <readingname>
Delete the reading <readingname>
for a device. <readingname> is a perl regular expression that must match the whole name of the reading.
Use with greatest care! FHEM might crash if you delete vital readings of a device.
See the Device specification section for details on
<devspec>.
Examples:
deletereading mySensor temp1
deletereading mySensor temp\d+
displayattr
displayattr <devspec> [<attrname>]
Display either the value of a single attribute (see the attr command)
or all attributes for a device (if no <attrname> is defined).
See the Device specification section for details on
<devspec>.
If more then one device is specified, then the device name will also included
in the output.
Examples:
fhem> di WEB
menuEntries AlarmOn,/fhem?cmd=set%20alarm%20on
room Misc.
fhem> di WEB room
Misc.
get
get <devspec> <type-specific>
Ask a value directly from the device, and wait for an answer. In general, you
can get a list of possible parameters by
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|raw} [regexp]
If set to on, and a device state changes, send a notification to the current
client. This command can be used by other programs/modules to receive a
notification.
The option timer prepends a timerstamp to the line. Note: this command is
a nice way to check which events are generated, to help you when creating
notify or FileLog entries.
list
list [devspec] [value]
Output a list of all definitions, all notify settings and all at
entries. This is one of the few commands which return a string in a
normal case.
See the Device specification section for details on
<devspec>.
If value is specified, then output this property (like DEF, TYPE, etc) or
reading (actuator, measured-temp) for all devices from the devspec.
Example:
fhem> list
Type list for detailed info.
Internal:
global (Internal)
FHZ:
FHZ (fhtbuf: 23)
FS20:
Btn4 (on-old-for-timer)
Roll1 (on)
Stehlampe (off)
FHT:
fl (measured-temp: 21.1 (Celsius))
KS300:
out1 (T: 2.9 H: 74 W: 2.2 R: 8.2 IR: no)
at:
at_rollup (Next: 07:00:00)
notify:
ntfy_btn4 (active)
FileLog:
avglog (active)
If specifying
name, then a detailed status for
name
will be displayed, e.g.:
fhem> list fl
Internals:
CODE 5102
DEF 5102
NAME fl
NR 15
STATE measured-temp: 21.1 (Celsius)
TYPE FHT
IODev FHZ
Attributes:
room Heizung
Readings:
2006-11-02 09:45:56 actuator 19%
[...]
modify
modify <name> <type-dependent-options>
Used to modify some definitions. Useful for changing some at or notify definitions. If specifying
one argument to an at type definition, only the time part will be changed. In
case of a notify type definition, only the regex part will be changed. All
other values (state, attributes, etc) will remain intact.
After modify, the global event "MODIFIED" will be generated.
Example:
define lampon at 19:00 set lamp on
modify lampon *19:00
modify lampon 19:00 set lamp on-for-timer 16
quit
quit
If used in a TCP/IP session, terminate the client session.
If used in a script, terminate the parsing of the current script.
Example:
reload
reload <module>
Reload the given module from the module directory. It is a convenient way to
test modules whithout restarting the program.
Example:
rename
rename <oldname> <newname>
Rename a device from the <oldname> to <newname>, together with
its attributes. The global event RENAMED will be generated, see the notify
section for details.
Example:
rename FHT_1234 fht.kitchen
rereadcfg
rereadcfg [fhem-config-file]
Re-read the active configuration file, or the optionally specified file.
The sequence: the statefile will be saved first,
then all devices will be deleted, then the currently active config file (or
the specified file) will be read and at last the statefile will be
reloaded.
Upon completion it triggers the global:REREADCFG event. All existing
connections up to the one issuing the rereadcfg will be closed.
Example:
save
save [<configfile>]
Save first the statefile, then the
configfile information. If a parameter is specified,
it will be used instead the global configfile attribute.
Notes:
- save only writes out definitions and attributes, but no (set/get)
commands which were previously part of the config file. If you need such
commands after the initialization (e.g. FHTcode), you
should trigger them via notify, when receiving the
INITIALIZED event.
- save tries to preserve comments (lines starting with #) and include
structures, but it won't work correctly if some of these files are not
writeable.
set
set <devspec> <type-specific>
Set parameters of a device / send signals to a device. You can
get a list of possible parameters by
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.
Some modules support a common list of set extensions, and point in
their documentation to this section. If the module itself implements one of
the following commands, then the module-implementation takes precedence.
- on-for-timer <seconds>
Issue the on command for the device, and after <seconds> the off
command. For issuing the off command an internal timer will be
scheduled, which is deleted upon a restart. To delete this internal
timer without restart specify 0 as argument.
- off-for-timer <seconds>
see on-for-timer above.
- on-till <timedet>
Issue the on command for the device, and create an at definition with
<timedet> (in the form HH:MM[:SS]) to set it off. This definition
is visible, and its name is deviceName+"_till". To cancel the scheduled
off, delete the at definition.
- off-till <timedet>
see on-till above.
- blink <number> <blink-period>
set the device on for <blink-period> then off for
<blink-period> and repeat this <number> times.
To stop blinking specify "0 0" as argument.
- intervals <from1>-<till1> <from2>-<till2>...
set the device on for the specified intervals, which are all timespecs
in the form HH:MM[:SS]. The intervals are space separated.
Examples:
set switch on-for-timer 12.5
set switch on-till {sunset()}
set switch blink 3 1
set switch intervals 08:00-12:00 13:00-18:00
setreading
setreading <devspec> <reading> <value>
Set the reading <reading> for the device <name> to
<value> without sending out commands to the device, but triggering
events and eventMap/stateFormat transformations as usual.
Examples:
Note: setreading won't generate an event for device X, if it is called from a
notify for device X. Use "sleep 0.1; setreading X Y Z" in this case.
setstate
setstate <devspec> <value>
Set the STATE entry for the device specified by <devspec>,
which is used for displaying the device state in different frontends.
No signals will be sent to the device, no events will be generated, and no
eventMap or stateFormat translation will be done either.
This command is also used in the statefile.
See the Device specification section for details on
<devspec>.
Examples:
shutdown
shutdown [restart]
Shut down the server (after saving the state information
). It triggers the global:SHUTDOWN event. If the optional restart
parameter is specified, fhem tries to restart itself.
Example:
shutdown
shutdown restart
trigger
sleep
sleep <sec> [quiet]
Sleep for a given amount, millisecond accuracy.
When called in a notify/at/etc, then nonempty return values of the following
commands is logged to the global logfile with loglevel 2.
If quiet is specified, then skip this logging.
Example:
sleep 0.5
define n3 notify btn3.* set lamp toggle;;sleep 0.5;;set lamp
toggle
define a3 at +*00:05 set Windsensor 1w_measure;; sleep 2 quiet;; get
Windsensor 1w_temp
Note: sleep followed by another command and issued in at/notify/etc is not
blocking fhem
version
version [filter]
List the version of fhem.pl and all loaded modules. The optional parameter
can be used to filter the ouput.
Example output:
# $Id: fhem.pl 3405 2013-07-11 19:46:39Z rudolfkoenig $
# $Id: 00_CUL.pm 3237 2013-06-01 17:15:59Z rudolfkoenig $
# $Id: 10_CUL_HM.pm 3378 2013-07-02 16:57:27Z martinp876 $
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
Set
Get
Attributes
- archivedir
- archivecmd
- nrarchive
- autoload_undefined_devices
If set, automatically load the corresponding module when a message
of this type is received. This is used by the
autocreate device, to automatically create a fhem device upon
receiving a corresponding message.
- backupcmd
You could pass the backup to your own command / script by using this attribute.
If this attribute is specified, then it will be started as a shell command and
passes a space separated list of files / directories as one
argument to the command, like e.g.:
"/etc/fhem.cfg /var/log/fhem/fhem.save /usr/share/fhem/contrib
/usr/share/fhem/FHEM /usr/share/fhem/foo /usr/share/fhem/foobar
/usr/share/fhem/www"
Note: Your command / script has to return the string "backup done" or
everything else to report errors, to work properly with updatefhem!
This Attribute is used by the backup command.
Example:
attr global backupcmd /usr/local/bin/myBackupScript.sh
- backupdir
A folder to store the compressed backup file.
This Attribute is used by the backup command.
Example:
attr global backupdir /Volumes/BigHD
- backupsymlink
If this attribute is set to everything else as "no", the archive command tar
will support symlinks in your backup. Otherwise, if this attribute is set to
"no" symlinks are ignored by tar.
This Attribute is used by the backup command.
Example:
attr global backupsymlink yes
- configfile
Contains the name of the fhem configuration file. If save is called without argument, then the output will
be written to this file.
- holiday2we
If this attribute is set, then the $we variable
will be true, if the value of the holiday
variable referenced by this attribute is not none.
Example:
attr global holiday2we hessen
- lastinclude
If this attribute is set, then the last command of the generated
configfile (see the save command) will be
include <lastinclude-value>
This attribute is DEPRECATED, use notify, with
the INITIALIZED event to execute commands after initialization.
- logfile
Specify the logfile to write. You can use "-" for
stdout, in this case the server won't background itself.
The logfile name can also take wildcards for easier logfile rotation,
see the FileLog section. Just apply the
archivecmd / archivedir / nrarchive attributes to the
global device as you would do for a FileLog device.
You can access the current name of the logfile with
{ $currlogfile }.
- modpath
Specify the path to the modules directory FHEM. The path
does not contain the directory FHEM. Upon setting the
attribute, the directory will be scanned for filenames of the form
NN_<NAME>.pm, and make them available for device definition under
<NAME>. If the first device of type <NAME> is defined, the
module will be loaded, and its function with the name
<NAME>_Initialize will be called. Exception to this rule are
modules with NN=99, these are considered to be utility modules
containing only perl helper functions, they are loaded at startup (i.e.
modpath attribute definition time).
- motd
Message Of The Day. Displayed on the homescreen of the FHEMWEB package,
or directly after the telnet logon, before displaying the fhem> prompt.
SecurityCheck is setting motd if it is not defined upon startup, to
avoid this set the motd value to none. motd is also used to show
collected error messages upon fhem start.
- mseclog
If set, the timestamp in the logfile will contain a millisecond part.
- nofork
If set and the logfile is not "-", do not try to background. Needed on
some Fritzbox installations, and it will be set automatically for
Windows.
- pidfilename
Write the process id of the perl process to the specified file. The
server runs as a daemon, and some distributions would like to check by
the pid if we are still running. The file will be deleted upon
shutdown.
- sendStatistics
- statefile
Set the filename where the state and certain at
information will be saved before shutdown. If it is not specified, then
no information will be saved.
- title
Used by the web frontend fhemweb.pl (webpgm2) as a Page title.
- uniqueID
- userattr
A space separated list which contains the names of additional
attributes for all devices. Without specifying them you will not be
able to set them (in order to prevent typos).
userattr can also specified for other devices, in this case
these additinal attribute names are only valid for this device.
- dupTimeout
Define the timeout for which 2 identical events from two different
receiver are considered a duplicate. Default is 0.5 seconds.
- showInternalValues
Show data used for internal computations. If the name of an internal
value, reading or attribute starts with dot (.), then it is normally
hidden, and will only be visible, if this attribute is set to 1.
The attribute is checked by the list command, by the FHEMWEB room
overview and by xmllist.
- stacktrace
if set (to 1), dump a stacktrace to the log for each "PERL WARNING".
Perl specials
If you want to automate some tasks via fhem, then you'll probably use
at or
notify. For more complex tasks
you'll use either a shell-script or a perl "oneliner" as the at/notify
argument. This chapter gives some tips in using the perl oneliners.
To test perl oneliners, type them on the telnet prompt (or FHEMWEB text
input) by enclosing it in {}, one line at once. The last line will only
write something in the logfile, the output of the other lines is directly
visible.
{ "Hello" }
{ 1+3*4 }
{ `ls /etc` }
{ Log 1, "Hello" }
Perl expressions are separated by ;, in fhem oneliners they have to
escaped with ;;
{ my $a = 1+1;; Log 1, "Hello $a" }
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:
{ fhem "set light on" }
define n1 notify piri:on { fhem "set light on" }
Note: if this function returns a value, it will also be logged into the
global fhem log. Use 1 as a second argument to disable this logging, this
makes sense when obtainig some values via fhem "get...".
Notify can be used to store macros for manual execution. Use the trigger command to execute the macro:
define MyMacro notify MyMacro { Log 1, "Hello"}
trigger MyMacro
define MacroWithArg notify MyMacro { Log 1, "Hello %"}
trigger MyMacro MyArg
To make date and time handling easier, the variables $sec, $min, $hour,
$mday, $month, $year, $wday, $yday, $isdst are available in the perl
oneliners (see also perldoc -f localtime). Exceptions: $month is in the
range of 1 to 12, and $year is corrected by 1900 (as I would expect).
Additionally the variable $hms contains the time in the HH:MM:SS format.
Additionally the variabe $we is 1 if it is weekend (i.e $wday == 0 or
$wday == 6), and 0 otherwise. If the holida2we
global attribute is set, $we is 1 for holidays too.
define n2 notify piri:on { if($hour > 18 || $hour < 5) {
fhem "set light on" } }
define roll_en *07:45:00 { fhem "trigger SwitchAllRoll on" if(!$we) }
define roll_en *08:30:00 { fhem "trigger SwitchAllRoll on" if($we) }
The following helper functions are defined in 99_Util.pm (which will
be loaded automatically, as every module with prefix 99):
- 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 access the device states/attributes, use the following functions:
- Value(<devicename>)
returns the state of the device (the string you see in paranthesis in
the output of the list command).
- OldValue(<devicename>)
- OldTimestamp(<devicename>)
returns the old value/timestamp of the device.
-
ReadingsVal(<devicename>,<reading>,<defaultvalue>)
Return the reading (the value in the Readings section of "list device")
-
ReadingsNum(<devicename>,<reading>,<defaultvalue>)
Return the reading as a number, i.e. delete non-numerical values.
-
AttrVal(<devicename>,<attribute>,<defaultvalue>)
Return the attribute of the device
{ Value("wz") }
{ OldValue("wz") }
{ time_str2num(OldTimestamp("wz")) }
{ ReadingsVal("wz", "measured-temp", "20")+0 }
{ ReadingsTimestamp("wz", "measured-temp", 0)}
{ AttrVal("wz", "room", "none") }
-
InternalVal(<devicename>,<property>,<defaultvalue>)
Return the internal value (the value in the Internals section of "list
device").
By using the 99_SUNRISE_EL.pm module, you have access to the following
functions:
sunset($offset, $min, $max)
sunrise($offset, $min, $max)
isday()
offset is in seconds, and the format of min/max is "HH:MM" or "HH:MM:SS".
isday returns 1 if the sun is visible, and 0 else.
gnuplot file syntax
The .gplot files are also used by the
FHEMWEB/SVG module
when the
plotmode attribute is set to SVG. In this case
only a subset of the .gnuplot attributes are used, and some lines have special
meanings: the difference will be explained in this chapter. See also
this fhemwiki entry on
creating logs.
Following is a minimal .gplot definition (valid only for plotmode SVG):
set terminal size <SIZE>
#FileLog 4:::
plot title 'Temperature' with lines
The .gnuplot file consists of 3 parts:
- set commands
Following sets are recognized:
- terminal, only the size parameter.
This is usually set to <SIZE>, which is replaced by the plotsize attribute of the FHEMWEB or weblink
instance.
- title
Usually set to <TL> which is replace by the weblink title attribute, or to <Lx>, which is replaced
by the weblink label attribute.
- ylabel,y2label
Left and right labels, printed vertically. Are also subject to label
replacement.
- yrange,y2range
Specify the range of the left and right axis. Examples:
set yrange [-0.1:1.1]
set y2range [0:]
- ytics,y2tics
the label for the left/right axis tics. Examples:
set ytics ("on" 0, "off" 1)
set y2tics
- #FileLog entries
Each line from the plot section must have one corresponding #FileLog
line. For the syntax see the column_spec paragraph of the Filelog get description.
Note that for SVG plots the first column of the input file always has to
be in the standard fhem timestamp format (YYYY-MM-DD_HH:MM:SS)
- plot entries
There is always one plot command with comma separated argument-blocks.
Each argument-block represents one line, and has its own parameters.
Following parameters are recognized:
- axes x1y1 / x1y2
tells the program to assign the current line to one of the two axes
(left or right).
- title
Caption of the line. Whan clicking on this title, a small javascript
program will change the title to the min/max and last values of the plot,
will enable copying this line or pasting an already copied one (the
existing scale of the plot wont'be changed, only the pasted line will
be scaled), and other lines of the plot will temporarily be hidden.
- with <linetype>
Specify the line type. Following types are recognized: points,
steps, fsteps, histeps and lines. Everything unknown will be mapped to
the type lines.
SVG special: cubic and quadratic, are mapped to the SVG path types C,
and Q respectively.
- ls <linestyle>
The linestyle defaults to l0 for the first line, l1 for the second, and
so on. It is defined in the svg_style.css file. There are two sets
defined here: l0-l8 and l0fill-l6fill. The second set must be specified
explicitly. If the name of the linestyle contains the word fill, then
plots of the lineytype "lines" will have an additional starting and
ending segment, so that filling is done correctly.
See the SVG spec for details of this CSS file.
Note: if you plan to use this attribute, you have to specify it for all
the lines (attribute-blocks) in the plot command.
- lw <linewidth>
Sets the stroke-width style of the line. This attribute is deprecated,
the corresponding feature of the CSS file / (attribute ls) should be
used instead.