--- title: "Samsung WindFree Condizionatore" description: "Samsung WindFree tramite SmartThings cloud API — HVAC, ventilatore, alette, temperatura, modalità WindFree, umidità." url: "https://taphome.com/it/compatibility/samsung-windfree-air-conditioner/" language: it lastmod: 2026-04-13 generator: hugo ai: topics: ["http","air-conditioning","cloud-api","smartthings","hvac"] questions: ["Come integrare il condizionatore Samsung WindFree con TapHome?","Cosa controlla il template Samsung WindFree in TapHome?","Come ottenere un Personal Access Token SmartThings per TapHome?","Come trovare il DeviceId SmartThings per un condizionatore Samsung?","TapHome può controllare la modalità WindFree sul condizionatore Samsung?","Qual è l'intervallo di temperatura impostabile nel template Samsung WindFree?"] --- # Samsung WindFree Condizionatore Comunicazione: Packet Parser → HTTP - [Portale sviluppatori Samsung SmartThings](https://developer.smartthings.com) ## Guida all'integrazione 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 1. Accedi al portale sviluppatori Samsung SmartThings su [account.smartthings.com/tokens](https://account.smartthings.com/tokens) con l'account Samsung associato all'unità di climatizzazione 2. Clicca su **Generate new token** 3. Assegna un nome al token (es. "TapHome") e seleziona lo scope **Devices** (read + execute) 4. 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. 1. Apri un browser o uno strumento API e invia una richiesta GET a: ``` https://api.smartthings.com/v1/devices ``` con l'header `Authorization: Bearer ` 2. Trova il condizionatore Samsung WindFree nella risposta — il campo `deviceId` contiene il GUID richiesto 3. In alternativa, usa la [SmartThings CLI](https://github.com/SmartThingsCommunity/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 | > [!WARNING] > 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](https://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. > [!TIP] > 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) 1. Verifica che il Personal Access Token sia ancora valido — i PAT possono scadere o essere revocati manualmente 2. Genera un nuovo token su [account.smartthings.com/tokens](https://account.smartthings.com/tokens) e aggiorna la variabile `Token` nelle impostazioni del modulo TapHome 3. Assicurati che il token abbia lo scope **Devices** abilitato ### Dispositivo non trovato (HTTP 404) 1. Conferma che il `DeviceId` sia corretto — invia `GET /v1/devices` con il token e verifica il GUID 2. Verifica che l'unità di climatizzazione sia online nell'app SmartThings 3. Controlla che l'unità sia registrata sotto lo stesso account Samsung del token ### Il dispositivo non risponde 1. Verifica la connessione internet del TapHome Core 2. Controlla che il servizio cloud Samsung SmartThings funzioni (stato su [status.smartthings.com](https://status.smartthings.com)) 3. 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. > [!WARNING] > 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 8 Questi dispositivi compaiono in TapHome dopo l'importazione. 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 Lettura e scrittura Controllo velocità ventilatore — Auto, Low, Medium, High, Turbo enum JSON PARSEJSON() Valori / Stati: AUTO · LOW · MEDIUM · HIGH · TURBO Lettura stato interruttore ```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 ``` Scrittura stato interruttore ```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); ``` Modalità HVAC Interruttore multivalore Lettura e scrittura Modalità operativa — Heat, Cool, Cool+Heat (auto), Dry, Fan Only enum JSON PARSEJSON() Valori / Stati: HEAT · COOL · COOL + HEAT · DRY · FAN ONLY Lettura stato interruttore ```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 ``` Scrittura stato interruttore ```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); ``` Alimentazione Interruttore Lettura e scrittura boolean JSON PARSEJSON() Valori / Stati: ON · OFF Lettura stato interruttore ```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 ``` Scrittura stato interruttore ```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); ``` Modalità preset Interruttore multivalore Lettura e scrittura Modalità opzionali Samsung — Off, Sleep, Quiet, Smart, Speed, WindFree, WindFree Sleep enum JSON PARSEJSON() Valori / Stati: OFF · SLEEP · QUIET · SMART · SPEED · WindFree · WindFreeSleep Lettura stato interruttore ```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 ``` Scrittura stato interruttore ```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); ``` Modalità oscillazione Interruttore multivalore Lettura e scrittura Oscillazione alette direzionali — Fixed, All, Vertical, Horizontal enum JSON PARSEJSON() Valori / Stati: FIXED · ALL · VERTICAL · HORIZONTAL Variabile: `swing` Lettura stato interruttore ```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 ``` Scrittura stato interruttore ```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); ``` 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() Lettura umidità ```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 ``` Lettura temperatura ```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 ``` 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() Lettura temperatura ```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 ``` Termostato Interruttore multivalore Lettura e scrittura 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 Lettura stato interruttore ```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 ``` Scrittura stato interruttore ```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); ``` **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 ## Parametri di importazione Inserisci questi valori quando importi l'XML. | Richiesto nell'app | Predefinito | |--------------------|------------------------------| | Token | Da inserire all'importazione | | DeviceId | Da inserire all'importazione | ## Fonti - 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 ## Documentazione correlata - [Integrazione Packet Parser](https://taphome.com/it/compatibility/packet-parser-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/it/docs/integration/packet-parser/) - [Funzioni Packet parser](https://taphome.com/it/docs/script/packet-parser/) - [Funzioni di parsing](https://taphome.com/it/docs/script/parsing-functions/)