Samsung WindFree — Klimaanlagen-Integration

Samsung WindFree Klimaanlage

Packet Parser → HTTP

Eingereicht von

Zuletzt aktualisiert: 04. 2026

Samsung SmartThings Developer Portal

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

Melden Sie sich im Samsung SmartThings Developer Portal unter account.smartthings.com/tokens mit dem Samsung-Konto an, das mit dem Klimagerät verknüpft ist
Klicken Sie auf Generate new token
Benennen Sie den Token (z. B. “TapHome”) und wählen Sie den Scope Devices (read + execute)
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.

Öffnen Sie einen Browser oder ein API-Tool und senden Sie einen GET-Request an:
1
https://api.smartthings.com/v1/devices
mit dem Header Authorization: Bearer <Ihr-Token>
Finden Sie die Samsung WindFree Klimaanlage in der Antwort — das Feld deviceId enthält die benötigte GUID
Alternativ können Sie die 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

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

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)

Überprüfen Sie, ob der Personal Access Token noch gültig ist — PATs können ablaufen oder manuell widerrufen werden
Generieren Sie einen neuen Token unter account.smartthings.com/tokens und aktualisieren Sie die Token-Variable in den TapHome-Moduleinstellungen
Stellen Sie sicher, dass der Token den Scope Devices aktiviert hat

Gerät nicht gefunden (HTTP 404)

Bestätigen Sie, dass die DeviceId korrekt ist — senden Sie GET /v1/devices mit dem Token und überprüfen Sie die GUID
Überprüfen Sie, ob das Klimagerät in der SmartThings App online ist
Prüfen Sie, ob das Klimagerät unter demselben Samsung-Konto wie der Token registriert ist

Gerät reagiert nicht

Überprüfen Sie die Internetverbindung des TapHome Core
Prüfen Sie, ob der Samsung SmartThings Cloud-Dienst funktioniert (Status unter status.smartthings.com)
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.

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

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

Lüftergeschwindigkeitssteuerung — Auto, Low, Medium, High, Turbo

enum JSON PARSEJSON()

Werte / Zustände: AUTO · LOW · MEDIUM · HIGH · TURBO

Lüftermodus

Schaltzustand lesen

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

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

Betriebsmodus — Heat, Cool, Cool+Heat (auto), Dry, Fan Only

enum JSON PARSEJSON()

Werte / Zustände: OFF · HEAT · COOL · COOL + HEAT · DRY · FAN ONLY

HVAC-Modus

Schaltzustand lesen

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

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

boolean JSON PARSEJSON()

Werte / Zustände: ON · OFF

Stromversorgung

Schaltzustand lesen

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

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

Samsung optionale Modi — Off, Sleep, Quiet, Smart, Speed, WindFree, WindFree Sleep

enum JSON PARSEJSON()

Werte / Zustände: OFF · SLEEP · QUIET · SMART · SPEED · WindFree · WindFreeSleep

Voreinstellungsmodus

Schaltzustand lesen

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

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

Lamellenoszillation — Fixed, All, Vertical, Horizontal

enum JSON PARSEJSON()

Werte / Zustände: FIXED · ALL · VERTICAL · HORIZONTAL

Variable: swing

Schwenkmodus

Schaltzustand lesen

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

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

Temperatur + Luftfeuchtigkeit

Luftfeuchtigkeit lesen

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

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

Kühlsollwert (Rückmeldung)

Temperatur lesen

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

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

Thermostat

Schaltzustand lesen

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

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

Vorlage herunterladen

Quellen

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