TapHome

Samsung WindFree Klimatyzator

Packet Parser → HTTP
Dodane przez
Ostatnia aktualizacja: 04. 2026
Samsung WindFree Klimatyzator

Szablon Samsung WindFree dla klimatyzatora łączy TapHome z jednostkami split Samsung poprzez Samsung SmartThings cloud API. Cała komunikacja odbywa się przez HTTPS do api.smartthings.com — nie jest wymagane żadne lokalne okablowanie ani adaptery protokołów. Jedyne wymagania to konto Samsung ze SmartThings, Personal Access Token (PAT) oraz Device ID jednostki klimatyzacyjnej.

Szablon udostępnia 8 urządzeń zapewniających pełne sterowanie klimatyzacją: włączanie/wyłączanie, wybór trybu HVAC, prędkość wentylatora, kierunek przepływu powietrza, ustawienie temperatury docelowej, odczyt temperatury i wilgotności pomieszczenia oraz ekskluzywne presety Samsung, w tym WindFree i WindFree Sleep.

Konfiguracja

Konfiguracja dostępu do SmartThings API
  1. Zaloguj się do portalu deweloperskiego Samsung SmartThings na account.smartthings.com/tokens przy użyciu konta Samsung powiązanego z jednostką klimatyzacyjną
  2. Kliknij Generate new token
  3. Nazwij token (np. “TapHome”) i wybierz scope Devices (read + execute)
  4. Kliknij Generate Token i skopiuj ciąg tokenu — nie zostanie ponownie wyświetlony
Znalezienie Device ID

Device ID to GUID (np. a1b2c3d4-e5f6-7890-abcd-ef1234567890), który identyfikuje konkretną jednostkę klimatyzacyjną w SmartThings.

  1. Otwórz przeglądarkę lub narzędzie API i wyślij żądanie GET na:
    1

    https://api.smartthings.com/v1/devices
    z nagłówkiem Authorization: Bearer <Twój-token>
  2. Znajdź klimatyzator Samsung WindFree w odpowiedzi — pole deviceId zawiera wymagany GUID
  3. Alternatywnie użyj SmartThings CLI lub aplikacji mobilnej Samsung SmartThings (sekcja Device Info)
Parametry importu

Podczas importu szablonu w TapHome wprowadź:

ParametrOpisFormat
TokenSmartThings Personal Access TokenDługi ciąg alfanumeryczny
DeviceIdIdentyfikator urządzenia SmartThingsFormat UUID / GUID

SmartThings Personal Access Tokeny (PAT) są przeznaczone do testów i użytku osobistego. Mogą wygasnąć lub zostać unieważnione. Jeśli token stanie się nieprawidłowy, wygeneruj nowy na account.smartthings.com/tokens i zaktualizuj zmienną modułu w TapHome.

Zależność od internetu

Jest to integracja wyłącznie chmurowa. Wszystkie dane przechodzą przez serwery Samsung SmartThings (api.smartthings.com:443). Szablon wymaga aktywnego połączenia internetowego na TapHome Core. Jednostka klimatyzacyjna musi być zarejestrowana i online w aplikacji SmartThings.

Możliwości urządzeń

Zasilanie i tryb HVAC

Przełącznik Power włącza i wyłącza jednostkę klimatyzacyjną przez SmartThings capability switch.

Selektor HVAC Mode oferuje pięć trybów pracy: Heat, Cool, Cool+Heat (auto), Dry i Fan Only. Nazwy trybów w TapHome odpowiadają wartościom SmartThings API heat, cool, auto, dry i wind.

Wentylator i sterowanie przepływem powietrza

Selektor Fan Mode oferuje pięć prędkości: Auto, Low, Medium, High i Turbo.

Selektor Swing Mode steruje oscylacją lameli kierunkowych z czterema opcjami: Fixed (brak ruchu), All (obie osie), Vertical i Horizontal.

Tryby presetów (WindFree)

Selektor Preset Mode steruje opcjonalnymi trybami specyficznymi dla Samsung przez capability custom.airConditionerOptionalMode. Dostępnych jest siedem presetów:

WartośćTrybOpis
0OffBrak aktywnego trybu presetu
1SleepStopniowa regulacja temperatury dla nocnego komfortu
2QuietPraca ze zmniejszonym poziomem hałasu
3SmartOptymalizacja oparta na AI
4SpeedSzybkie chłodzenie lub ogrzewanie
5WindFreePowietrze rozprowadzane przez tysiące mikro-otworów — brak bezpośredniego przepływu
6WindFree SleepPołączenie dystrybucji powietrza WindFree z trybem snu

WindFree to opatentowana funkcja Samsung unikalna dla serii WindFree. Eliminuje bezpośredni przepływ powietrza, rozprowadzając klimatyzowane powietrze przez mikro-perforacje w panelu przednim.

Urządzenie Preset Mode odczytuje status z dedykowanego endpointu capability (/v1/devices/{DeviceId}/components/main/capabilities/custom.airConditionerOptionalMode/status) zamiast z pełnego endpointu statusu urządzenia, co zapewnia niezawodny odczyt aktywnego presetu.

Sterowanie i monitorowanie temperatury

Urządzenie Thermostat ustawia docelową temperaturę chłodzenia w 10 dyskretnych krokach od 18 °C do 27 °C. Każdy krok odpowiada indeksowi przełącznika (0 = 18 °C, 9 = 27 °C). SmartThings API obsługuje szerszy zakres (16–30 °C), ale szablon wykorzystuje podzbiór 18–27 °C.

Urządzenie Cooling Setpoint (Readback) to czujnik temperatury tylko do odczytu, który odzwierciedla aktualny punkt nastawy zgłaszany przez jednostkę klimatyzacyjną. Zapewnia wizualne sprzężenie zwrotne w TapHome bez możliwości zapisu — do zmiany temperatury użyj urządzenia Thermostat.

Czujnik Temperature + Humidity odczytuje temperaturę pomieszczenia (°C) i wilgotność względną z wbudowanych czujników jednostki klimatyzacyjnej. Wilgotność jest zwracana jako liczba całkowita 0–100 z API i konwertowana na stosunek 0–1 dla wejścia analogowego TapHome (np. 55 % staje się 0,55). To urządzenie odpytuje w 15-sekundowych interwałach (wolniej niż 2,5-sekundowy interwał urządzeń sterujących).

Dodatkowe możliwości

Niektóre modele WindFree udostępniają również czujniki poziomu pyłu (PM2.5/PM10), poziomu zapachów i kombinowanej jakości powietrza, a także sterowanie obciążeniem na żądanie i automatyczny tryb samoczyszczenia. Te możliwości są dostępne przez SmartThings API, ale nie są jeszcze zaimplementowane w szablonie. Mogą zostać dodane w przyszłej aktualizacji szablonu.

Rozwiązywanie problemów

Błędy uwierzytelniania (HTTP 401)
  1. Sprawdź, czy Personal Access Token jest nadal ważny — tokeny PAT mogą wygasnąć lub zostać ręcznie unieważnione
  2. Wygeneruj nowy token na account.smartthings.com/tokens i zaktualizuj zmienną Token w ustawieniach modułu TapHome
  3. Upewnij się, że token ma włączony scope Devices
Urządzenie nie znalezione (HTTP 404)
  1. Potwierdź, że DeviceId jest prawidłowy — wyślij GET /v1/devices z tokenem i zweryfikuj GUID
  2. Sprawdź, czy jednostka klimatyzacyjna jest online w aplikacji SmartThings
  3. Sprawdź, czy jednostka jest zarejestrowana pod tym samym kontem Samsung co token
Urządzenie nie reaguje
  1. Sprawdź połączenie internetowe TapHome Core
  2. Sprawdź, czy usługa chmurowa Samsung SmartThings działa (status na status.smartthings.com)
  3. Uruchom ponownie jednostkę klimatyzacyjną i poczekaj, aż ponownie pojawi się w aplikacji SmartThings
Ograniczenie liczby żądań (HTTP 429)

SmartThings API wymusza limity liczby żądań. Szablon odpytuje urządzenia sterujące co 2,5 sekundy, a czujniki co 15 sekund. Jeśli inne integracje (Home Assistant, automatyzacje SmartThings) współdzielą to samo konto, łączna częstotliwość żądań może przekroczyć limit. W przypadku throttlingu rozważ zwiększenie interwałów odpytywania w szablonie TapHome.

Jest to integracja wyłącznie chmurowa, zależna od dostępności serwerów Samsung SmartThings i aktywnego połączenia internetowego. Podczas awarii chmury lub przerw w łączności szablon nie może odczytywać ani sterować jednostką klimatyzacyjną. Nie istnieje lokalna ścieżka komunikacji awaryjnej.

Dostępne urządzenia

SmartThings — Samsung WindFree AC Moduł
Zmienne niestandardowe
Token (string)SmartThings Personal Access Token — wygeneruj na account.smartthings.com/tokens
DeviceId (string)SmartThings Device ID jednostki klimatyzacyjnej Samsung (format GUID)
Tryb wentylatora Przełącznik wielowartościowy

Sterowanie prędkością wentylatora — Auto, Low, Medium, High, Turbo

enum JSON PARSEJSON()
Wartości / Stany: AUTO · LOW · MEDIUM · HIGH · TURBO

Tryb wentylatora

Odczyt stanu przełącznika
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization:Bearer " + Token);
IF(response.IsSuccess = 1)
    VAR state := PARSEJSON(response.Content, "components.main.airConditionerFanMode.fanMode.value");
    if state = "auto"
    return(0);
        elseif state = "low"
        return(1);
        elseif state = "medium"
        return(2);
        elseif state = "high"
        return(3);
        elseif state = "turbo"
        return(4);
        end    
END
Zapis stanu przełącznika
VAR localfan := SWITCH(Mu, 0, "auto", 1, "low", 2, "medium", 3, "high", 4, "turbo", "");

SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/commands", "POST", "{\"commands\":[{\"component\": \"main\", \"capability\": \"airConditionerFanMode\", \"command\": \"setFanMode\", \"arguments\": [\""+localfan+"\"]}]}", "Authorization:Bearer " + Token);
Tryb HVAC Przełącznik wielowartościowy

Tryb pracy — Heat, Cool, Cool+Heat (auto), Dry, Fan Only

enum JSON PARSEJSON()
Wartości / Stany: OFF · HEAT · COOL · COOL + HEAT · DRY · FAN ONLY

Tryb HVAC

Odczyt stanu przełącznika
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization:Bearer " + Token);
IF(response.IsSuccess = 1)
    VAR state := PARSEJSON(response.Content, "components.main.airConditionerMode.airConditionerMode.value");        
        if state = "heat"
        return(1);
        elseif state = "cool"
        return(2);
        elseif state = "auto"
        return(3);
        elseif state = "dry"
        return(4);
        elseif state = "wind"
        return(5);             
        end    
END
Zapis stanu przełącznika
VAR localhvac := SWITCH(Mu, 1, "heat", 2, "cool", 3, "auto", 4, "dry", 5, "wind", "");

SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/commands", "POST", "{\"commands\":[{\"component\": \"main\", \"capability\": \"airConditionerMode\", \"command\": \"setAirConditionerMode\", \"arguments\": [\""+localhvac+"\"]}]}", "Authorization:Bearer " + Token);
Zasilanie Przełącznik
boolean JSON PARSEJSON()
Wartości / Stany: ON · OFF

Zasilanie

Odczyt stanu przełącznika
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization:Bearer " + Token);
IF(response.IsSuccess = 1)
    VAR state := PARSEJSON(response.Content, "components.main.switch.switch.value");
    if state = "off"
    return(0);
    elseif state = "on"
        return(1);
        end    
END
Zapis stanu przełącznika
VAR localpower := SWITCH(St, 0, "off", 1, "on", "");

SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/commands", "POST", "{\"commands\":[{\"component\": \"main\", \"capability\": \"switch\", \"command\": \""+localpower+"\"}]}", "Authorization:Bearer " + Token);
Tryb presetu Przełącznik wielowartościowy

Opcjonalne tryby Samsung — Off, Sleep, Quiet, Smart, Speed, WindFree, WindFree Sleep

enum JSON PARSEJSON()
Wartości / Stany: OFF · SLEEP · QUIET · SMART · SPEED · WindFree · WindFreeSleep

Tryb presetu

Odczyt stanu przełącznika
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/components/main/capabilities/custom.airConditionerOptionalMode/status", "GET", "", "Authorization:Bearer " + Token);
IF(response.IsSuccess = 1)
    VAR state := PARSEJSON(response.Content, "acOptionalMode.value");
    if state = "sleep"
        return(1);
        elseif state = "off"
        return(0);
        elseif state = "quiet"
        return(2);
        elseif state = "smart"
        return(3);
        elseif state = "speed"
        return(4);
        elseif state = "windFree"
        return(5);         
        elseif state = "windFreeSleep"
        return(6);        
        end
end
Zapis stanu przełącznika
VAR localpreset := SWITCH(Mu, 0, "off", 1, "sleep", 2, "quiet", 3, "smart", 4, "speed", 5, "windFree", 6, "windFreeSleep", "");

SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/commands", "POST", "{\"commands\":[{\"component\": \"main\", \"capability\": \"custom.airConditionerOptionalMode\", \"command\": \"setAcOptionalMode\", \"arguments\": [\""+localpreset+"\"]}]}", "Authorization:Bearer " + Token);
Tryb lameli Przełącznik wielowartościowy

Oscylacja lameli kierunkowych — Fixed, All, Vertical, Horizontal

enum JSON PARSEJSON()
Wartości / Stany: FIXED · ALL · VERTICAL · HORIZONTAL
Zmienna: swing

Tryb lameli

Odczyt stanu przełącznika
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization:Bearer " + Token);
IF(response.IsSuccess = 1)
    VAR state := PARSEJSON(response.Content, "components.main.fanOscillationMode.fanOscillationMode.value");
    if state = "fixed"
    return(0);
    elseif state = "all"
        return(1);
        elseif state = "vertical"
        return(2);
        elseif state = "horizontal"
        return(3);
        end    
END
Zapis stanu przełącznika
VAR localswing := SWITCH(Mu, 0, "fixed", 1, "all", 2, "vertical", 3, "horizontal", "");

SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/commands", "POST", "{\"commands\":[{\"component\": \"main\", \"capability\": \"fanOscillationMode\", \"command\": \"setFanOscillationMode\", \"arguments\": [\""+localswing+"\"]}]}", "Authorization:Bearer " + Token);
Temperatura + Wilgotność Czujnik temperatury Tylko do odczytu

Temperatura pomieszczenia (°C) i wilgotność względna z wbudowanych czujników jednostki klimatyzacyjnej

numeric Jednostka: °C / % JSON PARSEJSON()

Temperatura + Wilgotność

Odczyt wilgotności
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization:Bearer " + Token);
IF(response.IsSuccess = 1)
    VAR state := PARSEJSON(response.Content, "components.main.relativeHumidityMeasurement.humidity.value");
    return(ToDouble(state / 100));
END
Odczyt temperatury
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization:Bearer " + Token);
IF(response.IsSuccess = 1)
    VAR state := PARSEJSON(response.Content, "components.main.temperatureMeasurement.temperature.value");
    return(ToDouble(state));
END
Nastawa chłodzenia (odczyt) Czujnik temperatury Tylko do odczytu

Odczyt aktualnej temperatury docelowej zgłaszanej przez jednostkę klimatyzacyjną (tylko do odczytu)

numeric Jednostka: °C JSON PARSEJSON()

Nastawa chłodzenia (odczyt)

Odczyt temperatury
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization:Bearer " + Token);
IF(response.IsSuccess = 1)
    VAR state := PARSEJSON(response.Content, "components.main.thermostatCoolingSetpoint.coolingSetpoint.value");
    return(ToDouble(state));
END
Termostat Przełącznik wielowartościowy

Docelowa temperatura chłodzenia — 10 kroków od 18 °C do 27 °C

integer Jednostka: °C JSON PARSEJSON()
Wartości / Stany: 18°C · 19°C · 20°C · 21°C · 22°C · 23°C · 24°C · 25°C · 26°C · 27°C

Termostat

Odczyt stanu przełącznika
VAR response := SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/status", "GET", "", "Authorization:Bearer " + Token);
IF(response.IsSuccess = 1)
    VAR state := PARSEJSON(response.Content, "components.main.thermostatCoolingSetpoint.coolingSetpoint.value");        
    if state = 18
    return(0);
        elseif state = 19
        return(1);
        elseif state = 20
        return(2);
        elseif state = 21
        return(3);
        elseif state = 22
        return(4);
        elseif state = 23
        return(5);
        elseif state = 24
        return(6);
        elseif state = 25
        return(7);
        elseif state = 26
        return(8);
        elseif state = 27
        return(9);            
        end    
END
Zapis stanu przełącznika
VAR localtemperature := SWITCH(Mu, 0, "18", 1, "19", 2, "20", 3, "21", 4, "22", 5, "23", 6, "24", 7, "25", 8, "26", 9, "27", "");

SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/commands", "POST", "{\"commands\":[{\"component\": \"main\", \"capability\": \"thermostatCoolingSetpoint\", \"command\": \"setCoolingSetpoint\", \"arguments\": ["+localtemperature+"]}]}", "Authorization:Bearer " + Token);
Połączenie: Packet Parser → HTTP
Możliwe ulepszenia (5)
  • Dust Level — PM2.5/PM10 dust sensor available on some WindFree models. Not all models support this capability
  • Odor Level — Air quality odor level sensor. Available on select WindFree models with air purification
  • Air Quality — Combined air quality index. Available on WindFree models with built-in air quality sensors
  • Demand Response Load Control — Energy demand response capability for smart grid integration. Allows utility-driven load shedding
  • Auto Cleaning Mode — Automatic self-cleaning function. Available on most WindFree models — enables/disables auto-clean cycle

Źródła