Weinor Markisen mit NodeRed und Somfy API steuern

Weinor Markisen sind seit vielen Jahrzehnten im Einsatz und gelten als sehr zuverlässig. Nach dem Kauf einer neuen Weinor-Markise wollte ich diese mittels Node-Red einbinden und über Taster von Homematic-IP schalten.

Dabei habe ich festgestellt, dass die verbauten Somfy Motoren nur noch das io-Homecontrol Protokoll unterstützen. Für dieses habe ich leider keine funktionsfähigen Bibliotheken für Node-Red gefunden, die den Zugriff auf die Somfy Produkte ermöglichen. Daher habe ich mich damit beschäftigt, wie man das Thema auch ohne fremde Bibiotheken lösen kann und zeige in den folgenden Absätzen wie das trotzdem geht.  Ich verwende dazu Node-Red, über das ich auch die Schalter von Homematic-IP nutzen kann.

Wenige Grundlagen

Schon seit langem werden Weinor Markisen mit Somfy Motoren ausgestattet. Somfy unterscheidet hier zwei selbst entwickelte Technologien:

• RTS (Radio Technology Somfy): Dise unidirektionale Technologie gibt einfach nur Befehle an den Motor weitere.
• io-Homecontrol: Dies ist eine biderektionale Funktechnologie, die auch den Status von Aktoren abfragen kann. Diese wird mittlerweile auch standardmäßig in Weinor Produkten eingebaut.

Für das RTS-Prokololl gibt es eine Vielzahl von Lösungsmöglichkeiten u.a. über einen nano-CUL Stick an, der auf dem Frequenzbank 433 MHz kommuniziert. Eine Anleitung hierzu ist  u.a unter folgendem Link zu finden: https://www.byteride.com/iobroker-somfy/

Für io-Homecontrol sieht das Ganze schon deutlich schwieriger aaus, das Somfy dieses Protkoll erst seit wenigen Jahren als neues Protokoll in seinen Geräten verbaut.

Um die von mir vorgestellte Lösung nutzen zu können, braucht man einen Tahoma Switch, von Somfy, der eine Basisstation für alle Somfy-Produkte ist. Ein Somfy Connectivity Kit ist nicht geeignet. Die angelernten Geräte sich sich dann auch über eine Somfy-App sehr komfortabel einrichten und steuern.  In diesem Tahoma Switch hat Somfy eine lokale API installiert, die man für eigene Zwecke sehr schön nutzen kann, und über die die Steuerung aller Parameter eines am Tahoma-Siwtch angeschlossenen Gerätes inkl. von der Weinor-Markisen gelingt. Die vorgestellte Lösung kann somit für beliebige Somfy-Geräte verwendet werden, die an dem lokalen Tahoma-Switch angeschlossen werden.

Welche Technologie unterstützt meine Markise

Welche Technologie der Markisenmotor unterstützt ist fast immer anhand der Bezeichnung der Fernbedienung abzulesen, auf der z.B. ein kleines "io" zu finden ist, wenn die aktuelle Technologie verbaut wurde.

Alternativ  kann man sich den Aufdruck auf dem Markisenmotor anschauen, was meist etwas unpraktisch ist. Kennt man aber die Bezeichnung entweder vom Motor oder von der Fernbedienung kann man die Funktechnologien, die diese Geräte unterstützen,  auch direkt auf der Somfy-Webseite nachschauen.

Developer Mode aktivieren

Somfy hat in 2022 die Möglichkeiten zum Steuern von IOT-Devices komplett auf eine neue API umgestellt, die auf der lokalen Tahoma Basisstation aktiviert werden muss und anders angesprochen wird, als die alten APIs. Hierzu muss auf der Tahoma Basisstation der sogenannte "Developer Mode" aktiviert werden.

Man installiert den Switch wie in der Anleitung beschrieben und registriert sich bei Somfy (ohne geht es nicht, da für die Nutzung der API  Daten mit Somfy ausgetauscht werden müssen).

Loggt man sich anschließend in seinen Account ein, sollte die Box unter "Produkte" erscheinen und aktiv sein (sonst bitte nochmal die Installationsschritte prüfen).

Unter dem Link "Tahoma/Connexoon bedienen" findet man nun die Möglichkeit den Developermode zu aktivieren. Sobald dieser aktiviert wurde sollte das Ergebnis wie folgt aussehen:

Den PIN-Code, der angezeigt wird kopiert man, da dieser später noch benötigt wird. Wird die Möglichkeit zum Aktivieren des Entwicklermodus nicht angezeigt, dann ist ein Gerät nicht für die folgenden Schritte geeignet (z.B. Connexoon-Box, Connectivity Kit). Mit Aktivierung des Developer Modes wird der Zugriff auf die API freigeschaltet.

Session ID erzeugen

Alle Schritte für das Generieren und das Ansprechen der Befehle sind von den Entwicklern in der Doku Somfy Tahoma Developer Mode beschrieben. Da dies aber für den Laien echt kryptisch klingt, erkläre ich die wichtigen Schritte detailliert in den folgenden Absätzen.

Für die nächsten Schritte empfehle ich, das Tool Postman zu verwenden, da die Kommunikation auch über POST-Befehle erfolgt und ein normaler Browser diese nicht unterstützt. Natürlich kann man das Ganze auch über curl machen, aber ich finde Postman einfacher. Im Prinzip braucht man nur die freie Version vom Postman zu installieren, d.h. eine Registrierung ist nicht erforderlich.

Zuerst muss eine Session ID erzeugt werden, die die aktive Kommunikation mit der Somfy API authentifiziert.

Hierzu wählt man in Postman in der oberen Zeile den Befehl "POST" aus (das kann man leicht vergessen und dann gibt es schnell einen Fehler, wenn da noch GET drinsteht) und gibt im nachfolgenden Feld die folgende Adresse ein:

https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/login

Nun müssen noch die folgenden Parameter in den Reitern unterhalb der Adresszeile ergänzt werden:

Nach dem Drücken auf "Send" sollte als Ergebnis folgendes erscheinen:

Wichtig ist dass irgendwo "sucess: true" steht und im Bereiche Cookies ein Cookie Code verfügbar ist. Diese Session ID ist erforderlich, um im nächsten Schritt einen dauerhaften Token anzulegen, mit dem man zukünftig alle Befehle authentifizieren kann. Der Vorteil von Postman ist, dass er diesen Cookie mit der Session ID "behält" und automatisch für die folgenden Befehle verwendet.

Token erzeugen

Die Kommunikation mit der API erfordert grundsätzlich eine Authentifizierung. Dazu muss ein Token generiert werden, der zukünftig bei jedem Befehl an die Tahoma Box mitgesendet wird. Auch hierzu braucht man nun Postman.

Dazu wird zuerst GET Befehl mit der folgenden Syntax benötigt:

https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/config/{{pod}}/local/tokens/generate

{{pod}} ist dabei die PIN des Gateways, die man wie oben beschreiben unter den Geräteinformation des Tahoma Switch findet. Der Befehl lautet dann beispielsweise:

https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/config/2031-1587-1994/local/tokens/generate

Auch hier gibt man nun in Postman folgende Parameter an:

Weitere Angaben müssen nicht gemacht werden, da die Authentifizierung über die im vorigen Abschnitt generierte Session ID erfolgt. Nun kann der Befehl wieder per "Send" ausgeführt werden.

Tipp: Wenn der Fehler "{"errorCode":"RESOURCE_ACCESS_DENIED","error":"Not authenticated"}" erscheint, dann ist aus irgendeinem Grund die SessionID abgelaufen. Hier hilft es, einfach den Befehl aus dem vorigen Abschnitt nochmal aufzurufen (einfach in Postman den Reiter wechseln und wieder auf SEND drücken) und schon sollte es wieder funktionen. D.h. die Befehle zur Erzeugung der Session ID sowie des Tokens sollten zeitlich nicht zu weit auseinander liegen.

Als Ergebnis sollte man einen 20-stelligen alphanumerischen Tokenwert erhalten, den man zur weiteren Verwendung kopiert (siehe Bild).

Token aktivieren

Um den Token nutzen zu können, muss er noch aktiviert werden. Dies wird wieder durch einen POST Befehl im folgenden Format erreicht:

https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/config/{{pod}}/local/tokens

{{pod}} ist dabei wieder die PIN des Gateways, der Befehl lautet dann beispielsweise:

https://ha101-1.overkiz.com/enduser-mobile-web/enduserAPI/config/2031-1587-1994/local/tokens

Hier gibt man nun folgende Parameter an:

Nach dem Absenden des Befehls erhält man eine RequestID als Bestätigung, die angibt, dass der Befehl an die API erfolgreich versendet wurde (und gleich abgearbeitet wird).

Nun sind alle Voraussetzungen geschaffen, um die API zu nutzen.

Parameter zur Steuerung identifizieren

Welche Parameter (in diesem Fall eine Markise) ein Somfy Gerät besitzt und auf welche Befehle es reagiert, lässt sich nun einfach herausfinden. Dazu braucht man  nur die Devices im Tahoma Switch abzufragen (ähnliche wie bei einer CCU mit DevConfig) und sich die gelieferten Daten anzuschauen. Hierzu kann man wieder Postman verwenden oder die folgende interaktive Somfy Developer Webseite benutzen, die auf die lokale API zugreift:

https://somfy-developer.github.io/Somfy-TaHoma-Developer-Mode/#/Api/get_apiVersion

Dort trägt man oben als erstes die Geräte-PIN ein, der Port bleibt auf 8443 stehen. Durch Klicken auf den grünen "Auhorize-Button", kann man den vorhin generierten Token angeben.

Nun können die auf der Webseite dargestellten Funktionsaufrufe genutzt werden.

Unter der Rubrik "Setup" findet man den Befehl "GET /setup/devices". Dieser wird ausgeführt und als  Ergebnis erhält man eine riesige JSON-Datei mit allen Geräten, Paramatern, Befehlen und Namen der Devices, die über die Tahoma Box ansprechbar sind.

Aus der Datei habe ich die folgende Zeile heruasgesucht (sie enthält auch die bekannte Switch Adresse), die wie im folgenden Beispiel aussieht:

"deviceURL": "io://2031-1587-1994/4637294"

Dies ist die Adresse, unter der meine Markise intern angesprochen werden kann. Jeder Geräteblock in dieser Datei beginnt mit einer solchen deviceURL.

Tipp: Wer mehrere Geräte über eine Tahoma Box angeschlossen hat, sollte diesen Geräten über die Somfy App einen aussagekräftigen Namen geben, denn dieser Name taucht immer kurz nach der deiveURL auf. So kann man sicher sein, dass man das richtige Gerät erwischt hat.

Ebenso brauche ich den Namen des Geräte, der in einer weiteren Zeile zu finden ist:

"label": "Markise SUNEA"

Scrollt man weiter runter, findet man irgendwann auch eine Zeile, die mit "commands" beginnt. Hier sind nun alle Commands aufgeführt, auf das ein Somfy Gerät reagiert. In meinem Fall brauche ich nur den Befehlsnamen (CommandName) "open".

Markise über Postman steuern

Ich habe jetzt alle Parameter zusammen, um meine Markise über Postman mit einem Befehl an die Somfy API ausfahren zu lassen. Die Befehlssyntax hierzu lautet:

PUT https://gateway-{{PIN}}.local:8443/enduser-mobile-web/1/enduserAPI/exec/apply

In meinem Fall lautet der Befehl wie folgt:

https://gateway-2031-1587-1994.local:8443/enduser-mobile-web/1/enduserAPI/exec/apply

Folgende Parameter werden angegeben:

Nach dem Absenden erhält man wieder eine "execID" und die Markise fährt aus.

Befehl über Node-Red ausführen

Den gleichen Befehl wie für Postman kann man auch über NodeRed ausführen lassen. Dort kann ich dann auch andere System einbinden und die Markise auf z.B. den Tastendruck eines Schalters reagieren lassen.

Ein einfacher Flow zum Ausfahren der Markise ist in folgendem Bild dargstellt:

Ich verwende in dem Beispiel einen Input Node. Dieser muss als JSON-Objekt konfiguriert werden, da er den RAW-Text für den Body des PUT Befehls erzeugt.

Der http Request Node wird wie folgt konfiguiert:

Wichtig hierbei ist, dass im Gegensatz zum Postman-Beispiel in der Zieladresse das ".local" weggelassen wird. Bei der TLS-Konfiguration gibt es nichts besonderes zu beachten.

Dieses Beispiel kann nun beliebig erweitert werden. Ich frage hierüber bereits den Status der Markise ab, steuere diese über einen HMIP-Schalter und lasse sie einfahren, wenn es anfängt zu regnen oder der Wind zu stark ist.