Smart home

Tuya lokalnie w Home Assistant: Tuya Local, LocalTuya czy chmura

Oficjalna integracja Tuya w Home Assistant działa przez chmurę Tuya: logujesz się kodem użytkownika (User Code) i kodem QR zeskanowanym w aplikacji Smart Life lub Tuya Smart, a sterowanie wymaga internetu. Lokalnie, bez pośrednictwa chmury, urządzenia Tuya Wi-Fi obsługują integracje z HACS, czyli Tuya Local i LocalTuya. Potrzebują one klucza lokalnego urządzenia (local key) i nie obsługują każdego modelu. Urządzenia Tuya na Zigbee nie potrzebują chmury wcale: wystarczy koordynator i ZHA albo Zigbee2MQTT.

Poniżej opis wszystkich trzech dróg według dokumentacji Home Assistant i repozytoriów projektów, stan na 25.10.2026: Home Assistant 2026.10.4, Tuya Local 2026.10.0, LocalTuya v5.2.5 i jej fork hass-localtuya 2026.10.0. Nie obiecujemy, że konkretne urządzenie zadziała: to zależy od modelu i oprogramowania, które ma w środku.

Spis treści 14
  1. Jak działa oficjalna integracja Tuya w Home Assistant?
    1. Dlaczego urządzenie jest „nieobsługiwane” albo nie ma wszystkich funkcji?
  2. Co znaczy „Please use the designated app to scan the code to log in”?
  3. Jak sterować urządzeniami Tuya lokalnie, bez chmury?
  4. Skąd wziąć local key urządzenia Tuya?
    1. Kreator Tuya Local z logowaniem aplikacją
    2. Platforma deweloperska Tuya (iot.tuya.com)
    3. LocalTuya z kontem Cloud API i tinytuya
  5. Która wersja protokołu: 3.3, 3.4 czy 3.5?
  6. Tuya Local czy LocalTuya: co wybrać?
  7. Czy lepiej kupić Tuya Zigbee niż Tuya Wi-Fi?
  8. Co zrobić, gdy urządzenia Tuya są offline albo nie działają?
  9. Najczęstsze pytania
  10. Źródła

Jak działa oficjalna integracja Tuya w Home Assistant?

Integracja Tuya jest wbudowana w Home Assistant. Według dokumentacji obejmuje wszystkie urządzenia „Powered by Tuya” dodane do aplikacji Tuya Smart i Smart Life i obsługuje wszystkie platformy Home Assistant oprócz zamków (lock) i pilotów (remote). Jej klasa to Cloud Push: stan urządzeń przychodzi z chmury Tuya. Strona integracji podaje, że korzysta z niej 29,5% aktywnych instalacji Home Assistant.

Do konfiguracji potrzebujesz konta w aplikacji Smart Life lub Tuya Smart z co najmniej jednym urządzeniem, telefonu z tą aplikacją i drugiego ekranu, na którym Home Assistant wyświetli kod QR.

  1. W aplikacji otwórz kartę „Ja” (w angielskiej wersji Me), wybierz ikonę zębatki w prawym górnym rogu, potem „Konto i bezpieczeństwo” (Account and Security). Na dole jest User Code.
  2. W Home Assistant wybierz Ustawienia → Urządzenia i usługi → Dodaj integrację → Tuya i wpisz User Code.
  3. W aplikacji Smart Life naciśnij „+” albo „Dodaj urządzenie”, wybierz skaner kodów i zeskanuj kod QR z ekranu Home Assistant.

Nazwy menu w polskiej wersji aplikacji mogą się nieco różnić, dokumentacja podaje je po angielsku. Po dodaniu nowych urządzeń w aplikacji integrację trzeba przeładować (Urządzenia i usługi → Tuya → menu z trzema kropkami → Przeładuj). Sceny utworzone w aplikacji Tuya pojawiają się w Home Assistant same przy kolejnej aktualizacji integracji.

Lista obsługiwanych kategorii rośnie z wydaniami. Home Assistant 2026.9 dodał kategorię taśm LED z efektem „chasing” (lista zmian 2026.9), a 2026.10 dwukanałowe liczniki energii na szynę DIN, wyłączniki, ładowarki samochodów elektrycznych i zawory wody. Trójfazowe liczniki raportują teraz moc bierną, pozorną i współczynnik mocy dla każdej fazy (lista zmian 2026.10).

Dlaczego urządzenie jest „nieobsługiwane” albo nie ma wszystkich funkcji?

Integracja korzysta z oficjalnego SDK Tuya, które według dokumentacji nie udostępnia wszystkich funkcji aplikacji Smart Life. Sprawdzisz to w diagnostyce: Urządzenia i usługi → Tuya → urządzenie → menu z trzema kropkami → Pobierz diagnostykę. W pliku zobacz klucze status, status_range i function. Jeśli wszystkie trzy są puste, w Home Assistant będą dostępne tylko sceny zdefiniowane w Tuya.

Drugi znany problem to prośba o ponowne logowanie po każdym przeładowaniu. Dokumentacja wiąże ją ze zmianą regulaminu platformy iot.tuya.com: trzeba się tam zalogować, zaakceptować warunki, uruchomić ponownie Home Assistant i skonfigurować integrację od nowa.

Co znaczy „Please use the designated app to scan the code to log in”?

Ten komunikat pojawia się w aplikacji przy skanowaniu kodu QR z Home Assistant. Dokumentacja Home Assistant go nie opisuje (stan na 25.10.2026), więc opieramy się na zgłoszeniach użytkowników na GitHubie. W zgłoszeniu #120619 (czerwiec 2024) błąd wystąpił przy aplikacji Resun, a w komentarzach także przy innych aplikacjach markowych opartych na Tuya. Podobny przypadek z aplikacją ELESION opisuje zgłoszenie #751 w repozytorium Tuya.

Typowa przyczyna to skanowanie kodu aplikacją innej marki, zbudowaną na platformie Tuya, zamiast Smart Life lub Tuya Smart. W tym samym wątku jeden z użytkowników napisał, że pomogło dodanie urządzenia w aplikacji Tuya Smart i zeskanowanie kodu tą aplikacją. Kilka osób zgłaszało jednak ten sam błąd także w samej aplikacji Smart Life, a zgłoszenie zamknięto w październiku 2025 bez opisanej poprawki.

  • Jeśli urządzenie da się dodać do Smart Life lub Tuya Smart, przenieś je tam i skanuj kod tą aplikacją.
  • Jeśli producent wymaga własnej aplikacji, oficjalna integracja może nie zadziałać. Zostaje droga lokalna z dalszej części tekstu.
  • Autorzy Tuya Local ostrzegają, że po przeniesieniu do aplikacji Tuya część urządzeń może stracić funkcje dostępne w aplikacji producenta, np. mapy niektórych odkurzaczy (DEVICE_DETAILS.md).

Jak sterować urządzeniami Tuya lokalnie, bez chmury?

Urządzenia Tuya Wi-Fi mają w oprogramowaniu lokalny protokół: Home Assistant może łączyć się z nimi bezpośrednio w sieci domowej, jeśli zna cztery dane. Są to adres IP urządzenia, jego identyfikator (device_id), klucz lokalny (local_key) i wersja protokołu. Obsługują to integracje instalowane przez HACS: Tuya Local oraz LocalTuya i jej fork hass-localtuya.

Sterowanie lokalne nie odcina urządzenia od chmury

README Tuya Local mówi wprost, że integracja nie zatrzymuje wysyłania stanu urządzenia do chmury Tuya i nie należy jej traktować jako zabezpieczenia. Zyskujesz szybkość i niezawodność, a czasem funkcje niedostępne w API chmury.

Trzy zasady, o których mówią oba projekty:

  • Jedno połączenie lokalne. Według README Tuya Local wiele urządzeń Tuya przyjmuje tylko jedno połączenie lokalne. Zamknij aplikację Tuya na telefonie w tej samej sieci i nie dodawaj tego samego urządzenia do dwóch integracji lokalnych. LocalTuya zaleca zamknięcie aplikacji podczas dodawania urządzenia.
  • Stały adres IP. Tuya Local pozwala wpisać „Auto” zamiast IP, ale wykrywanie zawodzi, gdy działa LocalTuya, aplikacja jest połączona lokalnie albo sieć ma kilka podsieci. Lepiej przypisać urządzeniu stały adres w routerze.
  • Blokada internetu z głową. README LocalTuya ostrzega, że jeśli blokujesz urządzeniom dostęp do internetu, trzeba zablokować także zapytania DNS do lokalnego serwera. Inaczej urządzenie przechodzi w „stan zombie” i odrzuca połączenia z kluczem lokalnym. Klucze pobierz, zanim wprowadzisz blokadę.

Urządzenia IoT warto trzymać w osobnej sieci, np. sieci gości albo VLAN. Ogólne zasady opisaliśmy przy okazji cyberbezpieczeństwa falownika, a obowiązują one także gniazdka i przekaźniki Wi-Fi.

Skąd wziąć local key urządzenia Tuya?

Klucz lokalny pobierasz z konta Tuya, na którym jest urządzenie. Korzystaj tylko z oficjalnej platformy Tuya albo z kreatora integracji. Narzędzia z hasłem „local key extractor”, zmodyfikowane aplikacje i zmiana oprogramowania urządzenia wychodzą poza ten poradnik i niosą ryzyko dla bezpieczeństwa.

Kreator Tuya Local z logowaniem aplikacją

Najprostsza droga. W kreatorze Tuya Local logujesz się aplikacją Tuya Smart lub Smart Life, wybierasz urządzenie z listy, a device_id i local_key wypełniają się same; adres IP także, jeśli wykrywanie w sieci nie jest blokowane. Według README nie potrzebujesz konta deweloperskiego Tuya. Token logowania wygasa po kilku godzinach i nie jest zapisywany, ale do restartu Home Assistant możesz dodać kolejne urządzenia bez ponownego logowania.

Platforma deweloperska Tuya (iot.tuya.com)

Klasyczna droga opisana w DEVICE_DETAILS.md Tuya Local: projekt chmurowy z połączonym kontem aplikacji, w sekcji Cloud lista urządzeń z Device ID, potem API Explorer → Devices Management → Query Device Details in Bulk. W wyniku jest local_key. Działa tylko z markowymi aplikacjami Tuya Smart lub Smart Life.

Ta droga staje się mniej wygodna. Według autorów Tuya Local Tuya ograniczyła dostęp do kluczowej funkcji danych na platformie do miesiąca, z możliwością odnowienia okresu próbnego co 6 miesięcy. README biblioteki tinytuya opisuje to podobnie: bezpłatna subskrypcja IoT Core wygasa po miesiącu i trzeba ją przedłużać. Na stronie Tuya tych warunków nie sprawdziliśmy, więc starsze poradniki „wejdź na iot.tuya.com” mogą być nieaktualne.

LocalTuya z kontem Cloud API i tinytuya

LocalTuya może sama pobierać klucze, jeśli podasz Client ID, Client Secret i User ID projektu z platformy Tuya. README nazywa to opcją nieobowiązkową, ale zalecaną: integracja pobiera wtedy i aktualizuje klucze po ponownym parowaniu urządzenia, łącząc się z chmurą tylko przy starcie i przy potrzebie zmiany klucza. Projekt musi być utworzony po 25 maja 2021 r. Dla zaawansowanych jest też polecenie python -m tinytuya wizard z biblioteki tinytuya (wydanie v1.20.0), które korzysta z tych samych danych API platformy.

Klucz zmienia się przy ponownym parowaniu

Każde ponowne sparowanie urządzenia w aplikacji zmienia local key (README Tuya Local i tinytuya). Traktuj klucz jak hasło: nie wklejaj go na forach ani do zrzutów ekranu.

Która wersja protokołu: 3.3, 3.4 czy 3.5?

Urządzenia Tuya używają różnych wersji lokalnego protokołu. Biblioteka tinytuya, na której opiera się Tuya Local, obsługuje wersje 3.1, 3.2, 3.3, 3.4 i 3.5. W Tuya Local pole protocol_version przyjmuje wartości auto, 3.1, 3.2, 3.3, 3.4, 3.5 oraz 3.22, czyli specjalny wariant 3.3 dla tzw. urządzeń „device22”.

  • Jeśli nie wiesz, wybierz „auto”. Według README część urządzeń 3.2, 3.22 i być może 3.4 bywa wykrywana jako 3.3 (lub odwrotnie). Gdy urządzenie niestabilnie reaguje na polecenia, wybierz wersję ręcznie.
  • Przy wersji 3.1 zły klucz wyjdzie dopiero przy próbie sterowania, bo klucz służy tylko do wysyłania poleceń. Od nowszych wersji błąd klucza widać od razu przy konfiguracji.
  • Oryginalna LocalTuya deklaruje obsługę protokołów od 3.1 do 3.4. Fork hass-localtuya ma na liście wersje 3.1–3.5 (const.py).

Są też urządzenia, których lokalnie nie obsłużysz. Według README Tuya Local czujniki bateryjne bez huba, np. otwarcia drzwi czy dymu, nie utrzymują połączenia Wi-Fi ze względu na oszczędzanie baterii. Huby Tuya są obsługiwane z ograniczeniami: każde pod-urządzenie to osobne połączenie sieciowe, a hub przyjmuje zwykle 1 albo 3 połączenia. Niektóre huby Tuya obsługują Matter over Wi-Fi, co jest alternatywą z własnymi ograniczeniami.

Tuya Local czy LocalTuya: co wybrać?

Tuya Local ma gotowe profile urządzeń. Jeśli twój model jest na liście, konfiguracja sprowadza się do wybrania go z kreatora. LocalTuya wymaga ręcznego przypisania punktów danych (DP) do encji, co daje więcej swobody przy urządzeniach spoza list, ale wymaga więcej pracy. Sama Tuya Local wskazuje LocalTuya i jej nowsze forki jako alternatywę, gdy urządzenia nie ma na liście.

CechaTuya (wbudowana)Tuya LocalLocalTuyahass-localtuya
Połączeniechmura (Cloud Push)lokalnie (Wi-Fi)lokalnie; chmura tylko do kluczylokalnie; chmura tylko do konfiguracji
Instalacjawbudowana w Home AssistantHACS, repozytorium niestandardoweHACS, domyślny katalogHACS, repozytorium niestandardowe
KonfiguracjaUser Code + kod QRkreator z logowaniem aplikacją albo ręczniekreator w interfejsie (YAML nieobsługiwany od v4.0.0), opcjonalnie Cloud APIkreator, automatyczna konfiguracja z Cloud API
Urządzeniawedług SDK Tuyaponad 1000 gotowych profili (lista DEVICES.md)dowolne przez ręczne DPdowolne przez DP, pod-urządzenia bramek, piloty IR
Protokoły lokalnenie dotyczy3.1–3.5 i 3.223.1–3.43.1–3.5
Ostatnie wydanie2026.10.4 (24.10.2026)2026.10.0 (23.10.2026)v5.2.5 (29.01.2026)2026.10.0 (19.10.2026)
LicencjaApache-2.0MITGPL-3.0GPL-3.0

Źródło: home-assistant.io (integracja Tuya), README i wydania repozytoriów make-all/tuya-local, rospogrigio/localtuya, xZetsubou/hass-localtuya, home-assistant/core oraz lista hacs/default (GitHub), dostęp 25.10.2026.

Przed instalacją sprawdź datę ostatniego wydania: oryginalna LocalTuya nie miała nowego wydania od stycznia 2026, a Tuya Local i fork hass-localtuya wydały nowe wersje w październiku 2026. Obecność modelu na liście Tuya Local też nie daje gwarancji. README zaznacza, że pod tą samą nazwą bywają sprzedawane wersje z innym oprogramowaniem. W katalogu HACS jest jeszcze xtend_tuya, które według README dodaje encje brakujące w oficjalnej integracji (m.in. dla panelu Energia); README nie opisuje sterowania lokalnego.

Czy lepiej kupić Tuya Zigbee niż Tuya Wi-Fi?

Jeśli zależy ci na pracy bez chmury, Zigbee jest prostsze. README Tuya Local zauważa, że urządzenia Tuya Zigbee to zwykle standardowe urządzenia Zigbee, więc zamiast huba Tuya możesz użyć koordynatora z ZHA albo Zigbee2MQTT. Nie potrzebujesz wtedy local key ani konta Tuya.

Haczyk to niestandardowe urządzenia Tuya. Według dokumentacji Zigbee2MQTT korzystają one z własnego klastra Tuya i punktów danych, a wiele modeli ma to samo oznaczenie (np. TS0601). Rozpoznaje się je dopiero po parze modelu i nazwy producenta, np. _TZE200_…. ZHA obsługuje je przez quirki z projektu zha-device-handlers. Różnice między integracjami opisaliśmy w porównaniu Zigbee2MQTT czy ZHA, a wybór radia w poradniku jaki koordynator Zigbee wybrać.

Urządzenie Zigbee należy tylko do jednej sieci (FAQ Zigbee2MQTT). Jeśli jest sparowane z bramką Tuya, zresetuj je i sparuj z koordynatorem Home Assistant. Bramki Tuya Wi-Fi/Zigbee to bramki chmurowe, a nie koordynatory dla ZHA czy Zigbee2MQTT; z Tuya Local działają jako hub z limitem połączeń opisanym wyżej.

Krótka reguła wyboru

Kupujesz nowe urządzenie: Tuya Zigbee, które sprawdzisz wcześniej na liście Zigbee2MQTT. Masz już Tuya Wi-Fi: najpierw Tuya Local, potem LocalTuya lub jej fork. Oficjalna integracja wystarczy, gdy akceptujesz pracę przez chmurę.

Co zrobić, gdy urządzenia Tuya są offline albo nie działają?

Lista kontrolna według dokumentacji Home Assistant i README projektów:

  • Oficjalna integracja: pobierz diagnostykę i sprawdź, czy status, status_range i function nie są puste.
  • Oficjalna integracja: po dodaniu urządzenia w aplikacji przeładuj integrację w Home Assistant.
  • Ciągłe ponowne logowanie: zaakceptuj nowy regulamin na iot.tuya.com, uruchom ponownie Home Assistant i skonfiguruj integrację.
  • Integracja lokalna: zamknij aplikację Tuya na telefonie i usuń urządzenie z drugiej integracji lokalnej.
  • Sprawdź, czy urządzenie nie zmieniło adresu IP; ustaw stały adres w routerze.
  • Po ponownym parowaniu w aplikacji pobierz nowy local key.
  • Przy niestabilnym sterowaniu zmień ręcznie wersję protokołu (3.3, 3.4, 3.5; niekiedy 3.2).
  • Blokujesz internet urządzeniom: blokuj też DNS. Według Tuya Local wiele urządzeń Tuya przestaje odpowiadać, gdy długo nie może połączyć się z serwerami Tuya, a niektóre zachowują się lepiej, gdy zablokowany jest i DNS, i TCP.
  • Seria szybkich poleceń z automatyzacji: dodaj opóźnienia. README Tuya Local opisuje urządzenia, które po przeciążeniu restartują się albo znikają z sieci na 30 sekund do kilku minut.

Gniazdka i przekaźniki Tuya to częsty element domowej automatyki energii, np. gniazdko z pomiarem energii w panelu Energia albo grzałka bojlera włączana z nadwyżki fotowoltaiki. Przekaźniki dopuszkowe 230 V powinna montować osoba z uprawnieniami (świadectwo kwalifikacyjne według rozporządzenia z 1 lipca 2022 r., Dz.U. 2022 poz. 1392). Smarting HOME FREE może grzać bojler z nadwyżki PV przez gniazdko lub przekaźnik smart; opis funkcji jest na stronie Smarting HOME HEMS.

Sprzęt do tego poradnika w naszym sklepie

Więcej: Gniazdka, włączniki i przekaźniki →

Najczęstsze pytania

Czy Tuya działa w Home Assistant bez chmury?

Oficjalna integracja Tuya działa przez chmurę Tuya i wymaga internetu. Lokalnie urządzenia Wi-Fi obsługują integracje z HACS, np. Tuya Local lub LocalTuya, które potrzebują klucza local key. Urządzenia Tuya na Zigbee działają bez chmury przez koordynator i ZHA lub Zigbee2MQTT.

Co oznacza komunikat „Please use the designated app to scan the code”?

Najczęściej to, że kod QR z Home Assistant zeskanowano aplikacją innej marki zbudowaną na Tuya, a integracja oczekuje Smart Life lub Tuya Smart. Użytkownicy na GitHubie piszą, że pomaga dodanie urządzenia do jednej z tych aplikacji i skanowanie w niej. Błąd zgłaszano jednak także w samej aplikacji Smart Life.

Jak zdobyć local key urządzenia Tuya?

Najprościej w kreatorze Tuya Local, logując się aplikacją Tuya Smart lub Smart Life, bez konta deweloperskiego. Druga droga to projekt na platformie iot.tuya.com i funkcja Query Device Details in Bulk w API Explorer. Klucz zmienia się po każdym ponownym sparowaniu urządzenia.

Tuya Local czy LocalTuya: co wybrać?

Tuya Local ma ponad 1000 gotowych profili urządzeń i obsługuje protokoły do 3.5, więc jest prostsza, jeśli twój model jest na liście. LocalTuya wymaga ręcznego przypisania punktów danych, ale obsłuży urządzenia spoza list. Oryginał obsługuje protokoły do 3.4, fork hass-localtuya do 3.5.

Dlaczego urządzenie Tuya nie łączy się lokalnie?

Najczęstsze przyczyny to otwarta aplikacja na telefonie lub druga integracja zajmująca jedyne połączenie lokalne, nieaktualny local key po ponownym parowaniu, zła wersja protokołu albo zmieniony adres IP. Czujników bateryjnych bez huba nie da się obsłużyć lokalnie.

Źródła

Autor

Twórca integracji Smarting HOME dla Home Assistant.

Dyskusja

Pytania i komentarze

Masz pytanie o integrację, falownik, magazyn albo rozliczenie? Napisz model urządzenia, wersję integracji i co dokładnie się dzieje. Odpowiada autor, Grzegorz Ciupek, a odpowiedź zostaje tu dla kolejnych osób.

    Jeszcze nikt nie zapytał. Coś nie działa albo nie pasuje do Twojej instalacji? Zapytaj, odpowiedź przyda się też innym.

    Zadaj pytanie albo dodaj komentarz

    Nie wklejaj kluczy ani haseł. Klucza licencji, tokenu Home Assistant, haseł do falownika, chmury producenta ani publicznego adresu swojej instalacji nie podawaj tu nigdy. Nikt z nas nie poprosi o nie w komentarzu.

    Bez reklam i linków polecających. Komentarze z numerami telefonów, kodami polecającymi albo kilkoma linkami czekają na moderatora. Zasady dyskusji

    Co napisać, żeby dostać konkretną odpowiedź?

    Model falownika i magazynu (np. GoodWe ET 10 kW, Lynx Home F), sposób połączenia (Modbus, chmura), wersję integracji Smarting HOME i Home Assistant, taryfę (G11, G12, dynamiczna) oraz co dokładnie widzisz: nazwę encji, komunikat, godzinę. Zrzut ekranu opisz słowami, załączników tu nie ma.

    Zgłoś komentarz

    Powód