+
+
Inhalt
+
+
+
+
+
Einleitung
+
+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:
+
+
+ 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> (Die Betätigung der "Enter"-Taste schaltet in den "prompt"
+ Modus)
+ <command>...
+ quit
+
+ oder
+
+ fhem.pl 7072 "set lamp off"
+
+
+
+
+
+
FHEM Befehlstypen
+
+Es gibt drei Arten von Befehlen: „fhem“ Befehle (werden in diesem Dokument
+beschrieben), SHELL-Befehle (diese müssen von doppelten Anführungszeichen „“
+eingeschlossen werden) und PERL-Ausdrücken (von geschwungenen Klammern {}
+eingeschlossen). SHELL-Befehle oder PERL-Ausdrücke werden für komplexe at
+oder notify Ausdrücke benötigt, können aber auch als „normale“ Befehle angewendet werden.
+ Die folgenden drei Befehle bewirken z.B. dasselbe
+ Ergebnis, wenn sie am “telnet”-Prompt eingegeben werden:
+
+
+ set lamp off
+ "fhem.pl 7072 "set lamp off""
+ {fhem("set lamp off")}
+
+ 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.
+
+
+ define lampoff at 07:00 set Lamp1 off; set Lamp2 off
+ define lampoff at 07:00 set Lamp1 off;; set Lamp2 off
+
+ 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
+
+ Bemerkungen:
+
+ - 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
+
+ Sie erhalten eine Liste aller Befehle mit einer Kurzbeschreibung jedes
+ Befehls.
+
+
+
+
attr
+
+ attr <devspec> <attrname> [<value>]
+
+
+ Dieser Befehl setzt ein Attribut für ein Gerät welches mit define definiert wurde. Sie können auch
+ Ihre eigenen Attribute definieren, um sie in anderen Applikationen anzuwenden.
+ Geben Sie „<attr <name> ?“ ein, um eine Liste verfügbarer Attribute
+ anzuzeigen. Bitte lesen Sie das Kapitel Device specification
+ um Detail-Informationen zu <devspec> zu erhalten.
+ 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.
+
+
+
+
+ Die folgenden Attribute werden bei Modulen verwendet, die standardisierte „readings“
+ Aktualisierung der fhem.pl benutzen. Informieren Sie sich in der Liste der
+ Modulattribute wenn Sie wissen möchten ob dies unterstützt wird.
+
+
+ - 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.
+
+
+
+
+
+ Gerätespezifische Attribute sind in der Beschreibung zum jeweiligen Gerät
+ aufgeführt.
+
+
+ Beispiele:
+
+ 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
+
+
+
+ Bemerkungen:
+
+ - Lesen Sie unter deleteattr nach um Attribute
+ zu löschen.
+
+
+
+
+
setdefaultattr
+
+ setdefaultattr [<attrname> [<value>]]
+
+
Add a default attribute. Each device defined from now on will receive
+ this attribute.
If no attrname is specified, then the default attribute
+ list will be deleted.
+
+
+ Example to set the attribute "room kitchen" and "loglevel 4" to
+ each of the lamps:
+
+ setdefaultattr room kitchen
+ setdefaultattr loglevel 4
+ define lamp1 FS20 1234 11
+ define lamp2 FS20 1234 12
+ define lamp3 FS20 1234 13
+ setdefaultattr
+
+
+
+ Notes:
+
+ - There is no way to delete a single default-attribute from the list
+
+
+
+
+
+
define
+
+ define <name> <type> <type-specific>
+
+ 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)".
+ Use "define <name> ?" to get a list of possible types.
+ After definition, the global event "DEFINED" will be generated, see the
+ notify section for details.
+
+
+ Each device takes different additional arguments at definition, see the
+ corresponding device section for details.
+
+
+
+
+
+
deleteattr
+
+ deleteattr <devspec> [<attrname>]
+
+ Delete either a single attribute (see the attr command)
+ or all attributes for a device (if no <attrname> is defined).
+ See the Device specification section for details on
+ <devspec>.
+
+
+ Examples:
+
+ deleteattr lamp follow-on-for-timer
+ deleteattr lamp
+
+
+
+
+
+
delete
+
+ delete <devspec>
+
+ Delete something created with the define command.
+ See the Device specification section for details on
+ <devspec>.
+ After deletion, the global event "DELETED" will be generated, see the notify
+ section for details.
+ Examples:
+
+
+
+
+
+
get
+
+ get <devspec> <type-specific>
+
+ Ask a value directly from the device, and wait for an answer. In general, you
+ can get a list of possible parameters by
+
+ See the Device specification section for details on
+ <devspec>.
+
+ Each device has different get parameters, see the corresponding device
+ section for details.
+
+
+
+
+
+
+
getstate
+
+ getstate <devspec>
+
+ Output a short space seperated status for <devspec>. It is useful for
+ monitoring the device in e.g. Cacti.
+ Examples:
+
+ getstate lamp
+ state:1
+
+ getstate fl
+ ack:0 actuator:2 day-temp:21.5 desired-temp:22.5 [...] measured-temp:22.9 [...]
+
+ Note: to use this command copy the file contrib/getstate/99_getstate.pm into
+ your FHEM directory.
+
+
+
+
+
+
+
include
+
+ include <filename>
+
+ Read in the file, and process every line as a fhem command. Makes
+ configuration files more modular and enables to reread them.
+
+
+
+
+
inform
+
+ inform {on|off|timer|raw} [regexp]
+
+ 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.
+ 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
+ notify or FileLog entries.
+
+
+
+
+
+
list
+
+ list [devspec] [value]
+
+ 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 Device specification section for details on
+ <devspec>.
+
+ If value is specified, then output this property (like DEF, TYPE, etc) or
+ reading (actuator, measured-temp) for all devices from the devspec.
+
+ Example:
+
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)
+
+
+ If specifying
name, then a detailed status for
name
+ will be displayed, e.g.:
+
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>
+
+
+ Used to modify some definitions. Useful for changing some at or notify 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.
+
+ Example:
+
+ define lampon at 19:00 set lamp on
+ modify lampon *19:00
+ modify lampon 19:00 set lamp on-for-timer 16
+
+
+
+
+
quit
+
+ quit
+
+ If used in a TCP/IP session, terminate the client session.
+ If used in a script, terminate the parsing of the current script.
+
+ Example:
+
+
+
+
+
+
reload
+
+ reload <module>
+
+ Reload the given module from the module directory. It is a convenient way to
+ test modules whithout restarting the program.
+
+ Example:
+
+
+
+
+
rename
+
+ rename <oldname> <newname>
+
+ Rename a device from the <oldname> to <newname>, together with
+ its attributes. The global event RENAMED will be generated, see the notify
+ section for details.
+
+ Example:
+
+ rename FHT_1234 fht.kitchen
+
+
+
+
+
+
rereadcfg
+
+ rereadcfg [fhem-config-file]
+
+ Re-read the active configuration file, or the optionally specified file.
+ The sequence: the statefile 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.
+ Upon completion it triggers the global:REREADCFG event. All existing
+ connections up to the one issuing the rereadcfg will be closed.
+
+
+ Example:
+
+
+
+
+
save
+
+ save [<configfile>]
+
+ Save first the statefile, then the
+ configfile information. If a parameter is specified,
+ it will be used instead the global configfile attribute.
+ Notes:
+
+ - 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 parameters of a device / send signals to a device. You can
+ get a list of possible parameters by
+
+ See the Device specification section for details on
+ <devspec>. The set command returns only a value on error.
+
+ Each device has different set parameters, see the corresponding device
+ section for details.
+
+
+
+
+
+
+
setstate
+
+ setstate <devspec> <value>
+
+ Set the "STATE" for <name> as shown in paranthesis in the
+ list command
+ to <value> without sending any signals to the device
+ itself. This command is also used in the statefile.
+ See the Device specification section for details on
+ <devspec>.
+
+ Examples:
+
+ Note:
+
+ - The statefile uses another version of this command, don't be surprised.
+
+
+
+
+
+
+
shutdown
+
+ shutdown [restart]
+
+ Shut down the server (after saving the state information
+ ). It triggers the global:SHUTDOWN event. If the optional restart
+ parameter is specified, fhem tries to restart itself.
+
+ Example:
+
+ shutdown
+ shutdown restart
+
+
+
+
+
+
trigger
+
+ trigger <devspec> <state>
+
+ Trigger a notify definition.
+ See the Device specification section for details on
+ <devspec>.
+
+
+ Example:
+
+
+
+
+
sleep
+
+ sleep <sec>
+
+ Sleep for a given amount, millisecond accuracy.
+
+ Example:
+
+ sleep 0.5
+ define n3 notify btn3.* set lamp toggle;;sleep 0.5;;set lamp toggle
+
+
+ Note: sleep followed by another command and issued in at/notify/etc is not
+ blocking fhem.
+
+
+
+
+
global
+
+ 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
+
+
+ Define
+
+ Set
+
+ Get
+
+ 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:
+
+ attr global backup_before_update 0
+
+
+
+
+ - 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.:
+
+
+ "/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"
+
+ 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:
+
+ attr global backupcmd /usr/local/bin/myBackupScript.sh
+
+
+
+
+ - backupdir
+ A folder to store the compressed backup file.
+ This Attribute is used by the backup command.
+ Example:
+
+ attr global backupdir /Volumes/BigHD
+
+
+
+
+ - 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:
+
+ attr global backupsymlinks yes
+
+
+
+
+ - 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:
+
+ attr global exclude_from_update 21_OWTEMP.pm temp4hum4.gplot FS20.on.png FS20.off.png
+
+
+
+
+ - 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:
+
+ attr global holiday2we hessen
+
+
+
+
+ - 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.
+
+ { "Hello" }
+ { 1+3*4 }
+ { `ls /etc` }
+ { Log 1, "Hello" }
+
+
+
+
+ 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:
+
+ { fhem "set light on" }
+ define n1 notify piri:on { fhem "set light on" }
+
+ 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:
+
+ define MyMacro notify MyMacro { Log 1, "Hello"}
+ trigger MyMacro
+ define MacroWithArg notify MyMacro { Log 1, "Hello %"}
+ trigger MyMacro MyArg
+
+
+
+
+ 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.
+
+ define n2 notify piri:on { if($hour > 18 || $hour < 5) {
+ fhem "set light on" } }
+ define roll_en *07:45:00 { fhem "trigger SwitchAllRoll on" if(!$we) }
+ define roll_en *08:30:00 { fhem "trigger SwitchAllRoll on" if($we) }
+
+
+
+
+
+ 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:
+
+ sunset($offset, $min, $max)
+ sunrise($offset, $min, $max)
+ isday()
+
+ 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:
+
+ set yrange [-0.1:1.1]
+ set y2range [0:]
+
+
+ - ytics,y2tics
+ the label for the left/right axis tics. Examples:
+
+ set ytics ("on" 0, "off" 1)
+ set y2tics
+
+
+
+
+
+
+ - #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.
+
+
+
+
+
+
+
+
+