FHEMWiki - Benutzerbeiträge [de]

ESPEasy

2019-03-09T09:01:48Z

DDT: Korrigiert: setExtentions mit userSetCmds + {args => -1}

{{Infobox Modul
|ModPurpose=Steuerung eines Espressif ESP8266 WLAN-SoC
|ModType=d
|ModCmdRef=
|ModForumArea=Bastelecke/ESP8266
|ModFTopic=55728
|ModTechName=34_ESPEasy.pm
|ModOwner={{Link2FU|7465|dev0}}
}}
Dieser Wiki-Artikel soll und kann die {{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=ESPEasy Modul-Dokumentation}}(aka FHEM Command Reference) nicht ersetzen, sondern ergänzt die Dokumentation nur um ein paar Informationen.

== Grundlegende ESP Easy Einstellungen ==

Diese Einstellungen sind in der Weboberfläche des ESP vorzunehmen und bewirken u.a., dass für jedes ESPEasy-Device ein FHEM Device angelegt wird. Das kann bspw. für einen ESP sinnvoll sein, der Relays über GPIOs schalten soll (ESPEasy Device-Type ''Switch Input'').

*Es muss ein einmaliger ESP Devicename vergeben werden (''Config'' -> ''Main Settings'' ->''Name'')
*Die verwendeten ESP Easy Devices sollten einen ESP-weit einmaligen Namen erhalten (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Name''). Ist dieser Name nicht eindeutig oder wird nicht vergeben, dann gibt es u.a. Probleme mit ESP Easy Rules [link].
*Jeder Wert, der gesendet werden soll, benötigt ebenfalls einen Namen, der in diesem ESP Device einmalig sein muss (''Device'' -> ''Edit'' -> ''Optional Settings'' -> ''Value Name'')
*Soll dieser Wert nun automatisch in einem Interval von x Sekunden (an FHEM) gesendet werden, dann muss noch das ''Delay'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Delay'') angegeben und die Option ''Send Data'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Send Data'') aktiviert werden. Die Option ''Send Boot State'' ist an dieser Stelle ebenfalls sinnvoll.

=== Attribut combineDevices ===

Wenn das oben genannte Verhalten (ein FHEM Device pro ESP Easy Device) nicht gewünscht ist, dann kann man mittels des Attributes ''combineDevices'' der {{Link2CmdRef|Anker=ESPEasy_bridge_define|Lang=en|Label=ESPEasy Bridge}} einstellen, ob die ESP Easy Devices eines einzelnen ESPs in ein FHEM Device zusammengeführt werden sollen.
Diese Funktionalität kann man global einschalten, indem man dem Attribut ''combineDevices'' den Wert ''1'' gibt.

Will man nur von bestimmten ESPs die Devices zusammen fassen, dann kann man eine komma-getrennte Liste der ESPs angeben. Die Liste kann aus ESP Namen, IP Adressen und/oder Netzwerkbereichen bestehen. Netzwerkbereiche können mit einer Netzmaske in dotted decimal (/255.255.255.0) oder in bitmask (/24) Schreibweise angegeben werden. Hostnamen und FQDNs werden nicht unterstützt.

Beispiele:
attr <esp> combineDevices ESP1,ESP2
attr <esp> combineDevices 10.0.0.148,10.0.0.149
attr <esp> combineDevices 192.168.124.0/24
attr <esp> combineDevices 192.168.124.0/255.255.255.0
attr <esp> combineDevices ESP1,ESP2,10.0.0.0/8,192.168.0.0/255.255.0.0

IPv6 Adressen/Bereiche werden zwar von FHEM, allerdings zur Zeit noch nicht von der öffentlichen ESP Easy Distribution unterstützt.

Beispiel:
attr <esp> combineDevices 2001:1a50:50a8::148,2001:abcd:efff::/48

== Presence Erkennung ==
Die "Presence Detection", also die Erkennung, ob ein ESP noch Daten sendet, wurde anhand des Alters der empfangenen (Sensor-)Werte realisiert. Vereinfacht gesagt: Werden keine Readings mehr innerhalb von x Sekunden empfangen (siehe Device-Attribut ''Interval''), wird das FHEM Device als "absent" gekennzeichnet. Das hat den Vorteil, dass auch ESP Easy Devices, die zwischen dem Senden von Daten in den so genannten Deep Sleep Modus gehen, erkannt werden können.

Das Attribut ''Interval'' gibt unter anderem vor, in welchem zeitlichen Abstand Werte vom ESP erwartet werden, damit der ESP als "present" (und nicht absent) markiert wird.

Wenn ein ESP Easy Device Werte alle 60 Sekunden sendet (Option ''Delay'' in der ESP Easy Device GUI) und das FHEM Device Interval auf 60 gesetzt ist, dann würde das Device-Reading "presence" auf "absent" wechseln, wenn innerhalb von 60-120 Sekunden keine Werte empfangen werden.

Also wäre zum Beispiel die ESP Easy Firmware so zu konfigurieren, dass mindestens ein Wert alle 60 Sekunden gesendet wird. Das Interval-Attribut des entsprechenden FHEM ESPEasy Device müsste ebenfalls auf 60 (default) gesetzt werden. Ein paar Sekunden Toleranz sind im ESPEasy Modul eingebaut.

Wenn man kein ESP Easy Device hat, das Daten an FHEM sendet, dann kann man zusätzlich einen der "System Info" Werte senden lassen und ''combineDevices'' für diesen ESP aktivieren. Es reicht nämlich, wenn ein Reading regelmäßig aktualisiert wird.

Wenn die Presence Erkennung nicht genutzt werden soll, dann muss das Attribut ''presenceCheck'' auf 0 gesetzt werden.

== Sicherheit ==

Wenn eine ESPEasy Bridge in FHEM eingerichtet wurde, dann werden Verbindungen nur von IP Adressen aus [https://tools.ietf.org/html/rfc1918 privaten Bereichen] zugelassen.

Wenn ESP Easy Geräte außerhalb dieser Bereiche Daten an FHEM senden (z.B. über das Internet), dann muss das in der ESPEasy Bridge konfiguriert werden, andernfalls wird die Verbindung abgewiesen.

Einerseits muss die IP Adresse bzw. der IP Bereich erlaubt (Attribute ''allowedIPs'', ''deniedIPs''), andererseits die Authentifizierung über "Basic Auth" in der ESPEasy Bridge eingerichtet werden.
Die Authentifizierung wird über das Attribut ''authentication'' eingeschaltet. Die Benutzerdaten für die Authentifizierung werden über die Set-Befehle ''user'' und ''pass'' der Bridge eingegeben
{{Hinweis|Hinweis: Username und Passwort werden unverschlüsselt in ./FHEM/FhemUtils/uniqueID gespeichert.}}

=== Attribut authentication ===
Beispiel:
set <espbridge> user MeinUserName
set <espbridge> pass sehrgeheim
attr <espbridge> authentication 1

=== Attribute allowedIPs / deniedIPs ===
Beispiel:
attr <espbridge> allowedIPs 192.0.2.0/24 # erlaubt ist 192.0.2.0 bis 192.0.2.255
attr <espbridge> deniedIPs 192.0.2.0/29 # ausgeschlossen werden aber die IPs von 192.0.2.0 bis 192.0.2.7

Das Attribut ''deniedIPs'' hat Vorrang vor ''allowedIPs''. Das bedeutet, dass verbotene IPs niemals eine Verbindung aufbauen können, auch wenn sie vorher erlaubt wurden.

Regular Expressions sind können ebenfalls verwendet werden:
attr <espbridge> allowedIPs 192.0.2.1([0-4][0-9]|50) # erlaubt IP von 192.168.30.100 bis 192.168.30.150

Alle Details dazu sind in der {{Link2CmdRef|Anker=ESPEasy_bridge_attr_allowedips|Lang=en|Label=Command Reference}} beschrieben.

== Erweiterte Beispiele==
Hier ein paar Beispiele für unterschiedlichste Anwendungsfälle

=== Schalter in FHEMWEB mit devStateIcons ===
Beispiel für GPIO 12:
attr <ESP> stateFormat {ReadingsVal($name,"presence","") eq "absent" ? "absent" : ReadingsVal($name,"GPIO12","")}
attr <ESP> devStateIcon on:ios-on-green:off off:ios-off:on absent:10px-kreis-rot:statusRequest
attr <ESP> eventMap /gpio 12 on:on/gpio 12 off:off/
attr <ESP> webCmd :

=== on-for-timer und off-for-timer ===
Beispiel für GPIO 15:
attr <ESP> /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/

=== (on|off)-for-timer und devStateIcons ===
Beispiel für GPIO 15:
attr <ESP> eventMap /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/gpio 15 on:on/gpio 15 off:off/

=== userSetCmds ===
Mithilfe des Attributes userSetCmds kann man:
*Einzelne ESP Easy Befehle nachrüsten
*Eigene oder nicht unterstützte Plugins integrieren
*Bereits integrierte Befehle verändern
*Befehle einzelner Plugins mappen: Statt 'set <dev> plugin_a on' kann man so 'set <dev> on' verwenden. Das wird z.B. benötigt, um FHEMs setExtentions oder auch um FHEMWEB Widgets nutzen zu können.

Die genrelle Syntax des Attributes ist ein Perl Hash, der die Eigenschaften des ESP Easy Befehls/Plugins beschreibt.
Folgende Eigenschaften (Keys) gibt es:
*args: Anzahl der benötigten Parameter. Default: 0
*url: Die aufzurufende URL. Default: /control?cmd=
*widget: Das FHEMWEB Widget, dass beim FHEMWEB Setter des Befehls verwendet werden soll. Default: keines
*usage: Diese Zeichenkette wird zum einen angezeigt, wenn ein falscher oder zu wenige Parameter beim Befehlsaufruf angeben wurden. Zum anderen haben folgende Zeichenketten eine besondere Bedeutung:
**<0|1|off|on>: Innerhalb des FHEM Befehl kann on/off statt 0/1 angegeben werden. An die ESP Easy Firmware wird 0/1 gesendet.
**<pin>: Bei dem Paramater handelt es sin um einen GPIO Port. Aliasnamen können verwendet werden. Siehe: get <dev> pinMap
**<text>: Dieser Paramter wird url encoded an die ESP Easy Firmware gesendet. Wird für die Ausgabe auf (O)led Displays benötigt.
*cmds: Diese Eigenschaft (key) muss ebenfalls ein Perl Hash sein. Dieser Key definiert die Unterbefehle des Plugins. Alle oben genannten Eigenschaften (Keys) können benutzt werden. Nur der Key 'url' kann nicht angegeben werden, da in diesem Fall die URL des Plugins verwendet wird.

Ein einzelner neuer Befehl 'myCmd1':
attr <dev> userSetCmds ( myCmd1 => {} )

Ein einzelner neuer Befehl 'myCmd1'. Der erste Paramater enthält einen GPIO Port, der durch Aliasnamen ersetzt werden kann. Der zweite Paramater kann als on/off geschrieben werden, gesendet wird aber 1/0:
attr <dev> userSetCmds ( myCmd1 => { usage => "<pin> <0|1|off|on>" } )

Zwei neue Befehle, mit allen default Werten:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => {} )

Zwei neue Befehle, der zweite Befehl verwendet eine abweichende URL:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => { url => "/?cmd=" } )

Beispiel für das fiktive Plugin 'LED' mit den Unterbefehlen 'rgb' und 'ct'. Die Unterbefehle 'rgb' und 'ct' können ohne Angabe des Pluginnamens 'LED' verwendet werden. Zusätzlich werden in der FHEMWEB-Ansicht die Slider Widgets hsv/ct verwendet:
<source lang="text">
attr <dev> userSetCmds (
LED => {
args => 2,
url => "/control?cmd=",
usage => "<rgb|ct> <rrggbb|colortemp>",
cmds => {
rgb => { args => 1, usage => "<rrggbb>", widget => "colorpicker,HSV" },
ct => { args => 1, usage => "<colortemp>", widget => "colorpicker,CT,2000,10,4000" }
}
}
)
</source>

=== useSetExtensions ===
Mithilfe der FHEM setExtentions kann man die Befehle on-for-timer, off-for-timer, on-till, off-till, blink, intervals, toggle, etc nutzen. Im Gegensatz zu den ESP Easy Firmware Befehlen 'pulse', 'longpulse' und 'longpulse_ms' laufen die Timer nicht innerhalb der ESP Easy Firmware, sondern in FHEM. Mit allen Vor- und Nachteilen.
Um die setExtensions nutzen zu können muss das Attribut 'useExtensions' auf 1 gesetzt sein. Weiterhin müssen die Befehle 'on' und 'off', für das entsprechende Device, verfügbar sein. Das kann man auf verschiedene Weisen realisieren:
==== setExtensions mit eventMap ====
In diesem Beispiel wird der Befehl 'set <dev> GPIO 15 on' mithilfe des globalen Attributs 'eventMap' auf den Befehl 'set <dev> on' gemappt. Gleiches gilt für 'off'.
<source lang="text">
attr <dev> useSetExtensions 1
attr <dev> eventMap /gpio 15 on:^on$/gpio 15 off:^off$/
</source>
==== setExtentions mit userSetCmds ====
In diesem Beispiel wird nicht das globale Attribut 'eventMap' benutzt, sondern das ESPEasy Attribut 'userSetCmds', um die 'on' und 'off' Befehle bereitzustellen.
<source lang="text">
attr <dev> useSetExtensions 1
attr <dev> userSetCmds ( on => {url=>"/control?cmd=gpio,15,1", args => -1}, off => {url=>"/control?cmd=gpio,15,0", args => -1}
)
</source>

==Logging==
===ESPEasy Bridge===
<source lang="text">
2018.02.10 08:48:06.197 4: Connection accepted from eb_10.0.0.148_25654
2018.02.10 08:48:06.199 4: ESPEasy eb_10.0.0.148_25654: Peer address accepted
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received content: {"module":"ESPEasy","version":"1.02","data":{"ESP":{"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":{"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":{"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Basic authentication accepted
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Send http close '200 OK'
2018.02.10 08:48:06.202 4: ESPEasy eb_10.0.0.148_25654: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1
2018.02.10 08:48:06.202 5: eb: dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2
2018.02.10 08:48:06.209 4: ESPEasy eb_10.0.0.148_25654: Closing tcp session.
</source>

Im Detail bedeuten die Logeinträge:

;Connection accepted from eb_10.0.0.148_25654
:Eine TCP Verbindung wurde vom ESP (IP: 10.0.0.148, source port: 25654) zur Bridge "eb" aufgebaut.

;ESPEasy eb_10.0.0.148_25654
:Es wurde ein temporäres ESPEasy Bridge Devices angelegt, das Daten von der IP 10.0.0.148 und Quellport 25654 empfängt.

;Peer address accepted
:Die IP Adresse des ESP wurde akzeptiert und die empfangenen Daten werden nun verarbeitet. Wenn die IP Adresse nicht akzeptiert wird, dann wird '''Peer address rejected''' gelogged.

;<nowiki>Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}</nowiki>
:Diese ''received header'' Zeile enthält die Daten des Headers, die via HTTP vom ESP empfangen werden. Ein eventuell vorhandenes Passwort wird maskiert.

;<nowiki>Received content: {"module":"ESPEasy","version":"1.02","data":"ESP":"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}</nowiki>
:Diese ''received content'' Zeile enthält die Daten, die vom ESP via HTTP empfangenen werden. Mehr oder weniger Klartext im JSON Format.

;Basic authentication accepted
:In diesem Schritt wird geprüft ob eine Authentifizierung erforderlich und im besten Fall auch korrekt ist.
:Folgende Meldungen wären an dieser Stelle auch möglich:
:*No basic authentication required (auf beiden Seiten ist keine basic auth eingerichtet)
:*No basic authentication active but credentials received (auf FHEM Seite ist keine basic auth eingerichtet, der ESP sendet aber basic auth)
:*Basic authentication rejected (Username oder Passwort passen nicht zusammen)

;Send http close '200 OK'
:"Quittung" an den ESP senden. Daraufhin wird der ESP die Verbindung beenden.

;<nowiki>Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1</nowiki>
:Die Daten wurden vom ESP mit dem Namen BA_SEN1 und dem ESP Device DHT22 gesendet. Auf FHEM Seite werden die Daten dem Device mit dem Ident "BA_SEN1" zugewiesen. Dieses Ident wird vom FHEM Device ESPEasy_BA_SEN1 verwendet. Für diesen ESP ist das Attribut ''combineDevices'' wirksam. Wäre ''combineDevices'' nicht aktiv, dann würde das Ident "BA_SEN1_DHT22" lauten.

;<nowiki>dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2</nowiki>
:Die Daten werden nun von der Bridge an das logische ESPEasy Device weitergegeben.
:Im Details bedeuten die einzelnen Elemente dieser Zeichenkette:
:*'''BA_SEN1::''': Daten an das FHEM Device mit dem Ident BA_SEN1 schicken.
:*'''10.0.0.148::''': IP Adresse des ESPs
:*'''1::''': autocreate enabled? ja
:*'''0::''': autosave enabled? nein
:*'''1::''': wird nicht mehr benutzt
:*'''i||unit||4||0|||''': Der ESP hat die Unit Nummer 4
:*'''i||sleep||1||0|||''': Ist der ESP für den deep sleep mode konfiguriert? ja
:*'''i||build||137||0|||''': ESPEasy build version 137
:*'''i||version||9||0|||''': ESPEasy Release 9
:*'''r||temperature||21.5||2|||''': Readingname: temperature, Wert: 21.5, Sensortyp: 2
:*'''r||humidity||12.2||2''': Readingname: humidity, Wert 12.2, Sensortyp: 2
:Je nach ESPEasy Firmware Version können die Internals (Zeilen mit i am Anfang) auch
zusätzliche/andere Informationen aufweisen.

;Closing tcp session.
:Die tcp Verbindung wird geschlossen, das temporäre ESPEasy Bridge Device wird gelöscht.

===ESPEasy Device===
<source lang="text">
2018.02.10 10:08:41.235 5: ESPEasy ESPEasy_BA_SEN1: Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2
2018.02.10 10:08:41.236 4: ESPEasy ESPEasy_BA_SEN1: temperature: 21.2
2018.02.10 10:08:41.237 4: ESPEasy ESPEasy_BA_SEN1: humidity: 10.3
2018.02.10 10:08:41.237 5: ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:0 build:137 version:9
</source>
Im Detail:

;<nowiki>Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2</nowiki>
:Das ist wieder die, bereits oben beschriebene, ''dispatch'' Zeichenkette, die jetzt vom logischen Device empfangen wurde.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: temperature: 21.2</nowiki>
;<nowiki>ESPEasy ESPEasy_BA_SEN1: humidity: 10.3</nowiki>
:Die Readings ''temperature'' und ''humidity'' wurden aktualisiert.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:1 build:137 version:9</nowiki>
:Die Internals ''unit'', ''sleep'', ''build'' und ''version'' wurden aktualisiert.

===Zusätzliche Logeinträge===
Wird ein Device via Autocreate angelegt, gibt es zusätzliche Einträge im Logfile
<source lang="text">
2018.02.10 10:23:52.243 4: ESPEasy eb_10.0.0.148_3446: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:undef combinedDevice:1
2018.02.10 10:23:52.243 2: ESPEasy eb: Autocreate ESPEasy_BA_SEN1 ESPEasy 10.0.0.148 80 eb BA_SEN1
2018.02.10 10:23:52.244 4: ESPEasy ESPEasy_BA_SEN1: Opened for BA_SEN1 10.0.0.148:80 using bridge eb
2018.02.10 10:23:52.258 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 setState 3
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 Interval 300
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: Start internalTimer +304 => 2018-02-10 10:28:57
2018.02.10 10:23:52.266 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 presenceCheck 1
2018.02.10 10:23:52.269 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 readingSwitchText 1
2018.02.10 10:23:52.271 2: ESPEasy eb: Autosave is disabled: Do not forget to save changes.
</source>

==Weblinks==
*{{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=FHEM ESPEasy Modul-Dokumentation}}
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy ESP Easy Firmware Wiki]
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy_Command_Reference ESP Easy Command Reference]
*[https://www.letscontrolit.com/wiki/index.php/Tutorial_Rules ESP Easy Rules]

==Credits==
Vielen Dank an:

*'''ESP Easy Team''', für die kontinuierliche Pflege und Erweiterungen der Software

*'''Drhrin''', für die initiale Umsetzung dieses Wiki-Eintags

ESPEasy

2018-10-14T12:19:26Z

DDT: Added credits

{{Infobox Modul
|ModPurpose=Steuerung eines Espressif ESP8266 WLAN-SoC
|ModType=d
|ModCmdRef=
|ModForumArea=Bastelecke/ESP8266
|ModFTopic=55728
|ModTechName=34_ESPEasy.pm
|ModOwner={{Link2FU|7465|dev0}}
}}
Dieser Wiki-Artikel soll und kann die {{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=ESPEasy Modul-Dokumentation}}(aka FHEM Command Reference) nicht ersetzen, sondern ergänzt die Dokumentation nur um ein paar Informationen.

== Grundlegende ESP Easy Einstellungen ==

Diese Einstellungen sind in der Weboberfläche des ESP vorzunehmen und bewirken u.a., dass für jedes ESPEasy-Device ein FHEM Device angelegt wird. Das kann bspw. für einen ESP sinnvoll sein, der Relays über GPIOs schalten soll (ESPEasy Device-Type ''Switch Input'').

*Es muss ein einmaliger ESP Devicename vergeben werden (''Config'' -> ''Main Settings'' ->''Name'')
*Die verwendeten ESP Easy Devices sollten einen ESP-weit einmaligen Namen erhalten (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Name''). Ist dieser Name nicht eindeutig oder wird nicht vergeben, dann gibt es u.a. Probleme mit ESP Easy Rules [link].
*Jeder Wert, der gesendet werden soll, benötigt ebenfalls einen Namen, der in diesem ESP Device einmalig sein muss (''Device'' -> ''Edit'' -> ''Optional Settings'' -> ''Value Name'')
*Soll dieser Wert nun automatisch in einem Interval von x Sekunden (an FHEM) gesendet werden, dann muss noch das ''Delay'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Delay'') angegeben und die Option ''Send Data'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Send Data'') aktiviert werden. Die Option ''Send Boot State'' ist an dieser Stelle ebenfalls sinnvoll.

=== Attribut combineDevices ===

Wenn das oben genannte Verhalten (ein FHEM Device pro ESP Easy Device) nicht gewünscht ist, dann kann man mittels des Attributes ''combineDevices'' der {{Link2CmdRef|Anker=ESPEasy_bridge_define|Lang=en|Label=ESPEasy Bridge}} einstellen, ob die ESP Easy Devices eines einzelnen ESPs in ein FHEM Device zusammengeführt werden sollen.
Diese Funktionalität kann man global einschalten, indem man dem Attribut ''combineDevices'' den Wert ''1'' gibt.

Will man nur von bestimmten ESPs die Devices zusammen fassen, dann kann man eine komma-getrennte Liste der ESPs angeben. Die Liste kann aus ESP Namen, IP Adressen und/oder Netzwerkbereichen bestehen. Netzwerkbereiche können mit einer Netzmaske in dotted decimal (/255.255.255.0) oder in bitmask (/24) Schreibweise angegeben werden. Hostnamen und FQDNs werden nicht unterstützt.

Beispiele:
attr <esp> combineDevices ESP1,ESP2
attr <esp> combineDevices 10.0.0.148,10.0.0.149
attr <esp> combineDevices 192.168.124.0/24
attr <esp> combineDevices 192.168.124.0/255.255.255.0
attr <esp> combineDevices ESP1,ESP2,10.0.0.0/8,192.168.0.0/255.255.0.0

IPv6 Adressen/Bereiche werden zwar von FHEM, allerdings zur Zeit noch nicht von der öffentlichen ESP Easy Distribution unterstützt.

Beispiel:
attr <esp> combineDevices 2001:1a50:50a8::148,2001:abcd:efff::/48

== Presence Erkennung ==
Die "Presence Detection", also die Erkennung, ob ein ESP noch Daten sendet, wurde anhand des Alters der empfangenen (Sensor-)Werte realisiert. Vereinfacht gesagt: Werden keine Readings mehr innerhalb von x Sekunden empfangen (siehe Device-Attribut ''Interval''), wird das FHEM Device als "absent" gekennzeichnet. Das hat den Vorteil, dass auch ESP Easy Devices, die zwischen dem Senden von Daten in den so genannten Deep Sleep Modus gehen, erkannt werden können.

Das Attribut ''Interval'' gibt unter anderem vor, in welchem zeitlichen Abstand Werte vom ESP erwartet werden, damit der ESP als "present" (und nicht absent) markiert wird.

Wenn ein ESP Easy Device Werte alle 60 Sekunden sendet (Option ''Delay'' in der ESP Easy Device GUI) und das FHEM Device Interval auf 60 gesetzt ist, dann würde das Device-Reading "presence" auf "absent" wechseln, wenn innerhalb von 60-120 Sekunden keine Werte empfangen werden.

Also wäre zum Beispiel die ESP Easy Firmware so zu konfigurieren, dass mindestens ein Wert alle 60 Sekunden gesendet wird. Das Interval-Attribut des entsprechenden FHEM ESPEasy Device müsste ebenfalls auf 60 (default) gesetzt werden. Ein paar Sekunden Toleranz sind im ESPEasy Modul eingebaut.

Wenn man kein ESP Easy Device hat, das Daten an FHEM sendet, dann kann man zusätzlich einen der "System Info" Werte senden lassen und ''combineDevices'' für diesen ESP aktivieren. Es reicht nämlich, wenn ein Reading regelmäßig aktualisiert wird.

Wenn die Presence Erkennung nicht genutzt werden soll, dann muss das Attribut ''presenceCheck'' auf 0 gesetzt werden.

== Sicherheit ==

Wenn eine ESPEasy Bridge in FHEM eingerichtet wurde, dann werden Verbindungen nur von IP Adressen aus [https://tools.ietf.org/html/rfc1918 privaten Bereichen] zugelassen.

Wenn ESP Easy Geräte außerhalb dieser Bereiche Daten an FHEM senden (z.B. über das Internet), dann muss das in der ESPEasy Bridge konfiguriert werden, andernfalls wird die Verbindung abgewiesen.

Einerseits muss die IP Adresse bzw. der IP Bereich erlaubt (Attribute ''allowedIPs'', ''deniedIPs''), andererseits die Authentifizierung über "Basic Auth" in der ESPEasy Bridge eingerichtet werden.
Die Authentifizierung wird über das Attribut ''authentication'' eingeschaltet. Die Benutzerdaten für die Authentifizierung werden über die Set-Befehle ''user'' und ''pass'' der Bridge eingegeben
{{Hinweis|Hinweis: Username und Passwort werden unverschlüsselt in ./FHEM/FhemUtils/uniqueID gespeichert.}}

=== Attribut authentication ===
Beispiel:
set <espbridge> user MeinUserName
set <espbridge> pass sehrgeheim
attr <espbridge> authentication 1

=== Attribute allowedIPs / deniedIPs ===
Beispiel:
attr <espbridge> allowedIPs 192.0.2.0/24 # erlaubt ist 192.0.2.0 bis 192.0.2.255
attr <espbridge> deniedIPs 192.0.2.0/29 # ausgeschlossen werden aber die IPs von 192.0.2.0 bis 192.0.2.7

Das Attribut ''deniedIPs'' hat Vorrang vor ''allowedIPs''. Das bedeutet, dass verbotene IPs niemals eine Verbindung aufbauen können, auch wenn sie vorher erlaubt wurden.

Regular Expressions sind können ebenfalls verwendet werden:
attr <espbridge> allowedIPs 192.0.2.1([0-4][0-9]|50) # erlaubt IP von 192.168.30.100 bis 192.168.30.150

Alle Details dazu sind in der {{Link2CmdRef|Anker=ESPEasy_bridge_attr_allowedips|Lang=en|Label=Command Reference}} beschrieben.

== Erweiterte Beispiele==
Hier ein paar Beispiele für unterschiedlichste Anwendungsfälle

=== Schalter in FHEMWEB mit devStateIcons ===
Beispiel für GPIO 12:
attr <ESP> stateFormat {ReadingsVal($name,"presence","") eq "absent" ? "absent" : ReadingsVal($name,"GPIO12","")}
attr <ESP> devStateIcon on:ios-on-green:off off:ios-off:on absent:10px-kreis-rot:statusRequest
attr <ESP> eventMap /gpio 12 on:on/gpio 12 off:off/
attr <ESP> webCmd :

=== on-for-timer und off-for-timer ===
Beispiel für GPIO 15:
attr <ESP> /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/

=== (on|off)-for-timer und devStateIcons ===
Beispiel für GPIO 15:
attr <ESP> eventMap /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/gpio 15 on:on/gpio 15 off:off/

=== userSetCmds ===
Mithilfe des Attributes userSetCmds kann man:
*Einzelne ESP Easy Befehle nachrüsten
*Eigene oder nicht unterstützte Plugins integrieren
*Bereits integrierte Befehle verändern
*Befehle einzelner Plugins mappen: Statt 'set <dev> plugin_a on' kann man so 'set <dev> on' verwenden. Das wird z.B. benötigt, um FHEMs setExtentions oder auch um FHEMWEB Widgets nutzen zu können.

Die genrelle Syntax des Attributes ist ein Perl Hash, der die Eigenschaften des ESP Easy Befehls/Plugins beschreibt.
Folgende Eigenschaften (Keys) gibt es:
*args: Anzahl der benötigten Parameter. Default: 0
*url: Die aufzurufende URL. Default: /control?cmd=
*widget: Das FHEMWEB Widget, dass beim FHEMWEB Setter des Befehls verwendet werden soll. Default: keines
*usage: Diese Zeichenkette wird zum einen angezeigt, wenn ein falscher oder zu wenige Parameter beim Befehlsaufruf angeben wurden. Zum anderen haben folgende Zeichenketten eine besondere Bedeutung:
**<0|1|off|on>: Innerhalb des FHEM Befehl kann on/off statt 0/1 angegeben werden. An die ESP Easy Firmware wird 0/1 gesendet.
**<pin>: Bei dem Paramater handelt es sin um einen GPIO Port. Aliasnamen können verwendet werden. Siehe: get <dev> pinMap
**<text>: Dieser Paramter wird url encoded an die ESP Easy Firmware gesendet. Wird für die Ausgabe auf (O)led Displays benötigt.
*cmds: Diese Eigenschaft (key) muss ebenfalls ein Perl Hash sein. Dieser Key definiert die Unterbefehle des Plugins. Alle oben genannten Eigenschaften (Keys) können benutzt werden. Nur der Key 'url' kann nicht angegeben werden, da in diesem Fall die URL des Plugins verwendet wird.

Ein einzelner neuer Befehl 'myCmd1':
attr <dev> userSetCmds ( myCmd1 => {} )

Ein einzelner neuer Befehl 'myCmd1'. Der erste Paramater enthält einen GPIO Port, der durch Aliasnamen ersetzt werden kann. Der zweite Paramater kann als on/off geschrieben werden, gesendet wird aber 1/0:
attr <dev> userSetCmds ( myCmd1 => { usage => "<pin> <0|1|off|on>" } )

Zwei neue Befehle, mit allen default Werten:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => {} )

Zwei neue Befehle, der zweite Befehl verwendet eine abweichende URL:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => { url => "/?cmd=" } )

Beispiel für das fiktive Plugin 'LED' mit den Unterbefehlen 'rgb' und 'ct'. Die Unterbefehle 'rgb' und 'ct' können ohne Angabe des Pluginnamens 'LED' verwendet werden. Zusätzlich werden in der FHEMWEB-Ansicht die Slider Widgets hsv/ct verwendet:
<source lang="text">
attr <dev> userSetCmds (
LED => {
args => 2,
url => "/control?cmd=",
usage => "<rgb|ct> <rrggbb|colortemp>",
cmds => {
rgb => { args => 1, usage => "<rrggbb>", widget => "colorpicker,HSV" },
ct => { args => 1, usage => "<colortemp>", widget => "colorpicker,CT,2000,10,4000" }
}
}
)
</source>

=== useSetExtensions ===
Mithilfe der FHEM setExtentions kann man die Befehle on-for-timer, off-for-timer, on-till, off-till, blink, intervals, toggle, etc nutzen. Im Gegensatz zu den ESP Easy Firmware Befehlen 'pulse', 'longpulse' und 'longpulse_ms' laufen die Timer nicht innerhalb der ESP Easy Firmware, sondern in FHEM. Mit allen Vor- und Nachteilen.
Um die setExtensions nutzen zu können muss das Attribut 'useExtensions' auf 1 gesetzt sein. Weiterhin müssen die Befehle 'on' und 'off', für das entsprechende Device, verfügbar sein. Das kann man auf verschiedene Weisen realisieren:
==== setExtensions mit eventMap ====
In diesem Beispiel wird der Befehl 'set <dev> GPIO 15 on' mithilfe des globalen Attributs 'eventMap' auf den Befehl 'set <dev> on' gemappt. Gleiches gilt für 'off'.
<source lang="text">
attr <dev> useSetExtensions 1
attr <dev> eventMap /gpio 15 on:^on$/gpio 15 off:^off$/
</source>
==== setExtentions mit userSetCmds ====
In diesem Beispiel wird nicht das globale Attribut 'eventMap' benutzt, sondern das ESPEasy Attribut 'userSetCmds', um die 'on' und 'off' Befehle bereitzustellen.
<source lang="text">
attr <dev> useSetExtensions 1
attr <dev> userSetCmds (
myPlugin =>
{
args => 1,
usage => "<0|1|off|on>",
cmds => {
on => { widget => "noArg" },
off => { widget => "noArg" },
}
}
)
</source>

==Logging==
===ESPEasy Bridge===
<source lang="text">
2018.02.10 08:48:06.197 4: Connection accepted from eb_10.0.0.148_25654
2018.02.10 08:48:06.199 4: ESPEasy eb_10.0.0.148_25654: Peer address accepted
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received content: {"module":"ESPEasy","version":"1.02","data":{"ESP":{"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":{"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":{"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Basic authentication accepted
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Send http close '200 OK'
2018.02.10 08:48:06.202 4: ESPEasy eb_10.0.0.148_25654: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1
2018.02.10 08:48:06.202 5: eb: dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2
2018.02.10 08:48:06.209 4: ESPEasy eb_10.0.0.148_25654: Closing tcp session.
</source>

Im Detail bedeuten die Logeinträge:

;Connection accepted from eb_10.0.0.148_25654
:Eine TCP Verbindung wurde vom ESP (IP: 10.0.0.148, source port: 25654) zur Bridge "eb" aufgebaut.

;ESPEasy eb_10.0.0.148_25654
:Es wurde ein temporäres ESPEasy Bridge Devices angelegt, das Daten von der IP 10.0.0.148 und Quellport 25654 empfängt.

;Peer address accepted
:Die IP Adresse des ESP wurde akzeptiert und die empfangenen Daten werden nun verarbeitet. Wenn die IP Adresse nicht akzeptiert wird, dann wird '''Peer address rejected''' gelogged.

;<nowiki>Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}</nowiki>
:Diese ''received header'' Zeile enthält die Daten des Headers, die via HTTP vom ESP empfangen werden. Ein eventuell vorhandenes Passwort wird maskiert.

;<nowiki>Received content: {"module":"ESPEasy","version":"1.02","data":"ESP":"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}</nowiki>
:Diese ''received content'' Zeile enthält die Daten, die vom ESP via HTTP empfangenen werden. Mehr oder weniger Klartext im JSON Format.

;Basic authentication accepted
:In diesem Schritt wird geprüft ob eine Authentifizierung erforderlich und im besten Fall auch korrekt ist.
:Folgende Meldungen wären an dieser Stelle auch möglich:
:*No basic authentication required (auf beiden Seiten ist keine basic auth eingerichtet)
:*No basic authentication active but credentials received (auf FHEM Seite ist keine basic auth eingerichtet, der ESP sendet aber basic auth)
:*Basic authentication rejected (Username oder Passwort passen nicht zusammen)

;Send http close '200 OK'
:"Quittung" an den ESP senden. Daraufhin wird der ESP die Verbindung beenden.

;<nowiki>Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1</nowiki>
:Die Daten wurden vom ESP mit dem Namen BA_SEN1 und dem ESP Device DHT22 gesendet. Auf FHEM Seite werden die Daten dem Device mit dem Ident "BA_SEN1" zugewiesen. Dieses Ident wird vom FHEM Device ESPEasy_BA_SEN1 verwendet. Für diesen ESP ist das Attribut ''combineDevices'' wirksam. Wäre ''combineDevices'' nicht aktiv, dann würde das Ident "BA_SEN1_DHT22" lauten.

;<nowiki>dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2</nowiki>
:Die Daten werden nun von der Bridge an das logische ESPEasy Device weitergegeben.
:Im Details bedeuten die einzelnen Elemente dieser Zeichenkette:
:*'''BA_SEN1::''': Daten an das FHEM Device mit dem Ident BA_SEN1 schicken.
:*'''10.0.0.148::''': IP Adresse des ESPs
:*'''1::''': autocreate enabled? ja
:*'''0::''': autosave enabled? nein
:*'''1::''': wird nicht mehr benutzt
:*'''i||unit||4||0|||''': Der ESP hat die Unit Nummer 4
:*'''i||sleep||1||0|||''': Ist der ESP für den deep sleep mode konfiguriert? ja
:*'''i||build||137||0|||''': ESPEasy build version 137
:*'''i||version||9||0|||''': ESPEasy Release 9
:*'''r||temperature||21.5||2|||''': Readingname: temperature, Wert: 21.5, Sensortyp: 2
:*'''r||humidity||12.2||2''': Readingname: humidity, Wert 12.2, Sensortyp: 2
:Je nach ESPEasy Firmware Version können die Internals (Zeilen mit i am Anfang) auch
zusätzliche/andere Informationen aufweisen.

;Closing tcp session.
:Die tcp Verbindung wird geschlossen, das temporäre ESPEasy Bridge Device wird gelöscht.

===ESPEasy Device===
<source lang="text">
2018.02.10 10:08:41.235 5: ESPEasy ESPEasy_BA_SEN1: Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2
2018.02.10 10:08:41.236 4: ESPEasy ESPEasy_BA_SEN1: temperature: 21.2
2018.02.10 10:08:41.237 4: ESPEasy ESPEasy_BA_SEN1: humidity: 10.3
2018.02.10 10:08:41.237 5: ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:0 build:137 version:9
</source>
Im Detail:

;<nowiki>Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2</nowiki>
:Das ist wieder die, bereits oben beschriebene, ''dispatch'' Zeichenkette, die jetzt vom logischen Device empfangen wurde.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: temperature: 21.2</nowiki>
;<nowiki>ESPEasy ESPEasy_BA_SEN1: humidity: 10.3</nowiki>
:Die Readings ''temperature'' und ''humidity'' wurden aktualisiert.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:1 build:137 version:9</nowiki>
:Die Internals ''unit'', ''sleep'', ''build'' und ''version'' wurden aktualisiert.

===Zusätzliche Logeinträge===
Wird ein Device via Autocreate angelegt, gibt es zusätzliche Einträge im Logfile
<source lang="text">
2018.02.10 10:23:52.243 4: ESPEasy eb_10.0.0.148_3446: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:undef combinedDevice:1
2018.02.10 10:23:52.243 2: ESPEasy eb: Autocreate ESPEasy_BA_SEN1 ESPEasy 10.0.0.148 80 eb BA_SEN1
2018.02.10 10:23:52.244 4: ESPEasy ESPEasy_BA_SEN1: Opened for BA_SEN1 10.0.0.148:80 using bridge eb
2018.02.10 10:23:52.258 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 setState 3
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 Interval 300
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: Start internalTimer +304 => 2018-02-10 10:28:57
2018.02.10 10:23:52.266 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 presenceCheck 1
2018.02.10 10:23:52.269 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 readingSwitchText 1
2018.02.10 10:23:52.271 2: ESPEasy eb: Autosave is disabled: Do not forget to save changes.
</source>

==Weblinks==
*{{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=FHEM ESPEasy Modul-Dokumentation}}
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy ESP Easy Firmware Wiki]
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy_Command_Reference ESP Easy Command Reference]
*[https://www.letscontrolit.com/wiki/index.php/Tutorial_Rules ESP Easy Rules]

==Credits==
Vielen Dank an:

*'''ESP Easy Team''', für die kontinuierliche Pflege und Erweiterungen der Software

*'''Drhrin''', für die initiale Umsetzung dieses Wiki-Eintags

ESPEasy

2018-10-12T09:20:07Z

DDT:

{{Infobox Modul
|ModPurpose=Steuerung eines Espressif ESP8266 WLAN-SoC
|ModType=d
|ModCmdRef=
|ModForumArea=Bastelecke/ESP8266
|ModFTopic=55728
|ModTechName=34_ESPEasy.pm
|ModOwner={{Link2FU|7465|dev0}}
}}
Dieser Wiki-Artikel soll und kann die {{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=ESPEasy Modul-Dokumentation}}(aka FHEM Command Reference) nicht ersetzen, sondern ergänzt die Dokumentation nur um ein paar Informationen.

== Grundlegende ESP Easy Einstellungen ==

Diese Einstellungen sind in der Weboberfläche des ESP vorzunehmen und bewirken u.a., dass für jedes ESPEasy-Device ein FHEM Device angelegt wird. Das kann bspw. für einen ESP sinnvoll sein, der Relays über GPIOs schalten soll (ESPEasy Device-Type ''Switch Input'').

*Es muss ein einmaliger ESP Devicename vergeben werden (''Config'' -> ''Main Settings'' ->''Name'')
*Die verwendeten ESP Easy Devices sollten einen ESP-weit einmaligen Namen erhalten (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Name''). Ist dieser Name nicht eindeutig oder wird nicht vergeben, dann gibt es u.a. Probleme mit ESP Easy Rules [link].
*Jeder Wert, der gesendet werden soll, benötigt ebenfalls einen Namen, der in diesem ESP Device einmalig sein muss (''Device'' -> ''Edit'' -> ''Optional Settings'' -> ''Value Name'')
*Soll dieser Wert nun automatisch in einem Interval von x Sekunden (an FHEM) gesendet werden, dann muss noch das ''Delay'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Delay'') angegeben und die Option ''Send Data'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Send Data'') aktiviert werden. Die Option ''Send Boot State'' ist an dieser Stelle ebenfalls sinnvoll.

=== Attribut combineDevices ===

Wenn das oben genannte Verhalten (ein FHEM Device pro ESP Easy Device) nicht gewünscht ist, dann kann man mittels des Attributes ''combineDevices'' der {{Link2CmdRef|Anker=ESPEasy_bridge_define|Lang=en|Label=ESPEasy Bridge}} einstellen, ob die ESP Easy Devices eines einzelnen ESPs in ein FHEM Device zusammengeführt werden sollen.
Diese Funktionalität kann man global einschalten, indem man dem Attribut ''combineDevices'' den Wert ''1'' gibt.

Will man nur von bestimmten ESPs die Devices zusammen fassen, dann kann man eine komma-getrennte Liste der ESPs angeben. Die Liste kann aus ESP Namen, IP Adressen und/oder Netzwerkbereichen bestehen. Netzwerkbereiche können mit einer Netzmaske in dotted decimal (/255.255.255.0) oder in bitmask (/24) Schreibweise angegeben werden. Hostnamen und FQDNs werden nicht unterstützt.

Beispiele:
attr <esp> combineDevices ESP1,ESP2
attr <esp> combineDevices 10.0.0.148,10.0.0.149
attr <esp> combineDevices 192.168.124.0/24
attr <esp> combineDevices 192.168.124.0/255.255.255.0
attr <esp> combineDevices ESP1,ESP2,10.0.0.0/8,192.168.0.0/255.255.0.0

IPv6 Adressen/Bereiche werden zwar von FHEM, allerdings zur Zeit noch nicht von der öffentlichen ESP Easy Distribution unterstützt.

Beispiel:
attr <esp> combineDevices 2001:1a50:50a8::148,2001:abcd:efff::/48

== Presence Erkennung ==
Die "Presence Detection", also die Erkennung, ob ein ESP noch Daten sendet, wurde anhand des Alters der empfangenen (Sensor-)Werte realisiert. Vereinfacht gesagt: Werden keine Readings mehr innerhalb von x Sekunden empfangen (siehe Device-Attribut ''Interval''), wird das FHEM Device als "absent" gekennzeichnet. Das hat den Vorteil, dass auch ESP Easy Devices, die zwischen dem Senden von Daten in den so genannten Deep Sleep Modus gehen, erkannt werden können.

Das Attribut ''Interval'' gibt unter anderem vor, in welchem zeitlichen Abstand Werte vom ESP erwartet werden, damit der ESP als "present" (und nicht absent) markiert wird.

Wenn ein ESP Easy Device Werte alle 60 Sekunden sendet (Option ''Delay'' in der ESP Easy Device GUI) und das FHEM Device Interval auf 60 gesetzt ist, dann würde das Device-Reading "presence" auf "absent" wechseln, wenn innerhalb von 60-120 Sekunden keine Werte empfangen werden.

Also wäre zum Beispiel die ESP Easy Firmware so zu konfigurieren, dass mindestens ein Wert alle 60 Sekunden gesendet wird. Das Interval-Attribut des entsprechenden FHEM ESPEasy Device müsste ebenfalls auf 60 (default) gesetzt werden. Ein paar Sekunden Toleranz sind im ESPEasy Modul eingebaut.

Wenn man kein ESP Easy Device hat, das Daten an FHEM sendet, dann kann man zusätzlich einen der "System Info" Werte senden lassen und ''combineDevices'' für diesen ESP aktivieren. Es reicht nämlich, wenn ein Reading regelmäßig aktualisiert wird.

Wenn die Presence Erkennung nicht genutzt werden soll, dann muss das Attribut ''presenceCheck'' auf 0 gesetzt werden.

== Sicherheit ==

Wenn eine ESPEasy Bridge in FHEM eingerichtet wurde, dann werden Verbindungen nur von IP Adressen aus [https://tools.ietf.org/html/rfc1918 privaten Bereichen] zugelassen.

Wenn ESP Easy Geräte außerhalb dieser Bereiche Daten an FHEM senden (z.B. über das Internet), dann muss das in der ESPEasy Bridge konfiguriert werden, andernfalls wird die Verbindung abgewiesen.

Einerseits muss die IP Adresse bzw. der IP Bereich erlaubt (Attribute ''allowedIPs'', ''deniedIPs''), andererseits die Authentifizierung über "Basic Auth" in der ESPEasy Bridge eingerichtet werden.
Die Authentifizierung wird über das Attribut ''authentication'' eingeschaltet. Die Benutzerdaten für die Authentifizierung werden über die Set-Befehle ''user'' und ''pass'' der Bridge eingegeben
{{Hinweis|Hinweis: Username und Passwort werden unverschlüsselt in ./FHEM/FhemUtils/uniqueID gespeichert.}}

=== Attribut authentication ===
Beispiel:
set <espbridge> user MeinUserName
set <espbridge> pass sehrgeheim
attr <espbridge> authentication 1

=== Attribute allowedIPs / deniedIPs ===
Beispiel:
attr <espbridge> allowedIPs 192.0.2.0/24 # erlaubt ist 192.0.2.0 bis 192.0.2.255
attr <espbridge> deniedIPs 192.0.2.0/29 # ausgeschlossen werden aber die IPs von 192.0.2.0 bis 192.0.2.7

Das Attribut ''deniedIPs'' hat Vorrang vor ''allowedIPs''. Das bedeutet, dass verbotene IPs niemals eine Verbindung aufbauen können, auch wenn sie vorher erlaubt wurden.

Regular Expressions sind können ebenfalls verwendet werden:
attr <espbridge> allowedIPs 192.0.2.1([0-4][0-9]|50) # erlaubt IP von 192.168.30.100 bis 192.168.30.150

Alle Details dazu sind in der {{Link2CmdRef|Anker=ESPEasy_bridge_attr_allowedips|Lang=en|Label=Command Reference}} beschrieben.

== Erweiterte Beispiele==
Hier ein paar Beispiele für unterschiedlichste Anwendungsfälle

=== Schalter in FHEMWEB mit devStateIcons ===
Beispiel für GPIO 12:
attr <ESP> stateFormat {ReadingsVal($name,"presence","") eq "absent" ? "absent" : ReadingsVal($name,"GPIO12","")}
attr <ESP> devStateIcon on:ios-on-green:off off:ios-off:on absent:10px-kreis-rot:statusRequest
attr <ESP> eventMap /gpio 12 on:on/gpio 12 off:off/
attr <ESP> webCmd :

=== on-for-timer und off-for-timer ===
Beispiel für GPIO 15:
attr <ESP> /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/

=== (on|off)-for-timer und devStateIcons ===
Beispiel für GPIO 15:
attr <ESP> eventMap /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/gpio 15 on:on/gpio 15 off:off/

=== userSetCmds ===
Mithilfe des Attributes userSetCmds kann man:
*Einzelne ESP Easy Befehle nachrüsten
*Eigene oder nicht unterstützte Plugins integrieren
*Bereits integrierte Befehle verändern
*Befehle einzelner Plugins mappen: Statt 'set <dev> plugin_a on' kann man so 'set <dev> on' verwenden. Das wird z.B. benötigt, um FHEMs setExtentions oder auch um FHEMWEB Widgets nutzen zu können.

Die genrelle Syntax des Attributes ist ein Perl Hash, der die Eigenschaften des ESP Easy Befehls/Plugins beschreibt.
Folgende Eigenschaften (Keys) gibt es:
*args: Anzahl der benötigten Parameter. Default: 0
*url: Die aufzurufende URL. Default: /control?cmd=
*widget: Das FHEMWEB Widget, dass beim FHEMWEB Setter des Befehls verwendet werden soll. Default: keines
*usage: Diese Zeichenkette wird zum einen angezeigt, wenn ein falscher oder zu wenige Parameter beim Befehlsaufruf angeben wurden. Zum anderen haben folgende Zeichenketten eine besondere Bedeutung:
**<0|1|off|on>: Innerhalb des FHEM Befehl kann on/off statt 0/1 angegeben werden. An die ESP Easy Firmware wird 0/1 gesendet.
**<pin>: Bei dem Paramater handelt es sin um einen GPIO Port. Aliasnamen können verwendet werden. Siehe: get <dev> pinMap
**<text>: Dieser Paramter wird url encoded an die ESP Easy Firmware gesendet. Wird für die Ausgabe auf (O)led Displays benötigt.
*cmds: Diese Eigenschaft (key) muss ebenfalls ein Perl Hash sein. Dieser Key definiert die Unterbefehle des Plugins. Alle oben genannten Eigenschaften (Keys) können benutzt werden. Nur der Key 'url' kann nicht angegeben werden, da in diesem Fall die URL des Plugins verwendet wird.

Ein einzelner neuer Befehl 'myCmd1':
attr <dev> userSetCmds ( myCmd1 => {} )

Ein einzelner neuer Befehl 'myCmd1'. Der erste Paramater enthält einen GPIO Port, der durch Aliasnamen ersetzt werden kann. Der zweite Paramater kann als on/off geschrieben werden, gesendet wird aber 1/0:
attr <dev> userSetCmds ( myCmd1 => { usage => "<pin> <0|1|off|on>" } )

Zwei neue Befehle, mit allen default Werten:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => {} )

Zwei neue Befehle, der zweite Befehl verwendet eine abweichende URL:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => { url => "/?cmd=" } )

Beispiel für das fiktive Plugin 'LED' mit den Unterbefehlen 'rgb' und 'ct'. Die Unterbefehle 'rgb' und 'ct' können ohne Angabe des Pluginnamens 'LED' verwendet werden. Zusätzlich werden in der FHEMWEB-Ansicht die Slider Widgets hsv/ct verwendet:
<source lang="text">
attr <dev> userSetCmds (
LED => {
args => 2,
url => "/control?cmd=",
usage => "<rgb|ct> <rrggbb|colortemp>",
cmds => {
rgb => { args => 1, usage => "<rrggbb>", widget => "colorpicker,HSV" },
ct => { args => 1, usage => "<colortemp>", widget => "colorpicker,CT,2000,10,4000" }
}
}
)
</source>

=== useSetExtensions ===
Mithilfe der FHEM setExtentions kann man die Befehle on-for-timer, off-for-timer, on-till, off-till, blink, intervals, toggle, etc nutzen. Im Gegensatz zu den ESP Easy Firmware Befehlen 'pulse', 'longpulse' und 'longpulse_ms' laufen die Timer nicht innerhalb der ESP Easy Firmware, sondern in FHEM. Mit allen Vor- und Nachteilen.
Um die setExtensions nutzen zu können muss das Attribut 'useExtensions' auf 1 gesetzt sein. Weiterhin müssen die Befehle 'on' und 'off', für das entsprechende Device, verfügbar sein. Das kann man auf verschiedene Weisen realisieren:
==== setExtensions mit eventMap ====
In diesem Beispiel wird der Befehl 'set <dev> GPIO 15 on' mithilfe des globalen Attributs 'eventMap' auf den Befehl 'set <dev> on' gemappt. Gleiches gilt für 'off'.
<source lang="text">
attr <dev> useSetExtensions 1
attr <dev> eventMap /gpio 15 on:^on$/gpio 15 off:^off$/
</source>
==== setExtentions mit userSetCmds ====
In diesem Beispiel wird nicht das globale Attribut 'eventMap' benutzt, sondern das ESPEasy Attribut 'userSetCmds', um die 'on' und 'off' Befehle bereitzustellen.
<source lang="text">
attr <dev> useSetExtensions 1
attr <dev> userSetCmds (
myPlugin =>
{
args => 1,
usage => "<0|1|off|on>",
cmds => {
on => { widget => "noArg" },
off => { widget => "noArg" },
}
}
)
</source>

==Logging==
===ESPEasy Bridge===
<source lang="text">
2018.02.10 08:48:06.197 4: Connection accepted from eb_10.0.0.148_25654
2018.02.10 08:48:06.199 4: ESPEasy eb_10.0.0.148_25654: Peer address accepted
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received content: {"module":"ESPEasy","version":"1.02","data":{"ESP":{"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":{"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":{"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Basic authentication accepted
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Send http close '200 OK'
2018.02.10 08:48:06.202 4: ESPEasy eb_10.0.0.148_25654: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1
2018.02.10 08:48:06.202 5: eb: dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2
2018.02.10 08:48:06.209 4: ESPEasy eb_10.0.0.148_25654: Closing tcp session.
</source>

Im Detail bedeuten die Logeinträge:

;Connection accepted from eb_10.0.0.148_25654
:Eine TCP Verbindung wurde vom ESP (IP: 10.0.0.148, source port: 25654) zur Bridge "eb" aufgebaut.

;ESPEasy eb_10.0.0.148_25654
:Es wurde ein temporäres ESPEasy Bridge Devices angelegt, das Daten von der IP 10.0.0.148 und Quellport 25654 empfängt.

;Peer address accepted
:Die IP Adresse des ESP wurde akzeptiert und die empfangenen Daten werden nun verarbeitet. Wenn die IP Adresse nicht akzeptiert wird, dann wird '''Peer address rejected''' gelogged.

;<nowiki>Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}</nowiki>
:Diese ''received header'' Zeile enthält die Daten des Headers, die via HTTP vom ESP empfangen werden. Ein eventuell vorhandenes Passwort wird maskiert.

;<nowiki>Received content: {"module":"ESPEasy","version":"1.02","data":"ESP":"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}</nowiki>
:Diese ''received content'' Zeile enthält die Daten, die vom ESP via HTTP empfangenen werden. Mehr oder weniger Klartext im JSON Format.

;Basic authentication accepted
:In diesem Schritt wird geprüft ob eine Authentifizierung erforderlich und im besten Fall auch korrekt ist.
:Folgende Meldungen wären an dieser Stelle auch möglich:
:*No basic authentication required (auf beiden Seiten ist keine basic auth eingerichtet)
:*No basic authentication active but credentials received (auf FHEM Seite ist keine basic auth eingerichtet, der ESP sendet aber basic auth)
:*Basic authentication rejected (Username oder Passwort passen nicht zusammen)

;Send http close '200 OK'
:"Quittung" an den ESP senden. Daraufhin wird der ESP die Verbindung beenden.

;<nowiki>Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1</nowiki>
:Die Daten wurden vom ESP mit dem Namen BA_SEN1 und dem ESP Device DHT22 gesendet. Auf FHEM Seite werden die Daten dem Device mit dem Ident "BA_SEN1" zugewiesen. Dieses Ident wird vom FHEM Device ESPEasy_BA_SEN1 verwendet. Für diesen ESP ist das Attribut ''combineDevices'' wirksam. Wäre ''combineDevices'' nicht aktiv, dann würde das Ident "BA_SEN1_DHT22" lauten.

;<nowiki>dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2</nowiki>
:Die Daten werden nun von der Bridge an das logische ESPEasy Device weitergegeben.
:Im Details bedeuten die einzelnen Elemente dieser Zeichenkette:
:*'''BA_SEN1::''': Daten an das FHEM Device mit dem Ident BA_SEN1 schicken.
:*'''10.0.0.148::''': IP Adresse des ESPs
:*'''1::''': autocreate enabled? ja
:*'''0::''': autosave enabled? nein
:*'''1::''': wird nicht mehr benutzt
:*'''i||unit||4||0|||''': Der ESP hat die Unit Nummer 4
:*'''i||sleep||1||0|||''': Ist der ESP für den deep sleep mode konfiguriert? ja
:*'''i||build||137||0|||''': ESPEasy build version 137
:*'''i||version||9||0|||''': ESPEasy Release 9
:*'''r||temperature||21.5||2|||''': Readingname: temperature, Wert: 21.5, Sensortyp: 2
:*'''r||humidity||12.2||2''': Readingname: humidity, Wert 12.2, Sensortyp: 2
:Je nach ESPEasy Firmware Version können die Internals (Zeilen mit i am Anfang) auch
zusätzliche/andere Informationen aufweisen.

;Closing tcp session.
:Die tcp Verbindung wird geschlossen, das temporäre ESPEasy Bridge Device wird gelöscht.

===ESPEasy Device===
<source lang="text">
2018.02.10 10:08:41.235 5: ESPEasy ESPEasy_BA_SEN1: Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2
2018.02.10 10:08:41.236 4: ESPEasy ESPEasy_BA_SEN1: temperature: 21.2
2018.02.10 10:08:41.237 4: ESPEasy ESPEasy_BA_SEN1: humidity: 10.3
2018.02.10 10:08:41.237 5: ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:0 build:137 version:9
</source>
Im Detail:

;<nowiki>Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2</nowiki>
:Das ist wieder die, bereits oben beschriebene, ''dispatch'' Zeichenkette, die jetzt vom logischen Device empfangen wurde.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: temperature: 21.2</nowiki>
;<nowiki>ESPEasy ESPEasy_BA_SEN1: humidity: 10.3</nowiki>
:Die Readings ''temperature'' und ''humidity'' wurden aktualisiert.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:1 build:137 version:9</nowiki>
:Die Internals ''unit'', ''sleep'', ''build'' und ''version'' wurden aktualisiert.

===Zusätzliche Logeinträge===
Wird ein Device via Autocreate angelegt, gibt es zusätzliche Einträge im Logfile
<source lang="text">
2018.02.10 10:23:52.243 4: ESPEasy eb_10.0.0.148_3446: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:undef combinedDevice:1
2018.02.10 10:23:52.243 2: ESPEasy eb: Autocreate ESPEasy_BA_SEN1 ESPEasy 10.0.0.148 80 eb BA_SEN1
2018.02.10 10:23:52.244 4: ESPEasy ESPEasy_BA_SEN1: Opened for BA_SEN1 10.0.0.148:80 using bridge eb
2018.02.10 10:23:52.258 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 setState 3
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 Interval 300
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: Start internalTimer +304 => 2018-02-10 10:28:57
2018.02.10 10:23:52.266 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 presenceCheck 1
2018.02.10 10:23:52.269 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 readingSwitchText 1
2018.02.10 10:23:52.271 2: ESPEasy eb: Autosave is disabled: Do not forget to save changes.
</source>

==Weblinks==
*{{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=FHEM ESPEasy Modul-Dokumentation}}
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy ESP Easy Firmware Wiki]
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy_Command_Reference ESP Easy Command Reference]
*[https://www.letscontrolit.com/wiki/index.php/Tutorial_Rules ESP Easy Rules]

ESPEasy

2018-10-12T09:19:01Z

DDT: {{Baustelle}} entfernt.

{{Infobox Modul
|ModPurpose=Steuerung eines Espressif ESP8266 WLAN-SoC
|ModType=d
|ModCmdRef=
|ModForumArea=Bastelecke/ESP8266
|ModFTopic=55728
|ModTechName=34_ESPEasy.pm
|ModOwner={{Link2FU|7465|dev0}}
}}
Dieser Wiki-Artikel soll und kann die {{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=ESPEasy Modul-Dokumentation}}(aka FHEM Command Reference) nicht ersetzen, sondern ergänzt die Dokumentation nur um ein paar Informationen.

== Grundlegende ESP Easy Einstellungen ==

Diese Einstellungen sind in der Weboberfläche des ESP vorzunehmen und bewirken u.a., dass für jedes ESPEasy-Device ein FHEM Device angelegt wird. Das kann bspw. für einen ESP sinnvoll sein, der Relays über GPIOs schalten soll (ESPEasy Device-Type ''Switch Input'').

*Es muss ein einmaliger ESP Devicename vergeben werden (''Config'' -> ''Main Settings'' ->''Name'')
*Die verwendeten ESP Easy Devices sollten einen ESP-weit einmaligen Namen erhalten (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Name''). Ist dieser Name nicht eindeutig oder wird nicht vergeben, dann gibt es u.a. Probleme mit ESP Easy Rules [link].
*Jeder Wert, der gesendet werden soll, benötigt ebenfalls einen Namen, der in diesem ESP Device einmalig sein muss (''Device'' -> ''Edit'' -> ''Optional Settings'' -> ''Value Name'')
*Soll dieser Wert nun automatisch in einem Interval von x Sekunden (an FHEM) gesendet werden, dann muss noch das ''Delay'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Delay'') angegeben und die Option ''Send Data'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Send Data'') aktiviert werden. Die Option ''Send Boot State'' ist an dieser Stelle ebenfalls sinnvoll.

=== Attribut combineDevices ===

Wenn das oben genannte Verhalten (ein FHEM Device pro ESP Easy Device) nicht gewünscht ist, dann kann man mittels des Attributes ''combineDevices'' der {{Link2CmdRef|Anker=ESPEasy_bridge_define|Lang=en|Label=ESPEasy Bridge}} einstellen, ob die ESP Easy Devices eines einzelnen ESPs in ein FHEM Device zusammengeführt werden sollen.
Diese Funktionalität kann man global einschalten, indem man dem Attribut ''combineDevices'' den Wert ''1'' gibt.

Will man nur von bestimmten ESPs die Devices zusammen fassen, dann kann man eine komma-getrennte Liste der ESPs angeben. Die Liste kann aus ESP Namen, IP Adressen und/oder Netzwerkbereichen bestehen. Netzwerkbereiche können mit einer Netzmaske in dotted decimal (/255.255.255.0) oder in bitmask (/24) Schreibweise angegeben werden. Hostnamen und FQDNs werden nicht unterstützt.

Beispiele:
attr <esp> combineDevices ESP1,ESP2
attr <esp> combineDevices 10.0.0.148,10.0.0.149
attr <esp> combineDevices 192.168.124.0/24
attr <esp> combineDevices 192.168.124.0/255.255.255.0
attr <esp> combineDevices ESP1,ESP2,10.0.0.0/8,192.168.0.0/255.255.0.0

IPv6 Adressen/Bereiche werden zwar von FHEM, allerdings zur Zeit noch nicht von der öffentlichen ESP Easy Distribution unterstützt.

Beispiel:
attr <esp> combineDevices 2001:1a50:50a8::148,2001:abcd:efff::/48

== Presence Erkennung ==
Die "Presence Detection", also die Erkennung, ob ein ESP noch Daten sendet, wurde anhand des Alters der empfangenen (Sensor-)Werte realisiert. Vereinfacht gesagt: Werden keine Readings mehr innerhalb von x Sekunden empfangen (siehe Device-Attribut ''Interval''), wird das FHEM Device als "absent" gekennzeichnet. Das hat den Vorteil, dass auch ESP Easy Devices, die zwischen dem Senden von Daten in den so genannten Deep Sleep Modus gehen, erkannt werden können.

Das Attribut ''Interval'' gibt unter anderem vor, in welchem zeitlichen Abstand Werte vom ESP erwartet werden, damit der ESP als "present" (und nicht absent) markiert wird.

Wenn ein ESP Easy Device Werte alle 60 Sekunden sendet (Option ''Delay'' in der ESP Easy Device GUI) und das FHEM Device Interval auf 60 gesetzt ist, dann würde das Device-Reading "presence" auf "absent" wechseln, wenn innerhalb von 60-120 Sekunden keine Werte empfangen werden.

Also wäre zum Beispiel die ESP Easy Firmware so zu konfigurieren, dass mindestens ein Wert alle 60 Sekunden gesendet wird. Das Interval-Attribut des entsprechenden FHEM ESPEasy Device müsste ebenfalls auf 60 (default) gesetzt werden. Ein paar Sekunden Toleranz sind im ESPEasy Modul eingebaut.

Wenn man kein ESP Easy Device hat, das Daten an FHEM sendet, dann kann man zusätzlich einen der "System Info" Werte senden lassen und ''combineDevices'' für diesen ESP aktivieren. Es reicht nämlich, wenn ein Reading regelmäßig aktualisiert wird.

Wenn die Presence Erkennung nicht genutzt werden soll, dann muss das Attribut ''presenceCheck'' auf 0 gesetzt werden.

== Sicherheit ==

Wenn eine ESPEasy Bridge in FHEM eingerichtet wurde, dann werden Verbindungen nur von IP Adressen aus [https://tools.ietf.org/html/rfc1918 privaten Bereichen] zugelassen.

Wenn ESP Easy Geräte außerhalb dieser Bereiche Daten an FHEM senden (z.B. über das Internet), dann muss das in der ESPEasy Bridge konfiguriert werden, andernfalls wird die Verbindung abgewiesen.

Einerseits muss die IP Adresse bzw. der IP Bereich erlaubt (Attribute ''allowedIPs'', ''deniedIPs''), andererseits die Authentifizierung über "Basic Auth" in der ESPEasy Bridge eingerichtet werden.
Die Authentifizierung wird über das Attribut ''authentication'' eingeschaltet. Die Benutzerdaten für die Authentifizierung werden über die Set-Befehle ''user'' und ''pass'' der Bridge eingegeben
{{Hinweis|Hinweis: Username und Passwort werden unverschlüsselt in ./FHEM/FhemUtils/uniqueID gespeichert.}}

=== Attribut authentication ===
Beispiel:
set <espbridge> user MeinUserName
set <espbridge> pass sehrgeheim
attr <espbridge> authentication 1

=== Attribute allowedIPs / deniedIPs ===
Beispiel:
attr <espbridge> allowedIPs 192.0.2.0/24 # erlaubt ist 192.0.2.0 bis 192.0.2.255
attr <espbridge> deniedIPs 192.0.2.0/29 # ausgeschlossen werden aber die IPs von 192.0.2.0 bis 192.0.2.7

Das Attribut ''deniedIPs'' hat Vorrang vor ''allowedIPs''. Das bedeutet, dass verbotene IPs niemals eine Verbindung aufbauen können, auch wenn sie vorher erlaubt wurden.

Regular Expressions sind können ebenfalls verwendet werden:
attr <espbridge> allowedIPs 192.0.2.1([0-4][0-9]|50) # erlaubt IP von 192.168.30.100 bis 192.168.30.150

Alle Details dazu sind in der {{Link2CmdRef|Anker=ESPEasy_bridge_attr_allowedips|Lang=en|Label=Command Reference}} beschrieben.

== Erweiterte Beispiele==
Hier ein paar Beispiele für unterschiedlichste Anwendungsfälle

=== Schalter in FHEMWEB mit devStateIcons ===
Beispiel für GPIO 12:
attr <ESP> stateFormat {ReadingsVal($name,"presence","") eq "absent" ? "absent" : ReadingsVal($name,"GPIO12","")}
attr <ESP> devStateIcon on:ios-on-green:off off:ios-off:on absent:10px-kreis-rot:statusRequest
attr <ESP> eventMap /gpio 12 on:on/gpio 12 off:off/
attr <ESP> webCmd :

=== on-for-timer und off-for-timer ===
Beispiel für GPIO 15:
attr <ESP> /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/

=== (on|off)-for-timer und devStateIcons ===
Beispiel für GPIO 15:
attr <ESP> eventMap /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/gpio 15 on:on/gpio 15 off:off/

=== userSetCmds ===
Mithilfe des Attributes userSetCmds kann man:
*Einzelne ESP Easy Befehle nachrüsten
*Eigene oder nicht unterstützte Plugins integrieren
*Bereits integrierte Befehle verändern
*Befehle einzelner Plugins mappen: Statt 'set <dev> plugin_a on' kann man so 'set <dev> on' verwenden. Das wird z.B. benötigt, um FHEMs setExtentions oder auch um FHEMWEB Widgets nutzen zu können.

Die genrelle Syntax des Attributes ist ein Perl Hash, der die Eigenschaften des ESP Easy Befehls/Plugins beschreibt.
Folgende Eigenschaften (Keys) gibt es:
*args: Anzahl der benötigten Parameter. Default: 0
*url: Die aufzurufende URL. Default: /control?cmd=
*widget: Das FHEMWEB Widget, dass beim FHEMWEB Setter des Befehls verwendet werden soll. Default: keines
*usage: Diese Zeichenkette wird zum einen angezeigt, wenn ein falscher oder zu wenige Parameter beim Befehlsaufruf angeben wurden. Zum anderen haben folgende Zeichenketten eine besondere Bedeutung:
**<0|1|off|on>: Innerhalb des FHEM Befehl kann on/off statt 0/1 angegeben werden. An die ESP Easy Firmware wird 0/1 gesendet.
**<pin>: Bei dem Paramater handelt es sin um einen GPIO Port. Aliasnamen können verwendet werden. Siehe: get <dev> pinMap
**<text>: Dieser Paramter wird url encoded an die ESP Easy Firmware gesendet. Wird für die Ausgabe auf (O)led Displays benötigt.
*cmds: Diese Eigenschaft (key) muss ebenfalls ein Perl Hash sein. Dieser Key definiert die Unterbefehle des Plugins. Alle oben genannten Eigenschaften (Keys) können benutzt werden. Nur der Key 'url' kann nicht angegeben werden, da in diesem Fall die URL des Plugins verwendet wird.

Ein einzelner neuer Befehl 'myCmd1':
attr <dev> userSetCmds ( myCmd1 => {} )

Ein einzelner neuer Befehl 'myCmd1'. Der erste Paramater enthält einen GPIO Port, der durch Aliasnamen ersetzt werden kann. Der zweite Paramater kann als on/off geschrieben werden, gesendet wird aber 1/0:
attr <dev> userSetCmds ( myCmd1 => { usage => "<pin> <0|1|off|on>" } )

Zwei neue Befehle, mit allen default Werten:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => {} )

Zwei neue Befehle, der zweite Befehl verwendet eine abweichende URL:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => { url => "/?cmd=" } )

Beispiel für das fiktive Plugin 'LED' mit den Unterbefehlen 'rgb' und 'ct'. Die Unterbefehle 'rgb' und 'ct' können ohne Angabe des Pluginnamens 'LED' verwendet werden. Zusätzlich werden in der FHEMWEB-Ansicht die Slider Widgets hsv/ct verwendet:
<source lang="text">
attr <dev> userSetCmds (
LED => {
args => 2,
url => "/control?cmd=",
usage => "<rgb|ct> <rrggbb|colortemp>",
cmds => {
rgb => { args => 1, usage => "<rrggbb>", widget => "colorpicker,HSV" },
ct => { args => 1, usage => "<colortemp>", widget => "colorpicker,CT,2000,10,4000" }
}
}
)
</source>

=== setExtensions ===
Mithilfe der FHEM setExtentions kann man die Befehle on-for-timer, off-for-timer, on-till, off-till, blink, intervals, toggle, etc nutzen. Im Gegensatz zu den ESP Easy Firmware Befehlen 'pulse', 'longpulse' und 'longpulse_ms' laufen die Timer nicht innerhalb der ESP Easy Firmware, sondern in FHEM. Mit allen Vor- und Nachteilen.
Um die setExtensions nutzen zu können muss das Attribut 'useExtensions' auf 1 gesetzt sein. Weiterhin müssen die Befehle 'on' und 'off', für das entsprechende Device, verfügbar sein. Das kann man auf verschiedene Weisen realisieren:
==== setExtensions mit eventMap ====
In diesem Beispiel wird der Befehl 'set <dev> GPIO 15 on' mithilfe des globalen Attributs 'eventMap' auf den Befehl 'set <dev> on' gemappt. Gleiches gilt für 'off'.
<source lang="text">
attr <dev> useSetExtensions 1
attr <dev> eventMap /gpio 15 on:^on$/gpio 15 off:^off$/
</source>
==== setExtentions mit userSetCmds ====
In diesem Beispiel wird nicht das globale Attribut 'eventMap' benutzt, sondern das ESPEasy Attribut 'userSetCmds', um die 'on' und 'off' Befehle bereitzustellen.
<source lang="text">
attr <dev> useSetExtensions 1
attr <dev> userSetCmds (
myPlugin =>
{
args => 1,
usage => "<0|1|off|on>",
cmds => {
on => { widget => "noArg" },
off => { widget => "noArg" },
}
}
)
</source>

==Logging==
===ESPEasy Bridge===
<source lang="text">
2018.02.10 08:48:06.197 4: Connection accepted from eb_10.0.0.148_25654
2018.02.10 08:48:06.199 4: ESPEasy eb_10.0.0.148_25654: Peer address accepted
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received content: {"module":"ESPEasy","version":"1.02","data":{"ESP":{"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":{"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":{"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Basic authentication accepted
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Send http close '200 OK'
2018.02.10 08:48:06.202 4: ESPEasy eb_10.0.0.148_25654: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1
2018.02.10 08:48:06.202 5: eb: dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2
2018.02.10 08:48:06.209 4: ESPEasy eb_10.0.0.148_25654: Closing tcp session.
</source>

Im Detail bedeuten die Logeinträge:

;Connection accepted from eb_10.0.0.148_25654
:Eine TCP Verbindung wurde vom ESP (IP: 10.0.0.148, source port: 25654) zur Bridge "eb" aufgebaut.

;ESPEasy eb_10.0.0.148_25654
:Es wurde ein temporäres ESPEasy Bridge Devices angelegt, das Daten von der IP 10.0.0.148 und Quellport 25654 empfängt.

;Peer address accepted
:Die IP Adresse des ESP wurde akzeptiert und die empfangenen Daten werden nun verarbeitet. Wenn die IP Adresse nicht akzeptiert wird, dann wird '''Peer address rejected''' gelogged.

;<nowiki>Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}</nowiki>
:Diese ''received header'' Zeile enthält die Daten des Headers, die via HTTP vom ESP empfangen werden. Ein eventuell vorhandenes Passwort wird maskiert.

;<nowiki>Received content: {"module":"ESPEasy","version":"1.02","data":"ESP":"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}</nowiki>
:Diese ''received content'' Zeile enthält die Daten, die vom ESP via HTTP empfangenen werden. Mehr oder weniger Klartext im JSON Format.

;Basic authentication accepted
:In diesem Schritt wird geprüft ob eine Authentifizierung erforderlich und im besten Fall auch korrekt ist.
:Folgende Meldungen wären an dieser Stelle auch möglich:
:*No basic authentication required (auf beiden Seiten ist keine basic auth eingerichtet)
:*No basic authentication active but credentials received (auf FHEM Seite ist keine basic auth eingerichtet, der ESP sendet aber basic auth)
:*Basic authentication rejected (Username oder Passwort passen nicht zusammen)

;Send http close '200 OK'
:"Quittung" an den ESP senden. Daraufhin wird der ESP die Verbindung beenden.

;<nowiki>Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1</nowiki>
:Die Daten wurden vom ESP mit dem Namen BA_SEN1 und dem ESP Device DHT22 gesendet. Auf FHEM Seite werden die Daten dem Device mit dem Ident "BA_SEN1" zugewiesen. Dieses Ident wird vom FHEM Device ESPEasy_BA_SEN1 verwendet. Für diesen ESP ist das Attribut ''combineDevices'' wirksam. Wäre ''combineDevices'' nicht aktiv, dann würde das Ident "BA_SEN1_DHT22" lauten.

;<nowiki>dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2</nowiki>
:Die Daten werden nun von der Bridge an das logische ESPEasy Device weitergegeben.
:Im Details bedeuten die einzelnen Elemente dieser Zeichenkette:
:*'''BA_SEN1::''': Daten an das FHEM Device mit dem Ident BA_SEN1 schicken.
:*'''10.0.0.148::''': IP Adresse des ESPs
:*'''1::''': autocreate enabled? ja
:*'''0::''': autosave enabled? nein
:*'''1::''': wird nicht mehr benutzt
:*'''i||unit||4||0|||''': Der ESP hat die Unit Nummer 4
:*'''i||sleep||1||0|||''': Ist der ESP für den deep sleep mode konfiguriert? ja
:*'''i||build||137||0|||''': ESPEasy build version 137
:*'''i||version||9||0|||''': ESPEasy Release 9
:*'''r||temperature||21.5||2|||''': Readingname: temperature, Wert: 21.5, Sensortyp: 2
:*'''r||humidity||12.2||2''': Readingname: humidity, Wert 12.2, Sensortyp: 2
:Je nach ESPEasy Firmware Version können die Internals (Zeilen mit i am Anfang) auch
zusätzliche/andere Informationen aufweisen.

;Closing tcp session.
:Die tcp Verbindung wird geschlossen, das temporäre ESPEasy Bridge Device wird gelöscht.

===ESPEasy Device===
<source lang="text">
2018.02.10 10:08:41.235 5: ESPEasy ESPEasy_BA_SEN1: Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2
2018.02.10 10:08:41.236 4: ESPEasy ESPEasy_BA_SEN1: temperature: 21.2
2018.02.10 10:08:41.237 4: ESPEasy ESPEasy_BA_SEN1: humidity: 10.3
2018.02.10 10:08:41.237 5: ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:0 build:137 version:9
</source>
Im Detail:

;<nowiki>Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2</nowiki>
:Das ist wieder die, bereits oben beschriebene, ''dispatch'' Zeichenkette, die jetzt vom logischen Device empfangen wurde.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: temperature: 21.2</nowiki>
;<nowiki>ESPEasy ESPEasy_BA_SEN1: humidity: 10.3</nowiki>
:Die Readings ''temperature'' und ''humidity'' wurden aktualisiert.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:1 build:137 version:9</nowiki>
:Die Internals ''unit'', ''sleep'', ''build'' und ''version'' wurden aktualisiert.

===Zusätzliche Logeinträge===
Wird ein Device via Autocreate angelegt, gibt es zusätzliche Einträge im Logfile
<source lang="text">
2018.02.10 10:23:52.243 4: ESPEasy eb_10.0.0.148_3446: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:undef combinedDevice:1
2018.02.10 10:23:52.243 2: ESPEasy eb: Autocreate ESPEasy_BA_SEN1 ESPEasy 10.0.0.148 80 eb BA_SEN1
2018.02.10 10:23:52.244 4: ESPEasy ESPEasy_BA_SEN1: Opened for BA_SEN1 10.0.0.148:80 using bridge eb
2018.02.10 10:23:52.258 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 setState 3
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 Interval 300
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: Start internalTimer +304 => 2018-02-10 10:28:57
2018.02.10 10:23:52.266 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 presenceCheck 1
2018.02.10 10:23:52.269 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 readingSwitchText 1
2018.02.10 10:23:52.271 2: ESPEasy eb: Autosave is disabled: Do not forget to save changes.
</source>

==Weblinks==
*{{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=FHEM ESPEasy Modul-Dokumentation}}
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy ESP Easy Firmware Wiki]
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy_Command_Reference ESP Easy Command Reference]
*[https://www.letscontrolit.com/wiki/index.php/Tutorial_Rules ESP Easy Rules]

ESPEasy

2018-10-12T09:09:07Z

DDT: Beispiele für setExtensions

{{Baustelle}}
{{Infobox Modul
|ModPurpose=Steuerung eines Espressif ESP8266 WLAN-SoC
|ModType=d
|ModCmdRef=
|ModForumArea=Bastelecke/ESP8266
|ModFTopic=55728
|ModTechName=34_ESPEasy.pm
|ModOwner={{Link2FU|7465|dev0}}
}}
Dieser Wiki-Artikel soll und kann die {{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=ESPEasy Modul-Dokumentation}}(aka FHEM Command Reference) nicht ersetzen, sondern ergänzt die Dokumentation nur um ein paar Informationen.

== Grundlegende ESP Easy Einstellungen ==

Diese Einstellungen sind in der Weboberfläche des ESP vorzunehmen und bewirken u.a., dass für jedes ESPEasy-Device ein FHEM Device angelegt wird. Das kann bspw. für einen ESP sinnvoll sein, der Relays über GPIOs schalten soll (ESPEasy Device-Type ''Switch Input'').

*Es muss ein einmaliger ESP Devicename vergeben werden (''Config'' -> ''Main Settings'' ->''Name'')
*Die verwendeten ESP Easy Devices sollten einen ESP-weit einmaligen Namen erhalten (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Name''). Ist dieser Name nicht eindeutig oder wird nicht vergeben, dann gibt es u.a. Probleme mit ESP Easy Rules [link].
*Jeder Wert, der gesendet werden soll, benötigt ebenfalls einen Namen, der in diesem ESP Device einmalig sein muss (''Device'' -> ''Edit'' -> ''Optional Settings'' -> ''Value Name'')
*Soll dieser Wert nun automatisch in einem Interval von x Sekunden (an FHEM) gesendet werden, dann muss noch das ''Delay'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Delay'') angegeben und die Option ''Send Data'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Send Data'') aktiviert werden. Die Option ''Send Boot State'' ist an dieser Stelle ebenfalls sinnvoll.

=== Attribut combineDevices ===

Wenn das oben genannte Verhalten (ein FHEM Device pro ESP Easy Device) nicht gewünscht ist, dann kann man mittels des Attributes ''combineDevices'' der {{Link2CmdRef|Anker=ESPEasy_bridge_define|Lang=en|Label=ESPEasy Bridge}} einstellen, ob die ESP Easy Devices eines einzelnen ESPs in ein FHEM Device zusammengeführt werden sollen.
Diese Funktionalität kann man global einschalten, indem man dem Attribut ''combineDevices'' den Wert ''1'' gibt.

Will man nur von bestimmten ESPs die Devices zusammen fassen, dann kann man eine komma-getrennte Liste der ESPs angeben. Die Liste kann aus ESP Namen, IP Adressen und/oder Netzwerkbereichen bestehen. Netzwerkbereiche können mit einer Netzmaske in dotted decimal (/255.255.255.0) oder in bitmask (/24) Schreibweise angegeben werden. Hostnamen und FQDNs werden nicht unterstützt.

Beispiele:
attr <esp> combineDevices ESP1,ESP2
attr <esp> combineDevices 10.0.0.148,10.0.0.149
attr <esp> combineDevices 192.168.124.0/24
attr <esp> combineDevices 192.168.124.0/255.255.255.0
attr <esp> combineDevices ESP1,ESP2,10.0.0.0/8,192.168.0.0/255.255.0.0

IPv6 Adressen/Bereiche werden zwar von FHEM, allerdings zur Zeit noch nicht von der öffentlichen ESP Easy Distribution unterstützt.

Beispiel:
attr <esp> combineDevices 2001:1a50:50a8::148,2001:abcd:efff::/48

== Presence Erkennung ==
Die "Presence Detection", also die Erkennung, ob ein ESP noch Daten sendet, wurde anhand des Alters der empfangenen (Sensor-)Werte realisiert. Vereinfacht gesagt: Werden keine Readings mehr innerhalb von x Sekunden empfangen (siehe Device-Attribut ''Interval''), wird das FHEM Device als "absent" gekennzeichnet. Das hat den Vorteil, dass auch ESP Easy Devices, die zwischen dem Senden von Daten in den so genannten Deep Sleep Modus gehen, erkannt werden können.

Das Attribut ''Interval'' gibt unter anderem vor, in welchem zeitlichen Abstand Werte vom ESP erwartet werden, damit der ESP als "present" (und nicht absent) markiert wird.

Wenn ein ESP Easy Device Werte alle 60 Sekunden sendet (Option ''Delay'' in der ESP Easy Device GUI) und das FHEM Device Interval auf 60 gesetzt ist, dann würde das Device-Reading "presence" auf "absent" wechseln, wenn innerhalb von 60-120 Sekunden keine Werte empfangen werden.

Also wäre zum Beispiel die ESP Easy Firmware so zu konfigurieren, dass mindestens ein Wert alle 60 Sekunden gesendet wird. Das Interval-Attribut des entsprechenden FHEM ESPEasy Device müsste ebenfalls auf 60 (default) gesetzt werden. Ein paar Sekunden Toleranz sind im ESPEasy Modul eingebaut.

Wenn man kein ESP Easy Device hat, das Daten an FHEM sendet, dann kann man zusätzlich einen der "System Info" Werte senden lassen und ''combineDevices'' für diesen ESP aktivieren. Es reicht nämlich, wenn ein Reading regelmäßig aktualisiert wird.

Wenn die Presence Erkennung nicht genutzt werden soll, dann muss das Attribut ''presenceCheck'' auf 0 gesetzt werden.

== Sicherheit ==

Wenn eine ESPEasy Bridge in FHEM eingerichtet wurde, dann werden Verbindungen nur von IP Adressen aus [https://tools.ietf.org/html/rfc1918 privaten Bereichen] zugelassen.

Wenn ESP Easy Geräte außerhalb dieser Bereiche Daten an FHEM senden (z.B. über das Internet), dann muss das in der ESPEasy Bridge konfiguriert werden, andernfalls wird die Verbindung abgewiesen.

Einerseits muss die IP Adresse bzw. der IP Bereich erlaubt (Attribute ''allowedIPs'', ''deniedIPs''), andererseits die Authentifizierung über "Basic Auth" in der ESPEasy Bridge eingerichtet werden.
Die Authentifizierung wird über das Attribut ''authentication'' eingeschaltet. Die Benutzerdaten für die Authentifizierung werden über die Set-Befehle ''user'' und ''pass'' der Bridge eingegeben
{{Hinweis|Hinweis: Username und Passwort werden unverschlüsselt in ./FHEM/FhemUtils/uniqueID gespeichert.}}

=== Attribut authentication ===
Beispiel:
set <espbridge> user MeinUserName
set <espbridge> pass sehrgeheim
attr <espbridge> authentication 1

=== Attribute allowedIPs / deniedIPs ===
Beispiel:
attr <espbridge> allowedIPs 192.0.2.0/24 # erlaubt ist 192.0.2.0 bis 192.0.2.255
attr <espbridge> deniedIPs 192.0.2.0/29 # ausgeschlossen werden aber die IPs von 192.0.2.0 bis 192.0.2.7

Das Attribut ''deniedIPs'' hat Vorrang vor ''allowedIPs''. Das bedeutet, dass verbotene IPs niemals eine Verbindung aufbauen können, auch wenn sie vorher erlaubt wurden.

Regular Expressions sind können ebenfalls verwendet werden:
attr <espbridge> allowedIPs 192.0.2.1([0-4][0-9]|50) # erlaubt IP von 192.168.30.100 bis 192.168.30.150

Alle Details dazu sind in der {{Link2CmdRef|Anker=ESPEasy_bridge_attr_allowedips|Lang=en|Label=Command Reference}} beschrieben.

== Erweiterte Beispiele==
Hier ein paar Beispiele für unterschiedlichste Anwendungsfälle

=== Schalter in FHEMWEB mit devStateIcons ===
Beispiel für GPIO 12:
attr <ESP> stateFormat {ReadingsVal($name,"presence","") eq "absent" ? "absent" : ReadingsVal($name,"GPIO12","")}
attr <ESP> devStateIcon on:ios-on-green:off off:ios-off:on absent:10px-kreis-rot:statusRequest
attr <ESP> eventMap /gpio 12 on:on/gpio 12 off:off/
attr <ESP> webCmd :

=== on-for-timer und off-for-timer ===
Beispiel für GPIO 15:
attr <ESP> /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/

=== (on|off)-for-timer und devStateIcons ===
Beispiel für GPIO 15:
attr <ESP> eventMap /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/gpio 15 on:on/gpio 15 off:off/

=== userSetCmds ===
Mithilfe des Attributes userSetCmds kann man:
*Einzelne ESP Easy Befehle nachrüsten
*Eigene oder nicht unterstützte Plugins integrieren
*Bereits integrierte Befehle verändern
*Befehle einzelner Plugins mappen: Statt 'set <dev> plugin_a on' kann man so 'set <dev> on' verwenden. Das wird z.B. benötigt, um FHEMs setExtentions oder auch um FHEMWEB Widgets nutzen zu können.

Die genrelle Syntax des Attributes ist ein Perl Hash, der die Eigenschaften des ESP Easy Befehls/Plugins beschreibt.
Folgende Eigenschaften (Keys) gibt es:
*args: Anzahl der benötigten Parameter. Default: 0
*url: Die aufzurufende URL. Default: /control?cmd=
*widget: Das FHEMWEB Widget, dass beim FHEMWEB Setter des Befehls verwendet werden soll. Default: keines
*usage: Diese Zeichenkette wird zum einen angezeigt, wenn ein falscher oder zu wenige Parameter beim Befehlsaufruf angeben wurden. Zum anderen haben folgende Zeichenketten eine besondere Bedeutung:
**<0|1|off|on>: Innerhalb des FHEM Befehl kann on/off statt 0/1 angegeben werden. An die ESP Easy Firmware wird 0/1 gesendet.
**<pin>: Bei dem Paramater handelt es sin um einen GPIO Port. Aliasnamen können verwendet werden. Siehe: get <dev> pinMap
**<text>: Dieser Paramter wird url encoded an die ESP Easy Firmware gesendet. Wird für die Ausgabe auf (O)led Displays benötigt.
*cmds: Diese Eigenschaft (key) muss ebenfalls ein Perl Hash sein. Dieser Key definiert die Unterbefehle des Plugins. Alle oben genannten Eigenschaften (Keys) können benutzt werden. Nur der Key 'url' kann nicht angegeben werden, da in diesem Fall die URL des Plugins verwendet wird.

Ein einzelner neuer Befehl 'myCmd1':
attr <dev> userSetCmds ( myCmd1 => {} )

Ein einzelner neuer Befehl 'myCmd1'. Der erste Paramater enthält einen GPIO Port, der durch Aliasnamen ersetzt werden kann. Der zweite Paramater kann als on/off geschrieben werden, gesendet wird aber 1/0:
attr <dev> userSetCmds ( myCmd1 => { usage => "<pin> <0|1|off|on>" } )

Zwei neue Befehle, mit allen default Werten:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => {} )

Zwei neue Befehle, der zweite Befehl verwendet eine abweichende URL:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => { url => "/?cmd=" } )

Beispiel für das fiktive Plugin 'LED' mit den Unterbefehlen 'rgb' und 'ct'. Die Unterbefehle 'rgb' und 'ct' können ohne Angabe des Pluginnamens 'LED' verwendet werden. Zusätzlich werden in der FHEMWEB-Ansicht die Slider Widgets hsv/ct verwendet:
<source lang="text">
attr <dev> userSetCmds (
LED => {
args => 2,
url => "/control?cmd=",
usage => "<rgb|ct> <rrggbb|colortemp>",
cmds => {
rgb => { args => 1, usage => "<rrggbb>", widget => "colorpicker,HSV" },
ct => { args => 1, usage => "<colortemp>", widget => "colorpicker,CT,2000,10,4000" }
}
}
)
</source>

=== setExtensions ===
Mithilfe der FHEM setExtentions kann man die Befehle on-for-timer, off-for-timer, on-till, off-till, blink, intervals, toggle, etc nutzen. Im Gegensatz zu den ESP Easy Firmware Befehlen 'pulse', 'longpulse' und 'longpulse_ms' laufen die Timer nicht innerhalb der ESP Easy Firmware, sondern in FHEM. Mit allen Vor- und Nachteilen.
Um die setExtensions nutzen zu können muss das Attribut 'useExtensions' auf 1 gesetzt sein. Weiterhin müssen die Befehle 'on' und 'off', für das entsprechende Device, verfügbar sein. Das kann man auf verschiedene Weisen realisieren:
==== setExtensions mit eventMap ====
In diesem Beispiel wird der Befehl 'set <dev> GPIO 15 on' mithilfe des globalen Attributs 'eventMap' auf den Befehl 'set <dev> on' gemappt. Gleiches gilt für 'off'.
<source lang="text">
attr <dev> useSetExtensions 1
attr <dev> eventMap /gpio 15 on:^on$/gpio 15 off:^off$/
</source>
==== setExtentions mit userSetCmds ====
In diesem Beispiel wird nicht das globale Attribut 'eventMap' benutzt, sondern das ESPEasy Attribut 'userSetCmds', um die 'on' und 'off' Befehle bereitzustellen.
<source lang="text">
attr <dev> useSetExtensions 1
attr <dev> userSetCmds (
myPlugin =>
{
args => 1,
usage => "<0|1|off|on>",
cmds => {
on => { widget => "noArg" },
off => { widget => "noArg" },
}
}
)
</source>

==Logging==
===ESPEasy Bridge===
<source lang="text">
2018.02.10 08:48:06.197 4: Connection accepted from eb_10.0.0.148_25654
2018.02.10 08:48:06.199 4: ESPEasy eb_10.0.0.148_25654: Peer address accepted
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received content: {"module":"ESPEasy","version":"1.02","data":{"ESP":{"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":{"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":{"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Basic authentication accepted
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Send http close '200 OK'
2018.02.10 08:48:06.202 4: ESPEasy eb_10.0.0.148_25654: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1
2018.02.10 08:48:06.202 5: eb: dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2
2018.02.10 08:48:06.209 4: ESPEasy eb_10.0.0.148_25654: Closing tcp session.
</source>

Im Detail bedeuten die Logeinträge:

;Connection accepted from eb_10.0.0.148_25654
:Eine TCP Verbindung wurde vom ESP (IP: 10.0.0.148, source port: 25654) zur Bridge "eb" aufgebaut.

;ESPEasy eb_10.0.0.148_25654
:Es wurde ein temporäres ESPEasy Bridge Devices angelegt, das Daten von der IP 10.0.0.148 und Quellport 25654 empfängt.

;Peer address accepted
:Die IP Adresse des ESP wurde akzeptiert und die empfangenen Daten werden nun verarbeitet. Wenn die IP Adresse nicht akzeptiert wird, dann wird '''Peer address rejected''' gelogged.

;<nowiki>Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}</nowiki>
:Diese ''received header'' Zeile enthält die Daten des Headers, die via HTTP vom ESP empfangen werden. Ein eventuell vorhandenes Passwort wird maskiert.

;<nowiki>Received content: {"module":"ESPEasy","version":"1.02","data":"ESP":"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}</nowiki>
:Diese ''received content'' Zeile enthält die Daten, die vom ESP via HTTP empfangenen werden. Mehr oder weniger Klartext im JSON Format.

;Basic authentication accepted
:In diesem Schritt wird geprüft ob eine Authentifizierung erforderlich und im besten Fall auch korrekt ist.
:Folgende Meldungen wären an dieser Stelle auch möglich:
:*No basic authentication required (auf beiden Seiten ist keine basic auth eingerichtet)
:*No basic authentication active but credentials received (auf FHEM Seite ist keine basic auth eingerichtet, der ESP sendet aber basic auth)
:*Basic authentication rejected (Username oder Passwort passen nicht zusammen)

;Send http close '200 OK'
:"Quittung" an den ESP senden. Daraufhin wird der ESP die Verbindung beenden.

;<nowiki>Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1</nowiki>
:Die Daten wurden vom ESP mit dem Namen BA_SEN1 und dem ESP Device DHT22 gesendet. Auf FHEM Seite werden die Daten dem Device mit dem Ident "BA_SEN1" zugewiesen. Dieses Ident wird vom FHEM Device ESPEasy_BA_SEN1 verwendet. Für diesen ESP ist das Attribut ''combineDevices'' wirksam. Wäre ''combineDevices'' nicht aktiv, dann würde das Ident "BA_SEN1_DHT22" lauten.

;<nowiki>dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2</nowiki>
:Die Daten werden nun von der Bridge an das logische ESPEasy Device weitergegeben.
:Im Details bedeuten die einzelnen Elemente dieser Zeichenkette:
:*'''BA_SEN1::''': Daten an das FHEM Device mit dem Ident BA_SEN1 schicken.
:*'''10.0.0.148::''': IP Adresse des ESPs
:*'''1::''': autocreate enabled? ja
:*'''0::''': autosave enabled? nein
:*'''1::''': wird nicht mehr benutzt
:*'''i||unit||4||0|||''': Der ESP hat die Unit Nummer 4
:*'''i||sleep||1||0|||''': Ist der ESP für den deep sleep mode konfiguriert? ja
:*'''i||build||137||0|||''': ESPEasy build version 137
:*'''i||version||9||0|||''': ESPEasy Release 9
:*'''r||temperature||21.5||2|||''': Readingname: temperature, Wert: 21.5, Sensortyp: 2
:*'''r||humidity||12.2||2''': Readingname: humidity, Wert 12.2, Sensortyp: 2
:Je nach ESPEasy Firmware Version können die Internals (Zeilen mit i am Anfang) auch
zusätzliche/andere Informationen aufweisen.

;Closing tcp session.
:Die tcp Verbindung wird geschlossen, das temporäre ESPEasy Bridge Device wird gelöscht.

===ESPEasy Device===
<source lang="text">
2018.02.10 10:08:41.235 5: ESPEasy ESPEasy_BA_SEN1: Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2
2018.02.10 10:08:41.236 4: ESPEasy ESPEasy_BA_SEN1: temperature: 21.2
2018.02.10 10:08:41.237 4: ESPEasy ESPEasy_BA_SEN1: humidity: 10.3
2018.02.10 10:08:41.237 5: ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:0 build:137 version:9
</source>
Im Detail:

;<nowiki>Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2</nowiki>
:Das ist wieder die, bereits oben beschriebene, ''dispatch'' Zeichenkette, die jetzt vom logischen Device empfangen wurde.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: temperature: 21.2</nowiki>
;<nowiki>ESPEasy ESPEasy_BA_SEN1: humidity: 10.3</nowiki>
:Die Readings ''temperature'' und ''humidity'' wurden aktualisiert.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:1 build:137 version:9</nowiki>
:Die Internals ''unit'', ''sleep'', ''build'' und ''version'' wurden aktualisiert.

===Zusätzliche Logeinträge===
Wird ein Device via Autocreate angelegt, gibt es zusätzliche Einträge im Logfile
<source lang="text">
2018.02.10 10:23:52.243 4: ESPEasy eb_10.0.0.148_3446: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:undef combinedDevice:1
2018.02.10 10:23:52.243 2: ESPEasy eb: Autocreate ESPEasy_BA_SEN1 ESPEasy 10.0.0.148 80 eb BA_SEN1
2018.02.10 10:23:52.244 4: ESPEasy ESPEasy_BA_SEN1: Opened for BA_SEN1 10.0.0.148:80 using bridge eb
2018.02.10 10:23:52.258 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 setState 3
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 Interval 300
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: Start internalTimer +304 => 2018-02-10 10:28:57
2018.02.10 10:23:52.266 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 presenceCheck 1
2018.02.10 10:23:52.269 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 readingSwitchText 1
2018.02.10 10:23:52.271 2: ESPEasy eb: Autosave is disabled: Do not forget to save changes.
</source>

==Weblinks==
*{{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=FHEM ESPEasy Modul-Dokumentation}}
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy ESP Easy Firmware Wiki]
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy_Command_Reference ESP Easy Command Reference]
*[https://www.letscontrolit.com/wiki/index.php/Tutorial_Rules ESP Easy Rules]

ESPEasy

2018-10-12T05:59:31Z

DDT: Attribut userSetCmds hinzugefügt

{{Baustelle}}
{{Infobox Modul
|ModPurpose=Steuerung eines Espressif ESP8266 WLAN-SoC
|ModType=d
|ModCmdRef=
|ModForumArea=Bastelecke/ESP8266
|ModFTopic=55728
|ModTechName=34_ESPEasy.pm
|ModOwner={{Link2FU|7465|dev0}}
}}
Dieser Wiki-Artikel soll und kann die {{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=ESPEasy Modul-Dokumentation}}(aka FHEM Command Reference) nicht ersetzen, sondern ergänzt die Dokumentation nur um ein paar Informationen.

== Grundlegende ESP Easy Einstellungen ==

Diese Einstellungen sind in der Weboberfläche des ESP vorzunehmen und bewirken u.a., dass für jedes ESPEasy-Device ein FHEM Device angelegt wird. Das kann bspw. für einen ESP sinnvoll sein, der Relays über GPIOs schalten soll (ESPEasy Device-Type ''Switch Input'').

*Es muss ein einmaliger ESP Devicename vergeben werden (''Config'' -> ''Main Settings'' ->''Name'')
*Die verwendeten ESP Easy Devices sollten einen ESP-weit einmaligen Namen erhalten (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Name''). Ist dieser Name nicht eindeutig oder wird nicht vergeben, dann gibt es u.a. Probleme mit ESP Easy Rules [link].
*Jeder Wert, der gesendet werden soll, benötigt ebenfalls einen Namen, der in diesem ESP Device einmalig sein muss (''Device'' -> ''Edit'' -> ''Optional Settings'' -> ''Value Name'')
*Soll dieser Wert nun automatisch in einem Interval von x Sekunden (an FHEM) gesendet werden, dann muss noch das ''Delay'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Delay'') angegeben und die Option ''Send Data'' (''Device'' -> ''Edit'' -> ''Task Settings'' -> ''Send Data'') aktiviert werden. Die Option ''Send Boot State'' ist an dieser Stelle ebenfalls sinnvoll.

=== Attribut combineDevices ===

Wenn das oben genannte Verhalten (ein FHEM Device pro ESP Easy Device) nicht gewünscht ist, dann kann man mittels des Attributes ''combineDevices'' der {{Link2CmdRef|Anker=ESPEasy_bridge_define|Lang=en|Label=ESPEasy Bridge}} einstellen, ob die ESP Easy Devices eines einzelnen ESPs in ein FHEM Device zusammengeführt werden sollen.
Diese Funktionalität kann man global einschalten, indem man dem Attribut ''combineDevices'' den Wert ''1'' gibt.

Will man nur von bestimmten ESPs die Devices zusammen fassen, dann kann man eine komma-getrennte Liste der ESPs angeben. Die Liste kann aus ESP Namen, IP Adressen und/oder Netzwerkbereichen bestehen. Netzwerkbereiche können mit einer Netzmaske in dotted decimal (/255.255.255.0) oder in bitmask (/24) Schreibweise angegeben werden. Hostnamen und FQDNs werden nicht unterstützt.

Beispiele:
attr <esp> combineDevices ESP1,ESP2
attr <esp> combineDevices 10.0.0.148,10.0.0.149
attr <esp> combineDevices 192.168.124.0/24
attr <esp> combineDevices 192.168.124.0/255.255.255.0
attr <esp> combineDevices ESP1,ESP2,10.0.0.0/8,192.168.0.0/255.255.0.0

IPv6 Adressen/Bereiche werden zwar von FHEM, allerdings zur Zeit noch nicht von der öffentlichen ESP Easy Distribution unterstützt.

Beispiel:
attr <esp> combineDevices 2001:1a50:50a8::148,2001:abcd:efff::/48

== Presence Erkennung ==
Die "Presence Detection", also die Erkennung, ob ein ESP noch Daten sendet, wurde anhand des Alters der empfangenen (Sensor-)Werte realisiert. Vereinfacht gesagt: Werden keine Readings mehr innerhalb von x Sekunden empfangen (siehe Device-Attribut ''Interval''), wird das FHEM Device als "absent" gekennzeichnet. Das hat den Vorteil, dass auch ESP Easy Devices, die zwischen dem Senden von Daten in den so genannten Deep Sleep Modus gehen, erkannt werden können.

Das Attribut ''Interval'' gibt unter anderem vor, in welchem zeitlichen Abstand Werte vom ESP erwartet werden, damit der ESP als "present" (und nicht absent) markiert wird.

Wenn ein ESP Easy Device Werte alle 60 Sekunden sendet (Option ''Delay'' in der ESP Easy Device GUI) und das FHEM Device Interval auf 60 gesetzt ist, dann würde das Device-Reading "presence" auf "absent" wechseln, wenn innerhalb von 60-120 Sekunden keine Werte empfangen werden.

Also wäre zum Beispiel die ESP Easy Firmware so zu konfigurieren, dass mindestens ein Wert alle 60 Sekunden gesendet wird. Das Interval-Attribut des entsprechenden FHEM ESPEasy Device müsste ebenfalls auf 60 (default) gesetzt werden. Ein paar Sekunden Toleranz sind im ESPEasy Modul eingebaut.

Wenn man kein ESP Easy Device hat, das Daten an FHEM sendet, dann kann man zusätzlich einen der "System Info" Werte senden lassen und ''combineDevices'' für diesen ESP aktivieren. Es reicht nämlich, wenn ein Reading regelmäßig aktualisiert wird.

Wenn die Presence Erkennung nicht genutzt werden soll, dann muss das Attribut ''presenceCheck'' auf 0 gesetzt werden.

== Sicherheit ==

Wenn eine ESPEasy Bridge in FHEM eingerichtet wurde, dann werden Verbindungen nur von IP Adressen aus [https://tools.ietf.org/html/rfc1918 privaten Bereichen] zugelassen.

Wenn ESP Easy Geräte außerhalb dieser Bereiche Daten an FHEM senden (z.B. über das Internet), dann muss das in der ESPEasy Bridge konfiguriert werden, andernfalls wird die Verbindung abgewiesen.

Einerseits muss die IP Adresse bzw. der IP Bereich erlaubt (Attribute ''allowedIPs'', ''deniedIPs''), andererseits die Authentifizierung über "Basic Auth" in der ESPEasy Bridge eingerichtet werden.
Die Authentifizierung wird über das Attribut ''authentication'' eingeschaltet. Die Benutzerdaten für die Authentifizierung werden über die Set-Befehle ''user'' und ''pass'' der Bridge eingegeben
{{Hinweis|Hinweis: Username und Passwort werden unverschlüsselt in ./FHEM/FhemUtils/uniqueID gespeichert.}}

=== Attribut authentication ===
Beispiel:
set <espbridge> user MeinUserName
set <espbridge> pass sehrgeheim
attr <espbridge> authentication 1

=== Attribute allowedIPs / deniedIPs ===
Beispiel:
attr <espbridge> allowedIPs 192.0.2.0/24 # erlaubt ist 192.0.2.0 bis 192.0.2.255
attr <espbridge> deniedIPs 192.0.2.0/29 # ausgeschlossen werden aber die IPs von 192.0.2.0 bis 192.0.2.7

Das Attribut ''deniedIPs'' hat Vorrang vor ''allowedIPs''. Das bedeutet, dass verbotene IPs niemals eine Verbindung aufbauen können, auch wenn sie vorher erlaubt wurden.

Regular Expressions sind können ebenfalls verwendet werden:
attr <espbridge> allowedIPs 192.0.2.1([0-4][0-9]|50) # erlaubt IP von 192.168.30.100 bis 192.168.30.150

Alle Details dazu sind in der {{Link2CmdRef|Anker=ESPEasy_bridge_attr_allowedips|Lang=en|Label=Command Reference}} beschrieben.

== Erweiterte Beispiele==
Hier ein paar Beispiele für unterschiedlichste Anwendungsfälle

=== Schalter in FHEMWEB mit devStateIcons ===
Beispiel für GPIO 12:
attr <ESP> stateFormat {ReadingsVal($name,"presence","") eq "absent" ? "absent" : ReadingsVal($name,"GPIO12","")}
attr <ESP> devStateIcon on:ios-on-green:off off:ios-off:on absent:10px-kreis-rot:statusRequest
attr <ESP> eventMap /gpio 12 on:on/gpio 12 off:off/
attr <ESP> webCmd :

=== on-for-timer und off-for-timer ===
Beispiel für GPIO 15:
attr <ESP> /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/

=== (on|off)-for-timer und devStateIcons ===
Beispiel für GPIO 15:
attr <ESP> eventMap /longpulse 15 on:on-for-time:slider,0,1,60/longpulse 15 off:off-for-time:slider,0,1,60/gpio 15 on:on/gpio 15 off:off/

=== userSetCmds ===
Mithilfe des Attributes userSetCmds kann man:
*Einzelne ESP Easy Befehle nachrüsten
*Eigene oder nicht unterstützte Plugins integrieren
*Bereits integrierte Befehle verändern
*Befehle einzelner Plugins mappen: Statt 'set <dev> plugin_a on' kann man so 'set <dev> on' verwenden. Das wird z.B. benötigt, um FHEMs setExtentions oder auch um FHEMWEB Widgets nutzen zu können.

Die genrelle Syntax des Attributes ist ein Perl Hash, der die Eigenschaften des ESP Easy Befehls/Plugins beschreibt.
Folgende Eigenschaften (Keys) gibt es:
*args: Anzahl der benötigten Parameter. Default: 0
*url: Die aufzurufende URL. Default: /control?cmd=
*widget: Das FHEMWEB Widget, dass beim FHEMWEB Setter des Befehls verwendet werden soll. Default: keines
*usage: Diese Zeichenkette wird zum einen angezeigt, wenn ein falscher oder zu wenige Parameter beim Befehlsaufruf angeben wurden. Zum anderen haben folgende Zeichenketten eine besondere Bedeutung:
**<0|1|off|on>: Innerhalb des FHEM Befehl kann on/off statt 0/1 angegeben werden. An die ESP Easy Firmware wird 0/1 gesendet.
**<pin>: Bei dem Paramater handelt es sin um einen GPIO Port. Aliasnamen können verwendet werden. Siehe: get <dev> pinMap
**<text>: Dieser Paramter wird url encoded an die ESP Easy Firmware gesendet. Wird für die Ausgabe auf (O)led Displays benötigt.
*cmds: Diese Eigenschaft (key) muss ebenfalls ein Perl Hash sein. Dieser Key definiert die Unterbefehle des Plugins. Alle oben genannten Eigenschaften (Keys) können benutzt werden. Nur der Key 'url' kann nicht angegeben werden, da in diesem Fall die URL des Plugins verwendet wird.

Ein einzelner neuer Befehl 'myCmd1':
attr <dev> userSetCmds ( myCmd1 => {} )

Ein einzelner neuer Befehl 'myCmd1'. Der erste Paramater enthält einen GPIO Port, der durch Aliasnamen ersetzt werden kann. Der zweite Paramater kann als on/off geschrieben werden, gesendet wird aber 1/0:
attr <dev> userSetCmds ( myCmd1 => { usage => "<pin> <0|1|off|on>" } )

Zwei neue Befehle, mit allen default Werten:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => {} )

Zwei neue Befehle, der zweite Befehl verwendet eine abweichende URL:
attr <dev> userSetCmds ( myCmd1 => {}, myCmd2 => { url => "/?cmd=" } )

Beispiel für das fiktive Plugin 'LED' mit den Unterbefehlen 'rgb' und 'ct'. Die Unterbefehle 'rgb' und 'ct' können ohne Angabe des Pluginnamens 'LED' verwendet werden. Zusätzlich werden in der FHEMWEB-Ansicht die Slider Widgets hsv/ct verwendet:
<source lang="text">
attr <dev> userSetCmds (
LED => {
args => 2,
url => "/control?cmd=",
usage => "<rgb|ct> <rrggbb|colortemp>",
cmds => {
rgb => { args => 1, usage => "<rrggbb>", widget => "colorpicker,HSV" },
ct => { args => 1, usage => "<colortemp>", widget => "colorpicker,CT,2000,10,4000" }
}
}
)
</source>

==Logging==
===ESPEasy Bridge===
<source lang="text">
2018.02.10 08:48:06.197 4: Connection accepted from eb_10.0.0.148_25654
2018.02.10 08:48:06.199 4: ESPEasy eb_10.0.0.148_25654: Peer address accepted
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}
2018.02.10 08:48:06.199 5: ESPEasy eb_10.0.0.148_25654: Received content: {"module":"ESPEasy","version":"1.02","data":{"ESP":{"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":{"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":{"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Basic authentication accepted
2018.02.10 08:48:06.200 4: ESPEasy eb_10.0.0.148_25654: Send http close '200 OK'
2018.02.10 08:48:06.202 4: ESPEasy eb_10.0.0.148_25654: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1
2018.02.10 08:48:06.202 5: eb: dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2
2018.02.10 08:48:06.209 4: ESPEasy eb_10.0.0.148_25654: Closing tcp session.
</source>

Im Detail bedeuten die Logeinträge:

;Connection accepted from eb_10.0.0.148_25654
:Eine TCP Verbindung wurde vom ESP (IP: 10.0.0.148, source port: 25654) zur Bridge "eb" aufgebaut.

;ESPEasy eb_10.0.0.148_25654
:Es wurde ein temporäres ESPEasy Bridge Devices angelegt, das Daten von der IP 10.0.0.148 und Quellport 25654 empfängt.

;Peer address accepted
:Die IP Adresse des ESP wurde akzeptiert und die empfangenen Daten werden nun verarbeitet. Wenn die IP Adresse nicht akzeptiert wird, dann wird '''Peer address rejected''' gelogged.

;<nowiki>Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}</nowiki>
:Diese ''received header'' Zeile enthält die Daten des Headers, die via HTTP vom ESP empfangen werden. Ein eventuell vorhandenes Passwort wird maskiert.

;<nowiki>Received content: {"module":"ESPEasy","version":"1.02","data":"ESP":"name":"BA_SEN1","unit":4,"version":9,"build":137,"sleep":0,"ip":"10.0.0.148"},"SENSOR":"0":{"deviceName":"DHT22","valueName":"temperature","type":2,"value":"21.5"},"1":"deviceName":"DHT22","valueName":"humidity","type":2,"value":"12.2"}}}}</nowiki>
:Diese ''received content'' Zeile enthält die Daten, die vom ESP via HTTP empfangenen werden. Mehr oder weniger Klartext im JSON Format.

;Basic authentication accepted
:In diesem Schritt wird geprüft ob eine Authentifizierung erforderlich und im besten Fall auch korrekt ist.
:Folgende Meldungen wären an dieser Stelle auch möglich:
:*No basic authentication required (auf beiden Seiten ist keine basic auth eingerichtet)
:*No basic authentication active but credentials received (auf FHEM Seite ist keine basic auth eingerichtet, der ESP sendet aber basic auth)
:*Basic authentication rejected (Username oder Passwort passen nicht zusammen)

;Send http close '200 OK'
:"Quittung" an den ESP senden. Daraufhin wird der ESP die Verbindung beenden.

;<nowiki>Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1</nowiki>
:Die Daten wurden vom ESP mit dem Namen BA_SEN1 und dem ESP Device DHT22 gesendet. Auf FHEM Seite werden die Daten dem Device mit dem Ident "BA_SEN1" zugewiesen. Dieses Ident wird vom FHEM Device ESPEasy_BA_SEN1 verwendet. Für diesen ESP ist das Attribut ''combineDevices'' wirksam. Wäre ''combineDevices'' nicht aktiv, dann würde das Ident "BA_SEN1_DHT22" lauten.

;<nowiki>dispatch BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.5||2|||r||humidity||12.2||2</nowiki>
:Die Daten werden nun von der Bridge an das logische ESPEasy Device weitergegeben.
:Im Details bedeuten die einzelnen Elemente dieser Zeichenkette:
:*'''BA_SEN1::''': Daten an das FHEM Device mit dem Ident BA_SEN1 schicken.
:*'''10.0.0.148::''': IP Adresse des ESPs
:*'''1::''': autocreate enabled? ja
:*'''0::''': autosave enabled? nein
:*'''1::''': wird nicht mehr benutzt
:*'''i||unit||4||0|||''': Der ESP hat die Unit Nummer 4
:*'''i||sleep||1||0|||''': Ist der ESP für den deep sleep mode konfiguriert? ja
:*'''i||build||137||0|||''': ESPEasy build version 137
:*'''i||version||9||0|||''': ESPEasy Release 9
:*'''r||temperature||21.5||2|||''': Readingname: temperature, Wert: 21.5, Sensortyp: 2
:*'''r||humidity||12.2||2''': Readingname: humidity, Wert 12.2, Sensortyp: 2
:Je nach ESPEasy Firmware Version können die Internals (Zeilen mit i am Anfang) auch
zusätzliche/andere Informationen aufweisen.

;Closing tcp session.
:Die tcp Verbindung wird geschlossen, das temporäre ESPEasy Bridge Device wird gelöscht.

===ESPEasy Device===
<source lang="text">
2018.02.10 10:08:41.235 5: ESPEasy ESPEasy_BA_SEN1: Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2
2018.02.10 10:08:41.236 4: ESPEasy ESPEasy_BA_SEN1: temperature: 21.2
2018.02.10 10:08:41.237 4: ESPEasy ESPEasy_BA_SEN1: humidity: 10.3
2018.02.10 10:08:41.237 5: ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:0 build:137 version:9
</source>
Im Detail:

;<nowiki>Received: BA_SEN1::10.0.0.148::1::0::1::i||unit||4||0|||i||sleep||0||0|||i||build||137||0|||i||version||9||0|||r||temperature||21.2||2|||r||humidity||10.3||2</nowiki>
:Das ist wieder die, bereits oben beschriebene, ''dispatch'' Zeichenkette, die jetzt vom logischen Device empfangen wurde.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: temperature: 21.2</nowiki>
;<nowiki>ESPEasy ESPEasy_BA_SEN1: humidity: 10.3</nowiki>
:Die Readings ''temperature'' und ''humidity'' wurden aktualisiert.

;<nowiki>ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:1 build:137 version:9</nowiki>
:Die Internals ''unit'', ''sleep'', ''build'' und ''version'' wurden aktualisiert.

===Zusätzliche Logeinträge===
Wird ein Device via Autocreate angelegt, gibt es zusätzliche Einträge im Logfile
<source lang="text">
2018.02.10 10:23:52.243 4: ESPEasy eb_10.0.0.148_3446: Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:undef combinedDevice:1
2018.02.10 10:23:52.243 2: ESPEasy eb: Autocreate ESPEasy_BA_SEN1 ESPEasy 10.0.0.148 80 eb BA_SEN1
2018.02.10 10:23:52.244 4: ESPEasy ESPEasy_BA_SEN1: Opened for BA_SEN1 10.0.0.148:80 using bridge eb
2018.02.10 10:23:52.258 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 setState 3
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 Interval 300
2018.02.10 10:23:52.262 5: ESPEasy ESPEasy_BA_SEN1: Start internalTimer +304 => 2018-02-10 10:28:57
2018.02.10 10:23:52.266 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 presenceCheck 1
2018.02.10 10:23:52.269 5: ESPEasy ESPEasy_BA_SEN1: received event: ATTR ESPEasy_BA_SEN1 readingSwitchText 1
2018.02.10 10:23:52.271 2: ESPEasy eb: Autosave is disabled: Do not forget to save changes.
</source>

==Weblinks==
*{{Link2CmdRef|Anker=ESPEasy|Lang=en|Label=FHEM ESPEasy Modul-Dokumentation}}
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy ESP Easy Firmware Wiki]
*[https://www.letscontrolit.com/wiki/index.php/ESPEasy_Command_Reference ESP Easy Command Reference]
*[https://www.letscontrolit.com/wiki/index.php/Tutorial_Rules ESP Easy Rules]

SmartVISU Installation

2017-05-06T12:05:57Z

DDT: moved / bring forward: "Config.ini kopieren"

{{SEITENTITEL:smartVISU Installation}}

Dieser Artikel beschreibt die Installation des Web-Frontends [[smartVISU]] und berücksichtigt mehrerer Alternativen für unterschiedliche Web-Server. Zum Betrieb von smartVISU mit FHEM ist die Installation und Konfiguration von [[fronthem]] erforderlich.

Alle Artikel zur Thematik fronthem/smartVISU sind [[:Kategorie:fronthem/smartVISU|hier]] kategorisiert.

----

__TOC__

Für die Installation ist es immer sinnvoll, von einem auf aktuellem Stand befindlichen System zu starten.

Für das Betriebssystem (Linuxderivat)
sudo apt-get update

sudo apt-get upgrade

Für FHEM
<code>update</code> in der Eingabezeile

Die Installation lässt sich in 4 Bereiche unterteilen.

== Webserver installieren ==

Welcher Webserver zum Einsatz kommt, ist unerheblich. Im Folgenden sind Beispiele für lighttpd, nginx und Apache2 zu finden. Es wird nur '''eine''' Installation benötigt.

=== lighttpd ===
Dieses Beispiel basiert auf diesem {{Link2Forum|Topic= 27291|Message=208880|LinkText=Forumsbeitrag}}.

Webserver installieren:
sudo apt-get install lighttpd

PHP installieren:
sudo apt-get install php5-common php5-cgi php5

PHP konfigurieren:
sudo lighty-enable-mod fastcgi-php

Webserver-Dienst einmal neu starten, damit die Einstellungen wirksam werden:
sudo service lighttpd force-reload

Welchseln in des Root-Verzeichnis des Webservers (bei Bedarf, wenn sich das Root-Verzeichnis einer Distribution woanders ist, muss dieser Pfad entsprechend angepasst werden):
cd /var/www

Setzen des Besitzers und der Gruppe für das Root-Verzeichnis (TODO: Ist dieser Schritt wirklich notwendig?):
sudo chown www-data:www-data /var/www

Setzen der Berechtigungen des Root-Verzeichnis (TODO: Ist dieser Schritt wirklich notwendig?):
sudo chmod 775 /var/www

=== nginx ===
==== mit PHP5 ====

Dieses Beispiel basiert auf diesem {{Link2Forum|Topic=30909|Message=273180|LinkText=Forumsbeitrag}}.

Für die Installation des Webservers und PHP5 werden folgende Pakete benötigt:
sudo apt-get install nginx php5-fpm

Die Konfiguration für PHP muss in der entsprechenden Konfigurationsdatei vorgenommen werden:
sudo nano /etc/nginx/sites-enabled/default

Folgende Konfiguration sollte direkt funktionieren:
<pre>
server {
listen 80;
root /var/www;
index index.html index.php;
server_name localhost;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/var/run/php5-fpm.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
</pre>

==== mit PHP7 ====
Ubuntu 16.04 läuft standardmäßig mit PHP7. Der Betrieb ist noch nicht zu 100% getestet und daher ohne Garantie.

Für die Installation des Webservers und PHP werden folgende Pakete benötigt:
sudo apt-get install nginx php7.0-fpm

Die Konfiguration für PHP muss in der entsprechenden Konfigurationsdatei vorgenommen werden:
sudo nano /etc/nginx/sites-enabled/default

Folgende Konfiguration sollte direkt funktionieren:
<pre>
server {
listen 80 default_server;
listen [::]:80 default_server;
root /var/www/html;
index index.php index.html index.htm index.nginx-debian.html;

server_name _;

location / {
try_files $uri $uri/ =404;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/run/php/php7.0-fpm.sock;
fastcgi_index index.php;
include fastcgi.conf;
fastcgi_read_timeout 600;
}
location ~* \.(js|css|png|jpg|jpeg|gif|ico|eot|otf|ttf|woff)$ {
access_log off; log_not_found off; expires 30d;
}
location = /robots.txt { access_log off; log_not_found off; }
location ~ /\. { deny all; access_log off; log_not_found off; }
}
</pre>

=== Apache2 ===

Dieses Beispiel basiert auf diesem [http://www.meintechblog.de/2015/06/smartvisu-mit-fhem-die-perfekte-visualisierung-teil-1-basics/ Blogeintrag].

Für die Installation des Webservers und PHP5 werden folgende Pakete benötigt:
sudo apt-get install apache2 php5 libapache2-mod-php5

Für das git /cleaninstall: da liegt die erweiterte smartVISU, mit Mandanten und reparierten widgets (wo nötig) - ansonsten aber unverfälscht und nicht mit widgets erweitert.

== smartVISU Installation ==

Für das Klonen (Herunterladen) wird folgendes Paket benötigt:
sudo apt-get install git

;Verfügbare Versionen (Stand Juli 2016):
Bis zur V2.7 gibt es ein offizielles Release, auf dem sowohl die Dokumentation auf der Seite [www.smartVISU.de] basiert, als auch das nachfolgend beschriebene smartvisu-cleaninstall.

Die nicht offizielle V2.8 kann aus den Entwicklungszweig von smartVISU heruntergeladen werden, muss aber im Anschluss um die Erweiterungen für den Betrieb mit FHEM ergänzt werden. Ob es ein offizielles Release V2.8 geben wird, ist derzeit unbekannt. Unabhängig davon wird an einem Fork in Zusammenhang für den Betrieb mit FHEM gearbeitet.

Zwar sollten alle Widgets, die auf V2.7 lauffähig sind, auch mit V2.8 kompatibel sein, dieses ist derzeit aber nicht getestet und kann nicht garantiert werden. Die Widgets müssen bei Bedarf entsprechend angepasst werden. Andererseits gibt es bereits Widgets, die V2.8 voraussetzen. Bei manchen Widgets sind die Voraussetzungen ist der Dokumentation beschrieben.

Die Unterschiede zwischen V2.7 und V2.8 sind in diesem {{Link2Forum|Topic=54506|Message=469401|LinkText=Beitrag}} zusammengefasst.

Derzeit kann aber bereits empfohlen werden, bei einer Neuinstallation gleich V2.8 zu installieren {{Link2Forum|Topic=53881|Message=471075|LinkText=(Forum)}}.

=== smartVISU-cleaninstall, V2.7 ===
==== Herunterladen ====
Für die Installation gibt es ein fertig zusammengestelltes Paket aus dem git-Repo von Jörg Herrmanns ([https://github.com/herrmannj/smartvisu-cleaninstall]).

Hierbei handelt es sich um das Original smartVISU inkl. einigen Anpassungen (fhem-Treiber, Widget-Korrekturen, ...).

Einrichten eines Installationsordners im home-Verzeichnis:
mkdir ~/install

Wechseln in das Verzeichnis:
cd ~/install

Klonen der Pakets:
git clone https://github.com/herrmannj/smartvisu-cleaninstall.git
Dabei wird der Unterordner ./smartvisu-cleaninstall angelegt, in den die Dateien heruntergeladen werden.

==== Kopieren in das Webserver Root-Verzeichnis ====
Damit der Webserver die Seiten von smartVISU zur Verfügung stellt, müssen diese an die richtige Stelle in Abhängigkeit des verwendeten Webservers und Konfiguration kopiert werden. Ggf. muss die Konfiguration des Webservers entsprechend angepasst werden.

Das neu erstellte Verzeichnis in das Root-Verzeichnis des Webservers kopieren. Dass, wie in diesem Fall angegeben, das Verzeichnis /var/www/ das richtige Verzeichnis ist, kann z.B. dadurch bestätigt werden, dass dort bereits die Default-Seite des Webservers nach der Ersteinrichtung zu finden ist. Bei Bedarf ist das Verzeichnis anzupassen.
sudo cp -rp smartvisu-cleaninstall /var/www/smartVISU

Selbstverständlich lässt dich auch ein anderes Installationsverzeichnis wählen. Die folgenden Schritte müssen dann entsprechend angepasst werden.

==== Config.ini kopieren ====
Hierbei handelt es sich um die Hauptdatei mit der das Verhalten von smartVISU gesteuert wird.

Die Datei "config.ini.default" muss zu "config.ini" umbenennen oder besser kopiert werden:
sudo cp /var/www/smartVISU/config.ini.default /var/www/smartVISU/config.ini

==== Berechtigungen setzen ====
Später wird zumindest die Konfiguration von dem, was auf dem Endgerät angezeigt werden soll, vom Endgerät aus konfiguriert. Damit dieses auch funktioniert, müssen die Berechtigungen der Seiten entsprechend angepasst werden.

Wechseln in das Verzeichnis:
cd /var/www

Setzen des Besitzers und der Gruppe für das Root-Verzeichnis von smartVISU
chown -R www-data:www-data smartVISU

Setzen der Berechtigungen für das Root-Verzeichnis "smartVISU" und alle Unterordner
chmod -R 775 smartVISU

==== ggf. Gruppenmitgliedschaft anpassen ====
Dieser Schritt ist optional und dann hilfreich, wenn man mit einem normalen user z.B. über fileZilla die Dateien austauschen möchte. Da der Schritt zulasten der Sicherheit geht, sollte man ihn nach Abschluss der Konfiguration ggf. wieder rückgängig machen.

In diesem Beispiel wird der user "pi" zur Gruppe <code>www-data</code> hinzugefügt. Verwendet man einen anderen user, muss dieses selbstverständig angepasst werden.
sudo usermod -a -G www-data pi

Rückgängig machen kann man die Gruppenzugehörigkeit über
sudo deluser pi www-data

==== Installation überprüfen ====

Beim Aufruf der Seite <code>http://<IP-Adresse>/smartVISU</code> sollte folgende Seite angezeigt werden: {{Randnotiz|RNTyp=y|RNText=
Ggf. in der php.ini (error_reporting) die Ausgabe von Warnings abschalten, wenn so was kommt wie "Notice: Undefined index..."
}}

Diese Seite wird ggf. nur einmal direkt nach der Ersteinrichtung angezeigt und ist im Folgenden nicht mehr notwendig.

[[Datei:Installation_SmartVISU.png]]

=== nicht offizielle Version, V2.8 ===

Die Beschreibung für die Installation der nicht offiziellen Version 2.8 von smartVISU basiert auf diesem [https://github.com/ddtlabs/build-smartvisu-cleaninstall Git-Eintrag] von [user=dev0].

Da man das Softwarepaket für smartVISU direkt aus dem Entwicklungszweig herunterläd, müssen die notwendigen Erweiterungen für den Betrieb mit FHEM nachträglich manuell eingefügt werden. Dabei ist der "Treiber" am wichtigsten.

Wie leicht zu erkennen, ist im folgenden Beispiel das Root-Verzeichnis des Webservers <code>/var/www/html</code> und das Verzeichnis, in das smartVISU installiert wird "sv".
Die smartVISU-Seite wird am Ende der Installation entsprechend mit <code>http://<IP-Adresse>/sv</code> aufgerufen.

Anpassen der Gruppenmitgliedschaften kann nach dem oben beschriebenen Muster durchgeführt werden.

==== Herunterladen ====

Die Dateien werden direkt aus dem Entwicklungszweig heruntergeladen.
git clone https://github.com/Martin-Gleiss/smartvisu.git

==== Kopieren in das Webserver Root-Verzeichnis ====
sudo cp -rp smartvisu /var/www/html/sv

==== Herunterladen der Erweiterungen für FHEM ====
git clone https://github.com/herrmannj/smartvisu-cleaninstall.git

==== Kopieren der Erweiterungen ====
sudo cp ./smartvisu-cleaninstall/readme.txt /var/www/html/sv/
sudo cp ./smartvisu-cleaninstall/lib/functions_config.php /var/www/html/sv/lib/
sudo cp ./smartvisu-cleaninstall/lib/includes.php /var/www/html/sv/lib/
sudo cp ./smartvisu-cleaninstall/config.ini.default /var/www/html/sv/
sudo cp ./smartvisu-cleaninstall/pages/base/configure.php /var/www/html/sv/pages/base/
sudo cp ./smartvisu-cleaninstall/driver/io_fhem.js /var/www/html/sv/driver/
sudo cp ./smartvisu-cleaninstall/driver/io_fhem.min.js /var/www/html/sv/driver/

==== Config.ini kopieren ====
sudo cp /var/www/html/sv/config.ini.default /var/www/html/sv/config.ini

==== Setzen der Berechtigungen (Besitzer und Gruppe) ====
cd /var/www/html
sudo chown -R www-data:www-data sv

== Troubleshooting ==

=== SSL ===

Wird derzeit nicht unterstützt {{Link2Forum|Topic=43226|Message=352115|LinkText=(Forum)}}.

=== Performanceproblem ===

Während der Entwicklung gab es mehrere Evolutionen, was die Verbindung über den Treiber angeht. Trotzdem hat auch die Platform, auf der smartVISU läuft einen gehörigen Anteil an der Reaktivität der Oberfläche. Darüber hinaus hat selbstredend die Komplexität einer Seite Einfluss auf die Geschwindigkeit.
Mit einem Webserver auf dem RPi2 scheint es noch potential nach oben zu geben, setzte man eine performantere Platform ein {{Link2Forum|Topic= 48243|Message=402427|LinkText=(Forum)}}.

=== Config-Seite anstatt der individuellen Seite ===

Es wurde vergessen, die Datei config.ini.default nach config.ini zu kopieren {{Link2Forum|Topic= 46501|Message=382426|LinkText=(Forum)}}.

=== Zugriffsprobleme mit Apache ===
Anscheinend gab es vereinzelt Zugriffsprobleme auf das smartVISU-Vereichnis, die sich aber mit dieser Erweiterung der Apache-Konfiguration beheben lies {{Link2Forum|Topic=30909|Message=239882|LinkText=(Forum)}}:

<pre>
<Directory "/var/www/smartvisu">
Options +Indexes FollowSymLinks +ExecCGI
AllowOverride AuthConfig FileInfo
Order allow,deny
Allow from all
</Directory>
</pre>

=== 404 not found ===

Wird noch nicht einmal die Seite gefunden (404), sind bereits die statischen Seiteninhalte der Webseite nicht richtig konfiguriert. Es muss sichergestellt werden, dass eine Datei im Verzeichnis von smartVISU von einem Endgerät angezeigt werden kann {{Link2Forum|Topic= 46501|Message=49524|LinkText=(Forum)}}.

=== *.js dateien ===

Sollte jemand Änderungen an den *.js Dateien bearbeiten muss man daran denken, dass in der config.ini ganz unten vereinbart wird welche Version der Datei benutzt wird {{Link2Forum|Topic=30909|Message=252375|LinkText=(Forum)}}.

=== verschiedene Devices, verschiedene Anzeigen ===

Möchte man sicherstellen, dass auf allen Endgeräten die gleiche page konfiguriert ist, verschiebt man den entsprechenden Teil in der config.ini in den <nowiki>[default]</nowiki>-Bereich.

An dieser Stelle sei eindringlich empfohlen, diese Änderung nur bei nicht laufendem Websocket durchzuführen und in jedem Falle ein Backup der Datei vorzuhalten. Bei Syntaxfehlern wird diese Datei neu erzeugt und überschreibt ohne Nachfrage die Vorversion {{Link2Forum|Topic=46541|Message=383006|LinkText=(Forum)}} {{Link2Forum|Topic=36420|Message=287038|LinkText=(Forum)}}.

=== Welcher Treiber ist installiert ===

Um zu prüfen, welche Version vom Treiber man aktuell verwendet, kann man im Browser die Konsole öffnen und nach einem page reload diesen Log-Eintrag suchen:

[io.fhem]: init [V1.10] (address= ...

In diesem Beispiel ist es Version 1.10 {{Link2Forum|Topic=35960|Message=283617|LinkText=(Forum)}}.

=== neue Clients ===

Das Anlegen neuer Clients In smartVISU müssen nicht händisch ergänzt werden. In der config.ini gibt es den parameter auto_add = true|false. Wenn dieser auf true steht, werden neue Clients automatisch in smartVISU angelegt und bekommen eine Kopie der default Einstellungen.
Im Anschluss können über die Config-Seite die individuellen Einstellungen über die smartVISU-Oberfläche konfiguriert und gespeichert werden (page, design, evtl. calender, etc) {{Link2Forum|Topic=30909|Message=236222|LinkText=(Forum)}}.

=== Ordner und Dateien ===
Auch wenn es im Normalfall nicht notwendig ist sollte, kann es manchmal sinnvoll sein, den genauen Speicherort aller Dateien und Konfigurationsdateien zu kennen und entsprechend Debugging-Trigger hinzuzufügen oder Konfigurationen direkt zu korrigieren.

Die folgenden Pfadangaben gehen davon aus, dass das Root-Verzeichnis des eingesetzten Webservers /var/www/html/ ist und smartVISU im Unterordner /var/www/html/sv liegt.

Dokumenten Root für smartVISU:
/var/www/html/sv/

Konfigurationsdatei von smartVISU:
/var/www/html/sv/config.ini

Treiber:
/var/www/html/sv/driver/io-fhem.js

/var/www/html/sv/driver/io_fhem.min.js

Temp-Ordner:
/var/www/html/sv/temp

Template-Ordner für neue "page":
/var/www/html/sv/pages/_template

Eigener Page-Ordner
/var/www/html/sv/pages/<eigeneSeite>

[[Kategorie:fronthem/smartVISU]]

NetIO-230B

2016-02-14T05:39:32Z

DDT: NETIO230 Modul im Forum hinzugefügt (dev0)

Bei der '''NetIO-230B''' handelt es sich um eine Mehrfachsteckdose (Spannungsverteiler) des Herstellers Koukaam, die sowohl über (TCP-)IP-Befehle als auch manuell gesteuert werden kann.

== Eigenschaften ==
* Eingebauter Webserver
* Vier geschaltete Spannungsausgänge
* Unterstützte Protokolle: HTTP, SMTP, SNTP, DHCP, DNS und Telnet
* CGI Befehle und Telnet-Steuerung
* Abgesichertes Login
* Benutzerrechtgruppen
* LED–Anzeigen für aktuellen Status jedes Ausgangs
* Sicheres Design schützt vor Stromschlag, feuersichere Materialien
* Timer
* Wählbare Start-Einstellungen für jeden Ausgang (An/Aus)
* Taster für manuelle Schaltung der Ausgänge
* Watchdog (automatischer Neustart von nicht antwortenden Netzwerkgeräten)
* E-Mail Benachrichtigung

== Spezifikationen ==
* Eingangsspannung: 230V AC
* Maximaler Schaltstrom: 6A per Steckdose, 10A gesamt
* Latenzzeit: max. 10 ms
* Maße: 300x60x90 mm (BxHxT)
* Netzwerk-Anschluss: 10/100 Mbit/s, RJ-45

== Modul ==
[http://forum.fhem.de/index.php/topic,47814.0.html Hier im Forum] gibt es seit Februar 2016 ein neues NETIO230 Modul, dass non-blocking arbeitet.

== Allgemein ==
NetIO-230B lässt sich komplett per Web Browser bedienen/konfigurieren. Javascript wird benötigt.

== Hinweise zum Betrieb mit FHEM ==
Kopiert aus dieser [http://forum.fhem.de/index.php/topic,13399.0.html Diskussion im Forum].

===Definition===
Steuervariablen definieren, für die spätere Steuerung
:<code>define NET_IO_Switch1 dummy</code>

Notify Script 1 für ON
:<code>define NETIO230_SwitchOn_Switch1 notify NET_IO_Switch1:on {GetHttpFile("<NETIO IP>", "/tgi/control.tgi?login=p:admin:<password>");; \ GetHttpFile("<NETIO IP>", "/tgi/control.tgi?p=1uuu");; \ GetHttpFile("<NETIO IP>", "/tgi/control.tgi?quit=quit");; }</code>

Notify Script 2 für OFF
:<code>define NETIO230_SwitchOn_Switch1 notify NET_IO_Switch1:off {GetHttpFile("<NETIO IP>", "/tgi/control.tgi?login=p:admin:<password>");; \ GetHttpFile("<NETIO IP>", "/tgi/control.tgi?p=0uuu");; \ GetHttpFile("<NETIO IP>", "/tgi/control.tgi?quit=quit");; }</code>

===Erläuterung des Aufrufs===
Mit dieser Zeile wird eine Verbindung mit der NetIO-230B aufgebaut:
:<code>GetHttpFile("<NETIO IP>", "/tgi/control.tgi?login=p:admin:<Password>");;</code>

Ersetzungen:
* ''<Password>'' hier muss das Passwort (im Klartext) eingetragen werden
* ''<NETIO IP>'' hier ist die IP Adresse, z.B. 192.168.1.3 der NetIO-230B einzutragen.

Mit dieser Zeile wird der Ausgangsstatus der NetIO-230B verändert:
:<code>GetHttpFile("<NETIO IP>", "/tgi/control.tgi?p=1uuu");; </code>

Ersetzungen:
* u=nicht verändern
* 0=Ausschalten
* 1=Einschalten

Hierbei müssen immer vier Zeichen angegeben werden. Im obigen Beispiel schaltet '''1uuu''' den ersten Port ein und lässt alle anderen unverändert.

Beenden der Verbindung:
:<code>GetHttpFile("<NETIO IP>", "/tgi/control.tgi?quit=quit");;</code>

===Steuerung in FHEM===
Die Steuerung erfolgt wie folgt:

* Einschalten
:<code>set NET_IO_Switch1 on</code>

* Ausschalten
:<code>set NET_IO_Switch1 off</code>

== Bekannte Probleme ==
Keine

== Links ==

* [http://www.reichelt.de/Messen-Steuern-Regeln/LAN-NETIO230B-SI/3//index.html?ACTION=3&GROUPID=4308&ARTICLE=102254&SHOW=1&START=0&OFFSET=16& Artikelseite] beim Versender [http://www.reichelt.de Reichelt] (Herstellerseite www.koukaam.se derzeit (20.9.2013) nicht erreichbar) mit Beschreibung / Bedienungsanleitung zum Download
* Website des Herstellers [http://www.koukaam.se Koukaam]

[[Kategorie:Other Components]]
[[Kategorie:IP Components]]
[[Kategorie:Schalter (Empfänger)]]

Fronthem

2015-11-16T06:20:34Z

DDT: GAD Editor Einstellungen hinzugefügt

{{Infobox Modul
|ModPurpose=Anbindung von externen Frontends an FHEM (befindet sich in der Alpha-Phase)
|ModType=x


|ModForumArea=Sonstige Systeme
|ModTechName=01_fronthem.pm
|ModOwner=[http://forum.fhem.de/index.php?action=profile;u=769 Jörg alias herrmannj]
}}
Fronthem ist ein Projekt von herrmannj und wurde im fhem-Forum erstmalig angekündigt: http://forum.fhem.de/index.php/topic,27291.0.html

Fronthem verfolgt die Idee, ein externes Web-Frontend (z. B. SmartVisu
http://smartvisu.de) an fhem anzukoppeln und den Datenverkehr sowie die Zusammenarbeit von Befehlen und Parametern zwischen FHEM und dem Web-Frontend zu übernehmen.

Eine Installation für die Verwendung von [[SmartVisu]] mit Fronthem findet man hier [[Installation Fronthem|Installation Fronthem]].

Dazu besteht fronthem aus vier Bausteinen:

==Bausteine==
=== websocket ===
Der Websocket ist eine generische http-Schnittstelle, die von einem externen Frontend aus angesprochen werden kann.

Der Websocket wird durch ein fhem-Modul 01_fronthem.pm realisiert, das im Ordner .../fhem/FHEM/ abgelegt wird.

Der Websocket ist auf Port 2121 fest eingestellt, wird implizit durch die anderen Bausteine verwendet und benötigt im Prinzip keine weitere Beachtung, außer man möchte das Webinterface auf einem anderen Device neben FHEM laufen lassen.

=== device connector ===
Die Device-Connectoren dienen dazu, Endgeräte des Benutzers (PCs, Tablets, Smartphones usw.) als Clients zuzulassen und deren Berechtigungen (read, write) auf der Ebene einzelner Objekte zu steuern. Damit können z. B. die lieben Kinder zwar das Licht und die eigene Heizung steuern, aber nicht die Heizung umprogrammieren oder den Alarm ausschalten. Auch ein PIN-Schutz ist vorgesehen, im Moment aber noch nicht umgesetzt.

Die Device-Connectoren werden durch das fhem-Modul 31_fronthemDevice.pm realisiert, welches im Ordner .../fhem/FHEM/ abgelegt wird.

An den einzelnen Device-Connectoren werden die durch den websocket vom externen Frontend mitgeteilten Objekte aufgelistet und können dort einerseits mit fhem devices und andererseits in den Berechtigungen des jeweiligen Endgerätes konfiguriert werden.

Umgekehrt bedeutet dies, dass man die Kombination der Frontend-items mit den fhem-Devices über die Converter nur einmal pro item machen muss, die Berechtigungen der verwendeten Endgeräte muss man aber jeweils pro Endgerät einzeln setzen.

=== readings converter ===
Die Readings von fhem müssen in die Form der möglichen Werte des Frontends umgewandelt werden. Im umgekehrten Fall müssen Befehle des Frontends in fhem kompatible Befehle umgesetzt werden.
Diese Aufgabe übernehmen die Readings Converter. Sie werden durch die Datei fhconverter.pm realisiert, die im Ordner .../fhem/FHEM/ abgelegt wird.
Bisher gibt es folgende Converter:
* [[#Direct]] für Übertragung ohne Konvertierung
* [[#NumDirect]] für Übertragung von Zahlenwerten in einem begrenzten Werteraum zwischen Min und Max
* [[#NumDisplay]] für Zahlenwerte aus fhem Readings, nur lesend
* [[#WordDisplay]] ist in Planung, für Übertragung von selbst definierbaren Wörtern/Sätze
* [[#OnOff]] für Schalter, Übersetzung von On in 1 und Off in 0
* [[#RGBCombined]] für Übertragung von RGB-Werten so das sie FHEM akzeptiert
Näheres zu denn Convertern unter [[#Converter]]

Weitere Readings Converter werden noch folgen.

=== fronthemEditor ===
Der Javascript Editor ist eine fhem WebIF Erweiterung, um die Bindung der fremden Frontend-Objekte an FHEM Devices/Readings vorzunehmen und die dazu notwendigen Konvertierungen zu wählen.
Er wird durch die Datei fronthemEditor.js repräsentiert, die in den Ordner .../fhem/www/frontend/pgm2/ kopiert wird.

Der Editor erscheint in fhem als komplette gad-Liste in den Details von jedem definierten fronthemDevice. Das mag auf den ersten Blick irreführend sein, weil die Definition der gad/items/plots fhem-global geschieht, war aber wohl die beste mögliche Umsetzung zur Zeit.

Man muss also durch den Editor an einem beliebigen fronthemDevice die Verknüpfung zwischen fhem-devices und smartVISU items herstellen, dann gilt diese für alle fhem Devices. Nur die Berechtigungen der einzelnen fhem Devices werden unterschiedlich gepflegt. (S. u.)

==Basic Syntax==
===Websocket===
:<code>define <name> fronthem</code>

===Device Connector===
Man muss jedes Device, mit dem man zugreifen will definieren.

Dadurch kann genau festgelegt werden, welches Device Rechte für eine jeweilige Schaltfunktion hat.
====IP-Identify====
Identifizierung per IP-Adresse. Dies ist nur im internen Netzwerk sehr sinnvoll.
Ein Device wird definiert mit:
:<code>define <device> fronthemDevice <ip></code>
====Zertificate-Identify====
Das Device wird über ein Zertifikat identifiziert.
Zuerst wird ein Zertifikat generiert, welches dann auf dem Device installiert werden muss.

Diese Methode der Identifizierung verspricht höhere Sicherheit, wie auch denn Vorteil, das man sich nicht einloggen muss.

Diese Funktion ist noch in Entwicklung.

==Converter==
Die Converter sind alle kompatibel mit dem oben erwähnten Frontend [[SmartVisu]] und werden auf Basis dieses Frontends erklärt.

Wenn jemand ein anderes Frontend verwenden will, muss er möglicherweise die Converter anpassen.
===Direct===
Die Werte werden ohne Konvertierung weitergegeben.

Gibt den Wert des von <reading> ohne weitere Wandlung an das Frontend weiter. In umgekehrter Richtung wird der vom Frontend geliefert Wert ohne Wandlung im hinterlegten <set> eingesetzt.

Beispiel:
Anzeige eines An- oder Abwesenheitszustandes im Frontend (Textanzeige, Icon, Button)

===NumDirect===
NumDirect arbeitet bidirektional. Die Werte werden genau wie bei Direct ohne Umwandlung weitergegeben.

Der feine Unterschied zu Direct ist jedoch, das nur Zahlenwerte übergeben werden können.

Desweiteren kann man einen minimalen und maximalen Wert mitangeben. Dies hat denn Sinn, das man keine Werte einstellen kann, die überhaupt nicht möglich wären.

In der SmartVisu kann man z.B. -100°C einstellen, das wäre in FHEM jedoch gar nicht möglich.

===NumDelayed===
NumDelayed ist noch in Arbeit.

Ein bidirektionaler numerischer Converter mit einstellbarer Verzögerung.

Bietet bei der Ansteuerung mechanischer Aktoren (Markise, Jalousie) Vorteile gegenüber NumDirect. Als Beispiel sei die Steuerung einer Jalousie über einen Slider genannt. Da Slider ihre Werte kontinuierlich an FHEM übermitteln, würde bei der Verwendung anderer Converter dem entsprechenden Aktor (z.B. HM-BP), während der Benutzer den Slider bedient, mehrfach der vermeindliche Sollwert übermittelt werden. Gleichzeitig beginnt der Aktor seine Fahrt und übermittelt dem Slider seine aktuelle ist Position. Das führt zu einem springen des Sliders und einer "unschönen" Bedienung.

NumDelayed nimmt daher die Signale des Sliders entgegen, wartet jedoch mit der Weitergabe solange, bis sich der Slider (xxx ms, konfigurierbar) nicht mehr bewegt. In Gegenrichtung wird ebenso verfahren, erst wenn der Aktor seine Endposition erreicht, wird der Slider im Frontend aktualisiert. In diesem Beispiel würde das bedeuten das der Slider im Normalfall ohnehin so steht (Soll) wie vom Aktor gemeldet (Ist). Natürlich könnte der Benutzer oder ein Hindernis die Fahrt auch unterbrochen haben, dann würde der Slider auf die gemeldete Position aktualisiert.

===NumDisplay===
NumDisplay arbeitet nur in eine Richting, FHEM zu Frontend. Die Werte werden ohne Umwandlung weitergegeben.

Es ist dazu gedacht Zahlenwerte zu übergeben, ohne etwas zu verändern.

z.B. für Temperaturwerte

===WordDisplay===
WordDisplay ist derzeit in Planung, es wird noch über die Umsetzung diskutiert.

WordDisplay soll nur in eine Richtung arbeiten, FHEM zu Frontend. Es ist dazu gedacht Wörter oder Textpassagen zu übertragen.

Jedoch soll es möglich sein, eine Umwandlung selbst festzulegen. So kann man einfach mehrere Textausgaben abhängig vom Zustand an das Frontend schicken:

z.B. Geofancy: Home -> Zuhause, Underway -> Unterwegs, Work -> Arbeit

===OnOff===
Für einfache Ein/Aus-Funktionen.

FHEM interpretiert Ein/Aus-Funktionen mit on/off, SmartVisu jedoch mit 1/0.

Der OnOff-Converter wandelt diese bidirektional, damit sie richtig interpretiert werden.

===RGBCombined===
Ein Converter zur Steuerung von RGB Leuchtmitteln über Farbauswahlfelder (zb. Farbkreis)

Bidirektional, wandelt, verwendet 3 Frontend Items

reading: Name eines reading mit HEX RGB Wert des Leuchtmittels
converter (mit Parameter): <code>RGBCombined <itemRed>, <itemYellow>, <itemBlue></code>

set: Name des set Befehls, bekommt HEX RGB Wert übergeben

Dieser Converter muss gleichlautend für alle 3 RGB Kanäle des Frontends definiert werden.

==Device Connector==
Sobald ein fronthemDevice definiert ist, kann man über die device details in fhem die GADs definieren und die Rechte verteilen.
===GAD definieren===
Eine GAD-Definierung besteht aus:
[[Datei:DeviceDefine.png|400px|thumb|right|GADs definieren]]
*mode
*device
*reading
*converter
*cmd set
====mode====
Es gibt 2 Modis:
*item
*plot
====device====
Hier wird der Name des FHEM-Devices eingetragen, an das die Befehle geschickt werden. Die vorhandenen Devices in fhem werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Groß/Kleinschreibung muss beachtet werden!

====reading====
Das für die Anzeige zu verwendende Reading des fhem Devices, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Readings werden, wenn das Frontend dies anfordert, aktiv von fronthem gelesen und (per push) proaktiv an das Frontend gesendet wenn fhem entsprechende events erzeugt.

====converter====
Hier gibt man denn Namen des Converters an, denn man verwenden möchte.
Es stehen unterschiedliche converter für verschiedene Aufgabenstellungen zur Verfügung. Über das Konzept der converter können fhem Device unterschiedlichster Typen und Funktionen über das Frontend bedient werden. So versorgt der gleiche converter der die Solltemperatur des virtuellen Heizungsthermostats (bidriektional) einstellt auch die Füllstandanzeige der Zisterne sowie den Dimmer. In all diesen Fällen handelt es sich um die Übertragung von numerischen Werten. Converter können dabei auch Spezialaufgaben wie die Begrenzung des Wertebereichs übernehmen. So lässt sich über NumDirect zum Beispiel die Solltemperatur Einstellung für virtuelle Heizungsregler auf Min und Max Werte begrenzen.

Oben ist eine Standardliste der [[#Converter]]. Die meisten Devices können mit diesen Convertern angesteuert werden.

Groß/Kleinschreibung muss beachtet werden!

====cmd set====
Das zum Schreiben zu verwendende Reading des fhem Devices, z. B. "state" oder "Level". Die vorhandenen Readings des gewählten fhem-Devices werden als Liste unter dem Eingabefeld angezeigt, sobald man mit der Eingabe beginnt.

Das gewählte Reading gibt den "set" des fhem Devices an, der die Rückgabe des Converters entgegen nimmt.

Bei Lampe z.B. "state".

===Devicerechte vergeben===
[[Datei:DeviceRechte.png|400px|thumb|right|Devicerechte vergeben]]
Devicerechte bestehen aus:
*read
*write
*PIN GAD
====read====
Das Device darf die Statuswerte auslesen, jedoch nicht verändern.

====write====
Das Device darf Statuswerte ändern.

====PIN GAD====
In Entwicklung...

====Whitelisting deaktivieren====
Möchte man diese. differenzierte Berechtigungssteuerung umgehen, kann das Attribut "whitelisting" der fronthemDevices auf false gesetzt werden. Das bedeutet dann, dass unabhängig von den whitelisting - Checkboxen das fronthemDevice immer auf alle GADs lesen und schreiben darf.

==Universelle ZeitSchaltUhr UZSU==
Es existiert ein Widget für eine universelle ZeitSchaltUhr auf GitHub unter https://github.com/herrmannj/smartvisu-widgets beziehen

Dank dafür an mworion!

Man muss dazu die uzsu_widget.html in das eigene Verzeichnis in ../pages/.. kopieren und die visu.js und die visu.css in seine Installation integrieren (Achtung, wenn die beiden Dateien schon bestehen, dann muss man das manuell zusammenkopieren!)

Das Widget kann in SmartVISU-Seiten wie gewohnt eingebunden werden:

(für ein Ergebnis, das der Benutzer direkt eintippen kann, z.B. 'on' oder 'off')

<nowiki>
{% import "widget_uzsu.html" as visu %}

{{ visu.uzsu_icon('UZSUtxt', gad_uzsu, '', '', '', '', 'text') }}
</nowiki>

oder Text als Dropdown:

<nowiki>
{% import "widget_uzsu.html" as visu %}

{{ visu.uzsu_icon('UZSUtxt', gad_uzsu, '', '', '', '', 'text', ['an', 'aus']) }}
</nowiki>

oder (für eine einzugebende Ziffer zwischen 0 und 100)
<nowiki>
{% import "widget_uzsu.html" as visu %}

{{ visu.uzsu_icon('UZSUnum', gad_uzsu, '', '', '', '', 'num', [0, 100]) }}
</nowiki>

oder (für ein Ergebnis {0,1}, das aber als flip mit 'an' und 'aus' angezeigt wird)
<nowiki>
{% import "widget_uzsu.html" as visu %}

{{ visu.uzsu_icon('UZSUnum', gad_uzsu, '', '', '', '', 'bool', ['an', 'aus']) }}
</nowiki>

Um die Antwort des Widgets in fhem zu verarbeiten, benötigt man

1. je ein Reading uzsu an dem zu schaltenden Device, das man mit

<nowiki>
setreading <device> uzsu {}
</nowiki>

erzeugen MUSS.

2. eine Anbindung des UZSU-GAD per UZSU Converter aus der 99_fronthemUtils.pm (s. u.) an das Reading uzsu des zu schaltenden Device read und write in fhem

3. Den sonstigen UZSU Code aus der 99_FronthemUtils.pm aus dem http://github.com/herrmannj/fronthem (ist bei aktuellem fronthem alles schon drin)

Dieser Code erzeugt aus den Einstellungen im Widget entsprechende WeekdayTimer in fhem und löscht und erstellt neu bei jeder Änderung in SmartVISU.

4. Die Funktion muss getriggert werden. Dazu ist ein notify nötig, das auf die Veränderung der uzsu Readings reagiert:

<nowiki>

define UZSU notify .*:uzsu:.* { UZSU_execute($NAME, $EVTPART1) }

</nowiki>

5. GAD Editor Einstellungen:

<nowiki>
mode: item
device: <DEIN_DEVICE>
reading: uzsu
converter: UZSU
cmd set: uzsu
</nowiki>

Voila!

[[Kategorie: FHEM Frontends]]