Dokumentacja Zigbee
Ta strona opisuje, jak ZiggyMeter wygląda w sieci Zigbee: punkty końcowe, klastry i atrybuty. Jak dołączyć do sieci, opisuje Konfiguracja Zigbee.
O Zigbee
Zigbee to energooszczędny bezprzewodowy protokół sieci kratowej dla urządzeń IoT, działający na IEEE 802.15.4 w paśmie 2,4 GHz. Wiadomości przeskakują przez routery zasilane z sieci, i właśnie dzięki temu działa w szafkach licznikowych i piwnicach, gdzie bezpośrednie łącze Wi-Fi by nie dało rady.
ZiggyMeter dołącza jako urządzenie końcowe: niczego nie przekazuje dla innych i śpi między odczytami.
Wymagania
- Koordynator Zigbee — adapter USB albo hub, który tworzy sieć i nią zarządza
- Oprogramowanie rozumiejące klastry Zigbee Cluster Library v8
Wszystkie klastry udostępniane przez ZiggyMeter są standardowe. Nie ma żadnych klastrów specyficznych dla producenta, więc większość integracji działa od razu, bez dedykowanego sterownika urządzenia.
Punkty końcowe
Punkt końcowy 1 — urządzenie
Identyfikacja urządzenia i podstawowy stan. Przełączenie przełącznika On/Off włącza lub wyłącza Wi-Fi.
Klastry wejściowe
| ID klastra | Nazwa |
|---|---|
0x0000 | Basic |
0x0001 | Power Configuration |
0x0003 | Identify |
0x0006 | On/Off |
0x0402 | Temperature Measurement |
Klastry wyjściowe
| ID klastra | Nazwa |
|---|---|
0x0003 | Identify |
0x0019 | OTA Upgrade |
Punkt końcowy 2 — licznik
Dane licznika. Przełączenie przełącznika On/Off wyzwala odczyt licznika.
Klastry wejściowe
| ID klastra | Nazwa |
|---|---|
0x0006 | On/Off |
0x0702 | Simple Metering |
0x0B04 | Electrical Measurement |
Brak klastrów wyjściowych.
Klaster Metering (0x0702)
Dwa atrybuty, oba standardowe. Nie są potrzebne żadne polecenia własne producenta.
| ID atrybutu | Nazwa |
|---|---|
0x0000 | Current Summation Delivered |
0x0001 | Current Summation Received |
Current Summation Received jest aktualizowany tylko wtedy, gdy licznik podaje tę wartość.
Klaster Electrical Measurement (0x0B04)
Parametry elektryczne. Klaster deklaruje pełny zestaw atrybutów poniżej, ale tylko trzy z nich — Active power (0x050B), RMS current (0x0508) i RMS voltage (0x0505) — mogą być zasilone wartością z licznika i raportowane koordynatorowi. Zobacz Dostępne cele.
To, które z nich są faktycznie aktualizowane, zależy potem od licznika: licznik jednofazowy oczywiście nigdy nie wypełni faz B i C.
Niektóre integracje Zigbee nie pokazują każdego atrybutu, nawet gdy urządzenie poprawnie go aktualizuje. Sprawdź surowe wartości klastrów we własnych narzędziach koordynatora, zanim uznasz, że urządzenie nic nie raportuje.
| ID atrybutu | Nazwa |
|---|---|
0x0300 | AC frequency |
0x0304 | Total active power |
0x0305 | Total reactive power |
0x0306 | Total apparent power |
0x0501 | Line current (phase A) |
0x0502 | Active current (phase A) |
0x0503 | Reactive current (phase A) |
0x0505 | RMS voltage (phase A) |
0x0508 | RMS current (phase A) |
0x050B | Active power (phase A) |
0x050E | Reactive power (phase A) |
0x050F | Apparent power (phase A) |
0x0901 | Line current (phase B) |
0x0902 | Active current (phase B) |
0x0903 | Reactive current (phase B) |
0x0905 | RMS voltage (phase B) |
0x0908 | RMS current (phase B) |
0x090B | Active power (phase B) |
0x090E | Reactive power (phase B) |
0x090F | Apparent power (phase B) |
0x0A01 | Line current (phase C) |
0x0A02 | Active current (phase C) |
0x0A03 | Reactive current (phase C) |
0x0A05 | RMS voltage (phase C) |
0x0A08 | RMS current (phase C) |
0x0A0B | Active power (phase C) |
0x0A0E | Reactive power (phase C) |
0x0A0F | Apparent power (phase C) |
Jak wartości licznika stają się atrybutami
Licznik posługuje się kodami OBIS, a Zigbee atrybutami klastrów. ZiggyMeter utrzymuje tabelę mapowania między nimi.
Każdy wpis mapowania to kod OBIS plus ID mapowania: cztery bajty szesnastkowo, gdzie pierwsze dwa to klaster, a ostatnie dwa to atrybut.
| OBIS | ID mapowania | Klaster / atrybut | Znaczenie |
|---|---|---|---|
1-0:1.8.0 | 07020000 | 0x0702 / 0x0000 | Current summation delivered |
1-0:2.8.0 | 07020001 | 0x0702 / 0x0001 | Current summation received |
1-0:1.7.0 | 0b04050b | 0x0B04 / 0x050B | Moc czynna, faza A |
1-0:11.7.0 | 0b040508 | 0x0B04 / 0x0508 | Prąd skuteczny, faza A |
1-0:12.7.0 | 0b040505 | 0x0B04 / 0x0505 | Napięcie skuteczne, faza A |
Zmień to, gdy Twój licznik używa kodu, którego nie obejmują ustawienia domyślne — na przykład licznika zgłaszającego napięcie pod kodem właściwym dla modelu, przez co wartość pojawia się w odczycie, ale nigdy nie dociera do koordynatora.
Zmiana mapowania
Robi się to w interfejsie webowym. Otwórz Licznik → Odczyt i kliknij dwukrotnie komórkę Mapowanie w wierszu, który chcesz zmienić; komórka zamienia się w listę rozwijaną dostępnych celów Zigbee. Wybierz jeden, a zapisze się natychmiast — nie ma osobnego kroku zapisu.
INFO
Zmapować można wyłącznie kody OBIS, które pojawiają się w odczycie, bo ta tabela jest odczytem. Jeśli brakuje wiersza, którego szukasz, najpierw odczytaj licznik.
Dostępne cele
Lista rozwijana oferuje sześć pozycji i nic więcej. Tylko tym pięciu parom klaster/atrybut można przypisać kod OBIS — pozostałe atrybuty wymienione powyżej istnieją w klastrach, ale nie są celami mapowania.
| Pozycja listy rozwijanej | ID mapowania | Klaster / atrybut |
|---|---|---|
| Nieprzypisane | 00000000 | — (wartość jest odczytywana, ale nie publikowana przez Zigbee) |
| Summation Delivered [kWh] | 07020000 | 0x0702 / 0x0000 |
| Summation Received [kWh] | 07020001 | 0x0702 / 0x0001 |
| Active Power [kW] | 0b04050b | 0x0B04 / 0x050B |
| Current RMS [A] | 0b040508 | 0x0B04 / 0x0508 |
| Voltage RMS [V] | 0b040505 | 0x0B04 / 0x0505 |
WARNING
Każdy cel może być jednocześnie używany przez jeden kod OBIS. Przypisanie celu, który trzyma już inny wiersz, przenosi go: tamten wiersz zostaje automatycznie ustawiony z powrotem na Nieprzypisane. Po zmianie sprawdź tabelę, jeśli przestawiasz kilka wierszy.
Porównywany jest pełny kod OBIS wraz z taryfą (1-0:15.8.0*101). API przyjmuje dodatkowo porównanie z krótkim kodem (15.8.0).
Edycja przez API
/api/v1/zigbee/map czyta i zapisuje tę samą tabelę, co przydaje się przy identycznym konfigurowaniu wielu urządzeń. To alternatywa dla interfejsu webowego, a nie zwykła droga — POST zastępuje całą tabelę i nie stosuje za Ciebie zasady „jeden cel, jeden kod”.
Oprogramowanie bezprzewodowo
Punkt końcowy 1 niesie standardowy klaster OTA Upgrade (0x0019), więc dowolny koordynator obsługujący Zigbee OTA może zaktualizować urządzenie. Gotowe pliki indeksowe są publikowane dla Zigbee2MQTT oraz dla zigpy/ZHA: