Quick-Start

Installation

Zunächst installieren Sie FHEM auf der von Ihnen bevorzugten Hardware (oder virtuellen Maschine). Sie finden dazu Erklärungen für die unterschiedlichsten Betriebssysteme hier.

Nach dem ersten Start von FHEM sehen die Einträge im FHEM-Logfile des Log-Verzeichnisses zum Beispiel wie folgt aus:

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)

Erster Aufruf von FHEM

FHEM bietet grundsätzlich zwei Möglichkeiten an, mit denen es konfiguriert werden kann.

1. Eine telnet-Schnittstelle über Port 7072
2. Ein Webinterface (FHEMWEB), welches unter drei URLs erreicht werden kann:
   • http://<fhem-server>:8083/fhem für große Bildschirme
   • http://<fhem-server>:8084/fhem für Smartphones bzw. Geräte mit kleinen Displays
   • http://<fhem-server>:8085/fhem für mobile Geräte mit größeren Displays (z.B. Tablets)

• 

  Eine erste Telnet-Verbindung mit dem Aufruf von version

• 

  Die Startseite direkt nach der Installation auf einem Desktop

• 

  Der erste Aufruf von FHEM auf einem Smartphone

Das Web-Interface kurz erklärt

• Am oberen Bildschirmrand befindet sich ein Kommandofeld. In diesem können Befehle eingegeben werden, die FHEM nach Eingabe der Enter-Taste ausführt
• Mit dem ersten Menüpunkt links - Save config - können Änderungen gespeichert werden. Erst dann werden werden diese in die Konfigurationsdatei geschrieben und sind somit auch noch nach einem Neustart von FHEM vorhanden. Ungespeicherte Änderungen signalisiert FHEM durch ein ? neben dem Menüpunkt
• Im nächsten Abschnitt links werden alle vorhandenen Räume aufgelistet. Zu Beginn sind das nur die Räume Unsorted und Everything. Weitere Räume können natürlich später angelegt werden.
• Im - vorläufig - letzten Abschnitt auf der linken Seite sind einige nützliche Links untergebracht

Absicherung der FHEM-Serverkomponente

In der Grundkonfiguration kann jeder, der sich in dem selben Netzwerk wie der FHEM-Server befindet, unverschlüsselt und ohne der Eingabe von Benutzerdaten auf FHEM zugreifen. FHEM weist mit einer Sicherheitswarnung auf diesen Umstand hin. Um die Installation abzusichern, bieten sich mehrere empfohlene Optionen an.

allowed und SSL

Mit diesen Einstellungen können beide Konfigurations-Möglichkeiten in FHEM (telnet und Webinterface) mit einem Passwort und einer Transport-Verschlüsselung (HTTPS/SSL) abgesichert werden.

Sie erhalten für alle FHEM-Befehle die jeweilige Syntax und weitere Informationen, wenn Sie help <Befehl> in der Kommandozeile eingeben.

Dazu müssen zunächst ein oder mehrere allowed-Geräte definiert werden. Die Anleitung dazu findet sich in der CommandRef oder indem in der FHEM-Kommandozeile der Web-Schnittstelle help allowed eingeben wird.

Ist keine allowed-Instanz definiert, sind Zugriffe auf FHEM nur innerhalb desselben Netzwerks möglich.

Hier wie im Folgenden und in vielen Beispielen, die in der Dokumentation zu finden sind, findet sich die Schreibweise <Befehl> <Parameter>. Dies ist so zu verstehen, dass die Angaben in der Klammer jeweils einschließlich der <>-Zeichen durch eine sinnvolle eigene Angabe zu ersetzen sind.

Zusätzlich kann für FHEMWEB mithilfe des Attributes HTTPS eine HTTPS-Verbindung aktiviert werden. Für telnet (welches mehr oder weniger ein TCP/IP Port ist) wird das Attribut SSL verwendet.

Standardmäßig ist keine dieser Einstellungen gesetzt. Um die deshalb erscheinende Sicherheitswarnungen zu deaktivieren, kann das globale Attribut motd verwendet werden.

FHEM und das Internet

Sofern FHEM nicht nur aus dem lokalen Netz erreichbar sein soll, sollten zusätzliche Sicherheitsmaßnahmen ergriffen werden. Mögliche Optionen dafür sind die Verwendung eines VPNs (Virtual Private Network) und/oder eines Reverse-Proxy-Servers mit z.B. Apache oder nginx.

Weitere Sicherheitshinweise

Beachten Sie, dass nicht nur die Software auf Ihrem Server stets aktuell gehalten werden muss, sondern auch die von Ihnen verwendeten Komponenten maßgeblich dazu beitragen, wie sicher Ihre Hausautomatisierung insgesamt ist.

Schnittstellen zur realen Welt

Sofern Sie an dieser Stelle keine konkreten Geräte haben, die Sie in Ihr FHEM einbinden wollen, können Sie mit Hilfe der ersten Schritte in FHEM einen Eindruck gewinnen, wie Geräte in FHEM eingerichtet werden.

Um Informationen über Ereignisse oder Zustände in der realen Welt zu erhalten, muss FHEM mit der Außenwelt verbunden werden.

Dies geschieht in vielen FHEM-Installationen durch die Verwendung eines oder mehrerer USB-Geräte (z.B. CUL, FHZ1x00, TCM, ZWave, etc.) welche mit dem FHEM-Server verbunden sind. Dazu werden die Perl serial-Module benötigt. Im commandref-Abschnitt zum jeweiligen USB-Gerät ist ersichtlich, welche Module genau benötigt werden. Sie benötigen dieses Modul nicht, wenn das Gerät über Ethernet angeschlossen wird (z.B. HM-LAN oder CUNO).

Automatische Konfiguration

In der Standard-Konfiguration sucht FHEM beim Start automatisch nach USB-Geräten wie z.B. FHZ, CUL , COC, ZWave oder TCM und erstellt die entsprechenden Einträge in seiner Konfigurationsdatei. Wird ein Gerät im laufenden FHEM-Betrieb angeschlossen, muss FHEM durch die Eingabe von shutdown restart in der Befehlszeile neu gestartet werden, bevor das Gerät verwendet werden kann.

Für automatisch eingebundene Geräte müssen in der Regel noch weitere Einstellungen vorgenommen werden. Dies erfolgt durch das Setzen entsprechender Attribute. Die verfügbaren Attribute sowie teilweise auch konkret einstellbare Werte für die Attribute können aufgerufen werden, indem auf auf das entsprechende Gerät im jeweiligen Raum geklickt wird. Neu angelegte Geräte werden im Raum Unsorted angezeigt.

Sobald die automatische Konfiguration aller zu verwendenden USB-Geräte abgeschlossen ist, sollte die automatische Erkennung durch Eingabe von attr initialUsbCheck disable 1 in der Befehlszeile deaktiviert werden.

Manuelle Konfiguration

In der Commandref findet sich in der Regel eine Darstellung in der folgenden Form: define <name> CUL <device> <FHTID>. Dabei sind alle Angaben mit Klammern dazu gedacht, durch eigene Werte (ohne Klammern) ersetzt zu werden.

Um Geräte mit USB-Anschluss manuell zu definieren (oder falls FHEM diese nicht automatisch erkennt), kann - nach Anschluss des Gerätes - im Verzeichnis /dev nach der dort entsprechend eingetragenen Gerätebezeichnung gesucht werden. Für einen CUL zum Beispiel wird unter einem Linux-Betriebssystem eine Datei mit der Bezeichnung /dev/ttyACM* angelegt. Auf OS X /dev/cu.usbmodem*. Mit dieser Gerätebezeichnung (also des Dateinamens) kann das Gerät manuell in der Befehlszeile angelegt werden.

• Am Beispiel eines CUL-Sticks: define CUL1 CUL /dev/ttyACM0@9600 1234
• Oder eines Z-Wave-Controllers: define ZWDongle ZWDongle /dev/serial/by-id/usb-0658_0200-if00@115200

Informationen, wie genau das jeweilige Gerät angelernt wird, finden sich im zugehörigen Abschnitt der commandref

Einbinden und Konfiguration von Sensoren und Aktoren

autocreate

Viele funkgesteuerte Geräte werden in der default-Konfiguration wegen der voreingestellten autocreate-Funktion automatisch erstellt, sobald diese Werte senden.

Diese Funktion erzeugt automatisch beim Empfang einer Nachricht von einem Geräten (z.B. eines Sensors wie dem S300 oder FHT) ein neues Device in FHEM. Bitte warten Sie eine gewisse Zeit, beobachten Sie die Logeinträge oder den Eventmonitor und aktualisieren Sie Ihren Browser um neu erstellte Geräte angezeigt zu bekommen. Die automatisch vergebenen Namen orientieren sich dabei an technischen Parametern.

Umbenennen

Wenn Sie das Gerät selbst umbenennen, werden auch die zugehörigen Logfiles und Weblinks automatisch mit umbenannt. Wenn Sie dagegen die Weblinks oder Logfiles umbenennen, werden die zugehörigen Geräte nicht mit umbenannt.

Um automatisch erstellte Geräteeinträge umzubenennen, kann der Befehl rename verwendet werden. Geben Sie den Befehl mit den entsprechenden Parametern in der Befehlszeile der Webseite ein. Z.B.:

   rename FHT_1234 fht.kitchen 

Manuelles Anlegen

Wenn Sie das Gerät manuell anlegen wollen oder müssen, weil autocreate diese nicht anlegen kann, dann gehen Sie folgendermaßen vor:

Warten Sie eine Weile bis Daten übertragen werden. Im Logfile (zu erreichen unter Webseite Menüpunkt Unsorted-> FileLog -> Logfile -> text) erscheint z.B. folgende Textzeile:

   FS20 Unknown device <HOUSECODE>, Button <BTN> Code <CDE>, please define it  

Definieren Sie dieses neue Gerät mittels folgendem Eintrag:

   define piri1 FS20 <HOUSECODE> <BTN>  

Setzen sie das model-Attribut des Gerätes:

   attr piri1 model fs20piri  

Anschließend erhalten Sie nur noch die für dieses Gerät verfügbaren Attribute angezeigt. Hier sehen Sie eine komplette Liste der FS20 Modelle. Bei einem anderen neuen Geräten sollte eine ähnliche Nachricht im Logfile erscheinen.

Um HomeMatic- oder zWave-Geräte anzulernen, muss FHEM zuerst mit dem Befehl set CUL hmPairForSec 600 in Empfangsbereitschaft versetzt werden und anschließend der Anlernknopf auf dem Gerät gedrückt werden.

Einbinden von Geräten, die Anlernbefehle benötigen

Manche Geräte benötigen Anlernsignale, um eine Koppelung mit anderen Geräten bzw. einer Zentrale wie FHEM herzustellen. Für solche Geräte muss zunächst manuell eine Konfiguration in FHEM vorgenommen werden, um solche Anlernsignale generieren zu können.

Definieren Sie z.B. ein FS20 Gerät mit z.B folgendem Befehl in der Befehlszeile:

   define lamp1 FS20 1234 56

Dann drücken Sie den Anmeldeknopf an dem Gerät solange, bis die LED blinkt. Anschließend klicken sie auf den on Link auf der FHEM Webseite um das Einschalt-Kommando zu senden. Die LED sollte aufhören zu blinken. Das Gerät ist nun auf den Hauscode 1234 Gerätecode 56 programmiert. Sie können alternativ die 4-base ELV-Notation benutzen. Anschließend können Sie wieder modellspezifische Attribute für das Gerät setzen. Z.B.:

   attr lamp1 model fs20st

Mit diesem Eintrag bekommen Sie nunmehr wieder nur die für dieses Gerät relevanten Kommandos angezeigt.

Das automatische oder manuelle Eintragen von FHT/HomeMatic/EnOcean-Geräten in FHEM bedeutet nicht automatisch, dass das betreffende Gerät mit FHEM gepairt ist bzw. das pairing erfolgreich abgeschlossen wurde!

Andere Systeme (EnOcean/HomeMatic/ZWave) brauchen eine umfangreichere Prozedur und das entsprechende Gerät muss zuerst in den pairing mode versetzt werden. Bitte sehen Sie sich den entsprechenden Eintrag auf der commandref.html-Seite für Ihr Gerät zur Information an.

Grundlegendes zum Steuern Ihrer Geräte

Sobald Sensoren und Aktoren in FHEM eingebunden sind, können diese bereits über telnet oder die WEB-Schnittstelle gesteuert werden.

Für Einsteiger empfiehlt sich die Lektüre der [Einführung in die Automatisierung mit FHEM]. Diese ist in den wesentlichen Teilen weiterhin aktuell.

Für den Aufbau einer zeit- und ereignisorientierten Steuerung werden jedoch weitere Steuerungselemente - sogenannte "Module" - benötigt. Nachfolgend sollen kurz einige der wichtigsten Module vorgestellt werden:

Zeitabhängige Kommandos

Die einfachste Methode, zeitgesteuert Befehle ausführen zu lassen, ist ein at. Entsprechende Beispiele und Definitionen finden Sie in der commandref.

Reaktion auf Ereignisse

Um Kommandos ausführen zu lassen, sobald ein Gerät eine Nachricht (ein "Event") aussendet, wird ein event-handler benötigt. Die einfachste Form eines solchen ist ein Device vom Typ notify.

Um die in FHEM auftretenden Ereignisse besser zu verstehen/erkennen, kann ein weiteres Browser-Fenster mit dem Event monitor geöffnet oder eine Telnet-Verbindung zu FHEM aufgebaut werden. Geben Sie z.B. in der Eingabeaufforderung folgendes ein:

   telnet <fhemhost> 7072

Nachdem die Verbindung aufgebaut wurde geben Sie ein:

   inform timer 

Nun sehen Sie in dieser telnet-Verbindung bzw. im Event Monitor alle Ereignisse wie z.B.:

   2011-12-16 21:51:55 FS20 myPiri on-for-timer 120 

Gemäß diesem Eintrag können Sie eine Aktion wie folgt definieren:

   define lampNotify notify myPiri set myLamp on 

oder

   define lampNotify notify myPiri:on.* set myLamp on 

Um dieses notify zu testen können Sie die Ereignisse unter Verwendung des trigger-Kommandos simulieren. Z.B.:

   trigger myPiri on-for-timer 120 
    

at, notify und andere Eventhandler wie z.B. watchdog verwenden entweder vordefinierte FHEM-Kommandos, SHELL-Scripte oder Perl-oneliners als Argumente. Für Details und Tipps zu Perl-oneliners lesen Sie bitte den Abschnitt zu Perl Besonderheiten in der commandref. Sowohl bei der Auswertung von Ereignissen, als auch bei den FHEM-Kommandos können Sie reguläre Ausdrücke verwenden, sogenannte regex. Eine kurze Einführung zu regex finden Sie z.B. hier: https://regex101.com/.

Daten aufzeichnen und darstellen

Loggen

Um Daten/Nachrichten/Ereignisse in einer Datei zu speichern müssen Sie ein Device vom Typ FileLog anlegen. Die Funktion autocreate erstellt für neu erkannte Geräte automatisch eine Logdatei. Sie können jedoch die Funktion createlog nutzen, um später eine weitere Logdatei hinzuzufügen.

Um Daten/Nachrichten/Ereignisse in einer Datenbank zu speichern informieren Sie sich im Verzeichnis contrib/dblog der FHEM Distribution.

FHEMWEB hat eine vordefinierte Funktionen Anzeige von Dateien des Typs FileLog. Weitere Informationen im folgenden Abschnitt plot.

Die Geräte einer jeden Logdatei (FileLog) werden durch die eingegebenen Logkriterien (z.B. Jahr/Monat/Woche/Tag) bestimmt. Sie können das Archivieren mit den Attributen nrarchive oder archivecmd erlauben.

Inhalte von Logdateien plotten (zeichnen)

Die Funktion autocreate erstellt Weblinks (d.h. Plots) für neu erkannte Geräte. Der folgende Abschnitt beschreibt wie man z.B. Plots von unterschiedlichen Sensoren gemeinsam ausgibt.

Die Daten für einen Plot stammen jeweils aus seiner FileLog-Datei. Ändern Sie ggf. die Filterkriterien (regexp) wenn noch andere Daten geplottet werden sollen. Als nächsten Schritt setzen Sie das logtype-Attribut des FileLog. Damit bestimmen Sie, welche Plotvorlagedatei (.gplot) benutzt werden soll. Die Übersicht über die vorhandenen gnuplot-Dateien finden Sie unter dem Menüunkt Edit files. Die gnuplot-Dateien enthalten die zugehörigen FileLog Beispiele.

Beachten Sie bitte, dass die .gnuplot-Dateien ebenfalls bei der Darstellung von SVG anstelle des Gnuplot Backends benutzt werden.

Die gnuplot-Dateien müssen Filelog-Einträge haben, damit sie mit gnuplot scroll oder SVG benutzt werden können (Diese Zeilen werden von gnuplot, aber nicht von FHEM, als Kommentare behandelt). Wenn die Auswahl mittels der FileLog get-Funktion erfolgen soll, dann lesen Sie sich für die Syntax die mitgelieferten gnuplot-Dateien oder den column_spec Abschnitt hier durch.

Beispiele:

• attr em1000log logtype power8:Power,text
• attr fs20_log logtype fs20:Plot,text
• attr hms100th_log logtype temp4hum6:Plot,text

Lassen Sie sich das Diagramm (/denPlot) anzeigen, indem Sie darauf klicken und erstellen Sie einen Weblink der seine eigenen Attribute hat. Wenn der Weblink zur aktuellen Logdatei gehört, dann wird er als aktueller Weblink gespeichert und angezeigt (Sie müssen ihn nicht erneut definieren, wenn sich in seinem Dateinamen die Bezeichnungen für Jahr/Monat/Datum ändern).

Die Logs können entweder mit gnuplot (welches im aktuellen Pfad installiert sein muss), oder mittels des im Programm enthaltenen SVG-Moduls erstellt werden. In diesem Fall muss Ihr Browser SVG unterstützen. Alle Browser unterstützen SVG, ausser dem Internet Explorer vor der Version 9 und Android vor der Version 3.0. Wenn Sie ein Gerät mit diesen Android-Versionen benutzen, dann versuchen Sie bitte als Browser Opera oder Firefox.

Der voreingestellte Modus ist SVG. Um das zu ändern, setzen Sie die plotmode Attribute auf gnuplot oder gnuplot scroll.

Um ältere Daten anzeigen zu lassen, erstellen Sie bitte einen anderen Weblink und setzen das fixedrange-Attribut auf z.B.:

   attr weblink_1 fixedrange 2006-01-01 2007-01-01 

Um fremde (nicht unter FHEM erfasste) Daten als Plot oder als normalen Text anzuzeigen, erstellen Sie bitte ein fake-Logfile mit dem korrekten Dateinamen und einer unbenutzten regexp, z.B.:

   define messages FileLog /var/log/messages fakelog

FHEMWEB (pgm2) anpassen

Räume und Gruppen

Es ist in der Regel zu empfehlen, alle Geräte in Räumen zu gruppieren und auch innerhalb der Räume sinnvoll anzuordnen, indem Sie das group-Attribut setzen. FHEMWEB zeigt Geräte ohne Raum-Attribut im Raum (Menüpunkt) Unsorted. Fügen Sie Geräten das hidden-Raumattribut hinzu, so werden diese Geräte nicht auf der Webseite angezeigt.

Sie können ein kürzeres Menü auf der Webseite erzeugen, indem Sie Menüpunkte die nicht angezeigt werden sollen mit dem Attribut hiddenroom versehen.

Farben und Schriften können Sie durch Anpassung der Datei style.css ändern (Edit files -> style.css) oder Sie erstellen Ihren eigenen Stil (siehe auch stylesheetPrefix) dann wird Ihr neuer Stil auch nicht beim nächsten Ausführen des update-Kommandos überschrieben.

Andere Frontends

FHEMWEB kann mit dem neuen Style "f18" auch auf eine dynamischere Darstellung für verschiedene Bildschirmgeräte und -größen eingestellt werden. Darüber hinaus besteht die Möglichkeit, andere Frontends an FHEM anzubinden und darüber Ihre Geräte zu steuern und darzustellen. Entsprechende Hinweise finden Sie hier im Wiki und in dem Forumsbereich dazu.

Komplexe Strukturen

Um gleichzeitig verschiedene Geräte auf einmal anzusprechen, kann mit Filtern und Abfragen gearbeitet werden. Details entnehmen sie bitten dem devspec-Abschnitt der commandref. Z.B. können Sie die room=<roomname> Spezifikation verwenden, um gleichzeitig alle diesem Raum zugeordneten Geräte auf einmal anzusprechen.

Für noch komplexere Szenarien informieren sie sich bitte über das structure-Modul. Sie können verschiedene Ebenen wie Flure, Gebäude usw. definieren und alle Geräte einer definierten Struktur auf einmal ansprechen.

Wichtige Befehle für die erste Zeit

• list - (Wiki)
• define
• defmod
• version - (Wiki)
• update - (Wiki)
• shutdown
• notify - (Wiki)
• at - (Wiki)
• sleep
• cancel
• watchdog - (Wiki)