Erste Schritte in FHEM

An dieser Seite wird momentan noch gearbeitet.

Eine kurze Erklärung zu den ersten Schritten in fhem.

Diese Anleitung wurde ursprünglich von Ulrich Maass publiziert, der die Genehmigung erteilt hat, sie auch im Wiki zu veröffentlichen.

Der erste Einstieg

Um fhem zum ersten Mal aufzurufen, geben Sie im Browser ein:

http://<ip-Adresse>:8083

also z.B. http://192.168.1.1:8083. Sie gelangen auf den Startbildschirm:

• Am oberen Bildschirmrand sehen Sie das weiße Kommandofeld, in das Sie Befehle tippen können.
• Als ersten Menüpunkt sehen Sie die Schaltfläche Save config, mit der Änderungen so gespeichert werden, dass sie auch nach einem Neustart noch vorhanden sind.
• Außerdem gibt es bereits die Räume Unsorted und Everything, die wir bald kennenlernen.
• Im unteren Block befinden sich weitere Links, auf die wir später ebenfalls eingehen.

Der Hinweis Security Check besagt, dass Sie noch kein Passwort für fhem eingerichtet haben. Wie man einen Passwortschutz einrichten kann, steht in der fhem-Befehlsreferenz commandref, in der es übrigens eine Beschreibung zu allen Funktionen und Modulen von fhem gibt. Um diese Meldung erst einmal zu unterdrücken, geben Sie in das Kommandofeld ein:

attr global motd none

und bestätigen Ihre Eingabe mit der Enter-Taste.

Devices anlegen - define

Um fhem zunächst kennenzulernen, legen wir erst einmal einige "dummy"-devices an. So können Sie diese Tests auch ohne ein Hardware-System durchführen bzw. kann hier eine allgemeine Einführung erfolgen, ohne auf die Unterschiede der einzelnen Hardwaresysteme einzugehen. Ein dummy-device sieht auf der fhem-Oberfläche im Allgemeinen genau so aus, wie ein fhem-device zu einem "echten" Gerät Ihres Hardwaresystems.

Zunächst legen wir einen Schalter an. Dieser soll einen Lichtschalter an der Wand simulieren. Geben Sie dazu folgenden Befehl in das Kommandofeld ein:

define mySchalter1 dummy

Nach drücken der Enter-Taste wird die Detail-Ansicht des neuen fhem-device "mySchalter1" angezeigt.

Der Block Internals zeigt immer die grundlegende Ausprägung eines fhem-device an:

• NAME ist der von Ihnen vergebene Name.
• TYPE ist der Typ des fhem-device, hier dummy.
• STATE ist der in allen Übersichten angezeigte Status des Geräts. Da noch keine Zuordnung stattgefunden hat, ist dieser zunächst ???.

Räume definieren

In Räumen können Sie Geräte gruppieren, die sich auch physisch in einem Raum (Wohnzimmer, Schlafzimmer, etc.) befinden.

Um ein Device einem Raum zuzuordnen (der Raum muss zu diesem Zeitpunkt noch nicht existieren), verwenden Sie folgenden Befehl:

attr mySchalter1 room Schulungsraum

Nach Eingabe dieses Befehls in das Kommandofeld und Abschließen der Eingabe mit Enter ist das Device dem Raum Schulungsraum zugeordnet. Durch diese Zuordnung ist dieser Raum links zur Liste der Räume hinzugefügt worden.

Klicken Sie einmal auf den Raum Schulungsraum.

Es werden nun alle Geräte angezeigt, die diesem Raum zugeordnet wurden. Bisher haben wir hier nur ein Gerät: mySchalter1. Es wird in einem Block mit der Typbezeichnung dummy dargestellt. Neben dem Device-Namen wird immer der Status des Device angezeigt, hier noch ???. Wenn Sie auf den Namen mySchalter1 klicken, gelangen Sie wieder in dessen Detailansicht.

Schaltbefehle definieren

Nun soll unser mySchalter1 Schalterflächen für on und off bekommen.

attr mySchalter1 webCmd on:off

Statt den o.g. Befehl in das Kommandofeld einzugeben, können Sie auch im unteren Bereich der Detailansicht das gewünschte Attribut (hier: webCmd) auswählen und in dem Textfeld rechts daneben die gewünschten Werte eintragen, hier on:off. Schließen Sie Ihre Eingabe durch Klick auf den Button attr ab.

Klicken Sie nun wieder links auf den Schulungsraum.

Sie sehen, dass durch die Attribut-Angabe im vorhergehenden Schritt, nun in der Raumansicht die Schaltflächen für on und off hinzugekommen sind.

Klicken Sie versuchsweise auf on und off: Statt der bisher angezeigten ??? erscheint nun ein Glühbirnensymbol, das den aktuellen Status darstellt.

Wenn Sie durch Klicken auf den Device-Namen mySchalter1 wieder in die Detailansicht wechseln, sehen Sie, dass im Block Internals nun auch der aktuelle Zustand STATE angezeigt wird. Dieser wird in der Raumansicht als Icon (Glühbirne) dargestellt.

Auch sehen Sie im Detail-Bildschirm einen neuen Block Readings. Dieser zeigt Informationen an, die - anders als Attribute - nicht direkt vom Anwender geändert werden können. Unter anderem werden hier Datum und Uhrzeit der letzten Zustandsänderung angezeigt.

Schalten Sie mySchalter1 noch einmal aus und prüfen Sie, ob das Reading STATE incl. seines Zeitstempels aktualisiert wurde.

Event Monitor

Öffnen Sie nun in Ihrem Browser ein zusätzliches Fenster, in dem Sie ebenfalls fhem und darin den Event Monitor anzeigen. Am Schnellsten geht das, indem Sie mit der rechten Maustaste auf Event Monitor klicken und aus dem Kontextmenü des Browsers Öffnen in neuem Fenster auswählen. Legen Sie die Fenster so übereinander, dass Sie gleichzeitig den Event Monitor sehen und Ihren mySchalter1 bedienen können. Unter Windows ab Version 7 geht das am Einfachsten, wenn Sie zuerst das eine Fenster aktivieren und Windows+Pfeil rechts drücken, anschließend das selbe mit dem anderen Fenster und Windows+Pfeil links wiederholen.

Bei jedem Schalten von mySchalter1 wird in fhem ein Ereignis, englisch event, ausgelöst. Bei jeder Betätigung des Schalters erscheint ein neuer Event im Event Monitor. Probieren Sie auch, was passiert, wenn Sie zweimal hintereinander auf on klicken.

Ein Event besteht immer aus dem Zeitstempel, gefolgt vom Typ des auslösenden Gerätes (hier dummy), dem auslösenden Device-Namen (hier mySchalter1), sowie dem ausgelösten Befehl (hier on oder off).

Auch "echte" sendende fhem-Geräte, also z.B. eine Fernbedienung oder ein Funkschalter an der Wand, lösen bei jedem Tastendruck auf dieses Gerät oder bei Klick auf das zugehörige fhem-Device einen Event aus. Das Verständnis von Events und wie sie aufgebaut sind ist also elementar, wir werden sie noch oft benötigen. Probieren Sie ein wenig damit herum.

mySchalter1 kann also über Klicken auf on oder off geschaltet werden. Alternativ geht das auch über die Eingabe eines Befehls in das Kommandofeld.

Schalten von Geräten - set

Geben Sie in das Kommandofeld set mySchalter1 on oder set mySchalter1 off ein und bestätigen jeweils mit der Enter-Taste. Auch hierbei ändert sich der Schaltzustand und ein Event wird ausgelöst. Den set-Befehl werden wir ebenfalls noch häufig verwenden.

Für weitere Tests legen wir nun ein neues Device myLampe1 an. Diese wollen wir später mit mySchalter1 bedienen.

define myLampe1 dummy

Da dies eine Lampe, also einen Aktor darstellen soll, werden wir der Lampe selbst keine Buttons für on oder off geben.

Die Lampe soll im Schulungsraum stehen. Diese Zuordnung könnten Sie wie zuvor über die Kommandozeile erreichen. Diesmal sind wir aber tippfaul und möchten die Zuordnung durch Klicken vornehmen.

Da myLampe1 noch keinem Raum zugeordnet ist, erscheint sie im Raum Unsorted. Wechseln Sie in diesen Raum und klicken Sie auf den Namen von myLampe1, um in die Detailansicht zu gelangen.

Im unteren Bereich können wir wieder die Attributzuordnung vornehmen.

Praktischerweise ist das Attribut room bereits ausgewählt, auch der Raum Schulungsraum ist bereits voreingestellt. Sie müssen also nur noch auf den Button attr klicken.

Wechseln Sie nun wieder in den Raum Schulungsraum. Es werden nun beide Geräte angezeigt.

Bei Event ausführen - notify

Im nächsten Schritt werden wir fhem beibringen, auf einen Event von mySchalter1 zu reagieren. Immer dann, wenn mySchalter1 einen Event mit dem Befehl on auslöst, soll myLampe1 eingeschaltet werden. Dazu wird in fhem ein "notify" verwendet. Die Befehlsstruktur ist

define <NAME> notify <REGEXP> <command>

• Der Name <name> dient später dazu, dieses fhem-Device anzeigen und wiederfinden zu können. Als Name verwende ich hier n_mySchalter1_on, also n_ um es als Notify kenntlich zu machen, dann das auslösende Gerät mySchalter1 und den auslösenden Event on. Dieser Name scheint jetzt kompliziert, ist aber hilfreich, wenn Sie später mehrere Notify angelegt haben. Sie können es ganz nach Gusto auch n1 nennen oder Karlheinz. Device-Namen dürfen aus den Zeichen a-z, A-Z, 0-9, Unterstrich _ und Punkt . bestehen, wobei ein Punkt nicht an erster Stelle stehen darf. Sie werden später sehen, dass der Punkt in perl und damit fhem eine besondere Bedeutung hat, wenn möglich sollten Sie daher auf seine Verwendung in Device-Namen verzichten.
• <regex> steht für "Regular Expression" und ist die Bedingung, unter der das Notify ausgeführt werden soll. Wann immer in fhem ein Event auftritt, wird für alle vorhandenen Notify geprüft, ob die angegebene Regex zutrifft. Der auslösende Event ist in unserem Fall, dass mySchalter1 ein Event mit dem Befehl on erzeugt. Dafür wird für die Regular Expression die Schreibweise mySchalter1:on verwendet. Regular Expressions werden in perl und fhem häufig verwendet, Sie werden sich damit später detaillierter auseinandersetzen dürfen :)
• <command> definiert, was denn eigentlich ausgeführt werden soll. In unserem Beispiel soll das set myLampe1 on sein.

Unser Notify wird also erstellt mit

define n_mySchalter1_on notify mySchalter1:on set myLampe1 on

Nach Eingabe dieses Befehls in das Kommandofeld, abgeschlossen durch Enter, sehen Sie wieder die Detailansicht des neuen fhem-Device, also des Notify (siehe TYPE).

Im Block Internals sehen Sie hier die Definition DEF. Angezeigt wird hier alles, was bei der Definition nach dem Wort "notify", also nach dem Gerätetyp angegeben wurde. Es erscheinen also <regexp> und <command>.

Im unteren Bereich werden die fhem-Devices angezeigt, die mit dem Notify verbunden sind. Die Geräte werden als klickbare Device-Namen angezeigt. Das ist praktisch, da man so mit einem Klick zur Detailansicht des jeweiligen Geräts springen kann.

Ordnen Sie auch das Notify unserem Schulungsraum zu (im unteren Bereich das Attribut room und den passenden Raum auswählen und dann auf attr klicken).

Wenn Sie nun im fhem-Menü auf Schulungsraum klicken, werden unsere drei fhem-Devices angezeigt.

Hinweis: Üblicherweise würde man das Notify nicht dem Raum zuordnen, da es später für den Benutzer gar nicht sichtbar sein soll. Für unsere Testdurchläufe ist es aber praktischer.

Wenn Sie nun mySchalter1 auf on schalten, wird auch myLampe1 auf on geschaltet. Das funktioniert scheinbar nur beim ersten Mal – wenn Sie aber den Event Monitor prüfen oder in der Detailansicht von myLampe1 auf den Zeitstempel der letzten Statusänderung schauen, werden Sie sehen, dass es jedes Mal ausgeführt wird.

Damit das Ganze auch beim Ausschalten funktioniert, legen Sie ein zweites notify an:

define n_mySchalter1_off notify mySchalter1:off set myLampe1 off

Funktioniert es wie erwartet?

Natürlich möchte man nicht für jeden Befehl, den ein Device auslöst, ein eigenes Notify anlegen. Es geht auch einfacher. Statt

define n_mySchalter1_on  notify mySchalter1:on  set myLampe1 on
define n_mySchalter1_off notify mySchalter1:off set myLampe1 off

definieren wir nun

define n_mySchalter1     notify mySchalter1     set myLampe1 $EVENT

Wir sehen, dass die Regex nun nicht mehr unterscheidet, ob mySchalter1 den Event on oder off sendet. Lassen wir diese Angabe weg, löst dieses Notify bei jedem Event von mySchalter1 aus, egal mit welchem Kommando. Im auszuführenden set-Befehl verwenden wir nun die fhem-Variable $EVENT (Groß/Kleinschreibung beachten!). Dies ist ein Platzhalter für den Befehl, der vom auslösenden Event übernommen wird. Wenn also mySchalter1 ein on auslöst, nimmt $EVENT den Wert on an. Entsprechend für off oder jeden anderen Befehl.

Wenn Sie den Event Monitor beachten, werden Sie sehen, dass nach jeder Betätigung von mySchalter1 der Befehl für myLampe1 nun zweimal ausgeführt wird. Das liegt daran, dass auf jeden Event von mySchalter1 zwei Notify reagieren – sowohl die "alten" Notify wie auch das Neue. Um dies zu umgehen, müssen wir die alten Notify loswerden. Dazu gibt es zwei Möglichkeiten.

Devices löschen oder deaktivieren – delete, disable

1. Löschen Sie ein Notify mit dem Befehl delete <name>, z.B. mit delete n_mySchalter1_on. Der delete Befehl funktioniert übrigens für jedes Objekt in fhem. Sie können damit also auch "echte" Devices löschen.
2. Deaktivieren Sie ein Notify, indem Sie das Attribut disable verwenden. Das können Sie wieder über die Detailansicht des Notify setzen (im unteren Bereich das Attribut disable auswählen und den Wert 1 auswählen), oder in der Kommandozeile attr n_mySchalter1_off disable 1 eingeben.