--- title: "Samsung WindFree Klimaanlage" description: "Samsung WindFree über SmartThings Cloud API steuern — HVAC-Modus, Lüfter, Lamellen, Temperatur, WindFree-Modi, Luftfeuchtigkeit." url: "https://taphome.com/de/compatibility/samsung-windfree-air-conditioner/" language: de lastmod: 2026-04-13 generator: hugo ai: topics: ["http","air-conditioning","cloud-api","smartthings","hvac"] questions: ["Wie integriert man eine Samsung WindFree Klimaanlage mit TapHome?","Was steuert die Samsung WindFree Vorlage in TapHome?","Wie erhält man einen SmartThings Personal Access Token für TapHome?","Wie findet man die SmartThings DeviceId für eine Samsung Klimaanlage?","Kann TapHome den WindFree-Modus der Samsung Klimaanlage steuern?","Welcher Temperaturbereich ist in der Samsung WindFree Vorlage verfügbar?"] --- # Samsung WindFree Klimaanlage Kommunikation: Packet Parser → HTTP - [Samsung SmartThings Developer Portal](https://developer.smartthings.com) ## Integrationsanleitung Die Samsung-WindFree-Klimaanlagen-Vorlage verbindet TapHome über die Samsung SmartThings Cloud API mit Samsung Split-Klimageräten. Die gesamte Kommunikation erfolgt über HTTPS an `api.smartthings.com` — keine lokale Verkabelung oder Protokolladapter erforderlich. Die einzigen Voraussetzungen sind ein Samsung-Konto mit SmartThings, ein Personal Access Token (PAT) und die Device ID des Klimageräts. Die Vorlage bietet 8 Geräte für die vollständige Klimasteuerung: Ein-/Ausschalten, HVAC-Modusauswahl, Lüftergeschwindigkeit, Luftstromrichtung, Temperatursollwert, Rückmeldung von Raumtemperatur und Luftfeuchtigkeit sowie Samsung-exklusive Voreinstellungen einschließlich WindFree und WindFree Sleep. ## Konfiguration ### SmartThings API-Zugang einrichten 1. Melden Sie sich im Samsung SmartThings Developer Portal unter [account.smartthings.com/tokens](https://account.smartthings.com/tokens) mit dem Samsung-Konto an, das mit dem Klimagerät verknüpft ist 2. Klicken Sie auf **Generate new token** 3. Benennen Sie den Token (z. B. "TapHome") und wählen Sie den Scope **Devices** (read + execute) 4. Klicken Sie auf **Generate Token** und kopieren Sie den Token-String — er wird nicht erneut angezeigt ### Device ID ermitteln Die Device ID ist eine GUID (z. B. `a1b2c3d4-e5f6-7890-abcd-ef1234567890`), die das spezifische Klimagerät in SmartThings identifiziert. 1. Öffnen Sie einen Browser oder ein API-Tool und senden Sie einen GET-Request an: ``` https://api.smartthings.com/v1/devices ``` mit dem Header `Authorization: Bearer ` 2. Finden Sie die Samsung WindFree Klimaanlage in der Antwort — das Feld `deviceId` enthält die benötigte GUID 3. Alternativ können Sie die [SmartThings CLI](https://github.com/SmartThingsCommunity/smartthings-cli) oder die Samsung SmartThings Mobile-App (Bereich Device Info) verwenden ### Import-Parameter Beim Import der Vorlage in TapHome geben Sie ein: | Parameter | Beschreibung | Format | |-----------|-------------|--------| | **Token** | SmartThings Personal Access Token | Langer alphanumerischer String | | **DeviceId** | SmartThings Geräte-Identifikator | UUID / GUID Format | > [!WARNING] > SmartThings Personal Access Tokens (PATs) sind für Tests und den persönlichen Gebrauch bestimmt. Sie können ablaufen oder widerrufen werden. Wenn der Token ungültig wird, generieren Sie einen neuen unter [account.smartthings.com/tokens](https://account.smartthings.com/tokens) und aktualisieren Sie die Modulvariable in TapHome. ### Internetabhängigkeit Dies ist eine reine Cloud-Integration. Alle Daten laufen über Samsung SmartThings Server (`api.smartthings.com:443`). Die Vorlage erfordert eine aktive Internetverbindung am TapHome Core. Das Klimagerät muss in der SmartThings App registriert und online sein. ## Gerätefähigkeiten ### Stromversorgung und HVAC-Modus Der **Power**-Schalter schaltet das Klimagerät über die SmartThings Capability `switch` ein und aus. Der **HVAC Mode**-Wahlschalter bietet fünf Betriebsmodi: Heat, Cool, Cool+Heat (auto), Dry und Fan Only. Die Modusnamen in TapHome entsprechen den SmartThings API-Werten `heat`, `cool`, `auto`, `dry` und `wind`. ### Lüfter und Luftstromsteuerung Der **Fan Mode**-Wahlschalter bietet fünf Geschwindigkeiten: Auto, Low, Medium, High und Turbo. Der **Swing Mode**-Wahlschalter steuert die Lamellenoszillation mit vier Optionen: Fixed (keine Bewegung), All (beide Achsen), Vertical und Horizontal. ### Voreinstellungsmodi (WindFree) Der **Preset Mode**-Wahlschalter steuert Samsung-spezifische optionale Modi über die Capability `custom.airConditionerOptionalMode`. Sieben Voreinstellungen sind verfügbar: | Wert | Modus | Beschreibung | |------|-------|-------------| | 0 | Off | Kein Voreinstellungsmodus aktiv | | 1 | Sleep | Schrittweise Temperaturanpassung für nächtlichen Komfort | | 2 | Quiet | Betrieb mit reduziertem Geräuschpegel | | 3 | Smart | KI-basierte Optimierung | | 4 | Speed | Schnelles Kühlen oder Heizen | | 5 | WindFree | Luft wird durch tausende Mikrolöcher verteilt — kein direkter Luftzug | | 6 | WindFree Sleep | Kombination aus WindFree-Luftverteilung und Schlafmodus | WindFree ist eine proprietäre Samsung-Funktion, die einzigartig für die WindFree-Serie ist. Sie eliminiert direkten Luftstrom durch Verteilung der klimatisierten Luft über Mikro-Perforationen im Frontpanel. > [!TIP] > Das Preset Mode-Gerät liest den Status von einem dedizierten Capability-Endpunkt (`/v1/devices/{DeviceId}/components/main/capabilities/custom.airConditionerOptionalMode/status`) statt vom vollständigen Gerätestatus-Endpunkt, was eine zuverlässige Rückmeldung der aktiven Voreinstellung gewährleistet. ### Temperatursteuerung und -überwachung Das **Thermostat**-Gerät setzt die Zielkühltemperatur in 10 diskreten Schritten von 18 °C bis 27 °C. Jeder Schritt entspricht einem Schalterindex (0 = 18 °C, 9 = 27 °C). Die SmartThings API unterstützt einen breiteren Bereich (16–30 °C), aber die Vorlage verwendet die Teilmenge 18–27 °C. Das Gerät **Cooling Setpoint (Readback)** ist ein schreibgeschützter Temperatursensor, der den aktuellen Temperatursollwert des Klimageräts spiegelt. Es bietet visuelle Rückmeldung in TapHome ohne Schreibmöglichkeit — verwenden Sie das Thermostat-Gerät zur Temperaturänderung. Der **Temperature + Humidity**-Sensor liest die Raumtemperatur (°C) und relative Luftfeuchtigkeit von den eingebauten Sensoren des Klimageräts. Die Luftfeuchtigkeit wird als Ganzzahl 0–100 von der API zurückgegeben und in ein Verhältnis 0–1 für den analogen TapHome-Eingang konvertiert (z. B. wird 55 % zu 0,55). Dieses Gerät pollt in 15-Sekunden-Intervallen (langsamer als das 2,5-Sekunden-Intervall der Steuergeräte). ### Weitere Fähigkeiten Einige WindFree-Modelle stellen auch Sensoren für Staubgehalt (PM2.5/PM10), Geruchsniveau und kombinierte Luftqualität bereit, sowie Laststeuerung nach Bedarf und einen automatischen Selbstreinigungsmodus. Diese Fähigkeiten sind über die SmartThings API verfügbar, aber noch nicht in der Vorlage implementiert. Sie können in einem zukünftigen Vorlagen-Update hinzugefügt werden. ## Fehlerbehebung ### Authentifizierungsfehler (HTTP 401) 1. Überprüfen Sie, ob der Personal Access Token noch gültig ist — PATs können ablaufen oder manuell widerrufen werden 2. Generieren Sie einen neuen Token unter [account.smartthings.com/tokens](https://account.smartthings.com/tokens) und aktualisieren Sie die `Token`-Variable in den TapHome-Moduleinstellungen 3. Stellen Sie sicher, dass der Token den Scope **Devices** aktiviert hat ### Gerät nicht gefunden (HTTP 404) 1. Bestätigen Sie, dass die `DeviceId` korrekt ist — senden Sie `GET /v1/devices` mit dem Token und überprüfen Sie die GUID 2. Überprüfen Sie, ob das Klimagerät in der SmartThings App online ist 3. Prüfen Sie, ob das Klimagerät unter demselben Samsung-Konto wie der Token registriert ist ### Gerät reagiert nicht 1. Überprüfen Sie die Internetverbindung des TapHome Core 2. Prüfen Sie, ob der Samsung SmartThings Cloud-Dienst funktioniert (Status unter [status.smartthings.com](https://status.smartthings.com)) 3. Starten Sie das Klimagerät neu und warten Sie, bis es wieder in der SmartThings App erscheint ### Ratenbegrenzung (HTTP 429) Die SmartThings API erzwingt Ratenlimits. Die Vorlage pollt Steuergeräte alle 2,5 Sekunden und Sensoren alle 15 Sekunden. Wenn andere Integrationen (Home Assistant, SmartThings-Automatisierungen) dasselbe Konto nutzen, kann die kombinierte Anfragerate das Limit überschreiten. Erwägen Sie bei Throttling die Erhöhung der Abfrageintervalle in der TapHome-Vorlage. > [!WARNING] > Dies ist eine reine Cloud-Integration, die von der Verfügbarkeit der Samsung SmartThings Server und einer aktiven Internetverbindung abhängt. Bei Cloud-Ausfällen oder Internetunterbrechungen kann die Vorlage das Klimagerät weder auslesen noch steuern. Es gibt keinen lokalen Fallback-Kommunikationsweg. ## Verfügbare Geräte 8 Diese Geräte erscheinen nach dem Import in TapHome. SmartThings — Samsung WindFree AC Modul Benutzerdefinierte Variablen | | | |---------------------|-------------------------------------------------------------------------------------| | `Token` (string) | SmartThings Personal Access Token — generieren unter account.smartthings.com/tokens | | `DeviceId` (string) | SmartThings Device ID des Samsung Klimageräts (GUID-Format) | Lüftermodus Mehrwertschalter Lesen und Schreiben Lüftergeschwindigkeitssteuerung — Auto, Low, Medium, High, Turbo enum JSON PARSEJSON() Werte / Zustände: AUTO · LOW · MEDIUM · HIGH · TURBO Schaltzustand lesen ```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 ``` Schaltzustand schreiben ```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); ``` HVAC-Modus Mehrwertschalter Lesen und Schreiben Betriebsmodus — Heat, Cool, Cool+Heat (auto), Dry, Fan Only enum JSON PARSEJSON() Werte / Zustände: HEAT · COOL · COOL + HEAT · DRY · FAN ONLY Schaltzustand lesen ```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 ``` Schaltzustand schreiben ```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); ``` Stromversorgung Schalter Lesen und Schreiben boolean JSON PARSEJSON() Werte / Zustände: ON · OFF Schaltzustand lesen ```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 ``` Schaltzustand schreiben ```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); ``` Voreinstellungsmodus Mehrwertschalter Lesen und Schreiben Samsung optionale Modi — Off, Sleep, Quiet, Smart, Speed, WindFree, WindFree Sleep enum JSON PARSEJSON() Werte / Zustände: OFF · SLEEP · QUIET · SMART · SPEED · WindFree · WindFreeSleep Schaltzustand lesen ```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 ``` Schaltzustand schreiben ```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); ``` Schwenkmodus Mehrwertschalter Lesen und Schreiben Lamellenoszillation — Fixed, All, Vertical, Horizontal enum JSON PARSEJSON() Werte / Zustände: FIXED · ALL · VERTICAL · HORIZONTAL Variable: `swing` Schaltzustand lesen ```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 ``` Schaltzustand schreiben ```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); ``` Temperatur + Luftfeuchtigkeit Temperatursensor Nur lesen Raumtemperatur (°C) und relative Luftfeuchtigkeit von den eingebauten Sensoren des Klimageräts numeric Einheit: °C / % JSON PARSEJSON() Luftfeuchtigkeit lesen ```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 ``` Temperatur lesen ```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 ``` Kühlsollwert (Rückmeldung) Temperatursensor Nur lesen Schreibgeschützte Rückmeldung der aktuellen Zieltemperatur vom Klimagerät numeric Einheit: °C JSON PARSEJSON() Temperatur lesen ```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 ``` Thermostat Mehrwertschalter Lesen und Schreiben Zielkühltemperatur — 10 Stufen von 18 °C bis 27 °C integer Einheit: °C JSON PARSEJSON() Werte / Zustände: 18°C · 19°C · 20°C · 21°C · 22°C · 23°C · 24°C · 25°C · 26°C · 27°C Schaltzustand lesen ```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 ``` Schaltzustand schreiben ```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); ``` **Verbindung:** Packet Parser → HTTP Mögliche Verbesserungen (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 ## Importparameter Diese Werte geben Sie beim Import des XML ein. | In der App abgefragt | Standard | |----------------------|----------------------| | Token | Beim Import eingeben | | DeviceId | Beim Import eingeben | ## Quellen - 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 ## Verwandte Dokumentation - [Packet-Parser-Integration](https://taphome.com/de/compatibility/packet-parser-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/de/docs/integration/packet-parser/) - [Packet-Parser-Funktionen](https://taphome.com/de/docs/script/packet-parser/) - [Parsing-Funktionen](https://taphome.com/de/docs/script/parsing-functions/)