Samsung WindFree — Integrazione condizionatore

Samsung WindFree Condizionatore

Packet Parser → HTTP

Inviato da

Ultimo aggiornamento: 04. 2026

Portale sviluppatori Samsung SmartThings

Il template Samsung WindFree per condizionatori collega TapHome alle unità split Samsung tramite la Samsung SmartThings cloud API. Tutta la comunicazione avviene via HTTPS verso api.smartthings.com — non è necessario alcun cablaggio locale o adattatore di protocollo. Gli unici requisiti sono un account Samsung con SmartThings, un Personal Access Token (PAT) e il Device ID dell’unità di climatizzazione.

Il template fornisce 8 dispositivi per il controllo completo del condizionatore: accensione/spegnimento, selezione modalità HVAC, velocità ventilatore, direzione del flusso d’aria, impostazione temperatura target, lettura temperatura e umidità ambiente e preset esclusivi Samsung tra cui WindFree e WindFree Sleep.

Configurazione

Configurazione dell’accesso alle API SmartThings

Accedi al portale sviluppatori Samsung SmartThings su account.smartthings.com/tokens con l’account Samsung associato all’unità di climatizzazione
Clicca su Generate new token
Assegna un nome al token (es. “TapHome”) e seleziona lo scope Devices (read + execute)
Clicca su Generate Token e copia la stringa del token — non verrà mostrata di nuovo

Trovare il Device ID

Il Device ID è un GUID (es. a1b2c3d4-e5f6-7890-abcd-ef1234567890) che identifica la specifica unità di climatizzazione in SmartThings.

Apri un browser o uno strumento API e invia una richiesta GET a:
1
https://api.smartthings.com/v1/devices
con l’header Authorization: Bearer <il-tuo-token>
Trova il condizionatore Samsung WindFree nella risposta — il campo deviceId contiene il GUID richiesto
In alternativa, usa la SmartThings CLI o l’app mobile Samsung SmartThings (sezione Device Info)

Parametri di importazione

Durante l’importazione del template in TapHome, inserisci:

Parametro	Descrizione	Formato
Token	SmartThings Personal Access Token	Stringa alfanumerica lunga
DeviceId	Identificatore dispositivo SmartThings	Formato UUID / GUID

I Personal Access Token (PAT) SmartThings sono destinati a test e uso personale. Possono scadere o essere revocati. Se il token diventa non valido, generane uno nuovo su account.smartthings.com/tokens e aggiorna la variabile del modulo in TapHome.

Dipendenza da internet

Questa è un’integrazione esclusivamente cloud. Tutti i dati passano attraverso i server Samsung SmartThings (api.smartthings.com:443). Il template richiede una connessione internet attiva sul TapHome Core. L’unità di climatizzazione deve essere registrata e online nell’app SmartThings.

Capacità dei dispositivi

Alimentazione e modalità HVAC

L’interruttore Power accende e spegne l’unità di climatizzazione tramite la capability SmartThings switch.

Il selettore HVAC Mode offre cinque modalità operative: Heat, Cool, Cool+Heat (auto), Dry e Fan Only. I nomi delle modalità in TapHome corrispondono ai valori API SmartThings heat, cool, auto, dry e wind.

Ventilatore e controllo del flusso d’aria

Il selettore Fan Mode offre cinque velocità: Auto, Low, Medium, High e Turbo.

Il selettore Swing Mode controlla l’oscillazione delle alette direzionali con quattro opzioni: Fixed (nessun movimento), All (entrambi gli assi), Vertical e Horizontal.

Modalità preset (WindFree)

Il selettore Preset Mode controlla le modalità opzionali specifiche Samsung tramite la capability custom.airConditionerOptionalMode. Sono disponibili sette preset:

Valore	Modalità	Descrizione
0	Off	Nessuna modalità preset attiva
1	Sleep	Regolazione graduale della temperatura per il comfort notturno
2	Quiet	Funzionamento a rumorosità ridotta
3	Smart	Ottimizzazione basata su AI
4	Speed	Raffreddamento o riscaldamento rapido
5	WindFree	Aria dispersa attraverso migliaia di micro-fori — nessun flusso d’aria diretto
6	WindFree Sleep	Combina la dispersione d’aria WindFree con la modalità sleep

WindFree è una funzionalità proprietaria Samsung esclusiva della serie WindFree. Elimina il flusso d’aria diretto disperdendo l’aria condizionata attraverso micro-perforazioni nel pannello frontale.

Il dispositivo Preset Mode legge lo stato da un endpoint capability dedicato (/v1/devices/{DeviceId}/components/main/capabilities/custom.airConditionerOptionalMode/status) anziché dall’endpoint completo dello stato del dispositivo, garantendo una lettura affidabile del preset attivo.

Controllo e monitoraggio della temperatura

Il dispositivo Thermostat imposta la temperatura target di raffreddamento con 10 step discreti da 18 °C a 27 °C. Ogni step corrisponde a un indice del selettore (0 = 18 °C, 9 = 27 °C). L’API SmartThings supporta un intervallo più ampio (16–30 °C), ma il template utilizza il sottoinsieme 18–27 °C.

Il dispositivo Cooling Setpoint (Readback) è un sensore di temperatura in sola lettura che rispecchia il setpoint corrente riportato dall’unità di climatizzazione. Fornisce feedback visivo in TapHome senza possibilità di scrittura — usa il dispositivo Thermostat per modificare la temperatura.

Il sensore Temperature + Humidity legge la temperatura ambiente (°C) e l’umidità relativa dai sensori integrati dell’unità di climatizzazione. L’umidità viene restituita come intero 0–100 dall’API e convertita in rapporto 0–1 per l’ingresso analogico TapHome (es. 55 % diventa 0,55). Questo dispositivo esegue il polling a intervalli di 15 secondi (più lento dell’intervallo di 2,5 secondi dei dispositivi di controllo).

Capacità aggiuntive

Alcuni modelli WindFree rendono disponibili anche sensori per livello di polvere (PM2.5/PM10), livello di odore e qualità dell’aria combinata, oltre al controllo del carico su richiesta e alla modalità di autopulizia automatica. Queste capacità sono disponibili tramite l’API SmartThings ma non sono ancora implementate nel template. Potranno essere aggiunte in un futuro aggiornamento del template.

Risoluzione dei problemi

Errori di autenticazione (HTTP 401)

Verifica che il Personal Access Token sia ancora valido — i PAT possono scadere o essere revocati manualmente
Genera un nuovo token su account.smartthings.com/tokens e aggiorna la variabile Token nelle impostazioni del modulo TapHome
Assicurati che il token abbia lo scope Devices abilitato

Dispositivo non trovato (HTTP 404)

Conferma che il DeviceId sia corretto — invia GET /v1/devices con il token e verifica il GUID
Verifica che l’unità di climatizzazione sia online nell’app SmartThings
Controlla che l’unità sia registrata sotto lo stesso account Samsung del token

Il dispositivo non risponde

Verifica la connessione internet del TapHome Core
Controlla che il servizio cloud Samsung SmartThings funzioni (stato su status.smartthings.com)
Riavvia l’unità di climatizzazione e attendi che ricompaia nell’app SmartThings

Limitazione delle richieste (HTTP 429)

L’API SmartThings applica limiti al numero di richieste. Il template esegue il polling dei dispositivi di controllo ogni 2,5 secondi e dei sensori ogni 15 secondi. Se altre integrazioni (Home Assistant, automazioni SmartThings) condividono lo stesso account, la frequenza combinata delle richieste potrebbe superare il limite. In caso di throttling, considera l’aumento degli intervalli di polling nel template TapHome.

Questa è un’integrazione esclusivamente cloud che dipende dalla disponibilità dei server Samsung SmartThings e da una connessione internet attiva. Durante interruzioni del cloud o problemi di connettività, il template non può leggere né controllare l’unità di climatizzazione. Non esiste un percorso di comunicazione locale di fallback.

Dispositivi disponibili

SmartThings — Samsung WindFree AC Modulo

Variabili personalizzate

`Token` (string)	SmartThings Personal Access Token — genera su account.smartthings.com/tokens
`DeviceId` (string)	SmartThings Device ID dell'unità di climatizzazione Samsung (formato GUID)

Modalità ventilatore Interruttore multivalore

Controllo velocità ventilatore — Auto, Low, Medium, High, Turbo

enum JSON PARSEJSON()

Valori / Stati: AUTO · LOW · MEDIUM · HIGH · TURBO

Modalità ventilatore

Lettura stato interruttore

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

Scrittura stato interruttore

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

Modalità HVAC Interruttore multivalore

Modalità operativa — Heat, Cool, Cool+Heat (auto), Dry, Fan Only

enum JSON PARSEJSON()

Valori / Stati: OFF · HEAT · COOL · COOL + HEAT · DRY · FAN ONLY

Modalità HVAC

Lettura stato interruttore

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

Scrittura stato interruttore

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

Alimentazione Interruttore

boolean JSON PARSEJSON()

Valori / Stati: ON · OFF

Alimentazione

Lettura stato interruttore

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

Scrittura stato interruttore

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

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

Modalità preset Interruttore multivalore

Modalità opzionali Samsung — Off, Sleep, Quiet, Smart, Speed, WindFree, WindFree Sleep

enum JSON PARSEJSON()

Valori / Stati: OFF · SLEEP · QUIET · SMART · SPEED · WindFree · WindFreeSleep

Modalità preset

Lettura stato interruttore

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

Scrittura stato interruttore

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

Modalità oscillazione Interruttore multivalore

Oscillazione alette direzionali — Fixed, All, Vertical, Horizontal

enum JSON PARSEJSON()

Valori / Stati: FIXED · ALL · VERTICAL · HORIZONTAL

Variabile: swing

Modalità oscillazione

Lettura stato interruttore

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

Scrittura stato interruttore

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

Temperatura + Umidità Sensore di temperatura Solo lettura

Temperatura ambiente (°C) e umidità relativa dai sensori integrati dell'unità di climatizzazione

numeric Unità: °C / % JSON PARSEJSON()

Temperatura + Umidità

Lettura umidità

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

Lettura temperatura

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

Setpoint raffreddamento (lettura) Sensore di temperatura Solo lettura

Lettura della temperatura target corrente riportata dall'unità di climatizzazione (sola lettura)

numeric Unità: °C JSON PARSEJSON()

Setpoint raffreddamento (lettura)

Lettura temperatura

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

Termostato Interruttore multivalore

Temperatura target di raffreddamento — 10 step da 18 °C a 27 °C

integer Unità: °C JSON PARSEJSON()

Valori / Stati: 18°C · 19°C · 20°C · 21°C · 22°C · 23°C · 24°C · 25°C · 26°C · 27°C

Termostato

Lettura stato interruttore

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

Scrittura stato interruttore

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

Connessione: Packet Parser → HTTP

Possibili miglioramenti (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

Scarica template

Fonti

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 Condizionatore

Configurazione#

Configurazione dell’accesso alle API SmartThings

Trovare il Device ID

Parametri di importazione

Dipendenza da internet

Capacità dei dispositivi#

Alimentazione e modalità HVAC

Ventilatore e controllo del flusso d’aria

Modalità preset (WindFree)

Controllo e monitoraggio della temperatura

Capacità aggiuntive

Risoluzione dei problemi#

Errori di autenticazione (HTTP 401)

Dispositivo non trovato (HTTP 404)

Il dispositivo non risponde

Limitazione delle richieste (HTTP 429)

Dispositivi disponibili

Modalità ventilatore

Modalità HVAC

Alimentazione

Modalità preset

Modalità oscillazione

Temperatura + Umidità

Setpoint raffreddamento (lettura)

Termostato

Fonti

Configurazione

Capacità dei dispositivi

Risoluzione dei problemi