Forse annunciato anche se non inizialmente previsto, l’articolo che ho dedicato ad Arlo e alla comunicazione con le sue API via bash (Arlo: dialogare con il sistema tramite bash) è figlio del rallentamento che ha subìto IFTTT negli ultimi giorni, il quale ha ben deciso di farmi sapere su Telegram che Home Mode si disattiva (o riattiva al rientro a casa) solo ore dopo rispetto alla reale geolocalizzazione del mio smartphone (o di quello di Ilaria) ed effettivo cambio di stato di tado°. Ho risolto il problema relativo all’attivazione / disattivazione del rilevamento movimenti di Arlo ma a questo punto ho voluto fare il giro completo e mi sono “portato a casa” anche il check dello stato di presenza tado°, sempre via bash, sempre via cURL, stavolta mettendo all’opera il Raspberry direttamente anziché passare dal NAS (ma ci vorrebbe davvero un attimo a integrare il tutto con quanto già presente sul mio Synology).

Bentrovato token!

Tutto cambia per non cambiare, per interrogare le API di tado° ti servirà ancora una volta un token, questo lo si ottiene dalla combinazione di utente e password già in tuo possesso come gestore del riscaldamento / raffreddamento tado°, l’operazione è davvero automatizzabile con un paio di trucchi tattici che andrò chiaramente a spiegarti. Tutto il codice sorgente sarà disponibile contestualmente nel mio spazio GitHub, ma ci arriveremo tra breve. Ancora una volta voglio ringraziare immediatamente l’autore dell’articolo che mi ha indicato la giusta via permettendomi di arrivare al risultato desiderato, si tratta di Terence Eden e l’articolo originale si trova all’indirizzo shkspr.mobi/blog/2019/02/tado-api-guide-updated-for-2019.

Passiamo quindi alla pratica e diamo un’occhiata insieme alla stringa da eseguire e da cosa dovrà essere composta:

curl --request POST 'https://auth.tado.com/oauth/token' \
-d 'client_id=tado-web-app' \
-d 'grant_type=password' \
-d 'scope=home.user' \
-d 'username=TUO-UTENTE' \
-d 'password=TUA-PASSWORD' \
-d 'client_secret=wZaRN7rpjn3FoNyF5IFuxg9uMzYJcvOoQ8QWiIqS3hfk6gLhVlG57j5YNoZL2Rtc'

Se al posto di TUO-UTENTE e TUA-PASSWORD sono certo ti sarà chiaro cosa specificare, credo possa essere meno chiaro o immediato quel client_secret già dichiarato. Quel codice è stabilito direttamente da tado°, eventualmente aggiornato da quest’ultimo solo in caso di necessità. Per capirci: l’articolo di Terence è stato pubblicato nel 2019 (nel giorno di S. Valentino più precisamente) ma ancora oggi il client_secret è il medesimo. Per poter conoscere in qualsiasi momento il giusto client_secret da utilizzare ti basterà puntare il browser all’indirizzo my.tado.com/webapp/env.js. Io ho previsto che il mio script lo vada a recuperare autonomamente, più precisamente se ne occuperà questo pezzo di codice:

curl -s -o tado.env https://my.tado.com/webapp/env.js > /dev/null
env=$(more tado.env | grep "clientSecret")
clientSecret=$(sed -n "s/^.*'\(.*\)'.*$/\1/p" <<< $env)
rm tado.env

Quanto vedi qui sopra non farà altro che scaricare il contenuto del file presente sui server di tado° all’interno di un temporaneo tado.env (un puro file di testo), cercherà poi la stringa contenente il clientSecret e ne memorizzerà il codice all’interno di una variabile ignorando qualsiasi altra cosa. Al termine cancellerà il file temporaneo e io successivamente utilizzerò quella variabile per poter procedere con la creazione del token (quindi ciò dovrebbe farti capire che nel mio script non è dichiarata in maniera fissa la client_secret all’interno della cURL, ma lo vedrai meglio dopo).

Come già visto per Arlo, la risposta della cURL sarà qualcosa di molto simile, in JSON:

{"access_token":"XXXXXXXXXXXXXXX",
"token_type":"bearer",
"refresh_token":"XXXXXXXXXXXXXXX",
"expires_in":599,
"scope":"home.user",
"jti":"xx123xxx-x12x-1x23-1xx2-x1234x56789x"}

Forse inutile dire che al posto di quelle poche “X” vedrai a monitor molte più lettere e numeri. L’access_token ha una durata di 10 minuti (599 secondi, lo si può vedere anche nella risposta JSON che hai ottenuto), allo scadere dei 10 minuti potrai rinnovare il token andando a eseguire un refresh tramite – manco a dirlo – il refresh_token. Se non vuoi farlo puoi sempre chiedere un nuovo access_token, cosa che io faccio (come scoprirai tra poco).

La casa

Hai il tuo token, la chiave segreta ufficiale tado° da questo momento non serve più, a questo punto ciò che manca è conoscere l’ID assegnato alla tua casa, attraverso il quale sarà possibile successivamente chiedere al sistema il dettaglio riguardo lo stato di presenza (ma non solo). Per conoscere questo dettaglio ti basterà imbastire una nuova cURL:

curl -s "https://my.tado.com/api/v1/me" -H "Authorization: Bearer XXXXXXXXXXXXXXX"

Al posto di tutte quelle “X” dovrai indicare il tuo token autorizzativo precedentemente ottenuto. Così facendo dovresti poter arrivare a una risposta JSON simile a questa:

{"name":"Mario Rossi",
"email":"mario.rossi@contoso.com",
"username":"mario.rossi@contoso.com",
"enabled":true,
"id":"XXXXXXXXXXXXXXX",
"homeId":123456,
"locale":"it",
"type":"WEB_USER"}

È proprio quel valore homeId a servirti, è un identificativo univoco associato alla tua casa, salvato (e quindi riconosciuto) sui server di tado°.

Dove mi trovo?

Tutto chiaro fino a ora, non resta che chiedere alle API di tado° dove vengo attualmente rilevato per avere la conferma ultima che – mettendo tutto insieme – io possa fare un controllo ogni 10 minuti (minimo, non avrebbe senso farlo a cadenza inferiore secondo me, a meno di non aver indicato un raggio molto limitato nell’applicazione di tado° per la geolocalizzazione) avvisandomi se tutto sta funzionando correttamente tramite il mio solito bot di Telegram (o qualsiasi altra soluzione a tuo piacimento). Per poter fare questa mossa ti basterà lanciare ancora una volta una cURL in cui indicare il token autorizzativo e l’identificativo della casa, più precisamente:

curl -s https://my.tado.com/api/v2/homes/TUO-ID-CASA/state -H "Authorization: Bearer XXXXXXXXXXXXXXX"

Credo che aguzzando un po’ la tua vista capirai bene dove mettere le mani, dovrai infatti sostituire TUO-ID-CASA con il reale identificativo (homeId) che hai ottenuto poco fa, al posto delle varie “X” deve invece trovare spazio il token generato anch’esso in precedenza. Non perdere la pazienza se arrivato qui il tuo token sarà stato invalidato, creane uno nuovo utilizzando le indicazioni che ti ho fornito qualche colpo di scroll di mouse più sopra, il resto dei dati rimane praticamente invariato e potrai tornare facilmente a questo paragrafo. La risposta a questa cURL, sempre JSON, sarà molto simile a questa:

{"presence":"HOME","presenceLocked":false}

Quello che a te interessa è ciò che restituisce il valore presence, questo infatti corrisponderà a HOME se ti trovi tra le mura di casa, AWAY quando sarai fuori dal tuo appartamento, superata la distanza da te scelta come raggio di scansione della geolocalizzazione dell’applicazione di tado°.

Mettere tutto insieme

Ho messo tutto questo insieme, per molti versi ho riadattato il lavoro che era stato fatto con lo script di sorveglianza Synology, ripensato e ottimizzato per poter lavorare con tado°, restituendomi quel valore di presenza che è l’unica cosa che attualmente mi interessa, in realtà tu puoi chiedere alle API tado° molto più di quanto io non ti abbia mostrato, l’articolo di Terence è davvero un ottimo spunto per poter scoprire molte più curiosità e modi di intervenire sui propri prodotti. Quello che lo script va a fare non è null’altro che:

• procurarsi il valore di chiave segreta stabilito da tado°, senza necessità che tu lo debba conoscere o che tu possa rimanere indietro rispetto a un nuovo valore che potrebbe essere sempre ritoccato in futuro (a meno che non cambi proprio l’indirizzo del file JS che viene controllato, in tal caso cercherò il nuovo URL e aggiornerò lo script).
• Generare il token utilizzando nome utente e password che tu gli darai in pasto.
• Trovare l’identificativo della tua casa.
• Verificare lo stato di presenza e tenerne traccia in un file di stato, contestualmente – se abilitato – avvisarmi riguardo il cambio di stato rilevato via Telegram, appoggiandosi a un bot che manderà una nota scritta (da me stabilita) in un determinato canale.

Nello script ho fatto uso di un po’ di funzioni di pulizia del testo per cercare di ottenere sempre il dato preciso a me utile, ho poi scoperto piacevolmente jq per evitare di dovermi reinventare la ruota facendo elaborare i risultati JSON a uno codice PHP. Il risultato potrebbe non essere di tuo gradimento ma funziona, ti invito a collaborare con me per renderlo migliore rispetto a oggi, ho pubblicato il tutto su GitHub come al mio solito, ho creato una sottocartella del progetto di sorveglianza Synology (d’altronde si parla grosso modo sempre della stessa cosa): github.com/gioxx/AVM-FRITZ-Box-Synology-Surveillance-Home-Mode-Automation/blob/mschippr/master/tado/tado.sh.

Le uniche cose da modificare all’interno dello script saranno:

• TELEGRAM (modificare da 0 a 1 se vuoi che il cambiamento di stato ti venga notificato tramite Telegram) specificando chiaramente il token del bot (BOT_TOKEN) e il canale (CHAT_ID) dove far pubblicare l’alert (entrambi questi dati sono a tuo carico, ti ho già parlato in passato di come creare un bot Telegram).
• Utente (TADOUSER), password (TADOPWD) e messaggi di rientro in modalità Home (MSG_TADO_HOME) o abbandono della stessa, quindi Away (MSG_TADO_AWAY), da lanciare su Telegram nel caso tu abbia deciso di attivare la funzionalità, diversamente non ti serviranno a nulla.

Il resto può rimanere invariato, pensa a tutto lo script. Altra cosa che devi sapere: il file di stato di presenza verrà salvato nella stessa identica cartella dello script, si chiamerà tado.state ed è un file di testo, puoi quindi leggerlo come meglio credi. La prima volta che il file verrà creato verrà inizializzato con la modalità AWAY. Non preoccupartene, se ti trovi in casa al successivo ti basterà avviare nuovamente lo script, questo verificherà il parametro di presence e chiaramente modificherà quello salvato nel file di stato utilizzando quello reale (quindi HOME).

Tutto questo circo è stato testato con successo sul mio sistema tado° casalingo che utilizza le valvole termostatiche intelligenti e relativo gateway per comunicare con i server del produttore. Ho pressoché certezza che tutto possa filare altrettanto liscio come l’olio nel caso in cui tu utilizzi il termostato intelligente o il sistema di controllo dei condizionatori d’aria.

Io resto a disposizione per qualsiasi tuo dubbio in merito, l’area commenti è lì che ti aspetta.

#StaySafe

Riconoscimenti:
shkspr.mobi/blog/2019/02/tado-api-guide-updated-for-2019
cameronnokes.com/blog/working-with-json-in-bash-using-jq
stackoverflow.com/questions/59895/how-to-get-the-source-directory-of-a-bash-script-from-within-the-script-itself