Quick-Start/en

zur deutschen Version geht es hier

Installation

First step is to install FHEM on your server (dedicated hardware or virtual machine). We provide instructions for different operating systems here.

Having started FHEM the first time, please have a look at the FHEM logfile. The log file will look something like the following example:

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

After installation, FHEM can be accessed by a FHEMWEBinterface to be found at the following URL: http://<fhem-server>:8083/fhem

You may add more FHEMWEB devices. This may be helpfull in case you want to use a different style than default f18 on smaller display sizes or provide pages with limited options to controll FHEM for other users. In case you need a lower level communication channel to FHEM, e.g. for scripting or emergancy cases, have a look at telnet.

• 

  Desktop version of the FHEM start screen just after installation

• 

  Smallscreen version of the start screen

• 

  A new telnet connection after issuing a version command

Elements of the web interface

• The input box at the top is used to enter commands and here referred to as "command field". Finish your typing with Enter to pass the commands to FHEM for processing.
• Left of the command field there's a symbol (+). Clicking will prompt a popup field to enter RAW-Code - a very effective way to enter multiple command lines in one step.
• The menu 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 menu 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 menu is built by some links you might find useful.

Securing the FHEM server component

As you have already seen, in a fresh installation you merely 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 help <command> in the command field and press Enter.

It is recommended to define one or more allowed devices. For instructions on how to do this, please have a look at our CommandRef 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.

The notation <command> <parameter> is not only used here, but is also very common in other documents and examples you'll find when using FHEM. In these cases you are asked to replace the placeholder in the brackets (including the "<>"-brackets) by your own meaningful content.

Additionally you may add for your FHEMWEB device, whose 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 off the respective warning using the global attribute motd.

FHEM and the WWW

If you intend to have access to 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 to the operating system and other software components installed on it. Besides that, any other components you use for home automation will contribute to the level of (non-)security of the entire system you run in the end.

Interfaces to the real world

If at this point you do not have any hardware to be included in your FHEM you may follow our first steps in FHEM to get an impression how to configure devices in FHEM.

To get information about what is happening in the real world, you have to somehow connect FHEM with it.

Many 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).

Automatic Configuration

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 its 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 do additional configuration work also for automatically detected devices by assigning the appropriate values to attributes. You can easily get an overview of the available attributes and to some extent 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 attr initialUsbCheck disable 1 to the command field.

Manual Configuration

In commandref you'll find again a notation like define <name> CUL <device> <FHTID>. Please replace the placeholders in the brackets with own content and also delete the brackets.

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) to enter the define command directly in the command field. Examples:

• A CUL stick can be defined like this: define CUL1 CUL /dev/ttyACM0@9600 1234
• Z-Wave controller: 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

autocreate

By default, FHEM is also configured to automatically add to your configuration all kinds of devices it detects when running. This especially happens when you use RF equipment. FHEM will use its 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, look out for changes in the logfile and refresh the FHEM webpage in your browser. The naming of newly detected devices is oriented on their technical parameters.

Rename

When renaming a device, also the respective logfiles and weblinks will be renamed automatically. Please note: It is possible to manually rename also the weblinks or logfiles, but in this case, the corresponding main device will not be renamed alongside.

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 menu at "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 types of hardware devices not automatically recognized there should appear a similar line in the logfile.

The exact procedure to include other types of RF equipment typically varies. E.g. HomeMatic devices do 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 field to make the latter 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 types of devices require special RF commands to configure them for 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 its physical registration button until the LED starts blinking. Then you click on the link in the device's FHEM web page to send out the learning command. The LED should stop blinking to indicate that 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

Whenever there's a (FHT/HomeMatic/EnOcean or other) device visible in FHEM after automatic or manual inclusion this not necessarily means it also is fully integrated or "paired". It is highly recommended to check out first if there are still commands pending or options to be set and sent to the device first!

Other types of RF systems (EnOcean/HomeMatic/ZWave) also need specific and substantial procedures to be followed to get these devices under full control of FHEM. Please have a look at 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.

Timer

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 or more sensors or other devices (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:

   inform timer 

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 to such an event. This may be something like:

   define lampNotify notify myPiri set myLamp on 

or

   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 to 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 measured brightness is lower than 40. If the condition gets false, the lamp is switched off.

DOIF-Solution:

define di_lamp DOIF ([06:00-19:00] and [sensor:brightness] < 40) (set lamp on) DOELSE (set lamp off)

Record and present data

Example: plot of a solar heat system

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. This 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.

There's also a (German) article Plots erzeugen that will direct you to some practical examples. For further information also look at the commandref's SVG section.

To include data in your diagrams not directly logged from within FHEM, add the readonly parameter to the FileLog definition. Make sure that there are no other devices named identically and enter something like the following to the command field (usually <regexp> needs to be identical to the device name, i.e. messages in this case):

define messages FileLog /var/log/messages <regexp> readonly

Frontends: Adopting the web interface to your needs

So far FHEMWEB - to be exact FHEMWEB's default style "f18" has been used as user interface between you and the FHEM server. "f18" is capable to adopt the web sites to different display sizes for all kind of gadgets like mobile phones, tablets or computers.

Styles

To change FHEMWEB's look and feel, you may choose other color shemes or styles. You are not limited to just one scheme, but may use different styles or color schemes for different FHEMWEB instanzes. So you may see at one glance, if you are using a more administrative instance or just a very limited instance with just a few devices to interact.

Rooms and groups

It makes sense to group your devices for structured access in FHEMWEB by setting the room and/or group attributes, attribute defaultRoom will mark a starting page. 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 or forum board FHEM » Frontends to find the solution that fits your needs best!

Complex structures

Put your devices into 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)
• define
• defmod
• version - (Wiki)
• update - (Wiki)
• shutdown
• DOIF - (Wiki)
• notify - (Wiki)
• at - (Wiki)
• sleep
• cancel
• watchdog - (Wiki)

FHEM (TM) is a GPL'd perl server...

As FHEM is written in perl, most users will be reminded of it's perl nature at some point in time. Though it may not be mandatory for FHEM users to learn perl, it's highly recommended to also have a look at this programming language for getting deeper insights in what is going on in your home automation system. As often regular expressions (german) are used within the perl code, getting familiar with this toolset is also a good idea. To solve some problems you may encounter using perl and regex is the most efficient way to go. For first insight see FHEM command types, Perl specials and the article 99 myUtils anlegen (german). Despite beeing marked as outdated, this article and others in this sections still privide usefull futher info in English to more experienced users and experts.