Smart-Home-API aktivieren und ansprechen App-Entwicklung für Philips Hue

Die Smart-Home-Lösung Philips Hue ist einsteigerfreundlich und birgt Chancen für Entwickler: Hue bietet eine simple API – und der Hersteller weist eindeutig darauf hin, dass Dritte eigene Hue-Apps entwickeln und auch kommerziell verwerten dürfen.

Anbieter zum Thema

PresseBox - unn | UNITED NEWS NETWORK GmbH

Mit Philips Hue könnte das Konzept Smart Home in großem Maße in deutsche Haushalte einziehen. Bedienung und Installation sind einfach, die Qualität stimmt, dank ZigBee-Protokoll können auch Dritthersteller einbezogen werden und man kann ganz klein einsteigen.

Der Markt ist noch jung, das Potenzial enorm und der Einstieg ziemlich einfach; das perfekte Spielfeld also für Entwickler – nicht zuletzt, weil sie im Hue-Universum schnell erste Erfolge verzeichnen können. Und was den Markt angeht: Die Zeiten, als es im Wesentlichen die Hue-Leuchten und ein wenig Zubehör zu sehen gab, sind gezählt.

Mittlerweile gibt es allein von Philips selbst dutzende Lampen und Leuchten für innen und außen, diverse Sensoren und Schalter. Aber auch traditionelle Hersteller von Hauselektronik sind längst auf den Zug aufgesprungen, jüngst hat beispielsweise Busch-Jaeger Hue-kompatible Schalter-Linien herausgebracht und Jung hat ebenfalls passende Produkte im Portfolio.

Das Zentrum der Entwicklung ist natürlich die API. Was hier gleich auf Anhieb gefällt: Der Zugriff auf und die Arbeit mit der Programmierschnittstelle erfordern weder ein Entwicklerkonto bei Philips noch eine Online-Verbindung. Es genügt die lokale Hue Bridge. Dazu muss zunächst ein Nutzer angelegt werden, um eine User-ID zu erhalten; beispielsweise über ein bereits auf der Bridge laufendes Formular.

Anschließend ist es ganz simpel über HTTP-Anfragen mit der API zu kommunizieren. Im Folgenden führen wir Sie Schritt für Schritt vom Prozedere der Anmeldung über die Auflistung aller und Ansprache einzelner Leuchten bis hin zu einem Minimalskript, um einzelne Leuchten blinken zu lassen. Hinzu kommt ein Überblick der API-Funktionen.

Hue-API freischalten

Zunächst müssen Sie eine ID generieren, um überhaupt Befehle absetzen zu können. Dazu nutzen Sie am besten das Formular „Clip API Debugger“, das bereits auf der Hue läuft. Suchen Sie zunächst die IP Ihrer Bridge heraus und rufen Sie das Formular dann über „http://192.168.178.100/debug/clip.html“ auf. Im Feld URL tragen Sie „/api“ ein – das steht auch allen anderen Anfragen voran. Unter „Message Body" folgt nun ein „{"devicetype":"foobar"}“ – statt foobar kann hier natürlich beliebiger Text stehen; Philips nutzt hier in der Dokumentation zum Beispiel „{"devicetype":"my_hue_app#iphone Peter"}“.

Anschließend drücken Sie den Knopf auf der Bridge, damit die API sieht, dass Sie auch tatsächlich physische Kontrolle über das Gerät haben – andernfalls würde gleich eine Fehlermeldung folgen. Nun können Sie das Formular über „POST“ absenden. Als Antwort bekommen Sie unter anderem einen Part in der Art „"username": "ABCDEabcde1234567890"“. Kopieren Sie sich das “ABCDEabcde1234567890” heraus. Diese ID werden Sie für alle künftigen Anfragen an die API benötigen.

Hue-Leuchten abfragen

Einfacher lässt sich die API natürlich über die Kommandozeile ansprechen, wo sich HTTP-Anfragen üblicherweise mit dem Programm „curl“ erledigen lassen, das es sowohl für Windows als auch für Linux gibt, wo es in der Regel bereits vorinstalliert ist. Ein erster Aufruf soll zunächst mal alle vorhandenen Leuchten samt Eigenschaften auflisten:

Hier sehen Sie bereits den grundsätzlichen Aufbau: „URL/api/User-ID/Geräteklasse“. Die Ausgabe ist alles andere als hübsch, dank JSON-Format können Sie sie aber deutlich aufhübschen, indem Sie sie zum Beispiel, zumindest unter Linux, an das Tool „json_pp“ pipen. Dann werden die Infos sauber als Baum aufgelistet. Das Gute: Sie sehen hier auf einen Blick, welche Eigenschaften die Lights-API bietet.

Im Grunde wollen Sie aber etwas anderes: Einzelne Leuchten werden leider über ihre IDs angesprochen, nicht über ihre Namen. Sie müssen also zunächst wissen, welche Leuchte welche ID hat. Die vielleicht einfachste Variante ist ein Skript, das aus der obigen Liste die Namen und die IDs ausliest und als zweispaltige Tabelle darstellt:

Ohne jetzt exakt auf die regulären Ausdrücke der grep-Abfragen einzugehen: Zunächst werden die Namen ausgelesen und in der Hilfsdatei „0“ gespeichert, dann die IDs in der Datei „1“. Per paste-Befehl werden beide Dateien nebeneinander als Spalten ausgegeben und anschließend wieder gelöscht. Das ist eindeutig quick and dirty, genügt aber fürs Erste und sollte einfacher nachvollziehbar sein.

Über die IDs können Sie nun beispielsweise Lampen-Status abfragen:

Das Grundschema wird also auf „URL/api/User-ID/Geräteklasse/Gerät“ erweitert.

Hue-Leuchten steuern

Interessant wird es aber erst, wenn die Leuchten nicht bloß abgefragt, sondern auch manipuliert werden sollen. Hier kommen nun POST-Anfragen ins Spiel, für die curl ein paar Zeichen mehr benötigt. Angenommen, man möchte die Leuchte mit der ID „1“ einschalten:

Zunächst wird curl mit „-X PUT“ mitgeteilt, dass es sich um eine PUT-Anfrage handelt. Über „--data“ wird nun eingeleitet, was anfangs im Formular der „Message Body“ war. Den Part „{"on":true}“ finden Sie natürlich auch in der obigen Statusabfrage der Leuchten – neben vielen weiteren Eigenschaften, die sich allesamt über eine solche PUT-Anfrage manipulieren lassen.

Das Grundschema wird also abermals erweitert: „URL/api/User-ID/Geräteklasse/Gerät/Eigenschaft“ – und wie die Eigenschaft aussieht, steht im Datenbereich. Freilich lassen sich im Datenbereich auch mehrere Eigenschaften gleichzeitig unterbringen. Und das ist im Grunde auch schon alles, was Sie grundsätzlich über die Verwendung der API wissen müssen. Ein ganz simples Skript „mein-blink“, um eine Leuchte über „./mein-blink ID“ blinken zu lassen, könnten dann so aussehen:

Die ID wird also einfach über den Skript-Aufruf als Parameter übergeben und im Skript wie üblich über „$1“ angesprochen. Dieses Blinkverhalten könnten Sie nun zum Beispiel mit einer if-Abfrage an das Vorhandensein bestimmter Begriffe in einer System-Logdatei koppeln. Und schon hätten Sie ein rudimentäres Warnsystem aufgebaut.

Weitere API-Funktionen

Die komplette API-Referenz findet sich bei Philips, allerdings ist dafür eine Anmeldung erforderlich. Die Ansprache entspricht im Wesentlichen immer dem obigen Muster. Neben der Lights-API gibt es noch folgende Bereiche: Groups, Schedules, Scenes, Sensors, Rules, Configuration, Resourcelinks, Capabilities.

Bis auf die Resourcelinks dürften die anderen API-Bereiche selbsterklärend sein. Die einzelnen Optionen der Bereiche sind in der API-Referenz sauber aufgelistet. Über die Resourcelinks werden schlicht und ergreifend Fähigkeiten, Routinen und andere Ressourcen gruppiert. Eine Übersicht aller verfügbaren Resourcelinks bekommen Sie wieder über …

… sauber aufgelistet – das gilt natürlich für alle API-Bereiche.

Übrig bleibt im Grunde nur noch ein einziger Punkt: Remote Authentication. Wenn Sie eine App entwickelt haben, sollen Nutzer diese natürlich einfach einsetzen können und natürlich braucht es dafür wieder eine Authentifizierung. Dazu müssen Sie sich dann letztlich doch bei Philips Hue anmelden und ein Token für Ihre App ordern, wie es in der API-Referenz unter „Remote Authentication“ beschrieben ist.

(ID:45895923)