---
title: "Samsung WindFree Air Conditioner"
description: "Samsung WindFree split AC in TapHome via the SmartThings cloud API: power, mode, fan, swing, setpoint and WindFree modes. Needs a Personal Access Token."
url: "https://taphome.com/en/compatibility/samsung-windfree-air-conditioner/"
language: en
lastmod: 2026-04-13
generator: hugo
ai:
  topics: ["http","air-conditioning","cloud-api","smartthings","hvac"]
  questions: ["How to integrate Samsung WindFree air conditioner with TapHome?","What does the Samsung WindFree TapHome template control?","How to obtain a SmartThings Personal Access Token for TapHome?","How to find the SmartThings DeviceId for a Samsung air conditioner?","Can TapHome control WindFree mode on Samsung AC?","What is the temperature setpoint range in the Samsung WindFree template?"]
---

# Samsung WindFree Air Conditioner

Communication: Packet Parser → HTTP

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

## Integration guide

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

1. Log into the Samsung SmartThings developer portal at [account.smartthings.com/tokens](https://account.smartthings.com/tokens) using the Samsung account linked to the AC unit
2. Click **Generate new token**
3. Name the token (e.g. "TapHome") and select the **Devices** scope (read + execute)
4. 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.

1. Open a browser or API tool and send a GET request to:
   ```
   https://api.smartthings.com/v1/devices
   ```
   with the header `Authorization: Bearer <your-token>`
2. Find the Samsung WindFree AC in the response — the `deviceId` field contains the required GUID
3. Alternatively, use the [SmartThings CLI](https://github.com/SmartThingsCommunity/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 |

> [!WARNING]
> 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](https://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.

> [!TIP]
> 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)

1. Verify the Personal Access Token is still valid — PATs can expire or be manually revoked
2. Regenerate the token at [account.smartthings.com/tokens](https://account.smartthings.com/tokens) and update the `Token` variable in the TapHome module settings
3. Ensure the token has the **Devices** scope enabled

### Device not found (HTTP 404)

1. Confirm the `DeviceId` is correct — query `GET /v1/devices` with the token and verify the GUID
2. Check that the AC unit is still registered in the SmartThings app and shows as online
3. 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.

> [!WARNING]
> 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 8

These devices appear in TapHome after import.

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 Read and write

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

enum JSON PARSEJSON()

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

Read switch state

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

Write switch state

```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 Mode Multi-value Switch Read and write

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

enum JSON PARSEJSON()

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

Read switch state

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

Write switch state

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

Power Switch Read and write

boolean JSON PARSEJSON()

Values / States: ON · OFF

Read switch state

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

Write switch state

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

Preset Mode Multi-value Switch Read and write

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

enum JSON PARSEJSON()

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

Read switch state

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

Write switch state

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

Swing Mode Multi-value Switch Read and write

Air vane oscillation — Fixed, All, Vertical, Horizontal

enum JSON PARSEJSON()

Values / States: FIXED · ALL · VERTICAL · HORIZONTAL

Variable: `swing`

Read switch state

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

Write switch state

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

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

Read humidity

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

Read temperature

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

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

Read temperature

```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 Multi-value Switch Read and write

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

Read switch state

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

Write switch state

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

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

## Import parameters

Enter these values when you import the XML.

| Asked in the app | Default         |
|------------------|-----------------|
| Token            | Enter at import |
| DeviceId         | Enter at import |

## Sources

- 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

## Related Documentation

- [Packet Parser Integration](https://taphome.com/en/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/en/docs/integration/packet-parser/)
- [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/)
- [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/)