Philipp

Nanoleaf Aurora via API-Zugriff per Homematic steuern

Nachdem ich bereits beschrieben habe, wie sich Osram Lightify (zum Artikel), Philips Hue (zum Artikel) und ein Yamaha AV-Receiver (zum Artikel) über Homematic steuern lassen, möchte ich heute auf die Steuerung einer Nanoleaf Aurora über Homematic eingehen. Somit kann bei Bewegung im Wohnzimmer automatisch die Aurora loslegen. Beim Verlassen der Wohnung wird sie mit allen anderen Lampen abgeschaltet.

Leider ist es etwas umständlicher als bei Philips Hue, da für vieles HTTP PUT requests anstelle von HTTP GET verwendet werden. Somit wird eine Zusatzsoftware bei der ersten Einrichtung benötigt, um die HTTP Anfragen zu erstellen. Auf der CCU2 wird CUxD benötigt. In diesem Tutorial gehe ich auf alle wesentlichen Zwischenschritte ein, es sind also keine Programmierkenntnisse erforderlich. Lediglich ein Browser Addon sollte man installieren können.

Grundlegender Ablauf

Die grundsätzliche Vorgehensweise ist relativ einfach, aber leider sind recht viele Schritte notwendig. Als erster Schritt muss ein Benutzerzugriff auf die API angelegt werden. Die Account-Zugangsdaten können nicht verwendet werden. Die Zugangsdaten werden von dem Hub in Form eines API Tokens vergeben. Dabei handelt es sich um einen zufälligen Wert, mit dem der API Zugriff geschützt wird.

Anschließend können Kommandos über HTTP-PUT Anfragen an den Nanoleaf Hub geschickt werden. Eine HTTP-PUT Anfrage kann leider nicht so einfach, wie eine GET Anfrage in der Browserleiste geschickt werden. Dazu ist Zusatzsoftware nötig.

Auf der CCU2 kann der HTTP PUT request über CUxD erstellt werden.

Wichtiger Hinweis: Die IP des Nanoleaf Hubs muss unbedingt fest im Router eingestellt werden! Wie das geht, steht im Handbuch des jeweiligen Routers im Kapitel über DHCP. Sollte dieser Schritt ignoriert werden, wird die Steuerung irgendwann nicht mehr funktionieren!!!

Erzeugen eines Access Tokens am Nanoleaf Hub

Um die sogenannte PUT Anfrage zu senden, verwende ich das Browser-Plugin Postman für Chrome. Für Firefox verwende ich HttpRequester, funktioniert genau so aber die Screenshots in diesem Artikel zeigen Postman.

Nach der Installation von Postman, kann das Plugin wie ein eigenständiges Programm über die Startleiste gestartet werden. Ab hier sollte Nanoleaf vollständig eingerichtet sein und voll funktionsfähig sein (Eingesteckt/WLAN verbunden). Weiterhin muss die IP bekannt sein.


Die folgenden Schritte sind nun sehr genau zu befolgen:

Test der Verbindung und des Plugins: In die Adressleiste von Postman wird folgendes eingegeben (die IP ersetzen):

http://192.168.1.xyz:16021/api/v1/new

Links neben der Leiste muss ein großes GET stehen, anschließend schickt ein Klick auf den blauen Send Button die Anfrage ab. Nach kurzer Zeit sollte das Ergebnis so aussehen:

Solange rechts kein „401 Unauthorized“ erscheint, stimmt etwas nicht. In dem Fall bitte prüfen, ob die IP korrekt ist und ob der Nanloeaf Hub überhaupt über die App erreichbar ist. Wenn das funktioniert hat, geht es weiter.

Anmelden an dem Nanoleaf Hub: Als nächstes wird von GET auf POST umgestellt (links von der Adressleiste) aber noch nicht gesendet, der Inhalt ist weiterhin:

http://192.168.1.xyz:16021/api/v1/new

Um zu Bestätigen, dass ihr kein Angreifer aus dem Internet seid, muss nun der Power Knopf am Hub für ein paar Sekunden (5-7 ) gedrückt werden. Sobald die beiden LEDs am Hub zu blinken beginnen, geht es zurück an den Rechner. Innerhalb von 30 Sekunden wird die Anfrage durch einen Klick auf Send abgeschickt. Nun solltet ihr im Body den Token sehen. Das sollte dann so aussehen:

Solltet ihr anstelle des Tokens und des Status Codes „200 OK“ (rechte Seite), den Code „403 Forbidden“ bekommen, habt ihr das 30 Sekunden Zeitfenster verpasst oder den Knopf nicht richtig gedrückt. Einfach nochmal versuchen.

Den Token solltet ihr euch irgendwo wegspeichern, er wird später benötigt. Falls er verloren geht, kann einfach ein neuer auf dem gleichen Weg generiert werden.

Testen der Kommandos: Ich empfehle die Kommandos vorher immer via Postman zu testen, bevor sie mit der CCU2 geschickt werden. So ist die Fehlerdiagnose wesentlich einfacher. Die eigentlichen Kommandos werden via HTTP-PUT abgesetzt, dazu also auf PUT umstellen und folgenden Inhalt in die Adressleiste kopieren, dabei natürlich IP und Token ersetzen:

http://192.168.1.xyz:16021/api/v1/pZ8dfgkHGB3Hye6V8QKdehKlE4lk/state

Im unteren Bereich muss nun der Message Body eingestellt werden. Dazu unterhalb der Adressleiste auf Body klicken und darunter auf raw. In das Textfeld unten wird folgender Inhalt eingegeben, um die Lampe einzuschalten:

{"on" : {"value":true}}

Zum Ausschalten würde folgendes verwendet werden:

{"on" : {"value":false}}

Ein Klick auf Send schickt das Kommando und löst die Aktion aus. Der Statuscode bei Erfolg ist „204 No Content„. Falls die Lampe nicht in Sichtweite ist, kann einfach die App verwendet werden um zu kontrollieren, ob der Befehl korrekt verarbeitet wurde ;)

Im ganzen sollte das in Postman dann so aussehen:

Alles wichtige habe ich in Rot markiert, den Status Code in Grün. Ab jetzt kann mit der CCU2 weiter gemacht werden.

Zur Vollständigkeit, der Zustand der Nanoleaf Aurora kann per HTTP-GET über die folgende URL ausgelesen werden:

http://192.168.1.xyz:16021/api/v1/pZ8dfgkHGB3Hye6V8QKdehKlE4lk/state

Ansprechen der Nanoleaf API über die CCU2

Auf der CCU2 muss CUxD installiert sein und es muss ein System.Exec Gerät angelegt sein. Wie das geht habe ich hier beschrieben. Der Artiekl ist zwar über Philips Hue, aber weiter unten wird die Einrichtung von CUxD erläutert.

Wie ein Script angelegt wird sollte bekannt sein. Das Script um einen Befehl per HTTP-Put an den Nanoleaf Hub zu schicken, wird folgendes Script erstellt:

!Nanoleaf Aurora
!------------------------------
!__IP Adresse des Nanoleaf Hubs
string ip_address = "192.168.1.166";

!__Token
string api_key="pZ8dfgkHGB3Hye6V8QKdehKlE4lk";

!__Kommando
string reqdata="{\"on\" : {\"value\":true}}";

!------ NICHT MODIFIZIEREN-------
string request="/usr/local/addons/cuxd/curl -X PUT -H \"Content-Type: application/json\" -d '" # reqdata # "' http://" # ip_address # ":16021/api/v1/" # api_key # "/state/";
 dom.GetObject("CUxD.CUX2801001:1.CMD_EXEC").State(request);

Über die Funktion Skript Testen im unteren Bereich der Programmübersicht, kann das Skript manuell gestartet werden, ohne dass zuvor ein Trigger definiert werden muss.

Soll die Aurora ausgeschaltet werden, wird in dem Kommando einfach das true durch false ersetzt.

Um die Helligkeit auf einen bestimmten Wert (hier 60%) zu setzen, muss das Kommando wie folgt angepasst werden:

string reqdata="{\"brightness\" : {\"value\":60}}";

Der folgende Befehl verringert die Helligkeit um einen bestimmten Wert:

string reqdata="{\"brightness\" : {\"increment\":-10}}";

Starten eines Effekts

Um die Aurora einen bestimmten Effekt abspielen zu lassen, muss der API-Endpunkt angepasst werden, das passiert hinter den „nicht modifizieren“ Teil. Da die Erfahrung zeigt, dass sowas bei vielen Usern zu Problemen führt, kopiere das das angepasste Skript komplett rein. Ich empfehle auch, das einfach so zu übernehmen (natürlich mit eigenem API Key und IP):

!Nanoleaf Aurora
!------------------------------
!__IP Adresse des Nanoleaf Hubs
string ip_address = "192.168.1.166";

!__Token
string api_key="pZ8dfgkHGB3Hye6V8QKdehKlE4lk";

!__Effekt waehlen, aktuell Snowfall
string reqdata="{\"select\" : \"Snowfall\"}";

!------ NICHT MODIFIZIEREN-------
string request="/usr/local/addons/cuxd/curl -X PUT -H \"Content-Type: application/json\" -d '" # reqdata # "' http://" # ip_address # ":16021/api/v1/" # api_key # "/effects/";
 dom.GetObject("CUxD.CUX2801001:1.CMD_EXEC").State(request);

Damit sollten alle wichtigen Funktionen erklärt worden sein, die API kann natürlich mehr, aber das sollte dann in der App erledigt werden. Ich hoffe es lässt sich zu Hause reproduzieren und bereitet euch viel Freude ;)

Interessante Beiträge:

/15 Kommentare/von
15 Kommentare
  1. Ersch
    Ersch sagte:

    Hallo,
    danke für diese tolle Anleitung. Ich habe meine Nanoleaf Shapes an einem Homematic IP HmIPW-WRC6 6-fach Taster hängen und alle 6 Tasten mit unterschiedlichen Effekten belegt, die ich mit kurzem Tastendruck ansteuern kann. Bei langem Tastendruck schalte ich die Shapes mit dem Befehl

    string reqdata=“{\“on\“ : {\“value\“:false}}“;

    wieder aus. Nun habe ich das Problem, dass die Shapes nach undefinierter und unregelmäßiger Zeit wieder von alleine wie von Geisterhand einschalten. Ich habe bereits die Firmware der Nanoleafs von 7 auf 8.5.1 aktualisiert, auch den kompletten Nanoleaf Hub reseted, mit neuem Token versehen, aber ohne Erfolg. Hat jemand auch das Phänomen? Kann ein zusätzliche Befehl über Homematic Script abgesendet werden, der das dauerhafte Ausschalten noch untermauert?. Oder gibt es zum Ausschalten gar noch einen anderen Befehl?

    Antworten
  2. Christian
    Christian sagte:

    N`Abend zusammen,
    Danke erst einmal für diese tolle Anleitung, hatte bei mir Anfangs ganz gut geklappt. Leider kann ich seit heute keine Ansteuerung mehr vornehmen. Hat das zufällig noch jemand? Ein Nanoleaf klappt bei mir gar nicht mehr, kann auch irgendwie nicht neu eingespielt werden. Ein anderes ist zwar über die App ansteuerbar, aber ist nicht im WLAN und kann demnach auch keine Befehle erhalten.

    Antworten
  4. Chris
    Chris sagte:

    Moin, bin ich der einzige bei dem die Ansteuerung der Nanoleaf Aurora nicht mehr funktioniert?
    Von heute auf morgen ging es nicht mehr. Unter Info bei CUx Deamon sehe ich das die Befehle richtig gesendet werden. Nur an Nanoleaf passiert halt nichts. Trage ich unter Postman die Befehle manuell ein, lässt sich Nanoleaf erfolgreich ansteuern.
    Hat jemand eine Idee woran das liegen kann?

    Antworten
  5. Michael
    Michael sagte:

    Tolle Anleitung. Eine Frage habe ich aber dazu. Der Zustand wird mir leider nicht angezeigt. Ich habe zwar AN / AUS, sehe aber nicht in welchem Zustand er sich befindet. Gibt es hier eine Möglichkeit oder habe ich etwas übersehen?

    Antworten
  6. Timo S.
    Timo S. sagte:

    Danke für das tolle Tutorial!
    Postman möchte sich jetzt lieber als separate App installieren und der Link zu Cux-Daemon ist jetzt https://www.homematic-inside.de/addons

    Hat es irgendjemand geschafft, die „basic“ Farben (Daylight, Reading light, Warm white) in die CCU3 zu bekommen? Ich habe die Werte via Postman ausgelesen und ins Script eingetragen – passt aber nicht komplett.

    Antworten
  7. Sven
    Sven sagte:

    Hallo Phillip,

    vielen Dank für die tolle Anleitung hat perfekt geklappt.
    Ich hätte noch eine Frage wie kann ich die Helligkeit um +10 machen?
    string reqdata=“{\“brightness\“ : {\“increment\“:+10}}“;
    Habe das minus in plus gemacht das funktioniert aber nicht.
    Hast du einen Tipp für mich.

    Gruß Sven

    Antworten
  13. Frank
    Frank sagte:

    Hallo Philipp,
    vielen Dank für den tollen Bericht. Ist super nachzuvollziehen und hat auf Anhieb geklappt.
    Danke dafür :-)

    Antworten

Hinterlasse einen Kommentar

An der Diskussion beteiligen?
Hinterlasse uns deinen Kommentar!

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert