Samsung WindFree AC — Air Conditioning Integration

Samsung WindFree Air Conditioner

Packet Parser → HTTP

Submitted by

Last updated: 04. 2026

Samsung SmartThings Developer Portal

The Samsung WindFree air conditioner template connects TapHome to Samsung split AC units through the Samsung SmartThings cloud API. All communication goes via HTTPS to api.smartthings.com — no local network wiring or protocol adapters are needed. The only requirements are a Samsung account with SmartThings, a Personal Access Token (PAT), and the Device ID of the AC unit.

The template provides 8 devices covering full AC control: power on/off, HVAC mode selection, fan speed, air swing direction, temperature setpoint, room temperature and humidity readback, and Samsung-exclusive preset modes including WindFree and WindFree Sleep.

Configuration

Setting up SmartThings API access

Log into the Samsung SmartThings developer portal at account.smartthings.com/tokens using the Samsung account linked to the AC unit
Click Generate new token
Name the token (e.g. “TapHome”) and select the Devices scope (read + execute)
Click Generate Token and copy the token string — it will not be shown again

Finding the Device ID

The Device ID is a GUID (e.g. a1b2c3d4-e5f6-7890-abcd-ef1234567890) that identifies the specific AC unit in SmartThings.

Open a browser or API tool and send a GET request to:
1
https://api.smartthings.com/v1/devices
with the header Authorization: Bearer <your-token>
Find the Samsung WindFree AC in the response — the deviceId field contains the required GUID
Alternatively, use the SmartThings CLI or the Samsung SmartThings mobile app (Device Info section)

Import parameters

When importing the template in TapHome, enter:

Parameter	Description	Format
Token	SmartThings Personal Access Token	Long alphanumeric string
DeviceId	SmartThings device identifier	UUID / GUID format

SmartThings Personal Access Tokens (PATs) are intended for testing and personal use. They may expire or be revoked. If the token becomes invalid, generate a new one at account.smartthings.com/tokens and update the module variable in TapHome.

Internet dependency

This is a cloud-only integration. All data flows through Samsung SmartThings servers (api.smartthings.com:443). The template requires an active internet connection on the TapHome Core. The AC unit must be registered and online in the SmartThings app.

Device capabilities

Power and HVAC mode

The Power switch turns the AC unit on and off via the SmartThings switch capability.

The HVAC Mode selector provides five operating modes: Heat, Cool, Cool+Heat (auto), Dry and Fan Only. The mode names in TapHome correspond to the SmartThings API values heat, cool, auto, dry and wind.

Fan and airflow control

The Fan Mode selector offers five speeds: Auto, Low, Medium, High and Turbo.

The Swing Mode selector controls air vane oscillation with four options: Fixed (no movement), All (both axes), Vertical and Horizontal.

Preset modes (WindFree)

The Preset Mode selector controls Samsung-specific optional modes via the custom.airConditionerOptionalMode capability. Seven presets are available:

Value	Mode	Description
0	Off	No preset mode active
1	Sleep	Gradual temperature adjustment for nighttime comfort
2	Quiet	Reduced noise operation
3	Smart	AI-based optimization
4	Speed	Rapid cooling or heating
5	WindFree	Air dispersed through thousands of micro-holes — no direct draft
6	WindFree Sleep	Combines WindFree air dispersion with sleep mode

WindFree is a Samsung-proprietary feature unique to the WindFree series. It eliminates direct airflow by dispersing conditioned air through micro-perforations in the front panel.

The Preset Mode device reads status from a dedicated capability endpoint (/v1/devices/{DeviceId}/components/main/capabilities/custom.airConditionerOptionalMode/status) rather than the full device status endpoint, ensuring reliable readback of the active preset.

Temperature control and monitoring

The Thermostat device sets the target cooling temperature using 10 discrete steps from 18 °C to 27 °C. Each step maps to a multi-value switch index (0 = 18 °C, 9 = 27 °C). The SmartThings API supports a wider range (16–30 °C), but the template uses the 18–27 °C subset.

The Cooling Setpoint (Readback) device is a read-only temperature sensor that mirrors the current setpoint as reported by the AC unit. It provides visual feedback in TapHome without write capability — use the Thermostat device to change the temperature.

The Temperature + Humidity sensor reads the room temperature (°C) and relative humidity from the AC unit’s built-in sensors. Humidity is returned as a 0–100 integer by the API and converted to a 0–1 ratio for the TapHome analog input (e.g. 55% becomes 0.55). This device polls at 15-second intervals (slower than the 2.5-second interval used by control devices).

Additional capabilities

Some WindFree models also expose dust level (PM2.5/PM10), odor level and combined air quality sensors, as well as demand response load control and automatic self-cleaning mode. These capabilities are available through the SmartThings API but are not yet implemented in the template. They can be added in a future template update.

Troubleshooting

Authentication errors (HTTP 401)

Verify the Personal Access Token is still valid — PATs can expire or be manually revoked
Regenerate the token at account.smartthings.com/tokens and update the Token variable in the TapHome module settings
Ensure the token has the Devices scope enabled

Device not found (HTTP 404)

Confirm the DeviceId is correct — query GET /v1/devices with the token and verify the GUID
Check that the AC unit is still registered in the SmartThings app and shows as online
If the device was re-added to SmartThings, it may have received a new DeviceId

Rate limiting (HTTP 429)

The SmartThings API enforces rate limits. The template polls control devices every 2.5 seconds and sensors every 15 seconds. If other integrations (Home Assistant, SmartThings automations) share the same account, the combined request rate may exceed the limit. Consider increasing poll intervals in the TapHome template if throttling occurs.

This is a cloud-only integration that depends on Samsung SmartThings server availability and an active internet connection. During cloud outages or internet disruptions, the template cannot read or control the AC unit. There is no local fallback communication path.

Available devices

SmartThings — Samsung WindFree AC Module

Custom Variables

`Token` (string)	SmartThings Personal Access Token — generate at account.smartthings.com/tokens
`DeviceId` (string)	SmartThings Device ID of the Samsung AC unit (GUID format)

Fan Mode Multi-value Switch

Fan speed control — Auto, Low, Medium, High, Turbo

enum JSON PARSEJSON()

Values / States: AUTO · LOW · MEDIUM · HIGH · TURBO

Fan Mode

Read switch state

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

Write switch state

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 Mode Multi-value Switch

Operating mode — Heat, Cool, Cool+Heat (auto), Dry, Fan Only

enum JSON PARSEJSON()

Values / States: OFF · HEAT · COOL · COOL + HEAT · DRY · FAN ONLY

HVAC Mode

Read switch state

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

Write switch state

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

Power Switch

boolean JSON PARSEJSON()

Values / States: ON · OFF

Power

Read switch state

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

Write switch state

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

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

Preset Mode Multi-value Switch

Samsung optional modes — Off, Sleep, Quiet, Smart, Speed, WindFree, WindFree Sleep

enum JSON PARSEJSON()

Values / States: OFF · SLEEP · QUIET · SMART · SPEED · WindFree · WindFreeSleep

Preset Mode

Read switch state

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

Write switch state

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

Swing Mode Multi-value Switch

Air vane oscillation — Fixed, All, Vertical, Horizontal

enum JSON PARSEJSON()

Values / States: FIXED · ALL · VERTICAL · HORIZONTAL

Variable: swing

Swing Mode

Read switch state

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

Write switch state

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

Temperature + Humidity Temperature Sensor Read-only

Room temperature (°C) and relative humidity from the AC unit's built-in sensors

numeric Unit: °C / % JSON PARSEJSON()

Temperature + Humidity

Read humidity

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

Read temperature

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

Cooling Setpoint (Readback) Temperature Sensor Read-only

Read-only feedback of the current target temperature as reported by the AC unit

numeric Unit: °C JSON PARSEJSON()

Cooling Setpoint (Readback)

Read temperature

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 Multi-value Switch

Target cooling temperature — 10 steps from 18 °C to 27 °C

integer Unit: °C JSON PARSEJSON()

Values / States: 18°C · 19°C · 20°C · 21°C · 22°C · 23°C · 24°C · 25°C · 26°C · 27°C

Thermostat

Read switch state

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

Write switch state

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

Connection: Packet Parser → HTTP

Possible improvements (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

Download Template

Sources

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

Samsung WindFree Air Conditioner

Configuration#

Setting up SmartThings API access

Finding the Device ID

Import parameters

Internet dependency

Device capabilities#

Power and HVAC mode

Fan and airflow control

Preset modes (WindFree)

Temperature control and monitoring

Additional capabilities

Troubleshooting#

Authentication errors (HTTP 401)

Device not found (HTTP 404)

Rate limiting (HTTP 429)

Available devices

Fan Mode

HVAC Mode

Power

Preset Mode

Swing Mode

Temperature + Humidity

Cooling Setpoint (Readback)

Thermostat

Sources

Configuration

Device capabilities

Troubleshooting