TapHome

Somfy TaHoma – jaluzele și rulouri io și RTS (API local)

Packet Parser → HTTP
Trimis de
Ultima actualizare: 11. 2026

Necesită gateway extern

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

Acest dispozitiv acceptă mDNS

În loc să folosiți o adresă IP, puteți accesa dispozitivul la:

gateway-{pin}.local.local

Înlocuiți {MAC} cu adresa MAC a dispozitivului dvs. (majuscule, fără două puncte).

TapHome acceptă mDNS — folosirea unui nume de gazdă este mai fiabilă decât un IP static.

Somfy TaHoma – jaluzele și rulouri io și RTS (API local)

Șablonul Somfy TaHoma conectează TapHome la un gateway Somfy TaHoma (de exemplu TaHoma Switch) prin API-ul local oficial al gateway-ului, pe care Somfy îl numește Developer Mode. Motoarele se asociază cu gateway-ul ca de obicei în aplicația TaHoma by Somfy; TapHome comunică doar cu gateway-ul, prin HTTPS pe portul 8443 în rețeaua locală, fără conexiune la cloud.

Șablonul controlează poziția rulourilor și copertinelor io-homecontrol, poziția și unghiul lamelelor jaluzelelor exterioare io-homecontrol și trimite motoarelor RTS unidirecționale comenzile Deschide, My, Stop și Închide.

Șablon al comunității — încă netestat cu TapHome. Șablonul a fost generat în portalul TapHome din documentația Somfy pentru Developer Mode; numele stărilor și comenzilor dispozitivelor provin din surse ale comunității (Somfy nu le enumeră). A fost testat doar cu un gateway simulat pe un TapHome Core 2025.2 local, nu cu un gateway TaHoma real și nici cu motoare Somfy reale, iar experiența din teren este binevenită. Descărcați fișierul XML de pe această pagină sau din portalul TapHome: Somfy TaHoma — șablon al comunității, și importați-l ca modul nou.

Șablon · portalul TapHome Comunitate Beta · neverificat
Somfy TaHoma — io and RTS shading motors (Developer Mode, local API)
De Martin Keller
HTTP Vezi în portalul TapHome

Motoarele Somfy cu fir nu au nevoie de gateway. Un motor Somfy de 230 V fără receptor radio (de exemplu Somfy WT, patru conductori — PE, N, sus, jos) este controlat de TapHome direct cu module cu relee, ca orice alt motor de umbrire — vedeți Cerințe → Umbrire. Acest șablon este pentru motoarele radio (io-homecontrol sau RTS) asociate cu un gateway TaHoma.

Gateway-uri acceptate

Potrivit Somfy, Developer Mode funcționează pe marea majoritate a gateway-urilor TaHoma. Nu este disponibil pe:

  • TaHoma box sau Somfy box din prima generație (formă pătrată)
  • Connectivity Kit

Conexiunea hardware

Nu este necesar niciun cablaj. Gateway-ul TaHoma și TapHome Core trebuie să fie în aceeași rețea locală. Gateway-ul folosește un certificat semnat de autoritatea autosemnată Overkiz; șablonul se conectează ignorând erorile de certificat, deci nu trebuie instalat niciun certificat.

Configurare

Activarea Developer Mode și crearea unui token

  1. Deschideți aplicația TaHoma by Somfy.
  2. Mergeți la Configure the installation › Access the parameters al gateway-ului TaHoma.
  3. Atingeți de 7 ori PIN-ul gateway-ului (de exemplu 2001-1234-5678) — Developer Mode se activează și pornește API-ul local al gateway-ului.
  4. În meniul Developer Mode, generați un token.

Tokenul poate fi citit și copiat doar la creare — salvați-l imediat. Se pot genera mai multe tokenuri; dacă un token se pierde, generați unul nou și introduceți-l în TapHome.

Găsirea adreselor dispozitivelor

Fiecare motor asociat cu gateway-ul are o adresă, deviceURL. Adresele se obțin din lista de dispozitive a gateway-ului, cu tokenul — de exemplu de pe un computer din aceeași rețea:

1

curl -k -H "Authorization: Bearer <token>" https://<gateway-address>:8443/enduser-mobile-web/1/enduserAPI/setup/devices

Găsiți motorul după label (numele din aplicația TaHoma) și copiați-i deviceURL exact așa cum este afișat. Șablonul îl codifică singur pentru cerere.

ProtocolFormatExemplu
io-homecontrolio://{gateway-pin}/{device-id}io://1234-5678-9012/4820485
RTSrts://{gateway-pin}/{device-id}rts://1234-5678-9012/987654321

Același răspuns arată ce acceptă fiecare motor: definition.states și definition.commands. Șablonul așteaptă starea core:ClosureState și comanda setClosure la un rulou sau o copertină, core:ClosureState, core:SlateOrientationState și setClosureAndOrientation la o jaluzea și open, my, stop și close la un motor RTS. Un motor a cărui definiție nu conține aceste nume nu va funcționa cu dispozitivul respectiv.

Parametrii de import

Parametru de importDescriereValoare substituent
GatewayAddressAdresa IP sau numele de gazdă al gateway-ului TaHoma, de exemplu gateway-1234-5678-9012.local192.168.1.100
BearerTokenTokenul din Developer Mode(gol)
SlideDeviceUrldeviceURL al ruloului sau copertinei ioio://1234-5678-9012/12345678
BlindDeviceUrldeviceURL al jaluzelei ioio://1234-5678-9012/12345678
RtsDeviceUrldeviceURL al motorului RTSrts://1234-5678-9012/12345678

Dacă folosiți adresa IP, rezervați-o pentru gateway în router, ca să nu se schimbe.

Șablonul are câte un dispozitiv din fiecare tip. Ștergeți dispozitivele de care nu aveți nevoie. Pentru alte motoare, importați din nou șablonul cu celelalte adrese — fiecare import adaugă un modul de gateway cu propriile dispozitive — și ștergeți dispozitivele în plus, sau modificați variabila DeviceUrl a unui dispozitiv.

Funcțiile dispozitivului

Gateway

Modulul citește gateway-ul la fiecare 30 s și afișează trei atribute de service: Versiunea protocolului (versiunea API-ului local), ID gateway (PIN-ul gateway-ului) și Starea conectivității (de exemplu OK). La un token greșit, modulul afișează eroarea „Check Bearer token in TaHoma By Somfy app → Developer Mode”.

Rulouri și copertine io

  • Rulou / copertină io — poziția unui rulou sau a unei copertine io-homecontrol. Gateway-ul raportează 0 = complet deschis și 100 = complet închis; în TapHome 0 % este complet sus și 100 % complet jos, aceeași direcție. Dispozitivul citește poziția la fiecare 5 s și mișcă motorul cu comanda setClosure.

Jaluzele exterioare io

  • Jaluzea exterioară io — poziția și unghiul lamelelor unei jaluzele exterioare io-homecontrol. Ambele sunt trimise împreună într-o singură comandă setClosureAndOrientation, astfel încât o schimbare a poziției trimite și unghiul actual al lamelelor, iar o schimbare a lamelelor poziția actuală. Când TapHome schimbă simultan poziția și lamelele, comanda identică este trimisă o singură dată.

Motoare RTS

Motoarele RTS (Radio Technology Somfy) folosesc radio unidirecțional: primesc comenzi, dar nu își raportează poziția.

ValoareComandăAcțiune
DeschideopenMișcare în sus / deschidere completă
MymyDeplasare în poziția preferată memorată în motor
StopstopOprirea mișcării
ÎnchidecloseMișcare în jos / închidere completă
  • Motor RTS — după fiecare comandă, comutatorul arată Pregătit, astfel încât aceeași comandă poate fi trimisă din nou, de exemplu Închide după ce motorul a fost mișcat cu propria telecomandă. Alegerea Pregătit trimite Stop.

Niciun dispozitiv nu mișcă un motor la pornirea TapHome Core: își preiau starea de la gateway, nu din ultima valoare din TapHome.

Cum comunică șablonul cu gateway-ul

Toate apelurile merg la https://<gateway-address>:8443/enduser-mobile-web/1/enduserAPI cu antetul Authorization: Bearer <token>; fără token funcționează doar GET /apiVersion. Fiecare dispozitiv io își citește stările din /setup/devices/{deviceURL}/states la fiecare 5 s, iar toate dispozitivele trimit comenzi prin POST /exec/apply. Somfy nu impune o limită de apeluri pentru API-ul local, dar avertizează că apelurile prea dese supraîncarcă gateway-ul și întârzie controlul motoarelor — țineți cont de asta când sunt multe motoare pe un singur gateway.

Depanare

Eroarea „Check Bearer token in TaHoma By Somfy app → Developer Mode”

Gateway-ul a răspuns cu HTTP 401: tokenul este greșit sau nu a fost copiat complet. Generați un token nou în aplicația TaHoma by Somfy › Developer Mode și introduceți-l în TapHome.

Eroare de dispozitiv „Device unavailable (HTTP …)”

Gateway-ul nu cunoaște adresa. Verificați dacă deviceURL este copiat exact din GET /setup/devices — necodificat, fără spații — și dacă aparține tipului corect de dispozitiv.

Eroare de dispozitiv „Closure state not available”

Gateway-ul a răspuns, dar fără starea core:ClosureState. Verificați definition.states ale motorului. Unele copertine raportează în schimb starea core:DeploymentState (0 = retrasă, 100 = desfășurată); pe aceasta șablonul nu o citește.

Gateway-ul arată un dispozitiv ca indisponibil, dar acesta funcționează

Unele versiuni de firmware TaHoma raportează dispozitivele io ca indisponibile (available: false), deși funcționează normal — semnalat către Somfy în depozitul Developer Mode. Șablonul nu folosește acest indicator și nu afișează nicio eroare din cauza lui.

Motorul RTS nu se mișcă

Comenzile RTS sunt semnale radio unidirecționale fără confirmare de livrare, de aceea TapHome nu afișează nicio eroare când motorul nu reacționează. Verificați dacă motorul este în raza radio a gateway-ului și dacă se mișcă din aplicația TaHoma by Somfy.

Numele de gazdă al gateway-ului nu este accesibil

Dacă gateway-{pin}.local nu se rezolvă, folosiți adresa IP a gateway-ului — o găsiți în router. Developer Mode trebuie să rămână activat: el este cel care activează API-ul local al gateway-ului.

Dispozitive disponibile

Gateway Somfy TaHoma Modul
Atribute de service
Versiunea protocoluluiVersiunea API-ului local raportată de gateway
ID gatewayPIN-ul gateway-ului (de exemplu 1234-5678-9012), același PIN care face parte din adresa fiecărui dispozitiv
Starea conectivitățiiStarea conectivității raportată de gateway, de exemplu OK
Variabile personalizate
BearerToken (string)Tokenul API-ului local TaHoma, creat în aplicația TaHoma by Somfy › Developer Mode; modulul și fiecare dispozitiv îl trimit ca '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

Citire (modul)
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
Atribute de service
Protocol Version
PARSEJSON(ApiVersion, "$.protocolVersion", true)
Gateway ID
PARSEJSON(GatewayData, "[0].gatewayId", true)
Connectivity Status
PARSEJSON(GatewayData, "[0].connectivity.status", true)
Rulou / copertină io Glisare

Poziția unui rulou sau a unei copertine io-homecontrol — 0 % complet deschis, 100 % complet închis, aceeași direcție ca în gateway

numeric (0–100) Unitate: % json_path
Variabilă: DeviceUrl — Adresa motorului în gateway-ul TaHoma (deviceURL din GET /setup/devices), de exemplu io://1234-5678-9012/4820485

Rulou / copertină io

Citire (modul)
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
Citirea nivelului jaluzelei
VAR closure := PARSEJSON(StatesJson, "$.value", true);
IF ISNULL(closure)
    ADDERROR(0, "Closure state not available");
    RETURN(NaN);
END
RETURN(closure / 100);
Scrierea nivelului jaluzelei
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");
Jaluzea exterioară io Jaluzea

Poziția și unghiul lamelelor unei jaluzele exterioare io-homecontrol — ambele sunt trimise împreună într-o singură comandă

numeric (0–100) Unitate: % json_path
Variabilă: DeviceUrl — Adresa jaluzelei în gateway-ul TaHoma (deviceURL), de exemplu io://1234-5678-9012/5932104

Jaluzea exterioară io

Citire (modul)
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
Citirea nivelului jaluzelei
VAR closure := PARSEJSON(StatesJson, "$[?(@.name=='core:ClosureState')].value", true);
IF ISNULL(closure)
    ADDERROR(0, "Closure state not available");
    RETURN(NaN);
END
RETURN(closure / 100);
Scrierea nivelului jaluzelei
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
Citirea înclinării jaluzelei
VAR orientation := PARSEJSON(StatesJson, "$[?(@.name=='core:SlateOrientationState')].value", true);
IF ISNULL(orientation)
    RETURN(NaN);
END
RETURN(orientation / 100);
Scrierea înclinării jaluzelei
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
Motor RTS Comutator cu mai multe valori

Comenzi pentru un motor RTS unidirecțional — Deschide, My (poziția preferată), Stop sau Închide; RTS nu raportează poziția, de aceea comutatorul arată Pregătit după fiecare comandă

enum numeric
Valori / Stări: Pregătit · Deschide · My · Stop · Închide
Variabilă: DeviceUrl — Adresa motorului RTS în gateway-ul TaHoma (deviceURL), de exemplu rts://1234-5678-9012/987654321

Motor RTS

Citirea stării comutatorului
RETURN(0);
Scrierea stării comutatorului
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");
Conexiune: Packet Parser → HTTP • Nume gazdă: gateway-{pin}.local.local
Îmbunătățiri posibile (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.

Surse

  • 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

Ați găsit o problemă la acest șablon de dispozitiv?

Spuneți-ne ce nu funcționează, ce lipsește sau cum ar trebui să se comporte șablonul. Feedbackul dvs. ne ajută să păstrăm catalogul corect.

Comunitate — neverificat

Doriți să folosiți acest șablon în TapHome Core?

Deschideți acest șablon în Customer Portal pentru a-l aplica într-una dintre locuințele dvs. sau pentru a propune o îmbunătățire și a o trimite înapoi în catalog.

Deschideți în portal