mirror of
https://github.com/fhem/fhem-mirror.git
synced 2025-01-31 06:39:11 +00:00
442 lines
18 KiB
HTML
442 lines
18 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 id="block">
|
|
<b>Content:</b>
|
|
<div id="dist"></div>
|
|
<div id="dist"><a href="#starting">Starting</a></div>
|
|
<div id="dist"><a href="#attaching">USB device</a></div>
|
|
<div id="dist"><a href="#sensors">Sensors</a></div>
|
|
<div id="dist"><a href="#actors">Actors</a></div>
|
|
<div id="dist"><a href="#at">At / Notify</a></div>
|
|
<div id="dist"><a href="#logging">Logging data</a></div>
|
|
<div id="dist"><a href="#plotting">Plotting</a></div>
|
|
<div id="dist"><a href="#security">Security</a></div>
|
|
<div id="dist"><a href="#fhemweb">Look & Feel</a></div>
|
|
<div id="dist"><a href="#structure">Structures</a></div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div id="right">
|
|
|
|
<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. See the commandref section of your USB device, if
|
|
this module is needed.<br><br>
|
|
|
|
If yes, you can install it e.g. with <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 in the commandref.html as a last resort.<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="attaching"></a>
|
|
<h3>Attaching the USB device to 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>
|
|
|
|
In the default configuration, fhem will look for USB attached FHZ, CUL
|
|
and TCM devices on startup (unix/OSX only) and will create
|
|
appropriate fhem devices.<br><br>
|
|
|
|
On linux (esp. FB7390) it will even try to
|
|
flash the unflashed CUL, if it is attached at startup. See the <a
|
|
href="commandref.html#usb">usb</a> and <a
|
|
href="commandref.html#CULflash">CULflash</a> commands for details, and
|
|
check the "unsorted" room in FHEMWEB for the newly created
|
|
devices. Note that switching a CUL to HomeMatic mode is still has to be
|
|
done manually. Only one device is flashed per fhem-startup.<br><br>
|
|
|
|
For doing it manually (or if fhem failed to discover your device):
|
|
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="sensors"></a>
|
|
<h3>Configuring transmitter devices (i.e. 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:
|
|
<br><br>
|
|
<ul><code>
|
|
rename FHT_1234 fht.kitchen</pre>
|
|
</code></ul>
|
|
<br>
|
|
|
|
<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>
|
|
|
|
HomeMatic sensors do not need to be paired with fhem, on the other side
|
|
fhem will only autocreate such a device, when it receives a pairing
|
|
request. You still need to "set CUL hmPairForSec 600" to respond
|
|
to this request.
|
|
</ul>
|
|
|
|
<a name="actors"></a>
|
|
<h3>Configuring 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.
|
|
<br><br>
|
|
|
|
Creating a fhem FHT / HomeMatic / EnOcean device automatically or
|
|
manually does not imply that the CUL or the FHZ is paired with it.
|
|
<ul>
|
|
<li>FHT:<br>
|
|
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.
|
|
</li>
|
|
<li>HomeMatic:<br>
|
|
first set the CUL/HMLAN into pairing mode with
|
|
<ul><code>
|
|
set CUL hmPairForSec 600
|
|
</code></ul>
|
|
and then push the learning button on the HomeMatic device. If pairing was
|
|
successful, you'll see "CommandAccepted: yes" in the details window of the
|
|
device.
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
<a name="at"></a>
|
|
<h3>Timed commands (at) / Notification (notify,watchdog)</h3>
|
|
<ul>
|
|
To execute commands at a given time / periodically, you have to define
|
|
devices of the type <b>at</b>. See the definition and the examples
|
|
<a href="commandref.html#at">here</a>.
|
|
<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 should open a telnet session to your fhem
|
|
<br><br><ul><code>
|
|
telnet <fhemhost> 7072
|
|
</code></ul><br>
|
|
|
|
and type
|
|
<br><br><ul><code>
|
|
inform timer
|
|
</code></ul><br>
|
|
|
|
Now you will receive in this telnet session all events, e.g.
|
|
<br><br><ul><code>
|
|
2011-12-16 21:51:55 FS20 myPiri on-for-timer 120
|
|
</code></ul><br>
|
|
so you can define an action like:
|
|
<br><br><ul><code>
|
|
define lampNotify notify myPiri set myLamp on
|
|
</code></ul>
|
|
or
|
|
<ul><code>
|
|
define lampNotify notify myPiri:on.* set myLamp on
|
|
</code></ul><br>
|
|
To test your notify you can simulate events by using the
|
|
<a href="commandref.html#trigger">trigger</a> command:
|
|
<br><br><ul><code>
|
|
trigger myPiri on-for-timer 120
|
|
</code></ul><br>
|
|
|
|
at, notify and watchdog take either simple fhem commands, shell scripts
|
|
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="logging"></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.
|
|
You can enable archiving with the <a
|
|
href="commandref.html#nrarchive">nrarchive</a> or <a
|
|
href="commandref.html#archivedir">archivecmd</a> attributes.
|
|
</ul>
|
|
|
|
<a name="plotting"></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>
|
|
|
|
The data for a plot always comes from a single FileLog, change its regexp
|
|
so that it will collect all events you want to plot. As the next step
|
|
set the <a href="commandref.html#logtype">logtype</a> attribute of the
|
|
FileLog, this will define which .gplot files to use.
|
|
Take a look at the available gnuplot files in the "Edit files" section,
|
|
they contain the corresponding FileLog definition examples.<br>
|
|
Note that the .gplot files are also used if you use SVG output and
|
|
not the gnuplot backend!<br>
|
|
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>
|
|
|
|
|
|
Examples:<pre>
|
|
attr em1000log logtype power8:Power,text
|
|
attr fs20_log logtype fs20:Plot,text
|
|
attr hms100th_log logtype temp4hum6:Plot,text
|
|
</pre>
|
|
|
|
Display the plot by clicking on it, and create a <a
|
|
href="commandref.html#weblink">weblink</a>, which has its own attributes
|
|
(room, etc).
|
|
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, create another weblink and set its
|
|
fixedrange attribute, e.g.:
|
|
<ul><code>
|
|
attr weblink_1 fixedrange 2006-01-01 2007-01-01
|
|
</code></ul>
|
|
<br>
|
|
|
|
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>
|
|
</ul>
|
|
|
|
|
|
|
|
<a name="security"></a>
|
|
<h3>Security</h3>
|
|
<ul>
|
|
<li>The telnet port cannot be secured with a password. Usually this is
|
|
not a problem, since this port is only accessible from the secure
|
|
home network. Deleting the last "global" attribute from the "attr
|
|
global port 7073 global" (changing it to "attr global port 7073")
|
|
will accept only local connections (i.e. telnet only from the fhem
|
|
server itself). <br><br></li>
|
|
|
|
<li>One way of secure access from the outside is to use a VPN connection.
|
|
Connecting e.g. to a FritzBox by VPN works both for iOS and Android
|
|
devices.
|
|
<br><br></li>
|
|
|
|
<li>Securing FHEMWEB (method 1) by 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, so this
|
|
is not an option here.
|
|
<br><br></li>
|
|
|
|
<li>Securing FHEMWEB (method 2) by using apache to implement this
|
|
features, and redirect a certain prefix to each FHEMWEB instance.
|
|
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/wiki/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>
|
|
</ul>
|
|
|
|
<a name="fhemweb"></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>
|
|
|
|
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>
|
|
</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>
|