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
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:
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:
if you are using a normal desktop,
you are using a smartphone, or
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
slightly different parameters:
define FHZ1 FHZ /dev/ttyUSB0
- 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
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
Now define the fhem device:
FS20 Unknown device <HOUSECODE>, Button <BTN> Code
<CDE>, please define it
Set the model attribute of the device:
define piri1 FS20 <HOUSECODE> <BTN>
to get only the commands available for this device.
Here is a complete list of FS20
attr piri1 model fs20piri
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.
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.
first set the CUL/HMLAN into pairing mode with
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
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
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
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
define lampNotify notify myPiri:on.* set myLamp on
To test your notify you can simulate events by using the
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
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
To log messages into a
database, see the contrib/dblog directory in the fhem
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
You can enable archiving with the nrarchive or archivecmd attributes.
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.
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
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
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,
define messages FileLog /var/log/messages fakelog
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.
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.