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

Beim ersten Start ist FHEM über ein Webinterface (FHEMWEB) erreichbar. Die URL hierfür lautet http://<fhem-server>:8083/fhem.

Für spezielle Zwecke oder Nutzergruppen können weitere FHEMWEB-Geräte definiert werden. Dies bietet sich an, wenn man einen anderen Style als den Standard-Style f18 zusammen mit kleineren Bildschirmgrößen verwendet oder Zugänge für bestimmte Nutzergruppen mit reduziertem Funktionsumfang bereitstellen will. Daneben kann man eine telnet-Schnittstelle definieren.

• 

  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
• Links daneben befindet sich ein Symbol (+), über das Sie ein Eingabefeld für den Import von RAW-Code erreichen können
• 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 erscheinenden 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ät 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]. Zwar sind dort Neuerungen wie der Style f18, set magic, Module wie allowed oder DOIF nicht behandelt und die Auswahl an verfügbaren Hardwaresystemen hat sich seit dessen letzter Aktualisierung weiter erhöht. Dennoch bietet diese Einführung nach wie vor einen recht umfassenden Überblick in die allgemeinen Vorgehensweisen und Möglichkeiten mit FHEM.

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.

Unter Automatisierung stehen weitere Informationen zur Verfügung.

Zeitabhängige Kommandos

Zur Zeitsteuerung benötigt man einen Timehandler.

Reaktion auf Ereignisse

Geräte teilen bestimmte Aktualisierungen ihres Zustandes über Events mit, z.B. die Änderung eines Messwertes oder eines Schaltzustandes. Die Events werden von Eventhandlern empfangen und verarbeitet. Als Ergebnis der Verarbeitung werden Befehle ausgeführt.

Die einfachste Form eines Eventhandlers ist ein notify oder DOIF.

Die in FHEM auftretenden Ereignisse können mit dem Eventmonitor angezeigt werden oder in einem mit FHEM verbundenen Telnet-Client durch den Befehl inform timer.

Die angezeigten Events sind die wichtigste Grundlage, um einen Ereignisfilter, Suchmuster oder Auslöser zu formulieren.

Das Event wird auf die nachstehende Weise dargestellt:

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

Gemäß dieser Eventzeile 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 Befehls trigger 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-Ausdrücke als Argumente. Für Details und Tipps zu Perl-Ausdrücken 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/.

Kombinierte Zeit- und Ereignissteuerung

Auch eine kombinierte Zeit- und Ereignissteuerung ist mit Timehandlern und Eventhandlern möglich.

DOIF: Kombination einer Zeitspanne mit der Abfrage eines Readings

Zwischen 6 Uhr und 19 Uhr soll eine Lampe eingeschaltet werden, wenn die Helligkeit unter 40 gemessen wird. Sonst, wenn die Bedingung nicht zutrifft, soll die Lampe ausgeschaltet werden. Liegt die Helligkeit zum Beginn der Zeitspanne (6 Uhr) bereits unter 40, soll die Lampe zu diesem Zeitpunkt eingeschaltet werden. Liegt die Helligkeit zum Ende der Zeitspanne (19 Uhr) noch unter 40, soll die Lampe zu diesem Zeitpunkt ausgeschaltet werden.

Im Event monitor erscheint folgendes Event, der hervorgehobene Teil des Events löst die Bedingungsprüfung in DOIF aus.

2018-08-07 15:46:33.887 CUL_HM sensor brightness: 39.41

Im DOIF wird der Auslöser immer in eckigen Klammern angegeben, wie hier die Zeitspanne und das Ereignis; in der Definition fett hervorgehoben. Der Auslöser für das Ereignis kann über die Kombination von Gerätename (sensor) und Gerätevariable (brightness) angegeben werden, dabei wird der Wert des Readings zurückgegeben, vergleichbar mit set magic. Die Verknüpfung von Zeitspanne und Readingsvergleich erfolgt über einen logischen Operator, dem Perl-Operator and. Der Wert des Readings wird mit einem Vergleichswert (40) über einen vergleichenden Operator verglichen, dem Perl-Operator < mit der Bedeutung kleiner als.

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

Das DOIF kann mit dem FHEM-Befehl setreading getestet werden.

 setreading sensor brightness 39

Lässt das DOIF innerhalb der Zeitspanne die Lampe einschalten.

 setreading sensor brightness 40

Lässt das DOIF innerhalb der Zeitspanne die Lampe ausschalten.

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, spezifizieren Sie bitte den readonly Parameter bei der Definition des FileLog zusätzlich zu dem korrekten Dateinamen; der <regexp> Parameter sollte identisch dem Devicenamen sein (im folgenden Beispiel also messages):

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

Das Web-Interface anpassen

In der Darstellung bis hier war FHEMWEB für das Erscheinungsbild von FHEM im Browser verantwortlich, wobei der voreingestellte Style "f18" für eine dynamische Darstellung für verschiedene Bildschirmgeräte und -größen sorgt.

Styles

Sie können das Erscheinungsbild von FHEMWEB ändern, indem Sie andere Farbschemata oder andere Styles festlegen. Dabei können Sie für verschiedene Instanzen auch unterschiedliche Styes verwenden und so z.B. das Aussehen/und oder die Funktionalität von FHEM verändern, je nachdem, ob FHEM zu Administrationszwecken oder in der regulären Anwendung aufgerufen wird.

Räume und Gruppen

Um die Geräte zu ordnen, bietet FHEMWEB eine Reihe von Möglichkeiten an. 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, mit defaultRoom läßt sich eine Startseite festlegen. 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

Neben FHEMWEB können auch andere Frontends an FHEM angebunden werden, um darüber Ihre Geräte zu steuern und darzustellen. Weiterführende Hinweise finden Sie hier im Wiki und im Forum unter FHEM » Frontends.

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)

FHEM ist ein Perl Server...

Die meisten FHEM-Nutzer werden früher oder später daran erinnert, dass FHEM in Perl programmiert ist. Auch wenn es in vielen Fällen nicht zwingend erforderlich ist, diese Programmiersprache zu erlernen, ist es für ein vertieftes Verständnis der Funktionsweise Ihrer Hausautomatisierung hilfreich, wenn Sie sich auch mit den Grundlagen zu Perl sowie der häufig vorkommenden regex-Ausdrücken vertraut machen. Manche Problemstellungen lassen sich nach wie vor am effektivsten unmittelbar mit diesen Werkzeugen lösen. Einen ersten Einblick in diese Themen finden Sie in den FHEM Befehls-Typen, PERL Besonderheiten und dem Artikel zu 99 myUtils anlegen. In dieser Artikelserie sind weitere Informationen für Fortgeschrittene und Experten zu finden.