Quick-Start

An english version of this document is available here

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.

Bei einer Standard-Installation unter Linux befinden sich - mit Ausnahme des für den automatischen Start erforderlichen Scripts - alle Dateien, die FHEM für den Betrieb benötigt oder anlegt im Verzeichnis /opt/fhem sowie den darin befindlichen Unterverzeichnissen. Denken Sie daher rechtzeitig daran, Sicherheitskopien des Verzeichnisses anzufertigen.

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. DOIF, sequence, watchdog usw. 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

Beispiel für Solarthermie

Daten aufzeichnen: Loggen

Um Daten/Nachrichten/Ereignisse für eine spätere Analyse oder grafische Darstellung aufzuzeichnen, können Sie ein oder mehrere Device/s vom Typ FileLog anlegen. Die Funktion autocreate erstellt für neu erkannte Geräte automatisch jeweils eine Logdatei. Sie können jedoch die Funktion createlog nutzen, um später eine weitere Logdatei hinzuzufügen. Wenn Sie die Daten von mehreren Geräten in einem FileLog zusammenfassen wollen, passen Sie den regulären Ausdruck (regex) entsprechend an.

FHEMWEB hat eine vordefinierte Funktionen zur Erstellung von Grafiken aus den aufgezeichneten Daten, näheres dazu im folgenden Abschnitt.

Bei FileLog können Sie die Aufzeichnungsdauer sowie Archivierungsfunktionen selbst bestimmen. Setzen Sie dazu entsprechende Logkriterien (z.B. Jahr/Monat/Woche/Tag) bzw. die Attribute nrarchive und/oder archivecmd.

Wenn Sie statt FileLog lieber eine Datenbank nutzen wollen, können Sie dblog verwenden.

Grafische Aufarbeitung aufgezeichneter Daten: plotten

Um die aufgezeichneten Daten grafisch darzustellen, kann man in die Detailansicht eines FileLogs wechseln und dort auf "Create SVG instance" klicken. Damit gelangen Sie zum gplot-Editor.

In diesem können Sie nun alle Daten wählen, die grafisch dargestellt werden sollen und dabei auch Daten aus unterschiedlichen Quellen gemeinsam darstellen. Beachten Sie, dass Sie dazu ggf. Zwischenstände durch Drücken der Taste write .gplot file speichern müssen, um Daten aus anderen als der zuletzt genutzten Quelle auswählen zu können.

Im Beitrag Plots erzeugen sowie im Abschnitt SVG der commandref erhalten Sie hierzu weitere Informationen.

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 (bzw. Räume), 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 und Module für die erste Zeit

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