- 1 Installation
- 2 Talking to FHEM
- 3 Securing the FHEM server component
- 4 Interfaces to the real world
- 5 Adding and configuring sensors and actors
- 6 Basics about controlling your devices
- 7 Record and present data
- 8 Frontend: Adopting FHEMWEB (pgm2) to your needs
- 9 Complex structures
- 10 Shortlist: commands to learn first
- 11 References
First step is to install FHEM on your server (dedicated hardware or virtual machine). We provide instructions for different operating systems here.
2018.03.09 09:17:51 1: Including fhem.cfg 2018.03.09 09:17:51 3: telnetPort: port 7072 opened 2018.03.09 09:17:51 3: WEB: port 8083 opened 2018.03.09 09:17:51 3: WEBphone: port 8084 opened 2018.03.09 09:17:51 3: WEBtablet: port 8085 opened 2018.03.09 09:17:51 2: eventTypes: loaded 0 events from ./log/eventTypes.txt 2018.03.09 09:17:51 1: usb create starting 2018.03.09 09:17:51 3: [...] 2018.03.09 09:17:51 1: usb create end 2018.03.09 09:17:51 0: Featurelevel: 5.8 2018.03.09 09:17:51 0: Server started with 9 defined entities (fhem.pl:16349/2018-03-07 perl:5.024001 os:linux user:fhem pid:9341)
Talking to FHEM
FHEM offers two ways to interact and configure itself.
- A telnet interface at port 7072
- Websites (FHEMWEB) found at the following three locations:
- http://<fhem-server>:8083/fhem for normal desktop computer screen sizes
- http://<fhem-server>:8084/fhem for Smartphones and other devices with small display sizes
- http://<fhem-server>:8085/fhem for other mobile devices with medium display sizes like tablet PC's
- Elements of the web interface
- The input box at the top is used to enter commands and here refered to as "command field". Finish your typing with Enter to pass the commands to FHEM for processing.
- The menue on the left starts with the item Save config. FHEM allows to change its configuration at runtime. To make changes permanent and keep them available after restart of FHEM or the server hardware also, they have to be written to a configuration file. If you see a red ? beneath this menue item, this indicates unsaved changes of your configuration.
- Below "Save config" is a section listing the "rooms" known by FHEM. At first start you will only find the rooms Unsorted and Everything. New rooms will automatically appear if you assign the respective attribute to the devices you add later on.
- The - preliminary - last section of the menue is built by some links you might find useful.
Securing the FHEM server component
As you have already seen, in a fresh installation you just have to be in the same network segment to have full access to the FHEM server. There's no encryption nor authorization by user or password. This is why you get respective warnings at FHEM's starting page. FHEM may be secured using one of the following options:
allowed and SSL
These two methods may be combined and can be used to secure one or both ways (telnet and web interface) to interact with and configure FHEM. Allowed restricts access by user authentication, SSL adds transport layer encryption (HTTPS/SSL).
| For instructions on how to use FHEM commands and additional info just type |
It is recommended to define one or more allowed devices. For instructions on how to do this, please have a look in ourCommandRef or just pass
help allowed to the command field.
As long as there's no allowed device defined, FHEM restricts all interfaces access' to the local network.
Additionally you may add for your FHEMWEB device, which sole purpose is to serve you FHEM via browser, a HTTPS attribute to activate HTTPS for http connections. For telnet (being also to some extent also a TCP/IP port) please use the SSL attribute.
By default, none of these securing methods is activated. If you are securing your server and FHEM by other methods you may switch of the respective warning using the global attribute motd.
FHEM and the WWW
If you intent to have access FHEM not only from your local net it is highly recommended to take additional measures. Common options are to use a VPN (Virtual Private Network) and/or a reverse proxy server like Apache or nginx.
Additional remarks on security
Please note: Running a server system requires regular updates on the operating system and other software components installed on it. Besides that, any other components you use for home automatisation will contribute to the level of security of the entire system you run in the end.
Interfaces to the real world
|If you at this point do not have any hardware to be included in your FHEM you may follow our [First steps in FHEM|
To get information about what is happening in the real world, you have to somehow connect FHEM with it.
A lot of FHEM installations use one or more USB devices (e.g. CUL, FHZ1x00, TCM, ZWave, ...) directly attached to the FHEM server for this task. To use this type of connection You need additional pieces of software, especially the Perl module serial. Have a look at the respective part of the commandref for details about the configuration of your USB device(s). The Perl module is not required if the device is connected via ethernet (e.g. HM-LAN or CUNO).
By default FHEM will try to identify commonly used USB-devices like FHZ, CUL, COC, ZWave or TCM. These just have to be attached when FHEM is starting to have FHEM write the respective parts to it's configuration file. When attaching devices to a running FHEM you have to issue a
shutdown restart in the command field to start the auto configuration.
Typically you'll have to make additional configuration work also for automatically detected devices by assigning the appropriate values to attributes. You can easily get an overview on the available attributes and to some extend also a set of values for them by just clicking the name of the device shown in the respective room. New devices in most cases can be found in the room Unsorted.
Once you have basic definitions of all of your USB devices it's recommended to deactivate the automatic recognition of USB devices by entering >code>attr initialUsbCheck disable 1 to the command field.
| In commandref you'll find again a notation like |
USB devices can easily also be configured manualy, especially in cases they are not automatically detected as described above. After plugging them in, just look where these are located in your file system - typically somewhere in the directory
/dev. E.g. a CUL will be found as a file /dev/ttyACM* in a Linux environment. Mac OS X will label the same device as /dev/cu.usbmodem*. Use this description (entire path and file name) do enter the define command directly in the command field.
- A CUL-Stick can be defined like this:
define CUL1 CUL /dev/ttyACM0@9600 1234
define ZWDongle ZWDongle /dev/serial/by-id/usb-0658_0200-if00@115200
Please consult the commandref for further information on configuration of a specific device.
Adding and configuring sensors and actors
By default, FHEM is also configured to automatically add to your configuration all kind of devices it detects when running. This especially happens when you use RF equipment. FHEM will use it's autocreate function as soon as the respective device sends data over the air.
So if you want to include sensors like S300 or FHT, all you have to do is to attach an appropriate USB-device for reception of messages sent by your devices and wait, have a look on changes in the logfile and refresh the FHEM webpage in your browser. The naming of newly detected devices is oriented on their technical parameters.
You may use the command
rename to change this to your needs and likes. So for example for a FHT sensor you can type in the command field:
rename FHT_1234 fht.kitchen
Manual Definition of Devices
If you want to manually add a device or have to do so because autocreate won't work, you have to follow these steps:
Wait until the device sends some data. In the FHEM logfile (available via the menue unter "Unsorted-> FileLog -> Logfile -> text") you may see e.g. the following line:
FS20 Unknown device <HOUSECODE>, Button <BTN> Code <CDE>, please define it
Add the new device by passing the following command to the command field:
define piri1 FS20 <HOUSECODE> <BTN>
Set the appropriate model attribute:
attr piri1 model fs20piri
Once you did that, the other attributes you may set are restricted to the ones that really apply to the chosen model. Also for other RF type of hardware devices not automatically recognized there should apear a similar line in the logfile.
The exact procedure to include other type of RF equipment typically varies.
E.g. HomeMatic devices not necessarily need to be under full control of FHEM (paired). To be included by autocreate a HomeMatic device has to send a pairing request, and FHEM has to enter a special mode to accept this request. Enter
set CUL hmPairForSec 600 in the command filed to make the later happen and see the manual of the device how to do it on that end. ZWave devices require a similar procedure with slightly different commands.
Including Devices by Sending Configuration Commands
Some type of devices require special RF commands to configure them for the usage with a central unit like FHEM or to link them directly with other devices (e.g. a PIR message used directly by a switch). To include that type of hardware, you have to first manually configure FHEM to prepare it to send out these so called learning messages.
E.g. a FS20 device can be defined like this:
define lamp1 FS20 1234 56
Prepare the device by pressing it's physical registration button until the LED starts blinking. Then you klick on the link in the device's FHEM web page to send out the learning command. The LED should stop blinking to indicate it now is programmed to house code 1234 and device code 56. You may also use the 4-base ELV notation instead. Once this is sucessfully done, you may again set model specific attributes to limit the available options to ones relevant for this model, e.g.:
attr lamp1 model fs20st
Other type of RF systems (EnOcean/HomeMatic/ZWave) need also specific and substantial procedures to follow to get these devices under full control of FHEM. Please have a look in the corresponding section of the commandref and the manual of the device before starting these procedures.
Basics about controlling your devices
Once your sensors and actors are correctly defined in FHEM you will be able to control any of your actors using FHEM's telnet or web interface.
| If you start with FHEM and are able to read german, it's recommended to read the Einführung in die Automatisierung mit FHEM. This document is - beside some details - still up to date. Although new features like the f18 style, modules like allowed or DOIF are not covered there, and the selection of available hardware systems has continued to increase since its last update. Nevertheless, this introduction still offers a quite comprehensive overview of the general procedures and possibilities with FHEM.
The module DOIF has only a short English commandref. The complete commandref is provided by the module maintainer only in German with several example codes. If you can't understand this or don't want to get used to DOIF for this reason: you can use the full functionality of FHEM without DOIF. Use for example notify, at and the other modules instead.
The most basic way to implement timer functionality in FHEM is to define an "at". Examples and basic instructions you'll find in the commandref.
Reacting on events from the real world
If you want FHEM to react to any message sent by one ore more sensors or other device (an "event" in FHEM terminology), you use an event handler. The basic event-handler in FHEM is called notify; another one is for example DOIF.
Please open a new tab in your browser with the Event monitor or open a telnet connection by:
telnet <fhemhost> 7072
Once the connection is opened type:
Now you will see all events in the telnet-Connection or the Event Monitor. E.g.:
2011-12-16 21:51:55 FS20 myPiri on-for-timer 120
If you mark the line you want to react on, you may ask the assistant in the Event Monitor to help you to define a reaction on such an event. This may be something like:
define lampNotify notify myPiri set myLamp on
define lampNotify notify myPiri:on.* set myLamp on
To test if this notify or DOIF acts as expected you may use the
trigger command to simulate an event in the real world. E.g.:
trigger myPiri on-for-timer 120
at, notify and other event handler like DOIF, sequence, watchdog etc. use either predefined FHEM commands, shell scripts or Perl one liners as arguments. For details and tips for Perl one liners please read the Perl specials section at the commandref. You may use so-called regular expressions ("regex") to build more complex conditions. These regex can be applied for analysis of events and as well in the execution part of the notify. A short introduction in regex is available e.g. here: https://regex101.com/.
Combined time and event control
Combined time and event control is possible with DOIF (time and event control), notify and other modules.
The example shows a timespan combined with a readings value. Between 6 am and 7 pm a lamp is switched on, if the meassured brightness is lower than 40. If the condition gets false, the lamp is switched off.
define di_lamp DOIF ([06:00-19:00] and [sensor:brightness] < 40) (set lamp on) DOELSE (set lamp off)
Record and present data
Record data: Logging
To save data/events/messages to a logfile, you have to create one or several FileLog devices. There's a helper function called
autocreate. These also adds a logfile to devices automatically recognized and included by the autocreate mechanism. For manually added devices you can use the option createlog which may be used in case you want to add additional logfiles, too. To write just one logfile for several devices to be logged combined, use an appropriate regular expression.
For subsequent graphical presentation of the logged data, FHEMWEB offers the wizard described below.
The size of each logfile will be determined by its wildcard characters (year/month/week/day). Please take a look at the FileLog definition. You can enable archiving with the nrarchive or archivecmd attributes.
Take a look at dblog to use a database instead of a regular file for logging.
From logged data to diagrams: Plotting
To build diagrams out of the logged data, just click on "Create SVG instance" in the detail view of each logfile. This will direct you to the gplot-Editor, a wizard guiding you through a lot of options to fulfill this task.
Choose which of your sets of data should be part of your diagram. You may also mix data originating from different sources for your diagrams. Please note: Sometimes it's necessary to click on write .gplot file , especially to get the possibility to switch between different data sources.
To include data in your diagrams not directly logged from within FHEM, add a fake logfile. Make sure that there are no other device named identically and enter something like the following to the command field:
define messages FileLog /var/log/messages fakelog
Frontend: Adopting FHEMWEB (pgm2) to your needs
Rooms and groups
It makes sense to group your devices for structured access in FHEMWEB by setting the room and/or group attributes. FHEMWEB puts devices without a room attribute into the "Unsorted" room, new room names will be added to the menu on the left. Devices in the room "hidden" will not be shown by default.
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 update command.
More options on the frontend side
FHEMWEB offers a new style, called f18. This overcomes the need for several FHEMWEB instances for different screen sizes. Give it a try! Using a completely different frontend is also possible. Browse the wiki and the forum to find the solution that fits your needs at best!
Put your devices in different rooms. You can use the
room=<roomname> filter to set different devices at once. This is just a simple example: See the devspec section 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.
Shortlist: commands to learn first
- list - (Wiki)
- version - (Wiki)
- update - (Wiki)
- DOIF - (Wiki)
- notify - (Wiki)
- at - (Wiki)
- watchdog - (Wiki)
- In most cases you find the log in
- Most installations use Linux as operating system for the server. So if not stated differently, the commands and examples provided here use the syntax for Linux
- In most cases this is a text file, but you may also use a database. See configDB for how to use a database as configuration source
- Further informationen on the terminology used in a FHEM context is provided in our glossary (german)
- Please note: The term "device" is often used used in the FHEM context in a special way. This could - but must not necessarily be - a physical piece of equipment. "Device" just is a term for any physical or virtual "object" that can be introduced in a FHEM system by a define or defmod command.
- This also applies when devices are attached using serial interfaces provided at GPIO PINs of single-board computers like the Raspberry Pi.
- The Perl-serial-module can either be installed by issuing the
sudo cpan Device::SerialPortcommand at OS level or by installing precompiled Debian packages (libdevice-serialport-perl). Beginning with Mac OS X 10.5 (Leopard) the module is also provided as package. If the perl module is not available for your operating system you may use the @directio-option (see commandref for further information).
- In a Linux environment FHEM will also try to flash am attached CUL in case it's not yet programmed with firmware. For details see the descriptions of the commands
CUL flashin commandref.
- Please note: the number "1234" is just an example; replace this by your own parameter
- This type of representation of the USB device in the Linux file system can also be used. To get the information in that form, you just type
ls -l /dev/serial/by-idat operating system level
- DOIF combines event control, time control, state machine and frontend in one modul
- sequence handles series of events
- watchdog reacts on missing events