Tuya Home Assistant: scopriamo come poter gestire i dispositivi intelligenti Tuya Smart Life in Home Assistant, sia attraverso il cloud Tuya IoT con l’integrazione ufficiale Tuya che in rete locale col custom component Local Tuya per Home Assistant, nella mia guida passo passo completa in italiano incluso come recuperare le Tuya Local key.
Piattaforma Tuya Smart Life
Insieme a Sonoff / eWeLink e Shelly, Tuya Smart Life è sicuramente la piattaforma di domotica fai da te col maggior numero di produttori e dispositivi con firmware compatibile.
La piattaforma Tuya, dell’omonima azienda cinese, consente la gestione remota dei device nelle modalità seguenti:
- app Tuya Smart e Smart Life per smartphone Android e iOS
- comandi vocali mediante assistenti intelligenti Alexa e Google Home
L’architettura di un sistema di domotica Tuya Smart Life è basato sui componenti ed i flussi di comunicazione che ho rappresentato nel diagramma seguente:
Come si vede bene dallo schema, oltre ai dispositivi intelligenti compatibili Tuya Smart Life veri e propri, ci sono diversi elementi chiave per il corretto funzionamento del sistema:
- disponibilità e performance dei servizi cloud Tuya IoT
- connettività internet e router WiFi della nostra abitazione
- disponibilità di un eventuali hub gateway BLTE / Zigbee per i dispositivi Tuya Smart Life con tale tipologia di connettività
Come si intuisce abbastanza facilmente potrebbe bastare l’indisponibilità, anche solo temporanea, della nostra connessione ad internet o dei servizi cloud Tuya IoT perché i nostri dispositivi smart non siano più gestibili appieno e possano interagire tra di loro mediante scenari di automazione. Scenario alquanto fastidioso nel caso il problema si protragga per molte ore.
Alternative a Tuya Smart Life per gestire i dispositivi compatibili
Sicuramente l’utilizzo della piattaforma Tuya è sufficiente per la stragrande maggioranza degli utilizzatori “ordinari” ma pone sicuramente qualche vincolo nella modalità di gestione di un sistema di domotica Tuya Smart Life:
- disponibilità, performance e sicurezza connessione internet domestica e servizi cloud Tuya IoT
- impossibilità di collezione e visualizzazione dei dati misurati dai sensori ed i loro trend
- assenza di strumenti di gestione universali e compatibili con altre soluzioni di domotica (Shelly, Sonoff eWeLink, Philips Hue, Netatmo, Switchbot, etc)
Alcune delle soluzioni alternative più popolari sono valide ma non riescono a superare tutti i vincoli precedenti:
- Alexa, Google Home ed IFTTT che permettono di integrare sistemi di domotica eterogenei tramite i servizi in cloud eWeLink ma non hanno strumenti di gestione avanzate o raccolta dati
- Tasmota Tuya Convert: firmware alternativo che consente la gestione totalmente tramite rete locale dei dispositivi Tuya Smart Life ma è carente sotto tutti gli altri aspetti
Per fortuna ci vengono messere a disposizione delle modalità di gestione ed integrazione alternative che potrebbero far al caso nostro:
- La piattaforma Tuya IoT espone della API pubbliche per poter integrare applicazioni di terze parti tramite servizi in cloud
- I dispositivi intelligenti con firmare Tuya ITead prevedono anche delle API locali che consentono di gestire il dispositivo da un’applicazione terza direttamente tramite la rete locale, senza l’uso del cloud
Tutto questo ha reso possibile l’integrazione e la gestione dei dispositivi compatibili Tuya, con la più popolare piattaforma di domotica universale fai da te: Home Assistant.
Smart Life e Home Assistant: Tuya vs Local Tuya vs Tuya Local
Mettendo a fattor comune questa lunga introduzione, otteniamo il diagramma di funzionamento seguente in cui ai flussi di comunicazione di base tra app/web Tuya Smart Life ed Alexa/Google Home esclusivamente tramite i servizi cloud Tuya IoT via internet, si affiancano i nuovi flussi (in verde) tra Home Assistant, dispositivi e servizi cloud Tuya Smart Life:
- il server che ospita Home Assistant può comunicare direttamente con i dispositivi Tuya Smart Life tramite rete locale LAN / WiFi e le API locali
- in alternativa il server Home Assistant può comunque gestire i dispositivi Smart Life tramite la connessione internet ed i servizi cloud Tuya IoT
Per realizzare in pratica tutto questo, senza dover fare modifiche complicate e rischiose di firmware come quelle di Tasmota Tuya Convert, abbiamo due principali soluzioni possibili:
- integrazione ufficiale Tuya e Tuya v2 (beta non stabile) per Home Assistant che utilizza i servizi in cloud Tuya IoT
- Local Tuya custom component Home Assistant con accesso in locale; focalizzato su dispositivi complessi (termostati, stufette, purificatori aria, umidificatori)
- Tuya Local integrazione personalizzata Home Assistant con gestione in locale; copre bene dispositivi semplici come interruttori e luci smart
Prima di approfondirle in dettaglio qualche considerazione generale:
- in tutti i casi è necessario utilizzare le API pubbliche della piattaforma cloud Tuya IoT che vanno abilitate mediante la creazione e configurazione di un profilo
- Local Tuya e Tuya Local non sono palindromi: si tratta di due custom component Home Assistant distinti
- per la gestione in locale dei dispositivi con Home Assistant è fondamentale conoscerne la Tuya Local key che però va recuperata separatamente dal cloud
Configurazione piattaforma cloud Tuya IoT
Per gli scenari di integrazione di Tuya in Home Assistant che utilizzando i servizi cloud è necessario che disponiate di un vostro profilo a cui siano associati i vostri dispositivi sull’app Tuya Smart oppure sull’app Tuya Smart Life.
Per quanto possa sembra apparentemente bizzarro, il profilo su Tuya IoT Platform è diverso da quello delle app Tuya Smart / Smart Life che utilizzate per la gestione dei dispositivi da smartphone.
Occorre quindi configurare preliminarmente i servizi in cloud sulla piattaforma Tuya IoT:
Per farlo, accedete alla piattaforma Tuya IoT con le medesime credenziali con cui autenticate nell’app su smartphone accedendo alla vostra dashboard nella sezione Cloud:
Cliccate ora su Create Cloud Project per creare un nuovo progetto utilizzando questi parametri:
- Industry: Smart Home
- Development Method: Smart Home
- Data Center: Central Europe Data Center
Potete verificare la corrispondenza tra nazioni e data center Tuya IoT cloud: Italy (country code 39) è su Central Europe Data Center (AWS a Francoforte).
Nella finestra successiva dovrete aggiungere, oltre alle opzioni pre-impostate, anche Device Status Notification:
Cliccate su Authorize ed avrete così nella console il nuovo progetto appena creato. Per i passaggi successivi è necessario prendere nota delle credenziali relative alla vostra Authorization Key appena creata (Access ID/Client ID e Access Secret/Client Secret):
Dovete ora associare il vostro smartphone con l’app Tuya Smart o Tuya Smart Life installata al progetto Tuya IoT appena creato. Per farlo andate al tab Devices e poi su Link Tuya App Account:
Premendo sul pulsante Add App Account vi verrà mostrato un QRCode che dovrete inquadrare col vostro smartphone dalla sezione del vostro profilo dell’app Tuya Smart Life che utilizzate normalmente per gestire i vostri dispositivi:
Ora andate sul vostro smartphone ed effettuate il riconoscimento:
Il completamento del processo di configurazione è confermato sulla console di Tuya IoT platform dove è anche indicato il numero di dispositivi associati:
Integrazione ufficiale Tuya Smart Life su Home Assistant
L’integrazione ufficiale Tuya per Home Assistant è basata sull’utilizzo dei servizi cloud Tuya IoT.
Questo vuol dire che non migliorerete la resilienza rispetto a connettività internet e servizi in cloud ma la gestione dei dispositivi Tuya mediante Home Assistant vi garantirà comunque notevoli benefici:
- integrazione con dispositivi di altre piattaforme nell’ambiente unificato di Home Assistant
- funzioni avanzate di logging, monitoraggio ed archiviazione dei dati di Home Assistant
Al momento esistono due versioni dell’integrazione ufficiale Tuya Smart Life Home Assistant:
- Tuya: versione stabile
- Tuya
v2: versione beta non stabile e non più supportata
Dopo diverse peripezie col supporto tecnico di Tuya che hanno portato all’aggiornamento della documentazione ufficiale, raccomando l’utilizzo dell’integrazione Tuya Home Assistant in versione stabile. Tuya v2 non è più supportato.
Al fondo della mia guida passo passo troverete anche le istruzioni per Tuya v2.
Installazione e configurazione di Tuya Home Assistant per Smart Life
A questo punto accedete alla console di Home Assistant per la configurazione dell’integrazione Tuya.
Ora dovrete inserire rispettivamente Italy, la vostra Authorization Key Tuya IoT cloud ed infine le credenziali dell’app Smart Life:
Il successo dell’operazione sarà confermato dalla comparsa di una finestra che vi chiede conferma dei dispositivi rilevati:
Confermando, tutti i dispositivi Tuya Smart Life appariranno nella dashboard principale di Home Assistant:
Come amo dire, il gioco è fatto!
Installazione di Tuya v2 Home Assistant per Smart Life
Veniamo all’impresa di provare la versione beta del componente Tuya v2 per Home Assistant che però non è più supportato.
Assumiamo di disporre di un ambiente Home Assistant già pronto e configurato su cui installeremo Tuya v2. Se così non fosse fate riferimento alla guida ufficiale per l’installazione di Home Assistant.
E’ un pre-requisito fondamentale che Home Assistant utilizzi Python3.8 o il componente Tuya v2 non funzionerà.
Ci sono due possibilità per installare l’integrazione Tuya Home Assistant per Smart Life:
- Copiare manualmente il Custom component su Home Assistant
- Utilizzare HACS
Raccomando assolutamente di utilizzare HACS, puoi leggere la mia guida su come installare HACS su Home Assistant.
Copia manuale custom component Tuya v2 in Home Assistant
Scaricate il repository GitHub tuya-home-assistant all’interno del folder custom_components situato nella directory di configurazione di Home Assistant:
wget https://github.com/tuya/tuya-home-assistant/archive/refs/heads/master.zipNel caso di Home Assistant Core su Raspberry Pi potete installare Tuya v2 nel modo seguente:
sudo -u homeassistant -H -s
cd ~/.homeassistant
git clone https://github.com/tuya/tuya-home-assistant temp
cp -avr temp/custom_components/tuya_v2 custom_components/tuya_v2
rm -rf tempPotete usare la medesima sequenza di comandi anche in caso di aggiornamento del componente Tuya v2.
Se non fosse presente, è necessario installare preliminarmente git sul vostro Raspberry Pi:
sudo apt update
sudo apt install gitA questo punto facendo il riavvio del vostro ambiente Home Assistant all’interno delle Integrazioni troverete anche Tuya v2 tra quelle disponibili:
Installare Tuya v2 mediante Home Assistant Community Store (HACS)
L’alternativa che raccomando è quella di utilizzare HACS (Home Assistant Community Store) per effettuare l’installazione di Tuya.
Chiaramente in questo caso occorre aver effettuato preliminarmente l’installazione di HACS e la sua configurazione iniziale; se non lo avete ancora fatto leggete la mia guida come installare HACS su Home Assistant.
Dal menù di sinistra selezionate HACS, cliccate sull’icona in alto a destra selezionando poi Repository personalizzati:
A questo punto inserite come URL quella del repository GitHub del componente Tuya v2 https://github.com/tuya/tuya-home-assistant e come categoria Integrazione:
Confermando, il repository del componente Tuya v2 risulterà installabile in HACS:
A questo punto procedete con l’installazione di Tuya v2 in HACS:
Al termine avrete conferma dell’installazione del repository del componente Tuya v2 in HACS e verrete invitati a fare un restart di Home Assistant:
Dopo il restart il repository Tuya v2 risulta finalmente correttamente installato:
Potete ora passare all’aggiunta e configurazione della nuova integrazione Tuya v2 in Home Assistant.
Configurazione di Tuya v2 Home Assistant per Smart Life
A questo punto accedete alla console di Home Assistant per la configurazione dell’integrazione Tuya v2.
Come progetto cloud Tuya IoT lasciate Smart Home PaaS:
Ora dovrete inserire tutti i parametri per accedere al vostro profilo cloud Tuya creato in precedenza:
| Campo | Descrizione |
|---|---|
| ID di accesso | Access ID cloud Tuya IoT |
| Token segreto | Access Secret cloud Tuya IoT |
| Mobile App | Tuya Smart o Smart Life |
| Codice Paese | 39 |
| Account | Username app Tuya Smart o Smart Life |
| Password | Password app Tuya Smart o Smart Life |
Il successo dell’operazione sarà confermato dalla comparsa di una finestra che vi chiede conferma dei dispositivi rilevati:
Confermando, tutti i dispositivi Tuya Smart Life appariranno nella dashboard principale di Home Assistant:
Tuya Local key Home Assistant
I custom component Home Assistant che accedono solo tramite rete locale ai dispositivi Tuya necessitano di alcune informazioni identificative (in particolare la Tuya Local Key) che sono invece memorizzate nei servizi cloud della piattaforma Tuya IoT.
Quindi anche la configurazione con solo accesso locale di Home Assistant, il pre-requisito per recuperare la Tuya Local key è quello di disporre di un profilo sul cloud Tuya IoT a cui è stata associata l’app sul nostro smartphone (come già descritto in precedenza).
Potete trovare letteralmente milioni di modi di recuperare lae Tuya Local key per Home Assistant, tutti con complessità e tasso di successo discutibile. In diverse soluzioni si finisce con errore di accesso (1106): permission deny senza poterne uscire.
Il metodo più semplice da me identificato e provato con successo prevede di installare il package TinyTuya, che permette di interagire via Python con le API pubbliche Tuya e dispone già di diverse funzioni di supporto:
python -m pip install tinytuyaCompletata l’installazione di TinyTuya raccomando l’esecuzione della scansione della rete locale che permette di rilevare tutti i dispositivi intelligenti con firmare Tuya attivi:
python -m tinytuya scan
Come vedete le informazioni utili relative a ciascun dispositivo con firmware Tuya restituite dalla scansione di TinyTuya sono le seguenti e non includono la tanto desiderata Local Key che ci serve in Home Assistant::
- Product ID: identificativo unico del prodotto
- Device ID: identificativo di registrazione del dispositivo sul cloud Tuya IoT
- Versione API locali: 3.1 o 3.3
Possiamo ora finalmente lanciare il comando di avvio del wizard di recupero di tutte le Tuya Local key dei dispositivi registrati sul cloud Tuya IoT:
python -m tinytuya wizardCi verrà chiesto nell’ordine di inserire i dati seguenti:
- Authorization Key (API Key / API Secret) del cloud Tuya IoT
- Data center di riferimento (Central Europe Data Center per l’Italia)
- Device ID di uno qualsiasi dei dispositivi attivi identificati mediante la scansione della rete locale
Quasi come una magia, nessun errore di accesso (1106): permission deny, TinyTuya ci restituirà tutte le Tuya Local key insieme al nome del dispositivo, nonché farà la scansione dei dispositivi attivi sulla rete locale:
Tutte le Tuya Local key ritrovate sono anche salvate sul file devices.json. Anche le etichette dei dispositivi sono utili per riconoscergli rispetto a quanto presente in app Tuya Smart / Smart Life.
Se rilanciate nuovamente il comando di scansione della rete:
python -m tinytuya scan
Tutte queste informazioni sono anche salvate da TinyTuya sul file snapshot.json.
Otterrete questa volte informazioni complete tutto quello che vi servirà nella configurazione dei custom component Local Tuya e Tuya Local su Home Assistant:
- nome dispositivo
- indirizzo IP
- Tuya Device ID
- Tuya Local Key
Local Tuya custom component Home Assistant
Local Tuya è un’Integrazione personalizzata di Home Assistant per la gestione in locale di dispositivi smart compatibili Tuya.
Il custom component Local Tuya aggiorna lo stato dei dispositivi in modalità push: questo assicura che sia un’operazione molto rapida rispetto ad altri soluzioni in cui Home Assistant va invece in polling sui device.
Le tipologie di dispositivi supportati da Local Tuya è la seguente:
- interruttori smart con uno e più contatti
- prese smart
- lampadine
- ventilatori
- climatizzatori
Per i dispositivi compatibili Local Tuya supporta anche il monitoraggio dell’energia elettrica (tensione, corrente, potenza, ecc.).
Come vedete Local Tuya gestisce bene interruttori e lampadine, per dispositivi più complessi, come ad esempio termostati, suggerisco di considerare l’altro custom component Tuya Local.
La soluzione di Local Tuya su Home Assistant offre un significativo beneficio: in caso di problemi alla nostra connessione internet o ai servizi in cloud Tuya IoT continuerete a gestire i dispositivi tramite la rete locale:
Installazione Local Tuya su Home Assistant
Anche per il custom component Local Tuya abbiamo due possibilità di installazione su Home Asssistant:
- Copiare manualmente il custom component Local Tuya su Home Assistant
- Utilizzare HACS
Raccomando nuovamente la scelta dell’opzione Home Assistant Community Store, puoi leggere la mia guida su come installare HACS su Home Assistant.
Copia manuale componente Local Tuya in Home Assistant
Scaricate il repository GitHub Local Tuya all’interno del folder custom_components situato nella directory di configurazione di Home Assistant:
wget https://github.com/rospogrigio/localtuya/archive/refs/heads/master.zipNel caso di Home Assistant Core su Raspberry Pi potete installare Local Tuya nel modo seguente:
sudo -u homeassistant -H -s
cd ~/.homeassistant
git clone https://github.com/rospogrigio/localtuya temp
cp -avr temp/custom_components/localtuya custom_components/localtuya
rm -rf tempPotete usare la medesima sequenza di comandi anche in caso di aggiornamento del componente Local Tuya.
Se non fosse presente, è necessario installare preliminarmente git sul vostro Raspberry Pi:
sudo apt update
sudo apt install gitA questo punto facendo il riavvio del vostro ambiente Home Assistant:
exit
sudo systemctl restart home-assistant@homeassistant.serviceSe tutto è andato come previsto, all’interno delle Integrazioni in Home Assistant troverete anche Local Tuya tra quelle disponibili:
Selezionando Local Tuya si avvierà il processo di configurazione.
Installazione Local Tuya in Home Assistant con HACS
Utilizzando HACS la procedura di installazione di Local Tuya su Home Assistant è decisamente più semplice.
Dal menù di sinistra selezionate HACS e poi il tab Integrazioni, cliccate sull’icona in alto a destra ed infine su Repository personalizzati:
Inserite a questo punto il percorso del repository su GitHub https://github.com/rospogrigio/localtuya scegliendo come tipo Integrazione:
Confermando, il repository del componente Local Tuya risulterà ora installabile tramite HACS:
Procedete confermando il download del repository Local Tuya su Home Assistant tramite HACS. Ad operazione completata verrete invitati a fare un restart:
Completato il restart il componente Local Tuya risulta correttamente installato in HACS.
Configurazione Local Tuya in Home Assistant
Completata l’installazione potete andare a creare la nuova integrazione Local Tuya che scatenerà un wizard di configurazione iniziale:
Ricordatevi di chiudere l’app Smart Life sullo smartphone per ottenere un risultato attendibile.
Passato qualche secondo per il processo di scansione della rete locale, vi verrà mostrato l’elenco degli identificativi dei dispositivi compatibili Tuya trovati e la possibilità di aggiungerne manualmente:
Selezionandone uno, dovremo inserire un’etichetta, la local key e la versione delle API del dispositivo Tuya ritrovate in precedenza mediante TinyTuya:
Purtroppo Local Tuya non riconosce automaticamente il tipo di dispositivo per cui occorre inserirne i parametri in modo po’ “intuitivo”:
E’ anche possibile inserire manualmente la configurazione Local Tuya direttamente all’interno del file configuration.yaml di Home Assistant.
Tuya Local Home Assistant custom component
Anche Tuya Local è un componente aggiuntivo di Home Assistant per gestire i dispositivi con firmware Tuya senza passare tramite il cloud Tuya IoT.
L’utilizzo di questa integrazione non impedisce ai tuoi dispositivi continuare ad inviare il proprio stato al cloud Tuya IoT: è quindi da vedere come una soluzione per migliorare l’affidabilità complessiva ed addirittura poter accedere a funzioni specifiche di qualche dispositivo non supportate dalle API pubbliche.
Attualmente lo sviluppo di Tuya Local è focalizzato principalmente su dispositivi complessi (termostati, stufette, purificatori, umidificatori) che non sono ben supportati da altre integrazioni simili come Local Tuya che copre invece benissimo interruttori e luci.
Installazione Tuya Local su Home Assistant
Nel caso di Tuya Local è raccomandato utilizzare HACS per l’installazione.
Dal menù di sinistra selezionate HACS e poi il tab Integrazioni, cliccate sull’icona in alto a destra ed infine su Repository personalizzati:
Inserite a questo punto il percorso del repository su GitHub https://github.com/make-all/tuya-local scegliendo come tipo Integrazione:
Confermando, il repository del componente Tuya Local risulterà ora installabile tramite HACS:
Procedete confermando il download del repository Tuya Local su Home Assistant tramite HACS. Ad operazione completata verrete invitati a fare un restart:
Completato il restart il componente Tuya Local risulta correttamente installato in HACS.
Configurazione Tuya Local in Home Assistant
Completata l’installazione potete creare la nuova integrazione Tuya Local:
A questo punto verrà richiesto di inserire ID dispositivo, indirizzo IP e Tuya Local key ritrovati in precedenza mediante TinyTuya:
Inserendo ad esempio i dati del mio termostato WiFi, Tuya Local lo riconoscerà automaticamente come tale e mi verrà richiesto di confermare il modello specifico (Decdeal BHT-6000-GC):
Confermando il modello, Tuya Local mi richiederà di specificare le entità da associare al dispositivo:
Avreste mai detto che fosse possibile gestire in locale su Home Assistant il vostro termostato WiFi Smart Life grazie al custom component Tuya Local? E invece ci siamo riusciti:
Leggi tutti i miei articoli su Smart Life:
Ultimo aggiornamento Amazon Affiliate 2025-02-20 at 19:05
Alla data odierna tinytuya non effettua lo scan… quindi inutile
Ho appena installato l’applicazione per controllare i consumi di alcune prese ANTELA.
Avrei un paio di osservazioni.
– passando alla pagina dei consumi scompare dall’intestazione il nome della presa, col rischio di dimenticare di quale si tratta; e in un eventuale screenshot non è possibile documentare di che cosa si tratta; non dovrebbe essere difficile ripetere il nome della presa in tutte le schermate
– lo storico dei consumi giornalieri ha un fondo scala di 12 kWh, eccessivo per la maggior parte delle singole utenze, e che rende poco leggibili i grafici; non è possibile regolare il fondo scala, assegnandone ad ogni utenza uno appropriato ?
Ho questo tipo di wakeup light, con funzione di sveglia, radio etc…
https://www.amazon.it/gp/product/B07MJ5DP2R
ho provato sia la procedura web che local, purtroppo viene vista solo ed esclusivamente come lampadina, senza poter cambiare nemmeno colore. Qualcuno ha qualche suggerimento su come poterla integrare su home assistant con le tutte le funzioni che ho nell’app Tuya oppure SmartLife ??
Ciao Sandro,
la tipologia di dispositivo deve essere supportato dall’integrazione Tuya per Home Assistant.
Vista la particolarità del dispositivo sono scettico accada a breve.
Potresti fare una richiesta di Enhancement su Github ma banalmente qualcuno dovrebbe possedere quel dispositivo.
Questo è il mondo dell’Open Source!