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):

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:

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:

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:

Zum Ausschalten würde folgendes verwendet werden:

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:

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:

Ü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:

Der folgende Befehl verringert die Helligkeit um einen bestimmten Wert:

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):

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 ;)

Passende Beiträge


2 Comments

  • Frank

    22. Juli 2017

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

    Reply
    • Philipp

      Philipp

      23. Juli 2017

      Freut mich. Immer gerne ;)

      Reply

Schreibe einen Kommentar