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.

Many fhem installations access the "outer world" via a USB device connected to the fhem computer (CUL, FHZ1x00, TUL, EUL, etc), these installations most probably need the perl serial module. See the commandref section of your USB device, if this module is needed. You can avoid this module by using a device which connects via Ethernet, e.g. a HMLAN or a CUNO.

If you need this module, 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 /opt/fhem, edit the Makefile to change this. You can also start fhem directly from where you unpacked it, installation is optional. To install & start fhem type:

      make
      cd /opt/fhem
      perl fhem.pl fhem.cfg

After starting, the fhem logfile in the log directory should look like:

      2012.10.27 17:14:28 1: Including fhem.cfg
      2012.10.27 17:14:28 3: WEB: port 8083 opened
      2012.10.27 17:14:28 3: WEBphone: port 8084 opened
      2012.10.27 17:14:28 3: WEBtablet: port 8085 opened
      2012.10.27 17:14:28 1: Including /tmp/fhem.save
      2012.10.27 17:14:28 3: telnetPort: port 7072 opened
      2012.10.27 17:14:28 1: usb create starting
      2012.10.27 17:14:28 1: usb create end
      2012.10.27 17:14:28 2: SecurityCheck:  ...
      2012.10.27 17:14:28 0: Server started (version Fhem 5.3 ...

The SecurityCheck warning tells you, that some of the fhem interfaces are opened without a passwort. You should either set a password for each device (see below), or set a global attribute to disable this message if you are sure passwords are not needed.

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.

Note: On the FritzBox the default configuration enables password checking on all interfaces: The username is ignored, and the passwort is checked against the FritzBox password.

In the default configuration, fhem will look for USB attached FHZ, CUL, COC, ZWave and TCM devices on startup (unix/OSX only) and will create appropriate fhem devices. Make your life easier by attaching the device before starting fhem.

On linux (esp. FB7390) fhem will try to flash an 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.

For defining USB Input devices 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

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.
• Execute commands by typing enter in the FHEMWEB input line. Clicking on the save button won't execute your command.
• 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)

Many Radio devices will be created automatically in the default configuration, due to the enabled 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. The same is valid vor ZWave devices.

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/ZWave) 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

• Both default TCP/IP interfaces in fhem (telnet and FHEMWEB) can be secured by a password and additionally with encryption (HTTPS/SSL):
  • for FHEMWEB see the basicAuth and HTTPS attributes
  • for telnet (which is more or less a TCP/IP port) see the password and SSL attributes
  This is however not the default for most default configurations, and this is the reason why you receive a SecurityCheck warning after installation.
  
  
• Another 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, although the latter is more complicated to set up.
  
  
• You can secure FHEMWEB also by using apache to implement basicAuth / HTTPS by redirect a certain prefix to your 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, or this for the perfect solution with server and client certificates.
  
  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 or group 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.