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:
System/Backup/Restore/Reset alle Konfigurationsdaten

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

/xml/zone/getAll.xml

Listen Sie alle möglichen Zonen-IDs auf. test

/xml/zone/get.xml?zone=@0

Status einer einzelnen Zone abrufen. Optionale Parameter sind: & addSourceBasicData & addSourceStatusData

/xml/zone/getSelection.xml?grouped

Zonen mit vollständigen Gruppeninformationen auflisten.

/xml/zone/runCommand.xml?zone=@0&command=50

Schalten Sie die erste Zone auf default streaming. um

/xml/zone/runCommand.xml?zone=@0&command=1

Schalten Sie die erste Zone aus.

/xml/zone/runCommand.xml?zone=@0&command=15

Schalten Sie alle Zonen aus.

/xml/zone/runCommand.xml?zone=@0&command=680

Stumm auf

/xml/zone/runCommand.xml?zone=@0&command=681

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

a

a1

a3

first analog input

first analog input

third analog input

Depending on the Actuator hardware 0 to 8 analog inputs are supported.

p

p5

first FM tuner preset

fifth FM tuner preset

Requires that a default FM tuner is configured for the zone.

f

f2

first trivum favorite

second trivum favorite

y

y2

first trivum playlist

second trivum playlist

i

i2

first tunein preset

second tunein preset

s

default stream source of zone

playing recent selection

t

default FM tuner of zone

playing recent frequency

Beispiele

Ruf

Anmerkung

/xml/zone/set.xml?zone=@0&source=@a1

umschalten auf den ersten Analogeingang

/xml/zone/set.xml?zone=@0&source=@t

Schalten Sie auf den Standard-FM-Tuner der Zone und spielen Sie die letzte Frequenz ab

/xml/zone/set.xml?zone=@0&source=@p3

Schalten Sie auf den Standard-FM-Tuner der Zone und spielen Sie die Preset-Nummer 3

/xml/zone/set.xml?zone=@0&source=@f2

Wechseln Sie zum Standard-Streaming der Zone und spielen Sie den trivum Favoriten 2

/xml/zone/set.xml?zone=@0&source=@i5

Wechseln Sie zum Standard-Streaming der Zone und spielen Sie das Tunein-Preset 5 ab

/xml/zone/set.xml?zone=@1@source=@n

Nur C4: Verwenden Sie eine Quelle nach Kartenindex n, wobei n ein numerischer Wert von 0, ist

/xml/zone/runCommand.xml?zone=@0&command=15

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

/xml/zone/set.xml?zone=@0&volume=10

Lautstärke von 0 bis 100 einstellen

/xml/zone/set.xml?zone=@0&action=1

Wie / xml/zone/runCommand.xml, um einen numerischen Befehl auszuführen, in diesem Fall` ZONECMD_POWER_OFF (1) `

/xml/zone/set.xml?zone=@0&balance=0

Balance von -15 (ganz links) bis 15 (ganz rechts) einstellen

/xml/zone/set.xml?zone=@0&bass=-5

Stellen Sie die Bassreduzierung oder -verstärkung von -15 bis 15 ein

/xml/zone/set.xml?zone=@0&treble=5

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

&sequence=random-sequential

um mit einer zufälligen Spur zu beginnen

&sequence=random-random

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

&sequence=random-sequential

um mit einer zufälligen Spur zu beginnen

&sequence=random-random

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

/xml/system/getMusicCenterStatus.xml

Holen Sie sich den NAS-Bibliotheksstatus

/xml/system/scanMusicCenterShares.xml

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 - gefüllt) .

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

/xml/zone/setVolume.xml?id=@0&volume=0

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.

/xml/zone/setVolume.xml?id=@0&volume=99

Erhöhen Sie das Gruppenvolumen für die gesamte Gruppe nach oben. Das Volumen aller Zonenmitglieder wird um einige Schritte erhöht.

/xml/zone/setVolume.xml?id=@0&groupMemberVolume=99

Erhöhen Sie das Volumen einer einzelnen Zone schrittweise, wirkt sich nicht auf andere Gruppenmitglieder aus.

/xml/zone/setVolume.xml?id=@0&groupMemberVolume=0

Verringern Sie die Lautstärke einer einzelnen Zone schrittweise, wirkt sich nicht auf andere Gruppenmitglieder aus.

/xml/zone/setVolume.xml?id=@0&stop

Stoppen Sie das Lautstärke-Stepping sofort.

/xml/zone/setVolume.xml?id=@0&groupMemberVolume=50&absolute

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

id

Paging-ID, 0 - 31

volume

optional, 5 - 100. Wenn nicht angegeben, wird das konfigurierte Paging-Volume verwendet.

autostoptime

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&amp;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.
Insbesondere die von Musikdiensten bereitgestellten Menüs können sich im Laufe der Zeit ändern.

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

visuid

eine Zahl von 1 bis 99, um Ihre externe Visualisierungsinstanz zu identifizieren.

In diesem API-Dokument wird visuid = 90 für Testanforderungen verwendet.

apiLevel

sollte immer 2 sein. Dies erzeugt "button" xml-Objekte unter Tastatur/basic.

now

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.

reload=1

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