--- title: "Somfy TaHoma – tapparelle e frangisole io e RTS (API locale)" description: "Controllo di tapparelle, tende da sole e frangisole Somfy io e motori RTS da TapHome con l'API locale del gateway TaHoma (Developer Mode), senza cloud." url: "https://taphome.com/it/compatibility/somfy-tahoma-http/" language: it lastmod: 2026-11-04 generator: hugo ai: topics: ["http","gateway","blinds","shutters","awnings","io-homecontrol","rts","rest-api","mdns"] questions: ["Esiste un template TapHome per Somfy?","Posso integrare le tapparelle Somfy in TapHome tramite il gateway TaHoma?","Come ottenere il token Bearer del Developer Mode di Somfy TaHoma per TapHome?","Come trovare il deviceURL di un motore Somfy per il template TapHome?","TapHome può controllare i motori Somfy RTS?","I motori Somfy cablati senza radio hanno bisogno di un gateway TaHoma in TapHome?"] --- # Somfy TaHoma – tapparelle e frangisole io e RTS (API locale) Comunicazione: Packet Parser → HTTP - [Sito ufficiale Somfy](https://www.somfy.com) - [Pagina prodotto Somfy TaHoma Switch](https://www.somfy.co.uk/products/1870600/tahoma-switch) Il template Somfy TaHoma collega TapHome a un gateway Somfy TaHoma (ad esempio TaHoma Switch) tramite l'API locale ufficiale del gateway, che Somfy chiama Developer Mode. I motori si associano al gateway come di consueto nell'app TaHoma by Somfy; TapHome comunica solo con il gateway, in HTTPS sulla porta 8443 nella rete locale, senza connessione al cloud. Il template controlla la posizione di tapparelle e tende da sole io-homecontrol, la posizione e l'inclinazione delle lamelle dei frangisole io-homecontrol e invia ai motori RTS unidirezionali i comandi Apri, My, Stop e Chiudi. > [!WARNING] > **Template della community — non ancora testato con TapHome.** Il template è stato generato nel portale TapHome dalla documentazione Somfy sul Developer Mode; i nomi degli stati e dei comandi dei dispositivi provengono da fonti della community (Somfy non li elenca). È stato testato solo con un gateway simulato su un TapHome Core 2025.2 locale, non con un vero gateway TaHoma né con veri motori Somfy, e i riscontri dal campo sono benvenuti. Scarica l'XML da questa pagina o dal portale TapHome: [Somfy TaHoma — template della community](https://portal.taphome.com/portal/community/somfy-tahoma-http), e importalo come nuovo modulo. **[Somfy TaHoma — io and RTS shading motors (Developer Mode, local API)](https://portal.taphome.com/it/portal/community/somfy-tahoma-http)** — Somfy, HTTP. Somfy TaHoma gateway over its official local API (Developer Mode, HTTPS 8443, token): io roller shutters and awnings with position, io venetian blinds with slats, RTS motors as commands without feedback. > [!NOTE] > **I motori Somfy cablati non hanno bisogno del gateway.** Un motore Somfy a 230 V senza ricevitore radio (ad esempio Somfy WT, quattro conduttori — PE, N, su, giù) è controllato da TapHome direttamente con moduli a relè, come qualsiasi altro motore per schermature — vedi [Requisiti → Tende](https://taphome.com/it/docs/setup/requirements/#shading). Questo template è per i motori radio (io-homecontrol o RTS) associati a un gateway TaHoma. ## Gateway supportati Secondo Somfy, il Developer Mode funziona sulla grande maggioranza dei gateway TaHoma. **Non è disponibile** su: - TaHoma box o Somfy box di 1ª generazione (forma quadrata) - Connectivity Kit ## Collegamento hardware Non serve alcun cablaggio. Il gateway TaHoma e il TapHome Core devono trovarsi nella stessa rete locale. Il gateway usa un certificato firmato dall'autorità autofirmata Overkiz; il template si collega ignorando gli errori del certificato, quindi non occorre installare alcun certificato. ## Configurazione ### Attivare il Developer Mode e creare un token 1. Apri l'app **TaHoma by Somfy**. 2. Vai su **Configure the installation › Access the parameters** del tuo TaHoma box. 3. Tocca **7 volte** il PIN del gateway (ad esempio 2001-1234-5678) — il Developer Mode si attiva e parte l'API locale del gateway. 4. Nel menu **Developer Mode** genera un token. Il token si può leggere e copiare solo al momento della creazione — salvalo subito. Si possono generare più token; se un token va perso, generane uno nuovo e inseriscilo in TapHome. ### Trovare gli indirizzi dei dispositivi Ogni motore associato al gateway ha un indirizzo, il `deviceURL`. Gli indirizzi si leggono dall'elenco dei dispositivi del gateway con il token — ad esempio da un computer nella stessa rete: ``` curl -k -H "Authorization: Bearer " https://:8443/enduser-mobile-web/1/enduserAPI/setup/devices ``` Trova il motore in base al suo `label` (il nome nell'app TaHoma) e copia il suo `deviceURL` esattamente come appare. Il template lo codifica da sé per la richiesta. | Protocollo | Formato | Esempio | |---|---|---| | io-homecontrol | `io://{gateway-pin}/{device-id}` | `io://1234-5678-9012/4820485` | | RTS | `rts://{gateway-pin}/{device-id}` | `rts://1234-5678-9012/987654321` | La stessa risposta mostra che cosa supporta ogni motore: `definition.states` e `definition.commands`. Il template si aspetta lo stato `core:ClosureState` e il comando `setClosure` su una tapparella o tenda da sole, `core:ClosureState`, `core:SlateOrientationState` e `setClosureAndOrientation` su un frangisole e `open`, `my`, `stop` e `close` su un motore RTS. Un motore la cui definizione non contiene questi nomi non funzionerà con quel dispositivo. ### Parametri di importazione | Parametro di importazione | Descrizione | Segnaposto | |---|---|---| | `GatewayAddress` | Indirizzo IP o nome host del gateway TaHoma, ad esempio `gateway-1234-5678-9012.local` | `192.168.1.100` | | `BearerToken` | Token del Developer Mode | (vuoto) | | `SlideDeviceUrl` | `deviceURL` della tapparella o tenda da sole io | `io://1234-5678-9012/12345678` | | `BlindDeviceUrl` | `deviceURL` del frangisole io | `io://1234-5678-9012/12345678` | | `RtsDeviceUrl` | `deviceURL` del motore RTS | `rts://1234-5678-9012/12345678` | Se usi l'indirizzo IP, riservalo al gateway nel router in modo che non cambi. Il template contiene un dispositivo per ogni tipo. Elimina i dispositivi che non ti servono. Per altri motori importa di nuovo il template con gli altri indirizzi — ogni importazione aggiunge un modulo gateway con i propri dispositivi — ed elimina i dispositivi in eccesso, oppure modifica la variabile `DeviceUrl` di un dispositivo. ## Funzionalità dei dispositivi ### Gateway Il modulo legge il gateway ogni 30 s e mostra tre attributi di servizio: **Versione del protocollo** (la versione dell'API locale), **ID del gateway** (il PIN del gateway) e **Stato della connettività** (ad esempio OK). Con un token errato il modulo mostra l'errore "Check Bearer token in TaHoma By Somfy app → Developer Mode". ### Tapparelle e tende da sole io - **Tapparella / tenda da sole io** — posizione di una tapparella o tenda da sole io-homecontrol. Il gateway indica 0 = completamente aperta e 100 = completamente chiusa; in TapHome 0 % è tutto su e 100 % tutto giù, la stessa direzione. Il dispositivo legge la posizione ogni 5 s e muove il motore con il comando `setClosure`. ### Frangisole io - **Frangisole io** — posizione e inclinazione delle lamelle di un frangisole io-homecontrol. Entrambe vengono inviate insieme in un unico comando `setClosureAndOrientation`, quindi una modifica della posizione invia anche l'inclinazione attuale delle lamelle e una modifica delle lamelle la posizione attuale. Quando TapHome cambia posizione e lamelle insieme, il comando identico viene inviato una sola volta. ### Motori RTS I motori RTS (Radio Technology Somfy) usano una radio unidirezionale: ricevono comandi ma non comunicano la propria posizione. | Valore | Comando | Azione | |---|---|---| | Apri | `open` | Salita / apertura completa | | My | `my` | Vai alla posizione preferita memorizzata nel motore | | Stop | `stop` | Ferma il movimento | | Chiudi | `close` | Discesa / chiusura completa | - **Motore RTS** — dopo ogni comando l'interruttore mostra **Pronto**, quindi lo stesso comando può essere inviato di nuovo, ad esempio Chiudi dopo che il motore è stato mosso con il proprio telecomando. Scegliere Pronto invia Stop. Nessuno dei dispositivi muove un motore all'avvio del TapHome Core: prendono lo stato dal gateway, non dall'ultimo valore in TapHome. ### Come il template comunica con il gateway Tutte le chiamate vanno a `https://:8443/enduser-mobile-web/1/enduserAPI` con l'intestazione `Authorization: Bearer `; solo `GET /apiVersion` funziona senza token. Ogni dispositivo io legge i propri stati da `/setup/devices/{deviceURL}/states` ogni 5 s e tutti i dispositivi inviano i comandi con `POST /exec/apply`. Somfy non fissa limiti di chiamate per l'API locale, ma avverte che chiamate troppo frequenti sovraccaricano il gateway e ritardano il controllo dei motori — tienilo presente con molti motori su un solo gateway. ## Risoluzione dei problemi ### Errore "Check Bearer token in TaHoma By Somfy app → Developer Mode" Il gateway ha risposto HTTP 401: il token è errato o non è stato copiato per intero. Genera un nuovo token nell'app TaHoma by Somfy › Developer Mode e inseriscilo in TapHome. ### Errore del dispositivo "Device unavailable (HTTP …)" Il gateway non conosce l'indirizzo. Verifica che il `deviceURL` sia copiato esattamente da `GET /setup/devices` — non codificato, senza spazi — e che appartenga al tipo di dispositivo giusto. ### Errore del dispositivo "Closure state not available" Il gateway ha risposto, ma senza lo stato `core:ClosureState`. Controlla le `definition.states` del motore. Alcune tende da sole indicano invece lo stato `core:DeploymentState` (0 = chiusa, 100 = aperta); il template non lo legge. ### Il gateway mostra un dispositivo come non disponibile, ma funziona Alcuni firmware TaHoma indicano i dispositivi io come non disponibili (`available: false`) anche se funzionano normalmente — segnalato a Somfy nel repository del Developer Mode. Il template non usa questo indicatore e non mostra errori per questo motivo. ### Il motore RTS non si muove I comandi RTS sono segnali radio unidirezionali senza conferma di consegna, quindi TapHome non mostra errori quando il motore non reagisce. Verifica che il motore sia nel raggio radio del gateway e che si muova dall'app TaHoma by Somfy. ### Nome host del gateway non raggiungibile Se `gateway-{pin}.local` non viene risolto, usa l'indirizzo IP del gateway — lo trovi nel router. Il Developer Mode deve restare attivo: è lui ad abilitare l'API locale del gateway. ## Dispositivi disponibili Gateway Somfy TaHoma Modulo Attributi di servizio | | | |--------------------------|------------------------------------------------------------------------------------------------------------| | Versione del protocollo | Versione dell'API locale indicata dal gateway | | ID del gateway | PIN del gateway (ad esempio 1234-5678-9012), lo stesso PIN che fa parte dell'indirizzo di ogni dispositivo | | Stato della connettività | Stato della connettività indicato dal gateway, ad esempio OK | Variabili personalizzate `BearerToken` (string) Token dell'API locale TaHoma, creato nell'app TaHoma by Somfy › Developer Mode; il modulo e ogni dispositivo lo inviano come 'Authorization: Bearer <token>' TaHoma by Somfy app → Configure the installation → Access the parameters of your TaHoma box → tap the gateway PIN 7 times → Developer Mode → generate a token. The token can be copied only when it is created; enter it as the import parameter Bearer token. Tapparella / tenda da sole io Cursore Posizione di una tapparella o tenda da sole io-homecontrol — 0 % completamente aperta, 100 % completamente chiusa, stessa direzione del gateway numeric (0–100) Unità: % json\_path Variabile: `DeviceUrl` — Indirizzo del motore nel gateway TaHoma (deviceURL da GET /setup/devices), ad esempio io://1234-5678-9012/4820485 Frangisole io Tapparella Posizione e inclinazione delle lamelle di un frangisole io-homecontrol — entrambe vengono inviate insieme in un unico comando numeric (0–100) Unità: % json\_path Variabile: `DeviceUrl` — Indirizzo del frangisole nel gateway TaHoma (deviceURL), ad esempio io://1234-5678-9012/5932104 Motore RTS Interruttore multivalore Comandi per un motore RTS unidirezionale — Apri, My (posizione preferita), Stop o Chiudi; RTS non comunica la posizione, quindi dopo ogni comando l'interruttore mostra Pronto enum numeric Valori / Stati: Pronto · Apri · My · Stop · Chiudi Variabile: `DeviceUrl` — Indirizzo del motore RTS nel gateway TaHoma (deviceURL), ad esempio rts://1234-5678-9012/987654321 **Connessione:** Packet Parser → HTTP • Hostname: `gateway-{pin}.local.local` Possibili miglioramenti (6) - Event-driven state updates — Somfy recommends reading /setup at start and then fetching events at most once per second; the listener expires after 10 minutes without a fetch. The template polls the states of each device every 5 s instead. - Automatic device discovery — The gateway lists every paired device with its deviceURL, label, controllableName and definition. The template does not create devices from it; the installer enters one deviceURL per device. - Open / Close / Stop / My on io motors — io roller shutters and venetian blinds accept the same commands as RTS; the template drives them by position only (setClosure / setClosureAndOrientation). - Awnings that report the deployment instead of the closure — Awnings of type io:HorizontalAwningIOComponent may report core:DeploymentState (0 = retracted, 100 = deployed) instead of core:ClosureState; the roller shutter device reads ClosureState only. - Cancel running executions — Cancels all running commands launched from the local API. - Availability of a motor — The device description carries available and the state core:StatusState; some gateway firmware reports io devices as unavailable although they work (reported in the Developer Mode repository), so the template does not use it. ## Fonti - Somfy TaHoma Developer Mode — README (activation, token, certificate, mDNS, supported gateways) [github.com](https://github.com/Somfy-Developer/Somfy-TaHoma-Developer-Mode) 2026-11-04 - Somfy TaHoma local API — OpenAPI specification [somfy-developer.github.io](https://somfy-developer.github.io/Somfy-TaHoma-Developer-Mode/) 2026-11-04 ## 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/)