TapHome

SmartThings Przełącznik/Gniazdko z Pomiarem Mocy

Packet Parser → HTTP
Dodane przez
Ostatnia aktualizacja: 03. 2026
SmartThings Przełącznik/Gniazdko z Pomiarem Mocy

Ten szablon integruje dowolny przełącznik lub gniazdko kompatybilne ze SmartThings z pomiarem mocy do TapHome. Komunikacja odbywa się przez SmartThings Cloud REST API v1 pod adresem api.smartthings.com przez HTTPS — szablon nie komunikuje się bezpośrednio z urządzeniem fizycznym. Urządzenie może być ZigBee, Z-Wave lub Matter — pod warunkiem, że jest podłączone do konta SmartThings i udostępnia możliwości switch, powerMeter i energyMeter, szablon będzie działać.

Szablon został stworzony przez Csongora Vargę i zademonstrowany na gniazdku ZigBee BlitzWolf BW-SHP15, ale nie jest ograniczony do tego modelu.

Konfiguracja

Szablon wymaga dwóch zmiennych skonfigurowanych w TapHome po imporcie:

  • Token — SmartThings Personal Access Token (PAT) używany do uwierzytelnienia Bearer
  • DeviceId — UUID urządzenia docelowego w platformie SmartThings
Generowanie Personal Access Tokena
  1. Przejdź na account.smartthings.com/tokens i zaloguj się kontem Samsung
  2. Kliknij Generate new token i nadaj nazwę (np. „TapHome Integration")
  3. Wybierz uprawnienie Devices — jest wymagane do odczytu stanu i wysyłania poleceń
  4. Kliknij Generate Token i natychmiast skopiuj token — to jedyna okazja do pobrania wartości

Standardowe Personal Access Tokeny (utworzone po 30 grudnia 2024) są ważne tylko przez 24 godziny. Token musi zostać wygenerowany ponownie i zaktualizowany w TapHome przed wygaśnięciem, w przeciwnym razie integracja przestanie działać. Starsze tokeny utworzone przed tą datą mogą mieć dłuższy okres ważności.

Znajdowanie Device ID
  1. Zaloguj się na my.smartthings.com
  2. Znajdź urządzenie docelowe na liście urządzeń
  3. Skopiuj Device ID ze strony szczegółów urządzenia — to ciąg UUID (np. 47eff6bf-83c9-4374-a367-b254759b486d)
Dodawanie wielu urządzeń

Każde urządzenie SmartThings wymaga własnej instancji modułu. Aby dodać kolejne urządzenie, zaimportuj szablon ponownie i skonfiguruj nowe DeviceId. Ten sam Token można wykorzystać we wszystkich modułach.

Możliwości urządzenia

Sterowanie przełącznikiem

Szablon udostępnia urządzenie jako przełącznik. Stan jest odczytywany z odpowiedzi statusu SmartThings (components.main.switch.switch.value — "on" lub "off", mapowane na 1/0). Polecenia przełącznika są wysyłane przez POST /v1/devices/{DeviceId}/commands z możliwością switch.

Po wysłaniu polecenia przełącznika szablon czeka 500 ms i ponownie odczytuje stan urządzenia, aby zapobiec mieszaniu stanów między poleceniem a następnym cyklem pollingu. Przełącznik jest odpytywany co 2,5 sekundy.

Pomiar mocy

Wbudowany licznik energii odczytuje dwie wartości z odpowiedzi statusu:

  • Moc w czasie rzeczywistym — components.main.powerMeter.power.value raportowana w watach, konwertowana na kW przez szablon (÷ 1000)
  • Całkowite zużycie — components.main.energyMeter.energy.value raportowane bezpośrednio w kWh

Licznik jest tylko do odczytu i odpytywany co 15 sekund.

Dodatkowe możliwości

SmartThings API udostępnia również ciągi jednostek mocy i energii, stan zdrowia urządzenia oraz możliwość odświeżenia (refresh) wymuszającą natychmiastową aktualizację stanu. Mogą one zostać dodane w przyszłej aktualizacji szablonu.

Rozwiązywanie problemów

Integracja przestaje działać po 24 godzinach

Standardowe tokeny PAT SmartThings wygasają po 24 godzinach. Wygeneruj nowy token na account.smartthings.com/tokens i zaktualizuj zmienną Token w module TapHome. Jeśli częste odnawianie tokenu jest niepraktyczne, sprawdź, czy na koncie jest dostępny starszy token z dłuższym okresem ważności.

Urządzenie nie odpowiada
  1. Sprawdź, czy urządzenie SmartThings jest online — sprawdź jego stan w aplikacji SmartThings
  2. Potwierdź, że zmienna DeviceId odpowiada prawidłowemu UUID urządzenia
  3. Przetestuj API ręcznie: GET https://api.smartthings.com/v1/devices/{DeviceId}/status z nagłówkiem Authorization: Bearer {Token} — powinno zwrócić odpowiedź JSON ze stanem urządzenia
  4. Upewnij się, że Token ma prawidłowe uprawnienie (Devices — odczyt i wykonywanie)
Odczyty mocy pokazują zero
  1. Potwierdź, że urządzenie faktycznie zużywa energię — włącz podłączony odbiornik
  2. Sprawdź, czy urządzenie SmartThings obsługuje możliwości powerMeter i energyMeter — nie wszystkie przełączniki raportują moc
  3. Ręcznie odpytaj API statusu i sprawdź, czy components.main.powerMeter.power.value zwraca wartość różną od zera

To jest integracja oparta na chmurze — wymaga aktywnego połączenia internetowego na TapHome CCU. Szablon komunikuje się z serwerami Samsunga, a nie z urządzeniem fizycznym w sieci lokalnej.

Dostępne urządzenia

SmartThings Przełącznik/Gniazdko Moduł
Zmienne niestandardowe
Token (string) = 0ead2552-e331-4355-b483-81d3898eb5baSmartThings Personal Access Token for API authentication (generate at my.smartthings.com)
DeviceId (string) = 47eff6bf-83c9-4374-a367-b254759b486dSmartThings device UUID — identifies the target switch or plug

SmartThings Switch/Plug with Power Metering

Odczyt (moduł)
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization: Bearer "+Token);
IF response.IsSuccess
 StatusJson := response.Content;
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Licznik energii Licznik energii Tylko do odczytu

Pomiar zużycia energii — moc chwilowa (kW) i energia skumulowana (kWh) przez SmartThings Cloud API

numeric Jednostka: kW / kWh JSON
Zmienna: DeviceId

Licznik energii

Odczyt całkowitego zużycia
VAR value := PARSEJSON(StatusJson, "components.main.energyMeter.energy.value", 1);
IF(ISNULL(value), NaN, value);
Odczyt zapotrzebowania
VAR value := PARSEJSON(StatusJson, "components.main.powerMeter.power.value", 1);
IF(ISNULL(value), NaN, value / 1000);
Przełącznik Przełącznik
boolean JSON
Wartości / Stany: ON · OFF

Przełącznik

Odczyt stanu przełącznika
VAR value := PARSEJSON(StatusJson, "components.main.switch.switch.value", 1);
IF(ISNULL(value), NaN, if(value="on", 1, 0));
Zapis stanu przełącznika
# Set Http request method, body and headers
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/commands", 
"POST", 
"{\"commands\": [ { \"component\": \"main\", \"capability\": \"switch\", \"command\": \""+IF(St=1, "on", "off")+"\", \"arguments\": [] } ] }",
"Authorization: Bearer "+Token);


# Wait a little an read the state again to prevent state shuffle
SLEEP(500);
response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization: Bearer "+Token);
IF response.IsSuccess
 StatusJson := response.Content;
 # ADDINFO("StatusJson refreshed");
ELSE
 ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Połączenie: Packet Parser → HTTP
Możliwe ulepszenia (4)
  • Power Unit — Unit string for power reading (W), available in status response
  • Energy Unit — Unit string for energy reading (kWh), available in status response
  • Health Check — Device health/online status, available via SmartThings Health API
  • Refresh — Force refresh device state via SmartThings refresh capability command

Źródła