Smart-Home-API aktivieren und ansprechen

App-Entwicklung für Philips Hue

| Autor / Redakteur: Mirco Lang / Stephan Augsten

Über die Philips Hue Bridge lassen sich mittlerweile allerhand Smart-Home-Funktionen erdenken und umsetzen.
Über die Philips Hue Bridge lassen sich mittlerweile allerhand Smart-Home-Funktionen erdenken und umsetzen. (Bild gemeinfrei: HeikoAL - Pixabay.com / Pixabay)

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.

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"}“.

Das eingebaute API-Utility der Hue-Zentrale.
Das eingebaute API-Utility der Hue-Zentrale. (Bild: Lang)

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:

curl 192.168.178.100/api/ABCDEabcde1234567890/lights

Via json_pp gibt es Infos wie Name, ID und Produktbezeichnung auch schön formatiert.
Via json_pp gibt es Infos wie Name, ID und Produktbezeichnung auch schön formatiert. (Bild: Lang)

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:

#!/bin/sh

curl 192.168.178.119/api/ABCDEabcde1234567890/lights | grep -o -P "\"name.*?[,]" > 0
curl 192.168.178.119/api/ABCDEabcde1234567890/lights | egrep -o "\"[0-9]{1,2}\".{0,3}:{1}" >1
paste 1 0
rm 1 0

Die Ausgabe des Miniskripts genügt, um Leuchten gezielt über IDs ansprechen zu können.
Die Ausgabe des Miniskripts genügt, um Leuchten gezielt über IDs ansprechen zu können. (Bild: Lang)

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:

curl 192.168.178.100/api/ABCDEabcde1234567890/lights/1

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:

curl -X PUT --data '{"on":true}' --url 192.168.178.100 /api/ABCDEabcde1234567890/lights/1/state

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:

#!/bin/sh

while true
do
   curl -X PUT --data '{"on":true}' --url 192.168.178.100/api/ABCDEabcde1234567890/lights/$1/state
   sleep 1
   curl -X PUT --data '{"on":false}' –url 192.168.178.100/api/ABCDEabcde1234567890/lights/$1/state
   sleep 1
done

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 …

curl 192.168.178.100/api/ABCDEabcde1234567890/resourcelinks | json_pp

… 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.

Kommentare werden geladen....

Kommentar zu diesem Artikel

Der Kommentar wird durch einen Redakteur geprüft und in Kürze freigeschaltet.

Anonym mitdiskutieren oder einloggen Anmelden

Avatar
Zur Wahrung unserer Interessen speichern wir zusätzlich zu den o.g. Informationen die IP-Adresse. Dies dient ausschließlich dem Zweck, dass Sie als Urheber des Kommentars identifiziert werden können. Rechtliche Grundlage ist die Wahrung berechtigter Interessen gem. Art 6 Abs 1 lit. f) DSGVO.
  1. Avatar
    Avatar
    Bearbeitet von am
    Bearbeitet von am
    1. Avatar
      Avatar
      Bearbeitet von am
      Bearbeitet von am

Kommentare werden geladen....

Kommentar melden

Melden Sie diesen Kommentar, wenn dieser nicht den Richtlinien entspricht.

Kommentar Freigeben

Der untenstehende Text wird an den Kommentator gesendet, falls dieser eine Email-hinterlegt hat.

Freigabe entfernen

Der untenstehende Text wird an den Kommentator gesendet, falls dieser eine Email-hinterlegt hat.

copyright

Dieser Beitrag ist urheberrechtlich geschützt. Sie wollen ihn für Ihre Zwecke verwenden? Infos finden Sie unter www.mycontentfactory.de (ID: 45895923 / Embedded Software)