new commandref syntax - help is now working on fhem page

added ZoneIDs to readings - some code cleanup

README.md

@@ -1,18 +1,40 @@
 # FHEM-Tado
 
 FHEM Modul für [tado](https://www.tado.com/at/) Heizungssteuerung.
-Bin unter philipp@wolfmajer.at erreichbar.
+
+Für Fragen / Anliegen bin ich im FHEM-Forum (https://forum.fhem.de/index.php/topic,116764) oder unter philipp@wolfmajer.at erreichbar.
 
 ## Was wird unterstützt?
 * Übersicht aller Tado Zonen
 * Temperatur & Luftfeuchtigkeit
 * Batteriestatus
-* akruelle Heizleistung
+* aktuelle Heizleistung
 * Wunschtemperatur
-* Overlays
-* setzen einer gewünschten Temperatur pro Raum (set setZoneOverlay ``<zonenID>`` ``<Wunschtemperatur>``)
-* setzen der Geotracking Einstellung für ein Mobiles Gerät
-* ...
+* Overlays (static & timer)
+* ChildLock Status (nur Reading)
+
+## Installation 
+
+1. Wechsle mit der Console (SSH) in dein FHEM Installationsverzeichnis (Pfad ggf. anpassen): 
+
+`cd /opt/fhem/FHEM/`
+
+2. Lade die aktuellste Modulversion auf dein FHEM herunter:
+
+`wget https://git.wolfmajer.at/Public/FHEM-Tado/raw/branch/master/98_TadoAPI.pm`
+
+3. Zur Sicherheit noch die Berechtigungen anpassen:
+
+`sudo chown fhem:dialout 98_TadoAPI.pm`
+
+`sudo chmod 644 98_TadoAPI.pm`
+
+5. FHEM neu starten.
+
+ `sudo systemctl restart fhem.service`
+
+6. Fertig, weiter geht´s in FHEM mit der Definition
+
 
 ## Definition & Funktion
 
@@ -22,22 +44,64 @@ In FHEM wird das Modul folgendermaßen definiert:
 
 Das Passwort muss mit dem `set <name> <password>` Befehl (z.B. set myTado password 12345) gesetzt werden.
 
-Standardmäßig aktualisiert das Modul alle 5 Minuten die Werte *tado mode; Zone 1 Temperatur; Geolocation für die angegebene mobID und den API-Status*. (siehe Bild Modulübersicht)
+Standardmäßig aktualisiert das Modul alle 5 Minuten die folgenden Werte:
+* Zonen Temperatur
+* Zonen Luftfeuchtigkeit
+* aktuelle Wunschtemperatur einer Zone
+* Geolocation aller eingerichteten Smartphones
+* API-Status (siehe Bild Modulübersicht)
+* Batteriestatus aller Tado Geräte
+* Overlays (manuell eingestellte Wunschtemperatur die den Intelligenten Zeitplan überschreibt)
+* Timed Overlays (manuell eingestellte Wunschtemperatur, die den Intelligenten Zeitplan für die angegebene Zeitdauer (Sec) überschreibt)
 
 Sämtliche externen Aufrufe sind *nonblocking* ausgeführt.
 
-<img src="https://home.wolfmajer.at/wolfgit/Public/FHEM-Tado/raw/branch/master/doc/Modul1.PNG" width="500" />
+### Overlay für Zone setzen
+`set <name> setZoneOverlay <zonenID> <Wunschtemperatur> [Dauer des Overlay in Sekunden]`
 
-## OAuth2 Token Authentifizierung
+**INFO:** unterstützte Werte der Wunschtemperatur: `remove=delete overlay; 0=heating power off; 1<=desired temperature (overlay)`
 
-Alle Anfragen an das API sind über *oauth2* realisiert.
-Zuerst wird ein Token (mit Username und Passwort) von tado angefordert der ca. 10 Minuten gültig ist. Alle folgenden Aufrufe werden nur mehr über den Token realisiert. Das Modul prüft den Token auf Gültigkeit und erneuert ihn bevor er abläuft.
+<img src="https://git.wolfmajer.at/Public/FHEM-Tado/raw/branch/master/doc/so.PNG" width="500" />
 
-Pfad des Token ist im Modul fix eingestellt `/fhem-root/FHEM/FhemUtils/TadoAPI_token_<fhem-devicename>`
+#### Info für Overlay mit Timer
+Kann entweder mit wie oben beschrieben oder, für Widgets von Tablet UI interessant, mit `set <name> timedZoneOverlay <zonenID> <Dauer des Overlay in Sekunden> <Wunschtemperatur>` gesetzt werden.
+
+Bei einem Timer Overlay erscheint in den tado Readings ein neuer Wert `Zone<ID>Lock`. Zusätzlich ist in den Internals noch ein Helper mit der Info welche Zone gesperrt ist. Das kann man in FHEM dann in eigenen Scripts weiterverarbeiten. (z.B. Anwesenheitserkennung soll Overlay nicht überschreiben wenn Timer...)
+
+### Overlay für alle Zonen setzen
+`set <name> setAllOverlays <Wunschtemperatur> [Dauer des Overlay in Sekunden]`
+
+**INFO:** unterstützte Werte der Wunschtemperatur: `remove=delete overlay; 0=heating power off; 1<=desired temperature (overlay)`
+
+### Tado Geräte anzeigen (z.B. Battery State)
+`get <name> getZoneDevices`
+
+<img src="https://git.wolfmajer.at/Public/FHEM-Tado/raw/branch/master/doc/gzd.PNG" width="500" />
 
 
-## Verwendung
+## Screenshots
+### Modulübersicht
 
+<img src="https://git.wolfmajer.at/Public/FHEM-Tado/raw/branch/master/doc/Modul1.PNG" width="500" />
+
+
+## Verwendung in FHEM
+
+### FHEM Tablet-UI
+Im Tablet UI lassen sich alle Readings des tado FHEM Modul anzeigen:
+
+<img src="https://git.wolfmajer.at/Public/FHEM-Tado/raw/branch/master/doc/tablet-ui-readings.PNG" width="500" />
+
+Auch lassen sich im Tablet UI mit einem Thermostat Widget alle Zonen steuern:
+
+<img src="https://git.wolfmajer.at/Public/FHEM-Tado/raw/branch/master/doc/tablet-ui-thermostat.PNG" width="500" />
+
+Code Snippet für einen Thermostat Widget:
+```
+<div data-type="thermostat" data-height="250" data-width="285" data-temp="Temperatur_Heizung" data-min="15" data-max="24" data-device="mytd" data-set="timedZoneOverlay 1 7200" data-get="DesiredTemp_Heizung"></div>
+```
+
+### Tado mit Anwesenheit verknüpfen
 In Kombination mit dem Presence (bzw. Residents) Modul kann man *tado* automatisch zwischen HOME und AWAY umschalten lassen und die Temperatur mittels FHEM absenken lassen.
 
 Beispiel dafür:
@@ -46,12 +110,12 @@ Beispiel dafür:
 +*00:03:00 {
 if (Value("Bewohner") eq "absent" && ReadingsVal("mytd","OverlayType_<zonenName>",0) ne "MANUAL")
 {
-    fhem("set mytd setZoneOverlay <zonenID> 18.6; set mytd setGeo <Mobile ID> on");
+    fhem("set mytd setZoneOverlay <zonenID> 16; set mytd setGeo <Mobile ID> on");
     Log 3, "TadoAPI:  Keiner mehr zu Hause - Overlay und Geolocation wird aktiviert.";
 }elsif (Value("Bewohner") eq "home" && ReadingsVal("mytd","OverlayType_Heizung",0) eq "MANUAL")
 {
 	# jemand zu hause
-	fhem("set mytd setZoneOverlay <zonenID> off; set mytd setGeo <Mobile ID> off");
+	fhem("set mytd setZoneOverlay <zonenID> remove; set mytd setGeo <Mobile ID> off");
 	Log 3, "TadoAPI:  Bewohner anwesend - Overlay wird deaktiviert.";
 }
 }
@@ -60,7 +124,7 @@ if (Value("Bewohner") eq "absent" && ReadingsVal("mytd","OverlayType_<zonenName>
 
 GPlot-Beispiel:
 
-<img src="https://home.wolfmajer.at/wolfgit/Public/FHEM-Tado/raw/branch/master/doc/Modul2-SVG.PNG" width="500" />
+<img src="https://git.wolfmajer.at/Public/FHEM-Tado/raw/branch/master/doc/Modul2-SVG.PNG" width="500" />
 
 ```
 # Created by FHEM/98_SVG.pm, 2019-10-20 03:52:15
@@ -69,7 +133,7 @@ set output '<OUT>.png'
 set xdata time
 set timefmt "%Y-%m-%d_%H:%M:%S"
 set xlabel " "
-set title '<TL>'
+set title 'Schafzimmer <TL> <L1>'
 set ytics 
 set y2tics 
 set grid ytics
@@ -78,21 +142,31 @@ set y2label "Heizleistung"
 set yrange [18:26]
 set y2range [0:100]
 
-#Log_tadoAPI 4:mytd.Temperatur\x3a::
-#Log_tadoAPI 4:mytd.Geolocation\x3a::$fld[3]*=30
-#Log_tadoAPI 4:mytd.Luftfeuchtigkeit\x3a::
-#Log_tadoAPI 4:mytd.Heizleistung\x3a::
+#Log_tadoAPI 4:mytd.Temperatur_Schlafzimmer\x3a::
+#Log_tadoAPI 4:mytd.OverlayType_Schlafzimmer\x3a:1:$fld[3]&&$fld[3]=~"MANUAL"?20:0
+#Log_tadoAPI 4:mytd.Luftfeuchtigkeit_Schlafzimmer\x3a::
+#Log_tadoAPI 4:mytd.Heizleistung_Schlafzimmer\x3a::
+#Log_tadoAPI 4:mytd.DesiredTemp_Schlafzimmer\x3a::
 
 plot "<IN>" using 1:2 axes x1y1 title 'Temperatur' ls l1fill lw 1 with lines,\
-     "<IN>" using 1:2 axes x1y2 title 'Geo' ls l0fill_stripe lw 1 with histeps,\
+     "<IN>" using 1:2 axes x1y2 title 'Abwesenheit' ls l0fill_stripe lw 0.5 with histeps,\
      "<IN>" using 1:2 axes x1y2 title 'Feuchte' ls l2 lw 1 with lines,\
-     "<IN>" using 1:2 axes x1y2 title 'Heizleistung' ls l5 lw 1.5 with lines
+     "<IN>" using 1:2 axes x1y2 title 'Heizleistung' ls l5dot lw 1.5 with lines,\
+     "<IN>" using 1:2 axes x1y1 title 'Desired' ls l5 lw 0.5 with lines
 ```
 
-## Screenshots
+## Technische Information
+### OAuth2 Token Authentifizierung
 
-### Tado Geräte anzeigen (z.B. Batteriestatus)
-<img src="https://home.wolfmajer.at/wolfgit/Public/FHEM-Tado/raw/branch/master/doc/gzd.PNG" width="500" />
+Alle Anfragen an das API sind über *oauth2* realisiert.
+Zuerst wird ein Token (mit Username und Passwort) von tado angefordert der ca. 10 Minuten gültig ist. Alle folgenden Aufrufe werden nur mehr über den Token realisiert. Das Modul prüft den Token auf Gültigkeit und erneuert ihn bevor er abläuft.
 
-### Temperatur einer Zone manuell festlegen
-<img src="https://home.wolfmajer.at/wolfgit/Public/FHEM-Tado/raw/branch/master/doc/so.PNG" width="500" />
+Pfad des Token ist im Modul fix eingestellt `/fhem-root/FHEM/FhemUtils/TadoAPI_token_<fhem-devicename>`
+
+## Credits
+
+Thx to:
+
+[https://shkspr.mobi/blog/2019/02/tado-api-guide-updated-for-2019/](http://)
+
+[http://blog.scphillips.com/posts/2017/01/the-tado-api-v2/](http://)