get <name> <type-specific>

Ask a value directly from the device, and wait for an answer. In general, you can get a list of possible commands by
get <device> help
Right now only the FHZ module supports this function.

Type FHZ:

get FHZ <value>

where value is one of:


      init1
      init2
      init3
      serial
      fhtbuf

Notes:
• There is only one FHZ device (called FHZ), it is created automatically at startup.
• The mentioned codes are needed for initializing the FHZ1000
• The answer for a command is also displayed by list FHZ
• fhtbuf should be incorporated later in the FHT module:
the FHZ1000PC has a message buffer for the FHT, as it only can send messages to it every 2 (or so) minutes. If the buffer is full, then newly issued ones will be dropped. fhtbuf returns the free memory in this buffer (in hex), my maximum is 2c (42 bytes).

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]

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.

list

list [name]

Output a list of all definitions, all notifyon settings and all at entries. This is one of the few commands which return a string in a normal case.

Example:

  FHZ> list

  Type list  for detailed info.

  FHZ devices:
    FHZ                  (Last msg: Initialized)

  FS20 devices:
    Btn3                 (Last msg: off)
    Roll1                (Last msg: on-for-timer 11)
    Stehlampe            (Last msg: off)

  FHT devices:
    fl                   (Last msg: state: Bat: ok, Window: closed)
    wz                   (Last msg: actuator: 07%)

  NotifyOn:
    Btn3                 /usr/local/bin/setroll %

  At:
    +*{sunrise_rel(+10)} set Roll1 on-for-timer 10 (07:43:56)


  Logs:
    wzlog FileLog /var/tmp/wz.log wz:.*(temp|actuator).*
  

If specifying name, then a detailed status for name will be displayed, e.g.:

  FHZ> list wz

  2006-01-03 18:28:27   actuator        07%
  2006-01-03 18:26:32   mon-from1       06:00
  2006-01-03 18:26:33   mon-to1         23:00
  2006-01-03 18:26:34   tue-from1       06:00
  2006-01-03 18:26:34   tue-to1         23:00
  2006-01-03 18:26:35   wed-from1       06:00
  2006-01-03 18:26:35   wed-to1         23:00
  2006-01-03 18:26:37   thu-from1       06:00
  2006-01-03 18:26:37   thu-to1         23:00
  2006-01-03 18:26:38   fri-from1       06:00
  2006-01-03 18:26:38   fri-to1         23:00
  2006-01-03 18:26:39   sat-from1       06:00
  2006-01-03 18:26:40   sat-to1         23:50
  2006-01-03 18:26:41   sun-from1       06:00
  2006-01-03 18:26:41   sun-to1         23:00
  2006-01-03 18:26:45   mode            manual
  2006-01-03 18:26:44   desired-temp    21.5 (Celsius)
  2006-01-03 18:26:45   measured-temp   22.0 (Celsius)
  2006-01-03 18:26:46   state           Bat: ok, Window: closed
  2006-01-03 18:24:37   init            255
  2006-01-03 18:26:42   day-temp        21.0 (Celsius)
  2006-01-03 18:26:42   night-temp      17.0 (Celsius)
  2006-01-03 18:26:43   unknown_85      4
  2006-01-03 18:26:43   windowopen-temp 12.0 (Celsius)
  

logfile

logfile

Specify the logfile to write. Specify this as the first command in the configfile as everything gets logged in the logfile. 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 of the define command.

Examples:
logfile /var/log/fhem
logfile /var/log/fhem-%Y-%m.log

modpath

modpath <path>

Specify the path to the modules directory FHEM. The path should not contain the directory FHEM. Every module there will be loaded.

Example:
modpath /usr/local/lib

notifyon

notifyon <name> <command>

Execute a command when received an event for the definition <name>. As with normal commands, if it is enclosed in {}, then it is a perl expression, if it is enclosed in "", then it is a shell command, else it is a "plain" fhem.pl command (chain). See the trigger command for testing it. Examples:
notifyon btn3 set lamp %
notifyon btn3 { fhz "set lamp %" }
notifyon btn3 "/usr/local/bin/setlamp "%""
notifyon btn3 set lamp1 %;;set lamp2 %
notifyon wz:measured.* "/usr/local/bin/logfht @ "%""
notifyon .*H:.* {DbLog("@","%")}
notifyon UNDEFINED "send-me-mail.sh "%""


Notes:
• The character % will be replaced with the received event, e.g. with on or off or measured-temp: 21.7 (Celsius)
  It is advisable to put the % into double quotes, else the shell may get a syntax error.
  To use % or @ in the text itself, use the double mode (%% or @@)
• The character @ will be replaced with the device name.
• <name> may also be a compound of definition:event to filter for events.
• <name> is in fact a regexp. It must completely (!) match either the device name, or the compound of the device name and the event. The event is either the string you see in the list output in paranthesis after the device name, or the string you see when you do a detailed list of the device.
• To use database logging, copy the file contrib/91_DbLog.p into your modules directory, and change the $dbconn parameter in the file.
• Each undefined device (FS20, HMS, FHT) will be reported with the device name "UNDEFINED". The % parameter will contain the type (FS20, HMS100T, etc) and device number, separated by a space.

pidfile

pidfile <filename>

Write the process id of the perl process to the specified file. We are running as a daemon, and some distributions would like to check by the pid if we are still runnning.

Example:
pidfile /var/run/fhem.pid

port

port <number> [<global>]

Listen on the TCP/IP port <number> for incoming connections. To offer at least a little bit of security, the server will only listen for connections from the localhost per default. The optional global parameters enables listening for non-localhost connections too.

Example:
port 7072

quit

quit

If used in a TCP/IP session, terminate the client session.
If used in a script, terminate the parsing of the script.

Example:
quit

reload

reload <module>

Reload the given module from the module directory. Mainly intended to reload the 99_PRIV file (or equivalent) in order to test perl-scripts.

Example:
reload 99_PRIV

rereadcfg

rereadcfg

Re-read the configuration file. Note: The statefile will be saved first, then the config file will be read (all devices will be initialized again), and at last the statefile will be reloaded again.

Example:
rereadcfg

savefile

savefile <filename>

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

Example:
savefile /var/tmp/fhem.save

set

set <name> <type-specific>

Set parameters of a device / send signals to a device. In general, you can get a list of possible commands by
set <device> help
Instead of <name> you can also use an enumeration (separated by comma) or ranges (separated by -), see the FS20 examples.

Type FHZ:

set FHZ <variable> [<value>]

where value is one of:


      initFS20
      initHMS
      time
      FHTcode
      activefor
      raw

Notes:
• use activefor if you have multiple FHZ devices, and you want to change the association of an FS20 or FHT device (i.e. which device will send out the messages).
• raw is used to send out "raw" FS20/FHT messages. See the doc directory for some examples
• In order to set the time of your FHT's, schedule this command every minute:
  at +*00:01:00 set FHZ time
  See the attr command to prevent logging of this command.
• FHTcode is a two digit hex number (from 00 to 63?) and sets the central FHT code, which is used by the FHT devices. After changing it, you must reprogram each FHT80b with: PROG (until Sond appears), then select CEnt, Prog, Select nA.

Type FS20:

set <name> <value> [<time>]

where value is one of:


      dim06%
      dim12%
      dim18%
      dim25%
      dim31%
      dim37%
      dim43%
      dim50%
      dim56%
      dim62%
      dim68%
      dim75%
      dim81%
      dim87%
      dim93%
      dim100%
      dimdown
      dimup
      dimupdown
      off
      off-for-timer
      on     		# dimmer: set to value before switching it off
      on-for-timer      # see the note
      on-old-for-timer  # set to previous (before switching it on) 
      ramp-on-time      # time to reach the desired dim value on dimmers
      ramp-off-time     # time to reach the off state on dimmers
      reset
      sendstate
      timer
      toggle            # between off and previous dim val
      on-till           # Special, see the note
      

Examples:
set lamp on
set lamp1,lamp2,lamp3 on
set lamp1-lamp3 on
set lamp on-for-timer 12


Notes:
• Use reset with care: the device forgets even the housecode.
• As the FS20 protocol needs about 0.22 seconds to transmit a sequence, a pause of 0.22 seconds is inserted after each command.
• The FS20ST switches on for dim*%, dimup. It does not respond to sendstate.
• If the timer is set (i.e. it is not 0) then on, dim*, and *-for-timer will take it into account (at least by the FS20ST).
• The time argument ranges from 0.25sec to 4 hours and 16 minutes. As the time is encoded in one byte (there are only 112 distinct values), the resolution gets coarse with larger values. The program will report the used timeout if the specified one cannot be set exactly. The resolution is 0.25 sec from 0 to 4 sec, 0.5 sec from 4 to 8 sec, 1 sec from 8 to 16 sec and so on. If you need better precision for large values, use the at command which has a 1 sec resolution.
• If the attribute follow-on-for-timer is set for the device and the on-for-timer command is sent to the device with a time parameter, the program automatically schedules a "setstate off" for the specified time.
• on-till requires an absolute time in the "at" format (HH:MM:SS, HH:MM or {}, where the perl-code returns a time specification). If the current time is greater then the specified time, then the command is ignored, else an "on" command is generated, and for the given "till-time" an off command is scheduleld via the at command.

Type FHT:

set <name> <valuetype> <value>

where value is one of:


    mon-from1
    mon-to1
    mon-from2
    mon-to2
    tue-from1
    tue-to1
    tue-from2
    tue-to2
    wed-from1
    wed-to1
    wed-from2
    wed-to2
    thu-from1
    thu-to1
    thu-from2
    thu-to2
    fri-from1
    fri-to1
    fri-from2
    fri-to2
    sat-from1
    sat-to1
    sat-from2
    sat-to2
    sun-from1
    sun-to1
    sun-from2
    sun-to2
    mode
    desired-temp
    day-temp
    night-temp
    year
    month
    day
    hour
    minute
    refreshvalues

Notes:
• All *-temp valuetypes need a temperature as argument, which will be rounded to 0.5 Celsius
• mode is one of auto, manual or holiday
• The *-from1/*-from2/*-to1/*-to2 valuetypes need a time spec as argument in the HH:MM format. They define the periods, where the day-temp is valid. The minute (MM) will be rounded to 10, and 24:00 means off.
• refreshvalues does not need an argument, but sends a plea to the FHT device, so it may send its parameters. If you want to get these values regularly, then schedule:
  at +*01:00:00 set <name> refreshvalues
  My two FHT devices send the actuator, measured-temp and state regularly, and everything else if it changes, so I do not schedule this normally.
• The FHT is very economical (or lazy), it receives messages from the FHZ1000 every 2 minutes (or so). Don't be surprized if your command is accepted 10 minutes later by the device. See the related fhtbuf entry in the get section.

Type FHT:

set WS300Device <interval(min.)> <height(m)> <rainvalume(ml)>

Set some WS300 configuration parameters.

setstate <name> <value>

Set the "Last msg" for the definition <name> shown in the list command to <value> without sending any signals to the device itself. This command is also used in the savefile.
Setting/changing arbitrary comments is possible, if the value begins with comment:. To delete the comment, set it with an empty value, see below.

Examples:

    setstate lamp on
    setstate lamp comment:location sleeping room
    setstate lamp comment:location # deletes the comment


Note:
• You even may set the detailed state (i.e. what you get when you call list <name;> by specifying "<time> <attribute> <value>". Take a look at the savefile after devices reported values for an example.

shutdown

shutdown

Shut down the server (after saving the state information )

Example:
shutdown

trigger

trigger <dev> <state>

Trigger a notifyon command.

Example:
trigger btn3 on

sleep

sleep <sec>

Sleep for a given amount, millisecond accuracy.

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

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

verbose

verbose <level>

Set the verbosity level. Possible values:
• 0 - it will only tell you when the server was started, or stopped
• 1 - it logs all error messages or unknown packets
• 2 - it logs all signals received or sent in a "digested" format,
• 3 - it logs the signals for undefined devices,
• 4 - it logs the TCP/IP connections and the called programs with parameters,
• 5 - is for debugging.
Recommended level is 3 for normal use.

Example:
verbose 3

xmllist

xmllist

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

Example:

  FHZ> xmllist
    <FHZINFO>
	<FHZ_DEVICES>
	    <FHZ name="FHZ" definition="FHZ FHZ" state="fhtbuf: 1c">
                <STATE name="fhtbuf" value="23" measured="2006-02-12 14:03:39"/>
		<STATE name="serial" value="136e21bc" measured="2006-03-26 08:47:36"/>
    [...]
  

Perl specials

• To use fhz commands from the perl expression, use the function "fhz", which takes a string argument, this string will be evaluated as an fhz command chain.
  Example:
  notifyon piri:on { fhz "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:
  notifyon piri:on { if($hour > 18 || $hour < 5) { fhz "set light on" } }
• Note: do not forget to escape the semicolon (;) with two semicolons (;;), else your perl code will be interpreted as an fhz 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 currentliy 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.