fhem reference

FHEM wird hauptsächlich zur Heimautomatisierung benutzt, ist aber ebenso für andere Aufgaben einsetzbar wo Benachrichtigungen, Zeitschaltungen und Datensammlungen eine wichtige Rolle spielen.

FHEM unterstützt verschiedene Hardwaregeräte die eine Verbindung mittels unterschiedlicher Protokolle (z.B. FHZ1000 mit Interfaces vom Typ FS20 und HMS, CM11 um mit X10 zu arbeiten) sowie logischer Geräte wie FS20 oder FHT die einen Nachrichtenaustausch mit verschiedensten Geräten die diese Protokolle verwenden ermöglichen.

FHEM ist modular. Abhängig von den unterschiedlichen Geräten werden in den Modulen verschiedene Funktionen (z.B. define, get, set) realisiert. FHEM enthält weitere Funktionen wie Trigger (notify), Zeitabhängige Funktionen (at) die die Funktionalität erweitern.

FHEM wird entweder über einfache ASCII-Kommandozeilen gesteuert die in Dateien wie z.B. der Konfigurationsdatei fhem.cfg gespeichert sind oder über eine TCP/IP Verbindung, entweder direkt in einer „telnet“-Sitzung, oder per fhem.pl im Client-Modus oder über eines der Webfrontends.

Wenn Sie den FHEM-Server starten, müssen Sie eine Konfigurationsdatei auswählen:

fhem.pl ~/.fhem

Nachstehend eine Minimal-Konfiguration Datei:

    attr global logfile /tmp/fhem.log
    attr global statefile /tmp/fhem.save
    attr global verbose 3
    attr global port 7072
    attr global modpath /usr/share/fhem
    define FHZ FHZ /dev/tts/USB0

    define lamp FS20 8765 01

Beispiele für andere Konfigurationsdateien finden Sie im “examples“-Verzeichnis

Die Kommunikation mit FHEM kann entweder in einer “session” (über telnet) oder über einzelne Klient-Kommandos (über fhem.pl) erfolgen. Beispiel:

telnet localhost 7072

    <NL>



    <command>...

    quit

fhem.pl 7072 "set lamp off"

FHEM Befehlstypen

notify

Die folgenden drei Befehle bewirken z.B. dasselbe Ergebnis, wenn sie am “telnet”-Prompt eingegeben werden:

SHELL-Kommandos werden im Hintergrund ausgeführt, PERL-Ausdrücke und FHEM-Kommandos werden im Haupt-“thread” ausgeführt. Um PERL-Ausdrücke leichter eingeben zu können, sind einige Spezialfunktionen und Variablen verfügbar. Lesen Sie sich bitte die Abschnitte Perl special zum besseren Verständnis durch.

Um FHEM-Befehle in einen SHELL-Script zu triggern (dies ist eine „andere“ Möglichkeit), benutzen Sie bitte die oben beschriebene Client-Form der fhem.pl.

Mehrere FHEM-Kommandos hintereinander werden mittels Semikolon (;) getrennt. Weil Semikola auch in PERL-Code oder SHELL-Programmen benutzt werden, müssen sie mittels doppelten Semikola geschützt werden. Lesen Sie sich bitte die Bermerkungen des notify-Abschnittes zu Kommandoparametern und Regeln durch.

Z.B. schaltet die erste der folgenden Befehlszeilen die Lampe 1 nur/erst zur Uhrzeit 07:00 Uhr aus, die Lampe 2 aber sofort und die zweite Befehlszeile schaltet Lampe 1 und 2 um 7:00 Uhr gleichzeitig aus.

Befehle können entweder direkt eingegeben oder aus seiner Datei (z.B. am Start von FHEM aus der Konfugurationsdatei eingelesen werden. Die Befehle werden entweder direkt ausgeführt oder später wenn sie als Argumente eines at oder notify-Befehles verwendet werden.

Eine mit einem \ abgeschlossene Zeile wird mit der nachfolgenden Zeile verbunden. Somit können lange Befehlszeilen (die z.B. aus mehreren PERL-Befehlen bestehen) auf mehrere Zeilen aufgteilt werden. Einige Web-Frontends (z.B. webpgm2) erleichtern die Eingabe von sich über mehrere Zeilen erstreckende Befehle, indem man keine \ am Zeilenende eingeben muss.

Geräte-Spezifikation (devspec)

Die Befehle attr, deleteattr,delete, get, list, set, setstate, können eine komplexere Gerätespezifikation als Argumente enthalten, die auch eine Anzahl von Geräten betreffen kann. Eine Gerätespezifikation (Kurzfassung) kann z.B. so aussehen:

ein einzelner Gerätename. Dies ist der meist vorkommende Fall.
eine Liste von Gerätenamen, durch Kommata (,) getrennt
ein Bereich, durch ein Minuszeichen getrennt (-)
ein regulärer Ausdruck der eines der folgenden Zeichen enthält: ^*[]$
ein Geräteattribut, gefolgt von einem Gleichheitszeichen (=) und einem regulären Ausdruck für dieses Attribut. Als Attribut können Sie entweder Attribute die mittels “attr”-Befehl oder eines der “internen” Attribute wie DEF, STATE oder TYPE angeben.

Beispiele:

set lamp1 on

set lamp1,lamp2,lamp3 on

set lamp[1-3] on

set lamp.* on

set lamp1-lamp3 on

set lamp1-lamp3,lamp3 on

set room=kitchen off

list disabled=

list TYPE=FS20

zuerst wird die durch Kommata getrennte Spezifikation abgearbeitet, dann folgen die Bereichsspezifikationen und die regulären Ausdrücke
wenn für ein Gerät eine Spezifikation exakt zutrifft, werden keine weiteren Vergleiche vorgenommen.
die Befehlszeile kann die selbe Gerätebezeichnung mehrfach enthalten z.B.: "set lamp1-lamp3, lamp3 on". Lamp3 wird hier zwei Mal eingeschalten.
um Strukturen mit komplexeren Anforderungen zu realisieren lesen Sie bitte den Abschnitt zu structure.

?, help

?

help

attr

attr <devspec> <attrname> [<value>]

define

Device specification

Attribute, die für alle Geräte anwendbar sind:

comment
Fügt einen beliebigen Kommentar hinzu.
alias
Wird in FHEMWEB benutzt, um ein en anderen Namen für ein Gerät anzuzeigen z.B. wenn Sonderzeichen/Leerzeichen nicht in der Gerätedefinition verwendet werden können.
room
Filtert/gruppiert Geräte. Verwendbar unter web-pgm2 und web-pgm3. Ein Geräte kann zu mehr als einem Raum zugeordnet werden. In diesem Fall müssen die Raumzuordnungen durch Kommata getrennt angegeben werden.
Geräte, die dem Raum mit der Bezeichnung “hidden” zugeordnet werden, erscheinen nicht auf der Webseite, es sei denn Sie berücksichtigen FHEMWEB attribute to selectively disable rooms for certain FHEMWEB instances.

group
Gerätegruppen, anwendbar unter web-pgm2 (Modul FHEMWEB) zeigt Geräte die in die gleiche Gruppe gehören auch in einer gemeinsamen Box an. Das benutzt man, um später Geräte zu gruppieren. Ein Gerät kann zu mehr als einer Gruppe gehören. In diesem Fall müssen die entsprechenden Gruppen, durch Kommata getrennt, eingetragen werden
Wenn dieses Attribut nicht gesetzt ist, wird der in der Gerätegruppe gesetzte Gerätetyp verwendet.

showtime
Wird im Webfrontend pgm2 verwendet, um die Zeit der letzten Aktivität anstelle des Status in der Gesamtansicht anzuzeigen. Nützlich z.B. für FS20 PIRI Geräte.

event-on-update-reading
Wenn nicht gesetzt, erzeugt jede Veränderung eines “readings” ein Ereignis, welches z.B. von notify oder FileLog berücksichtigt wird. Wenn gesetzt erzeugen nur Aktualisierungen der eingetragenen „readings“ ein Ereignis.

event-on-change-reading
Dieses Attribut enthält eine durch Kommata getrennte Liste von “readings”. Wenn gesetzt, erzeugen nur Veränderungen der gelisteten „readings“ ein Ereignis. Wenn die aktualiserten Werte der gelisteten „readings“ identisch sind, wird kein Ereignis generiert.

Die unterschiedlichen Bedeutungen von event-on-update-reading und event-on-change-reading sind folgende:

Wenn beide Attribute nicht gesetzt sind erzeugt jede Aktualisierung eines jeden „readings“ eines Gerätes ein Ereignis.
Wenn eines der Attribute gesetzt ist, erzeugen nur Updates oder Änderungen von „readings“ die nicht in einem der Attribute gesetzt sind ein Ereignis.
Wenn ein „reading“ in event-on-update-reading aufgeführt ist, erzeugt eine Aktualisierung ein Ereignis unabhängig ob das „reading“ auch in event-on-change-reading aufgelistet ist.

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

Lesen Sie unter deleteattr nach um Attribute zu löschen.

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

define

define <name> <type> <type-specific>

deleteattr

deleteattr <devspec> [<attrname>]

attr

Device specification

deleteattr lamp follow-on-for-timer

deleteattr lamp

delete

delete <devspec>

define

Device specification

delete lamp

get

get <devspec> <type-specific>

get <device> ?

Device specification

getstate

getstate <devspec>


  getstate lamp

  state:1

  

  getstate fl

  ack:0 actuator:2 day-temp:21.5 desired-temp:22.5 [...] measured-temp:22.9 [...]

include

include <filename>

inform

inform {on|off|timer|raw} [regexp]

notify

FileLog

list

list [devspec] [value]

Device specification

  fhem> list

  Type list  for detailed info.

  Internal:
    global               (Internal)

  FHZ:
    FHZ                  (fhtbuf: 23)

  FS20:
    Btn4                 (on-old-for-timer)
    Roll1                (on)
    Stehlampe            (off)

  FHT:
    fl                   (measured-temp: 21.1 (Celsius))

  KS300:
    out1                 (T: 2.9  H: 74  W: 2.2  R: 8.2  IR: no)

  at:
    at_rollup            (Next: 07:00:00)

  notify:
    ntfy_btn4            (active)

  FileLog:
    avglog               (active)

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

set

set <devspec> <type-specific>

set <name> ?

Device specification

setstate

setstate <devspec> <value>

<name>

list

<value>

statefile

Device specification

setstate lamp on

The statefile uses another version of this command, don't be surprised.

shutdown

shutdown [restart]

state information

shutdown

shutdown restart

trigger

trigger <devspec> <state>

notify

Device specification

trigger btn3 on

sleep

sleep <sec>

sleep 0.5

define n3 notify btn3.* set lamp toggle;;sleep 0.5;;set lamp toggle

global

Define

N/A

Set

N/A

Get

N/A

Attributes

archivedir
archivecmd
nrarchive

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

backup_before_update
If this attribute is set to 0, an update skip always backing up your installation via the backup command. The default is to backup always before updates.
Note: Set this attribute only if you know what you do!
This Attribute is used by the update command.
Example:

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 updatefhem!
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:

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

exclude_from_update
Contains a space separated list of file which will be excluded by an update. This Attribute is used by the update command.
Example:

holiday2we
If this attribute is set, then the $we variable will be true, if the value of the holiday variable referenced by this attribute is not none.
Example:

lastinclude
If this attribute is set, then the last command of the generated configfile (see the save command) will be
include <lastinclude-value>
This attribute is DEPRECATED, use notify, with the INITIALIZED event to execute commands after initialization.

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

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

motd
Message Of The Day. Displayed on the homescreen of the FHEMWEB package, or directly after the telnet logon, before displaying the fhem> prompt. SecurityCheck is setting motd if it is not defined upon startup, to avoid this set the motd value to none

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.

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.

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

title
Used by the web frontend fhemweb.pl (webpgm2) as a Page title.

updatebranch
The update branch will be set by the file FhemUtils/release.pm contained in the modpath. For example, if a stable version (version 5.3 upwards) of fhem is installed via a direct download connection of the archieve on the fhem-website, then the branch of the update is automatically on "stable". In this branch, only updates fixing confirmed errors, relevant security fixes or new stable versions are provided.
By using the command "update development <filename>", particular files or packages can always be installed directly from the development branch (e.g. "update development <package>").
If you want to update from the development branch in stable verion in general, you can force this behaviour by using the attribute "updatebranch DEVELOPMENT". In case the installation of fhem should generally using the development branch, this attribute would not have to be set. Instead, use "update development force" to update all files including release.pm (containing the release-information) to the newest version.

userattr
A space separated list which contains the names of additional attributes. Without specifying them you will not be able to set them (in order to prevent typos).

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.
Recommended level is 3 for normal use.

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

Perl specials

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

To test perl oneliners, type them on the telnet prompt (or FHEMWEB text input) by enclosing it in {}, one line at once. The last line will only write something in the logfile, the output of the other lines is directly visible.

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

The following helper functions are defined in 99_Util.pm (which will be loaded automatically, as every module with prefix 99):

min(a,b), max(a,b)
time_str2num("YYYY-MM-DD HH:MM:SS") returns a numerical value, which makes computation of time differences easier
abstime2rel("HH:MM:SS") converts an absolute time to a relative one

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

Value(<devicename>)
returns the state of the device (the string you see in paranthesis in the output of the list command).
OldValue(<devicename>)
OldTimestamp(<devicename>)
returns the old value/timestamp of the device.
ReadingsVal(<devicename>,<reading>,<defaultvalue>)
Return the reading (the value in the Readings section of "list device")
AttrVal(<devicename>,<attribute>,<defaultvalue>)
Return the attribute of the device

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

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 fhemwiki entry on creating logs.
Following is a minimal .gplot definition (valid only for plotmode SVG):

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

The .gnuplot file consists of 3 parts:

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

Inhalt

Einleitung

FHEM Befehlstypen

Geräte-Spezifikation (devspec)

?, help

attr

setdefaultattr

define

deleteattr

delete

get

getstate

include

inform

list

modify

quit

reload

rename

rereadcfg

save

set

setstate

shutdown

trigger

sleep

global

Perl specials

gnuplot file syntax