FHEM Howto

Starting fhem

Skip this section if you installed fhem via the Debian package or via the Fritzbox7390 image

First install the Device::SerialPort (or Win32::SerialPort) perl module with the command "sudo cpan Device::SerialPort". There are also precompiled debian packages (libdevice-serialport-perl), and this module is already installed on OSX. You will need it to access the USB devices

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 for the PC (CUL / FHZ1x00PC / EM1010PC)

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.

Attach the USB device (CUL, FHZ1000PC/FHZ1300, EM1010PC) 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

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.

Note: 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 this FAQ entry.

Configuring FS20 receivers

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.

Timed commands / Notification

To execute commands at a given time / periodically, you have to define devices of the type at. See the definition here and the examples here. The last link only works if you are reading this HOWTO from your fhem Web.

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 can open a telnet session to your fhem

      telnet localhost 7072

and type

      inform timer

Now you will receive in this telnet session all events, just like the notifies/watchdogs do. You can even simulate events by using the trigger command:

      trigger lamp1 on

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.

Set the title of the webpage by setting the title attribute of the global device ("All together" -> global)

Edit the colors / fonts by changing the style.css ("Edit files" -> style.css)

Further FHEMWEB attributes: webname, plotmode, plotsize.

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. Don't forget to 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.

To convert a FileLog into a plot (chart) in FHEMWEB, set the logtype 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.
Note that the .gplot files are also used if you use SVG output and not the gnuplot backend!
Examples:

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

When displaying the plot, you can convert it into a "weblink" device, so that we can in turn have a room attribute to group more than one Plot together. 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. Firefox, Opera, Chrome, Safari (both on OSX and iOS) support SVG out of the box, Internet Explorer from version 9. IE prior to version 9 does it via the Adobe "SVG viewer" plugin, on Android you need 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, 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.

Note: the gnuplot files must have #FileLog entries in order to be useable with gnuplot-scroll or SVG, as the filtering happens with the FileLog get function, see the supplied gnuplot files or the column_spec paragraph here for the syntax.

The order of the #FileLog lines must match the corresponding 'awk' entries.

It make sense to build large logfiles for scrolling in them (year resolution), or smaller ones if you do not want to use the zoom/scroll feature. The size of the logfiles will be determined by its wildcard characters (year/month/week/day), look at the FileLog definition.

FHEMWEB tips

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.

There are two different ways to enable Password and HTTPS


• Using the builtin features of FHEMWEB for basic html authentication and HTTPS.
  
  
• 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).
  
  
  
To display "foreign" (non fhem) files as a plot or a 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

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.