hmetzner
/
do_fhem


			
							1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789
							<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>
  <title>FHEM reference</title>
  <script type="text/javascript" src="fhemdoc.js"></script>
  <noscript>
    <link rel="stylesheet" type="text/css" href="../www/pgm2/style.css" />
  </noscript>
  <meta http-equiv="Content-type" content="text/html; charset=UTF-8">
  <link rel="shortcut icon" href="/fhem/icons/favicon.ico"/>
</head>


<body style="word-wrap: break-word;">
  <div id="menuScrollArea">
    <div id="logo"></div>
    <div id="menu">
      <h3>fhem.pl reference</h3>
      Version: <b>EN</b>&nbsp;<a href="commandref_DE.html">DE</a>
      <br><br>
      <a href="#doctop">Scroll to top</a>
      <br><br>
      <a style="display:none" href="#" name="loadAll">Load complete doc</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 name="doctop"></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> &nbsp; <!-- provides information about execution times -->
      <a href="#attr">attr</a> &nbsp;       <!-- set an attribute for a FHEM device -->
      <a href="#cancel">cancel</a> &nbsp;   <!-- cancel sleep -->
      <a href="#createlog">createlog</a> &nbsp; <!-- add a FileLog and an SVG to an existing device -->
      <a href="#define">define</a> &nbsp;   <!-- define/create a FHEM device -->
      <a href="#defmod">defmod</a> &nbsp;   <!-- define or modify a FHEM device -->
      <a href="#delete">delete</a> &nbsp;   <!-- delete a FHEM device -->
      <a href="#deleteattr">deleteattr</a> &nbsp; <!-- delete an attribute -->
      <a href="#deletereading">deletereading</a> &nbsp; <!-- delete a reading -->
      <a href="#displayattr">displayattr</a> &nbsp;  <!-- show attributes -->
      <a href="#get">get</a> &nbsp;         <!-- retrieve a value from a FHEM device -->
      <a href="#IF">IF</a> &nbsp;           <!-- conditionally execute FHEM commands -->
      <a href="#include">include</a> &nbsp; <!-- read in a file with FHEM commands -->
      <a href="#inform">inform</a> &nbsp;   <!-- show events in a telnet connection -->
      <a href="#list">list</a> &nbsp;       <!-- display definition,readings and attributes of a FHEM device -->
      <a href="#modify">modify</a> &nbsp;   <!-- change the definition of a FHEM device -->
      <a href="#notice">notice</a> &nbsp;   <!-- view and confirm of system messages -->
      <a href="#quit">quit</a> &nbsp;       <!-- end a telnet connection to FHEM -->
      <a href="#reload">reload</a> &nbsp;   <!-- reload a FHEM module (program definition) -->
      <a href="#rename">rename</a> &nbsp;   <!-- rename a FHEM device -->
      <a href="#rereadcfg">rereadcfg</a> &nbsp; <!-- reread the FHEM configuration -->
      <a href="#save">save</a> &nbsp;       <!-- save the FHEM configuration -->
      <a href="#set">set</a> &nbsp;         <!-- set a value in a FHEM device -->
      <a href="#setdefaultattr">setdefaultattr</a> &nbsp; <!-- define a default attribute -->
      <a href="#setreading">setreading</a> &nbsp; <!-- set a reading for a FHEM device -->
      <a href="#setstate">setstate</a> &nbsp; <!-- set the main state of a FHEM device -->
      <a href="#shutdown">shutdown</a> &nbsp; <!-- shut down (terminate) FHEM -->
      <a href="#sleep">sleep</a> &nbsp;     <!-- sleep (delay execution) for a while -->
      <a href="#trigger">trigger</a> &nbsp; <!-- generate a FHEM event -->
      <a href="#usb">usb</a> &nbsp;         <!-- discover USB devices -->

  </ul>

  <br>
  <b>Devices</b>
  <ul>
      <a href="#global">global</a><br>
      <!-- header:device -->

  </ul>

  <br>
  <b>Helper modules</b>
  <ul>
      <!-- header:helper -->
    <a href="#CustomReadings">CustomReadings</a> &nbsp;
    <a href="#DOIF">DOIF</a> &nbsp;
    <a href="#Dashboard">Dashboard</a> &nbsp;
    <a href="#dewpoint">dewpoint</a> &nbsp;
    <a href="#FLOORPLAN">FLOORPLAN</a> &nbsp;
    <a href="#HCS">HCS</a> &nbsp;
    <a href="#Heating_Control">Heating_Control</a> &nbsp;
    <a href="#HMinfo">HMinfo</a> &nbsp;
    <a href="#HourCounter">HourCounter</a> &nbsp;    
    <a href="#MaxScanner">MaxScanner</a> &nbsp;     
    <a href="#PachLog">PachLog</a> &nbsp;
    <a href="#RandomTimer">RandomTimer</a> &nbsp;
    <a href="#rain">rain</a> &nbsp;
    <a href="#remotecontrol">remotecontrol</a> &nbsp;
    <a href="#statistics">statistics</a> &nbsp;
    <a href="#Twilight">Twilight</a> &nbsp;
    <a href="#THRESHOLD">THRESHOLD</a> &nbsp;
    <a href="#WeekdayTimer">WeekdayTimer</a> &nbsp;
    <a href="#WOL">WOL</a> &nbsp;
      <!-- header end -->
  </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://&lt;fhemhost&gt;: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 &lt;fhemhost&gt; 7072<br>
    &lt;NL&gt; </code>(This newline switches into "prompt" mode)<code><br>
    &lt;command&gt;...<br>
    quit</code><br>
</ul>
    or
<ul>
    <code>fhem.pl &lt;fhemhost&gt;:7072 "&lt;fhem-command&gt" "..."</code>
</ul>
</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>
<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.</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 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
&lt;attributelist&gt;</code><p> for the <a href="#global">global</a> device to
declare new global attributes and <p><code>attr &lt;devicespec&gt; userattr
&lt;attributelist&gt;</code><p> for individual devices according to <a
href="#devspec">devspec</a> to declare new local attributes. 

<code>&lt;attributelist&gt;</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
&lt;attributelist&gt;</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.
        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="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><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 enclused in {}, then it is evaluated. This attribute is
    evaluated each time a reading is updated.
    </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 timestamps of the listed readings will
    not be changed if event-on-change-reading is also set and it would not create
    an event for this reading.
    </li>
    <p>

    <a name="event-aggregator"></a>
    <li>event-aggregator</li>
    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 function 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.
    </li>
    <p>

    <a name="userReadings"></a>
    <li>userReadings<br>
      A comma-separated list of definitions of user-defined readings. Each
      definition has the form:
      <ul>
      <code>
      &lt;reading&gt;[:&lt;trigger&gt;] [&lt;modifier&gt;] { &lt;perl code&gt; }
      </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> { &lt;perl code&gt;
      }</code> for all definitions and setting the value of the respective
      user-defined reading <code>&lt;reading&gt;</code> to the result. If
      &lt;trigger&gt; is given, then all processing for this specific user
      reading is only done if one of the just updated "reading: value"
      combinations matches &lt;trigger&gt;, 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>&lt;modifier&gt;</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>
    <li>Special: attribute disable can be toggled<br/>
        Attribute "disable" can be toggled by issuing the following command:<br/>
        <br/>
        <code>attr &lt;device&gt; disable toggle</code><br/>
        <br/>
        Attribute "disable" must be offered by the corresponding module</li>
</ul>
<!-- attributes end - diese Zeile nicht entfernen! -->


<br><br>
<a name="commands"></a>
<a name="attr"></a>
<h3>attr</h3>
<ul>
  <code>attr &lt;devspec&gt; &lt;attrname&gt; [&lt;value&gt;] </code><br>

  <br>Set an attribute for a device defined by <a href="#define">define</a>.
  You can define your own <a href="#attributes">attributes</a> too to use them
  in other applications.

  Use "attr &lt;name&gt; ?" to get a list of possible attributes.
  See the <a href="#devspec">Device specification</a> section for details on
  &lt;devspec&gt;.
  After setting the attribute, the global event "ATTR" will be generated.
  <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="cancel"></a>
<h3>cancel</h3>
<ul>
  <code>cancel [&lt;id&gt; [quiet]]</code>
  <br><br>
  Cancels a named <a href="#sleep">sleep</a>.

</ul>

<a name="define"></a>
<h3>define</h3>
<ul>
  <code>define [option] &lt;name&gt; &lt;type&gt; &lt;type-specific&gt;</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>
  </ul>

</ul>

<a name="defmod"></a>
<h3>defmod</h3>
<ul>
  <code>defmod &lt;name&gt; &lt;type&gt; &lt;type-specific&gt;</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>
</ul>


<a name="delete"></a>
<h3>delete</h3>
<ul>
  <code>delete &lt;devspec&gt;</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
  &lt;devspec&gt;.<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 &lt;devspec&gt; [&lt;attrname&gt;]</code> <br>
  <br>
  Delete either a single attribute (see the <a href="#attr">attr</a> command)
  or all attributes for a device (if no &lt;attrname&gt; is defined).
  See the <a href="#devspec">Device specification</a> section for details on
  &lt;devspec&gt;.<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>

<a name="deletereading"></a>
<h3>deletereading</h3>
<ul>
  <code>deletereading &lt;devspec&gt; &lt;readingname&gt;</code> <br>
  <br>
  Delete the reading &lt;readingname&gt; 
  for a device. &lt;readingname&gt; 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
  &lt;devspec&gt;.<br>
  <br>

  Examples:
  <ul>
    <code>deletereading mySensor temp1</code><br>
    <code>deletereading mySensor temp\d+</code><br>
  </ul>
  <br>
</ul>

<a name="displayattr"></a>
<h3>displayattr</h3>
<ul>
  <code>displayattr &lt;devspec&gt; [&lt;attrname&gt;]</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 &lt;attrname&gt; is defined).
  See the <a href="#devspec">Device specification</a> section for details on
  &lt;devspec&gt;.<br>
  If more then one device is specified, then the device name will also included
  in the output.
  <br>

  Examples:
  <ul>
    <code>
    fhem&gt; di WEB<br>
    menuEntries AlarmOn,/fhem?cmd=set%20alarm%20on<br>
    room Misc.<br>
    fhem&gt di WEB room<br>
    Misc.<br>
    </code>
  </ul>
  <br>
</ul>

<a name="get"></a>
<h3>get</h3>
<ul>
  <code>get &lt;devspec&gt; &lt;type-specific&gt;</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 &lt;device&gt; ?</code>
  </ul>
  See the <a href="#devspec">Device specification</a> section for details on
  &lt;devspec&gt;.<br>
  <br>
  Each device has different get parameters, see the corresponding device
  section for details.<br>
  <br>

</ul>


<a name="include"></a>
<h3>include</h3>
<ul>
  <code>include &lt;filename&gt;</code> <br>
  <br>
  Read in the file, and process every line as a FHEM command. 
  Note: only experts should use this command.
  <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>
  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
  &lt;devspec&gt;.
  <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>
  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>

<a name="modify"></a>
<h3>modify</h3>
<ul>
  <code>modify &lt;name&gt; &lt;type-dependent-options&gt;</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><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 &lt;module&gt;</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 &lt;oldname&gt; &lt;newname&gt;</code>
  <br><br>
  Rename a device from the &lt;oldname&gt; to &lt;newname&gt;, 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 [&lt;configfile&gt;]</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 &lt;devspec&gt; &lt;type-specific&gt;</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 &lt;name&gt; ?</code>
  </ul>
  See the <a href="#devspec">Device specification</a> section for details on
  &lt;devspec&gt;. 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:reading] with the corresponding reading of device, if both device
    and reading exists.</li>
  <li>[device:reading:d] same as above, but only the number is retrieved, see
     ReadingsNum </li>
  <li>{(perlExpression)} with the result of perlExpression.
    The $DEV variable is additionally available, designating the set device
    name.
    </li>
  </ul>
  <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 &lt;seconds&gt<br>
        Issue the on command for the device, and after &lt;seconds&gt; 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 &lt;seconds&gt<br>
        see on-for-timer above.</li>
    <li>on-till &lt;timedet&gt<br>
        Issue the on command for the device, and create an at definition with
        &lt;timedet&gt; (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 &lt;timedet&gt<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 &lt;timedet&gt<br>
        see on-till above.</li>
    <li>off-till-overnight &lt;timedet&gt<br>
        see on-till-overnight above.</li>
    <li>blink &lt;number&gt; &lt;blink-period&gt;<br>
        set the device on for &lt;blink-period&gt; then off for
        &lt;blink-period&gt; and repeat this &lt;number&gt; times.
        To stop blinking specify "0 0" as argument.</li>
    <li>intervals &lt;from1&gt;-&lt;till1&gt; &lt;from2&gt;-&lt;till2&gt;...
        </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="setdefaultattr"></a>
<h3>setdefaultattr</h3>
<ul>
  <code>setdefaultattr [&lt;attrname&gt; [&lt;value&gt;]] </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="setreading"></a>
<h3>setreading</h3>
<ul>
  <code>setreading &lt;devspec&gt; &lt;reading&gt; &lt;value&gt;</code>
  <br><br>
  Set the reading &lt;reading&gt; for the device <code>&lt;name&gt;</code> to
  &lt;value&gt; 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><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>

<a name="setstate"></a>
<h3>setstate</h3>
<ul>
  <code>setstate &lt;devspec&gt; &lt;value&gt;</code>
  <br><br>
  Set the STATE entry for the device specified by <code>&lt;devspec&gt;</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
  &lt;devspec&gt;.
  <br><br>
  Examples:
  <ul>
    setstate lamp on
  </ul>
</ul>

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

<a name="sleep"></a>
<h3>sleep</h3>
<ul>
  <code>sleep &lt;sec&gt; [&lt;id&gt;] [quiet]</code>
  <br><br>
  sleep followed by another command is comparable to a nameless <a
  href="#at">at</a>, it executes the following commands after waiting the
  specified time. The unit is seconds, with millisecond accuracy, as you can
  specify decimal places.<br><br>

  A sleep with an &lt;id&lt; will replace a sleep with the same &lt;id&lt;
  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>

<a name="trigger"></a>
<h3>trigger</h3>
<ul>
  <code>trigger &lt;devspec&gt; &lt;state&gt;</code>
  <br><br>
  Trigger a <a href="#notify">notify</a> definition.
  See the <a href="#devspec">Device specification</a> section for details on
  &lt;devspec&gt;.

  <br><br>
  Example:
  <ul>
    <code>trigger btn3 on</code>
  </ul>
</ul>

<!-- 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>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="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.
    </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.
    </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" (default), then a full commandref will be generated
        after each update. If set to modular, there is only a short description
        at the beginning, and the module documentation is loaded from FHEM
        dynamically.
    </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="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="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="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="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_&lt;NAME&gt;.pm, and make them available for device definition under
        &lt;NAME&gt;. If the first device of type &lt;NAME&gt; is defined, the
        module will be loaded, and its function with the name
        &lt;NAME&gt;_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.  motd is also used to show
        collected error messages upon FHEM start.
    </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 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><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>

    <li><a href="#fheminfo">uniqueID</a><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 additinal 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 &lt;devname&gt;<br>after a device is defined.</li>
    <li>DELETED &lt;devname&gt;<br>after a device was deleted.</li>
    <li>RENAMED &lt;old&gt; &lt;new&gt;<br>after a device was renamed.</li>
    <li>UNDEFINED &lt;defspec&gt;<br>upon reception of a message for an
    undefined device.</li>
    <li>MODIFIED &lt;defspec&gt;</br> after a device modification.</li>
    <li>UPDATE</br> after an update is completed.</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>
    <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).
    Additionally the variable $hms contains the time in the HH:MM:SS 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 &gt; 18 || $hour &lt; 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(&lt;devicename&gt;)<br>
        returns the state of the device (the string you see in paranthesis in
        the output of the list command).
        </li><br>
      <li>OldValue(&lt;devicename&gt;)
      <li>OldTimestamp(&lt;devicename&gt;)<br>
        returns the old value/timestamp of the device.
        </li><br>
      <li>
        ReadingsVal(&lt;devicename&gt;,&lt;reading&gt;,&lt;defaultvalue&gt;)<br>
        Return the reading (the value in the Readings section of "list device")
        </li><br>
      <li>
        ReadingsNum(&lt;devicename&gt;,&lt;reading&gt;,&lt;defaultvalue&gt;)<br>
        Return the reading as a number, i.e. delete non-numerical values.
        </li><br>
      <li>
        AttrVal(&lt;devicename&gt;,&lt;attribute&gt;,&lt;defaultvalue&gt;)<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>
        </li><br>
      <li>
        InternalVal(&lt;devicename&gt;,&lt;property&gt;,&lt;defaultvalue&gt;)
        <br>
        Return the internal value (the value in the Internals section of "list
        device").
        </li><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>
<!-- perl end - diese Zeile nicht entfernen! -->

<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 &lt;SIZE&gt;
  #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 &lt;SIZE&gt;, which is replaced by the <a
        href="#plotsize">plotsize</a> attribute of the FHEMWEB or weblink
        instance.</li>

    <li>title<br>
        Usually set to &lt;TL&gt; which is replace by the weblink <a
        href="#title">title</a> attribute, or to &lt;Lx&gt;, 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 &lt;linetype&gt;<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 &lt;linestyle&gt;<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 &lt;linewidth&gt;<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>