Najczęstsze pytania i odpowiedzi [bramka ZigBee]

[vajera]

1. "Wgrałem oprogramowanie do bramki i skonfigurowałem dane Supla. W Cloud widzę bramkę wraz z jednym kanałem przekaźnika Gateway sensors notifications - do czego on służy i jak mam dodać nowe urządzenie Zigbee do bramki?"
   
   Odpowiedź:
   • Kanał Gateway sensors notifications jest elementem tzw. powiadomień lokalnych - więcej tutaj
     
   • Instrukcja parowania nowych urządzeń dostępna jest tutaj.
   ‎
2. "Odłączyłem urządzenie Zigbee od sieci a w aplikacji Supla nadal jest online?"
   
   Odpowiedź: viewtopic.php?t=16908 - wszystkie opisane tam parametry można ustawić z poziomu GUI lub w konsoli (Telnet).
   
   ‎
3. "Dodałem do bramki nowe urządzenie Zigbee, ale nie pojawiają się odczyty danych, ewentualnie pojawiają się zbyt rzadko?"
   
   Odpowiedź:
   
   • Tutaj podstawowe pojęcia (jeżeli wiesz co to endpoint, klaster i atrybut możesz pominąć ten punkt).
   • Tutaj omówienie tzw. raportowania konfiguracji (GUI, konsola), dzięki któremu możemy wymusić na urządzeniu Zigbee wysyłanie swojego stanu w zadanych odstępach czasu (np. co 30 sekund) lub przy określonej wielkości zmiany danego parametru (np. spadek poziomu baterii o 1%).
   • Niektóre liczniki energii elektrycznej (zwłaszcza Tuya) ignorują powyższe ustawienia raportowania - wtedy z pomocą przychodzi parametr refresh - więcej szczegółów tutaj.
   ‎
4. "Dodałem do bramki nowe urządzenie Zigbee, kanały są widoczne w Cloud/aplikacji, ale nie ma komunikacji z urządzeniem - nie przesyła żadnych danych, nie reaguje na polecenia?"
   
   Odpowiedź:
   
   • Proponuję zacząć od tzw. standardowej procedury reanimacji - opisanej w pkt. 4 Aa.

[vajera]

Na początek trochę podstaw dotyczących standardu Zigbee i komunikacji z urządzeniami końcowymi (ZED).

Urządzenia Supla składają się z kanałów (channels), np. kanał przekaźnika, dimmera lub temperatury.

W przypadku urządzeń Zigbee podstawową jednostką jest klaster (cluster), który realizuje konkretny zestaw funkcji, np. klaster OnOff służy do włączania/wyłączania.

Specyfikacja Zigbee zawiera kilkadziesiąt standardowych klastrów, wprowadza też możliwość definiowania tzw. custom clusters, z czego chętnie korzystają producenci z Tuya na czele.

Każdy klaster zdefiniowany w specyfikacji Zigbee ma swoją nazwę (np. OnOff), przypisany identyfikator (np. 0x0006) oraz zestaw tzw. atrybutów i rozkazów.

Atrybuty danego klastra służą do raportowania parametrów oraz do modyfikacji ustawień.

Atrybuty mają przypisane konkretne identyfikatory, typ danych (np. BOOL, S16) oraz sposób interpretacji wartości danego atrybutu.

Przykład nr 1

klaster: 0x402 (TEMPERATURE MEASUREMENT)
atrybut: 0x00 (TEMPERATURE)
typ danych: S16 (16 bitowa liczba ze znakiem)
wartość atrybutu: temperatura * 100, np. 2150 = 21,50°C

Atrybuty mogą być tylko do odczytu (np. temperatura), lub do odczytu i zapisu, mogą też mieć status reportable - taki atrybut można skonfigurować do regularnego raportowania przez urządzenie za pomocą funkcji configure-reporting.

Każdy klaster oprócz atrybutów posiada też zestaw rozkazów, które mogą mieć dodatkowe parametry.

Przykład nr 2

klaster: 0x0006 (ONOFF)
atrybut 0x00 (BOOL): określa stan Off(0), On(1)
próba zapisu do tego atrybutu zakończy się niepowodzeniem - w celu zmiany stanu wyłącznika wysyłamy rozkaz 0x00 (Off), 0x01(On), 0x02(Toggle)

Podsumowując - mamy kilkanaście najczęściej używanych klastrów, z których każdy ma własny zestaw atrybutów i rozkazów służących do odczytu danych klastra i ustawiana jego parametrów.
Podstawą konfiguracji dowolnego urządzenia jest więc znajomość wystawianych przez nie klastrów i dostępnych atrybutów.

Powyższy opis to jasna strona mocy (Jedi), ale oczywiście równowaga musi zostać zachowana, więc jest i ciemna strona (Sithowie tfu Tuya ).

Tuya wprowadziła swój własny system oparty o klaster 0xEF00, rozkaz 0x00 i tzw. datapoints (DP).
Wielu z was zapewne kojarzy rozkazy z długim ciągiem znaków np. custom-cmd x 0xEF00 0x0 set 10 0203402...

Oczywiście dokumentacja tych DP jest bardzo skąpa i większość informacji dostępna z sieci pochodzi od ludzi, którzy używając tzw. snifferów analizują informacje wymieniane pomiędzy urządzeniem a oryginalną bramką Tuya. Powiem szczerze - bez tych informacji bramka nie miałaby nawet ¼ swojej obecnej funkcjonalności.

[vajera]

Kontynuując poprzedni wątek chciałbym omówić raportowanie atrybutu i związane z tym polecenia odczytu i zapisu konfiguracji raportowania dostępne w GUI (zapis również w konsoli).

Niektóre atrybuty mają status RP, czyli można skonfigurować urządzenie Zigbee tak, by wysłało taki atrybut w zadanych odstępach czasu lub gdy wartość parametru zmieni się o żądaną wartość.

Ktoś mógłby powiedzieć, że taka funkcjonalność nie ma żadnej przewagi na mechanizmem wysyłania zapytań przez bramkę do urządzenia, ale to nie jest prawda.

Wiele z urządzeń Zigbee ma zasilanie bateryjne i użytkownik oczekuje wielomiesięcznej pracy czujnika bez konieczności wymiany baterii.
Żeby uzyskać ten efekt urządzenia przez większość czasu pozostają w stanie uśpienia i wyłączają odbiornik radiowy, przez co stają się głuche i ślepe na sygnały przychodzace z bramki.

Tutaj z pomocą przychodzi potęga polecenia configure-reporting. Odpowiednia konfiguracja sprawi, że co zadany czas lub przy zadanej wielkości zmiany parametru urządzenie włączy nadajnik I wyśle komunikat do bramki.

Konfigurując raportowanie musimy podać:

1. identyfikator klastra np. 0x402 (TEMPERATURE MEASUREMENT),
2. identyfikator atrybutu np. 0x0 (TEMPERATURE),
3. type danych, np. S16,
4. min_interval - to jest bardzo podchwytliwy parametr - jego wartość definiuje minimalny czas, po którym urządzenie zaraportuje dane, np. 60 oznacza, że raport zostanie wysłany nie częściej niż co 60 sekund,
5. max_interval- to jest wartość czasu, po upływie którego raport musi zostać wysłany, np. 3600 oznacza, że raport musi zostać wysłany co godzinę,
6. delta - ten parametr określa zmianę wartości, która spowoduje wysłanie raportu, np. w przypadku temperatury delta = 50 będzie oznaczać 0,5°C

Nowe GUI pozwala zarówno na odczyt aktualnej konfiguracji, jak i na wprowadzenie nowych parametrów.

Przykład nr 1:
Klaster nr 0x500 (IAS zone)
Atrybut 0x0002 (zone status) - to ten atrybut określa pozycję czujnika otwarcia,
Typ danych: 16BITMAP (2 bajty)
Min interval: 0
Max interval: 300
Delta: 1

Taka konfiguracja spowoduje, że czujnik otwarcia wyśle swój stan co 5 minut, niezależnie od tego czy uległ on zmianie.

[vajera]

Krótka instrukcja korzystania z nowego GUI w zakresie operacji na klastrach i ich atrybutach (na razie tylko tekstową bo nie mam możliwości wykonania zrzutów ekranu).

Zakładka Zigbee Clusters&Attributes pozwala na wykonanie następujących operacji na urządzeniu Zigbee:

• odczyt atrybutu (Read Attribute) - wartość + typ - można wybrać predefiniowany identyfikator atrybutu z listy lub wpisać dowolny identyfikator - więcej tutaj;

• zapis atrybutu(Write Attribute) - można wybrać z listy zdefiniowany atrybut razem z typem danych lub uzupełnić te dane ręcznie, niektóre atrybuty posiadają też listę zdefiniowanych wartości, ale podobnie jak w przypadku innych parametrów można te informacje uzupełnić ręcznie - więcej tutaj;

• wykonanie rozkazu (Custom Cmd) - analogiczna sytuacja - wybór z listy lub uzupełnienie danych ręcznie - więcej tutaj;

• odczyt ustawień raportowania(Read reporting settings) dla danego atrybutu - więcej tutaj;

• zapis ustawień raportowania(Configure reporting) dla danego atrybutu - więcej tutaj;

[vajera]

Ten mini poradnik poświęcony jest konfiguracji urządzeń Zigbee zawierających klaster ELECTRICAL MEASUREMENT - są to głównie gniazdka elektryczne z pomiarem takich parametrów jak napięcie, natężenie, moc prądu oraz zużycie energii elektrycznej.

Uwaga - niektóre samodzielne liczniki prądu elektrycznego (1 lub 3 fazowe) działają w oparciu o Tuya custom cluster i wymagają odrębnej konfiguracji.

Bramka może odczytywać powyższe parametry poprzez dwa mechanizmy:

1. Odpowiednio skonfigurowane raportowanie ich bezpośrednio przez urządzenie Zigbee - jest to mechanizm preferowany, gdyż w mniejszym stopniu obciąża bramkę, ale przede wszystkim tylko ta opcja pozwala ustawić reakcję na zmianę wartości, co może znacząco ograniczyć liczbę wysyłanych komunikatów.
2. Poprzez tzw. pooling - bramka wysyła zapytanie do urządzenia w zdefiniowanych odstępach czasu.

Mechanizm nr 1A (raportowanie czasowe):

• Zakładka Clustes&Attributes.
• Należy wybrać z listy urządzeń gniazdko z licznikiem, które chcemy skonfigurować.
• Z listy klastrów wybieramy ELECTRICAL MEASUREMENT.
• Z listy atrybutów wybieramy RMS VOLTAGE.
• Konfiguracja co XX sekund - wpisujemy min interval = 0, max interval = XX, delta = 0.
• Naciskamy Configure reporting.
• Powtarzamy te czynności dla atrybutów RMS CURRENT, ACTIVE POWER.

Mechanizm nr 1B (raportowanie zależne od zmiany parametru):

• Zakładka Clusters&Attributes.
• Należy wybrać z listy urządzeń gniazdko z licznikiem, które chcemy skonfigurować.
• Z listy klastrów wybieramy ELECTRICAL MEASUREMENT.
• Z listy atrybutów wybieramy RMS VOLTAGE.
• Wpisujemy min interval = 0, max interval = 0, delta = XX
• Naciskamy Configure reporting.
• Powtarzamy te czynności dla atrybutów RMS CURRENT, ACTIVE POWER.

XX - ten parametr określa wielkość zmiany - najczęściej* w V / mA / W.

*Niektóre liczniki podają np. wartość napięcia * 10, wtedy wartość zmiany będzie w 0,1 V.
W przypadku wątpliwości można odczytać wartości V / A / W dla znanego odbiornika prądu i ustalić, w jakich jednostkach raportuje licznik.

Niektóre modele liczników elektrycznych nie reagują na polecenie konfiguracji raportowania i wtedy jedynym rozwiązaniem pozostaje pooling

Mechanizm nr 2 (pooling):

• Zakładka ZigbeeChannels.
• Należy wybrać z listy kanał licznika, który chcemy skonfigurować (Type Electricity meter).
• Za pomocą suwaka ustawiamy refresh/autoset na np. 30 sekund, przy okazji można ustawić timeout na np. 60 sekund.

[vajera]

Procedura uczenia sterownika rolet działającego w oparciu o Tuya custom cluster.

1. zakładka Zigbee Devices.
2. Wybierz urządzenie z listy.
3. Klaster Tuya custom cluster 0xEF00.
4. W okienku Attribute id/command id wpisz wartość 0.
5. Z listy typów danych wybierz SET.
6. W polu data type size wpisz 7.
7. W polu attribute value/payload wpisz 00011004000104
8. Wciśnij Custom Cmd
9. Przy pomocy tych przycisków w aplikacji Supla przesuń ręcznie roletę do pozycji, gdzie ma być skrajna góra
10. W polu attribute value/Payload wpisz 00021004000100
11. Wciśnij Custom Cmd
12. Przy pomocy tych przycisków w aplikacji Supla przesuń ręcznie roletę do pozycji, gdzie ma być skrajny dół
13. W polu attribute value/Payload wpisz 00031004000101
14. Wciśnij Custom Cmd
15. Sprawdź czy teraz możesz sterować roletą?

[vajera]

Instrukcja aktualizacji modelu urządzenia Zigbee w przypadku, gdy wyświetla się ono jako Unknown::Unknown

Dwa najczęstsze scenariusze, w których występuje taka sytuacja to:

1. Bramka utworzona przed wprowadzeniem tabeli z2s_zb_devices_table (0.7.0-21/03/2025).
2. Bramka, w której użytkownik usunął urządzenie Zigbee korzystając z konsoli lub GUI.

W tej sytuacji dostępne jest następujące rozwiązanie (począwszy od wersji 0.9.24-11/09/2025 dwa rozwiązania):

• Należy ustalić tzw. device_slot - jest to pozycja urządzenia w tabeli - odpowiada mu pozycja na liście urządzeń (Devices) w zakładce Zigbee devices w GUI. Uwaga - urządzenia numerowane są od 0 w górę. Począwszy od wersji 0.9.16-09/09/2025 wartość ta widoczna jest również w polu Device info w Zakładce Zigbee devices (Slot#).
• Logujemy się do konsoli i wydajemy polecenie update-zb-device-uid device_slot device_uid, gdzie device_uid oznacza unikalny identyfikator urządzenia, który możemy znaleźć w poniższej tabeli:
  https://github.com/lsroka76/Z2S_Library ... se.h#L1140
• Restartujemy bramkę.

Alternatywne rozwiązanie (dostępne od wersji 0.9.24-11/09/2025) polega na wprowadzeniu bramki w tryb parowania a następnie na zainicjowaniu procedury parowania w urządzeniu Zigbee - bramka zaktualizuje manufacturer name i model name a wszystkie dane urządzenia i kanałów Supla po stronie bramki pozostaną nienaruszone. Ta operacja spowoduje jednak reset ustawień w obrębie samego urządzenia, włączając w to ustawienia poleceń configure reporting.

[vajera]

Instrukcja wykonania kopii zapasowej lub przeniesienia danych bramki Z2S


A) ESP32 C6 - wersja z 8/16 MB

Potrzebne będzie narzędzie esptool.py - po szczegóły dotyczące instalacji odsyłam do Internetu

Alternatywnie można wykorzystać narzędzie Flash Download Tool (podziękowania @bokk).

1. esptool.py --chip esp32c6 --port COMX read_flash 0x690000 0x160000 littlefs_zigbee.bin (bramka źródłowa)
2. esptool.py --chip esp32c6 --port COMX erase_flash (bramka docelowa)
3. esptool.py --chip esp32c6 --port COMX write_flash 0x0 Z2S_Gateway.ino.merged.bin (bramka docelowa)
4. esptool.py --chip esp32c6 --port COMX write_flash 0x690000 littlefs_zigbee.bin (bramka docelowa)

COMX - wpisujemy numeru portu COM, np. COM8

Uwaga - kroki (2) i (3) można zastąpić wgrywając plik merged, tak jak do tej pory (najlepiej z czyszczeniem pamięci FLASH).

Uwaga nr - krok (1) może się czasami zakończyć komunikatem o błędzie odczytu - należy wtedy ponowić to polecenie i najlepiej upewnić się, że plik littlefs_zigbee.bin jest na dysku zanim wyczyścimy FLASH.

B) ESP32 C6 - wersja z 4 MB

Potrzebne będzie narzędzie esptool.py - po szczegóły dotyczące instalacji odsyłam do Internetu

1. esptool.py --chip esp32c6 --port COMX read_flash 0x290000 0x160000 littlefs_zigbee.bin (bramka źródłowa)
2. esptool.py --chip esp32c6 --port COMX erase_flash (bramka docelowa)
3. esptool.py --chip esp32c6 --port COMX write_flash 0x0 Z2S_Gateway.ino.merged.bin (bramka docelowa)
4. esptool.py --chip esp32c6 --port COMX write_flash 0x290000 littlefs_zigbee.bin (bramka docelowa)

COMX - wpisujemy numeru portu COM, np. COM8

Uwaga - kroki (2) i (3) można zastąpić wgrywając plik merged, tak jak do tej pory (najlepiej z czyszczeniem pamięci FLASH).

Uwaga nr - krok (1) może się czasami zakończyć komunikatem o błędzie odczytu - należy wtedy ponowić to polecenie i najlepiej upewnić się, że plik littlefs_zigbee.bin jest na dysku zanim wyczyścimy FLASH.

C) Przeniesienie danych z bramki 4MB na 8/16 MB (podziękowania @Zibi_007)

Potrzebne będzie narzędzie esptool.py - po szczegóły dotyczące instalacji odsyłam do Internetu

1. esptool.py --chip esp32c6 --port COMX read_flash 0x290000 0x160000 littlefs_zigbee.bin (bramka źródłowa)
2. esptool.py --chip esp32c6 --port COMY erase_flash (bramka docelowa)
3. esptool.py --chip esp32c6 --port COMY write_flash 0x0 Z2S_Gateway.ino.merged.bin (bramka docelowa)
4. esptool.py --chip esp32c6 --port COMY write_flash 0x690000 littlefs_zigbee.bin (bramka docelowa)

COMX - wpisujemy numeru portu COM, np. COM8

Uwaga - kroki (2) i (3) można zastąpić wgrywając plik merged do bramki docelowej, tak jak do tej pory (najlepiej z czyszczeniem pamięci FLASH).

Uwaga nr - krok (1) może się czasami zakończyć komunikatem o błędzie odczytu - należy wtedy ponowić to polecenie.

[vajera]

Instrukcja wykonania kopii zapasowej bramki Z2S - ESP FLASH DOWNLOAD TOOL

Uruchamiamy FDT - w oknie konfiguracji ustawiamy parametry, jak poniżej:

Zrzut ekranu 2025-10-19 182753.png

Po uruchomieniu interface graficznego FDT wybieramy zakładkę chipInfoDump

Zrzut ekranu 2025-10-19 182844.png

Wybieramy port COM, do którego podłączona jest bramka Zigbee (uwaga - w tym czasie wszystkie inne monitory portu muszą być wyłączone).

Parametry Read Flash ustawiamy następująco:

A) ESP32 C6 - wersja z 8/16 MB


address 0x690000
size 0x160000

Wciskamy przycisk Read Flash (w przypadku komunikatu o błędzie trzeba spróbować ponownie - czasami nawet kilka razy).
Program zapisze plik i otworzy okno przeglądarki plików - tutaj możemy np. zmienić nazwę tego pliku na bardziej przyjazną.


B) ESP32 C6 - wersja z 4 MB


address 0x290000
size 0x160000

Wciskamy przycisk Read Flash (w przypadku komunikatu o błędzie trzeba spróbować ponownie - czasami nawet kilka razy).
Program zapisze plik i otworzy okno przeglądarki plików - tutaj możemy np. zmienić nazwę tego pliku na bardziej przyjazną.

[vajera]

Urządzenia oparte o tzw. Tuya custom cluster (0xEF00) - krótki poradnik.


Firma Tuya opracowała swój własny system, z którego korzysta wielu producentów (Zemismart, Moes, itd.).
Zamiast zastosować się do standardu Zigbee, Tuya wprowadziła pojęcie tzw. datapoints, czyli liczb z przedziału [1..255], pod którymi ukryte są różne funkcje danego urządzenia, poniżej kilka charakterystycznych cech tego rozwiązania:

- liczby odpowiadające konkretnym datapoints są związane z konkretnym modelem urządzenia, czyli ta sama liczba może definiować zupełnie inną funkcję oraz ta sama funkcja może mieć zupełnie inną wartość datapoint w zależności od modelu urządzenia,

- nie ma żadnego oficjalnego katalogu tych liczb, wszystkie znane datapoints pochodzą z analiz zewnętrznych i nie zawsze są kompletne,

- datapoints mogą być zapisywalne, ale nie spotkałem się z odczytywalnym datapoint - to oznacza, że ich zawartość można poznać tylko wtedy, gdy urządzenie zdecyduje się ją wysłać.

GUI zawiera zakładkę o nazwie Tuya custom cluster (0xEF00) devices - jeżeli któreś z urządzeń dodanych do bramki działa w oparciu o to rozwiązanie, to pojawi się tam na liście wyboru.
Niektóre z tych urządzeń mają predefiniowane datapoints, które pozwalają na ustawienie dodatkowych funkcji urządzenia. Po wybraniu takiego predefiniowanego zestawu z listy automatycznie uzupełnią się pola datapoint type i datapoint size.
Użytkownik musi uzupełnić pole datapoint value - zgodnie z legendą zawartą poniżej tego pola i nacisnąć przycisk Data request.
UWAGA: urządzenia zasilane bateryjnie wymagają najpierw obudzenia przyciskiem.