fhem.pl command reference

Introduction
?,help
attr
defattr
define
delattr
delete
get
include
inform
list
modify
quit
reload
rereadcfg
save
set
setstate
shutdown
trigger
sleep
xmllist
Perl specials

Introduction

You can use all of the following commands in in two ways: There are three types of commands: "fhem" commands (described in this document), shell commands (they must be enclosed in double quotes ") and perl expressions (enclosed in curly brackets {}). shell commands or perl expressions are needed for complex at or notify arguments.

Shell commands will be executed in the background, the perl program and the fhem commands will be executed in the main "thread". In order to make perl expressions easier to write, some special functions and variables are available. See the section Perl special for a description. To trigger "fhem" commands from a shell script, use the client form of fhem.pl (described above).

Multiple fhem commands are separated by semicolon (;). In order to use semicolon in perl code or shell programs, they have to be escaped by the double semicolon (;;).

Commands can be either typed in plain, or read from a file (e.g. the configuration file at startup). The commands are either executed directly, or later if they are arguments to the at and notify fhem commands.

If commands are read from a file, then a line ending with \ will be concatenated with the next one, so long lines (e.g. perl oneliners) can be split in multiple lines

?, help

attr

defattr

define

delattr

delete

get

include

inform

list

modify

quit

reload

rereadcfg

save

set

setstate

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

    Examples: 
          setstate lamp on

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

shutdown

trigger

    trigger <dev> <state>

    Trigger a notify definition.

    Example:
      trigger btn3 on

sleep

    sleep <sec>

    Sleep for a given amount, millisecond accuracy.

    Example:
      sleep 0.5
      notify btn3 set lamp toggle;;sleep 0.5;;set lamp toggle

    Note: As the server is not multithreaded, everything is blocked for the given amount.

xmllist

    xmllist

    Returns an XML tree of all definitions, all notify settings and all at entries. It is not intended for human consumption.

    Example: 
      FHZ> xmllist
  <FHZINFO>
          <internal_LIST>
                  <internal name="global" state="internal" sets="" attrs="room configfile logfile modpath pidfilename port statefile userattr verbose version">
                          <INT key="DEF" value="<no definition>"/>
                          <INT key="NR" value="0"/>
                          <INT key="STATE" value="internal"/>
      [...]

Perl specials

  • To use fhem commands from the perl expression, use the function "fhem", which takes a string argument, this string will be evaluated as an fhem command chain.
    Example:
      define n1 notify piri:on { fhem "set light on" }
  • To make date and time handling easier, before evaluating a perl expression the variables $sec, $min, $hour, $mday, $month, $year, $wday, $yday, $isdst are set (see perldoc -f localtime), with the exception that $month is in the range of 1 to 12, and $year is also corrected by 1900 (as one would normally expect). Additionally $we is 1 if it is weekend (i.e $wday == 0 || $wday == 6), and 0 otherwise. Example:
      define n2 notify piri:on { if($hour > 18 || $hour < 5) { fhem "set light on" } }
  • Note: do not forget to escape the semicolon (;) with two semicolons (;;), else your perl code will be interpreted as an fhem command and you most certainly get syntax errors.
  • The current value (the string you see in paranthesis in the output of the list command) is available in the value hash; to access it use $value{<devicename>}
    If you need the old value (and time) of the currently triggered device, then you can access it with $oldvalue{$dev}{TIME} and $oldvalue{$dev}{VAL}.
  • To access the numerical value of an FS20 command (e.g. toggle), use the hash fs20_c2b. E.g. { Log 2, $fs20_c2b{"toggle"} }
  • If you add the 99_SUNRISE.pm from the contrib directory to your module directory (NOTE: you have to install the Perl module DateTime::Event::Sunrise first), then you have access to the follwing functions:
      sunset_rel()
      sunset_abs()
      sunrise_rel()
      sunrise_abs()
      isday()
    The _rel functions should be used as "at" spec, and the _abs functions as argument to the on-till argument of the set command.
    isday returns 1 if the sun is visible, and 0 else.