ESPEasy

ESPEasy
Zweck / Funktion
Steuerung eines Espressif ESP8266/ESP32 WLAN-SoC
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE Thema
Support (Forum)	Bastelecke/ESP Familie
Modulname	34_ESPEasy.pm
Ersteller	dev0
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Dieser Wiki-Artikel soll und kann die 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 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 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: 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 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 generelle 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:

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" }
    }
  }
)

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'.

attr <dev> useSetExtensions 1
attr <dev> eventMap /gpio 15 on:^on$/gpio 15 off:^off$/

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.

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} 
)

Logging

ESPEasy Bridge

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.

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.

Received header: {'Content-Length' => '298','Authorization' => 'Basic ***** ','Host' => '10.0.0.53','Connection' => 'close'}

Diese received header Zeile enthält die Daten des Headers, die via HTTP vom ESP empfangen werden. Ein eventuell vorhandenes Passwort wird maskiert.

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"}}}}

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.

Src:'BA_SEN1'/'DHT22' => ident:BA_SEN1 dev:ESPEasy_BA_SEN1 combinedDevice:1

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.

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

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

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

Im Detail:

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

Das ist wieder die, bereits oben beschriebene, dispatch Zeichenkette, die jetzt vom logischen Device empfangen wurde.

ESPEasy ESPEasy_BA_SEN1: temperature: 21.2

ESPEasy ESPEasy_BA_SEN1: humidity: 10.3

Die Readings temperature und humidity wurden aktualisiert.

ESPEasy ESPEasy_BA_SEN1: Internals: unit:4 sleep:1 build:137 version:9

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

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.

Weblinks

• FHEM ESPEasy Modul-Dokumentation
• ESP Easy Firmware Wiki
• ESP Easy Command Reference
• 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