mirror of
https://github.com/fhem/fhem-mirror.git
synced 2025-01-31 12:49:34 +00:00
402 lines
17 KiB
HTML
402 lines
17 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
|
<head>
|
|
<title>FHEM Howto</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css" />
|
|
<meta http-equiv="Content-type" content="text/html;charset=ISO-8859-1"/>
|
|
</head>
|
|
|
|
|
|
<body>
|
|
|
|
<div id="logo"></div>
|
|
<div id="menu">
|
|
<h3>FHEM Howto</h3>
|
|
</div>
|
|
|
|
|
|
<div id="right">
|
|
<!--
|
|
<a href="#starting">Starting</a><br>
|
|
<a href="#FHZ">Attaching an FHZ/CUL</a><br>
|
|
<a href="#FS20rx">Configuring FS20 receivers</a><br>
|
|
<a href="#FS20tx">Configuring FS20 transmitters</a><br>
|
|
<a href="#FHT">Configuring FHT devices</a><br>
|
|
<a href="#at">Timed commands / Notify</a><br>
|
|
<a href="#rooms">FHEMWEB look and feel</a><br>
|
|
<a href="#log">Logging data</a><br>
|
|
<a href="#plot">Plotting logs</a><br>
|
|
<a href="#tips">FHEMWEB tips</a><br>
|
|
<a href="#structure">Complex structures</a><br>
|
|
-->
|
|
|
|
|
|
<a name="starting"></a>
|
|
<h3>Starting fhem</h3>
|
|
<ul>
|
|
Skip this section if you installed fhem via the Debian <a
|
|
href="http://fhem.de/fhem-=VERS=.deb">package</a>, the Fritz!Box 7390
|
|
<a href="http://fhem.de/fhem-=VERS=-fb7390.image">image</a>, or the FB
|
|
7170/7270 <a href="http://fhem.de/fhem-=VERS=.fb7270.zip">zip file</a>.
|
|
<br><br>
|
|
|
|
As most fhem installations access the "outer world" via a USB device
|
|
connected to the fhem computer (CUL, FHZ1x00, etc), we most probably need
|
|
the perl serial module.<br>
|
|
|
|
This is why you should first install the Device::SerialPort (or
|
|
Win32::SerialPort) perl module with the command <code>"sudo cpan
|
|
Device::SerialPort"</code>. There are also precompiled debian packages
|
|
(libdevice-serialport-perl), and this module is already installed on OSX
|
|
10.6. If you cannot install it, you then take a look at the directio
|
|
option<br><br>
|
|
|
|
The default configuration will install fhem into /usr/bin,
|
|
/usr/share/fhem and /var/log/fhem and /etc/fhem.cfg, according to the
|
|
debian/ubuntu requirments. Edit the Makefile to change this.
|
|
|
|
To install & start fhem type:<pre>
|
|
make install-pgm2
|
|
perl /usr/bin/fhem.pl /etc/fhem.cfg</pre>
|
|
|
|
After starting, the logfile should look like:<pre>
|
|
2008.06.15 16:17:03 2: FHEMWEB port 8083 opened
|
|
2008.06.15 16:17:03 2: FHEMWEB port 8084 opened
|
|
2008.06.15 16:17:03 2: FHEMWEB port 8085 opened
|
|
2008.06.15 16:17:03 0: Server started (version ...)</pre>
|
|
</ul>
|
|
|
|
<a name="FHZ"></a>
|
|
<h3>Attaching the USB device for the PC (CUL / FHZ1x00PC / etc)</h3>
|
|
<ul>
|
|
Connect to fhem with an internet browser:
|
|
<a href="http://localhost:8083/fhem">http://fhem-host:8083/fhem</a>
|
|
if you are using a normal desktop,
|
|
<a href="http://localhost:8084/fhem">http://fhem-host:8084/fhem</a> if
|
|
you are using a smartphone, or
|
|
<a href="http://localhost:8084/fhem">http://fhem-host:8085/fhem</a> if
|
|
you are using a tablet like the iPad.<br><br>
|
|
|
|
Attach the USB device (CUL, FHZ1000PC/FHZ1300, TUL, EUL, etc) to your
|
|
computer, and look for the corresponding device in the /dev
|
|
directory. For <a href="commandref.html#CUL">CUL</a> a file named
|
|
/dev/ttyACM* will be created under
|
|
Linux and /dev/cu.usbmodem* under OS X. Note the exact name of the device.
|
|
Define it for fhem (by typing it in the "Fhem cmd" input field in the
|
|
browser):<pre>
|
|
define CUL1 CUL /dev/ttyACM0@9600 1234</pre>
|
|
|
|
You can find details about CUL define parameters <a
|
|
href="commandref.html#CUL">here</a>.<br><br>
|
|
|
|
The same is to be done for the <a href="commandref.html#FHZ">FHZ</a> with
|
|
slightly different parameters:<pre>
|
|
define FHZ1 FHZ /dev/ttyUSB0</pre>
|
|
For the FHZ on OSX you need to install the ftdi driver first from <a
|
|
href="http://www.ftdichip.com/Drivers/VCP.htm">
|
|
http://www.ftdichip.com/Drivers/VCP.htm</a>, the device name will be
|
|
/dev/cu.usbserial-xxxxxxxx.
|
|
|
|
<br><br>
|
|
<b>Notes:</b>
|
|
<ul>
|
|
<li>Don't forget to type "save" in the "Fhem cmd" input field of the
|
|
browser after defining a device or setting its attribute. Otherwise
|
|
the changes will disappear after the next start.
|
|
<li>The CUL is arriving without a firmware. You can flash it via the
|
|
<a href="commandref.html#CULflash">CULflash</a> command, if the
|
|
dfu-programmer is installed. dfu-programmer is part of the FB7390 image.
|
|
</ul>
|
|
</ul>
|
|
|
|
<a name="autocreate"></a>
|
|
<h3>Configuring transmitter devices (sensors)</h3>
|
|
<ul>
|
|
The sample configuration file installed via "make install-pgm2" has
|
|
configured an <a href="commandref.html#autocreate">autocreate</a>
|
|
instance. This will automatically create fhem devices upon reception
|
|
of a message from this device (typically a sensor like S300 or FHT).
|
|
Just wait for a while, watch the log and re-check your browser for newly
|
|
appeared devices. You can use <a href="commandref.html#rename">
|
|
rename</a> to rename the automatically created device, e.g. type in the
|
|
input field of the web frontend:
|
|
<ul><code>
|
|
rename FHT_1234 fht.kitchen</pre>
|
|
</code></ul>
|
|
|
|
<b>Note</b>: if you rename the device itself, the attached FileLog
|
|
and weblink will be renamed automatically. The other way round (renaming
|
|
the FileLog or weblink) will not rename the associated devices
|
|
automatically.<br><br>
|
|
|
|
If you want to do the same manually:<br>
|
|
Wait a while, until the transmitter sent some data. In the logfile
|
|
(Browser window: "Unsorted -> Logs / Fhemlog / text) a line
|
|
will appear:
|
|
<ul><code>
|
|
FS20 Unknown device <HOUSECODE>, Button <BTN> Code <CDE>, please define it
|
|
</code></ul>
|
|
|
|
Now define the fhem device:
|
|
<ul><code>
|
|
define piri1 FS20 <HOUSECODE> <BTN>
|
|
</code></ul>
|
|
|
|
Set the model attribute of the device:
|
|
<ul><code>
|
|
attr piri1 model fs20piri
|
|
</code></ul>
|
|
|
|
to get only the commands available for this device.
|
|
<a href="commandref.html#model">Here</a> is a complete list of FS20
|
|
models.<br> For other device types similar messages should appear.<br><br>
|
|
|
|
<b>Note:</b> Creating a fhem FHT or HomeMatic device automatically or
|
|
manually does not imply that the CUL or the FHZ is paired with it. For
|
|
this purpose you have to set the FHT to accept new devices
|
|
(Prog:Cent:N/A), and send a command to it (e.g. set fht.kitchen
|
|
desired-temp 20). If there is no signal for a while, then check <a
|
|
href="faq.html#faq6"> this</a> FAQ entry.
|
|
</ul>
|
|
|
|
<a name="FS20rx"></a>
|
|
<h3>Configuring FS20 receivers (actors)</h3>
|
|
<ul>
|
|
Configure the <a href="commandref.html#FS20">FS20</a> device in
|
|
fhem first with:<pre>
|
|
define lamp1 FS20 1234 56</pre>
|
|
|
|
Now press the button on the real device for a while until its LED starts to
|
|
blink. Click on the "on" link in the fhem window to send a command. The
|
|
LED should terminate blinking, the device is programmed to housecode
|
|
1234, device code 56. You can also use the 4-base ELV notation.
|
|
Now set the model attribute of the device:<pre>
|
|
attr lamp1 model fs20st</pre>
|
|
|
|
to get only the commands available for this device.<br><br>
|
|
|
|
Other systems (EnOcean/HomeMatic) require a more elaborate procedure, and
|
|
the corresponding USB device is to be set into a pairing mode first. See
|
|
the commandref entry for your device.
|
|
</ul>
|
|
|
|
|
|
|
|
<a name="at"></a>
|
|
<h3>Timed commands / Notification</h3>
|
|
<ul>
|
|
To execute commands at a given time / periodically, you have to define
|
|
devices of the type <b>at</b>. See the definition <a href="commandref.html#at">
|
|
here</a> and the examples <a href="example.06_at">here</a>. The last link
|
|
only works if you are reading this HOWTO from your fhem Web.<br><br>
|
|
|
|
To execute commands if a device sent a message you have to define
|
|
devices of the type <a href="commandref.html#notify">notify</a> or
|
|
<a href="commandref.html#watchdog">watchdog</a>. In order to understand
|
|
the fhem events better you can open a telnet session to your fhem<pre>
|
|
telnet localhost 7072</pre>
|
|
|
|
and type <pre>
|
|
inform timer</pre>
|
|
|
|
Now you will receive in this telnet session all events, just like the
|
|
notifies/watchdogs do. You can even simulate events by using the
|
|
<a href="commandref.html#trigger">trigger</a> command:<pre>
|
|
trigger lamp1 on</pre>
|
|
|
|
For a more complex automation you can either control fhem by an external
|
|
program via telnet or HTTP, or (the usual way) do this via the fhem at
|
|
and notify commands. at and notify takes either simple fhem commands,
|
|
shell skripts or "perl oneliners" as argument. For details and tips on
|
|
the perl oneliners read the <a href="commandref.html#perl">Perl
|
|
specials</a> section in the commandref.html</ul>
|
|
|
|
<a name="rooms"></a>
|
|
<h3>FHEMWEB (pgm2) look and feel</h3>
|
|
<ul>
|
|
It makes sense to group your devices into rooms by setting the room
|
|
attribute. FHEMWEB puts devices without a room attribute into the
|
|
"Unsorted" room. Devices in the room "hidden" will not be shown.
|
|
<br><br>
|
|
You can also define a stripped down FHEMWEB instance, by defining the
|
|
Menu entries to be hidden in the
|
|
<a href="commandref.html#hiddenroom">hiddenroom</a> FHEMWEB attribute.
|
|
<br><br>
|
|
|
|
|
|
Set the title of the webpage by setting the <code>title</code> attribute
|
|
of the global device ("All together" -> global)<br><br>
|
|
|
|
Edit the colors / fonts by changing the style.css ("Edit files" ->
|
|
style.css), or create you own style (see <a
|
|
href="commandref.html#stylesheetPrefix">stylesheetPrefix</a> , so it
|
|
won't be overwritten by the next <a
|
|
href="commandref.html#updatefhem">updatefhem</a> command.
|
|
<br><br>
|
|
|
|
Further FHEMWEB attributes:
|
|
<a href="commandref.html#webname">webname</a>,
|
|
<a href="commandref.html#plotmode">plotmode</a>,
|
|
<a href="commandref.html#plotsize">plotsize</a>.
|
|
</ul>
|
|
|
|
|
|
<a name="log"></a>
|
|
<h3>Logging data</h3>
|
|
<ul>
|
|
To log messages into files, define devices of the type <a
|
|
href="commandref.html#FileLog">FileLog</a>. Autocreate will create
|
|
logfiles for newly detected devices, or you can use <a
|
|
href="commandref.html#createlog">createlog</a> in order to add a FileLog
|
|
later.<br>
|
|
|
|
To log messages into a
|
|
database, see the contrib/dblog directory in the fhem
|
|
distribution.<br><br>
|
|
|
|
FHEMWEB has builtin support for displaying FileLog type logs as plots,
|
|
see the <a href="#plot">plot</a> section below.<br><br>
|
|
|
|
The size of each logfile will be determined by its wildcard characters
|
|
(year/month/week/day), look at the <a href="commandref.html#FileLog">
|
|
FileLog</a> definition.
|
|
Don't forget to enable archiving with the <a
|
|
href="commandref.html#nrarchive">nrarchive</a> or <a
|
|
href="commandref.html#archivedir">archivecmd</a> attributes.
|
|
</ul>
|
|
|
|
<a name="plot"></a>
|
|
<h3>Plotting logs</h3>
|
|
<ul>
|
|
Autocreate will create weblinks (i.e. plots) for newly detected devices.
|
|
The following section describes how to do it manually, e.g. if you want
|
|
to plot data from different sensors together.<br><br>
|
|
|
|
To convert a FileLog into a plot (chart) in FHEMWEB, set the
|
|
<a href="commandref.html#logtype">logtype</a> attribute of the
|
|
corresponding FileLog. Take a look at the available gnuplot files in the
|
|
"Edit files" section, they contain the corresponding FileLog definition
|
|
example.<br>
|
|
Note that the .gplot files are also used if you use SVG output and
|
|
not the gnuplot backend!<br>
|
|
Examples:<pre>
|
|
attr em1000log logtype power8:Power,text
|
|
attr fs20_log logtype fs20:Plot,text
|
|
attr hms100th_log logtype temp4hum6:Plot,text
|
|
</pre>
|
|
|
|
When displaying the plot, you can convert it into a
|
|
<a href="commandref.html#weblink">weblink</a>, which
|
|
has its own attributes. If the weblink refers to the current
|
|
logfile, then it will be stored as a CURRENT weblink, and it will always
|
|
display the most recent log (you do not have to redefine it if the
|
|
logfile changes due to year/month/date parameters in its name).
|
|
|
|
<br><br>
|
|
|
|
|
|
The logs can be converted to a plot either with gnuplot (which must be
|
|
installed and in your PATH), or via the builtin SVG module, in this case
|
|
your browser must support SVG. All browsers support SVG, the notable
|
|
exception is Internet Explorer prior to version 9 and Android prior to
|
|
version 3.0. For such Android devices try Opera or Firefox.<br><br>
|
|
|
|
SVG mode is the default, to change it set the <a
|
|
href="commandref.html#plotmode">plotmode</a> attribute to gnuplot or
|
|
gnuplot-scroll.<br><br>
|
|
|
|
In order to look at historic data, you can either convert the
|
|
archive entries to a weblink in "plotmode=gnuplot" mode, or use the
|
|
"plotmode=gnuplot-scroll" or "plotmode=SVG" modes. gnuplot-scroll and SVG
|
|
offer the possibility to zoom or scroll in the plot, see the arrow and
|
|
magnifier icons at the top of the page.<br><br>
|
|
|
|
Note: the gnuplot files must have #FileLog entries in order to be useable
|
|
with gnuplot-scroll or SVG (these lines are treated as comment by
|
|
gnuplot, but not by fhem!), as the filtering happens with the FileLog get
|
|
function, see the supplied gnuplot files or the column_spec paragraph <a
|
|
href="commandref.html#FileLogget">here</a> for the syntax.<br><br>
|
|
|
|
The order of the #FileLog lines must match the corresponding 'awk'
|
|
entries.<br><br>
|
|
|
|
I recommend using log files with year resolution, this is determined by
|
|
its wildcard characters (year/month/week/day), look at the FileLog
|
|
definition.
|
|
</ul>
|
|
|
|
<a name="tips"></a>
|
|
<h3>FHEMWEB tips</h3>
|
|
<ul>
|
|
Click on the State link on the detail page to get a documentation of
|
|
all its settable values, similarly clicking on "Attribute" will guide you
|
|
to the documentation of its attributes.
|
|
<br><br>
|
|
|
|
There are two different ways to enable <b>Password and HTTPS</b><br><br>
|
|
<ul>
|
|
<li>Using the builtin features of FHEMWEB for <a
|
|
href="commandref.html#basicAuth">basic</a> html authentication and <a
|
|
href="commandref.html#HTTPS">HTTPS</a>. The perl modules needed for
|
|
HTTPS are missing from the FritzBox distribution, I recommend a direct
|
|
VPN connection here.<br><br>
|
|
|
|
|
|
|
|
<li>Using apache to implement this features, and redirect a certain prefix to
|
|
each FHEMWEB instance.<br>
|
|
Add the following lines to your httpd.conf:<pre>
|
|
<Proxy *>
|
|
AuthType Basic
|
|
AuthName "Password Required"
|
|
AuthUserFile /home/httpd/etc/passwd
|
|
Require valid-user
|
|
Allow from 127.0.0.1
|
|
</Proxy>
|
|
ProxyPass /fhem http://localhost:8083/fhem
|
|
ProxyPassReverse /fhem http://localhost:8083/fhem</pre>
|
|
|
|
and then restart httpd with apachectl graceful. To create the password
|
|
file, execute<br>
|
|
htpasswd -c /home/httpd/etc/passwd <username>
|
|
<br>
|
|
See also <a href="http://fhemwiki.de/index.php/Apache_Authentication_Proxy">
|
|
this</a> fhemwiki entry for a more detailed description.
|
|
<br><br>
|
|
|
|
To enable HTTPS, please check the web. In essence:<br>
|
|
<ul>
|
|
<li>Edit httpd.conf, add:<pre>
|
|
LoadModule ssl_module lib/apache/mod_ssl.so
|
|
Include /etc/httpd/conf/ssl.conf</pre></li>
|
|
<li>Create a server certificate</li>
|
|
<li>Start httpd with the startssl option (SSL or the like must be set in
|
|
one of your system files, look at /etc/init.d/httpd).</li>
|
|
</ul>
|
|
<br><br>
|
|
</ul>
|
|
|
|
To display "foreign" (non fhem) files as a plot or just as plain text,
|
|
configure a fake logfile with the correct filename and an unused regexp,
|
|
e.g.<br><pre>
|
|
define messages FileLog /var/log/messages fakelog</pre>
|
|
</ul>
|
|
|
|
|
|
<a name="structure"></a>
|
|
<h3>Complex structures</h3>
|
|
<ul>
|
|
Put your devices in different rooms. You can now use the
|
|
room=<roomname> specification to set different devices at once.
|
|
See the <a href="commandref.html#devspec">devspec</a> paragraph for details.<br>
|
|
For more complex scenarios consider the <a href="commandref.html#structure">
|
|
structure</a> module. You can define different structure levels like
|
|
floors, buildings, etc. and set all elements of a given structure at once.
|
|
</ul>
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|