HTTP API Guide

Die nützlichste öffentliche Schnittstelle

Das öffentliche kuandoHUB-Manual dokumentiert sowohl eine einfache HTTP-GET-API als auch eine umfangreichere HTTP-POST-API. Für die meisten App-Integrationen ist POST die bessere langfristige Schnittstelle.

1. Voraussetzungen

Bevor irgendein Skript funktioniert:

1. Installiere und starte kuandoHUB.
2. Aktiviere die HTTP-Schnittstelle in den Advanced Settings.
3. Stelle sicher, dass die HTTP-Prioritätszeile aktiviert ist, wenn die HTTP-Quelle das Licht beeinflussen soll.
4. Nutze den standardmäßigen lokalen Listener, sofern du ihn nicht ausdrücklich geändert hast.

Das Manual gibt an:

• Standard-Listener-URL ist http://localhost:8989/,
• lokale Anfragen benötigen kein Token,
• ein Token ist nur für den Remote-Zugriff von anderen Geräten erforderlich,
• die Listener-URL kann über Einstellungen/Registry konfiguriert werden.

2. Schnellste Option: HTTP GET

GET ist für einfache Automatisierung und schnelle Tests in Ordnung.

Einfarbig

http://localhost:8989?action=light&red=100&green=0&blue=0

Alarm mit Ton

http://localhost:8989?action=alert&red=100&sound=5&volume=25

Blinken

http://localhost:8989?action=blink&blue=100&ontime=5&offtime=5

Jingle

http://localhost:8989?action=jingle&red=100&sound=3&volume=100

Pulsieren

http://localhost:8989?action=pulse&red=100&blue=100

Farbe mit Blitz

http://localhost:8989?action=colorwithflash&green=100&flashblue=100

Aus

http://localhost:8989?action=off

kuandoTimer

http://localhost:8989?action=kuandoTimer&command=start

Im Manual unterstützte Timer-Befehle:

• start
• stop
• pause
• mcontinue
• reset

3. Bessere Option: HTTP POST

POST akzeptiert JSON und unterstützt das umfangreichere SDK-artige Befehlsmodell, einschließlich der Registrierung eigener Datenquellen und der Prioritätseinrichtung.

Die üblichen JSON-Felder sind:

• action
• sender
• eventtype
• eventname
• parameter

parameter ist in den dokumentierten Beispielen selbst ein eingebetteter JSON-String.

4. Minimaler POST-Lichtbefehl

{
  "action": "Light",
  "sender": "SDK",
  "eventtype": "Light",
  "eventname": "Color",
  "parameter": "{\"RedRgbValue\":0,\"GreenRgbValue\":100,\"BlueRgbValue\":0}"
}

5. Nützliche POST-Befehle

Befehl	Wofür du ihn nutzt
Light	Eine einfarbige Farbe setzen
Alert	Farbe plus Ton
Blink	Einfaches Ein/Aus-Blinken
Jingle	Ton-Benachrichtigung mit Farbe
Pulse	Puls-Sequenz
ColorWithFlash	Einfarbige Basisfarbe plus Blitzfarbe
Off	Licht ausschalten
RegisterDataSource	Eine eigene logische Quelle in kuandoHUB anlegen
CreateInitialPriority	Deine Quelle zu den kuandoHUB-Prioritäten hinzufügen

6. Warum RegisterDataSource wichtig ist

Wenn du willst, dass sich deine App wie eine erstklassige Quelle innerhalb der kuandoHUB-Prioritäten verhält, ist POST mehr als nur „Lichtfarbe setzen".

Das Manual dokumentiert:

• RegisterDataSource, um deinen eigenen Quellennamen und deine Ereignisfamilien zu registrieren.
• CreateInitialPriority, um deine Quelle in die Prioritätskonfiguration einzufügen.

Das bedeutet, du kannst deine eigene App in das eingebaute Quellen-Arbitrierungsmodell von kuandoHUB integrieren, statt nur ad hoc Farben zu senden.

7. Ton- und Lautstärkewerte

Das öffentliche Manual listet Ton-IDs:

• 0: kein Ton
• 1: Fairy Tale
• 2: Funky
• 3: Kuando Train
• 4: Open Office
• 5: Quiet
• 6: Telephone Nordic
• 7: Telephone Original
• 8: Telephone Pick Me Up

Dokumentierte Lautstärkewerte:

• 100
• 75
• 50
• 25
• 0

8. GET oder POST

Nutze GET, wenn:

• du einen schnellen Proof of Concept willst,
• der Befehl einfach ist,
• du das Licht aus einem Webhook oder einer URL auslöst.

Nutze POST, wenn:

• du eine strukturierte Integration willst,
• du eine eigene Datenquelle registrieren willst,
• du eine konsistente Ereignisbenennung brauchst,
• du planst, über ein paar fest verdrahtete Lichtaufrufe hinauszuwachsen.