Samsung WindFree — Klíma integráció

Samsung WindFree Klíma

Packet Parser → HTTP

Beküldő

Utoljára frissítve: 04. 2026

Samsung SmartThings fejlesztői portál

A Samsung WindFree klíma sablon a TapHome-ot a Samsung SmartThings cloud API-n keresztül köti össze a Samsung split klímaberendezésekkel. A teljes kommunikáció HTTPS-en keresztül zajlik az api.smartthings.com felé — nincs szükség helyi hálózati kábelezésre vagy protokolladapterre. Az egyetlen követelmény egy SmartThings-hez kapcsolt Samsung fiók, egy Personal Access Token (PAT) és a klímaegység Device ID-je.

A sablon 8 eszközt biztosít a teljes klímavezérléshez: be-/kikapcsolás, HVAC mód kiválasztása, ventilátorsebesség, légáramlás iránya, hőmérséklet-célérték, szobahőmérséklet és páratartalom visszaolvasása, valamint Samsung-exkluzív előbeállítások, beleértve a WindFree és WindFree Sleep módokat.

Konfiguráció

SmartThings API hozzáférés beállítása

Jelentkezz be a Samsung SmartThings fejlesztői portálra az account.smartthings.com/tokens oldalon a klímaegységhez kapcsolt Samsung fiókkal
Kattints a Generate new token gombra
Nevezd el a tokent (pl. “TapHome”) és válaszd ki a Devices scope-ot (read + execute)
Kattints a Generate Token gombra és másold ki a token stringet — nem jelenik meg újra

Device ID megkeresése

A Device ID egy GUID (pl. a1b2c3d4-e5f6-7890-abcd-ef1234567890), amely a klímaegységet azonosítja a SmartThings rendszerben.

Nyiss meg egy böngészőt vagy API eszközt, és küldj egy GET kérést a következő címre:
1
https://api.smartthings.com/v1/devices
az Authorization: Bearer <a-tokened> fejléccel
Keresd meg a Samsung WindFree klímát a válaszban — a deviceId mező tartalmazza a szükséges GUID-ot
Alternatívaként használhatod a SmartThings CLI-t vagy a Samsung SmartThings mobilalkalmazást (Device Info szekció)

Import paraméterek

A sablon importálásakor a TapHome-ban add meg:

Paraméter	Leírás	Formátum
Token	SmartThings Personal Access Token	Hosszú alfanumerikus string
DeviceId	SmartThings eszközazonosító	UUID / GUID formátum

A SmartThings Personal Access Tokenek (PAT) tesztelésre és személyes használatra szolgálnak. Lejárhatnak vagy visszavonhatók. Ha a token érvénytelenné válik, generálj újat az account.smartthings.com/tokens oldalon, és frissítsd a modul változót a TapHome-ban.

Internet-függőség

Ez egy kizárólag felhőalapú integráció. Minden adat a Samsung SmartThings szervereken (api.smartthings.com:443) halad keresztül. A sablon aktív internetkapcsolatot igényel a TapHome Core-on. A klímaegységnek regisztráltnak és online-nak kell lennie a SmartThings alkalmazásban.

Eszközképességek

Tápellátás és HVAC mód

A Power kapcsoló a SmartThings switch capability-n keresztül kapcsolja be és ki a klímaegységet.

A HVAC Mode választó öt üzemmódot kínál: Heat, Cool, Cool+Heat (auto), Dry és Fan Only. A módnevek a TapHome-ban a SmartThings API heat, cool, auto, dry és wind értékeinek felelnek meg.

Ventilátor és légáramlás vezérlése

A Fan Mode választó öt sebességet kínál: Auto, Low, Medium, High és Turbo.

A Swing Mode választó a légterelő lamellák oszcillációját vezérli négy opcióval: Fixed (nincs mozgás), All (mindkét tengely), Vertical és Horizontal.

Előbeállított módok (WindFree)

A Preset Mode választó a Samsung-specifikus opcionális módokat vezérli a custom.airConditionerOptionalMode capability-n keresztül. Hét előbeállítás érhető el:

Érték	Mód	Leírás
0	Off	Nincs aktív előbeállított mód
1	Sleep	Fokozatos hőmérséklet-beállítás az éjszakai kényelem érdekében
2	Quiet	Csökkentett zajszintű üzemeltetés
3	Smart	AI-alapú optimalizáció
4	Speed	Gyors hűtés vagy fűtés
5	WindFree	A levegő több ezer mikro-nyíláson keresztül oszlik el — nincs közvetlen légáram
6	WindFree Sleep	A WindFree légoszlás kombinálása alvás móddal

A WindFree a Samsung szabadalmaztatott funkciója, amely a WindFree sorozatra jellemző. Kiküszöböli a közvetlen légáramlást azáltal, hogy a klimatizált levegőt a front panel mikro-perforációin keresztül osztja el.

A Preset Mode eszköz a státuszt egy dedikált capability végpontról (/v1/devices/{DeviceId}/components/main/capabilities/custom.airConditionerOptionalMode/status) olvassa a teljes eszközstátusz végpont helyett, ezzel biztosítva az aktív előbeállítás megbízható visszaolvasását.

Hőmérséklet-vezérlés és -monitorozás

A Thermostat eszköz 10 diszkrét lépésben állítja be a hűtési célhőmérsékletet 18 °C-tól 27 °C-ig. Minden lépés egy kapcsolóindexnek felel meg (0 = 18 °C, 9 = 27 °C). A SmartThings API szélesebb tartományt támogat (16–30 °C), de a sablon a 18–27 °C részt használja.

A Cooling Setpoint (Readback) eszköz egy csak olvasható hőmérséklet-szenzor, amely a klímaegység által jelentett aktuális célhőmérsékletet tükrözi. Vizuális visszajelzést nyújt a TapHome-ban írási lehetőség nélkül — a hőmérséklet megváltoztatásához használd a Thermostat eszközt.

A Temperature + Humidity szenzor a szobahőmérsékletet (°C) és a relatív páratartalmat olvassa a klímaegység beépített szenzoraiból. A páratartalmat az API 0–100 egész számként adja vissza, és a TapHome analóg bemenetéhez 0–1 arányra konvertálja (pl. 55 % = 0,55). Ez az eszköz 15 másodperces intervallumokban polloz (lassabban, mint a vezérlőeszközök 2,5 másodperces intervalluma).

További képességek

Egyes WindFree modellek porszint- (PM2.5/PM10), szagszint- és kombinált levegőminőség-szenzorokat is elérhetővé tesznek, valamint igényvezérelt terhelésvezérlést és automatikus öntisztító módot. Ezek a képességek elérhetők a SmartThings API-n keresztül, de jelenleg nincsenek implementálva a sablonban. Egy jövőbeli sablonfrissítésben adhatók hozzá.

Hibaelhárítás

Hitelesítési hibák (HTTP 401)

Ellenőrizd, hogy a Personal Access Token még érvényes-e — a PAT tokenek lejárhatnak vagy manuálisan visszavonhatók
Generálj új tokent az account.smartthings.com/tokens oldalon, és frissítsd a Token változót a TapHome modulbeállításaiban
Győződj meg róla, hogy a token rendelkezik a Devices scope-pal

Eszköz nem található (HTTP 404)

Ellenőrizd, hogy a DeviceId helyes-e — küldj GET /v1/devices kérést a tokennel, és ellenőrizd a GUID-ot
Ellenőrizd, hogy a klímaegység online-e a SmartThings alkalmazásban
Ellenőrizd, hogy a klímaegység ugyanahhoz a Samsung fiókhoz van-e regisztrálva, mint a token

Az eszköz nem reagál

Ellenőrizd a TapHome Core internetkapcsolatát
Ellenőrizd, hogy a Samsung SmartThings felhőszolgáltatás működik-e (állapot: status.smartthings.com)
Indítsd újra a klímaegységet, és várd meg, amíg újra megjelenik a SmartThings alkalmazásban

Kérésszám-korlátozás (HTTP 429)

A SmartThings API kérésszám-korlátokat érvényesít. A sablon a vezérlőeszközöket 2,5 másodpercenként, a szenzorokat 15 másodpercenként pollozza. Ha más integrációk (Home Assistant, SmartThings automatizálások) ugyanazt a fiókot használják, az összesített kérésfrekvencia meghaladhatja a korlátot. Throttling esetén fontold meg a lekérdezési intervallumok növelését a TapHome sablonban.

Ez egy kizárólag felhőalapú integráció, amely a Samsung SmartThings szerverek elérhetőségétől és aktív internetkapcsolattól függ. Felhőkimaradások vagy internetszakadások során a sablon nem tudja olvasni vagy vezérelni a klímaegységet. Nincs helyi tartalék kommunikációs útvonal.

Elérhető eszközök

SmartThings — Samsung WindFree AC Modul

Egyéni változók

`Token` (string)	SmartThings Personal Access Token — generáld az account.smartthings.com/tokens oldalon
`DeviceId` (string)	A Samsung klímaegység SmartThings Device ID-je (GUID formátum)

Ventilátor mód Többértékű kapcsoló

Ventilátorsebesség vezérlése — Auto, Low, Medium, High, Turbo

enum JSON PARSEJSON()

Értékek / Állapotok: AUTO · LOW · MEDIUM · HIGH · TURBO

Ventilátor mód

Kapcsoló állapot olvasása

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

Kapcsoló állapot írása

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

HVAC mód Többértékű kapcsoló

Üzemmód — Heat, Cool, Cool+Heat (auto), Dry, Fan Only

enum JSON PARSEJSON()

Értékek / Állapotok: OFF · HEAT · COOL · COOL + HEAT · DRY · FAN ONLY

HVAC mód

Kapcsoló állapot olvasása

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

Kapcsoló állapot írása

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

Tápellátás Kapcsoló

boolean JSON PARSEJSON()

Értékek / Állapotok: ON · OFF

Tápellátás

Kapcsoló állapot olvasása

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

Kapcsoló állapot írása

VAR localpower := SWITCH(St, 0, "off", 1, "on", "");

SENDHTTPREQUEST("/v1/devices/"+DeviceId+"/commands", "POST", "{\"commands\":[{\"component\": \"main\", \"capability\": \"switch\", \"command\": \""+localpower+"\"}]}", "Authorization:Bearer " + Token);

Előbeállított mód Többértékű kapcsoló

Samsung opcionális módok — Off, Sleep, Quiet, Smart, Speed, WindFree, WindFree Sleep

enum JSON PARSEJSON()

Értékek / Állapotok: OFF · SLEEP · QUIET · SMART · SPEED · WindFree · WindFreeSleep

Előbeállított mód

Kapcsoló állapot olvasása

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

Kapcsoló állapot írása

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

Lamella mód Többértékű kapcsoló

Légterelő lamellák oszcillációja — Fixed, All, Vertical, Horizontal

enum JSON PARSEJSON()

Értékek / Állapotok: FIXED · ALL · VERTICAL · HORIZONTAL

Változó: swing

Lamella mód

Kapcsoló állapot olvasása

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

Kapcsoló állapot írása

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

Hőmérséklet + Páratartalom Hőmérséklet-érzékelő Csak olvasható

Szobahőmérséklet (°C) és relatív páratartalom a klímaegység beépített szenzoraiból

numeric Egység: °C / % JSON PARSEJSON()

Hőmérséklet + Páratartalom

Páratartalom olvasása

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

Hőmérséklet olvasása

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

Hűtési célérték (visszaolvasás) Hőmérséklet-érzékelő Csak olvasható

A klímaegység által jelentett aktuális célhőmérséklet visszaolvasása (csak olvasható)

numeric Egység: °C JSON PARSEJSON()

Hűtési célérték (visszaolvasás)

Hőmérséklet olvasása

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

Termosztát Többértékű kapcsoló

Hűtési célhőmérséklet — 10 lépés 18 °C-tól 27 °C-ig

integer Egység: °C JSON PARSEJSON()

Értékek / Állapotok: 18°C · 19°C · 20°C · 21°C · 22°C · 23°C · 24°C · 25°C · 26°C · 27°C

Termosztát

Kapcsoló állapot olvasása

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

Kapcsoló állapot írása

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

Kapcsolat: Packet Parser → HTTP

Lehetséges fejlesztések (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

Sablon letöltése

Források

SmartThings REST API Reference
developer.smartthings.com 2026-04-13
Samsung WindFree AC — Home Assistant Integration (visiongeist)
github.com 2026-04-13
Samsung AC Controller — Python CLI Tool (CliveMlt)
github.com 2026-04-13