First steps in FHEM: Unterschied zwischen den Versionen

Aus FHEMWiki
Zur Navigation springen Zur Suche springen
K (→‎Event monitor: Schreibweise wie in der dt. Version (Event monitor) und Link)
Zeile 157: Zeile 157:


== Event trigger - notify ==
== Event trigger - notify ==
<!--
Now we will enable FHEM to react to an event of ''mySwitch1'': Every time ''mySwitch1'' is triggering event with command ''on'' we want to switch on ''myLamp1''.
==Bei Event ausführen - notify==


Im nächsten Schritt werden wir FHEM beibringen, auf einen Event von ''mySwitch1'' zu reagieren. Immer dann, wenn ''mySwitch1'' einen Event mit dem Befehl ''on'' auslöst, soll ''myLamp1'' eingeschaltet werden.
For it FHEM uses a "notify". Defining syntax looks like
Dazu wird in FHEM ein "notify" verwendet. Die Befehlsstruktur ist
  define <NAME> notify <REGEXP> <command>
  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_mySwitch1_on'', also ''n_'' um es als Notify kenntlich zu machen, dann das auslösende Gerät ''mySwitch1'' 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.
* Name '''<NAME>''' will help us to find this FHEM device and display its properties. This time we name the device ''n_mySwitch1_on'' - ''n_'' for marking es a notify, following by the name of triggering device and triggering command. Such a name may seem too complicated but it is very useful when working with a whole bunch ov notifies. You may name it if desired ''n1'' or ''John Doe''. Device names may consist of characters '''a-z''', '''A-Z''', '''0-9''', '''_ (underscore)''' and '''. (period)''' with a period not at first position. In perl and therefore in FHEM period has a special meaning, so avoid if possible periods in device names.
*'''<REGEXP>''' steht für "Regular Expression" und beschreibt die Bedingung, unter der das Notify ausgeführt werden soll. Regular Expressions werden in perl und FHEM sehr häufig verwendet. Sie dienen dazu, bestimmte (syntaktische) Eigenschaften von Zeichenketten zu beschreiben. So kann man mit Hilfe eines Regex beispielsweise prüfen, ob ein bestimmtes Wort in einer Zeichenkette enthalten ist oder ob es nicht in der Zeichenkette vorkommt, man kann Zahlen in einer Zeichenkette identifizieren und vieles mehr. Wann immer in FHEM ein Event auftritt, wird für alle vorhandenen Notify geprüft, ob die angegebene Regex zutrifft. In unserem Fall löst ''mySwitch1'' ein Event mit dem Befehl ''on'' aus. Um dieses Event "abzufangen" und darauf zu reagieren, wird für die Regular Expression die Schreibweise <code>mySwitch1:on</code> verwendet. Sie werden sich mit Regex später detaillierter auseinandersetzen dürfen :)
*'''<REGEXP>''' stands for "regular expression" and describes a condition for raising notify. We will meet regular expressions in perl and FHEM frequently. They are used to describe syntactical characteristics of strings, e. g. whether a string contains a given word or not, whether digits are in our string and much more. When ever in FHEM a event raises for every notify runs a check for regexp matching. In our case ''mySwitch1'' raises an event with command ''on''. To "catch" this event and react to it we have notation  <code>mySwitch1:on</code>. In future you will have much more moments to deal with regexps in detail. :)
*'''<command>''' definiert, was denn eigentlich ausgeführt werden soll. In unserem Beispiel soll das <code>set myLamp1 on</code> sein.
*'''<command>''' tells what to do. In our case: <code>set myLamp1 on</code>.


Unser Notify wird also erstellt mit
So our notify looks like
  define n_mySwitch1_on notify mySwitch1:on set myLamp1 on
  define n_mySwitch1_on notify mySwitch1:on set myLamp1 on


Nach Eingabe dieses Befehls in das Kommandofeld, abgeschlossen durch {{Taste|Enter}}, sehen Sie wieder die Detailansicht des neuen FHEM-Device, also des Notify (siehe TYPE).
After you have entered this in command field followed by {{Taste|Enter}}, you will see again detail view of the new FHEM notify device (see TYPE).


[[Datei:ErsteSchritteInFhem11.png]]
[[Datei:ErsteSchritteInFhem11.png]]


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>''.
In block ''Internals'' you can find definition '''DEF'''. Here you see all text you have entered in event definition after the word "notify" (device type). So you can see ''<regexp>'' and ''<command>''.
{{Hinweis|Im Block '''''Probably associated with''''' werden alle 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.}}
{{Hinweis|In Block '''''Probably associated with''''' you can find all FHEM devices associated with this notify. Devices are listed as clickable device names, so you can jump over with only one click to detail view of the respective device.}}


Ordnen Sie auch das Notify unserem Training zu (im unteren Bereich das Attribut ''room'' und den passenden Raum auswählen und dann auf ''attr'' klicken).
Please assign notify to room ''Training'' (find in the lower part attribute ''room'' and choose correct room followed by a click at ''attr'').


Wenn Sie nun im FHEM-Menü auf ''Training'' klicken, werden unsere drei FHEM-Devices angezeigt.
So clicking in FHEM's main menu at ''Training'' you will get our three FHEM devices.


[[Datei:ErsteSchritteInFhem12.png]]
[[Datei:ErsteSchritteInFhem12.png]]


{{Hinweis|Üblicherweise würde man das Notify keinem Raum zuordnen, da es später für den Benutzer gar nicht sichtbar sein soll. Für unsere Testdurchläufe ist es aber praktischer.}}
{{Hinweis|Usally a notify wouldn't be assigned to a room since it shouldn't be visible for user later on. We will do it anyway for our training purposes.}}


Wenn Sie nun ''mySwitch1'' auf ''on'' schalten, wird auch ''myLamp1'' auf ''on'' geschaltet. Das funktioniert scheinbar nur beim ersten Mal – wenn Sie aber den Event Monitor prüfen oder in der Detailansicht von ''myLamp1'' auf den Zeitstempel der letzten Statusänderung schauen, werden Sie sehen, dass es jedes Mal ausgeführt wird.
Now switch ''mySwitch1'' to ''on'' - ''myLamp1'' will be switched too. It seems that it works only at first time, but checking event monitor or looking in ''myLamp1'''s detail view at timestamp of last state change you can notice that it executes every time.


Damit das Ganze auch beim Ausschalten funktioniert, legen Sie ein zweites notify an:
To get it working for switching off too we define a second notify:
  define n_mySwitch1_off notify mySwitch1:off set myLamp1 off
  define n_mySwitch1_off notify mySwitch1:off set myLamp1 off
Funktioniert es wie erwartet?


Does it work like expected?


Natürlich möchte man nicht für jeden Befehl, den ein Device auslöst, ein eigenes Notify anlegen. Es geht auch einfacher.
Doubtless you dislike defining an own notify for every command a device should raise. You can get it easier.
Statt
 
Instead of
  define n_mySwitch1_on  notify mySwitch1:on  set myLamp1 on
  define n_mySwitch1_on  notify mySwitch1:on  set myLamp1 on
  define n_mySwitch1_off notify mySwitch1:off set myLamp1 off
  define n_mySwitch1_off notify mySwitch1:off set myLamp1 off
definieren wir nun
we define
  define n_mySwitch1 notify mySwitch1 set myLamp1 '''$EVENT'''
  define n_mySwitch1 notify mySwitch1 set myLamp1 '''$EVENT'''
Wir sehen, dass die Regex nun nicht mehr unterscheidet, ob ''mySwitch1'' den Event ''on'' oder ''off'' sendet. Lassen wir diese Angabe weg, löst dieses Notify bei jedem Event von ''mySwitch1'' 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 ''mySwitch1'' ein ''on'' auslöst, nimmt '''$EVENT''' den Wert ''on'' an. Entsprechend für ''off'' oder jeden anderen Befehl.
We see that this time regexp doesn't differ events ''on'' and ''off'' of ''mySwitch1''. With an absent regexp declaration notify raises for any event with whatsoever command. In executing set command we use FHEM variable '''$EVENT''' (follow the capital notation!). This is a placeholder for the command taken over from the raising event. Having from ''mySwitch1'' an ''on'', '''$EVENT''' will stand for value ''on'' too, accordingly for ''off'' and any other command.
-->


== Deleting or disabling devices – delete, disable ==
== Deleting or disabling devices – delete, disable ==

Version vom 20. August 2017, 19:22 Uhr


Clock - Under Construction.svg An dieser Seite wird momentan noch gearbeitet.




Hier entsteht die englische Fassung von Erste Schritte in FHEM...

  • Letzte Änderung der dt. Fassung: 17.05.2020
  • Letzte Änderung der engl. Fassung: 20.08.2017
  • Neuere Version ist: dt. Version


This a beginners course for those starting to work with FHEM. After you have installed FHEM on your server you may reproduce all steps without any additional smart home hardware.

This guide was primarily published by Ulrich Maass who permitted the use in FHEM wiki.

Note to editors: Everybody is called to improve orthography, grammar and style. Content changes and extentions should be discussed with the author (e. g. on associated discussion page).

First attempt

To start FHEM first time enter in your browsers address field:

http://<ip-address>:8083

e. g. http://192.168.1.1:8083.

So you get FHEM homepage:

ErsteSchritteInFhem01.png

  • At the head you can discover a white command line, where you may type in commands.
  • As a first menu entry you can see button Save config, that is intended to store configuration changes beyond a FHEM restart.
  • Beside this there are already rooms Unsorted and Everything, we will get to know later on.
  • More links are collected in a lower group, we will discuss later on too.

Advice Security Check indicates that there is no FHEM password. Ho to configure a password protection you can see at FHEM command reference commandref, where you by the way may find a description of all FHEM functions and modules. To suppress this message as a start enter in command line:

attr global motd none

and confirm this change pressing Enter-button.

ErsteSchritteInFhem02.png

Creating device - define

The main component type in FHEM is called device.Typical devices are e.g. remote controlled outlets, roller shutter motors, temperature sensors, solenoid valves etc.

But there are other kinds of devices too, where at first view you wouldn't expect it: FHEM's user interface ("FHEMWEB") is a device, there are devices without a physical equipment used to store a variable's value.

Now we will create a very simple device, called dummy.

A device of type dummy is a special object, inasmuch as it nonessential needs corresponding physical equipment (physical lamp, roller shutter, solenoid valve). So we can proceed in this guide without a real hardware system, or rather we don't need to concider differences between differrent hardware. A dummy device is generally represented on FHEM's user interface like a FHEM device with a physical equivalent.

Lets begin with a switch. It is designed to simulate a light switch on the wall. Please, enter command in command field:

define mySwitch1 dummy

"define" is the needed FHEM command, "mySwitch1" the future name of our device, "dummy" describes its type. Words "define" and "dummy" are part of FHEM'S command syntax and are unalterable, "mySwitch1" is (more or less) arbitrary. After pressing button Enter detail view of our new FHEM device mySwitch1 appears.

ErsteSchritteInFhem03.png


Info blue.png
Each device is of exactly one "type". This type determines Perl program file (more precisly called: "module"), with certain routines and properties coded. Since our device is of type dummy, FHEM can find routines and properties in module 98_dummy.pm. (Figure 98 formerly bore a meaning, now it doesn't no longer - for historical reason it is further used.)


Devices have a "state", changing in time and recorded by FHEM. E.g., some window is open, a shutter is closed, an outlet is under voltage. A state not necessary consists of exactly one value (window: "open" or "closed"), state can be described by a bunch of values (state of a Raspberry system - device type sysmon - contains CPU frequency, CPU temperature, load and much more).

Device status in FHEM consists of overall three blocks of values, called Internals, Attributes and Readings. It's early days yet to discuss in-depth meaning of these terms, but some remarks are important for our next steps:

  • Internals store very basic informationen about a device. Only in rare cases users will edit directly internals (mostly during define step).
  • Attributs control device behavior. Typically they can be changed (or even defined) by users.
  • Readings have in contrast to the values of the other two blocks a timestamp. Usually they are measured values of your device.

It may be confusing for beginners that there can be Internals and Readings of equal names (e.g. STATE and state). Though Perl distinguishes lower and upper case.


Info blue.png
Block Internals always shows basic characteristics of a FHEM device:
  • NAME: device name assigned by the user
  • TYPE: device type of FHEM device, here: dummy
  • STATE: device state shown in all summaries. Since there was no assignment till now it is initially ???.


Creating rooms

Let's do a step forward and arrange our devices in rooms. You may consider reasonable to put together devices physically (really) located in one room into a FHEM room. So you can find in "bedroom" appropriate devices like "shutter", "time switch" and "radio set". You may decide other assignments: put all measuring devices like thermometers, electric meters and hygrometers in one (possibly only virtually and not physically existing) room "measuring devices". Name of a room is arbitrary.

To achieve this you have to add to all devices your room should contain an "Attribute" (see above). Name of the attribute is "room" and it should get as its value the room name. Let's try it with our room dummy. Use command

attr mySwitch1 room Training

and finish input with Enter).

With this command you have added to device mySwitch1 Attribute room with value Training. Again, attr, mySwitch1 (while referencing to an existing object's name) and room are part of FHEM's command syntax and are unalterable, Training is arbitrary.

Now mySwitch1 belongs to room Training. Due to this assignment room appears in navigation bar on the left hand side in room's block. Try to click at room Training.

ErsteSchritteInFhem04.png

FHEM will show all devices belonging to this room. Until now we have only one device: mySwitch1 - our dummy.

Beside device name always device status is on display, we still get ???. Clicking at name mySwitch1 you will return to its detailed view.

Our dummy is shown in a block with (type) label dummy. You may change label as well introducing a further attribute "group" and assigning to it (arbitrary as well) name: groups order devices inside a room.

Note:
If you want to delete a room, you may do so removing all devices from this room. In our example of room Training you have to delete in all devices of room Training attribute room. Room Training will dispear by itself.

Creating switching commands

Now we want to add on/off-buttons to "mySwitch1":

attr mySwitch1 webCmd on:off

Again we use an attribute named webCmd with values on:off, we want to add to device "mySwitch1". Instead of entering mentioned above command into command line field you may choose desired attribute (in this case: webCmd) in lower part of detail view and enter needed values into text field right next, in this case on:off. Complete your input with a click on button attr.

ErsteSchritteInFhem05.png

Now let's click again on room Training.

You may see, that due to atribute added in last step in room view switch buttons for on and off have appeared.

ErsteSchritteInFhem06.png

Click experimentally on on and off: instead of ??? you got so far you may find a bulb symbol showing current state.

Clicking on device name mySwitch1 you change back to detail view and may see in block Internals current state STATE - being shown in room view as an icon (bulb).

ErsteSchritteInFhem07.png

In detail view you can see a new block Readings as well.

Please switch off mySwitch1 once again. Pay attention to readings: next to internal STATE you may find a reading of same name (see above: Perl distinguishes lower and upper case), but equipped with a timestamp. Check reading state for updating at value and timestamp.

Event monitor

Please, open in your browser another window with FHEM and in FHEM its Event monitor. The shortest way is to right-click on Event monitor and to select from the local menu "Open in new window". Place Windows in such a way, that you can follow event monitor and operate your "mySwitch1" at once. Using Windows 7 or newer simply activate one window and press Windows+Pfeil rechts, followed by activating second window and pressing Windows+Pfeil links.

ErsteSchritteInFhem08.png

Devices communicate via events. One device sends an event to FHEM and FHEM distributes this event to all devices. Devices decide whether to react or not and if yes - how. Let's have a closer look at this.

Switching mySwitch1 FHEM generates an event. With every actuation of the switch yet another event appears in Event monitor. Please look what happens when you consecutively click twice on on.

Events always consist of a timestamp followed by the type of the triggering device (in this case: dummy), name of the triggering device (in this case: mySwitch1) as well as triggered command (in this case: on or off).

FHEM devices like remotes or remote-controlled wall switches, which trigger physical events, generate events in FHEM with every keypress in device itself or click on associated FHEM device.

Understanding events, their structure and operation is crucial - we will frequently need them below.

Operating devices - set

So you have learned to switch mySwitch1 clicking at on or off. Alternatively you can use command line entering instructions there.

So please, enter in command line field set mySwitch1 on or set mySwitch1 off and confirm this with button Enter. Switching status will change accordingly as well and an Event will be triggered. By the way, we will frequently use command set in future.

Preparing further tests we now create a new device myLamp1 that we later on want to control with mySwitch1.

define myLamp1 dummy

Since myLamp1 is a lamp - an actor - it won't get buttons for on or off.

Lamp should be located in room Training. You might set this assignment via command line, like shown above. But this time we will use computer mouse...

Until now myLamp1 has no room assignment, so it appears in room Unsorted. Change over in this room and click at name myLamp1 getting so detail view.

In the lower part we can set attribute assignments.

Attribute room is already selected (as default). When you click at text field next to room, a dialog box opens that contains all rooms FHEM knows so far. You may select one ore more checkboxes and assign this or these rooms to device. Now select only room Training and confirm selection with button OK. Selected room will be transferred into text field and it remains only to click at button attr to activate assingment.

ErsteSchritteInFhem09.png

Now change back to room Training and you will see both devices:

ErsteSchritteInFhem10.png

Event trigger - notify

Now we will enable FHEM to react to an event of mySwitch1: Every time mySwitch1 is triggering event with command on we want to switch on myLamp1.

For it FHEM uses a "notify". Defining syntax looks like

define <NAME> notify <REGEXP> <command>
  • Name <NAME> will help us to find this FHEM device and display its properties. This time we name the device n_mySwitch1_on - n_ for marking es a notify, following by the name of triggering device and triggering command. Such a name may seem too complicated but it is very useful when working with a whole bunch ov notifies. You may name it if desired n1 or John Doe. Device names may consist of characters a-z, A-Z, 0-9, _ (underscore) and . (period) with a period not at first position. In perl and therefore in FHEM period has a special meaning, so avoid if possible periods in device names.
  • <REGEXP> stands for "regular expression" and describes a condition for raising notify. We will meet regular expressions in perl and FHEM frequently. They are used to describe syntactical characteristics of strings, e. g. whether a string contains a given word or not, whether digits are in our string and much more. When ever in FHEM a event raises for every notify runs a check for regexp matching. In our case mySwitch1 raises an event with command on. To "catch" this event and react to it we have notation mySwitch1:on. In future you will have much more moments to deal with regexps in detail. :)
  • <command> tells what to do. In our case: set myLamp1 on.

So our notify looks like

define n_mySwitch1_on notify mySwitch1:on set myLamp1 on

After you have entered this in command field followed by Enter, you will see again detail view of the new FHEM notify device (see TYPE).

ErsteSchritteInFhem11.png

In block Internals you can find definition DEF. Here you see all text you have entered in event definition after the word "notify" (device type). So you can see <regexp> and <command>.

Info blue.png
In Block Probably associated with you can find all FHEM devices associated with this notify. Devices are listed as clickable device names, so you can jump over with only one click to detail view of the respective device.


Please assign notify to room Training (find in the lower part attribute room and choose correct room followed by a click at attr).

So clicking in FHEM's main menu at Training you will get our three FHEM devices.

ErsteSchritteInFhem12.png


Info blue.png
Usally a notify wouldn't be assigned to a room since it shouldn't be visible for user later on. We will do it anyway for our training purposes.


Now switch mySwitch1 to on - myLamp1 will be switched too. It seems that it works only at first time, but checking event monitor or looking in myLamp1's detail view at timestamp of last state change you can notice that it executes every time.

To get it working for switching off too we define a second notify:

define n_mySwitch1_off notify mySwitch1:off set myLamp1 off

Does it work like expected?

Doubtless you dislike defining an own notify for every command a device should raise. You can get it easier.

Instead of

define n_mySwitch1_on  notify mySwitch1:on  set myLamp1 on
define n_mySwitch1_off notify mySwitch1:off set myLamp1 off

we define

define n_mySwitch1 notify mySwitch1 set myLamp1 $EVENT

We see that this time regexp doesn't differ events on and off of mySwitch1. With an absent regexp declaration notify raises for any event with whatsoever command. In executing set command we use FHEM variable $EVENT (follow the capital notation!). This is a placeholder for the command taken over from the raising event. Having from mySwitch1 an on, $EVENT will stand for value on too, accordingly for off and any other command.

Deleting or disabling devices – delete, disable

Save Config

Modifying existing – modify

Switching a couple of devices at once

Renaming devices

Scheduler - at

Event-driven timer start - notify und at

How do we go on?