fhem.pl command reference
Introduction
?,help
attr
define
delete
deleteattr
get
include
inform
list
modify
quit
reload
rereadcfg
save
set
setdefaultattr
setstate
shutdown
sleep
trigger
xmllist
Device specification
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.
A line ending with \ will be concatenated with the next one, so long lines
(e.g. multiple perl commands) can be split in multiple lines. Some web fronteds
make editing of multiline commands transparent.
?, help
?
help
Get a list of all commands and short description for each one
attr
attr <devspec> <attrname> [<value>]
or
attr at <at-spec-regexp> <attribute>
Set an attribute to something defined by define.
There are some special attributes used by the fhem.pl itself or the
web-frontends, but you can define your own to use them in other applications.
You have to define them first with userattr, see
below.
Use "attr <name> ?" to get a list of possible attributes.
See the Device specification section for details on
<devspec>.
Following are attributes of the global device:
- configfile
Contains the name of the configuration file. If save is called without argument, then the output will
be written to this file.
- lastinclude
If this attribute is set, then the last command of the generated
configfile (see the save command) will be
include <lastinclude-value>
This file is needed, as the save command will write only defines and
attributes to the config file, any other commands / includes will be
lost. E.g. it makes sense to set the FHTcode in
this file or the coordinates of your house via
sunrise_coord
- 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.
- modpath
Specify the path to the modules directory FHEM. The path
should 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).
- 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.
- pidfilename
Works for the global "device"
- port
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. If
there is a second value "global" then the server will listen for
non-localhost connections too.
- allowfrom
Comma (,) separated list of ip-addresses or hostnames. If set,
only connections from these addresses are allowed.
- 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.
- 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.
Attributes used by all devices:
- comment
Add an arbitrary comment.
- room
Filter/group devices. Recognized by web-pgm2 and web-pgm3.
Devices in the room hidden will not appear in the web output.
- 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.
Attributes used by some device types:
- archivecmd / archivedir / nrarchive
Can be applied to FileLog devices.
When a new FileLog file is opened, the FileLog archiver wil be called.
This happens only, if the name of the logfile has changed (due to
time-specific wildcards, see the FileLog
section), and there is a new entry to be written into the file.
If the attribute archivecmd is specified, then it will be started as a
shell command (no enclosing " is needed), and each % in the command
will be replaced with the name of the old logfile.
If this attribute is not set, but nrarchive and/or archivecmd is set,
then all superfluous logfiles will be moved to archivedir (or deleted if
archivedir is not set).
- disable
Can be applied to at/watchdog/notify/FileLog devices.
Disables the corresponding at/notify or FileLog device. Note:
If applied to an at, the command will not be executed,
but the next time will be computed.
- do_not_notify
Can be applied to FHZ/FS20/FHT/HMS/KS300/WS300 devices.
Disable FileLog/notify/inform notification for a device. This affects
the received signal, the set and trigger commands.
- dummy
Can be applied to FS20/FHT devices.
Set the device attribute dummy to define devices which should not
output any radio signals. Associated notifys will be executed if
the signal is received. Used e.g. to react to a code from a sender, but
it will not emit radio signal if triggered in the web frontend.
Implemented for FS20 and FHT devices.
- filtertimeout
Can be applied to FHZ devices.
Ignore duplicate messages for this amount of time. The time is in
seconds, fractions are allowed. It affects installations with more then
one FHZ device or repeater, see the repeater
entry.
- follow-on-for-timer
Can be applied to FS20 devices.
the program automatically schedules a "setstate off" for the time
specified as argument to the on-for-timer command (for the specified
device only).
- loglevel
Can be applied to FHZ/FS20/FHT/HMS/KS300/WS300 devices.
Set the device loglevel to e.g. 6 if you do not wish messages from a
given device to appear in the global logfile (FHZ/FS20/FHT). E.g. to
set the FHT time, you should schedule "set FHZ time" every minute, but
this in turn makes your logfile unreadable. These messages will not be
generated if the FHZ attribute loglevel is set to 6.
- logtype
Can be applied to FileLog devices.
Used by the pgm2 webfrontend to offer gnuplot/SVG images made from the
logs. The string is made up of tokens separated by comma (,), each
token specifies a different gnuplot program. The token may contain a
colon (:), the part before the colon defines the name of the program,
the part after is the string displayed in the web frontend. Currently
following types of gnuplot programs are implemented:
- fs20
Plots on as 1 and off as 0. The corresponding filelog definition
for the device fs20dev is:
define FileLog fslog fs20dev /var/log/fs20dev-%Y-%U.log
- fht
Plots the measured-temp/desired-temp/actuator lines. The
corresponding filelog definitions (for the FHT device named
fht1) looks like:
define FileLog fhtlog1 fht1:.*(temp|actuator).*
/var/log/fht1-%Y-%U.log
- ks300_1
Plots the temperature and rain (per hour and per day) of a
ks300. The corresponding filelog definitions (for the KS300
device named ks300) looks like:
define FileLog ks300log ks300:.*H:.*
/var/log/ks300-%Y-%U.log
- ks300_2
Plots the humidity and wind values of a
ks300. The corresponding filelog definition is the same as
above, both programs evaluate the same log.
- text
Shows the logfile as it is (plain text). Not gnuplot definition
is needed.
Example:
attr fhtlog1 logtype ks300_1:Temp/Rain,ks300_2:Hum/Wind,text:Raw-data
- model
Can be applied to FHZ/FS20/FHT/HMS/KS300/WS300 devices.
The model attribute denotes the model type of the device.
The attributes will (currently) not be used by the fhem.pl directly.
It can be used by e.g. external programs or web interfaces to
distinguish classes of devices and send the appropriate commands
(e.g. "on" or "off" to a fs20st, "dim..%" to fs20du etc.).
The spelling of the model names are as quoted on the printed
documentation which comes which each device. This name is used
without blanks in all lower-case letters. Valid characters should be
a-z 0-9 and - (dash),
other characters should be ommited. Here is a list of "official"
devices:
- repeater
Can be applied to FHZ devices.
Set the attribute "repeater" for an FHZ device to 1 to ignore events
received from a FS20 repeater. In fact we are not sure that they are
repeater messages, we just ignore messages which were sent out by our
device for the next 3 seconds (see the next attribute)
- skip_next
Can be applied to at devices.
Used for at commands: skip the execution of the command the next
time.
- fhtsoftbuffer
Can be applied to FHZ devices.
As the FHZ command buffer for FHT devices is limited (see fhtbuf),
and commands are only sent to the FHT device every 120 seconds,
the hardware buffer may overflow and FHT commands get lost.
Setting this attribute implements an "unlimited" software buffer
Default is disabled (i.e. not set or set to 0).
- retrycount
Can be applied to FHT devices.
If the fhtsoftbuffer attribute is set, then
resend commands retrycount times if after 240 seconds
no confirmation message is received from the corresponding FHT
device.
Default is 3.
- minfhtbuffer
Can be applied to FHT devices.
FHEM wont send commands to the FHZ if its fhtbuffer is below
this value, default is 0. If this value is low, then the ordering of
fht commands (see the note in the FHT section of set)
has little effect, as only commands in the softbuffer can be
prioritized. The maximum value should be 7 below the hardware maximum
(see fhtbuf).
- webname
Can be applied to FHEMWEB devices. (webfrontend/pgm2)
Path after the http://hostname:port/ specification. Defaults to fhem,
i.e the default http address is http://localhost:8083/fhem
- refresh
Can be applied to FHEMWEB devices. (webfrontend/pgm2)
If set, a http-equiv="refresh" entry will be genererated with the given
argument (i.e. the browser will reload the page after the given
seconds).
- plotmode
Can be applied to FHEMWEB devices. (webfrontend/pgm2)
Specifies how to generate the plots:
- gnuplot
Call the gnuplot script with each logfile. The filename
specification of the FileLog device will
determine what is in the plot. The data is converted into an
image on the backend with gnuplot.
- gnuplot-scroll
Fhemweb will offer zoom and scroll buttons in order to navigate
in the current logfile, i.e. you can select just a part of the
data to be displayed. The more data is contained in a single
logfile, the easier you can navigate. The recommendation is to
store the data for a whole year in one logfile. The data is
converted into an image on the backend with gnuplot.
- SVG
The same scrolling as with gnuplot scroll, but the data is sent
as an SVG script to the frontend, which will compute
the image: no need for gnuplot on the backend.
- plotsize
Can be applied to FHEMWEB devices. (webfrontend/pgm2)
Specifies
the defult size of the plot, in pixels, separated by comma:
width,height. You can set individual sizes by setting the plotsize of
the weblink.
Examples:
attr global verbose 3
attr lamp room kitchen
attr lamp dummy
attr lamp loglevel 6
attr FHZ fhtsoftbuffer 0 # disable the fhtsoftbuffer
attr FHZ retrycount 4 # resend commands to FHT devices at most 4 times.
Notes:
setdefaultattr
setdefaultattr [<attrname> [<value>]]
Set the default attribute. Each device defined from now on will receive
this attribute (see the attr entry for details on
attribute names and values).
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.
Type FHZ
define <name> FHZ <serial-device>
Specifies the serial port to communicate with the FHZ 1000 PC. The name(s)
of the serial-device(s) depends on your distribution. The program can
service multiple devices, FS20 and FHT device commands will be sent out
through the last FHZ device defined before the definition of the FS20/FHT
device. To change the association, use the set command
activefor. Important: this definition must occur after the
modpath command but before any other (FHZ related) device definition,
else you'll see "no I/O device found" messages.
If the serial-device is called none, then no device will be opened, so you
can experiment without hardware attached.
Set the attribute "repeater" for this device to 1 to ignore events received
from a FS20 repeater. In fact we are not sure that they are repeater
messages, we just ignore messages which were sent out by our device for the
next 3 seconds (or configured otherwise by filtertimeout).
For GNU/Linux you may want to read our hints for
GNU/Linux about multiple USB
devices.
Note:The firmware of the FHZ1x00 will drop commands if the airtime
for the last hour would exceed 1% (which corresponds roughly to 163
commands). For this purpose there is a command counter for the last hour
(see list FHZDEVICE), which triggers with "TRANSMIT LIMIT EXCEEDED" if
there were more than 163 commands in the last hour.
Type FS20
define <name> FS20 <housecode> <button>
[fg <fgaddr>] [lm <lmaddr>] [gm FF]
The values of housecode, button, fg, lm, and gm can be either defined as
hexadecimal value or as ELV-like "quad-decimal" value with digits 1-4. We
will reference this ELV-like notation as ELV4 later in this document. You
may even mix both hexadecimal and ELV4 notations, because FHEM can detect
the used notation automatically by counting the digits.
<housecode> is a 4 digit hex or 8 digit ELV4 number,
corresponding to the housecode address.<button> is a 2 digit hex or 4 digit ELV4 number,
corresponding to a button of the transmitter.- The optional
<fgaddr> specifies the function group.
It is a 2 digit hex or 4 digit ELV address. The first digit of the hex
adress must be F or the first 2 digits of the ELV4 address must be
44.
- The optional
<lmaddr> specifies the local
master. It is a 2 digit hex or 4 digit ELV address. The last digit of the
hex address must be F or the last 2 digits of the ELV4 address must be
44.
- The optional gm specifies the global master, the adress must be FF if
defined as hex value or 4444 if defined as ELV4 value.
Examples:
define lamp FS20 7777 00 fg F1 gm F
define roll1 FS20 7777 01
define otherlamp FS20 24242424 1111 fg 4412 gm 4444
define otherroll1 FS20 24242424 1114
Type FHT
define <name> FHT <housecode>
<housecode> is a four digit hex number,
corresponding to the adress of the FHT80b device.
Examples:
See the FHT section in set for more.
Type HMS
define <name> HMS <housecode>
<housecode> is a four digit hex number,
corresponding to the adress of the HMS device.
Examples:
Notes:
- There is _NO_ guarantee that the code will work as expected in all
circumstances, the authors are not liable for any damage occuring as a
result of incomplete or buggy code
- Currently supported devices are the HMS100-T HMS100-TF HMS100-WD
HMS100-MG HMS100-TFK HMS100-CO HMS100-FIT RM100-2
- The housecode of the HMS devices may change if the battery is renewed.
In order to make life easier, you can define a "wildcard" device for each
type of HMS device. First the real device-id will be checked, then the
wildcard device id. The wildcards are:
- 1000 for the HMS100-TF
- 1001 for the HMS100-T
- 1002 for the HMS100-WD
- 1003 for the RM100-2
- 1004 for the HMS100-TFK/li>
- 1006 for the HMS100-MG
- 1008 for the HMS100-CO
- 100e for the HMS100-FIT
- Some battery low notifications are not yet implemented (RM100,
HMS100WD).
- Please test your installation before relying on the
functionality.
Type KS300
define <name> KS300 <housecode> [ml/raincounter [wind-factor]]
<housecode> is a four digit hex number,
corresponding to the adress of the KS300 device, right now it is ignored.
The ml/raincounter defaults to 255 ml, but it must be specified if you wish
to set the wind factor, which defaults to 1.0.
Examples:
Type WS300
define WS300Device WS300 <serial device>
or
define <devname> WS300 [0-9]
The first line is mandatory if you have a WS300 device: it defines the
input device with its USB port. The name of this device is fixed and must
be WS300Device. It must be the first defined WS300 device.
For each additional device (with number 0 to 9) you have to define another
WS300 device, with an arbitrary name. The WS300 device which reports the
readings will be defined with the port number 9, an optional KS300 with the
port number 8.
Examples:
define WS300Device WS300 /dev/ttyUSB1
define ash2200.1 WS300 0
define ks300 WS300 8
define ws300 WS300 9
Type EM
define <name> EM <em1010pc-device>
Define a EM1010PC USB device. From the software point of view there should
be no problems if you attach/define more than one EM1010PC, but it is
unknown if the low-level radio protocol supports this.
Currently there
is no way to read the internal log of the EM1010PC, use the program
em1010.pl in the contrib directory for this purpose.
Examples:
define em EM /dev/elv_em1010pc
Type EMWZ
define <name> EMWZ <device-number>
Define up to 4 EM1000WZ attached to the EM1010PC. The device number must
be between 1 and 4 (else you have a differnt device connected to the
EM1010PC). Defining an EMWZ will schedule an internal task, which reads the
status of the device every 5 minutes, and triggers notify/filelog commands.
Example:
Type EMEM
define <name> EMEM <device-number>
Define up to 4 EM1000EM attached to the EM1010PC. The device number must
be between 5 and 8.
Defining an EMEM will schedule an internal task, which reads the
status of the device every 5 minutes, and triggers notify/filelog commands.
Note: Currently this device does not support a "set" function.
Example:
Type EMGZ
define <name> EMGZ <device-number>
Define up to 4 EM1000GZ attached to the EM1010PC. The device number must
be 9.
Defining an EMGZ will schedule an internal task, which reads the
status of the device every 5 minutes, and triggers notify/filelog commands.
Example:
Type M232
define <name> M232 <m232-device>
Define a M232 device. You can attach as many M232 devices as you like. A
M232 device provides 6 analog inputs (voltage 0..5V with 10 bit resolution)
and 8 bidirectional digital ports. The eighth digital port can be used as a
16 bit counter (maximum frequency 3kHz). The M232 device needs to be
connected to a 25pin sub-d RS232 serial port. A USB-to-serial converter
works fine if no serial port is available.
Examples:
define m232 M232 /dev/ttyUSB2
Type M232Counter
define <name> M232Counter [unit [factor]]
Define at most one M232Counter for a M232 device. Defining a M232Counter
will schedule an internal task, which reads the status of the counter every
minute, and triggers notify/filelog commands. unit is the unit
name, factor is used to calculate the reading of the counter
from number of ticks.
Note: the unit defaults to the string
"ticks", but it must be specified if you wish to set the factor, which
defaults to 1.0. In the second example below one tick equals 1/1250th kWh.
Do not forget to start the counter (with set .. start for
M232) or to start the counter and set the reading to a specified value
(with set ... value for M232Counter).
Example:
define counter M232Counter turns
define counter M232Counter kWh 0.0008
Type M232Voltage
define <name> M232Voltage [an0..an5] [unit [factor]]
Define as many M232Voltages as you like for a M232 device. Defining a
M232Voltage will schedule an internal task, which reads the status of the
analog input every minute, and triggers notify/filelog commands.
unit is the unit name, factor is used to
calibrate the reading of the analog input.
Note: the unit defaults to the string "volts", but it must be specified
if you wish to set the factor, which defaults to 1.0.
Example:
define volt M232Voltage an0
define brightness M232Voltage an5 lx 200.0
Type SCIVT
define <name> SCIVT <SCD-device>
Define a SCD series solar controler device. Details see here.
You probably need a Serial to USB controller like the PL2303.
Defining an SCIVT device will schedule an internal task, which reads the
status of the device every 5 minutes, and triggers notify/filelog commands.
Note: Currently this device does not support a "set" function, only
a single get function which reads the device status immediately.
Example:
define scd SCIVT /dev/ttyUSB2
Type WS2000
define <name> WS2000<device_to_connect>
Define a WS2000 series raw receiver device sold by ELV. Details see here.
Unlike 86_FS10.pm it will handle the complete device communication itself and
doesnt require an external program.
For this reason you can now use this also on windows.
This Device will be usually connect to a serial port, but you can also
define a raw network redirector like lantronix XPORT(TM).
Note: Currently this device does not support a "set" function
Attributes:
rain: factor for calculating amount of rain in ml/countaltitude: height in meters to calculate pressure for NN(not used yet)
Example:
define WS2000 WS2000 /dev/ttyS0
define WS2000 WS2000 xport:10001
attr WS2000 rain 366 : use factor 366 ml/count for rain sensor S2000R
Type IPWE
define <name> IPWE <hostname> [<delay>]
Define a IPWE network attached weather data receiver device sold by ELV. Details see here.
It's intended to receive the same sensors as WS300 (8 T/H-Sensors and one kombi sensor),
but can be accessed via http and telnet.
For unknown reason, my try to use the telnet interface was not working neither with raw sockets
nor with Net::Telnet module. Therefore i choosed here the "easy" way
to simple readout the http page and extract all data from the offered table. For this reason this module doesnt
contain any option to configure this device.
Note: You should give your sensors a name within the web interface, once they a received the first time.
To extract a single sensor simply match for this name or sensor id
Attributes:
delay: seconds between read accesses(default 300s)
Example:
define ipwe IPWE ipwe1 120
attr ipwe delay 600 : 10min between readouts
Type FileLog
define <name> FileLog <filename> <regexp>
Log events to <filename>. The log format is
YYYY:MM:DD_HH:MM:SS <device> <event>
The regexp will be checked against the (complete!) device name
or against the (complete!) devicename:event combination.
<filename> may contain one or more of the following
wildcards (a subset of the Unix date command arguments):
%d day of month (01..31)%m month (01..12)%Y year (1970...)
%w day of week (0..6); 0 represents Sunday
%j day of year (001..366)
%U week number of year with Sunday as first day of week (00..53)
%V week number of year with Monday as first day of week (01..53)
Examples:
define lamplog FileLog /var/tmp/lamp.log lamp
define wzlog FileLog /var/tmp/wz-%Y-%U.log
wz:(measured-temp|actuator).*
Type DbLog
define <name> DbLog <configfilename> <regexp>
Log events to a database. The database connection is defined in
<configfilename> (see sample configuration file
db.conf). The configuration is stored in a separate file
to avoid storing the password in the main configuration file and to have it
visible in the output of the list command.
You must have 93_DbLog.pm in the FHEM subdirectory
to make this work. Additionally, the modules DBI and
DBD::<dbtype> need to be installed (use
cpan -i <module> if your distribution does not have it).
<regexp> is the same as in FileLog.
Sample code to create a MySQL database is in fhemdb_create.sql.
The database contains two tables: current and
history. The latter contains all events whereas the former only
contains the last event for any given reading and device.
The columns have the following meaning:
- TIMESTAMP: timestamp of event, e.g.
2007-12-30 21:45:22
- DEVICE: device name, e.g.
Wetterstation
- TYPE: device type, e.g.
KS300
- EVENT: event specification as full string,
e.g.
humidity: 71 (%)
- READING: name of reading extracted from event,
e.g.
humidity
- VALUE: actual reading extracted from event,
e.g.
71
- UNIT: unit extracted from event, e.g.
%
The content of VALUE is optimized for automated post-processing, e.g.
yes is translated to 1.
The current values can be retrieved by means of the perl script
fhemdb_get.pl. Its output is adapted to what a
Cacti data input method expects.
Call fhemdb_get.pl without parameters to see the usage
information.
Examples:
# log everything to database
define logdb DbLog /etc/fhem/db.conf .*:.*
Type at
define <name> at <timespec> <command>
Start an arbitrary fhem.pl command at a later time.
<timespec> format: [+][*{N}]<timedet>
The optional + indicates that the specification is
relative(i.e. it will be added to the current time).
The optional * indicates that the command should be
executed repeatedly.
The optional {N} after the * indicates,that the command
should be repeated N-times only.
<timedet> is either HH:MM, HH:MM:SS or {perlfunc()}, where perlfunc
must return a HH:MM or HH:MM:SS date.
Examples:
# absolute ones:
define a1 at 17:00:00 set lamp on # fhem command
define a2 at 17:00:00 { Log 1, "Teetime" } # Perl command
define a3 at 17:00:00 "/bin/echo "Teetime" > /dev/console" # shell command
define a4 at *17:00:00 set lamp on # every day
# relative ones
define a5 at +00:00:10 set lamp on # switch the lamp on in 10 seconds
define a6 at +00:00:02 set lamp on-for-timer 1 # Blink once in 2 seconds
define a7 at +*{3}00:00:02 set lamp on-for-timer 1 # Blink 3 times
# Blink 3 times if the piri sends a command
define n1 notify piri:on.* define a8 at +*{3}00:00:02 set lamp on-for-timer 1
# Switch the lamp on from sunset to 11 PM
# Copy 99_SUNRISE_EL.pm in the FHEM directory to have sunset_rel()
{ sunrise_coord("8.686", "50.112", "") }
define a9 at +*{sunset_rel()} set lamp on
define a10 at *23:00:00 set lamp off
# More elegant version, works for sunset > 23:00 too
define a11 at +*{sunset_rel()} set lamp on-till 23:00
# Only do this on weekend
define a12 at +*{sunset_rel()} { fhem("set lamp on-till 23:00") if($we) }
# Switch lamp1 and lamp2 on from 7:00 till 10 minutes after sunrise
define a13 at *07:00 set lamp1,lamp2 on-till {sunrise_abs(+600)}
# Switch the lamp off 2 minutes after sunrise each day
define a14 at +*{sunrise_rel(+120)} set lamp on
Notes:
- if no
* is specified, then a command will be executed
only once, and then the at entry will be deleted. In
this case the command will be saved to the statefile (as it
considered volatile, i.e. entered by cronjob) and not to the
configfile (see the save command.)
- if the current time is greater then the time specified, then the
command will be executed tomorrow. This is why the relative forms
of the sunset/sunrise functions should be used with the relative
(+) flag
- In order to use the sunrise_rel()/sunset_rel() functions,
put { sunrise_coord(long, lat, "") } into your
lastinclude file, as in the above example.
If you are not using sunrise_coord, then the coordinates for
Frankfurt am Main, Germany will be used.
- For even more complex date handling you either have to call fhem from
cron or filter the date in a perl expression, see the last example and
the section Perl special.
Type watchdog
define <name> watchdog <regexp1> <timespec> <regexp2> <command>
Start an arbitrary fhem.pl command if after <timespec> receiving an
event matching <regexp1> no event matching <regexp2> is
received.
The syntax for <regexp1> and <regexp2> is the same as the
regexp for notify.
<timespec> is HH:MM[:SS]
<command> is a usual fhem command like used int the at or notify
Examples:
# "Reset" the FHT80 if we do not receive any message for 15 Minutes
define w watchdog FHT80 00:15:00 SAME set FHT80 refreshvalues
# Shout if the HMS100-FIT is not alive
define w watchdog HMS100-FIT 01:00:00 SAME "alarm-fit.sh"
Notes:
- if <regexp1> is . (dot), then activate the watchdog at
definition time. Else it will be activated when the first matching event
is received.
- if <regexp2> is SAME, then it will be the same as the first
regexp, and it will be reactivated, when it is received. This is probably
the normal operation.
Type notify
define <name> notify <pattern> <command>
Execute a command when received an event for the definition <pattern>. If
<command> 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:
define b3lampV1 notify btn3 set lamp %
define b3lampV2 notify btn3 { fhem "set lamp %" }
define b3lampV3 notify btn3 "/usr/local/bin/setlamp "%""
define b3lampV3 notify btn3 set lamp1 %;;set lamp2 %
define wzMessLg notify wz:measured.* "/usr/local/bin/logfht @ "%""
define LogUndef notify 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.
- The character
@ will be replaced with the device
name.
- To use % or @ in the text itself, use the double mode (%% or @@).
- Instead of
% and @, the parameters
%EVENT (same as %), %NAME
(same as @) and %TYPE (contains the device
type, e.g. FHT) can be used. A single %
looses its special meaning if any of these parameters appears in the
definition.
<pattern> may also be a compound of
definition:event to filter for events.<pattern> 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.pm 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.
Type weblink
define <name> weblink [link|fileplot] <argument>
This is a placeholder used with webpgm2 to be able to integrate links
into it, and to be able to put more than one gnuplot/SVG picture on one
page. It has no set or get methods.
Examples:
define wl_1 weblink link http://www.fhem.de
define wl_2 weblink fileplot <logdevice>:<gnuplot-file>:<logfile>
Notes:
- Normally you won't have to define fileplot weblinks manually, as
FHEMWEB makes it easy for you, just plot a logfile (see
logtype) and convert it to weblink. Now you
can group these weblinks by putting them into rooms. If you convert
the current logfile to a weblink, it will always refer to the current
file (and not the one you originally specified).
Type dummy
define <name> dummy
Define a dummy. A dummy can take via set any values.
Used for programming.
Example:
define myvar dummy
set myvar 7
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>.
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 commands by
get <device> ?
See the Device specification section for details on
<devspec>.
Type FHZ:
get FHZ <value>
where value is one of:
init1
init2
init3
serial
fhtbuf
Notes:
- The mentioned codes are needed for initializing the FHZ1X00
- The answer for a command is also displayed by
list FHZ
-
The FHZ1x00PC has a message buffer for the FHT (see the FHT entry in
the set section). If the buffer is full, then newly
issued commands will be dropped, if the attribute fhtsoftbuffer is not set.
fhtbuf returns the free memory in this buffer (in hex),
an empty buffer in the FHZ1000 is 2c (42 bytes), in the FHZ1300 is 4a
(74 bytes). A message occupies 3 + 2x(number of FHT commands) bytes,
this is the second reason why sending multiple FHT commands with one
set is a good idea. The first reason is, that
these FHT commands are sent at once to the FHT.
Type EM:
get EM <value>
where value is either version or time.
Type EMWZ:
get EMWZ status
This is the same command which is scheduled every 5 minutes internally.
Type M232:
get <name> [an0..an5]
Gets the reading of analog input 0..5 in volts.
get <name> [io0..io7]
Gets the state of digital ports 0..7, result is 0 or 1.
get <name> octet
Gets the state of all digital ports at once, result is 0..255.
get <name> counter
Gets the number of ticks of the counter since the last reset. The counter
wraps around from 65535 to 0.
Type M232Counter:
get <name> status
Gets the reading of the counter multiplied by the factor from the
define statement. Wraparounds of the counter are accounted for
by an offset (see reading basis in the output of the
list statement for the device).
Type WS2000:
get <name> list
Gets the last reading of all received sensord
get <name> [TH0..TH7, T0..T7, I0..I7, R0..R7, W0..W7, L0..L7, P0..P7,LAST,RAW]
get the last reading for the name sensor,
LAST: Last received Sensor
RAW: original Data from interface
Type IPWE
get <name> status
Gets actual data from device for sensors with data
get <name> < sensorname>
will grep output from device for this sensorname
Type FileLog
get <name> <infile> <outfile> <from>
<to> <column_spec>
Read data from the logfile.
- <infile>
Name of the logfile to grep. "-" is the current logfile, or you can
specify an older file (or a file from the archive).
- <outfile>
If it is "-", you get the data back on the current connection, else it
is the prefix for the output file. If more than one file is specified,
the data is separated by a comment line for "-", else it is written in
separate files, numerated from 0.
- <from> <to>
Used to grep the data. The elements should correspond to the
timeformat or be an initial substring of it.
- <column_spec>
For each column_spec return a set of data in a separate file or
separated by a comment line on the current connection.
Syntax: <col>:<regexp>:<default>:<fn>
- <col>
The column number to return, starting at 1 with the date.
If the column is enclosed in double quotes, then it is a fix text,
not a column nuber.
- <regexp>
If present, return only lines containing the regexp. Case sensitive.
- <default>
If no values were found and the default value is set, then return
one line containing the from value and this default. We need this
feature as gnuplot aborts if a dataset has no value at all.
- <fn>
One of the following:
- int
Extract the integer at the beginning og the string. Used e.g.
for constructs like 10%
- delta-h or delta-d
Return the delta of the values for a given hour or a given day.
Used if the column contains a counter, as is the case for the
KS300 rain column.
- everything else
The string is evaluated as a perl expression. @fld is the
current line splitted by spaces. Note: The string/perl
expression cannot contain spaces, as the part after the space
will be considered as the next column_spec.
Example:
get outlog out-2008.log - 2008-01-01 2008-01-08 4:IR:int: 9:IR::
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 [devspec]
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>.
Example:
FHZ> 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.:
FHZ> 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%
2006-10-28 15:10:58 code_0000aa 17
2006-10-07 10:52:09 code_0000ba 0
2006-11-02 10:40:08 code_4b004b 0
2006-11-02 08:24:46 code_7e0067 0
2006-11-02 04:13:35 day-temp 21.0 (Celsius)
2006-11-02 06:03:37 desired-temp 21.0 (Celsius)
2006-11-02 04:13:31 fri-from1 06:00
2006-11-02 04:13:31 fri-to1 23:50
2006-11-02 04:13:36 lowtemp-offset 2.0 (Celsius)
2006-11-02 10:40:06 measured-high 0
2006-11-02 10:40:06 measured-low 211
2006-11-02 10:40:06 measured-temp 21.1 (Celsius)
2006-11-02 04:13:39 mode auto
2006-11-02 04:13:25 mon-from1 06:00
2006-11-02 04:13:25 mon-to1 23:00
2006-11-02 04:13:35 night-temp 18.0 (Celsius)
2006-11-02 04:13:32 sat-from1 08:00
2006-11-02 04:13:33 sat-to1 23:50
2006-11-02 04:13:34 sun-from1 08:00
2006-11-02 04:13:34 sun-to1 23:00
2006-11-02 04:13:29 thu-from1 06:00
2006-11-02 04:13:29 thu-to1 23:00
2006-11-02 04:13:26 tue-from1 06:00
2006-11-02 04:13:26 tue-to1 23:00
2006-11-02 10:40:07 warnings Battery low
2006-11-02 04:13:27 wed-from1 06:00
2006-11-02 04:13:28 wed-to1 23:00
2006-11-02 04:13:36 windowopen-temp 12.0 (Celsius)
Send buffer:
2007-10-19 00:31:24 desired-temp 22.5
2007-10-19 00:33:20 mode auto
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 deinition, 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. Mainly intended to reload
the 99_PRIV file (or equivalent) in order to test perl-scripts.
Example:
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:
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 commands
which were previously part of the config file. Put such commands in the
lastinclude file.
set
set <devspec> <type-specific>
Set parameters of a device / send signals to a device. You can
get a list of possible commands by
set <name> ?
See the Device specification section for details on
<devspec>.
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:
define fhz_timer at +*00:01:00 set FHZ time
See the loglevel 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 at 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:
desired-temp
day-temp night-temp
report1 report2
mode
holiday1 holiday2 # Not verified
manu-temp # No clue what it does.
year month day hour minute
lowtemp-offset # Alarm-Temp.-Differenz
windowopen-temp
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
Examples:
set wz desired-temp 22.5
set fl desired-temp 20.5 day-temp 19.0 night-temp 16.0
Notes:
- Following events are reported (more or less regularly) by each FHT
device:
measured-temp actuator actuator1...actuator8 warnings
You can use these strings for notify or
FileLog definitions.
- warnings can contain following strings:
none, Battery low,Temperature too low, Window open,
Fault on window sensor
- actuator (without a suffix) stands for all actuators.
- actuator or actuator1..8 can take following values:
- <value>%
This is the normal case, the actuator is instructed to open to this value.
- offset <value>%
The actuator is running with this offset.
- lime-protection
The actuator was instructed to execute the lime-protection procedure.
- synctime
If you select Sond/Sync on the FHT80B, you'll see a count down.
- test
The actuator was instructed by the FHT80b to emit a beep.
- pair
The the FHT80b sent a "you-belong-to-me" to this actuator.
Note:
- The FHT is very economical (or lazy), it accepts one message from the
FHZ1x00 every 2 minutes (or so). Don't be surprized if your command
is only accepted 10 minutes later by the device. FHT commands are
buffered in the FHZ1x00 till they are sent to the FHT, see the related
fhtbuf entry in the get
section.
You can send up to 8 commands in one message at once to the FHT if
you specify them all as arguments to the same set command, see the
example above.
- All
*-temp values need a temperature
as argument, which will be rounded to 0.5 Celsius.
Temperature values must between 5.5 and 30.5 Celsius. Value 5.5 set
the actuator to OFF, value 30.5 set the actuator to ON
mode is one of auto, manual, holiday or
holiday_short.
If the mode is holiday, then
- holiday1 sets the end-day of the holiday
- holiday2 sets the end-month of the holiday
For holiday_short
- holiday1 sets the time, in 10-minute steps
- holiday2 sets number of days from now on.
- 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.
- As the FHT stops sending the values every 5-10
days, it is adviseable to schedule following command regularly:
define fht_report at +*06:00:00
set <name> report1 255 report2 255
report1 with parameter 255 requests all settings for
monday till sunday to be sent. The argument is a bitfield, to request
unique values add up the following:
- 1: monday
- 2: tuesday
- 4: thursday
- 8: wednesday
- 16: friday
- 32: saturday
- 64: sunday
measured-temp and actuator is sent along if it is considered appropriate
by the FHT.
report2 with parameter 255 requests the following
settings to be reported: day-temp night-temp windowopen-temp
lowtemp-offset desired-temp measured-temp mode warnings.
The argument is (more or less) a bitfield, to request unique values
add up the following:
- 1: warnings
- 2: mode
- 4: day-temp, night-temp, windowopen-temp
- 64: lowtemp-offset
measured-temp and actuator is sent along if it is considered appropriate
by the FHT.
lowtemp-offset needs a temperature as argument, valid
values must be between 1.0 and 5.0 Celsius.
It will trigger a
warning if desired-temp - measured-temp >
lowtemp-offset in a room for at least 1.5 hours after the last
desired-temp change.
- FHEM optionally has an internal software buffer for FHT devices.
This buffer should prevent transmission errors. If there is no
confirmation for a given period, FHEM resends the command. You can
see the queued commands with list
<fht-device>.
See the fhtsoftbuffer,
retrycount and
minfhtbuffer attributes for details.
- If a buffer is still in the softbuffer, it will be sent in the
following order:
desired-temp,mode,report1,report2,
holiday1,holiday2,day-temp,night-temp, [all other commands]
Type WS300:
set WS300Device <interval(min.)> <height(m)> <rainvalume(ml)>
Set some WS300 configuration parameters.
Type EMWZ:
set EMWZdevice <param> <value>
where param is one of:
- rperkw
Number of rotations for a KiloWatt of the EM1000WZ device (actually
of the device where the EM1000WZ is attached to). Without setting
this correctly, all other readings will be incorrect.
- alarm
Alarm in WATT. if you forget to set it, the default value is
rediculously low (random), and if a value above this threshold is
received, the EM1010PC will start beeping once every minute. It can
be very annoying.
- price
The price of one KW in EURO (use e.g. 0.20 for 20 Cents). It is used
only on the EM1010PC display, it is of no interest for FHEM.
Type M232:
set <name> stop
Stops the counter.
set <name> start
Resets the counter to zero and starts it.
set <name> octet
Sets the state of all digital ports at once, value is 0..255.
set <name> [io0..io7] 0|1
Turns digital port 0..7 off or on.
Type M232Counter:
set <name> value <value>
Sets the reading of the counter to the given value. The counter is reset
and started and the offset is adjusted to value/unit.
Type FileLog:
set <name> reopen
Used to reopen a FileLog after making some manual changes to the logfile.
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:
setstate lamp on
Note:
- The statefile uses another version of this command, don't be surprised.
shutdown
trigger
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"/>
[...]
Device specification
The commands
attr,
deleteattr,
delete,
get,
list,
set,
setstate,
trigger
can take a more complex device specification as argument,
which will be expanded to a list of devices. A devspec can be:
- a list of devices, separated by comma (,)
- a range of devices, separated by dash (-)
- a regular expression, if the the spec contains on e of the following
characters: ^*[]$
Example:
set lamp1,lamp2,lamp3 on
set lamp[1-3] on
set lamp.* on
set lamp1-lamp3 on
set lamp1-lamp3,lamp3 on
Notes:
- first the spec is separated by komma, then the range or the regular
expression operations are executed.
- if there is a device which xactly corresponds to the spec, then
no special processing is done.
- the returned list can contain the same device more than once, so
int tha last example the list will contain lamp3 twice.
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"} }
-
By using the 99_SUNRISE_EL.pm module, you have access to the following
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.