trivum HTTP-Schnittstelle
03-Mai-2018
Die HTTP-Schnittstelle trivum nimmt Anforderungen entgegen, die von einem Webbrowser problemlos getestet werden können, und gibt Antworten im XML-Format zurück. Wenn Sie in diesem Dokument Links sehen, wird durch Klicken auf diese sofort eine Beispielanforderung ausgeführt, in der die Ergebnisdaten in einem neuen Browser-Tab angezeigt werden.
1. Befehle
1.1. ZoneCommand
Ermöglicht grundlegende Dinge wie das Ausschalten einer Zone oder das Ändern der Lautstärke.
/xml/zone/runCommand.xml?zone=@zoneId&command=commandNumber
zoneId
Die ID einer Zone. Die Liste der möglichen IDs finden Sie in der
Webkonfiguration unter
Automation/trivum API
oder im Beispiel
getAll.xml.
Einige Aktoren adressieren die erste Zone aufgrund interner, nicht
verwendeter Konfigurationsdateien möglicherweise nicht mit @ 0, sondern mit
@ 1. Um dies zu beheben, können Sie die gesamte Konfiguration
zurücksetzen, indem Sie: |
Anstelle von "@ 0" kann der Zonenname angegeben werden. Wenn es Sonderzeichen enthält, schreiben Sie diese mit %neu:
/xml/zone/runCommand.xml?zone=living%20room&command=…
Befehlsnummer
Dies ist ein numerischer Befehl mit diesen möglichen Werten:
ZONECMD_POWER_OFF 001 ZONECMD_MUTE 002 toggle mute ZONECMD_MUTE_ON 680 since v9.29 ZONECMD_MUTE_OFF 681 since v9.29 ZONECMD_VOLUME_INC 003 ZONECMD_VOLUME_DEC 004 ZONECMD_VOLUME_INC2 009 ZONECMD_VOLUME_DEC2 010 ZONECMD_VOLUME_INC5 011 ZONECMD_VOLUME_DEC5 012 ZONECMD_ALLOFF 015 ZONECMD_SNOOZE 017 ZONECMD_LOCAL_SOURCE 019 if present (LineIn) ZONECMD_USE_PREV_SOURCE 029 see Zones / zone / KNX/HTTP sources ZONECMD_JOIN 030 ZONECMD_UNJOIN 031 ZONECMD_USE_NEXT_SOURCE 041 see Zones / zone / KNX/HTTP sources ZONECMD_USE_NEXT_ZONE 042 see Zones / zone / KNX/HTTP sources ZONECMD_DEFAULT_STREAMING 050 if present ZONECMD_DEFAULT_TUNER 051 if present ZONECMD_VOLUME_DEC_1 080 ZONECMD_VOLUME_DEC_10 089 ZONECMD_VOLUME_INC_1 090 ZONECMD_VOLUME_INC_10 099 MULTIKEY_BASIC_FORWARD 400 skip to next track, preset MULTIKEY_BASIC_BACKWARD 401 skip to prev. track, preset MULTIKEY_BASIC_FASTFORWARD 402 MULTIKEY_BASIC_FASTBACKWARD 403 MULTIKEY_BASIC_PLAYPAUSE 406 MULTIKEY_PLAY 431 MULTIKEY_PAUSE 432 MULTIKEY_STOP 433 MULTIKEY_STATION_DOWN 490 MULTIKEY_STATION_UP 491 MULTIKEY_NEXT_ALBUM 493 MULTIKEY_PREVIOUS_ALBUM 494 MULTIKEY_NEXT_PLAYLIST 495 MULTIKEY_PREVIOUS_PLAYLIST 496 ZONECMD_START_PAGING_1 500 ZONECMD_START_PAGING_32 531 ZONECMD_STOP_PAGING_1 550 ZONECMD_STOP_PAGING_32 581 ZONECMD_STOP_PAGING_ALL 599 ZONECMD_PRESET_1 600 ZONECMD_PRESET_7 606 ZONECMD_GROUP_START_1 621 ZONECMD_GROUP_START_8 628 ZONECMD_GROUP_STOP 630 ZONECMD_GROUP_STOP_1 631 ZONECMD_GROUP_STOP_8 638 ZONECMD_GROUP_STOP_ALL 639 ZONECMD_STREAMING_NOPLAY 641 ZONECMD_VOLUME_00 900 ZONECMD_VOLUME_99 999 ZONECMD_ROOM_VOLUME_00 1000 ZONECMD_ROOM_VOLUME_99 1099
Beispiele
Anruf | Funktion |
---|---|
|
Listen Sie alle möglichen Zonen-IDs auf. test |
|
Status einer einzelnen Zone abrufen. Optionale Parameter sind: & addSourceBasicData & addSourceStatusData |
|
Zonen mit vollständigen Gruppeninformationen auflisten. |
|
Schalten Sie die erste Zone auf default streaming. um |
|
Schalten Sie die erste Zone aus. |
|
Schalten Sie alle Zonen aus. |
|
Stumm auf |
|
Stumm ab |
1.2. Stellen Sie die Zonenquelle ein
Wählen Sie eine Zonenquelle nach Kurznamen aus
/xml/zone/set.xml?zone=@0&source=@shortSourceName
shortSourceName
Text | Aktion | Anmerkung |
---|---|---|
|
first analog input first analog input third analog input |
Depending on the Actuator hardware 0 to 8 analog inputs are supported. |
|
first FM tuner preset fifth FM tuner preset |
Requires that a default FM tuner is configured for the zone. |
|
first trivum favorite second trivum favorite |
|
|
first trivum playlist second trivum playlist |
|
|
first tunein preset second tunein preset |
|
|
default stream source of zone |
playing recent selection |
|
default FM tuner of zone |
playing recent frequency |
Beispiele
Ruf |
Anmerkung |
|
umschalten auf den ersten Analogeingang |
|
Schalten Sie auf den Standard-FM-Tuner der Zone und spielen Sie die letzte Frequenz ab |
|
Schalten Sie auf den Standard-FM-Tuner der Zone und spielen Sie die Preset-Nummer 3 |
|
Wechseln Sie zum Standard-Streaming der Zone und spielen Sie den trivum Favoriten 2 |
|
Wechseln Sie zum Standard-Streaming der Zone und spielen Sie das Tunein-Preset 5 ab |
|
Nur C4: Verwenden Sie eine Quelle nach Kartenindex n, wobei n ein numerischer Wert von 0, ist |
|
Schalten Sie alle Zonen aus. |
1.3. Stellen Sie Zonenattribut ein
Ändern Sie Grundwerte in einer Zone wie Lautstärke, Stummschaltung, Balance oder Bass.
Ruf |
Anmerkung |
|
Lautstärke von 0 bis 100 einstellen |
|
Wie |
|
Balance von -15 (ganz links) bis 15 (ganz rechts) einstellen |
|
Stellen Sie die Bassreduzierung oder -verstärkung von -15 bis 15 ein |
|
Stellen Sie die Höhenreduzierung oder -verbesserung von -15 bis 15 ein |
1.4. trivum Favoriten
Um trivum Favoriten zu erstellen:
-
spielen Sie Musikinhalte wie ein NAS-Album
-
Wählen Sie dann
…
oben rechts -
Wählen Sie dann "Fügen Sie zu trivum favorites" hinzu.
Holen Sie sich die Liste der trivum Favoriten:
/api/v1/trivum/favorite.xml
Spiele einen trivum-Favoriten:
/xml/zone/set.xml?source=@f1&zone=@0
Sie können auch Optionen hinzufügen:
Option |
Anmerkung |
|
um mit einer zufälligen Spur zu beginnen |
|
um nur zufällige Spuren zu spielen |
1.5. trivum Wiedergabelisten
Holen Sie sich die Liste der trivum Wiedergabelisten:
/api/v1/trivum/playlist.xml
Spielen Sie eine trivum-Wiedergabeliste:
/xml/zone/set.xml?source=@y1&zone=@0
Sie können auch Optionen hinzufügen:
Option |
Anmerkung |
|
um mit einer zufälligen Spur zu beginnen |
|
um nur zufällige Spuren zu spielen |
1.6. TuneIn Favoriten
Diese können auch durch "…" oben rechts erstellt werden, während eine TuneIn-Station abgespielt wird.
Holen Sie sich die Liste der TuneIn-Favoriten:
/api/v1/tunein/favorite.xml
Spielen Sie einen TuneIn-Favoriten:
/xml/zone/set.xml?source=@i1&zone=@0
1.7. FM-Voreinstellungen
FM-Presets auflisten:
/xml/system/getTunerStationList.xml
Auf C4 wird die systemweite Liste der FM-Voreinstellungen angezeigt, es sind jedoch keine lokalen Voreinstellungen pro FM-Tunerkarte gespeichert.
1.8. NAS-Status und Kontrolle
Ruf |
Anmerkung |
|
Holen Sie sich den NAS-Bibliotheksstatus |
|
Führen Sie den vollständigen NAS scan erneut aus |
1.9. Gruppenmanagement
Gruppen können durch einen Aufruf erstellt, geändert oder entfernt werden:
/xml/zone/createGroup.xml?zone=zVisu&oldgroup=zMaster&members=++----------
Parameter:
Name |
Anmerkung |
zVisu |
Index der aktuellen Zone des Visualisierungsclients |
zMaster |
Index des Gruppenmasters, dessen Musik verwendet werden soll (wenn beide Zonen derzeit unterschiedliche Quellen abspielen) |
+/- |
Zeichen, die grafisch angeben, welche Zonen an einer Gruppe teilnehmen sollen. Geben Sie beispielsweise bei einem 4-Zonen-System 4 Zeichen
oder weniger ein (wird automatisch mit |
Beispiel: Zweite Zone verbindet Wiedergabe der ersten Zone
-
Die erste Zone spielt einen Stream ab, die zweite Zone spielt den FM-Tuner ab, alle anderen Zonen sind ausgeschaltet.
-
Die zweite Zone sollte zu einer Gruppe mit der ersten Zone
hinzugefügt werden und Musik aus der ersten Zone (dem Stream) übernehmen.
/xml/zone/createGroup.xml?zone=1&oldgroup=0&members=++--
Ergebnis: Die zweite Zone spielt den gleichen Stream wie die erste Zone.
Beispiel: Die erste Zone verbindet die Wiedergabe der zweiten Zone
-
Die erste Zone spielt einen Stream ab, die zweite Zone spielt den FM-Tuner ab, alle anderen Zonen sind ausgeschaltet.
-
Die erste Zone sollte einer Gruppe mit der zweiten Zone hinzugefügt werden und Musik aus der zweiten Zone (dem Tuner) übernehmen.
/xml/zone/createGroup.xml?zone=0&oldgroup=1&members=++--
Ergebnis: In der ersten Zone wird derselbe FM-Tuner wie in der zweiten Zone abgespielt.
Das heißt, wenn beide Zonen unterschiedliche Quellen abspielen, entscheidet
"oldgroup", welche Musik nach dem Gruppenbeitritt abgespielt
werden soll.
Beispiel: Die zweite Zone sollte die Gruppe verlassen
/xml/zone/createGroup.xml?zone=0&oldgroup=0&members=+---
Relevant ist hier die Änderung von +
nach -
in der Mitgliederliste.
Ändern Sie das Volumen innerhalb einer Gruppe
Innerhalb einer Gruppe verwenden Zonen normalerweise keine isolierten
Volumes
, aber eine Änderung des Volumes wirkt sich auf alle
Gruppenmitglieder aus.
Diese Interdependenz wird vom Aufruf
behandelt:
/xml/zone/setVolume.xml
Standardmäßig setzt dieser Aufruf nicht einfach ein absolutes Volume , sondern *geht ein bisschen * in Richtung eines bestimmten Zielvolumes. Dies wird am besten mit einer + oder - Taste in Ihrer Visualisierung verwendet.
Ruf |
Anmerkung |
|
Schritt das Gruppenvolumen für die gesamte Gruppe nach unten. ID ist eine beliebige Zonen-ID aus der Gruppe. Das Volumen aller Zonenmitglieder wird um einige Schritte verringert. |
|
Erhöhen Sie das Gruppenvolumen für die gesamte Gruppe nach oben. Das Volumen aller Zonenmitglieder wird um einige Schritte erhöht. |
|
Erhöhen Sie das Volumen einer einzelnen Zone schrittweise, wirkt sich nicht auf andere Gruppenmitglieder aus. |
|
Verringern Sie die Lautstärke einer einzelnen Zone schrittweise, wirkt sich nicht auf andere Gruppenmitglieder aus. |
|
Stoppen Sie das Lautstärke-Stepping sofort. |
|
Stellen Sie das absolute Volumen für eine einzelne Zone ein, isoliert von anderen Gruppenmitgliedern. (Vorsichtig verwenden.) |
Um die neuen Informationen zur Lautstärke innerhalb einer Gruppe abzurufen, rufen Sie getChanges auf und sehen Sie in der Liste der Datenträgerstatus nach.
/xml/zone/getChanges.xml?zone=@0&visuid=90&apiLevel=2&now
Beispiel Ausgang, wenn gruppiert, unter Zone/Status:
<zone> ... <status> <volume>17</volume> - volume of zone making the getChanges call ... <group> <zone>0</zone> <volume>17</volume> - volume for zone id 0 </group> <group> <zone>1</zone> <volume>26</volume> - volume for zone id 1 </group> <group> ... </group> <groupMembers>2</groupMembers> </status> </zone>
Für eine vollständige Erklärung von getChanges siehe [Get Zone Status].
1.10. Paging
Pagings müssen in der Webkonfiguration konfiguriert werden. Dann können die folgenden Aufrufe verwendet werden:
Paging starten
/xml/paging/start.xml
Parameter
Name | Beschreibung |
---|---|
|
Paging-ID, 0 - 31 |
|
optional, 5 - 100. Wenn nicht angegeben, wird das konfigurierte Paging-Volume verwendet. |
|
optional, 5 - 100 Sekunden. Wenn nicht angegeben, werden die konfigurierten Stoppeinstellungen verwendet. |
Beispiel
/xml/paging/start.xml?id=0&volume=10&autostoptime=10
Ein Paging wird nach der festgelegten Zeit automatisch gestoppt. Sie können es jedoch früher stoppen, indem Sie:
/xml/paging/stop.xml?id=0
2. Interaktive Musikauswahl
Beginnen mit:
/xml/system/getWebTouchMenu.xml?which=music&zone=@0&visuid=90
was produziert Datensätze wie:
<row> <type>action</type> <mode>menu</mode> <action>/xml/system/getWebTouchMenu.xml?which=trivumFavorites&keypad=4</action> <icon>/imgs/visuIconServiceFavorites_128px.png</icon> <text>trivum_20favorites</text> </row>
dann pro Datensatz:
-
Dekodieren Sie das Textfeld und zeigen Sie es in Ihrer Visualisierung an.
_20
bedeutet ein Zeichen mit dem Ascii-Code 0x20 (ein Leerzeichen). -
Berühren Sie die Aktions-URL und zeigen Sie die nächste Menüebene an.
Verlassen Sie sich nicht auf die permanente Verfügbarkeit bestimmter
Menüebenen. |
3. Holen Sie sich den Zonenstatus
3.1. Synchrone
Holen Sie sich den Status einer Zone:
/xml/zone/getChanges.xml?zone=@0&visuid=90&apiLevel=2&now
Parameter
Name |
Funktion |
|
eine Zahl von 1 bis 99, um Ihre externe Visualisierungsinstanz zu identifizieren. In diesem API-Dokument wird visuid = 90 für Testanforderungen verwendet. |
|
sollte immer 2 sein. Dies erzeugt "button" xml-Objekte unter Tastatur/basic. |
|
Geben Sie sofort den neuen Zonenstatus zurück und schließen Sie die Verbindung. ohne "& now" würde der Anruf bis zu einer Zeitüberschreitung oder bis eine Änderung der Zonenstatusinformationen blockieren. |
|
Wenn zwei Visualisierungen mit demselben -Visuid auf denselben Server zugreifen, kann ein Fehler " auftreten, der zweimal verwendet wird". In diesem Fall sollte das aktuellste visu999920 beim ersten Aufruf "& reload = 1" hinzufügen, um zu sagen, dass es sich bei eindeutig um die neueste Visualisierung handelt. |
Über Steuereinheiten (Visualisierungen)
Wenn Sie Anforderungen mit "visuid = 90" senden, wird auf dem Server ein Control Unit-Objekt mit der ID 90 erstellt.
Die Liste der aktuellen Control Units in der Webkonfiguration finden Sie unter Control Units.
Nach dem ersten Zugriff wird das Gerät als "Nicht konfiguriert" aufgeführt. Sobald Sie die Konfiguration ändern, z. Wenn Sie "Off auf Power Short Press" setzen, heißt es Configured, und spätere Bereinigungen der Control Units-Liste löschen diese nicht.
Wenn für dieses Gerät keine Anforderungen vorliegen, wird es nach einiger Zeit unter " aktuell inaktive Steuergeräte" aufgeführt.
3.2. Asynchrone
Dies bedeutet, dass ein HTTP-Aufruf nicht sofort zurückgegeben wird, sondern blockiert wird, bis sich etwas ändert.
Beispiel:
/xml/zone/getChanges.xml?zone=@0&visuid=90&apiLevel=2
Beachten Sie, dass & now
fehlt. Folgendes wird passieren:
_auf den ersten Anruf: _
Eine Steuereinheit mit der ID 90 wird erstellt und mit der ersten Zone
verknüpft.
Der Anruf wird sofort mit den vollständigen
Statusdaten der Zone zurückgegeben.
_auf alle weiteren Anrufe: _
Die vorhandene Steuereinheit 90 wird wiederverwendet. Der Anruf kann blockieren, bis:
-
Eine Zeitüberschreitung ist erreicht (ca. 10 Sekunden). In diesem Fall erhalten Sie eine Antwort wie:
<Zeilen> <System> <timeout> 1 </ timeout>
-
oder bis sich etwas geändert hat, zum Beispiel die Lautstärke in der Zone.
Wenn sich zwischen zwei getChanges-Aufrufen (viele) Statusdaten auf dem Server geändert haben, wird der Aufruf möglicherweise überhaupt nicht blockiert, sondern der neue Status wird sofort zurückgegeben.
Wenn Sie eine Zeitüberschreitung erhalten, führen Sie getChanges einfach sofort erneut aus. Dies bedeutet, dass Sie getChanges endlos in einer Schleife ausführen können, beispielsweise in einem separaten E/A-Thread. Da eine Anforderung nur bei Änderungen zurückgegeben wird, verursacht dies keine Ladeprobleme mit dem Server.
Wenn Sie keine Zeitüberschreitung erhalten, d. h. der Anruf sofort oder nach einigen Sekunden (sobald sich etwas geändert hat) zurückkehrt, verarbeiten Sie die Statusdaten und führen Sie die getChanges-Anforderung erneut aus.
Anhang: Schema-Beispiel für eine Visu-Client-Anwendung
Einzel-Thread-Anwendung
Dies erfordert, dass Sie in Ihrer Programmiersprache
testen
können, ob Antwortdaten für einen Socket vorhanden sind (über den Aufruf
von select ()).
Main Thread +--+ - start: send /xml/zone/getChanges.xml?visuid=90&now | +--+ | | - loop begin: update the GUI. | | | | - process touch events from user. | | | | - send synchroneous commands like: | | /xml/zone/runCommand.xml?... | | receive reply, check rc AND process xml status data | | (same as with getChanges replies) | | | | - check if reply data exists for ongoing getChanges call | | (in C code: select() call on socket) | | IF data exists from trivum server: | | Look for <userdata name="rc">0</userdata>. | | If NOT present | | process error and wait a few seconds. | | Else if NOT a timeout | | process xml reply (status data) | | Endif | | async call (just send) | | /xml/zone/getChanges.xml&visuid=90&onlyChanges | | Endif | | | | - if no data from server within 1 minute | | // should not happen, just for safety | | async call (just send) | | /xml/zone/getChanges.xml&visuid=90&onlyChanges | | endif | | | | - re-run loop +--+
Two Thread Anwendungsbeispiel
Kann verwendet werden, wenn Sie Blocking Receives für Sockets in einem separaten E/A-Thread ausführen möchten.
Main Thread +--+ | | - update the GUI. | | | | - process touch events from user. | | | | - send synchroneous commands like: | | /xml/zone/runCommand.xml?... | | receive reply, check rc AND process xml status data | | (same as with getChanges replies) | | | | - receive status data and errors from Status Thread. | | | | - re-run this loop. +--+
Status Thread +--+ | | - IF on first loop: | | send /xml/zone/getChanges.xml?visuid=90&now | | ELSE | | send /xml/zone/getChanges.xml?visuid=90&onlyChanges | | | | - receive reply [is blocked up to 10 seconds] | | | | - Look for <userdata name="rc">0</userdata>. | | If this is NOT present then there is an error. | | Make sure not simply to re-run the loop on errors | | but at least wait a few seconds, and tell the Main Thread. | | | | - Look for <rows><system><timeout>1</timeout>. | | IF this is present THEN re-run the loop immediately. | | | | - ELSE process the reply status data, | | and copy new status data to Main Thread. | | | | - re-run this loop. +--+