FHEM Howto

Starting fhem

Skip this section if you installed fhem via the Debian package, the Fritz!Box 7390 image, or the FB 7170/7270 zip file.

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.

If yes, you can install it e.g. with "sudo cpan Device::SerialPort". 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.

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:

      make install-pgm2
      perl /usr/bin/fhem.pl /etc/fhem.cfg

After starting, the logfile should look like:

      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 ...)

Attaching the USB device to the PC (CUL / FHZ1x00PC / etc)

Connect to fhem with an internet browser: http://fhem-host:8083/fhem if you are using a normal desktop, http://fhem-host:8084/fhem if you are using a smartphone, or http://fhem-host:8085/fhem if you are using a tablet like the iPad.

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.

On linux (esp. FB7390) it will even try to flash the unflashed CUL, if it is attached at startup. See the usb and CULflash 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.

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 CUL 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):

      define CUL1 CUL /dev/ttyACM0@9600 1234

You can find details about CUL define parameters here.

The same is to be done for the FHZ with slightly different parameters:

      define FHZ1 FHZ /dev/ttyUSB0

For the FHZ on OSX you need to install the ftdi driver first from http://www.ftdichip.com/Drivers/VCP.htm, the device name will be /dev/cu.usbserial-xxxxxxxx.

Notes:
• 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.
• The CUL is arriving without a firmware. You can flash it via the CULflash command, if the dfu-programmer is installed. dfu-programmer is part of the FB7390 image.

Configuring transmitter devices (i.e. sensors)

The sample configuration file installed via "make install-pgm2" has configured an autocreate 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 rename to rename the automatically created device, e.g. type in the input field of the web frontend:


rename FHT_1234 fht.kitchen

Note: 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.

If you want to do the same manually:
Wait a while, until the transmitter sent some data. In the logfile (browser window: "Unsorted -> Logs / Fhemlog / text) a line will appear:
FS20 Unknown device <HOUSECODE>, Button <BTN> Code <CDE>, please define it
Now define the fhem device:
define piri1 FS20 <HOUSECODE> <BTN>
Set the model attribute of the device:
attr piri1 model fs20piri
to get only the commands available for this device. Here is a complete list of FS20 models.
For other device types similar messages should appear.

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.

Configuring receivers (actors)

Configure the FS20 device in fhem first with:

      define lamp1 FS20 1234 56

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:

      attr lamp1 model fs20st

to get only the commands available for this device.

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.

Creating a fhem FHT / HomeMatic / EnOcean device automatically or manually does not imply that the CUL or the FHZ is paired with it.
• FHT:
  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 this FAQ entry.
• HomeMatic:
  first set the CUL/HMLAN into pairing mode with
  set CUL hmPairForSec 600
  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.

Timed commands (at) / Notification (notify,watchdog)

To execute commands at a given time / periodically, you have to define devices of the type at. See the definition and the examples here.

To execute commands if a device sent a message you have to define devices of the type notify or watchdog. In order to understand the fhem events better you should open a telnet session to your fhem


telnet <fhemhost> 7072

and type


inform timer

Now you will receive in this telnet session all events, e.g.


2011-12-16 21:51:55 FS20 myPiri on-for-timer 120

so you can define an action like:


define lampNotify notify myPiri set myLamp on
or
define lampNotify notify myPiri:on.* set myLamp on

To test your notify you can simulate events by using the trigger command:


trigger myPiri on-for-timer 120

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 Perl specials section in the commandref.html

Logging data

To log messages into files, define devices of the type FileLog. Autocreate will create logfiles for newly detected devices, or you can use createlog in order to add a FileLog later.
To log messages into a database, see the contrib/dblog directory in the fhem distribution.

FHEMWEB has builtin support for displaying FileLog type logs as plots, see the plot section below.

The size of each logfile will be determined by its wildcard characters (year/month/week/day), look at the FileLog definition. You can enable archiving with the nrarchive or archivecmd attributes.

Plotting logs

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.

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 logtype 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.
Note that the .gplot files are also used if you use SVG output and not the gnuplot backend!
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 here for the syntax.

Examples:

        attr em1000log logtype power8:Power,text
        attr fs20_log logtype fs20:Plot,text
        attr hms100th_log logtype temp4hum6:Plot,text
      

Display the plot by clicking on it, and create a weblink, 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).

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.

SVG mode is the default, to change it set the plotmode attribute to gnuplot or gnuplot-scroll.

In order to look at historic data, create another weblink and set its fixedrange attribute, e.g.:
attr weblink_1 fixedrange 2006-01-01 2007-01-01

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.


      define messages FileLog /var/log/messages fakelog

Security

• 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).
  
  
• 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.
  
  
• Securing FHEMWEB (method 1) by using the builtin features of FHEMWEB for basic html authentication and HTTPS. The perl modules needed for HTTPS are missing from the FritzBox distribution, so this is not an option here.
  
  
• 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:

          <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

  and then restart httpd with apachectl graceful. To create the password file, execute
  htpasswd -c /home/httpd/etc/passwd <username>
  See also this fhemwiki entry for a more detailed description.
  
  To enable HTTPS, please check the web. In essence:
  
  • Edit httpd.conf, add:

        LoadModule ssl_module lib/apache/mod_ssl.so
        Include /etc/httpd/conf/ssl.conf

  • Create a server certificate
  • 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).

FHEMWEB (pgm2) look and feel

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.

You can also define a stripped down FHEMWEB instance, by defining the Menu entries to be hidden in the hiddenroom FHEMWEB attribute.

Edit the colors / fonts by changing the style.css ("Edit files" -> style.css), or create you own style (see stylesheetPrefix , so it won't be overwritten by the next updatefhem command.

Complex structures

Put your devices in different rooms. You can now use the room=<roomname> specification to set different devices at once. See the devspec paragraph for details.
For more complex scenarios consider the structure module. You can define different structure levels like floors, buildings, etc. and set all elements of a given structure at once.