Hue API

application programming interface

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.

Inhalt / Vorgehensweise

  • 1:
    IP der Bridge ermitteln
  • 2:
    Clip API Debugger aufrufen
  • 3:
    Anlegen eines Bridge-Users
  • 4:
    Test
1. IP der Bridge ermitteln
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.
2. Clip API Debugger aufrufen
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.
3. Anlegen eines Bridge-Users
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.
4. Test
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.
[
	{
		"success": {
			"username": "1028456e54a661cd463b2f336"
		}
	}
]

Beispielantwort: Lampen-Übersicht

{
    "1": {
        "state": {
            "on": true,
            "bri": 144,
            "hue": 13088,
            "sat": 212,
            "xy": [0.5128,0.4147],
            "ct": 467,
            "alert": "none",
            "effect": "none",
            "colormode": "xy",
            "reachable": true
        },
        "type": "Extended color light",
        "name": "Meine hue Lampe",
        "modelid": "LCT001",
        "swversion": "66009461"
    },
    "2": {
        "state": {
            "on": false,
            "bri": 0,
            "hue": 0,
            "sat": 0,
            "xy": [0,0],
            "ct": 0,
            "alert": "none",
            "effect": "none",
            "colormode": "hs",
            "reachable": true
        },
        "type": "Extended color light",
        "name": "Opferlampe",
        "modelid": "LCT001",
        "swversion": "66009461"
    }
}

Weiterführende Links

Philips Hue - Gruppe

HIER DREHT ES SICH ALLES RUND UM DAS PHILIPS HUE SYSTEM.
Facebook-Gruppe über das Philips Hue System sowie kompatible Soft- und Hardware.

Hue Developer Programm

Offizielle Seite des Hue Developer Programmes
Umfangreiche Anleitung zur Verwendung des integrierten CLIP API Debuggers der Hue Bridge

Copyright © 2019 Elias Ruemmler All Rights Reserved.