Zugegeben – Programmieren lernt man nicht von heute auf morgen und erst recht nicht an einem komplexen Beispiel, wie dem Benutzen der von Philips bereitgestellten API. Dennoch ist es kein Hexenwerk, was da „unter der Haube“ so passiert, wenn man mit einer App sein Hue-System bedient.
Rudimentär für die Benutzung der API ist ein authentifizieren Users. Wie man diesen User anlegt und einen zugehörigen Username erhält soll in diesem Artikel kurz beschrieben werden.
Die IP der eigenen Bridge wird in den verschiedenen Apps (iConnectHue, all4hue, etc.) angezeigt. Alternativ lässt sie sich am eigenen „Router“ auslesen oder mit dem Tool NetworkScanner ermitteln.
Der API Debugger lässt sich direkt im Browser über folgende URL aufrufen. Der Platzhalter <IP der Bridge> ist durch die in Schritt 1 ermittelte IP Adresse der eigenen Bridge zu ersetzen.
http://<IP der Bridge>/debug/clip.html
Dies sollte man der Einfachheit halber am besten mit einem Computer machen. Ein Smartphone würde sicherlich auch gehen, nur wäre die Eingabe der nachfolgenden Befehle dann unter Umständen nicht so einfach möglich. Wichtig ist nur, dass sich der Computer im selben Netzwerk wie die Bridge befindet und ein aktueller Internetbrowser verwendet wird.
Um Änderungen auf der Bridge vornehmen zu können bedarf es eines authentifizieren Users. Ein neuer User beziehungsweise Username lässt sich mit folgenden Kommando anlegen. Zu spezifizieren ist ein Gerätename und ein „App-Name“. Als „App-Name“ kann zum Beispiel mein_clip_user gewählt werden, wichtig ist das der Name keine Sonder- und/oder Leerzeichen enthält. Beim Gerätename kann zum Beispiel der Name des verwendeten Computers angegeben werden (ist aber nicht zwingend), im Beispiel unten ist Mein Computer angegeben. Der resultierende String ("mein_clip_user#Mein Computer") setzt sich aus beiden Angaben zusammen, die Trennung erfolgt mit dem #-Zeichen, dieses Schema ist dringend einzuhalten.
URL (CLIP)
/api
Body
{"devicetype":"mein_clip_user#Mein Computer"}
Method
Als Antwort bekommt man zuerst eine Fehlermeldung mit dem Hinweis link button not pressed. Betätigt man nun den Bridge-Button und sendet die Anfrage mit POST erneut, bekommt man einen Username zugewiesen, siehe „Beispielantwort: Neuer Username“. Diesen Username sollte man sich notieren, er kann auch für zukünftige Bridge-Zugriffe verwendet werden.
Um den neu angelegten Username zu testen kann eine erste Anfrage an die API gesendet werden. Zum Beispiel kann man die Übersicht aller verbundenen Leuchtmittel und Leuchten abfragen, dazu wird folges Kommando per GET gesendet.
URL (CLIP)
/api/<Username>/lights
Body
Method
Die Antwort auf das /lights Kommando enthält eine Übersicht der verbundenen Leuchtmittel und Leuchten, sortiert nach der intern vergebenen Light-ID.
Tipp
Gibt man in der Adresszeile eines Internet-Browsers eine URL ein, passiert wird auch eine GET-Anfrage ausgelöst. Es ist also möglich GET-Anfrage auch ohne den CLIP-Debugger an die Bridge zu stellen. Die Antwort wird dann direkt im Browser ausgegeben. Besonders hilfreich ist hierbei die automatische Formatierung von JSON. Die komplette URL, welche im Browser eingegeben werden muss sieht wie folgt aus:
URL (Browser)
http://<IP der Bridge>/api/<Username>/lights
Wie die Ausgabe aussehen könnte zeigt das untenstehende „Beispielantwort: Lampen-Übersicht“.
Beispielantwort: Neuer Username
Ein neuer Bridge-User wurde erfolgreich angelegt. Der generierte username lautet in diesem Beispiel 1028456e54a661cd463b2f336.