TapHome

Somfy TaHoma – Jalousien und Rollläden io und RTS (lokale API)

Packet Parser → HTTP
Eingereicht von
Zuletzt aktualisiert: 11. 2026

Erfordert externes Gateway

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

Dieses Gerät unterstützt mDNS

Anstelle einer IP-Adresse können Sie das Gerät unter folgender Adresse erreichen:

gateway-{pin}.local.local

Ersetzen Sie {MAC} durch die MAC-Adresse des Geräts (Großbuchstaben, ohne Doppelpunkte).

TapHome unterstützt mDNS — die Verwendung eines Hostnamens ist zuverlässiger als eine statische IP.

Somfy TaHoma – Jalousien und Rollläden io und RTS (lokale API)

Die Vorlage Somfy TaHoma verbindet TapHome mit einem Somfy TaHoma Gateway (zum Beispiel TaHoma Switch) über die offizielle lokale API des Gateways, die Somfy Developer Mode nennt. Die Motoren werden wie gewohnt in der App TaHoma by Somfy mit dem Gateway gekoppelt; TapHome spricht nur mit dem Gateway, über HTTPS auf Port 8443 im lokalen Netzwerk, ohne Cloud-Verbindung.

Die Vorlage steuert io-homecontrol-Rollläden und -Markisen nach Position, io-homecontrol-Raffstores nach Position und Lamellenwinkel und sendet Einweg-RTS-Motoren die Befehle Öffnen, My, Stopp und Schließen.

Community-Vorlage — noch nicht mit TapHome getestet. Die Vorlage wurde im TapHome-Portal aus der Somfy-Dokumentation zum Developer Mode erstellt; die Namen der Gerätezustände und Befehle stammen aus Community-Quellen (Somfy führt sie nicht auf). Getestet wurde sie nur mit einem simulierten Gateway auf einem lokalen TapHome Core 2025.2, nicht mit einem echten TaHoma Gateway oder echten Somfy-Motoren, und Erfahrungen aus der Praxis sind willkommen. Laden Sie das XML auf dieser Seite herunter oder holen Sie es im TapHome-Portal: Somfy TaHoma — Community-Vorlage, und importieren Sie es als neues Modul.

Vorlage · TapHome-Portal Community Beta · nicht verifiziert
Somfy TaHoma — io and RTS shading motors (Developer Mode, local API)
Von Martin Keller
HTTP Im TapHome-Portal ansehen

Verdrahtete Somfy-Motoren brauchen kein Gateway. Einen 230-V-Somfy-Motor ohne Funkempfänger (zum Beispiel Somfy WT, vier Adern — PE, N, auf, ab) steuert TapHome direkt mit Relaismodulen wie jeden anderen Beschattungsmotor — siehe Anforderungen → Beschattung. Diese Vorlage ist für Motoren mit Funk (io-homecontrol oder RTS), die mit einem TaHoma Gateway gekoppelt sind.

Unterstützte Gateways

Laut Somfy funktioniert der Developer Mode auf der großen Mehrheit der TaHoma Gateways. Nicht verfügbar ist er auf:

  • der TaHoma Box oder Somfy Box der 1. Generation (quadratische Form)
  • dem Connectivity Kit

Hardware-Anschluss

Es ist keine Verkabelung nötig. Das TaHoma Gateway und der TapHome Core müssen im selben lokalen Netzwerk sein. Das Gateway verwendet ein Zertifikat, das von der selbstsignierten Overkiz-Zertifizierungsstelle signiert ist; die Vorlage verbindet sich unter Ignorieren von Zertifikatsfehlern, sodass kein Zertifikat installiert werden muss.

Konfiguration

Developer Mode einschalten und Token erstellen

  1. Öffnen Sie die App TaHoma by Somfy.
  2. Gehen Sie zu Configure the installation › Access the parameters Ihrer TaHoma Box.
  3. Tippen Sie 7-mal auf die PIN des Gateways (zum Beispiel 2001-1234-5678) — der Developer Mode wird eingeschaltet und die lokale API des Gateways startet.
  4. Erzeugen Sie im Menü Developer Mode ein Token.

Das Token kann nur beim Erstellen gelesen und kopiert werden — speichern Sie es sofort. Es lassen sich mehrere Tokens erzeugen; geht ein Token verloren, erzeugen Sie ein neues und tragen es in TapHome ein.

Geräteadressen ermitteln

Jeder mit dem Gateway gekoppelte Motor hat eine Adresse, die deviceURL. Die Adressen liefert die Geräteliste des Gateways mit dem Token — zum Beispiel von einem Computer im selben Netzwerk:

1

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

Suchen Sie den Motor über sein label (den Namen aus der TaHoma-App) und kopieren Sie seine deviceURL genau so, wie sie angezeigt wird. Die Vorlage kodiert sie für die Anfrage selbst.

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

Dieselbe Antwort zeigt, was jeder Motor unterstützt: definition.states und definition.commands. Die Vorlage erwartet den Zustand core:ClosureState und den Befehl setClosure bei einem Rollladen oder einer Markise, core:ClosureState, core:SlateOrientationState und setClosureAndOrientation bei einem Raffstore und open, my, stop und close bei einem RTS-Motor. Ein Motor, dessen Definition diese Namen nicht enthält, funktioniert mit dem jeweiligen Gerät nicht.

Importparameter

ImportparameterBeschreibungPlatzhalter
GatewayAddressIP-Adresse oder Hostname des TaHoma Gateways, zum Beispiel gateway-1234-5678-9012.local192.168.1.100
BearerTokenToken aus dem Developer Mode(leer)
SlideDeviceUrldeviceURL des io-Rollladens oder der io-Markiseio://1234-5678-9012/12345678
BlindDeviceUrldeviceURL des io-Raffstoresio://1234-5678-9012/12345678
RtsDeviceUrldeviceURL des RTS-Motorsrts://1234-5678-9012/12345678

Wenn Sie die IP-Adresse verwenden, reservieren Sie sie im Router für das Gateway, damit sie sich nicht ändert.

Die Vorlage enthält von jeder Art ein Gerät. Löschen Sie die Geräte, die Sie nicht brauchen. Für weitere Motoren importieren Sie die Vorlage erneut mit den anderen Adressen — jeder Import fügt ein Gateway-Modul mit eigenen Geräten hinzu — und löschen die überzähligen Geräte, oder ändern Sie die Variable DeviceUrl eines Geräts.

Gerätefunktionen

Gateway

Das Modul liest das Gateway alle 30 s und zeigt drei Service-Attribute: Protokollversion (die Version der lokalen API), Gateway-ID (die PIN des Gateways) und Verbindungsstatus (zum Beispiel OK). Bei falschem Token zeigt das Modul den Fehler „Check Bearer token in TaHoma By Somfy app → Developer Mode“.

io-Rollläden und -Markisen

  • io-Rollladen / Markise — Position eines io-homecontrol-Rollladens oder einer Markise. Das Gateway meldet 0 = ganz offen und 100 = ganz geschlossen; in TapHome ist 0 % ganz oben und 100 % ganz unten, dieselbe Richtung. Das Gerät liest die Position alle 5 s und bewegt den Motor mit dem Befehl setClosure.

io-Raffstores

  • io-Raffstore — Position und Lamellenwinkel eines io-homecontrol-Raffstores. Beide werden zusammen in einem Befehl setClosureAndOrientation gesendet, sodass eine Positionsänderung auch den aktuellen Lamellenwinkel und eine Lamellenänderung die aktuelle Position mitsendet. Ändert TapHome Position und Lamellen gleichzeitig, geht der identische Befehl nur einmal hinaus.

RTS-Motoren

RTS-Motoren (Radio Technology Somfy) sind Einweg-Funk: Sie empfangen Befehle, melden aber ihre Position nicht.

WertBefehlAktion
ÖffnenopenNach oben fahren / ganz öffnen
MymyIn die im Motor gespeicherte Lieblingsposition fahren
StoppstopBewegung stoppen
SchließencloseNach unten fahren / ganz schließen
  • RTS-Motor — nach jedem Befehl zeigt der Schalter Bereit, sodass derselbe Befehl erneut gesendet werden kann, zum Beispiel Schließen, nachdem der Motor mit seiner eigenen Fernbedienung bewegt wurde. Die Wahl von Bereit sendet Stopp.

Keines der Geräte bewegt einen Motor, wenn der TapHome Core startet: Sie übernehmen ihren Zustand vom Gateway, nicht den letzten Wert in TapHome.

So kommuniziert die Vorlage mit dem Gateway

Alle Aufrufe gehen an https://<gateway-address>:8443/enduser-mobile-web/1/enduserAPI mit dem Header Authorization: Bearer <token>; nur GET /apiVersion funktioniert ohne Token. Jedes io-Gerät liest seine Zustände alle 5 s aus /setup/devices/{deviceURL}/states, und alle Geräte senden Befehle mit POST /exec/apply. Somfy setzt für die lokale API kein Aufruflimit, warnt aber, dass zu häufige Aufrufe das Gateway überlasten und die Steuerung der Motoren verzögern — denken Sie daran, wenn viele Motoren an einem Gateway hängen.

Fehlerbehebung

Fehler „Check Bearer token in TaHoma By Somfy app → Developer Mode“

Das Gateway hat mit HTTP 401 geantwortet: Das Token ist falsch oder wurde nicht vollständig kopiert. Erzeugen Sie in der App TaHoma by Somfy › Developer Mode ein neues Token und tragen Sie es in TapHome ein.

Gerätefehler „Device unavailable (HTTP …)“

Das Gateway kennt die Adresse nicht. Prüfen Sie, ob die deviceURL genau aus GET /setup/devices kopiert ist — nicht kodiert, ohne Leerzeichen — und ob sie zur richtigen Geräteart gehört.

Gerätefehler „Closure state not available“

Das Gateway hat geantwortet, aber ohne den Zustand core:ClosureState. Prüfen Sie die definition.states des Motors. Manche Markisen melden stattdessen den Zustand core:DeploymentState (0 = eingefahren, 100 = ausgefahren); den liest die Vorlage nicht.

Gateway zeigt ein Gerät als nicht verfügbar, es funktioniert aber

Manche TaHoma-Firmware meldet io-Geräte als nicht verfügbar (available: false), obwohl sie normal funktionieren — an Somfy im Developer-Mode-Repository gemeldet. Die Vorlage verwendet dieses Kennzeichen nicht und zeigt deswegen keinen Fehler.

RTS-Motor bewegt sich nicht

RTS-Befehle sind Einweg-Funksignale ohne Zustellbestätigung, daher zeigt TapHome keinen Fehler, wenn der Motor nicht reagiert. Prüfen Sie, ob der Motor in Funkreichweite des Gateways ist und ob er sich aus der App TaHoma by Somfy bewegen lässt.

Hostname des Gateways nicht erreichbar

Wenn gateway-{pin}.local nicht aufgelöst wird, verwenden Sie die IP-Adresse des Gateways — sie steht im Router. Der Developer Mode muss eingeschaltet bleiben: Er schaltet die lokale API des Gateways frei.

Verfügbare Geräte

Somfy TaHoma Gateway Modul
Serviceattribute
ProtokollversionVersion der lokalen API, die das Gateway meldet
Gateway-IDPIN des Gateways (zum Beispiel 1234-5678-9012), dieselbe PIN, die Teil jeder Geräteadresse ist
VerbindungsstatusVerbindungsstatus, den das Gateway meldet, zum Beispiel OK
Benutzerdefinierte Variablen
BearerToken (string)Token der lokalen TaHoma-API, erstellt in der App TaHoma by Somfy › Developer Mode; das Modul und jedes Gerät senden es als '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

Lesen (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
Serviceattribute
Protocol Version
PARSEJSON(ApiVersion, "$.protocolVersion", true)
Gateway ID
PARSEJSON(GatewayData, "[0].gatewayId", true)
Connectivity Status
PARSEJSON(GatewayData, "[0].connectivity.status", true)
io-Rollladen / Markise Schieber

Position eines io-homecontrol-Rollladens oder einer Markise — 0 % ganz offen, 100 % ganz geschlossen, dieselbe Richtung wie im Gateway

numeric (0–100) Einheit: % json_path
Variable: DeviceUrl — Adresse des Motors im TaHoma Gateway (deviceURL aus GET /setup/devices), zum Beispiel io://1234-5678-9012/4820485

io-Rollladen / Markise

Lesen (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
Jalousiestellung lesen
VAR closure := PARSEJSON(StatesJson, "$.value", true);
IF ISNULL(closure)
    ADDERROR(0, "Closure state not available");
    RETURN(NaN);
END
RETURN(closure / 100);
Jalousiestellung schreiben
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");
io-Raffstore Jalousie

Position und Lamellenwinkel eines io-homecontrol-Raffstores — beide werden zusammen in einem Befehl gesendet

numeric (0–100) Einheit: % json_path
Variable: DeviceUrl — Adresse des Raffstores im TaHoma Gateway (deviceURL), zum Beispiel io://1234-5678-9012/5932104

io-Raffstore

Lesen (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
Jalousiestellung lesen
VAR closure := PARSEJSON(StatesJson, "$[?(@.name=='core:ClosureState')].value", true);
IF ISNULL(closure)
    ADDERROR(0, "Closure state not available");
    RETURN(NaN);
END
RETURN(closure / 100);
Jalousiestellung schreiben
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
Lamellenneigung lesen
VAR orientation := PARSEJSON(StatesJson, "$[?(@.name=='core:SlateOrientationState')].value", true);
IF ISNULL(orientation)
    RETURN(NaN);
END
RETURN(orientation / 100);
Lamellenneigung schreiben
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
RTS-Motor Mehrwertschalter

Befehle für einen Einweg-RTS-Motor — Öffnen, My (Lieblingsposition), Stopp oder Schließen; RTS meldet keine Position, daher zeigt der Schalter nach jedem Befehl Bereit

enum numeric
Werte / Zustände: Bereit · Öffnen · My · Stopp · Schließen
Variable: DeviceUrl — Adresse des RTS-Motors im TaHoma Gateway (deviceURL), zum Beispiel rts://1234-5678-9012/987654321

RTS-Motor

Schaltzustand lesen
RETURN(0);
Schaltzustand schreiben
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");
Verbindung: Packet Parser → HTTP • Hostname: gateway-{pin}.local.local
Mögliche Verbesserungen (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.

Quellen

  • 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

Haben Sie ein Problem mit dieser Gerätevorlage gefunden?

Sagen Sie uns, was nicht funktioniert, was fehlt oder wie sich die Vorlage verhalten sollte. Ihr Feedback hilft uns, den Katalog genau zu halten.

Community — ungeprüft

Möchtest du das in deinem TapHome Core verwenden?

Öffne diese Vorlage im Kundenportal, um sie auf eine deiner Wohnungen anzuwenden, oder entwirf eine Anpassung und reiche sie an den Katalog ein.

Im Portal öffnen