mirror of
https://github.com/fhem/fhem-mirror.git
synced 2024-11-22 02:59:49 +00:00
2217 lines
84 KiB
HTML
2217 lines
84 KiB
HTML
<!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="../www/pgm2/style.css" />
|
|
<meta http-equiv="Content-type" content="text/html; charset=UTF-8">
|
|
<meta name="viewport" content="initial-scale=1.0,user-scalable=1">
|
|
<link rel="shortcut icon" href="/fhem/icons/favicon.ico"/>
|
|
</head>
|
|
|
|
|
|
<body style="word-wrap: break-word;" class="commandref">
|
|
<div id="menuScrollArea">
|
|
<div id="logo"></div>
|
|
<div id="menu">
|
|
<h3>fhem.pl reference</h3>
|
|
<br><br>
|
|
<a href="#top">Scroll to top</a>
|
|
<br><br>
|
|
<a style="display:none" href="#" name="loadAll">Load everything</a>
|
|
<br><br>
|
|
<a id="otherLang" style="display:none" href="#" name="otherLang">
|
|
Load <span style="display:none" lang="DE">german</span>
|
|
<span style="display:none" lang="EN">english</span>
|
|
doc for <span class="mod"></span>
|
|
</a>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="right">
|
|
<a id="top"></a>
|
|
<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>
|
|
<a href="#attributes">Attributes</a><br>
|
|
|
|
<br>
|
|
<b>FHEM commands</b>
|
|
<ul>
|
|
<!-- header:command -->
|
|
<a href="#apptime">apptime</a> <!-- provides information about execution times -->
|
|
<a href="#attr">attr</a> <!-- set an attribute for a FHEM device -->
|
|
<a href="#cancel">cancel</a> <!-- cancel sleep -->
|
|
<a href="#createlog">createlog</a> <!-- add a FileLog and an SVG to an existing device -->
|
|
<a href="#define">define</a> <!-- define/create a FHEM device -->
|
|
<a href="#defmod">defmod</a> <!-- define or modify a FHEM device -->
|
|
<a href="#delete">delete</a> <!-- delete a FHEM device -->
|
|
<a href="#deleteattr">deleteattr</a> <!-- delete an attribute -->
|
|
<a href="#deletereading">deletereading</a> <!-- delete a reading -->
|
|
<a href="#displayattr">displayattr</a> <!-- show attributes -->
|
|
<a href="#get">get</a> <!-- retrieve a value from a FHEM device -->
|
|
<a href="#IF">IF</a> <!-- conditionally execute FHEM commands -->
|
|
<a href="#include">include</a> <!-- read in a file with FHEM commands -->
|
|
<a href="#inform">inform</a> <!-- show events in a telnet connection -->
|
|
<a href="#list">list</a> <!-- display definition,readings and attributes of a FHEM device -->
|
|
<a href="#modify">modify</a> <!-- change the definition of a FHEM device -->
|
|
<a href="#notice">notice</a> <!-- view and confirm of system messages -->
|
|
<a href="#quit">quit</a> <!-- end a telnet connection to FHEM -->
|
|
<a href="#reload">reload</a> <!-- reload a FHEM module (program definition) -->
|
|
<a href="#rename">rename</a> <!-- rename a FHEM device -->
|
|
<a href="#rereadcfg">rereadcfg</a> <!-- reread the FHEM configuration -->
|
|
<a href="#save">save</a> <!-- save the FHEM configuration -->
|
|
<a href="#set">set</a> <!-- set a value in a FHEM device -->
|
|
<a href="#setdefaultattr">setdefaultattr</a> <!-- define a default attribute -->
|
|
<a href="#setreading">setreading</a> <!-- set a reading for a FHEM device -->
|
|
<a href="#setstate">setstate</a> <!-- set the main state of a FHEM device -->
|
|
<a href="#setuuid">setuuid</a> <!-- set the FUUID internal -->
|
|
<a href="#show">show</a> <!-- show temporary room (FHEMWEN only) -->
|
|
<a href="#shutdown">shutdown</a> <!-- shut down (terminate) FHEM -->
|
|
<a href="#sleep">sleep</a> <!-- sleep (delay execution) for a while -->
|
|
<a href="#trigger">trigger</a> <!-- generate a FHEM event -->
|
|
<a href="#usb">usb</a> <!-- discover USB devices -->
|
|
|
|
</ul>
|
|
|
|
<br>
|
|
<b>Device modules</b>
|
|
<ul>
|
|
<a href="#global">global</a><br>
|
|
<!-- header:device -->
|
|
|
|
</ul>
|
|
|
|
<br>
|
|
<b>Helper modules</b>
|
|
<ul>
|
|
<!-- header:helper -->
|
|
<a href="#CustomReadings">CustomReadings</a>
|
|
<a href="#DOIF">DOIF</a>
|
|
<a href="#Dashboard">Dashboard</a>
|
|
<a href="#dewpoint">dewpoint</a>
|
|
<a href="#FLOORPLAN">FLOORPLAN</a>
|
|
<a href="#HCS">HCS</a>
|
|
<a href="#Heating_Control">Heating_Control</a>
|
|
<a href="#HMinfo">HMinfo</a>
|
|
<a href="#HourCounter">HourCounter</a>
|
|
<a href="#MaxScanner">MaxScanner</a>
|
|
<a href="#PachLog">PachLog</a>
|
|
<a href="#RandomTimer">RandomTimer</a>
|
|
<a href="#rain">rain</a>
|
|
<a href="#remotecontrol">remotecontrol</a>
|
|
<a href="#statistics">statistics</a>
|
|
<a href="#Twilight">Twilight</a>
|
|
<a href="#THRESHOLD">THRESHOLD</a>
|
|
<a href="#WeekdayTimer">WeekdayTimer</a>
|
|
<a href="#WOL">WOL</a>
|
|
<!-- header end -->
|
|
</ul>
|
|
|
|
<br>
|
|
<a href="#perl">Perl specials</a><br>
|
|
<a href="#regexp">Regexp</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 reasonable 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
|
|
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 "<fhem-command>" "..."</code>
|
|
</ul>
|
|
<br>
|
|
If a OS-user called fhem exists, and FHEM is started as root, FHEM will
|
|
automatically change to to this user via setuid.
|
|
<br><br>
|
|
|
|
If FHEM is started with the -d option (perl fhem.pl -d fhem.cfg), then the
|
|
verbose level is set to 5 and the logfile is redirected to the STDOUT.
|
|
<br><br>
|
|
|
|
The environment variable FHEM_GLOBALATTR is evaluated: it consists of space
|
|
separated name=value pairs, where name is a global attribute. Values from this
|
|
source override values set in the configuration file.
|
|
|
|
</ul>
|
|
<!-- intro end - diese Zeile nicht entfernen! -->
|
|
|
|
|
|
<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>
|
|
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:<br>
|
|
<ul>
|
|
define onAt at 07:00 set Lamp1 on;;set Lamp2 on;; define offAt at +00:10 set Lamp1 off;;;;set Lamp2 off
|
|
</ul>
|
|
Don't dispair, the previous example can also be written as
|
|
<ul>
|
|
define onAt at 07:00 set Lamp1,Lamp2 on-for-timer 600
|
|
</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>
|
|
Note: mixing command types (FHEM/shell/perl) on one line is not supported, even
|
|
if it might work in some cases.
|
|
<br>
|
|
</ul>
|
|
<!-- command end - diese Zeile nicht entfernen! -->
|
|
|
|
|
|
<a name="devspec"></a>
|
|
<h3>Device specification (devspec)</h3>
|
|
<ul>
|
|
The commands
|
|
<a href="#attr">attr</a>,
|
|
<a href="#deleteattr">deleteattr</a>,
|
|
<a href="#displayattr">displayattr</a>,
|
|
<a href="#delete">delete</a>,
|
|
<a href="#get">get</a>,
|
|
<a href="#list">list</a>,
|
|
<a href="#set">set</a>,
|
|
<a href="#setreading">setreading</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 regular expression</li>
|
|
<li>a NAME=VALUE pair, where NAME can be an internal value like TYPE, a
|
|
Reading-Name or an attribute. VALUE is a regexp. To negate the
|
|
comparison, use NAME!=VALUE. To restrict the search, use i: as prefix
|
|
for internal values, r: for readings and a: for attributes.
|
|
See the example below.
|
|
Case sensitivity is being ignored using ~ or !~. </li>
|
|
<li>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.
|
|
</ul>
|
|
Examples:
|
|
<ul>
|
|
<code>set lamp1 on</code><br>
|
|
<code>set lamp1,lamp2,lamp3 on</code><br>
|
|
<code>set lamp.* on</code><br>
|
|
<code>set room=kitchen off</code><br>
|
|
<code>set room=kitchen:FILTER=STATE=on off</code><br>
|
|
<code>set room=kitchen:FILTER=STATE!=off off</code><br>
|
|
<code>list disabled=</code><br>
|
|
<code>list room~office</code><br>
|
|
<code>list TYPE=FS20 STATE</code><br>
|
|
<code>list i:TYPE=FS20 STATE</code><br>
|
|
</ul>
|
|
Notes:
|
|
<ul>
|
|
<li>the spec may not contain space characters.</n>
|
|
<li>if there is a device which exactly corresponds to the spec, then
|
|
no special processing is done.</li>
|
|
<li>first the spec is separated by comma, then the regular expression and
|
|
filter operations are executed.</li>
|
|
<li>the returned list can contain the same device more than once, so
|
|
"set lamp3,lamp3 on" switches lamp3 twice.</li>
|
|
<li>for more complex structuring demands see the <a href="#structure">
|
|
structure</a> device.
|
|
</ul>
|
|
</ul>
|
|
<!-- devspec end - diese Zeile nicht entfernen! -->
|
|
|
|
|
|
<a name="attributes"></a>
|
|
<h3>Attributes</h3>
|
|
|
|
All devices have attributes. These can be set by means of the <a
|
|
href="#attr">attr</a> command, displayed with the <a
|
|
href="#displayattr">displayattr</a> command, and deleted by the <a
|
|
href="#deleteattr">deleteattr</a> command.<p>
|
|
|
|
There are global attributes that are used by all devices and local attributes
|
|
that apply to individual device classes only.<p>
|
|
|
|
Some devices (like <a href="#FHEMWEB">FHEMWEB</a>) automatically define new
|
|
global attributes on the first definition of a device of such type.<p>
|
|
|
|
You can use the command <p><code>attr global userattr
|
|
<attributelist></code><p> for the <a href="#global">global</a> device to
|
|
declare new global attributes and <p><code>attr <devicespec> userattr
|
|
<attributelist></code><p> for individual devices according to <a
|
|
href="#devspec">devspec</a> to declare new local attributes.
|
|
|
|
<code><attributelist></code> is a space-separated list which contains the
|
|
names of the additional attributes. See the documentation of the <a
|
|
href="#attr">attr</a> command for examples.<p>
|
|
|
|
Be careful not to overwrite additional global attributes previously defined by
|
|
yourself or a device. Use the <code>attr global userattr
|
|
<attributelist></code> as early in your configuration as possible.
|
|
|
|
<h4>Device specific attributes</h4>
|
|
|
|
Device specific attributes are documented in the corresponding device section.
|
|
|
|
|
|
<h4>Global attributes used by all devices</h4>
|
|
|
|
<ul>
|
|
|
|
<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.
|
|
</li><br>
|
|
|
|
<a name="comment"></a>
|
|
<li>comment<br>
|
|
Add an arbitrary comment.
|
|
</li><br>
|
|
|
|
<a name="eventMap"></a>
|
|
<li>eventMap<br>
|
|
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.
|
|
You can specify a widgetOverride after an additional colon (e.g.
|
|
on-for-timer:OnFor:texField), the default widget is :noArg to avoid
|
|
extra input fields in cmdList.
|
|
Examples:<ul><code>
|
|
attr store eventMap on:open off:closed<br>
|
|
attr store eventMap /on-for-timer 10:open/off:closed/<br>
|
|
set store open
|
|
</code></ul>
|
|
The explicit variant of this attribute has the following syntax:
|
|
<ul><code>
|
|
attr store eventMap { dev=>{'on'=>'open'}, usr=>{'open'=>'on'} }<br>
|
|
attr store eventMap { dev=>{'^on(-for-timer)?(.*)'=>'open$2'},
|
|
usr=>{'^open(.*)'=>'on$1'},
|
|
fw=>{'^open(.*)'=>'open'} }
|
|
</code></ul>
|
|
This variant must be used, if the mapping is not symmetrical, the first
|
|
part (dev) representing the device to user mapping, i.e. if the device
|
|
reports on 100 or on-for-timer 100, the user will see open 100. The
|
|
second part (usr) is the other direction, if the user specified open
|
|
10, the device will receive on 10. On both occasions the key will be
|
|
first compared directly with the text, and if it is not equal, then it
|
|
will be tried to match it as a regexp. When using regexps in the usr
|
|
part with wildcards, the fw part must be filled with the exact same
|
|
keys to enable a correct display in the FHEMWEB set dropdown list in
|
|
the detail view.
|
|
</li><br>
|
|
|
|
<a name="genericDisplayType"></a>
|
|
<li>genericDisplayType<br>
|
|
used by some frontends (but not FHEMWEB) to offer a default image or
|
|
appropriate commands for this device. Currently the following values
|
|
are supported: switch,outlet,light,blind,speaker,thermostat
|
|
</li><br>
|
|
|
|
<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><br>
|
|
|
|
<a name="overrideNotifydev"></a>
|
|
<li>overrideNotifydev<br>
|
|
if set (the argument is a devspec), the optimization for notifications
|
|
is using this value instead of the module-set NOTIFYDEV internal.
|
|
Use it only, if you know it better than the module maintainer.
|
|
In order to be available, the global or the device userattr must be set
|
|
first, to include it.
|
|
</li><br>
|
|
|
|
<a name="room"></a>
|
|
<li>room<br>
|
|
Filter/group devices in frontends. 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 FHEMWEB attribute <a href="#hiddenroom">hiddenroom</a> to
|
|
selectively disable rooms for certain FHEMWEB instances.
|
|
The -> string is considered as a structure separator for rooms, e.g.
|
|
"1st. floor->Master bedroom".
|
|
</li><br>
|
|
|
|
<a name="suppressReading"></a>
|
|
<li>suppressReading<br>
|
|
Used to eliminate unwanted readings. The value is a regular expression,
|
|
with ^ and $ added. Only necessary in exceptional cases.
|
|
</li><br>
|
|
|
|
<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="verbose"></a>
|
|
<li>verbose<br>
|
|
Set the verbosity level. Possible values:
|
|
<ul>
|
|
<li>0 - server start/stop</li>
|
|
<li>1 - error messages or unknown packets</li>
|
|
<li>2 - major events/alarms.</li>
|
|
<li>3 - commands sent out will be logged.</li>
|
|
<li>4 - you'll see whats received by the different devices.</li>
|
|
<li>5 - debugging.</li>
|
|
</ul>
|
|
The value for the <a href="#global">global</a> device is a default for
|
|
other devices without own verbose attribute set.
|
|
</li></br>
|
|
</ul>
|
|
|
|
<a name="readingFnAttributes"></a>
|
|
<h4>readingFnAttributes</h4><p>
|
|
|
|
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. <br>
|
|
|
|
<ul>
|
|
|
|
<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 enclosed in {}, then it is evaluated. This attribute is
|
|
evaluated each time a reading is updated.<br>
|
|
The "set magic" described <a href="#set">here</a> is also applied.<br>
|
|
Note: some FHEM modules are setting STATE directly (against the guidelines),
|
|
in this case the attribute may not work as expected.
|
|
</li>
|
|
<p>
|
|
|
|
<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>
|
|
<p>
|
|
|
|
<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. If an optional [:threshold]
|
|
is given after a reading name events are only generated if the change is >= threshold.
|
|
</li>
|
|
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>
|
|
<p>
|
|
|
|
<a name="timestamp-on-change-reading"></a>
|
|
<li>timestamp-on-change-reading<br>
|
|
The attribute takes a comma-separated list of readings. You may use regular
|
|
expressions in that list. If set, the listed readings will not be changed
|
|
(or created) if event-on-change-reading is also set and it would not create
|
|
an event for this reading.
|
|
</li>
|
|
<p>
|
|
|
|
<a name="event-aggregator"></a>
|
|
<li>event-aggregator
|
|
The primary uses of this attribute are to calculate (time-weighted) averages of
|
|
readings over time periods and to throttle the update rate of readings and thus
|
|
the amount of data written to the logs.<p>
|
|
|
|
This attribute takes a comma-separated list of <code>reading:interval:method:function:holdTime</code>
|
|
quintuples. You may use regular expressions for <code>reading</code>. If set, updates for the
|
|
listed readings are ignored and associated events are suppressed for a black-out period of at
|
|
least <code>interval</code> seconds (downsampling). After the black-out period has expired, the reading is
|
|
updated with a value that is calculated from the values and timestamps of the previously ignored
|
|
updates within the black-out period as follows:
|
|
|
|
<table>
|
|
<tr><th>function</th><th>description</th></tr>
|
|
<tr><td>v</td><td>the last value encountered</td></tr>
|
|
<tr><td>v0</td><td>the first value encountered</td></tr>
|
|
<tr><td>min</td><td>the smallest value encountered</td></tr>
|
|
<tr><td>max</td><td>the largest value encountered</td></tr>
|
|
<tr><td>mean</td><td>the arithmetic mean of all values</td></tr>
|
|
<tr><td>sd</td><td>the standard deviation from the mean</td></tr>
|
|
<tr><td>median</td><td>the median of all values (requires holdTime and method none)</td></tr>
|
|
<tr><td>integral</td><td>the arithmetic sum (if not time-weighted) or integral area (if time-weighted) of all values</td></tr>
|
|
<tr><td>n</td><td>number of samples</td></tr>
|
|
<tr><td>t</td><td>timestamp of the last value</td></tr>
|
|
<tr><td>t0</td><td>timestamp of the first value</td></tr>
|
|
</table>
|
|
<p>
|
|
|
|
If <code>method</code> is <code>none</code>, then that's all there is. If <code>method</code>
|
|
is <code>const</code> or <code>linear</code>, the time-weighted series of values is taken into
|
|
account instead. The weight is the timespan between two subsequent updates.
|
|
With the <code>const</code> method, the value is the value of the reading at the beginning of
|
|
the timespan; with the <code>linear</code> method, the value is the arithmetic average of
|
|
the values at the beginning and the end of the timespan.
|
|
Rollovers of black-out periods are handled as one would expect it.<p>
|
|
|
|
One would typically use the <code>linear</code> method with the <code>mean</code> function for
|
|
quantities continuously varying over time like electric power consumption, temperature or speed.
|
|
For cumulative quantities like energy consumed, rain fallen or distance covered,
|
|
the <code>none</code> method with the <code>v</code> function is used. The <code>constant</code>
|
|
method is for discrete quantities that stay constant until the corresponding reading is updated,
|
|
e.g. counters, switches and the like.<p>
|
|
|
|
If the <code>holdTime</code> in seconds is defined, the samples will be kept in memory allowing
|
|
the calculation of floating statistics instead of blocked statistics. With <code>holdTime</code>
|
|
defined the <code>interval</code> can be kept undefined so that the readings update rate is unchanged
|
|
or it can be set to a value less then <code>holdTime</code> for downsampling as described above
|
|
with a full history of the readings in memory. Note that the historic samples are not persistent
|
|
and will be lost when restarting FHEM.<p>
|
|
|
|
The event aggregator only takes into consideration those updates that remain after preprocessing
|
|
according to the <code>event-on-update-reading</code> and <code>event-on-change-reading</code>
|
|
directives. Besides which, any update of a reading that occurs within a timespan from the preceding
|
|
update that is smaller than the resolution of FHEM's time granularity is ditched.<p>
|
|
|
|
When more than one function should be calculated for the same reading, the original reading must be
|
|
multiplied (e.g. by using a notify) before applying the event-aggregator to the derived readings.<p>
|
|
|
|
Examples:<br>
|
|
<code>attr myPowerMeter event-aggregator EP_POWER_METER:300:linear:mean,EP_ENERGY_METER:300:none:v</code><br>
|
|
<code>attr myBadSensor event-aggregator TEMP::none:median:300</code><br>
|
|
<code>attr mySunMeter event-aggregator SUN_INTENSITY_24H::const:integral:86400</code>
|
|
</li>
|
|
<p>
|
|
|
|
<a name="event-min-interval"></a>
|
|
<li>event-min-interval<br>
|
|
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. If event-on-change-reading is also specified, they are
|
|
combined with OR: if one of them is true, the event is generated.
|
|
</li>
|
|
|
|
<a name="oldreadings"></a>
|
|
<li>oldreadings<br>
|
|
This attribute takes a comma-separated list of readings. You may use
|
|
regular expressions in that list. For each reading in the list FHEM will
|
|
internaly store the previous value if the readings value changes. To access
|
|
the storead value use the OldReadings.* functions.
|
|
If the previous value is always to be stored (even if it didn't changed),
|
|
then set the last value of the comma-separated list to oldreadingsAlways.
|
|
</li>
|
|
|
|
<a name="userReadings"></a>
|
|
<li>userReadings<br>
|
|
A comma-separated list of definitions of user-defined readings. Each
|
|
definition has the form:
|
|
<ul>
|
|
<code>
|
|
<reading>[:<trigger>] [<modifier>] { <perl code> }
|
|
</code>
|
|
</ul>
|
|
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. 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.
|
|
<br>
|
|
Examples:<br>
|
|
<ul><code>
|
|
attr myEnergyMeter userReadings energy
|
|
{ ReadingsVal("myEnergyMeter","counters.A",0)/1250.0;; }<br>
|
|
attr myMultiMeter userReadings
|
|
energy1:counters.A.* { ReadingsVal("myMultiMeter","counters.A",0)/1250.0;; },
|
|
energy2:counters.B.* { ReadingsVal("myMultiMeter","counters.B",0)/1250.0;; }
|
|
</code></ul>
|
|
<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>
|
|
<li>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. <br>
|
|
result += (time - timeold) * (oldval + value) / 2
|
|
</li>
|
|
<li>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.</li>
|
|
<li>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</li>
|
|
</ul>
|
|
Example:<br>
|
|
<ul><code>attr myPowerMeter userReadings power
|
|
differential { ReadingsVal("myPowerMeter","counters.A",0)/1250.0;; }
|
|
</code></ul>
|
|
Notes:
|
|
<ul>
|
|
<li>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>
|
|
<li>the name of the defined Readings consists of alphanumeric characters
|
|
with underscore (_) and the minus (-) sign.</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>Common attributes</h4>
|
|
|
|
The following local attributes are used by a wider range of devices:
|
|
|
|
<ul>
|
|
<a name="IODev"></a>
|
|
<li>IODev<br>
|
|
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.</li><br>
|
|
|
|
<a name="disable"></a>
|
|
<li>disable<br>
|
|
Disables the corresponding device. Note: it can be toggled by issuing the following command:<br/>
|
|
<br>
|
|
<code>attr <device> disable toggle</code>
|
|
</li><br>
|
|
|
|
<a name="disabledForIntervals"></a>
|
|
<li>disabledForIntervals HH:MM-HH:MM HH:MM-HH:MM ...<br>
|
|
Space separated list of HH:MM or D@HH:MM tupels. If the current time is
|
|
between the two time specifications, the current device is disabled.
|
|
Instead of HH:MM you can also specify HH or HH:MM:SS. D is the day of
|
|
the week, with 0 indicating Sunday and 3 indicating Wednesday.
|
|
Specifying the day for the "from" part does _not_ specify it for the
|
|
"to" part, i.e. 1@00-24 will disable from monday to the end of the
|
|
week, but not on sunday (as 1@00 is greater than any time on sunday).
|
|
To specify an interval spawning midnight, you have to specify two
|
|
intervals, e.g.:
|
|
<ul>
|
|
23:00-24:00 00:00-01:00
|
|
</ul>
|
|
If parts of the attribute value are enclosed in {}, they are evaluated:
|
|
<ul>
|
|
{sunset_abs()}-24 {sunrise_abs()}-08
|
|
</ul>
|
|
</li><br>
|
|
|
|
</ul>
|
|
<!-- attributes end - diese Zeile nicht entfernen! -->
|
|
|
|
|
|
<br><br>
|
|
<a name="commands"></a>
|
|
<a name="attr"></a>
|
|
<h3>attr</h3>
|
|
<ul>
|
|
<code>attr [-a|-r|-silent] <devspec> <attrname> [<value>]</code>
|
|
<br>
|
|
|
|
<br>Set an attribute for a device defined by <a href="#define">define</a>.
|
|
The value is optional, and is set to 1 if missing.
|
|
You can define your own <a href="#attributes">attributes</a> 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>.
|
|
After setting the attribute, the global event "ATTR" will be generated.
|
|
<br>
|
|
If the option -a is specified, append the given value to the currently
|
|
existing value. Note: if the value does not start with a comma (,), then a
|
|
space will be added automatically to the old value before appending the
|
|
new.<br>
|
|
With the -r option one can remove a part of an attribute value.<br>
|
|
With the -silent option the command is not recorded in the "save -?" list.<br>
|
|
<br>
|
|
|
|
Examples:
|
|
<ul><code>
|
|
attr global verbose 3<br>
|
|
attr lamp room kitchen<br>
|
|
attr lamp group lights<br>
|
|
attr lamp loglevel 6<br>
|
|
attr weatherstation event-on-update-reading wind,temperature,humidity<br>
|
|
attr weatherstation event-on-change-reading israining<br>
|
|
attr weatherstation event-on-change-reading israining,state<br>
|
|
attr heating stateFormat Temp:measured-temp, Valve:actuator<br>
|
|
attr -a TYPE=SVG room ,SvgRoom</br>
|
|
attr -r TYPE=SVG room ,SvgRoom</br>
|
|
</code></ul>
|
|
<br>
|
|
|
|
Notes:<br>
|
|
<ul>
|
|
<li>See <a href="#deleteattr">deleteattr</a> to delete attributes.</li>
|
|
</ul>
|
|
</ul>
|
|
<!-- attr end -->
|
|
|
|
<a name="cancel"></a>
|
|
<h3>cancel</h3>
|
|
<ul>
|
|
<code>cancel [<id> [quiet]]</code>
|
|
<br><br>
|
|
List named sleeps or cancel a named <a href="#sleep">sleep</a>.
|
|
|
|
</ul>
|
|
<!-- cancel end -->
|
|
|
|
<a name="define"></a>
|
|
<h3>define</h3>
|
|
<ul>
|
|
<code>define [option] <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>
|
|
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>
|
|
Options:<br>
|
|
<ul>
|
|
<li>-temporary<br>
|
|
Add the TEMPORARY flag to the definition, which will prevent saving the
|
|
device to fhem.cfg.
|
|
</li><br>
|
|
<li>-ignoreErr<br>
|
|
Reduce the number of errors displayed when a certain FHEM-module cannot
|
|
be loaded. Used by fhem.cfg.demo, as using the RSS example requires the
|
|
installation of several uncommon perl modules.
|
|
</li><br>
|
|
<li>-silent<br>
|
|
Do no enter the command in the "save ?" list.
|
|
</li><br>
|
|
</ul>
|
|
|
|
</ul>
|
|
<!-- define end -->
|
|
|
|
<a name="defmod"></a>
|
|
<h3>defmod</h3>
|
|
<ul>
|
|
<code>defmod [option] <name> <type> <type-specific></code>
|
|
<br><br>
|
|
Define a device or modify it, if it already exists. E.g. to switch off a lamp
|
|
10 Minutes after the last message from the motion detector, you may use
|
|
<ul><code>
|
|
define mdNtfy notify motionDetector defmod mdOff at +00:10 set lamp off
|
|
</code></ul>
|
|
Using define here for the mdOff will generate an error if the motion detector
|
|
triggers within the 10 minutes after the first event, as the mdOff at
|
|
definition still exists.<br>
|
|
For the options see the define documentation.
|
|
<br>
|
|
</ul>
|
|
<!-- defmod end -->
|
|
|
|
|
|
<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>
|
|
<!-- delete end -->
|
|
|
|
<a name="deleteattr"></a>
|
|
<h3>deleteattr</h3>
|
|
<ul>
|
|
<code>deleteattr [-silent] <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>
|
|
<attrname> is in fact a regexp, complemented with ^ and $ as usual, so
|
|
a range of attributes can be deleted with one command.<br>
|
|
After deleting the attribute, the global event "DELETEATTR" will be generated.
|
|
<br>
|
|
|
|
Examples:
|
|
<ul>
|
|
<code>deleteattr lamp follow-on-for-timer</code><br>
|
|
<code>deleteattr lamp</code><br>
|
|
</ul>
|
|
<br>
|
|
</ul>
|
|
<!-- deleteattr end -->
|
|
|
|
<a name="deletereading"></a>
|
|
<h3>deletereading</h3>
|
|
<ul>
|
|
<code>deletereading <devspec> <readingname>
|
|
[<older-than-seconds>]</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>
|
|
<!-- deletereading end -->
|
|
|
|
<a name="displayattr"></a>
|
|
<h3>displayattr</h3>
|
|
<ul>
|
|
<code>displayattr <devspec> [<attrname>]</code> <br>
|
|
<br>
|
|
Display either the value of 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>
|
|
If more then one device is specified, then the device name will also included
|
|
in the output.
|
|
<br>
|
|
|
|
Examples:
|
|
<ul>
|
|
<code>
|
|
fhem> di WEB<br>
|
|
menuEntries AlarmOn,/fhem?cmd=set%20alarm%20on<br>
|
|
room Misc.<br>
|
|
fhem> di WEB room<br>
|
|
Misc.<br>
|
|
</code>
|
|
</ul>
|
|
<br>
|
|
</ul>
|
|
<!-- displayattr end -->
|
|
|
|
<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>
|
|
<!-- get end -->
|
|
|
|
|
|
<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.
|
|
Note: only experts should use this command.
|
|
<br>
|
|
</ul>
|
|
<!-- include end -->
|
|
|
|
<a name="inform"></a>
|
|
<h3>inform</h3>
|
|
<ul>
|
|
<code>inform {on|onWithState|off|raw|timer|log|status} [regexp]</code> <br>
|
|
<br>
|
|
Monitor events via a telnet client. This command is the telnet equivalent of
|
|
the FHEMWEB Event monitor, but can also be used by other programs/modules to
|
|
receive a notification. Options:<br>
|
|
<ul>
|
|
<li>on<br>
|
|
switch the inform mechanism on</li>
|
|
<li>onWithState<br>
|
|
show the additional state event too</li>
|
|
<li>off<br>
|
|
switch the inform mechanism off (both events and logs, see below)</li>
|
|
<li>raw<br>
|
|
show only raw events from physical devices</li>
|
|
<li>timer<br>
|
|
prepend a timestamp to each event</li>
|
|
<li>log<br>
|
|
show messages written by the FHEM Log interface</li>
|
|
<li>status<br>
|
|
show the current status</li>
|
|
</ul>
|
|
<br>
|
|
</ul>
|
|
<!-- inform end -->
|
|
|
|
<a name="list"></a>
|
|
<h3>list</h3>
|
|
<ul>
|
|
<code>list [devspec] [value ...]</code><br>
|
|
or<br>
|
|
<code>list {-r|-R} devspec</code><br>
|
|
<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 (internal, reading
|
|
or attribute) for all devices from the devspec. <value> can be
|
|
restricted with prefix i: for internals, r: for readings and a: for
|
|
attributes.
|
|
<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>
|
|
With the -r (raw) option output the device definition in a format suitable
|
|
for inclusion in fhem.cfg and fhem.state. -R returns the definition of the
|
|
device itself, together with the definition of probably associated devices.
|
|
Note: the algorithm to select associated devices is known to be imperfect.
|
|
</ul>
|
|
<!-- list end -->
|
|
|
|
<a name="modify"></a>
|
|
<h3>modify</h3>
|
|
<ul>
|
|
<code>modify [-silent] <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.
|
|
After modify, the global event "MODIFIED" will be generated.<br>
|
|
With the -silent option the command is not recorded in the "save -?" list.<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>
|
|
<!-- modify end -->
|
|
|
|
<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>
|
|
<!-- quit end -->
|
|
|
|
<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>
|
|
<!-- reload end -->
|
|
|
|
<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>
|
|
<!-- rename end -->
|
|
|
|
<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>
|
|
<!-- rereadcfg end -->
|
|
|
|
<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>
|
|
|
|
<li>before overwriting the files, the old version will be saved, see the <a
|
|
href="#restoreDirs">restoreDirs</a> global attribute for details.
|
|
|
|
</ul>
|
|
</ul>
|
|
<!-- save end -->
|
|
|
|
<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>
|
|
From featurelevel 5.7 on the set and setreading command replaces:
|
|
<ul>
|
|
<li>[device:name] with the reading, internal or attribute of the device, if
|
|
both device and the reading, internal or attribute exists.
|
|
<ul>
|
|
<li>You can use the r:, i: or a: prefix to restrict the search to one
|
|
type, analogue to the devspec filtering.</li>
|
|
<li>The suffix :d retrieves the first number</li>
|
|
<li>The suffix :i retrieves the integer part of the first number.</li>
|
|
<li>The suffix :r<n> retrieves the first number and rounds it to
|
|
<n> decimal places. If <n> is missing, then rounds it to
|
|
one decimal place.</li>
|
|
<li>The suffix :t returns the timestamp (works only for readings)</li>
|
|
<li>The suffix :sec returns the number of seconds since the reading was
|
|
set.</li>
|
|
</ul>
|
|
Example:
|
|
<ul>
|
|
set Lamp blink [blinkDummy:number] [r:blinkDummy:duration:d]
|
|
</ul>
|
|
</li>
|
|
<li>[device:name:d] same as above, but only the number is retrieved</li>
|
|
<li>[device:name:sec] same as above, but only the number is retrieved</li>
|
|
<li>{(perlExpression)} with the result of perlExpression.
|
|
The $DEV variable is additionally available, designating the set device
|
|
name.
|
|
</li>
|
|
</ul>
|
|
These replacements are also known as "set magic".
|
|
<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. Note: on-till is not active, if the
|
|
specified time is after the current time, in order to make things like
|
|
<ul><code>
|
|
define morningLight at *06:00 set Lamp on-till {sunrise()}
|
|
</code></ul>
|
|
easy.</li>
|
|
<li>on-till-overnight <timedet><br>
|
|
Like on-till, but wont compare the current time with the timespec, so
|
|
following will work:
|
|
<ul><code>
|
|
define nightLight at *{sunset()} set Lamp on-till-overnight 01:00
|
|
</code></ul>
|
|
</li>
|
|
<li>off-till <timedet><br>
|
|
see on-till above.</li>
|
|
<li>off-till-overnight <timedet><br>
|
|
see on-till-overnight 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>
|
|
<li>toggle<br>
|
|
Issue the off command, if the current STATE is on, else the on command.
|
|
dim XX is also interpreted as on, if XX is not 0.</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>
|
|
<br><br>
|
|
|
|
<a name="attrTemplate"></a>
|
|
attrTemplate<br>
|
|
with this command a set of predefined attributes may be set at once. The
|
|
template files containing the entries are in FHEM/lib/AttrTemplate
|
|
directory. Template entries can be module specific, and may require further
|
|
parameters to be specified.
|
|
|
|
</ul>
|
|
<!-- set end -->
|
|
|
|
<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>
|
|
<!-- setdefaultattr end -->
|
|
|
|
<a name="setreading"></a>
|
|
<h3>setreading</h3>
|
|
<ul>
|
|
<code>setreading <devspec> [YYYY-MM-DD HH:MM:SS] <reading>
|
|
<value></code>
|
|
<br><br>
|
|
Set the reading <reading> for the device <code><name></code> to
|
|
<value> without sending out commands to the device, but triggering
|
|
events and eventMap/stateFormat transformations as usual. See the set
|
|
command documentation for replacement description.<br>
|
|
If the timespec is omitted (default) the current time will be used.
|
|
<br><br>
|
|
Examples:
|
|
<ul>
|
|
setreading lamp state on
|
|
</ul>
|
|
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.
|
|
</ul>
|
|
<!-- setreading end -->
|
|
|
|
<a name="setstate"></a>
|
|
<h3>setstate</h3>
|
|
<ul>
|
|
<code>setstate <devspec> <value></code>
|
|
<br><br>
|
|
Set the STATE entry for the device specified by <code><devspec></code>,
|
|
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 <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: this command is also used to store the readings in the statefile, in
|
|
this case the timestamp will preceed the value. As a side-effect there is no
|
|
way to save a state correctly if it starts with a timestamp in the YYYY-MM-DD
|
|
HH:MM:SS form.
|
|
</ul>
|
|
<!-- setstate end -->
|
|
|
|
<a name="setuuid"></a>
|
|
<h3>setuuid</h3>
|
|
<ul>
|
|
<code>setuuid <device> <uuid></code>
|
|
<br><br>
|
|
System command, used to set the FUUID internal value.
|
|
Not intended to be used by an end user.
|
|
</ul>
|
|
<!-- setstate end -->
|
|
|
|
<a name="show"></a>
|
|
<h3>show</h3>
|
|
<ul>
|
|
<code>show <devspec></code>
|
|
<br><br>
|
|
show a temporary room with devices from <devspec>. The command ist only
|
|
available through FHEMWEB.<br> See the <a href="#devspec">Device
|
|
specification</a> section for details on <devspec>.
|
|
<br><br>
|
|
Example:
|
|
<ul>
|
|
<code>show TYPE=CUL_HM</code><br>
|
|
</ul>
|
|
</ul>
|
|
<!-- show end -->
|
|
|
|
<a name="shutdown"></a>
|
|
<h3>shutdown</h3>
|
|
<ul>
|
|
<code>shutdown [restart|exitValue]</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. exitValue may be
|
|
important for start scripts.
|
|
<br><br>
|
|
Example:
|
|
<ul>
|
|
<code>shutdown</code><br>
|
|
<code>shutdown restart</code><br>
|
|
<code>shutdown 1</code><br>
|
|
</ul>
|
|
</ul>
|
|
<!-- shutdown end -->
|
|
|
|
<a name="sleep"></a>
|
|
<h3>sleep</h3>
|
|
<ul>
|
|
<code>sleep <sec|timespec|regex> [<id>] [quiet]</code>
|
|
|
|
<br><br>
|
|
sleep followed by another command is comparable to a nameless <a
|
|
href="#at">at</a> or <a href="#notify">notify</a>, it executes the
|
|
following commands after waiting for the specified time or an event matching
|
|
<regex>. The delay can be given<ul>
|
|
<li>in seconds, with millisecond accuracy, as you can specify decimal places,
|
|
</li>
|
|
<li>as a timespec (HH:MM or HH:MM:SS or {perlfunc})</li>
|
|
<li>or as a regex (devicename or devicename:event)</li></ul><br>
|
|
|
|
A sleep with an <id> will replace a sleep with the same <id>
|
|
and can be canceled by <a href="#cancel">cancel</a>.
|
|
|
|
When called in a notify/at/etc, then nonempty return values of the following
|
|
commands are logged to the global logfile with loglevel 2.<br> If quiet is
|
|
specified, then skip this logging.
|
|
<br><br>
|
|
Example:
|
|
<ul>
|
|
define n3 notify btn3.* set lamp on;;sleep 1.5;;set lamp off<br>
|
|
define a3 at +*00:05 set Windsensor 1w_measure;; sleep 2 quiet;; get
|
|
Windsensor 1w_temp
|
|
</ul>
|
|
<br>
|
|
Note: a sleep not followed by any command will block FHEM, is deprecated, and
|
|
it issues a WARNING in the FHEM log.
|
|
<br>
|
|
</ul>
|
|
<!-- sleep end -->
|
|
|
|
<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>
|
|
<!-- trigger end -->
|
|
|
|
<!-- commands end - diese Zeile nicht entfernen! -->
|
|
|
|
<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>Internals</b>
|
|
<ul>
|
|
<a name="init_errors"></a>
|
|
<li>init_errors<br>
|
|
contains configuration errors and security issues collected at FHEM
|
|
startup.
|
|
</li><br>
|
|
</ul><br>
|
|
|
|
<b>Attributes</b>
|
|
<ul>
|
|
<a name="altitude"></a>
|
|
<li>altitude<br>
|
|
Specifies the mean sea level in meters. Default is 0.
|
|
</li><br>
|
|
|
|
<li><a href="#archivedir">archivedir</a></li>
|
|
<li><a href="#archivecmd">archivecmd</a></li>
|
|
<li><a href="#nrarchive">nrarchive</a></li>
|
|
<a name="archivesort"></a>
|
|
<li>archivesort<br>
|
|
archivesort may be set to the (default) alphanum or timestamp, and
|
|
specifies how the last files are computed for the nrarchive attribute.
|
|
</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="autosave"></a>
|
|
<li>autosave<br>
|
|
enable some modules to automatically trigger save after a configuration
|
|
change, e.g. after a new device was created. Default is 1 (true), you
|
|
can deactivate this feature by setting the value to 0. Configration
|
|
errors at startup automatically deactivate this value.
|
|
</li>
|
|
|
|
<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 update!<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 backupsymlink yes
|
|
</ul>
|
|
</li><br>
|
|
|
|
<a name="blockingCallMax"></a>
|
|
<li>blockingCallMax<br>
|
|
Limit the number of parallel running processes started by the
|
|
BlockingCall FHEM helper routine. Useful on limited hardware, default
|
|
is 32. If the limit is reached, further calls are delayed.
|
|
</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="commandref"></a>
|
|
<li>commandref<br>
|
|
If set to "full", then a full commandref will be generated after each
|
|
update. If set to modular (default since FHEM 6.1), there is only a
|
|
short description at the beginning, and the module documentation is
|
|
loaded from FHEM dynamically.
|
|
</li><br>
|
|
|
|
<a name="globaldisableFeatures"></a>
|
|
<li>disableFeatures <values><br>
|
|
comma separated list of values. Currently following values are
|
|
recognized:
|
|
<ul>
|
|
<li>attrTemplate: to avoid loading the AttrTemplates (which currently
|
|
consumes about 1MB of memory and needs some seconds to load on a
|
|
slow hardware)</li>
|
|
<li>securityCheck: to avoid checking if each Server port is secured
|
|
by password. May make sense to avoid warnings, if you know it
|
|
better.</li><br>
|
|
</ul>
|
|
</li>
|
|
|
|
<a name="dnsHostsFile"></a>
|
|
<li>dnsHostsFile<br>
|
|
If dnsServer is set, check the contents of the file specified as
|
|
argument. To use the system hosts file, set it to /etc/hosts on
|
|
Linux/Unix/OSX and C:\windows\system32\drivers\etc\hosts on Windows.
|
|
Note: only IPv4 is supported.
|
|
</li><br>
|
|
|
|
<a name="dnsServer"></a>
|
|
<li>dnsServer<br>
|
|
Contains the IP address of the DNS Server. If some of the modules or
|
|
user code calls the HttpUtils_NonblockingGet function, and this
|
|
attribute is set, then FHEM specific nonblocking code will be used to
|
|
resolve the given address. If this attribute is not set, the blocking
|
|
OS implementation (inet_aton and gethostbyname) will be used.
|
|
</li><br>
|
|
|
|
<a name="encoding"></a>
|
|
<li>encoding<br>
|
|
Set the internal encoding used for storing strings.
|
|
Possible values: bytestream (default) and unicode.<br>
|
|
Notes:
|
|
<ul>
|
|
<li>Since not all modules were checked, if they work correctly with
|
|
the internal unicode encoding, this feature is experimental.</li>
|
|
<li>Changing the attribute value triggers a save and a shutdown restart</li>
|
|
</ul>
|
|
</li><br>
|
|
|
|
<a name="featurelevel"></a>
|
|
<li>featurelevel<br>
|
|
Enable/disable old or new features, based on FHEM version.
|
|
E.g. the $value hash for notify is only set for featurelevel up to 5.6,
|
|
as it is deprecated, use the Value() function instead.
|
|
</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 it is either saturday/sunday, or the value of the <a
|
|
href="#holiday">holiday</a> variable referenced by this attribute is
|
|
not none.<br> If it is a comma separated list, then it is true, if one
|
|
of the referenced entities is not none.<br>
|
|
Example:<br>
|
|
<ul>
|
|
attr global holiday2we he
|
|
</ul>
|
|
Note: if one of the elements in the list is named weekEnd, then the
|
|
check for saturday/sunday is skipped If the name is noWeekEnd, and
|
|
its Value is not none, than $we is 0.
|
|
</li><br>
|
|
|
|
<a name="httpcompress"></a>
|
|
<li>httpcompress<br>
|
|
the HttpUtils module is used by a lot of FHEM modules, and enables
|
|
compression by default. Set httpcompress to 0 to disable this feature.
|
|
</li><br>
|
|
|
|
<a name="ignoreRegexp"></a>
|
|
<li>ignoreRegexp<br>
|
|
Do not log messages matching the value into the FHEM log. Note: the
|
|
usual ^ and $ will be appended to the regexp, like in notify or
|
|
FileLog.
|
|
</li><br>
|
|
|
|
<a name="keyFileName"></a>
|
|
<li>keyFileName<br>
|
|
FHEM modules store passwords and unique IDs in the file
|
|
FHEM/FhemUtils/uniqueID. In order to start multiple FHEM instances from
|
|
the same directory, you may set this attribute, whose value will
|
|
appended to FHEM/FhemUtils/
|
|
</li><br>
|
|
|
|
<a name="latitude"></a>
|
|
<li>latitude<br>
|
|
Used e.g. by SUNRISE_EL to calculate sunset/sunrise.<br>
|
|
Default is Frankfurt am Main, Germany (50.112).
|
|
</li><br>
|
|
|
|
<a name="longitude"></a>
|
|
<li>longitude<br>
|
|
Used e.g. by SUNRISE_EL to calculate sunset/sunrise.<br>
|
|
Default is Frankfurt am Main, Germany (8.686).
|
|
</li><br>
|
|
|
|
<a name="logdir"></a>
|
|
<li>logdir<br>
|
|
If set, the %L attribute in the logfile attribute (or in the FileLog
|
|
modules file definition) is replaced wth the value of the attribute.
|
|
Note: changing the value won't result in moving the files and may cause
|
|
other problems.
|
|
</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="maxChangeLog"></a>
|
|
<li>maxChangeLog<br>
|
|
FHEM stores the structural change history which is displayed by
|
|
"save ?" or in FHEMWEB by clicking on the red question mark.
|
|
By default this list is limited to 10 entries, this attribute changes
|
|
the limit.<br>
|
|
The length of each stored line is limited to 40 characters. This value
|
|
can be changed with the (optional, space separated) second number.<br>
|
|
Example: attr global myxChangeLog 20 200
|
|
</li><br>
|
|
|
|
<a name="maxShutdownDelay"></a>
|
|
<li>maxShutdownDelay<br>
|
|
Some modules need some time at shutdown to finish the cleanup, but FHEM
|
|
restricts the delay to 10 seconds. Use this attribute to modify the
|
|
maximum delay.
|
|
</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.
|
|
In addition, the content of the internal value init_errors will be
|
|
displayed. To avoid displaying messages set its 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, and it will be set automatically for
|
|
Windows.
|
|
</li><br>
|
|
|
|
<a id="perlSyntaxCheck"></a>
|
|
<li>perlSyntaxCheck<br>
|
|
by setting the <b>global</b> attribute perlSyntaxCheck, a syntax check
|
|
will be executed upon definition or modification, if the command is
|
|
perl and FHEM is already started.
|
|
</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>
|
|
|
|
<a name="proxy"></a>
|
|
<li>proxy<br>
|
|
IP:PORT of the proxy server to be used by HttpUtils.
|
|
</li><br>
|
|
<a name="proxyAuth"></a>
|
|
<li>proxyAuth<br>
|
|
Base64 encoded username:password
|
|
</li><br>
|
|
<a name="proxyExclude"></a>
|
|
<li>proxyExclude<br>
|
|
regexp for hosts to exclude when using a proxy
|
|
</li><br>
|
|
|
|
<a name="restoreDirs"></a>
|
|
<li>restoreDirs<br>
|
|
update saves each file before overwriting it with the new version from
|
|
the Web. For this purpose update creates a directory restoreDir/update
|
|
in the global modpath directory, then a subdirectory with the current
|
|
date, where the old version of the currently replaced file is stored.
|
|
The default value of this attribute is 3, meaning that 3 old versions
|
|
(i.e. date-directories) are kept, and the older ones are deleted.<br>
|
|
fhem.cfg and fhem.state will be also copied with this method before
|
|
executing save into restoreDir/save/YYYY-MM-DD. To restore the files,
|
|
you can use the restore FHEM command.<br><br>
|
|
If the attribute is set to 0, the feature is deactivated.
|
|
</li><br>
|
|
|
|
<li><a href="#fheminfo">sendStatistics</a><br>
|
|
|
|
<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>
|
|
|
|
<li><a href="#title">title</a><br>
|
|
|
|
<a name="useInet6"></a>
|
|
<li>useInet6<br>
|
|
try to use IPv6 in HttpUtils for communication. If the server does not
|
|
have an IPv6 address, fall back to IPv4. Note: IO::Socket::INET6 is
|
|
required.
|
|
</li><br>
|
|
|
|
<a name="userattr"></a>
|
|
<li>userattr<br>
|
|
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).<br>
|
|
userattr can also specified for other devices, in this case
|
|
these additional attribute names are only valid for this device.
|
|
</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><br>
|
|
|
|
<a name="sslVersion"></a>
|
|
<li>sslVersion<br>
|
|
Specifies the accepted cryptography algorithms by all modules using the
|
|
TcpServices helper module. The current default TLSv12:!SSLv3 is thought
|
|
to be more secure than the previously used SSLv23:!SSLv3:!SSLv2, but it
|
|
causes problems with some not updated web services.
|
|
</li><br>
|
|
|
|
<a name="stacktrace"></a>
|
|
<li>stacktrace<br>
|
|
if set (to 1), dump a stacktrace to the log for each "PERL WARNING".
|
|
</li><br>
|
|
|
|
<a name="restartDelay"></a>
|
|
<li>restartDelay<br>
|
|
set the delay for shutdown restart, default is 2 (seconds).
|
|
</li><br>
|
|
</ul>
|
|
|
|
<br>
|
|
<b>Events:</b>
|
|
<ul>
|
|
<li>INITIALIZED<br>after initialization is finished.</li>
|
|
<li>REREADCFG<br>after the configuration is reread.</li>
|
|
<li>SAVE<br>before the configuration is saved.</li>
|
|
<li>SHUTDOWN<br>before FHEM is shut down.</li>
|
|
<li>DEFINED <devname><br>after a device is defined.</li>
|
|
<li>DELETED <devname><br>after a device was deleted.</li>
|
|
<li>RENAMED <old> <new><br>after a device was renamed.</li>
|
|
<li>UNDEFINED <defspec><br>upon reception of a message for an
|
|
undefined device.</li>
|
|
<li>MODIFIED <defspec></br> after a device modification.</li>
|
|
<li>UPDATE</br> after an update is completed.</li>
|
|
<li>CANNOT_FORK</br>if BlockingCall encounters this problem.</li>
|
|
</ul>
|
|
|
|
|
|
</ul>
|
|
<!-- global end - do not remove this line! -->
|
|
|
|
|
|
<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 the following 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>
|
|
</li><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>
|
|
</li><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...".
|
|
</li><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>
|
|
</li><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).
|
|
Additionally the variable $hms contains the time in the HH:MM:SS format and
|
|
$today the current date in YYYY-MM-DD format.
|
|
<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>
|
|
$we is equivalent to calling IsWe(), which optionally takes the arguments
|
|
"today", "yesterday", "tomorrow", MM-DD or YYYY-MM-DD. Note: for everything
|
|
else the state reading is evaluated, and no error message is issued.
|
|
</li><br>
|
|
|
|
<li>
|
|
All helper functions defined in <a href="#Utils">99_Utils.pm</a><br>
|
|
</li><br>
|
|
|
|
<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 parenthesis in
|
|
the output of the list command). Note: STATE is meant for display
|
|
purposes, and can be customized by the user via the stateFormat
|
|
attribute. Use ReadingsVal(<devicename>, 'state', '') instead for
|
|
computational purposes.
|
|
</li><br>
|
|
<li>OldValue(<devicename>)
|
|
<li>OldTimestamp(<devicename>)<br>
|
|
Returns the old value/timestamp of the device.
|
|
</li><br>
|
|
<li>
|
|
ReadingsVal(<devicename>,<reading>,<defaultvalue>)<br>
|
|
Returns the reading (the value in the Readings section of "list device")
|
|
</li><br>
|
|
<li>
|
|
ReadingsNum(<devicename>,<reading>,
|
|
<defaultvalue>,<round>)<br>
|
|
Returns the first number from a reading value.
|
|
Round it to <round> decimal places (optional parameter). If <round> exeeds the length of
|
|
the factional part, 0's will be padded.
|
|
</li><br>
|
|
<li>ReadingsTimestamp(<devicename>,<reading>,<
|
|
defaultvalue>)<br>
|
|
Returns the timestamp of a reading.
|
|
</li><br>
|
|
<li>ReadingsAge(<devicename>,<reading>,<defaultvalue>)
|
|
<br>
|
|
Returns the age of a reading in seconds.
|
|
</li><br>
|
|
|
|
<li>
|
|
OldReadingsVal(<devicename>,<reading>,
|
|
<defaultvalue>)<br>
|
|
OldReadingsNum(<devicename>,<reading>,
|
|
<defaultvalue>,<round>)<br>
|
|
OldReadingsTimestamp(<devicename>,<
|
|
reading>,<defaultvalue>)<br>
|
|
OldReadingsAge(<devicename>,<reading>,
|
|
<defaultvalue>)<br>
|
|
similar to the above functions, but used to access the previous values.
|
|
see: <a href="#oldreadings">oldreadings</a>
|
|
</li><br>
|
|
|
|
<li>
|
|
AttrVal(<devicename>,<attribute>,<defaultvalue>)<br>
|
|
Returns the attribute of a 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>
|
|
</li><br>
|
|
<li>
|
|
AttrNum(<devicename>,<attribute>,
|
|
<defaultvalue>,<round>)<br>
|
|
Return the first number from an attribute value.
|
|
Round id to <round> devimal places (optional parameter).
|
|
</li><br>
|
|
<li>
|
|
InternalVal(<devicename>,<property>,<defaultvalue>)
|
|
<br>
|
|
Return the internal value (the value in the Internals section of "list
|
|
device").
|
|
</li><br>
|
|
<li>
|
|
InternalNum(<devicename>,<property>,
|
|
<defaultvalue>,<round>)<br>
|
|
Return the first number from an internal value.
|
|
Round it to <round> decimal places (optional parameter). If <round> exeeds the length of
|
|
the factional part, 0's will be padded.
|
|
</li><br>
|
|
</ul>
|
|
</li><br>
|
|
|
|
<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>
|
|
<!-- perl end - diese Zeile nicht entfernen! -->
|
|
|
|
<a name="regexp"></a>
|
|
<h3>Regexp</h3>
|
|
FHEM makes heavy use of regexp, which is short for regular expressions.
|
|
Other shorthands are regex or re.<br>
|
|
|
|
With a regexp you can check if a text/string contains the substrings what you
|
|
are looking for, or extract parts of this string for later usage.<br>
|
|
|
|
Regexp is not to be confused with glob, which is used in the shell: .* is the
|
|
regexp equivalent of the glob *<br>
|
|
|
|
Some examples:<ul>
|
|
<table>
|
|
<tr><th>Regexp</th><th>Explanation</th></tr>
|
|
<tr><td>.</td>
|
|
<td>Matches one arbitrary character.</td></tr>
|
|
<tr><td>x</td>
|
|
<td>Matches a string containing x: x, xy, but not abc</td></tr>
|
|
<tr><td>^x</td>
|
|
<td>Matches a string starting with x: x, xy, but not yx</td></tr>
|
|
<tr><td>x$</td>
|
|
<td>Matches a string ending with x: x, yx, but not xy</td></tr>
|
|
<tr><td>^x?$</td>
|
|
<td>Matches zero or one x: "", x, but not xx</td></tr>
|
|
<tr><td>^x*$</td>
|
|
<td>Matches zero or more x: "", x, xxxx, but not xy or yx</td></tr>
|
|
<tr><td>^x+$</td>
|
|
<td>Matches one or more x: x, xxxx, but not ""</td></tr>
|
|
<tr><td>^(xy|yx)$</td>
|
|
<td>Matches xy or yx</td></tr>
|
|
<tr><td>*</td><td>Not a valid regexp! This is a glob</td></tr>
|
|
</table>
|
|
</ul>
|
|
There is a lot more to know about regexps. There is an extensive
|
|
documentation coming with your perl installation: try in the OS commandline
|
|
perldoc perlretut first, and perldoc perlre for details.<br>
|
|
|
|
If unsure, test your regexp in an online regexp tester, like
|
|
<a target="_blank" href="https://regex101.com">regex101.com</a>,
|
|
<a target="_blank" href="https://regexr.com">regexr.com</a> or
|
|
<a target="_blank" href="https://regextester.com">regextester.com</a>
|
|
.<br>
|
|
|
|
You can also test your regexp in the FHEM commandline:<br>
|
|
<ul>
|
|
{ "StringToTest" =~ m/^Str/ }<br>
|
|
{ "StringToTest" =~ m/^str$/ }<br>
|
|
{ "StringToTest" =~ m/(To|From)/ }<br>
|
|
</ul>
|
|
<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://wiki.fhem.de/wiki/Creating_Plots">this</a> FHEM Wiki 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.
|
|
SVG special: cubic and quadratic, are mapped to the SVG path types C,
|
|
and Q respectively.
|
|
</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>
|
|
|
|
</div> <!-- right -->
|
|
</body>
|
|
</html>
|