trivum HTTP-Schnittstelle

03-Mai-2018

Die HTTP-Schnittstelle von trivum nimmt Anfragen entgegen, die von einem Webbrowser einfach 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, die Ergebnisdaten in einer neuen Browserregisterkarte anzeigt.

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 Stellglieder können die erste Zone aufgrund von internen, nicht verwendeten Konfigurationsdateien möglicherweise nicht mit @ 0, sondern mit @ 1 adressieren. Um dies zu beheben, können Sie die gesamte Konfiguration zurücksetzen, indem Sie: + System/Backup/Restore/Reset alle Konfigurationsdaten zurücksetzen

Anstelle von '@ 0' kann der Zonenname angegeben werden. Wenn es Sonderzeichen enthält, überschreiben Sie diese mit%:

/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_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

Anruf	Funktion
`/xml/zone/getAll.xml`	Listen Sie alle möglichen Zonen-IDs auf. test
`/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

/xml/zone/getAll.xml

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

/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

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.
`i` `i2`	first tunein preset second tunein preset	Requires that a default FM tuner is configured for the zone.
`s`	default stream source of zone	playing recent selection
`t`	default FM tuner of zone	playing recent frequency

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.

i

i2

first tunein preset
second tunein preset

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

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=@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 Zahlenwert 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

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. TuneIn Favoriten

Diese können auch durch "…" rechts oben erzeugt werden, während eine TuneIn-Station spielt.

Holen Sie sich die Liste der TuneIn-Favoriten:

/api/v1/tunein/favorite

Spielen Sie einen TuneIn-Favoriten:

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

1.6. FM-Voreinstellungen

FM-Presets auflisten:

/xml/system/getTunerStationList.xml

_An C4 zeigt dies die systemweite Liste der FM-Presets, aber keine lokalen Presets, die pro FM-Tuner-Karte gespeichert sind.

1.7. 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.8. 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 der Visualisierung client

zMaster

Index des Gruppenmasters, dessen Musik verwendet werden soll (wenn beide Zonen gerade unterschiedliche Quellen spielen)

+/-

Zeichen, die grafisch darstellen, welche Zonen in 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, die zweite Zone spielt FM-Tuner, alle anderen Zonen sind aus.
- Die zweite Zone sollte zu einer Gruppe mit der ersten Zone + hinzugefügt werden und sie sollte 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, die zweite Zone spielt FM-Tuner, alle anderen Zonen sind aus.
- Die erste Zone sollte zu einer Gruppe mit der zweiten Zone hinzugefügt werden, und sie sollte 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 spielen, entscheidet
"oldgroup", welche Musik gespielt wird, nachdem die Gruppe beigetreten ist.

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 Volumenänderung betrifft alle Gruppenmitglieder. + Diese gegenseitige Abhängigkeit wird durch den Aufruf behandelt:

/xml/zone/setVolume.xml

Standardmäßig wird mit diesem Aufruf nicht einfach ein absolutes Volumen festgelegt, sondern es schreitet ein Stückchen in die Richtung eines bestimmten Zielvolumens. Dies wird am besten mit einem + oder - Knopf in Ihrer Visualisierung verwendet.

Ruf

Anmerkung

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

Schränken Sie die Gruppenlautstärke für die gesamte Gruppe nach unten herunter. ID ist eine beliebige Zonen-ID aus der Gruppe. Die Lautstärke aller Zonenmitglieder wird um ein paar Schritte verringert.

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

Stellen Sie die Gruppenlautstärke für die gesamte Gruppe nach oben. Die Lautstärke aller Zonenmitglieder wird um einige Schritte erhöht.

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

Erhöhen Sie die Lautstärke einer einzelnen Zone schrittweise, beeinflusst andere Gruppenmitglieder nicht.

/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 absolute Lautstärke für eine einzelne Zone ein, isoliert von anderen Gruppenmitgliedern. (Verwenden Sie vorsichtig.)

Um die neuen Informationen zum Lautstärkepegel innerhalb einer Gruppe zu erhalten, rufen Sie getChanges auf und schauen Sie sich die Liste der Lautstärkestatus an.

/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.9. Paging

Zahlungen müssen in der Webkonfiguration konfiguriert werden. Dann können die folgenden Anrufe verwendet werden:

Paging starten *

/xml/paging/start.xml

Parameter

Name Beschreibung

Name	Beschreibung
`id`	Paging-ID, 0 - 31
`volume`	optional, 5 - 100. Wenn nicht mitgeliefert, wird das konfigurierte Paging-Volumen verwendet.
`autostoptime`	optional, 5 - 100 Sekunden. Wenn nicht mitgeliefert, werden die konfigurierten Stoppeinstellungen verwendet.

id

Paging-ID, 0 - 31

volume

optional, 5 - 100. Wenn nicht mitgeliefert, wird das konfigurierte Paging-Volumen verwendet.

autostoptime

optional, 5 - 100 Sekunden. Wenn nicht mitgeliefert, werden die konfigurierten Stoppeinstellungen verwendet.

Beispiel *

/xml/paging/start.xml?id=0&volume=10&autostoptime=10

Ein Paging stoppt automatisch nach der festgelegten Zeit, aber Sie können ihn früher stoppen durch:

/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 und zeigen Sie das Textfeld in Ihrer Visualisierung an. + _20 bedeutet ein Zeichen mit 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. + Vor allem die Menüs von Musikdiensten 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 Nummer von 1 bis 99, um Ihre externe Visualisierungsinstanz zu identifizieren.
innerhalb dieses API-Dokuments, visuUd = 90 wird für Testanfragen verwendet.

apiLevel

sollte immer 2 sein. Dies erzeugt taste xml objects unter keypad/basic.

now

geben Sie sofort den neuen Zonenstatus zurück und schließen Sie die Verbindung.
ohne & now würde der Anruf bis zu einem Timeout blockieren, oder bis eine Änderung in den Zonestatusinformationen.

reload=1

Wenn zwei Visualisierungen auf den gleichen Server mit der gleichen visuuid zugreifen, wird möglicherweise ein Fehler " zweimal verwendet" angezeigt. In diesem Fall sollte das neueste -Bild beim ersten Aufruf "& reload = 1" hinzufügen, um klar zu sagen, dass es sich um die neueste Visualisierung handelt.

Über Steuereinheiten (Visualisierungen) *

Wenn Sie Anfragen mit 'visuid = 90' senden, wird ein Control Unit Objekt mit der ID 90 im Server angelegt.

Sie können die Liste der aktuellen Control Units in der Webkonfiguration unter Control Units abrufen.

Nach dem ersten Zugriff wird die Einheit als "Nicht konfiguriert" aufgeführt. Sobald Sie die Konfiguration ändern, z. Durch Einstellung von "Aus bei kurzer Druckerleistung" wird es als Configured bezeichnet, und spätere Bereinigungen der Liste der Control Units werden diese nicht löschen.

Wenn für dieses Gerät keine Anfragen 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ückkehrt, sondern blockiert, 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 Control Unit mit der ID 90 wird erstellt und mit der ersten Zone verknüpft. + Der Anruf kehrt sofort mit vollen Statusdaten der Zone zurück.

_auf alle weiteren Anrufe: _

Die vorhandene Steuereinheit 90 wird wiederverwendet. Der Anruf kann blockieren, bis:

ein Timeout 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 (viele) Statusdaten auf dem Server zwischen zwei getChanges-Aufrufen geändert haben, blockiert der Aufruf möglicherweise überhaupt nicht, sondern gibt den neuen Status sofort zurück.

Wenn Sie eine Zeitüberschreitung erhalten, führen Sie die getChanges sofort erneut aus. Das bedeutet, dass Sie getChanges endlos in einer Schleife ausführen können, z. B. in einem separaten E/A-Thread. Da eine Anforderung nur bei Änderungen zurückgegeben wird, führt dies zu keinen Ladeproblemen mit dem Server.

Wenn der Anruf nicht sofort oder nach einigen Sekunden (sobald sich etwas geändert hat) zurückgegeben wird, 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

Dazu müssen Sie in Ihrer Programmiersprache prüfen können, ob Antwortdaten für einen Socket vorhanden sind (über den Aufruf 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 Blockierungen auf 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.
   +--+

trivum API-Dokumentation

trivum HTTP-Schnittstelle

1. Befehle

1.1. ZoneCommand

zoneId

Befehlsnummer

1.2. Stellen Sie die Zonenquelle ein

shortSourceName

1.3. Stellen Sie Zonenattribut ein

1.4. trivum Favoriten

1.5. TuneIn Favoriten

1.6. FM-Voreinstellungen

1.7. NAS-Status und Kontrolle

1.8. Gruppenmanagement

Ändern Sie das Volumen innerhalb einer Gruppe

1.9. Paging

2. Interaktive Musikauswahl

3. Holen Sie sich den Zonenstatus

3.1. Synchrone

3.2. Asynchrone