FHEM-Tado/README.md

# FHEM-Tado

FHEM Modul für [tado](https://www.tado.com/at/) Heizungssteuerung.
Bin unter philipp@wolfmajer.at erreichbar.

## Was wird unterstützt?
* Übersicht aller Tado Zonen
* Temperatur & Luftfeuchtigkeit
* Batteriestatus
* aktuelle Heizleistung
* Wunschtemperatur
* Overlays (static & timer)

## Definition & Funktion

In FHEM wird das Modul folgendermaßen definiert: 

`define <name> TadoAPI <username> [<homeID>]`

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 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 überschreibt für eine angegebene Zeitdauer)

Sämtliche externen Aufrufe sind *nonblocking* ausgeführt.

### Overlay für Zone setzen
`set setZoneOverlay <zonenID> <Wunschtemperatur> [Dauer des Overlay in Sekunden]`

**INFO:** unterstützte Werte der Wunschtemperatur: `remove=delete overlay; 0=heating power off; 1<=desired temperature (overlay)`

<img src="https://home.wolfmajer.at/wolfgit/Public/FHEM-Tado/raw/branch/master/doc/so.PNG" width="500" />

### Overlay für alle Zonen setzen
`set 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)
<img src="https://home.wolfmajer.at/wolfgit/Public/FHEM-Tado/raw/branch/master/doc/gzd.PNG" width="500" />


## Screenshots
### Modulübersicht

<img src="https://home.wolfmajer.at/wolfgit/Public/FHEM-Tado/raw/branch/master/doc/Modul1.PNG" width="500" />


## Verwendung in FHEM

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:

```
+*00:03:00 {
if (Value("Bewohner") eq "absent" && ReadingsVal("mytd","OverlayType_<zonenName>",0) ne "MANUAL")
{
    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> remove; set mytd setGeo <Mobile ID> off");
	Log 3, "TadoAPI:  Bewohner anwesend - Overlay wird deaktiviert.";
}
}
...
```

GPlot-Beispiel:

<img src="https://home.wolfmajer.at/wolfgit/Public/FHEM-Tado/raw/branch/master/doc/Modul2-SVG.PNG" width="500" />

```
# Created by FHEM/98_SVG.pm, 2019-10-20 03:52:15
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title 'Schafzimmer <TL> <L1>'
set ytics 
set y2tics 
set grid ytics
set ylabel "Temperatur"
set y2label "Heizleistung"
set yrange [18:26]
set y2range [0:100]

#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 '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 l5dot lw 1.5 with lines,\
     "<IN>" using 1:2 axes x1y1 title 'Desired' ls l5 lw 0.5 with lines
```

## Technische Information
### OAuth2 Token Authentifizierung

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.

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://)