FHEM reference

    attr global logfile log/fhem.log
    attr global modpath .
    attr global statefile log/fhem.save
    define telnetPort telnet 7072 global
    define WEB FHEMWEB 8083 global

http://<fhemhost>:8083

telnet <fhemhost> 7072

    <NL>



    <command>...

    quit

fhem.pl <fhemhost>:7072 "<fhem-command>" "..."

FHEM command types

notify

Perl special

Notes

notify

define onAt at 07:00 set Lamp1 on;;set Lamp2 on;; define offAt at +00:10 set Lamp1 off;;;;set Lamp2 off

define onAt at 07:00 set Lamp1,Lamp2 on-for-timer 600

notify

Device specification (devspec)

a single device name. This is the most common case.
a list of devices, separated by comma (,)
a regular expression
a NAME=VALUE pair, where NAME can be an internal value like TYPE, a Reading-Name or an attribute. VALUE is a regexp. To negate the comparison, use NAME!=VALUE. 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 !~.
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.

set lamp1 on

set lamp1,lamp2,lamp3 on

set lamp.* on

set room=kitchen off

set room=kitchen:FILTER=STATE=on off

set room=kitchen:FILTER=STATE!=off off

list disabled=

list room~office

list TYPE=FS20 STATE

list i:TYPE=FS20 STATE

the spec may not contain space characters.
if there is a device which exactly corresponds to the spec, then no special processing is done.
first the spec is separated by comma, then the regular expression and filter operations are executed.
the returned list can contain the same device more than once, so "set lamp3,lamp3 on" switches lamp3 twice.
for more complex structuring demands see the structure device.

Attributes

All devices have attributes. These can be set by means of the attr command, displayed with the displayattr command, and deleted by the deleteattr command.

There are global attributes that are used by all devices and local attributes that apply to individual device classes only.

Some devices (like FHEMWEB) automatically define new global attributes on the first definition of a device of such type.

You can use the command

attr global userattr <attributelist>

for the global device to declare new global attributes and

attr <devicespec> userattr <attributelist>

for individual devices according to devspec to declare new local attributes. <attributelist> is a space-separated list which contains the names of the additional attributes. See the documentation of the attr command for examples.

Be careful not to overwrite additional global attributes previously defined by yourself or a device. Use the attr global userattr <attributelist> as early in your configuration as possible.

Device specific attributes

Device specific attributes are documented in the corresponding device section.

Global attributes used by all devices

alias
Used by FHEMWEB to display a device with another name e.g. when using special characters/spaces not accepted by device definition.

comment
Add an arbitrary comment.

eventMap
Replace event names and set arguments. The value of this attribute consists of a list of space separated values, each value is a colon separated pair. The first part specifies the "old" value, the second the new/desired value. If the first character is slash(/) or comma(,) then split not by space but by this character, enabling to embed spaces. 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:
The explicit variant of this attribute has the following syntax:
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.

genericDisplayType
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

group
Group devices. Recognized by web-pgm2 (module FHEMWEB), it makes devices in the same group appear in the same box). This is used to further group devices together. A device can appear in more than one group, in this case the groups have to be specified comma-separated.
If this attribute is not set then the device type is used as the grouping attribute.

room
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.
Devices in the room hidden will not appear in the web output, or set the FHEMWEB attribute hiddenroom to selectively disable rooms for certain FHEMWEB instances. The -> string is considered as a structure separator for rooms, e.g. "1st. floor->Master bedroom".

suppressReading
Used to eliminate unwanted readings. The value is a regular expression, with ^ and $ added. Only necessary in exceptional cases.

showtime
Used in the webfrontend pgm2 to show the time of last activity instead of the state in the summary view. Useful e.g. for FS20 PIRI devices.

verbose
Set the verbosity level. Possible values:
- 0 - server start/stop
- 1 - error messages or unknown packets
- 2 - major events/alarms.
- 3 - commands sent out will be logged.
- 4 - you'll see whats received by the different devices.
- 5 - debugging.
The value for the global device is a default for other devices without own verbose attribute set.

readingFnAttributes

The following global attributes are honored by the modules that make use of the standardized readings updating mechanism in fhem.pl. Check the module's attribute list if you want to know if a device supports these attributes.

stateFormat
Modifies the STATE of the device, shown by the list command or in the room overview in FHEMWEB. If not set, its value is taken from the state reading. If set, then every word in the argument is replaced by the value of the reading if such a reading for the current device exists. If the value of this attribute is enclosed in {}, then it is evaluated. This attribute is evaluated each time a reading is updated.
The "set magic" described here is also applied.
Note: some FHEM modules are setting STATE directly (against the guidelines), in this case the attribute may not work as expected.

event-on-update-reading
If not set, every update of any reading creates an event, which e.g. is handled by notify or FileLog. The attribute takes a comma-separated list of readings. You may use regular expressions in that list. If set, only updates of the listed readings create events.

event-on-change-reading
The attribute takes a comma-separated list of readings. You may use regular expressions in that list. If set, only changes of the listed readings create events. In other words, if a reading listed here is updated with the new value identical to the old value, no event is created. If an optional [:threshold] is given after a reading name events are only generated if the change is >= threshold.

If both attributes are not set, any update of any reading of the device creates an event.
If any of the attributes is set, no events occur for updates or changes of readings not listed in any of the attributes.
If a reading is listed in event-on-update-reading, an update of the reading creates an event no matter whether the reading is also listed in event-on-change-reading.

timestamp-on-change-reading
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.

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.

This attribute takes a comma-separated list of reading:interval:method:function:holdTime quintuples. You may use regular expressions for reading. If set, updates for the listed readings are ignored and associated events are suppressed for a black-out period of at least interval 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:

function	description
v	the last value encountered
v0	the first value encountered
min	the smallest value encountered
max	the largest value encountered
mean	the arithmetic mean of all values
sd	the standard deviation from the mean
median	the median of all values (requires holdTime and method none)
integral	the arithmetic sum (if not time-weighted) or integral area (if time-weighted) of all values
n	number of samples
t	timestamp of the last value
t0	timestamp of the first value

If method is none, then that's all there is. If method is const or linear, the time-weighted series of values is taken into account instead. The weight is the timespan between two subsequent updates. With the const method, the value is the value of the reading at the beginning of the timespan; with the linear 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.

One would typically use the linear method with the mean 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 none method with the v function is used. The constant method is for discrete quantities that stay constant until the corresponding reading is updated, e.g. counters, switches and the like.

If the holdTime in seconds is defined, the samples will be kept in memory allowing the calculation of floating statistics instead of blocked statistics. With holdTime defined the interval can be kept undefined so that the readings update rate is unchanged or it can be set to a value less then holdTime 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.

The event aggregator only takes into consideration those updates that remain after preprocessing according to the event-on-update-reading and event-on-change-reading 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.

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.

Examples:
attr myPowerMeter event-aggregator EP_POWER_METER:300:linear:mean,EP_ENERGY_METER:300:none:v
attr myBadSensor event-aggregator TEMP::none:median:300
attr mySunMeter event-aggregator SUN_INTENSITY_24H::const:integral:86400

event-min-interval
This attribute takes a comma-separated list of reading:minInterval pairs. You may use regular expressions for reading. Events will only be generated, if at least minInterval seconds elapsed since the last reading of the matched type. If event-on-change-reading is also specified, they are combined with OR: if one of them is true, the event is generated.

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

userReadings
A comma-separated list of definitions of user-defined readings. Each definition has the form:
After a single or bulk readings update, the user-defined readings are set by evaluating the perl code{ <perl code> } for all definitions and setting the value of the respective user-defined reading <reading> to the result. If <trigger> is given, then all processing for this specific user reading is only done if one of the just updated "reading: value" combinations matches <trigger>, which is treated as a regexp.
Examples:
<modifier> can take one of these values:
- none: the same as it would not have been given at all.
- difference: the reading is set to the difference between the current and the previously evaluated value.
- differential: the reading is set to the difference between the current and the previously evaluated value divided by the time in seconds between the current and the previous evaluation. Granularity of time is one second. No value is calculated if the time past is below one second. Useful to calculate rates.
- integral: reverse function of differential. The result is incremented by the product of the time difference between the last two readings and the avarage of the last two readings.
  result += (time - timeold) * (oldval + value) / 2
- offset: if the current evaluated value is smaler than the previously evaluated value the reading is incremented by the previous value. the reading can then be used as an offset correct for a counter that is reset for example due to a power loss.
- monotonic: if the difference between the current and the previously evaluated value is positive the reading is incremented by this difference. this allows to derive a monotonic growing counter from an original counter even if the original will be rest by a power loss
Example:
Notes:
- user readings with modifiers difference and differential store the calculated values internally. The user reading is set earliest at the second evaluation. Beware of stale values when changing definitions!
- the name of the defined Readings consists of alphanumeric characters with underscore (_) and the minus (-) sign.

Common attributes

The following local attributes are used by a wider range of devices:

IODev
Set the IO or physical device which should be used for sending signals for this "logical" device. An example for the physical device is an FHZ or a CUL. Note: Upon startup FHEM assigns each logical device (FS20/HMS/KS300/etc) the last physical device which can receive data for this type of device. The attribute IODev needs to be used only if you attached more than one physical device capable of receiving signals for this logical device.

disable
Disables the corresponding device. Note: it can be toggled by issuing the following command:

attr <device> disable toggle

disabledForIntervals HH:MM-HH:MM HH:MM-HH:MM ...
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.:
If parts of the attribute value are enclosed in {}, they are evaluated:

attr

attr [-a|-r|-silent] <devspec> <attrname> [<value>]

define

attributes

Device specification


    attr global verbose 3

    attr lamp room kitchen

    attr lamp group lights

    attr lamp loglevel 6

    attr weatherstation event-on-update-reading wind,temperature,humidity

    attr weatherstation event-on-change-reading israining

    attr weatherstation event-on-change-reading israining,state

    attr heating stateFormat Temp:measured-temp, Valve:actuator

    attr -a TYPE=SVG room ,SvgRoom

    attr -r TYPE=SVG room ,SvgRoom

See deleteattr to delete attributes.

cancel

cancel [<id> [quiet]]

sleep

define

define [option] <name> <type> <type-specific>

-temporary
Add the TEMPORARY flag to the definition, which will prevent saving the device to fhem.cfg.

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

-silent
Do no enter the command in the "save ?" list.

defmod

defmod [option] <name> <type> <type-specific>


    define mdNtfy notify motionDetector defmod mdOff at +00:10 set lamp off

delete

delete <devspec>

define

Device specification

delete lamp

deleteattr

deleteattr [-silent] <devspec> [<attrname>]

attr

Device specification

deleteattr lamp follow-on-for-timer

deleteattr lamp

deletereading

deletereading <devspec> <readingname>
        [<older-than-seconds>]

Device specification

deletereading mySensor temp1

deletereading mySensor temp\d+

displayattr

displayattr <devspec> [<attrname>]

attr

Device specification


    fhem> di WEB

    menuEntries AlarmOn,/fhem?cmd=set%20alarm%20on

    room Misc.

    fhem> di WEB room

    Misc.

get

get <devspec> <type-specific>

get <device> ?

Device specification

include

include <filename>

inform

inform {on|onWithState|off|raw|timer|log|status} [regexp]

on
switch the inform mechanism on
onWithState
show the additional state event too
off
switch the inform mechanism off (both events and logs, see below)
raw
show only raw events from physical devices
timer
prepend a timestamp to each event
log
show messages written by the FHEM Log interface
status
show the current status

list

list [devspec] [value ...]

list {-r|-R} devspec

Device specification

  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)

name

  fhem> list fl

  Internals:
    CODE       5102
    DEF        5102
    NAME       fl
    NR         15
    STATE      measured-temp: 21.1 (Celsius)
    TYPE       FHT
    IODev      FHZ
  Attributes:
    room       Heizung
  Readings:
    2006-11-02 09:45:56   actuator        19%
    [...]

modify

modify [-silent] <name> <type-dependent-options>

notify

define lampon at 19:00 set lamp on

modify lampon *19:00

modify lampon 19:00 set lamp on-for-timer 16

quit

quit

reload

reload <module>

reload 99_PRIV

rename

rename <oldname> <newname>

rename FHT_1234 fht.kitchen

rereadcfg

rereadcfg [fhem-config-file]

statefile

rereadcfg

save

save [<configfile>]

statefile

configfile

save only writes out definitions and attributes, but no (set/get) commands which were previously part of the config file. If you need such commands after the initialization (e.g. FHTcode), you should trigger them via notify, when receiving the INITIALIZED event.
save tries to preserve comments (lines starting with #) and include structures, but it won't work correctly if some of these files are not writeable.
before overwriting the files, the old version will be saved, see the restoreDirs global attribute for details.

set

set <devspec> <type-specific>

set <name> ?

Device specification

[device:name] with the reading, internal or attribute of the device, if both device and the reading, internal or attribute exists.
- You can use the r:, i: or a: prefix to restrict the search to one type, analogue to the devspec filtering.
- The suffix :d retrieves the first number
- The suffix :i retrieves the integer part of the first number.
- 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.
- The suffix :t returns the timestamp (works only for readings)
- The suffix :sec returns the number of seconds since the reading was set.
Example:
[device:name:d] same as above, but only the number is retrieved
[device:name:sec] same as above, but only the number is retrieved
{(perlExpression)} with the result of perlExpression. The $DEV variable is additionally available, designating the set device name.

set extensions

on-for-timer <seconds>
Issue the on command for the device, and after <seconds> the off command. For issuing the off command an internal timer will be scheduled, which is deleted upon a restart. To delete this internal timer without restart specify 0 as argument.
off-for-timer <seconds>
see on-for-timer above.
on-till <timedet>
Issue the on command for the device, and create an at definition with <timedet> (in the form HH:MM[:SS]) to set it off. This definition is visible, and its name is deviceName+"_till". To cancel the scheduled off, delete the at definition. Note: on-till is not active, if the specified time is after the current time, in order to make things like
easy.
on-till-overnight <timedet>
Like on-till, but wont compare the current time with the timespec, so following will work:
off-till <timedet>
see on-till above.
off-till-overnight <timedet>
see on-till-overnight above.
blink <number> <blink-period>
set the device on for <blink-period> then off for <blink-period> and repeat this <number> times. To stop blinking specify "0 0" as argument.
intervals <from1>-<till1> <from2>-<till2>...
set the device on for the specified intervals, which are all timespecs in the form HH:MM[:SS]. The intervals are space separated.
toggle
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.


    set switch on-for-timer 12.5

    set switch on-till {sunset()}

    set switch blink 3 1

    set switch intervals 08:00-12:00 13:00-18:00

setdefaultattr

setdefaultattr [<attrname> [<value>]]

setdefaultattr room kitchen

setdefaultattr loglevel 4

define lamp1 FS20 1234 11

define lamp2 FS20 1234 12

define lamp3 FS20 1234 13

setdefaultattr

There is no way to delete a single default-attribute from the list

setreading

setreading <devspec> [YYYY-MM-DD HH:MM:SS] <reading>
        <value>

<name>

setreading lamp state on

setstate

setstate <devspec> <value>

<devspec>

statefile

Device specification

setstate lamp on

setuuid

setuuid <device> <uuid>

show

show <devspec>

Device specification

show TYPE=CUL_HM

shutdown

shutdown [restart|exitValue]

state information

shutdown

shutdown restart

shutdown 1

sleep

sleep <sec|timespec|regex> [<id>] [quiet]

notify

in seconds, with millisecond accuracy, as you can specify decimal places,
as a timespec (HH:MM or HH:MM:SS or {perlfunc})
or as a regex (devicename or devicename:event)

cancel

trigger

trigger <devspec> <state>

notify

Device specification

trigger btn3 on

global

Define

N/A

Set

N/A

Get

N/A

Internals

init_errors
contains configuration errors and security issues collected at FHEM startup.

Attributes

altitude
Specifies the mean sea level in meters. Default is 0.

archivedir
archivecmd
nrarchive

archivesort
archivesort may be set to the (default) alphanum or timestamp, and specifies how the last files are computed for the nrarchive attribute.

autoload_undefined_devices
If set, automatically load the corresponding module when a message of this type is received. This is used by the autocreate device, to automatically create a FHEM device upon receiving a corresponding message.

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

backupcmd
You could pass the backup to your own command / script by using this attribute. If this attribute is specified, then it will be started as a shell command and passes a space separated list of files / directories as one argument to the command, like e.g.:
Note: Your command / script has to return the string "backup done" or everything else to report errors, to work properly with update!
This Attribute is used by the backup command.
Example:

backupdir
A folder to store the compressed backup file. This Attribute is used by the backup command.
Example:

backupsymlink
If this attribute is set to everything else as "no", the archive command tar will support symlinks in your backup. Otherwise, if this attribute is set to "no" symlinks are ignored by tar. This Attribute is used by the backup command.
Example:

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

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

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

disableFeatures
comma separated list of values. Currently following values are recognized:
- attrTemplate: to avoid loading the AttrTemplates (which currently consumes about 1MB of memory and needs some seconds to load on a slow hardware)
- securityCheck: to avoid checking if each Server port is secured by password. May make sense to avoid warnings, if you know it better.

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

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

encoding
Set the internal encoding used for storing strings. Possible values: bytestream (default) and unicode.
Notes:
- Since not all modules were checked, if they work correctly with the internal unicode encoding, this feature is experimental.
- Changing the attribute value triggers a save and a shutdown restart

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

holiday2we
If this attribute is set, then the $we variable will be true, if it is either saturday/sunday, or the value of the holiday variable referenced by this attribute is not none.
If it is a comma separated list, then it is true, if one of the referenced entities is not none.
Example:
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.

httpcompress
the HttpUtils module is used by a lot of FHEM modules, and enables compression by default. Set httpcompress to 0 to disable this feature.

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

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

latitude
Used e.g. by SUNRISE_EL to calculate sunset/sunrise.
Default is Frankfurt am Main, Germany (50.112).

longitude
Used e.g. by SUNRISE_EL to calculate sunset/sunrise.
Default is Frankfurt am Main, Germany (8.686).

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

logfile
Specify the logfile to write. You can use "-" for stdout, in this case the server won't background itself.
The logfile name can also take wildcards for easier logfile rotation, see the FileLog section. Just apply the archivecmd / archivedir / nrarchive attributes to the global device as you would do for a FileLog device.
You can access the current name of the logfile with { $currlogfile }.

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

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

modpath
Specify the path to the modules directory FHEM. The path does not contain the directory FHEM. Upon setting the attribute, the directory will be scanned for filenames of the form NN_<NAME>.pm, and make them available for device definition under <NAME>. If the first device of type <NAME> is defined, the module will be loaded, and its function with the name <NAME>_Initialize will be called. Exception to this rule are modules with NN=99, these are considered to be utility modules containing only perl helper functions, they are loaded at startup (i.e. modpath attribute definition time).

motd
Message Of The Day. Displayed on the homescreen of the FHEMWEB package, or directly after the telnet logon, before displaying the fhem> prompt. In addition, the content of the internal value init_errors will be displayed. To avoid displaying messages set its value to none.

mseclog
If set, the timestamp in the logfile will contain a millisecond part.

nofork
If set and the logfile is not "-", do not try to background. Needed on some Fritzbox installations, and it will be set automatically for Windows.

perlSyntaxCheck
by setting the global attribute perlSyntaxCheck, a syntax check will be executed upon definition or modification, if the command is perl and FHEM is already started.

pidfilename
Write the process id of the perl process to the specified file. The server runs as a daemon, and some distributions would like to check by the pid if we are still running. The file will be deleted upon shutdown.

proxy
IP:PORT of the proxy server to be used by HttpUtils.

proxyAuth
Base64 encoded username:password

proxyExclude
regexp for hosts to exclude when using a proxy

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

If the attribute is set to 0, the feature is deactivated.

sendStatistics
statefile
Set the filename where the state and certain at information will be saved before shutdown. If it is not specified, then no information will be saved.

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

userattr
A space separated list which contains the names of additional attributes for all devices. Without specifying them you will not be able to set them (in order to prevent typos).
userattr can also specified for other devices, in this case these additional attribute names are only valid for this device.

dupTimeout
Define the timeout for which 2 identical events from two different receiver are considered a duplicate. Default is 0.5 seconds.

showInternalValues
Show data used for internal computations. If the name of an internal value, reading or attribute starts with dot (.), then it is normally hidden, and will only be visible, if this attribute is set to 1. The attribute is checked by the list command, by the FHEMWEB room overview and by xmllist.

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

stacktrace
if set (to 1), dump a stacktrace to the log for each "PERL WARNING".

restartDelay
set the delay for shutdown restart, default is 2 (seconds).

Events:

INITIALIZED
after initialization is finished.
REREADCFG
after the configuration is reread.
SAVE
before the configuration is saved.
SHUTDOWN
before FHEM is shut down.
DEFINED <devname>
after a device is defined.
DELETED <devname>
after a device was deleted.
RENAMED <old> <new>
after a device was renamed.
UNDEFINED <defspec>
upon reception of a message for an undefined device.
MODIFIED <defspec>
after a device modification.
UPDATE
after an update is completed.
CANNOT_FORK
if BlockingCall encounters this problem.

Perl specials

If you want to automate some tasks via FHEM, then you'll probably use at or notify. For more complex tasks you'll use either a shell-script or a perl "oneliner" as the at/notify argument. This chapter gives some tips in using the perl oneliners.

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

Perl expressions are separated by ;, in FHEM oneliners they have to escaped with ;;

{ my $a = 1+1;; Log 1, "Hello $a" }

To use FHEM commands from the perl expression, use the function fhem(), which takes a string argument, this string will be evaluated as a FHEM command:

Note: if this function returns a value, it will also be logged into the global FHEM log. Use 1 as a second argument to disable this logging, this makes sense when obtainig some values via FHEM "get...".

Notify can be used to store macros for manual execution. Use the trigger command to execute the macro:

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.
Additionally the variabe $we is 1 if it is weekend (i.e $wday == 0 or $wday == 6), and 0 otherwise. If the holida2we global attribute is set, $we is 1 for holidays too.

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

All helper functions defined in 99_Utils.pm

To access the device states/attributes, use the following functions:

Value(<devicename>)
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.

OldValue(<devicename>)
OldTimestamp(<devicename>)
Returns the old value/timestamp of the device.

ReadingsVal(<devicename>,<reading>,<defaultvalue>)
Returns the reading (the value in the Readings section of "list device")

ReadingsNum(<devicename>,<reading>, <defaultvalue>,<round>)
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.

ReadingsTimestamp(<devicename>,<reading>,< defaultvalue>)
Returns the timestamp of a reading.

ReadingsAge(<devicename>,<reading>,<defaultvalue>)
Returns the age of a reading in seconds.

OldReadingsVal(<devicename>,<reading>, <defaultvalue>)
OldReadingsNum(<devicename>,<reading>, <defaultvalue>,<round>)
OldReadingsTimestamp(<devicename>,< reading>,<defaultvalue>)
OldReadingsAge(<devicename>,<reading>, <defaultvalue>)
similar to the above functions, but used to access the previous values. see: oldreadings

AttrVal(<devicename>,<attribute>,<defaultvalue>)
Returns the attribute of a device

{ Value("wz") }
{ OldValue("wz") }
{ time_str2num(OldTimestamp("wz")) }
{ ReadingsVal("wz", "measured-temp", "20")+0 }
{ ReadingsTimestamp("wz", "measured-temp", 0)}
{ AttrVal("wz", "room", "none") }

AttrNum(<devicename>,<attribute>, <defaultvalue>,<round>)
Return the first number from an attribute value. Round id to <round> devimal places (optional parameter).

InternalVal(<devicename>,<property>,<defaultvalue>)
Return the internal value (the value in the Internals section of "list device").

InternalNum(<devicename>,<property>, <defaultvalue>,<round>)
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.

By using the 99_SUNRISE_EL.pm module, you have access to the following functions:

offset is in seconds, and the format of min/max is "HH:MM" or "HH:MM:SS". isday returns 1 if the sun is visible, and 0 else.

gnuplot file syntax

The .gplot files are also used by the FHEMWEB/SVG module when the plotmode attribute is set to SVG. In this case only a subset of the .gnuplot attributes are used, and some lines have special meanings: the difference will be explained in this chapter. See also this FHEM Wiki entry on creating logs.
Following is a minimal .gplot definition (valid only for plotmode SVG):

  set terminal size <SIZE>
  #FileLog 4:::
  plot title 'Temperature' with lines

The .gnuplot file consists of 3 parts:

set commands
Following sets are recognized:
- terminal, only the size parameter.
  This is usually set to <SIZE>, which is replaced by the plotsize attribute of the FHEMWEB or weblink instance.
- title
  Usually set to <TL> which is replace by the weblink title attribute, or to <Lx>, which is replaced by the weblink label attribute.
- ylabel,y2label
  Left and right labels, printed vertically. Are also subject to label replacement.
- yrange,y2range
  Specify the range of the left and right axis. Examples:
- ytics,y2tics
  the label for the left/right axis tics. Examples:

#FileLog entries
Each line from the plot section must have one corresponding #FileLog line. For the syntax see the column_spec paragraph of the Filelog get description. Note that for SVG plots the first column of the input file always has to be in the standard fhem timestamp format (YYYY-MM-DD_HH:MM:SS)

plot entries
There is always one plot command with comma separated argument-blocks. Each argument-block represents one line, and has its own parameters. Following parameters are recognized:
- axes x1y1 / x1y2
  tells the program to assign the current line to one of the two axes (left or right).
- title
  Caption of the line. Whan clicking on this title, a small javascript program will change the title to the min/max and last values of the plot, will enable copying this line or pasting an already copied one (the existing scale of the plot wont'be changed, only the pasted line will be scaled), and other lines of the plot will temporarily be hidden.
- with <linetype>
  Specify the line type. Following types are recognized: points, steps, fsteps, histeps and lines. Everything unknown will be mapped to the type lines. SVG special: cubic and quadratic, are mapped to the SVG path types C, and Q respectively.
- ls <linestyle>
  The linestyle defaults to l0 for the first line, l1 for the second, and so on. It is defined in the svg_style.css file. There are two sets defined here: l0-l8 and l0fill-l6fill. The second set must be specified explicitly. If the name of the linestyle contains the word fill, then plots of the lineytype "lines" will have an additional starting and ending segment, so that filling is done correctly.
  See the SVG spec for details of this CSS file. Note: if you plan to use this attribute, you have to specify it for all the lines (attribute-blocks) in the plot command.
- lw <linewidth>
  Sets the stroke-width style of the line. This attribute is deprecated, the corresponding feature of the CSS file / (attribute ls) should be used instead.

fhem.pl reference

Contents

Introduction

FHEM command types

Device specification (devspec)

Attributes

Device specific attributes

Global attributes used by all devices

readingFnAttributes

Common attributes

attr

cancel

define

defmod

delete

deleteattr

deletereading

displayattr

get

include

inform

list

modify

quit

reload

rename

rereadcfg

save

set

setdefaultattr

setreading

setstate

setuuid

show

shutdown

sleep

trigger

global

Perl specials

gnuplot file syntax