---
title: "Samsung WindFree Klimatizace"
description: "Ovládání Samsung WindFree přes SmartThings cloud API — HVAC, ventilátor, lamely, teplota, WindFree režimy, vlhkost."
url: "https://taphome.com/cs/compatibility/samsung-windfree-air-conditioner/"
language: cs
lastmod: 2026-04-13
generator: hugo
ai:
  topics: ["http","air-conditioning","cloud-api","smartthings","hvac"]
  questions: ["Jak integrovat klimatizaci Samsung WindFree s TapHome?","Co ovládá šablona Samsung WindFree v TapHome?","Jak získat SmartThings Personal Access Token pro TapHome?","Jak najít SmartThings DeviceId pro klimatizaci Samsung?","Může TapHome ovládat režim WindFree na klimatizaci Samsung?","Jaký je rozsah nastavení teploty v šabloně Samsung WindFree?"]
---

# Samsung WindFree Klimatizace

Komunikace: Packet Parser → HTTP

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

## Návod na integraci

Šablona Samsung WindFree klimatizace propojí TapHome se split klimatizačními jednotkami Samsung prostřednictvím Samsung SmartThings cloud API. Veškerá komunikace probíhá přes HTTPS na `api.smartthings.com` — není potřeba žádná lokální kabeláž ani protokolové adaptéry. Jediné požadavky jsou Samsung účet se SmartThings, Personal Access Token (PAT) a Device ID klimatizační jednotky.

Šablona poskytuje 8 zařízení pokrývajících kompletní ovládání klimatizace: zapnutí/vypnutí, výběr režimu HVAC, rychlost ventilátoru, směr proudění vzduchu, nastavení cílové teploty, zpětné čtení teploty a vlhkosti místnosti a exkluzivní Samsung předvolby včetně WindFree a WindFree Sleep.

## Konfigurace

### Nastavení přístupu ke SmartThings API

1. Přihlaste se do Samsung SmartThings developer portálu na [account.smartthings.com/tokens](https://account.smartthings.com/tokens) pomocí Samsung účtu propojeného s klimatizační jednotkou
2. Klikněte na **Generate new token**
3. Pojmenujte token (např. "TapHome") a vyberte scope **Devices** (read + execute)
4. Klikněte na **Generate Token** a zkopírujte řetězec tokenu — nebude znovu zobrazen

### Zjištění Device ID

Device ID je GUID (např. `a1b2c3d4-e5f6-7890-abcd-ef1234567890`), který identifikuje konkrétní klimatizační jednotku ve SmartThings.

1. Otevřete prohlížeč nebo API nástroj a odešlete GET request na:
   ```
   https://api.smartthings.com/v1/devices
   ```
   s hlavičkou `Authorization: Bearer <váš-token>`
2. Najděte Samsung WindFree klimatizaci v odpovědi — pole `deviceId` obsahuje požadovaný GUID
3. Alternativně použijte [SmartThings CLI](https://github.com/SmartThingsCommunity/smartthings-cli) nebo Samsung SmartThings mobilní aplikaci (sekce Device Info)

### Importní parametry

Při importu šablony v TapHome zadejte:

| Parametr | Popis | Formát |
|----------|-------|--------|
| **Token** | SmartThings Personal Access Token | Dlouhý alfanumerický řetězec |
| **DeviceId** | SmartThings identifikátor zařízení | UUID / GUID formát |

> [!WARNING]
> SmartThings Personal Access Tokeny (PAT) jsou určeny pro testování a osobní použití. Mohou expirovat nebo být zrušeny. Pokud se token stane neplatným, vygenerujte nový na [account.smartthings.com/tokens](https://account.smartthings.com/tokens) a aktualizujte proměnnou modulu v TapHome.

### Závislost na internetu

Jedná se o čistě cloudovou integraci. Veškerá data procházejí přes Samsung SmartThings servery (`api.smartthings.com:443`). Šablona vyžaduje aktivní internetové připojení na TapHome Core. Klimatizační jednotka musí být zaregistrovaná a online v SmartThings aplikaci.

## Schopnosti zařízení

### Napájení a režim HVAC

Spínač **Power** zapíná a vypíná klimatizační jednotku přes SmartThings capability `switch`.

Přepínač **HVAC Mode** nabízí pět provozních režimů: Heat, Cool, Cool+Heat (auto), Dry a Fan Only. Názvy režimů v TapHome odpovídají hodnotám SmartThings API `heat`, `cool`, `auto`, `dry` a `wind`.

### Ventilátor a proudění vzduchu

Přepínač **Fan Mode** nabízí pět rychlostí: Auto, Low, Medium, High a Turbo.

Přepínač **Swing Mode** ovládá oscilaci vzduchových lamel se čtyřmi možnostmi: Fixed (bez pohybu), All (obě osy), Vertical a Horizontal.

### Přednastavené režimy (WindFree)

Přepínač **Preset Mode** ovládá Samsung-specifické volitelné režimy přes capability `custom.airConditionerOptionalMode`. K dispozici je sedm předvoleb:

| Hodnota | Režim | Popis |
|---------|-------|-------|
| 0 | Off | Žádný přednastavený režim není aktivní |
| 1 | Sleep | Postupná úprava teploty pro noční komfort |
| 2 | Quiet | Provoz se sníženým hlukem |
| 3 | Smart | Optimalizace na bázi AI |
| 4 | Speed | Rychlé chlazení nebo vytápění |
| 5 | WindFree | Vzduch rozptýlený přes tisíce mikro-otvorů — bez přímého proudění |
| 6 | WindFree Sleep | Kombinace WindFree rozptylu vzduchu s režimem spánku |

WindFree je proprietární funkce Samsung unikátní pro sérii WindFree. Eliminuje přímé proudění vzduchu rozptýlením klimatizovaného vzduchu přes mikro-perforace v předním panelu.

> [!TIP]
> Zařízení Preset Mode čte stav z dedikovaného capability endpointu (`/v1/devices/{DeviceId}/components/main/capabilities/custom.airConditionerOptionalMode/status`) namísto z plného endpointu stavu zařízení, čímž zajišťuje spolehlivé zpětné čtení aktivní předvolby.

### Ovládání a monitorování teploty

Zařízení **Thermostat** nastavuje cílovou teplotu chlazení pomocí 10 diskrétních kroků od 18 °C do 27 °C. Každý krok odpovídá indexu přepínače (0 = 18 °C, 9 = 27 °C). SmartThings API podporuje širší rozsah (16–30 °C), ale šablona používá podmnožinu 18–27 °C.

Zařízení **Cooling Setpoint (Readback)** je teplotní senzor pouze pro čtení, který zrcadlí aktuální nastavený bod teploty hlášený klimatizační jednotkou. Poskytuje vizuální zpětnou vazbu v TapHome bez možnosti zápisu — ke změně teploty použijte zařízení Thermostat.

Senzor **Temperature + Humidity** čte pokojovou teplotu (°C) a relativní vlhkost z vestavěných senzorů klimatizační jednotky. Vlhkost je vrácena jako celé číslo 0–100 z API a konvertována na poměr 0–1 pro analogový vstup TapHome (např. 55 % se stává 0.55). Toto zařízení polluje v 15sekundových intervalech (pomaleji než 2,5sekundový interval ovládacích zařízení).

### Další schopnosti

Některé modely WindFree také zpřístupňují senzory úrovně prachu (PM2.5/PM10), úrovně zápachu a kombinované kvality vzduchu, stejně jako řízení zátěže podle poptávky a automatický samočisticí režim. Tyto schopnosti jsou dostupné přes SmartThings API, ale zatím nejsou implementovány v šabloně. Mohou být přidány v budoucí aktualizaci šablony.

## Řešení problémů

### Chyby autentizace (HTTP 401)

1. Ověřte, zda je Personal Access Token stále platný — PAT tokeny mohou expirovat nebo být manuálně zrušeny
2. Vygenerujte nový token na [account.smartthings.com/tokens](https://account.smartthings.com/tokens) a aktualizujte proměnnou `Token` v nastavení modulu TapHome
3. Ujistěte se, že token má povolený scope **Devices**

### Zařízení nenalezeno (HTTP 404)

1. Potvrďte, že `DeviceId` je správný — odešlete dotaz `GET /v1/devices` s tokenem a ověřte GUID
2. Ověřte, že klimatizační jednotka je online ve SmartThings aplikaci
3. Zkontrolujte, zda je AC jednotka zaregistrovaná pod stejným Samsung účtem jako token

### Zařízení nereaguje

1. Ověřte internetové připojení na TapHome Core
2. Zkontrolujte, zda Samsung SmartThings cloud služba funguje (stav na [status.smartthings.com](https://status.smartthings.com))
3. Restartujte klimatizační jednotku a počkejte, až se znovu objeví ve SmartThings aplikaci

### Omezení počtu požadavků (HTTP 429)

SmartThings API vynucuje limity počtu požadavků. Šablona polluje ovládací zařízení každých 2,5 sekundy a senzory každých 15 sekund. Pokud další integrace (Home Assistant, SmartThings automatizace) sdílejí stejný účet, kombinovaná frekvence požadavků může překročit limit. V případě throttlingu zvažte zvýšení intervalů pollování v TapHome šabloně.

> [!WARNING]
> Jedná se o čistě cloudovou integraci závislou na dostupnosti Samsung SmartThings serverů a aktivním internetovém připojení. Během výpadků cloudu nebo přerušení internetu šablona nemůže číst ani ovládat klimatizační jednotku. Neexistuje žádná lokální záložní komunikační cesta.

## Dostupná zařízení 8

Tato zařízení se po importu zobrazí v TapHome.

SmartThings — Samsung WindFree AC Modul

Vlastní proměnné

|                     |                                                                                   |
|---------------------|-----------------------------------------------------------------------------------|
| `Token` (string)    | SmartThings Personal Access Token — vygenerujte na account.smartthings.com/tokens |
| `DeviceId` (string) | SmartThings Device ID klimatizační jednotky Samsung (GUID formát)                 |

Režim ventilátoru Vícestavový přepínač Čtení i zápis

Ovládání rychlosti ventilátoru — Auto, Low, Medium, High, Turbo

enum JSON PARSEJSON()

Hodnoty / Stavy: AUTO · LOW · MEDIUM · HIGH · TURBO

Čtení stavu přepínače

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

Zápis stavu přepínače

```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);
```

Režim HVAC Vícestavový přepínač Čtení i zápis

Provozní režim — Heat, Cool, Cool+Heat (auto), Dry, Fan Only

enum JSON PARSEJSON()

Hodnoty / Stavy: HEAT · COOL · COOL + HEAT · DRY · FAN ONLY

Čtení stavu přepínače

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

Zápis stavu přepínače

```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);
```

Napájení Přepínač Čtení i zápis

boolean JSON PARSEJSON()

Hodnoty / Stavy: ON · OFF

Čtení stavu přepínače

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

Zápis stavu přepínače

```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);
```

Přednastavený režim Vícestavový přepínač Čtení i zápis

Volitelné režimy Samsung — Off, Sleep, Quiet, Smart, Speed, WindFree, WindFree Sleep

enum JSON PARSEJSON()

Hodnoty / Stavy: OFF · SLEEP · QUIET · SMART · SPEED · WindFree · WindFreeSleep

Čtení stavu přepínače

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

Zápis stavu přepínače

```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);
```

Režim lamel Vícestavový přepínač Čtení i zápis

Oscilace vzduchových lamel — Fixed, All, Vertical, Horizontal

enum JSON PARSEJSON()

Hodnoty / Stavy: FIXED · ALL · VERTICAL · HORIZONTAL

Proměnná: `swing`

Čtení stavu přepínače

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

Zápis stavu přepínače

```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);
```

Teplota + Vlhkost Teplotní senzor Pouze ke čtení

Pokojová teplota (°C) a relativní vlhkost z vestavěných senzorů klimatizační jednotky

numeric Jednotka: °C / % JSON PARSEJSON()

Čtení vlhkosti

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

Čtení teploty

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

Nastavená teplota (zpětné čtení) Teplotní senzor Pouze ke čtení

Zpětné čtení aktuální cílové teploty hlášené klimatizační jednotkou (pouze ke čtení)

numeric Jednotka: °C JSON PARSEJSON()

Čtení teploty

```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 Vícestavový přepínač Čtení i zápis

Cílová teplota chlazení — 10 kroků od 18 °C do 27 °C

integer Jednotka: °C JSON PARSEJSON()

Hodnoty / Stavy: 18°C · 19°C · 20°C · 21°C · 22°C · 23°C · 24°C · 25°C · 26°C · 27°C

Čtení stavu přepínače

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

Zápis stavu přepínače

```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);
```

**Připojení:** Packet Parser → HTTP

Možná vylepšení (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

Tyto hodnoty zadáte při importu XML.

| Ptá se v aplikaci | Výchozí            |
|-------------------|--------------------|
| Token             | Zadáte při importu |
| DeviceId          | Zadáte při importu |

## Zdroje

- 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

## Související dokumentace

- [Integrace Packet Parser](https://taphome.com/cs/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/cs/docs/integration/packet-parser/)
- [Funkce Packet parser](https://taphome.com/cs/docs/script/packet-parser/)
- [Funkce pro parsování](https://taphome.com/cs/docs/script/parsing-functions/)