FHEM (GPL'd FS20/HMS/FHT/KS300/WS300 server for linux, formerly known as fhz1000.pl)

News (as of =DATE=, Version =VERS=)

Description

This program makes the FHZ1000/FHZ1300/WS300 USB devices sold by ELV, Conrad and others useable with Linux. In fact, there is nothing Linux special in it, you should be able to use it on other platforms as long as you can access the hardware as a serial device.
The program runs as a server, you can control it via telnet, command line program or TCP/IP directly, like the supplied web frontends do.

Currently implemented features:

• reading and sending FS20 events (on/off/dimming, timer commands, etc)
  
• support of FS20 address features function group, local and global master
• reading and changing FHT80b parameters (temp, actuator, etc).
  The FHT8b seems to work too. Note: the FHT8 wont work.
• reading HMS data (HMS100-T,-TF,-WD,-MG,-TFK and RM100-2)
• reading KS300 data
• reading WS300 data
• logging events to files (or database), with regexp filters
• notifying external programs or internal modules when receiving certain events
• timed commands (e.g. switching a lamp on from sunset till midnight)
• modular architecture
• a lot of web frontends, choose your favorite


See commandref.html for a detailed command description and faq.html for the F.A.Q.

Links:

Homepage: http://www.koeniglich.de/fhem/fhem.html
Download: http://www.koeniglich.de/fhem/fhem-=VERS=.tar.gz
Google-Group: http://groups.google.com/group/FHZ1000-users-on-unix
Martins Web frontend: http://www.martin-haas.de/fhz
fhz1000 on Nas/Routers: http://www.martin-haas.de/fhz/nslu2fhz
LinViex (home automation frontend): http://sourceforge.net/projects/linviex

Related projects:

http://fhz4linux.info/

Installation

Linux driver

For kernels newer than 2.6.14 add one of the following lines to /etc/modprobe.conf:


  # FHZ1000 PC
  options ftdi_sio vendor=0x0403 product=0xf06f
  # FHZ1300 PC
  options ftdi_sio vendor=0x0403 product=0xe0e8

If in doubt, look at the id of the device with lsusb. For older kernels apply the patch from the doc directory to your kernel.
Recompile your kernel and reboot or load/reload the ftdi_sio module.
See also our hints for GNU/Linux.

Perl modules

You need perl with the Device::SerialPort ( http://search.cpan.org/dist/Device-SerialPort/) module. All other needed modules were present in my installation. If this module reports Can't call method "opened" on an undefined value... when starting the server, then you either may ignore this message, or replace the mentioned line with:

    $self->{HANDLE}->close if (defined($self->{HANDLE}) &&
    	                       $self->{HANDLE}->opened);

Server installation

• Copy the file fhem.pl into your path (e.g. /usr/local/bin), and the FHEM directory e.g. to /usr/local/lib.
• Make sure that you can access the serial USB device (e.g. /dev/tts/USB0).
• Create a configuration file (see the examples directory and docs/commandref.html), and change at least the modpath (/usr/local/lib) and define FHZ FHZ (/dev/tts/USB0) parameters.
• Delete the savefile if you are upgrading from an older version.
• Start the server with fhem.pl <configfile>
• For using the WS300, look into the contrib/ws300 directory.

General Notes for Webfrontends:

• You don't have to install all of them, one is probably more than enough :-)
• The web server and the fhem server must be on the same host
• Important: Make sure you add some protection (.htaccess, etc) else everybody will be able to set your devices

Web frontend 2 (webfrontend/pgm2, the simple one)

This frontend is CGI/CSS based. It has support for rooms, and FHT/KS300 logs.
Screenshots: overview, details and KS300 temperature logs


• Copy the file fhemweb.pl and *.gplot to your cgi-bin directory (/home/httpd/cgi-bin), the icons (*.gif) to your httpd icons (/home/httpd/icons), and commandref.html to the html directory (/home/httpd/html).
  Note: The program looks for icons in the following order: <device-name>.<state>, <device-name>, <device-type>.<state>, <device-type>
  
• Edit fhemweb.pl, and check the "Config" section.
• If you want to have access to plotted logs, then make sure that gnuplot is installed and set the logtype for the FileLog device (see commandref.html and example/04_log).
• Call <your-site>/cgi-bin/fhemweb.pl
For special features like assigning devices to rooms see the README file.

Web frontend 3 (webfrontend/pgm3, the professional one)

This frontend is PHP based and was contributed by Martin Haas. Look at the webfrontends/pgm3/docs for more documentation or at this screenshot. A lot more details can be found on Martins page: http://www.martin-haas.de/fhz


• Install PHP and enable it by commenting in the "LoadModule phpX_module ..." directive in httpd.conf (perhaps it is already done by your distro). Restart/reload httpd.
• Create a directory (e.g.: /home/httpd/html/pgm3) and copy all the files from the webfrontend/pgm3 to this directory.
  Make sure that this directory is writeable by the webserver!
• Edit index.php (/home/httpd/html/pgm3/index.php), and check the required settings section
• If you want to have access to the FHT temperature logs, then:
  • Make sure gnuplot is installed
  • check the showgnuplot section in index.php
  • For each FHT device copy the file docs/gnuplot/gnuplot.wz to gnuplot.fhtdevicename (to the /home/httpd/html/pgm3 directory) and replace fht.log in this file with the absolute name of the current logfile.
• Call <your-site>/pgm3/index.php

Web frontend 4 (webfrontend/pgm4, the template)

This frontend is PHP based and was contributed by Stefan Mayer. It won't work for you without modification, it is meant as a template or as an example. See the screenshot. To install:
• Copy the directory webfrontend/pgm4 to your html directory.
• Install/enable PHP (see the description for frontend3)
• Call the program with http://webserver/pgm4/fs20.php
Now you can go on, and modify it to suit your needs :-)

License:

Copyright:

• Rudolf Koenig (r dot koenig at koeniglich dot de)
• Raoul Matthiessen (webfrontends/pgm1)
• Martin Haas (webfrontends/pgm3)
License: GPL (v2)

Misc:

Thanks for Tosti for inspiration and numerous other people for help.