---
title: "Samsung WindFree Klimatyzator"
description: "Samsung WindFree przez SmartThings cloud API — HVAC, wentylator, lamele, temperatura, tryby WindFree, wilgotność."
url: "https://taphome.com/pl/compatibility/samsung-windfree-air-conditioner/"
language: pl
lastmod: 2026-04-13
generator: hugo
ai:
  topics: ["http","air-conditioning","cloud-api","smartthings","hvac"]
  questions: ["Jak zintegrować klimatyzator Samsung WindFree z TapHome?","Co steruje szablon Samsung WindFree w TapHome?","Jak uzyskać SmartThings Personal Access Token dla TapHome?","Jak znaleźć SmartThings DeviceId dla klimatyzatora Samsung?","Czy TapHome może sterować trybem WindFree na klimatyzatorze Samsung?","Jaki jest zakres ustawień temperatury w szablonie Samsung WindFree?"]
---

# Samsung WindFree Klimatyzator

Komunikacja: Packet Parser → HTTP

- [Portal deweloperski Samsung SmartThings](https://developer.smartthings.com)

## Poradnik integracji

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](https://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:
   ```
   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](https://github.com/SmartThingsCommunity/smartthings-cli) lub aplikacji mobilnej Samsung SmartThings (sekcja Device Info)

### Parametry importu

Podczas importu szablonu w TapHome wprowadź:

| Parametr | Opis | Format |
|----------|------|--------|
| **Token** | SmartThings Personal Access Token | Długi ciąg alfanumeryczny |
| **DeviceId** | Identyfikator urządzenia SmartThings | Format UUID / GUID |

> [!WARNING]
> 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](https://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ść | Tryb | Opis |
|---------|------|------|
| 0 | Off | Brak aktywnego trybu presetu |
| 1 | Sleep | Stopniowa regulacja temperatury dla nocnego komfortu |
| 2 | Quiet | Praca ze zmniejszonym poziomem hałasu |
| 3 | Smart | Optymalizacja oparta na AI |
| 4 | Speed | Szybkie chłodzenie lub ogrzewanie |
| 5 | WindFree | Powietrze rozprowadzane przez tysiące mikro-otworów — brak bezpośredniego przepływu |
| 6 | WindFree Sleep | Połą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.

> [!TIP]
> 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](https://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](https://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.

> [!WARNING]
> 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 8

Te urządzenia pojawią się w TapHome po imporcie.

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 Odczyt i zapis

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

enum JSON PARSEJSON()

Wartości / Stany: AUTO · LOW · MEDIUM · HIGH · TURBO

Odczyt stanu przełącznika

```taphome
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

```taphome
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 Odczyt i zapis

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

enum JSON PARSEJSON()

Wartości / Stany: HEAT · COOL · COOL + HEAT · DRY · FAN ONLY

Odczyt stanu przełącznika

```taphome
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

```taphome
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 Odczyt i zapis

boolean JSON PARSEJSON()

Wartości / Stany: ON · OFF

Odczyt stanu przełącznika

```taphome
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

```taphome
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 Odczyt i zapis

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

enum JSON PARSEJSON()

Wartości / Stany: OFF · SLEEP · QUIET · SMART · SPEED · WindFree · WindFreeSleep

Odczyt stanu przełącznika

```taphome
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

```taphome
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 Odczyt i zapis

Oscylacja lameli kierunkowych — Fixed, All, Vertical, Horizontal

enum JSON PARSEJSON()

Wartości / Stany: FIXED · ALL · VERTICAL · HORIZONTAL

Zmienna: `swing`

Odczyt stanu przełącznika

```taphome
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

```taphome
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()

Odczyt wilgotności

```taphome
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

```taphome
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()

Odczyt temperatury

```taphome
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 Odczyt i zapis

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

Odczyt stanu przełącznika

```taphome
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

```taphome
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

## Parametry importu

Te wartości podajesz podczas importu pliku XML.

| Pytanie w aplikacji | Domyślnie           |
|---------------------|---------------------|
| Token               | Podaj przy imporcie |
| DeviceId            | Podaj przy imporcie |

## Źródła

- SmartThings REST API Reference
  
  [developer.smartthings.com](https://developer.smartthings.com/docs/api/public) 2026-04-13
- Samsung WindFree AC — Home Assistant Integration (visiongeist)
  
  [github.com](https://github.com/visiongeist/samsung-ac-windfree-home-assistant) 2026-04-13
- Samsung AC Controller — Python CLI Tool (CliveMlt)
  
  [github.com](https://github.com/CliveMlt/Samsung-AC-Controller) 2026-04-13

## Powiązana dokumentacja

- [Integracja Packet Parser](https://taphome.com/pl/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/pl/docs/integration/packet-parser/)
- [Funkcje Packet parser](https://taphome.com/pl/docs/script/packet-parser/)
- [Funkcje parsowania](https://taphome.com/pl/docs/script/parsing-functions/)