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

FHEM offers two ways to interact and configure itself.

1. A telnet interface at port 7072
2. 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

• 

  A new telnet connection after issuing a version command

• 

  Desktop version of the FHEM start screen just after installation

• 

  Smallscreen version of the start screen

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

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

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

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

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

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 send to the device first!

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 highly recommended to read the Einführung in die Automatisierung mit FHEM. This document is - beside some details - still up to date.

To make full usage of FHEM's powerful options and to start the development of a control system that reacts on things happening in the real world and include timer functions you need additional components. In FHEM, these pieces of software are called "modules". A lot of these modules you have already installed as part of the FHEM installation process. Descriptions on them are available in the commandref. So let's have a look on some essential modules:

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 ore more sensors or other device (an "event" in FHEM terminology), you use a so-called event-handler. The basic event-handler in FHEM is called notify.

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 on 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 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 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/.

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

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 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!

Complex structures

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