<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>fhem reference</title>
<link rel="stylesheet" type="text/css" href="../css/style.css" />
<meta http-equiv="Content-type" content="text/html;charset=ISO-8859-1"/>
<link rel="shortcut icon" href="favicon.ico"/>
</head>
<body>
<div id="logo"></div>
<div id="menu">
<h3>fhem.pl reference</h3>
Version: <b>EN</b> <a href="commandref_DE.html">DE</a>
</div>
<div id="right">
<h3>Contents</h3>
<ul>
<a href="#intro">Introduction</a><br>
<a href="#command">Fhem command types</a><br>
<a href="#devspec">Device specification</a><br>
<br>
<b>Fhem commands</b>
<ul>
<a href="#attr">attr</a>
<a href="#backup">backup</a>
<a href="#CULflash">CULflash</a>
<a href="#createlog">createlog</a>
<a href="#define">define</a>
<a href="#delete">delete</a>
<a href="#deleteattr">deleteattr</a>
<a href="#deletereading">deletereading</a>
<a href="#fheminfo">fheminfo</a>
<a href="#get">get</a>
<a href="#getstate">getstate</a>
<a href="#help">?,help</a>
<a href="#include">include</a>
<a href="#inform">inform</a>
<a href="#JsonList">JsonList</a>
<a href="#list">list</a>
<a href="#modify">modify</a>
<a href="#notice">notice</a>
<a href="#quit">quit</a>
<a href="#reload">reload</a>
<a href="#rename">rename</a>
<a href="#rereadcfg">rereadcfg</a>
<a href="#save">save</a>
<a href="#set">set</a>
<a href="#setdefaultattr">setdefaultattr</a>
<a href="#setstate">setstate</a>
<a href="#shutdown">shutdown</a>
<a href="#sleep">sleep</a>
<a href="#trigger">trigger</a>
<a href="#update">update</a>
<a href="#usb">usb</a>
<a href="#XmlList">xmllist</a>
</ul>
<br>
<b>Devices</b>
<ul>
<a href="#global">global</a><br>
</ul>
<br>
<b>Helper modules</b>
<ul>
<a href="#Calendar">Calendar</a>
<a href="#DbLog">DbLog</a>
<a href="#FHEM2FHEM">FHEM2FHEM</a>
<a href="#FHEMWEB">FHEMWEB</a>
<a href="#FB_CALLMONITOR">FB_CALLMONITOR</a>
<a href="#FileLog">FileLog</a>
<a href="#FLOORPLAN">FLOORPLAN</a>
<a href="#PachLog">PachLog</a>
<a href="#PRESENCE">PRESENCE</a>
<a href="#PID">PID</a>
<a href="#SUNRISE_EL">SUNRISE_EL</a>
<a href="#at">at</a>
<a href="#autocreate">autocreate</a>
<a href="#average">average</a>
<a href="#dewpoint">dewpoint</a>
<a href="#dummy">dummy</a>
<a href="#holiday">holiday</a>
<a href="#HCS">HCS</a>
<a href="#Heating_Control">Heating_Control</a>
<a href="#notify">notify</a>
<a href="#sequence">sequence</a>
<a href="#structure">structure</a>
<a href="#telnet">telnet</a>
<a href="#Twilight">Twilight</a>
<a href="#watchdog">watchdog</a>
<a href="#weblink">weblink</a>
<a href="#WOL">WOL</a>
</ul>
<br>
<a href="#perl">Perl specials</a><br>
<a href="#gnuplot-syntax">gnuplot file syntax</a><br>
</ul>
<a name="intro"></a>
<h3>Introduction</h3>
<ul>
Fhem is mainly used for home automation, but it is suitable for other tasks
too, where notification, timers and logging plays an important role.<br>
<br>
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.<br>
<br>
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 (<a href="#notify">notify</a>) and timers (<a
href="#at">at</a>) are implemented this way, giving the possibility to
replace/extend this functionality.<br> <br>
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.<br> <br>
When starting the server you have to specify a configuration file:<br>
<ul>
<code>perl fhem.pl fhem.cfg</code>
</ul>
<br>
A minimal configuration file looks like: <pre>
attr global <a href="#logfile">logfile</a> log/fhem.log
attr global <a href="#modpath">modpath</a> .
attr global <a href="#statefile">statefile</a> log/fhem.save
attr global <a href="#verbose">verbose</a> 3
define telnetPort <a href="#telnet">telnet</a> 7072 global
define WEB <a href="#FHEMWEB">FHEMWEB</a> 8083 global</pre>
Note: the last two lines are optional and assume you wish to use the
builtin telnet and WEB interface.<br>
<br>
The web interface can be reached at
<ul>
http://<fhemhost>:8083
</ul>
<br>
TCP/IP communication with fhem can either happen in a "session" (via
telnet) or single client command (via fhem.pl). Example:
<ul>
<code>telnet <fhemhost> 7072<br>
<NL> </code>(This newline switches into "prompt" mode)<code><br>
<command>...<br>
quit</code><br>
</ul>
or
<ul>
<code>fhem.pl <fhemhost>:7072 "<command>..."</code>
</ul>
</ul>
<a name="command"></a>
<h3>Fhem command types</h3>
<ul>
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 <a href="#at">at</a> or <a href="#notify">notify</a>
arguments, but can also issued as a "normal" command.<br>
<br>
E.g. the following three commands all do the same when issued from a telnet
prompt:<br>
<ul>
set lamp off<br>
"fhem.pl 7072 "set lamp off""<br>
{fhem("set lamp off")}<br>
</ul>
<br>
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 <a href="#perl">Perl special</a> 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).<br>
<br>
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 <b>Notes</b> section of the <a href="#notify">notify</a>
chapter on command parameters and escape rules.<br>
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.<br>
<ul>
define lampoff at 07:00 set Lamp1 off; set Lamp2 off<br>
define lampoff at 07:00 set Lamp1 off;; set Lamp2 off<br>
</ul>
<br>
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 <a href="#at">at</a> and <a
href="#notify">notify</a> fhem commands.<br>
<br>
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 \) .<br>
<br>
</ul>
<a name="devspec"></a>
<h3>Device specification (devspec)</h3>
<ul>
The commands
<a href="#attr">attr</a>,
<a href="#deleteattr">deleteattr</a>,
<a href="#delete">delete</a>,
<a href="#get">get</a>,
<a href="#list">list</a>,
<a href="#set">set</a>,
<a href="#setstate">setstate</a>,
<a href="#trigger">trigger</a>
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:
<ul>
<li>a single device name. This is the most common case.</li>
<li>a list of devices, separated by comma (,)</li>
<li>a range of devices, separated by dash (-)</li>
<li>a regular expression, if the the spec contains on e of the following
characters: ^*[]$</li>
<li>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.</li>
</ul>
Example:
<ul>
<code>set lamp1 on</code><br>
<code>set lamp1,lamp2,lamp3 on</code><br>
<code>set lamp[1-3] on</code><br>
<code>set lamp.* on</code><br>
<code>set lamp1-lamp3 on</code><br>
<code>set lamp1-lamp3,lamp3 on</code><br>
<code>set room=kitchen off</code><br>
<code>list disabled=</code><br>
<code>list TYPE=FS20</code><br>
</ul>
Notes:
<ul>
<li>first the spec is separated by komma, then the range or the regular
expression operations are executed.</li>
<li>if there is a device which exactly corresponds to the spec, then
no special processing is done.</li>
<li>the returned list can contain the same device more than once, so
"set lamp1-lamp3,lamp3 on" switches lamp3 twice.</li>
<li>for more complex structuring demands see the <a href="#structure">
structure</a> device.
</ul>
</ul>
<a name="help"></a>
<h3>?, help</h3>
<ul>
<code>?</code><br>
<code>help</code><br>
<br>
Get a list of all commands and short description for each one
</ul>
<a name="attr"></a>
<h3>attr</h3>
<ul>
<code>attr <devspec> <attrname> [<value>] </code><br>
<br>Set an attribute for a device defined by <a href="#define">define</a>.
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 <a href="#devspec">Device specification</a> section for details on
<devspec>.
<br><br>
Attributes used by all devices:
<ul>
<a name="comment"></a>
<li>comment<br>
Add an arbitrary comment.
<a name="alias"></a>
<li>alias<br>
Used by FHEMWEB to display a device with another name e.g. when using
special characters/spaces not accepted by device definition.
<a name="room"></a>
<li>room<br>
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.<br>
Devices in the room hidden will not appear in the web output, or set
the <a href="#hiddenroom"> FHEMWEB attribute to selectively disable
rooms for certain FHEMWEB instances.
</li>
<a name="group"></a>
<li>group<br>
Group devices. Recognized by web-pgm2 (module <a href="#FHEMWEB">FHEMWEB</a>), 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.<br>
If this attribute is not set then the device type is used as the
grouping attribute.
</li>
<a name="showtime"></a>
<li>showtime<br>
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.
</li>
<br>
<a name="readingFnAttributes"></a>
<b>readingFnAttributes</b><br>
The following attributes are honored by the modules that make use
of the standardized readings updating mechanism in fhem.pl. Check the
modules attribute list if you want to know if it is supporting it.
<a name="stateFormat"></a>
<li>stateFormat<br>
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.
</li>
<a name="event-on-update-reading"></a>
<li>event-on-update-reading<br>
If not set, every update of any reading creates an event, which e.g. is
handled by <a href="#notify">notify</a> or <a href="#FileLog">FileLog</a>.
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.
</li>
<a name="event-on-change-reading"></a>
<li>event-on-change-reading<br>
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.
</li><br>
The precedence of event-on-update-reading and event-on-change-reading is as
follows:
<ol>
<li>If both attributes are not set, any update of any reading of the device
creates an event.</li>
<li>If any of the attributes is set, no events occur for updates or changes
of readings not listed in any of the attributes.</li>
<li>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.</li>
</ol><br>
<a name="userReadings"></a>
<li>userReadings<br>
A comma-separated list of definitions of user-defined readings. Each definition has the form
<code><reading> [<modifier>] { <perl code> }</code>. After a single or bulk
readings update, the user-defined readings are set by evaluating the <a href="#perl">
perl code</a>
<code>{ <perl code> }</code> for all definitions and setting the value of
the respective user-defined reading <code><reading></code> to the result.<br><br>
Examples:<br>
<code>attr myEnergyMeter userReadings energy { ReadingsVal("myEnergyMeter","counters.A",0)/1250.0;; }</code><br>
<code>attr myMultiMeter userReadings energy1 { ReadingsVal("myMultiMeter","counters.A",0)/1250.0;; },
energy2 { ReadingsVal("myMultiMeter","counters.B",0)/1250.0;; }</code>
<br><br>
<code><modifier></code> can take one of these values:
<ul>
<li>none: the same as it would not have been given at all.</li>
<li>difference: the reading is set to the difference between the current and the previously evaluated value.</li>
<li>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.</li>
</ul><br>
Example:<br>
<code>attr myPowerMeter userReadings power differential { ReadingsVal("myPowerMeter","counters.A",0)/1250.0;; }</code><br><br>
Note: 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!
</li><br>
</ul>
<br>
Device specific attributes are documented in the corresponding device section.
<br><br>
Examples:
<ul>
<code>attr global verbose 3</code><br>
<code>attr lamp room kitchen</code><br>
<code>attr lamp group lights</code><br>
<code>attr lamp loglevel 6</code><br>
<code>attr weatherstation event-on-update-reading wind,temperature,humidity</code><br>
<code>attr weatherstation event-on-change-reading israining</code><br>
<code>attr weatherstation event-on-change-reading israining,state</code><br>
<code>attr heating stateFormat Temp:measured-temp, Valve:actuator</code><br>
</ul>
<br>
Notes:<br>
<ul>
<li>See <a href="#deleteattr">deleteattr</a> to delete attributes.</li>
</ul>
</ul>
<a name="setdefaultattr"></a>
<h3>setdefaultattr</h3>
<ul>
<code>setdefaultattr [<attrname> [<value>]] </code><br>
<br>Add a default attribute. Each device defined from now on will receive
this attribute.<br> If no attrname is specified, then the default attribute
list will be deleted.
<br><br>
Example to set the attribute "room kitchen" and "loglevel 4" to
each of the lamps:
<ul>
<code>setdefaultattr room kitchen</code><br>
<code>setdefaultattr loglevel 4</code><br>
<code>define lamp1 FS20 1234 11</code><br>
<code>define lamp2 FS20 1234 12</code><br>
<code>define lamp3 FS20 1234 13</code><br>
<code>setdefaultattr</code><br>
</ul>
<br>
Notes:<br>
<ul>
<li>There is no way to delete a single default-attribute from the list</li>
</ul>
</ul>
<a name="define"></a>
<h3>define</h3>
<ul>
<code>define <name> <type> <type-specific></code><br>
<br>
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)". <br>
Use "define <name> ?" to get a list of possible types.<br>
After definition, the global event "DEFINED" will be generated, see the
notify section for details.<br>
<br><br>
Each device takes different additional arguments at definition, see the
corresponding device section for details.<br>
<br>
</ul>
<a name="delete"></a>
<h3>delete</h3>
<ul>
<code>delete <devspec></code> <br>
<br>
Delete something created with the <a href="#define">define</a> command.
See the <a href="#devspec">Device specification</a> section for details on
<devspec>.<br>
After deletion, the global event "DELETED" will be generated, see the notify
section for details.<br>
Examples:
<ul>
<code>delete lamp</code><br>
</ul>
<br>
</ul>
<a name="deleteattr"></a>
<h3>deleteattr</h3>
<ul>
<code>deleteattr <devspec> [<attrname>]</code> <br>
<br>
Delete either a single attribute (see the <a href="#attr">attr</a> command)
or all attributes for a device (if no <attrname> is defined).
See the <a href="#devspec">Device specification</a> section for details on
<devspec>.<br>
<br>
Examples:
<ul>
<code>deleteattr lamp follow-on-for-timer</code><br>
<code>deleteattr lamp</code><br>
</ul>
<br>
</ul>
<a name="deletereading"></a>
<h3>deletereading</h3>
<ul>
<code>deletereading <devspec> <readingname></code> <br>
<br>
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 <a href="#devspec">Device specification</a> section for details on
<devspec>.<br>
<br>
Examples:
<ul>
<code>deletereading mySensor temp1</code><br>
<code>deletereading mySensor temp\d+</code><br>
</ul>
<br>
</ul>
<a name="get"></a>
<h3>get</h3>
<ul>
<code>get <devspec> <type-specific></code>
<br><br>
Ask a value directly from the device, and wait for an answer. In general, you
can get a list of possible parameters by
<ul>
<code>get <device> ?</code>
</ul>
See the <a href="#devspec">Device specification</a> section for details on
<devspec>.<br>
<br>
Each device has different get parameters, see the corresponding device
section for details.<br>
<br>
</ul>
<a name="getstate"></a>
<h3>getstate</h3>
<ul>
<code>getstate <devspec></code>
<br><br>
Output a short space seperated status for <devspec>. It is useful for
monitoring the device in e.g. Cacti.<br>
Examples:
<ul><code>
getstate lamp<br>
state:1<br>
<br>
getstate fl<br>
ack:0 actuator:2 day-temp:21.5 desired-temp:22.5 [...] measured-temp:22.9 [...]
</code></ul>
Note: to use this command copy the file contrib/getstate/99_getstate.pm into
your FHEM directory.
<br>
</ul>
<a name="include"></a>
<h3>include</h3>
<ul>
<code>include <filename></code> <br>
<br>
Read in the file, and process every line as a fhem command. Makes
configuration files more modular and enables to reread them.
<br>
</ul>
<a name="inform"></a>
<h3>inform</h3>
<ul>
<code>inform {on|off|timer|raw} [regexp]</code> <br>
<br>
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.<br>
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
<a href="#notify">notify</a> or <a href="#FileLog">FileLog</a> entries.
<br>
</ul>
<a name="list"></a>
<h3>list</h3>
<ul>
<code>list [devspec] [value]</code>
<br><br>
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 <a href="#devspec">Device specification</a> section for details on
<devspec>.
<br>
If value is specified, then output this property (like DEF, TYPE, etc) or
reading (actuator, measured-temp) for all devices from the devspec.
<br><br>
Example:
<pre><code> fhem> list
Type list <name> 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)
</code></pre>
If specifying <code>name</code>, then a detailed status for <code>name</code>
will be displayed, e.g.:
<pre><code> 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%
[...]
</code></pre>
</ul>
<a name="modify"></a>
<h3>modify</h3>
<ul>
<code>modify <name> <type-dependent-options></code>
<br><br>
Used to modify some definitions. Useful for changing some <a
href="#at">at</a> or <a href="#notify">notify</a> 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.
<br><br>
Example:
<ul>
<code>define lampon at 19:00 set lamp on</code><br>
<code>modify lampon *19:00</code><br>
<code>modify lampon 19:00 set lamp on-for-timer 16</code><br>
</ul>
</ul>
<a name="quit"></a>
<h3>quit</h3>
<ul>
<code>quit</code>
<br><br>
If used in a TCP/IP session, terminate the client session.<br>
If used in a script, terminate the parsing of the current script.
<br><br>
Example:
<ul>
<code>quit</code>
</ul>
</ul>
<a name="reload"></a>
<h3>reload</h3>
<ul>
<code>reload <module></code>
<br><br>
Reload the given module from the module directory. It is a convenient way to
test modules whithout restarting the program.
<br><br>
Example:
<ul>
<code>reload 99_PRIV</code>
</ul>
</ul>
<a name="rename"></a>
<h3>rename</h3>
<ul>
<code>rename <oldname> <newname></code>
<br><br>
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.
<br><br>
Example:
<ul>
<code>rename FHT_1234 fht.kitchen</code>
</ul>
</ul>
<a name="rereadcfg"></a>
<h3>rereadcfg</h3>
<ul>
<code>rereadcfg [fhem-config-file]</code>
<br><br>
Re-read the active configuration file, or the optionally specified file.<br>
The sequence: the <a href="#statefile">statefile</a> 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.<br>
Upon completion it triggers the global:REREADCFG event. All existing
connections up to the one issuing the rereadcfg will be closed.
<br><br>
Example:
<ul>
<code>rereadcfg</code>
</ul>
</ul>
<a name="save"></a>
<h3>save</h3>
<ul>
<code>save [<configfile>]</code>
<br><br>
Save first the <a href="#statefile">statefile</a>, then the
<a href="#configfile">configfile</a> information. If a parameter is specified,
it will be used instead the global configfile attribute.<br><br>
Notes:
<ul>
<li>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. <a href="FHZset">FHTcode</a>), you
should trigger them via <a href="#notify">notify</a>, when receiving the
INITIALIZED event.</li>
<li>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.</li>
</ul>
</ul>
<a name="set"></a>
<h3>set</h3>
<ul>
<code>set <devspec> <type-specific></code>
<br><br>
Set parameters of a device / send signals to a device. You can
get a list of possible parameters by
<ul>
<code>set <name> ?</code>
</ul>
See the <a href="#devspec">Device specification</a> section for details on
<devspec>. The set command returns only a value on error.<br>
<br>
Each device has different set parameters, see the corresponding device
section for details.<br>
<br>
<br>
<a name="setExtensions"></a>
Some modules support a common list of <b>set extensions</b>, and point in
their documentation to this section. If the module itself implements one of
the following commands, then the module-implementation takes precedence.
<ul>
<li>on-for-timer <seconds><br>
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.</li>
<li>off-for-timer <seconds><br>
see on-for-timer above.</li>
<li>on-till <timedet><br>
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.</li>
<li>off-till <timedet><br>
see on-till above.</li>
<li>blink <number> <blink-period><br>
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.</li>
<li>intervals <from1>-<till1> <from2>-<till2>...
</br>
set the device on for the specified intervals, which are all timespecs
in the form HH:MM[:SS]. The intervals are space separated.</li>
</ul>
Examples:
<ul>
<code>
set switch on-for-timer 12.5<br>
set switch on-till {sunset()}<br>
set switch blink 3 1<br>
set switch intervals 08:00-12:00 13:00-18:00<br>
</code>
</ul>
</ul>
<a name="setstate"></a>
<h3>setstate</h3>
<ul>
<code>setstate <devspec> <value></code>
<br><br>
Set the "STATE" for <code><name></code> as shown in paranthesis in the
<a href="#list">list</a> command
to <code><value></code> without sending any signals to the device
itself. This command is also used in the <a href="#statefile">statefile</a>.
See the <a href="#devspec">Device specification</a> section for details on
<devspec>.
<br><br>
Examples:
<ul>
setstate lamp on
</ul>
Note:
<ul>
<li>The statefile uses another version of this command, don't be surprised.
</li>
</ul>
</ul>
<a name="shutdown"></a>
<h3>shutdown</h3>
<ul>
<code>shutdown [restart]</code>
<br><br>
Shut down the server (after saving the <a href="#statefile">state information
</a>). It triggers the global:SHUTDOWN event. If the optional restart
parameter is specified, fhem tries to restart itself.
<br><br>
Example:
<ul>
<code>shutdown</code><br>
<code>shutdown restart</code>
</ul>
</ul>
<a name="trigger"></a>
<h3>trigger</h3>
<ul>
<code>trigger <devspec> <state></code>
<br><br>
Trigger a <a href="#notify">notify</a> definition.
See the <a href="#devspec">Device specification</a> section for details on
<devspec>.
<br><br>
Example:
<ul>
<code>trigger btn3 on</code>
</ul>
</ul>
<a name="sleep"></a>
<h3>sleep</h3>
<ul>
<code>sleep <sec></code>
<br><br>
Sleep for a given amount, millisecond accuracy.
<br><br>
Example:
<ul>
<code>sleep 0.5</code><br>
<code>define n3 notify btn3.* set lamp toggle;;sleep 0.5;;set lamp toggle</code>
</ul>
<br>
Note: sleep followed by another command and issued in at/notify/etc is not
blocking fhem.<br>
</ul>
<a name="global"></a>
<h3>global</h3>
<ul>
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<br>
<br>
<b>Define</b><ul>N/A</ul><br>
<b>Set </b><ul>N/A</ul><br>
<b>Get</b><ul>N/A</ul><br>
<b>Attributes</b>
<ul>
<li><a href="#archivedir">archivedir</a></li>
<li><a href="#archivecmd">archivecmd</a></li>
<li><a href="#nrarchive">nrarchive</a></li><br>
<a name="autoload_undefined_devices"></a>
<li>autoload_undefined_devices<br>
If set, automatically load the corresponding module when a message
of this type is received. This is used by the <a href="#autocreate">
autocreate</a> device, to automatically create a fhem device upon
receiving a corresponding message.
</li><br>
<a name="backup_before_update"></a>
<li>backup_before_update<br>
If this attribute is set to 0, an update skip always backing up your
installation via the <a href="#backup">backup</a> command. The default
is to backup always before updates.<br>
Note: Set this attribute only if you know what you do!<br>
This Attribute is used by the <a href="#update">update</a> command.<br>
Example:<br>
<ul>
attr global backup_before_update 0
</ul>
</li><br>
<a name="backupcmd"></a>
<li>backupcmd<br>
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 <strong>one</strong>
argument to the command, like e.g.:
<br>
<ul>
<code>"/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"</code>
</ul>
Note: Your command / script has to return the string "backup done" or
everything else to report errors, to work properly with updatefhem!<br>
This Attribute is used by the <a href="#backup">backup</a> command.<br>
Example:<br>
<ul>
attr global backupcmd /usr/local/bin/myBackupScript.sh
</ul>
</li><br>
<a name="backupdir"></a>
<li>backupdir<br>
A folder to store the compressed backup file.
This Attribute is used by the <a href="#backup">backup</a> command.<br>
Example:<br>
<ul>
attr global backupdir /Volumes/BigHD
</ul>
</li><br>
<a name="backupsymlink"></a>
<li>backupsymlink<br>
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 <a href="#backup">backup</a> command.<br>
Example:<br>
<ul>
attr global backupsymlinks yes
</ul>
</li><br>
<a name="configfile"></a>
<li>configfile<br>
Contains the name of the fhem configuration file. If <a
href="#save">save</a> is called without argument, then the output will
be written to this file.
</li><br>
<a name="exclude_from_update"></a>
<li>exclude_from_update<br>
Contains a space separated list of file which will be excluded by an update.
This Attribute is used by the <a href="#update">update</a> command.<br>
Example:<br>
<ul>
attr global exclude_from_update 21_OWTEMP.pm temp4hum4.gplot FS20.on.png FS20.off.png
</ul>
</li><br>
<a name="holiday2we"></a>
<li>holiday2we<br>
If this attribute is set, then the <a href="#perl">$we</a> variable
will be true, if the value of the <a href="#holiday">holiday</a>
variable referenced by this attribute is not none.<br>
Example:<br>
<ul>
attr global holiday2we hessen
</ul>
</li><br>
<a name="lastinclude"></a>
<li>lastinclude<br>
If this attribute is set, then the last command of the generated
configfile (see the <a href="#save">save</a> command) will be<br>
include <lastinclude-value><br>
This attribute is DEPRECATED, use <a href="#notify">notify</a>, with
the INITIALIZED event to execute commands after initialization.
</li><br>
<a name="logfile"></a>
<li>logfile<br>
Specify the logfile to write. You can use "-" for
stdout, in this case the server won't background itself.<br>
The logfile name can also take wildcards for easier logfile rotation,
see the <a href="#FileLog">FileLog</a> section. Just apply the
<code>archivecmd / archivedir / nrarchive</code> attributes to the
<code>global</code> device as you would do for a FileLog device.<br>
You can access the current name of the logfile with
<code>{ $currlogfile }</code>.
</li><br>
<a name="modpath"></a>
<li>modpath<br>
Specify the path to the modules directory <code>FHEM</code>. The path
does <b>not</b> 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).
</li><br>
<a name="motd"></a>
<li>motd<br>
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
</li><br>
<a name="mseclog"></a>
<li>mseclog<br>
If set, the timestamp in the logfile will contain a millisecond part.
</li><br>
<a name="nofork"></a>
<li>nofork<br>
If set and the logfile is not "-", do not try to background. Needed
on some Fritzbox installations.
</li><br>
<a name="pidfilename="></a>
<li>pidfilename<br>
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.
</li><br>
<li><a href="#fheminfo">sendStatistics</a>
<a name="statefile"></a>
<li>statefile<br>
Set the filename where the state and certain <a href="#at">at</a>
information will be saved before shutdown. If it is not specified, then
no information will be saved.
</li><br>
<a name="title"></a>
<li>title<br>
Used by the web frontend fhemweb.pl (webpgm2) as a Page title.
</li><br>
<li><a href="#fheminfo">uniqueID</a>
<a name="updatebranch"></a>
<li>updatebranch<br>
The update branch will be set by the file FhemUtils/release.pm contained
in the modpath. For example, if a stable version (version 5.3 upwards) of
fhem is installed via a direct download connection of the archieve on the
fhem-website, then the branch of the update is automatically on "stable".
In this branch, only updates fixing confirmed errors, relevant security
fixes or new stable versions are provided.<br>
By using the command "update development <filename>", particular files
or packages can always be installed directly from the development branch
(e.g. "update development <package>").<br>
If you want to update from the development branch in stable verion in
general, you can force this behaviour by using the attribute "updatebranch DEVELOPMENT".
In case the installation of fhem should generally using the development
branch, this attribute would not have to be set. Instead, use "update development force"
to update all files including release.pm (containing the release-information)
to the newest version.
</li><br>
<a name="userattr"></a>
<li>userattr<br>
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).
</li><br>
<a name="verbose"></a>
<li>verbose<br>
Set the verbosity level. Possible values:
<ul>
<li>0 - server start/stop
<li>1 - error messages or unknown packets
<li>2 - major events/alarms.
<li>3 - commands sent out will be logged.
<li>4 - you'll see whats received by the different devices.
<li>5 - debugging.</li>
</ul>
Recommended level is 3 for normal use.
</li><br>
<a name="dupTimeout"></a>
<li>dupTimeout<br>
Define the timeout for which 2 identical events from two different
receiver are considered a duplicate. Default is 0.5 seconds.
</li><br>
<a name="showInternalValues"></a>
<li>showInternalValues<br>
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.
</li>
</ul>
</ul>
<a name="perl"></a>
<h3>Perl specials</h3>
If you want to automate some tasks via fhem, then you'll probably use <a
href="#at">at</a> or <a href="#notify">notify</a>. 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.<br><br>
<li>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.
<ul>
{ "Hello" }<br>
{ 1+3*4 }<br>
{ `ls /etc` }<br>
{ Log 1, "Hello" }<br>
</ul>
<br>
<li>
Perl expressions are separated by ;, in fhem oneliners they have to
escaped with ;;<br>
<ul>
{ my $a = 1+1;; Log 1, "Hello $a" }
</ul>
<br>
<li>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:<br>
<ul>
{ fhem "set light on" }<br>
define n1 notify piri:on { fhem "set light on" }
</ul>
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...".
<br>
<br>
<li>Notify can be used to store macros for manual execution. Use the <a
href="#trigger">trigger</a> command to execute the macro:<br>
<ul>
define MyMacro notify MyMacro { Log 1, "Hello"}<br>
trigger MyMacro<br>
define MacroWithArg notify MyMacro { Log 1, "Hello %"}<br>
trigger MyMacro MyArg<br>
</ul>
<br>
<li>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).<br>
Additionally the variabe $we is 1 if it is weekend (i.e $wday == 0 or
$wday == 6), and 0 otherwise. If the <a href="#holiday2we">holida2we</a>
global attribute is set, $we is 1 for holidays too.<br>
<ul>
define n2 notify piri:on { if($hour > 18 || $hour < 5) {
fhem "set light on" } }<br>
define roll_en *07:45:00 { fhem "trigger SwitchAllRoll on" if(!$we) }<br>
define roll_en *08:30:00 { fhem "trigger SwitchAllRoll on" if($we) }<br>
</ul>
<br>
<li>
The following helper functions are defined in 99_Util.pm (which will
be loaded automatically, as every module with prefix 99):
<ul>
<li>min(a,b), max(a,b)</li>
<li>time_str2num("YYYY-MM-DD HH:MM:SS") returns a numerical value,
which makes computation of time differences easier</li>
<li>abstime2rel("HH:MM:SS") converts an absolute time to a relative one
</li>
</ul>
</li>
<li>
To access the device states/attributes, use the following functions:
<br>
<ul>
<li>Value(<devicename>)<br>
returns the state of the device (the string you see in paranthesis in
the output of the list command).
<br><br>
<li>OldValue(<devicename>)
<li>OldTimestamp(<devicename>)<br>
returns the old value/timestamp of the device.
<br><br>
<li>
ReadingsVal(<devicename>,<reading>,<defaultvalue>)<br>
Return the reading (the value in the Readings section of "list device")
<br><br>
<li>
AttrVal(<devicename>,<attribute>,<defaultvalue>)<br>
Return the attribute of the device
<br><br>
{ Value("wz") }<br>
{ OldValue("wz") }<br>
{ time_str2num(OldTimestamp("wz")) }<br>
{ ReadingsVal("wz", "measured-temp", "20")+0 }<br>
{ ReadingsTimestamp("wz", "measured-temp", 0)}<br>
{ AttrVal("wz", "room", "none") }<br>
</ul>
<li>
By using the 99_SUNRISE_EL.pm module, you have access to the following
functions: <br>
<ul>
sunset($offset, $min, $max)<br>
sunrise($offset, $min, $max)<br>
isday()<br>
</ul>
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.
</li>
<br>
<br>
<a name="gnuplot-syntax"></a>
<h3>gnuplot file syntax</h3>
The .gplot files are also used by the <a href="#FHEMWEB">FHEMWEB</a>/SVG module
when the <a href="#plotmode">plotmode</a> 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 <a
href="http://fhemwiki.de/wiki/Creating_Plots">this</a> fhemwiki entry on
creating logs.<br>
Following is a minimal .gplot definition (valid only for plotmode SVG):<br>
<pre>
set terminal size <SIZE>
#FileLog 4:::
plot title 'Temperature' with lines
</pre>
The .gnuplot file consists of 3 parts:
<ul>
<li>set commands<br>
Following sets are recognized:
<ul>
<li>terminal, only the size parameter.<br>
This is usually set to <SIZE>, which is replaced by the <a
href="#plotsize">plotsize</a> attribute of the FHEMWEB or weblink
instance.</li>
<li>title<br>
Usually set to <TL> which is replace by the weblink <a
href="#title">title</a> attribute, or to <Lx>, which is replaced
by the weblink <a href="#label">label</a> attribute.</li>
<li>ylabel,y2label<br>
Left and right labels, printed vertically. Are also subject to label
replacement.</li>
<li>yrange,y2range<br>
Specify the range of the left and right axis. Examples:<br>
<ul>
set yrange [-0.1:1.1]<br>
set y2range [0:]<br>
</ul>
</li>
<li>ytics,y2tics<br>
the label for the left/right axis tics. Examples:<br>
<ul>
set ytics ("on" 0, "off" 1)<br>
set y2tics<br>
</ul>
</li>
</ul>
</li>
<br>
<li>#FileLog entries<br>
Each line from the plot section must have one corresponding #FileLog
line. For the syntax see the column_spec paragraph of the <a
href="#FileLogget">Filelog get</a> 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)
</li>
<br>
<li>plot entries<br>
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:
<ul>
<li>axes x1y1 / x1y2<br>
tells the program to assign the current line to one of the two axes
(left or right).
</li>
<li>title<br>
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.
</li>
<li>with <linetype><br>
Specify the line type. Following types are recognized: points,
steps, fsteps, histeps and lines. Everything unknown will be mapped to
the type lines.
</li>
<li>ls <linestyle><br>
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.<br>
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.
</li>
<li>lw <linewidth><br>
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.
</li>
</ul>
</ul>
</li>
</body>
</html>