Come configurare Tuya Local per controllare i dispositivi Tuya senza cloud

Tuya Local è un’integrazione custom di Home Assistant che prova a comunicare direttamente con dispositivi basati su Tuya, senza usare il cloud durante il controllo quotidiano. Non va confusa con l’integrazione ufficiale Tuya, che usa il servizio cloud, né con il marchio hardware: Tuya è la piattaforma/firmware, Tuya Local è software comunitario. Compatibilità, protocollo e datapoint dipendono dal modello specifico.

Prerequisiti & Hardware Necessario

• Dispositivo Tuya o Smart Life supportato dal repository Tuya Local, collegato alla stessa rete IP di Home Assistant.
• Home Assistant con HACS già funzionante e accesso amministrativo.
• Indirizzo IP riservato del dispositivo, device_id e local_key. La chiave locale non è la password dell’app e non deve essere pubblicata.
• Account Tuya IoT Platform e app Tuya Smart/Smart Life, quando necessari per recuperare ID e chiave; i passaggi di collegamento cambiano per regione e tipo di account.
• Nessun link d’acquisto: il dispositivo deve essere già posseduto e compatibile; non tutti i prodotti Tuya espongono un controllo locale.

Procedura passo-passo

1. Identifica esattamente il dispositivo. Annota marca commerciale, modello, app usata, categoria e firmware. Due prodotti esteticamente uguali possono avere datapoint o firmware diversi. Cerca il modello nell’elenco di dispositivi supportati del repository Tuya Local prima di procedere.
2. Riserva l’indirizzo IP. Nel router crea una prenotazione DHCP, per esempio 192.168.1.60. Tuya Local comunica con l’IP locale: se cambia, l’integrazione può risultare non disponibile.
3. Installa Tuya Local da HACS. Apri HACS, cerca Tuya Local e installa la repository del progetto make-all/tuya-local. Se non compare, aggiungila come repository custom di tipo Integration, usando l’URL ufficiale del repository e la procedura HACS. Non installare contemporaneamente fork diversi chiamati LocalTuya/Tuya Local: possono creare componenti duplicati e conflitti.
4. Riavvia Home Assistant. Dopo l’installazione riavvia Home Assistant e controlla che non ci siano errori in Impostazioni → Sistema → Registri. Un’integrazione custom viene salvata nella directory custom_components della configurazione, ma non va modificata manualmente durante la prima installazione.
5. Recupera device ID e local key. Usa il percorso documentato dal repository e dalla piattaforma Tuya IoT per collegare il progetto all’account Tuya Smart/Smart Life e visualizzare il dispositivo. Copia device_id e local_key in un gestore password. Il valore può cambiare dopo un reset o una nuova associazione del dispositivo.
6. Configura l’integrazione. In Home Assistant apri Impostazioni → Dispositivi e servizi → Aggiungi integrazione, cerca Tuya Local e inserisci IP, device ID, local key e protocollo richiesti. Se il repository propone più versioni, seleziona quella indicata dal dispositivo o dalla documentazione; non indovinare 3.3, 3.4 o 3.5.
7. Configura i datapoint. Seleziona la piattaforma corretta, per esempio switch, light, climate o sensor, e associa i DP ID alle funzioni del dispositivo. I DP ID non sono universali: 1 può rappresentare un interruttore in un modello e una modalità in un altro. Usa lo schema del dispositivo o il rilevamento del repository.
8. Salva e assegna l’area. Dai al dispositivo un nome stabile, assegna stanza e disabilita solo le entità che hai verificato essere inutili. Non rinominare i datapoint finché non hai confermato che lo stato e il comando sono corretti.
9. Testa il controllo locale. Blocca temporaneamente l’accesso Internet del dispositivo dal router, lasciando attiva la LAN. Comanda il dispositivo da Home Assistant e verifica il ritorno di stato. Se funziona senza Internet, il percorso è locale; se smette di funzionare, non significa necessariamente che la configurazione sia errata: il modello può dipendere dal cloud.
10. Proteggi le credenziali. Tratta local key, device ID e token Tuya come segreti. Non inserirli in screenshot, repository o automazioni condivise. Limita il dispositivo alla VLAN IoT e consenti Home Assistant verso il suo IP e le porte richieste dall’integrazione.
11. Gestisci gli aggiornamenti. Prima di aggiornare Home Assistant o Tuya Local crea un backup. Dopo l’aggiornamento verifica entità, datapoint e controllo locale; una custom integration può richiedere adattamenti dopo modifiche del core o del firmware Tuya.

Verifica del funzionamento

1. Controlla che il dispositivo risponda all’IP riservato sulla LAN.
2. In Home Assistant verifica che l’integrazione Tuya Local sia caricata senza errori e che tutte le entità attese siano disponibili.
3. Invia un comando e controlla stato, log e tempo di risposta.
4. Riavvia Home Assistant: l’integrazione deve riconnettersi senza una nuova configurazione.
5. Ripeti il test senza Internet, se il modello dovrebbe supportare il controllo locale, e riapri l’accesso cloud solo dopo aver completato la verifica.

Problemi comuni

FAQ essenziali

Tuya Local elimina l’account Tuya?

No. Per alcuni modelli servono comunque app e piattaforma Tuya per onboarding, recupero di ID/chiave o aggiornamenti. Il controllo dopo la configurazione può però avvenire localmente, se il dispositivo lo supporta.

Tuya Local è un’integrazione ufficiale Home Assistant?

No. È una custom integration comunitaria installata tramite HACS. Tieni backup, repository e compatibilità sotto controllo prima di aggiornare Home Assistant.