TapHome

Somfy TaHoma – żaluzje i rolety io i RTS (lokalne API)

Packet Parser → HTTP
Dodane przez
Ostatnia aktualizacja: 11. 2026

Wymaga zewnętrznej bramki

Somfy TaHoma with Developer Mode (local API, HTTPS port 8443) — strona produktu

To urządzenie obsługuje mDNS

Zamiast adresu IP możesz połączyć się z urządzeniem pod adresem:

gateway-{pin}.local.local

Zastąp {MAC} adresem MAC urządzenia (wielkie litery, bez dwukropków).

TapHome obsługuje mDNS — użycie nazwy hosta jest bardziej niezawodne niż statyczny IP.

Somfy TaHoma – żaluzje i rolety io i RTS (lokalne API)

Szablon Somfy TaHoma łączy TapHome z bramką Somfy TaHoma (na przykład TaHoma Switch) przez oficjalne lokalne API bramki, które Somfy nazywa Developer Mode. Silniki paruje się z bramką jak zwykle w aplikacji TaHoma by Somfy; TapHome komunikuje się tylko z bramką, przez HTTPS na porcie 8443 w sieci lokalnej, bez połączenia z chmurą.

Szablon steruje położeniem rolet i markiz io-homecontrol, położeniem i kątem listew żaluzji zewnętrznych io-homecontrol, a jednokierunkowym silnikom RTS wysyła polecenia Otwórz, My, Stop i Zamknij.

Szablon społeczności — jeszcze nie przetestowany z TapHome. Szablon powstał w portalu TapHome na podstawie dokumentacji Somfy do trybu Developer Mode; nazwy stanów i poleceń urządzeń pochodzą ze źródeł społeczności (Somfy ich nie wymienia). Przetestowano go tylko z symulatorem bramki na lokalnym TapHome Core 2025.2, nie z prawdziwą bramką TaHoma ani z prawdziwymi silnikami Somfy, a doświadczenia z praktyki są mile widziane. Pobierz XML z tej strony lub z portalu TapHome: Somfy TaHoma — szablon społeczności, i zaimportuj go jako nowy moduł.

Szablon · portal TapHome Społeczność Beta · niezweryfikowany
Somfy TaHoma — io and RTS shading motors (Developer Mode, local API)
Autor: Martin Keller
HTTP Zobacz w portalu TapHome

Przewodowe silniki Somfy nie potrzebują bramki. Silnikiem Somfy na 230 V bez odbiornika radiowego (na przykład Somfy WT, cztery przewody — PE, N, góra, dół) TapHome steruje bezpośrednio modułami przekaźnikowymi, jak każdym innym silnikiem zacieniania — zobacz Wymagania → Zacienianie. Ten szablon jest przeznaczony dla silników radiowych (io-homecontrol lub RTS) sparowanych z bramką TaHoma.

Obsługiwane bramki

Według Somfy tryb Developer Mode działa na zdecydowanej większości bramek TaHoma. Nie jest dostępny na:

  • TaHoma box lub Somfy box 1. generacji (kwadratowy kształt)
  • Connectivity Kit

Połączenie sprzętowe

Okablowanie nie jest potrzebne. Bramka TaHoma i TapHome Core muszą być w tej samej sieci lokalnej. Bramka używa certyfikatu podpisanego przez samopodpisany urząd certyfikacji Overkiz; szablon łączy się z ignorowaniem błędów certyfikatu, więc nie trzeba instalować żadnego certyfikatu.

Konfiguracja

Włączenie trybu Developer Mode i utworzenie tokenu

  1. Otwórz aplikację TaHoma by Somfy.
  2. Przejdź do Configure the installation › Access the parameters swojej bramki TaHoma.
  3. Stuknij 7 razy w PIN bramki (na przykład 2001-1234-5678) — włącza się Developer Mode i startuje lokalne API bramki.
  4. W menu Developer Mode wygeneruj token.

Token można odczytać i skopiować tylko przy jego tworzeniu — od razu go zapisz. Można wygenerować wiele tokenów; jeśli token zaginie, wygeneruj nowy i wpisz go w TapHome.

Ustalenie adresów urządzeń

Każdy silnik sparowany z bramką ma adres, deviceURL. Adresy podaje lista urządzeń bramki odczytana z tokenem — na przykład z komputera w tej samej sieci:

1

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

Znajdź silnik po jego label (nazwa z aplikacji TaHoma) i skopiuj jego deviceURL dokładnie tak, jak jest wyświetlony. Szablon sam go zakoduje na potrzeby żądania.

ProtokółFormatPrzykład
io-homecontrolio://{gateway-pin}/{device-id}io://1234-5678-9012/4820485
RTSrts://{gateway-pin}/{device-id}rts://1234-5678-9012/987654321

Ta sama odpowiedź pokazuje, co obsługuje każdy silnik: definition.states i definition.commands. Szablon oczekuje stanu core:ClosureState i polecenia setClosure przy rolecie lub markizie, core:ClosureState, core:SlateOrientationState i setClosureAndOrientation przy żaluzji oraz open, my, stop i close przy silniku RTS. Silnik, którego definicja nie zawiera tych nazw, nie będzie działał z danym urządzeniem.

Parametry importu

Parametr importuOpisWartość zastępcza
GatewayAddressAdres IP lub nazwa hosta bramki TaHoma, na przykład gateway-1234-5678-9012.local192.168.1.100
BearerTokenToken z trybu Developer Mode(puste)
SlideDeviceUrldeviceURL rolety lub markizy ioio://1234-5678-9012/12345678
BlindDeviceUrldeviceURL żaluzji ioio://1234-5678-9012/12345678
RtsDeviceUrldeviceURL silnika RTSrts://1234-5678-9012/12345678

Jeśli używasz adresu IP, zarezerwuj go dla bramki w routerze, aby się nie zmieniał.

Szablon ma po jednym urządzeniu każdego rodzaju. Usuń urządzenia, których nie potrzebujesz. Dla kolejnych silników zaimportuj szablon ponownie z innymi adresami — każdy import dodaje moduł bramki z własnymi urządzeniami — i usuń zbędne urządzenia albo zmień zmienną DeviceUrl urządzenia.

Możliwości urządzeń

Bramka

Moduł odczytuje bramkę co 30 s i pokazuje trzy atrybuty serwisowe: Wersja protokołu (wersja lokalnego API), ID bramki (PIN bramki) i Stan łączności (na przykład OK). Przy błędnym tokenie moduł pokazuje błąd „Check Bearer token in TaHoma By Somfy app → Developer Mode”.

Rolety i markizy io

  • Roleta / markiza io — położenie rolety lub markizy io-homecontrol. Bramka zgłasza 0 = całkowicie otwarta i 100 = całkowicie zamknięta; w TapHome 0 % to pozycja całkiem u góry, a 100 % całkiem na dole, ten sam kierunek. Urządzenie odczytuje położenie co 5 s i porusza silnikiem poleceniem setClosure.

Żaluzje zewnętrzne io

  • Żaluzja zewnętrzna io — położenie i kąt listew żaluzji zewnętrznej io-homecontrol. Oba są wysyłane razem w jednym poleceniu setClosureAndOrientation, więc zmiana położenia wysyła też aktualny kąt listew, a zmiana listew aktualne położenie. Gdy TapHome zmienia jednocześnie położenie i listwy, identyczne polecenie wychodzi tylko raz.

Silniki RTS

Silniki RTS (Radio Technology Somfy) to jednokierunkowe radio: odbierają polecenia, ale nie zgłaszają swojego położenia.

WartośćPolecenieDziałanie
OtwórzopenRuch w górę / całkowite otwarcie
MymyPrzejście do ulubionej pozycji zapisanej w silniku
StopstopZatrzymanie ruchu
ZamknijcloseRuch w dół / całkowite zamknięcie
  • Silnik RTS — po każdym poleceniu przełącznik pokazuje Gotowy, więc to samo polecenie można wysłać ponownie, na przykład Zamknij po tym, jak silnik został poruszony własnym pilotem. Wybór Gotowy wysyła Stop.

Żadne z urządzeń nie porusza silnikiem przy starcie TapHome Core: stan przejmują z bramki, a nie z ostatniej wartości w TapHome.

Jak szablon komunikuje się z bramką

Wszystkie wywołania idą na https://<gateway-address>:8443/enduser-mobile-web/1/enduserAPI z nagłówkiem Authorization: Bearer <token>; bez tokenu działa tylko GET /apiVersion. Każde urządzenie io odczytuje swoje stany z /setup/devices/{deviceURL}/states co 5 s, a wszystkie urządzenia wysyłają polecenia przez POST /exec/apply. Somfy nie ustala limitu wywołań lokalnego API, ale ostrzega, że zbyt częste wywołania przeciążają bramkę i opóźniają sterowanie silnikami — pamiętaj o tym przy wielu silnikach na jednej bramce.

Rozwiązywanie problemów

Błąd „Check Bearer token in TaHoma By Somfy app → Developer Mode”

Bramka odpowiedziała HTTP 401: token jest błędny lub nie został skopiowany w całości. Wygeneruj nowy token w aplikacji TaHoma by Somfy › Developer Mode i wpisz go w TapHome.

Błąd urządzenia „Device unavailable (HTTP …)”

Bramka nie zna adresu. Sprawdź, czy deviceURL jest skopiowany dokładnie z GET /setup/devices — niezakodowany, bez spacji — i czy należy do właściwego rodzaju urządzenia.

Błąd urządzenia „Closure state not available”

Bramka odpowiedziała, ale bez stanu core:ClosureState. Sprawdź definition.states silnika. Niektóre markizy zgłaszają zamiast niego stan core:DeploymentState (0 = zwinięta, 100 = rozwinięta); tego szablon nie odczytuje.

Bramka pokazuje urządzenie jako niedostępne, ale ono działa

Niektóre wersje oprogramowania TaHoma zgłaszają urządzenia io jako niedostępne (available: false), chociaż działają normalnie — zgłoszono to Somfy w repozytorium Developer Mode. Szablon nie używa tego znacznika i nie pokazuje z jego powodu błędu.

Silnik RTS się nie rusza

Polecenia RTS to jednokierunkowe sygnały radiowe bez potwierdzenia dostarczenia, dlatego TapHome nie pokazuje błędu, gdy silnik nie reaguje. Sprawdź, czy silnik jest w zasięgu radiowym bramki i czy rusza się z aplikacji TaHoma by Somfy.

Nazwa hosta bramki jest nieosiągalna

Jeśli gateway-{pin}.local nie jest rozwiązywana, użyj adresu IP bramki — znajdziesz go w routerze. Developer Mode musi pozostać włączony: to on udostępnia lokalne API bramki.

Dostępne urządzenia

Bramka Somfy TaHoma Moduł
Atrybuty serwisowe
Wersja protokołuWersja lokalnego API zgłaszana przez bramkę
ID bramkiPIN bramki (na przykład 1234-5678-9012), ten sam PIN, który jest częścią adresu każdego urządzenia
Stan łącznościStan łączności zgłaszany przez bramkę, na przykład OK
Zmienne niestandardowe
BearerToken (string)Token lokalnego API TaHoma, utworzony w aplikacji TaHoma by Somfy › Developer Mode; moduł i każde urządzenie wysyłają go jako '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

Odczyt (moduł)
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
Atrybuty serwisowe
Protocol Version
PARSEJSON(ApiVersion, "$.protocolVersion", true)
Gateway ID
PARSEJSON(GatewayData, "[0].gatewayId", true)
Connectivity Status
PARSEJSON(GatewayData, "[0].connectivity.status", true)
Roleta / markiza io Suwak

Położenie rolety lub markizy io-homecontrol — 0 % całkowicie otwarta, 100 % całkowicie zamknięta, ten sam kierunek co w bramce

numeric (0–100) Jednostka: % json_path
Zmienna: DeviceUrl — Adres silnika w bramce TaHoma (deviceURL z GET /setup/devices), na przykład io://1234-5678-9012/4820485

Roleta / markiza io

Odczyt (moduł)
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
Odczyt poziomu rolety
VAR closure := PARSEJSON(StatesJson, "$.value", true);
IF ISNULL(closure)
    ADDERROR(0, "Closure state not available");
    RETURN(NaN);
END
RETURN(closure / 100);
Zapis poziomu rolety
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");
Żaluzja zewnętrzna io Roleta

Położenie i kąt listew żaluzji zewnętrznej io-homecontrol — oba są wysyłane razem w jednym poleceniu

numeric (0–100) Jednostka: % json_path
Zmienna: DeviceUrl — Adres żaluzji w bramce TaHoma (deviceURL), na przykład io://1234-5678-9012/5932104

Żaluzja zewnętrzna io

Odczyt (moduł)
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
Odczyt poziomu rolety
VAR closure := PARSEJSON(StatesJson, "$[?(@.name=='core:ClosureState')].value", true);
IF ISNULL(closure)
    ADDERROR(0, "Closure state not available");
    RETURN(NaN);
END
RETURN(closure / 100);
Zapis poziomu rolety
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
Odczyt nachylenia lameli
VAR orientation := PARSEJSON(StatesJson, "$[?(@.name=='core:SlateOrientationState')].value", true);
IF ISNULL(orientation)
    RETURN(NaN);
END
RETURN(orientation / 100);
Zapis nachylenia lameli
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
Silnik RTS Przełącznik wielowartościowy

Polecenia dla jednokierunkowego silnika RTS — Otwórz, My (ulubiona pozycja), Stop lub Zamknij; RTS nie zgłasza położenia, dlatego przełącznik po każdym poleceniu pokazuje Gotowy

enum numeric
Wartości / Stany: Gotowy · Otwórz · My · Stop · Zamknij
Zmienna: DeviceUrl — Adres silnika RTS w bramce TaHoma (deviceURL), na przykład rts://1234-5678-9012/987654321

Silnik RTS

Odczyt stanu przełącznika
RETURN(0);
Zapis stanu przełącznika
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");
Połączenie: Packet Parser → HTTP • Hostname: gateway-{pin}.local.local
Możliwe ulepszenia (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.

Źródła

  • 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

Znalazłeś problem z tym szablonem urządzenia?

Napisz nam, co nie działa, czego brakuje lub jak powinien zachowywać się szablon. Twoja opinia pomaga nam utrzymać katalog dokładnym.

Społeczność — niezweryfikowane

Chcesz tego użyć w swoim TapHome Core?

Otwórz ten szablon w portalu klienta, aby zastosować go w swoim domu, lub zaproponuj modyfikację i wyślij ją z powrotem do katalogu.

Otwórz w portalu