TapHome

Somfy TaHoma – tapparelle e frangisole io e RTS (API locale)

Packet Parser → HTTP
Inviato da
Ultimo aggiornamento: 11. 2026

Richiede gateway esterno

Somfy TaHoma with Developer Mode (local API, HTTPS port 8443) — pagina prodotto

Questo dispositivo supporta mDNS

Invece di un indirizzo IP, puoi raggiungere il dispositivo a:

gateway-{pin}.local.local

Sostituisci {MAC} con l'indirizzo MAC del dispositivo (maiuscolo, senza due punti).

TapHome supporta mDNS — usare un hostname è più affidabile di un IP statico.

Somfy TaHoma – tapparelle e frangisole io e RTS (API locale)

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.

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, e importalo come nuovo modulo.

Modello · portale TapHome Community Beta · non verificato
Somfy TaHoma — io and RTS shading motors (Developer Mode, local API)
Di Martin Keller
HTTP Vedi nel portale TapHome

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. 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:

1

curl -k -H "Authorization: Bearer <token>" https://<gateway-address>: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.

ProtocolloFormatoEsempio
io-homecontrolio://{gateway-pin}/{device-id}io://1234-5678-9012/4820485
RTSrts://{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 importazioneDescrizioneSegnaposto
GatewayAddressIndirizzo IP o nome host del gateway TaHoma, ad esempio gateway-1234-5678-9012.local192.168.1.100
BearerTokenToken del Developer Mode(vuoto)
SlideDeviceUrldeviceURL della tapparella o tenda da sole ioio://1234-5678-9012/12345678
BlindDeviceUrldeviceURL del frangisole ioio://1234-5678-9012/12345678
RtsDeviceUrldeviceURL del motore RTSrts://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.

ValoreComandoAzione
ApriopenSalita / apertura completa
MymyVai alla posizione preferita memorizzata nel motore
StopstopFerma il movimento
ChiudicloseDiscesa / 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://<gateway-address>:8443/enduser-mobile-web/1/enduserAPI con l’intestazione Authorization: Bearer <token>; 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 protocolloVersione dell'API locale indicata dal gateway
ID del gatewayPIN 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.

Somfy TaHoma Gateway

Lettura (modulo)
VAR r := SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/apiVersion");
IF r.IsSuccess
    ApiVersion := r.Content;
END

r := SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/setup/gateways", "GET", "", "Authorization: Bearer " + BearerToken);
IF r.StatusCode = 401
    ADDERROR(0, "Check Bearer token in TaHoma By Somfy app → Developer Mode");
ELSEIF r.IsSuccess
    GatewayData := r.Content;
END
Attributi di servizio
Protocol Version
PARSEJSON(ApiVersion, "$.protocolVersion", true)
Gateway ID
PARSEJSON(GatewayData, "[0].gatewayId", true)
Connectivity Status
PARSEJSON(GatewayData, "[0].connectivity.status", true)
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

Tapparella / tenda da sole io

Lettura (modulo)
VAR encodedUrl := REPLACE(REPLACE(DeviceUrl, ":", "%3A"), "/", "%2F");
VAR r := SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/setup/devices/" + encodedUrl + "/states/core%3AClosureState", "GET", "", "Authorization: Bearer " + BearerToken);
IF r.StatusCode = 401
    ADDERROR(0, "Check Bearer token in TaHoma By Somfy app → Developer Mode");
ELSEIF r.IsSuccess
    StatesJson := r.Content;
ELSE
    ADDERROR(1, "Device unavailable (HTTP " + r.StatusCode + ")");
END
Lettura livello tapparella
VAR closure := PARSEJSON(StatesJson, "$.value", true);
IF ISNULL(closure)
    ADDERROR(0, "Closure state not available");
    RETURN(NaN);
END
RETURN(closure / 100);
Scrittura livello tapparella
VAR pos := ROUND(Bl * 100);
VAR body := "{\"label\":\"Set roller shutter\",\"actions\":[{\"deviceURL\":\"" + DeviceUrl + "\",\"commands\":[{\"name\":\"setClosure\",\"parameters\":[" + pos + "]}]}]}";
SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/exec/apply", "POST", body, "Authorization: Bearer " + BearerToken, "Content-Type: application/json");
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

Frangisole io

Lettura (modulo)
VAR encodedUrl := REPLACE(REPLACE(DeviceUrl, ":", "%3A"), "/", "%2F");
VAR r := SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/setup/devices/" + encodedUrl + "/states", "GET", "", "Authorization: Bearer " + BearerToken);
IF r.StatusCode = 401
    ADDERROR(0, "Check Bearer token in TaHoma By Somfy app → Developer Mode");
ELSEIF r.IsSuccess
    StatesJson := r.Content;
ELSE
    ADDERROR(1, "Device unavailable (HTTP " + r.StatusCode + ")");
END
Lettura livello tapparella
VAR closure := PARSEJSON(StatesJson, "$[?(@.name=='core:ClosureState')].value", true);
IF ISNULL(closure)
    ADDERROR(0, "Closure state not available");
    RETURN(NaN);
END
RETURN(closure / 100);
Scrittura livello tapparella
VAR pos := ROUND(Bl * 100);
VAR ori := ROUND(Bs * 100);
VAR body := "{\"label\":\"Set venetian blind\",\"actions\":[{\"deviceURL\":\"" + DeviceUrl + "\",\"commands\":[{\"name\":\"setClosureAndOrientation\",\"parameters\":[" + pos + "," + ori + "]}]}]}";
VAR date := NOW();
IF body != LastBody OR date.UNIXTIME - LastSentAt > 3
    SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/exec/apply", "POST", body, "Authorization: Bearer " + BearerToken, "Content-Type: application/json");
    LastBody := body;
    LastSentAt := date.UNIXTIME;
END
Lettura inclinazione tapparella
VAR orientation := PARSEJSON(StatesJson, "$[?(@.name=='core:SlateOrientationState')].value", true);
IF ISNULL(orientation)
    RETURN(NaN);
END
RETURN(orientation / 100);
Scrittura inclinazione tapparella
VAR pos := ROUND(Bl * 100);
VAR ori := ROUND(Bs * 100);
VAR body := "{\"label\":\"Set venetian blind\",\"actions\":[{\"deviceURL\":\"" + DeviceUrl + "\",\"commands\":[{\"name\":\"setClosureAndOrientation\",\"parameters\":[" + pos + "," + ori + "]}]}]}";
VAR date := NOW();
IF body != LastBody OR date.UNIXTIME - LastSentAt > 3
    SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/exec/apply", "POST", body, "Authorization: Bearer " + BearerToken, "Content-Type: application/json");
    LastBody := body;
    LastSentAt := date.UNIXTIME;
END
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

Motore RTS

Lettura stato interruttore
RETURN(0);
Scrittura stato interruttore
VAR cmd := SWITCH(Mu, 1, "open", 2, "my", 3, "stop", 4, "close", "stop");
VAR body := "{\"label\":\"RTS command\",\"actions\":[{\"deviceURL\":\"" + DeviceUrl + "\",\"commands\":[{\"name\":\"" + cmd + "\",\"parameters\":[]}]}]}";
SENDHTTPREQUEST("/enduser-mobile-web/1/enduserAPI/exec/apply", "POST", body, "Authorization: Bearer " + BearerToken, "Content-Type: application/json");
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 2026-11-04
  • Somfy TaHoma local API — OpenAPI specification
    somfy-developer.github.io 2026-11-04

Hai trovato un problema con questo template?

Dicci cosa non funziona, cosa manca o come dovrebbe comportarsi il template. Il tuo feedback ci aiuta a mantenere il catalogo accurato.

Community — non revisionato

Vuoi usarlo nel tuo TapHome Core?

Apri questo template nel Customer Portal per applicarlo a una delle tue case, o crea una proposta di modifica e inviala al catalogo.

Apri nel portale