trivum HTTP-interface

25-jul-2023

De trivum HTTP-interface accepteert verzoeken die eenvoudig kunnen worden getest door een webbrowser en retourneert antwoorden in XML-indeling.

1. commando’s

1.1. ZoneCommand

Maakt het mogelijk om elementaire zaken uit te voeren, zoals het uitschakelen van een zone of het wijzigen van het volume.

 /xml/zone/runCommand.xml?zone=@zoneId&command=commandNumber

zoneId

De ID van een zone. Kijk voor de lijst met mogelijke ID’s in de webconfiguratie onder
Automation /trivum API of zie hieronder het getAll.xml-voorbeeld.

Sommige actuatoren adresseren de eerste zone mogelijk niet met @0 maar met @1 vanwege interne, ongebruikte configuratiebestanden. Om dit op te lossen, kunt u de hele configuratie resetten door:
Systeem/Back-up/Herstellen/Alle configuratiegegevens resetten

In plaats van @0 kan de zonenaam worden opgegeven. Als het speciale tekens bevat, herschrijf ze dan met %:

/xml/zone/runCommand.xml?zone=living%20room&command=…

commandNumber

Dit is een numeriek commando met deze mogelijke waarden:

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

Voorbeelden * *

bel function

bel	function
`/xml/zone/getAll.xml`	Maak een lijst van alle mogelijke zone-ID’s.
`/xml/zone/get.xml?zone=@0`	Ontvang de status van een enkele zone. Optionele parameters zijn: &addSourceBasicData &addSourceStatusData
`/xml/zone/getSelection.xml?grouped`	Maak een lijst van zones met volledige groepsinformatie.
`/xml/zone/runCommand.xml?zone=@0&command=50`	Schakel de eerste zone naar standaard streaming.
`/xml/zone/runCommand.xml?zone=@0&command=1`	Schakel de eerste zone uit.
`/xml/zone/runCommand.xml?zone=@0&command=15`	Schakel alle zones uit.
`/xml/zone/runCommand.xml?zone=@0&command=680`	Dempen on
`/xml/zone/runCommand.xml?zone=@0&command=681`	Dempen uit

/xml/zone/getAll.xml

Maak een lijst van alle mogelijke zone-ID’s.

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

Ontvang de status van een enkele zone. Optionele parameters zijn: &addSourceBasicData &addSourceStatusData

/xml/zone/getSelection.xml?grouped

Maak een lijst van zones met volledige groepsinformatie.

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

Schakel de eerste zone naar standaard streaming.

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

Schakel de eerste zone uit.

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

Schakel alle zones uit.

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

Dempen on

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

Dempen uit

1.2. Stel zonebron in

Selecteer een zonebron op korte naam

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

shortSourceName

tekst actie remark

tekst	actie	remark
`a` `a1` `a3`	eerste analoge ingang eerste analoge ingang derde analoge ingang	Afhankelijk van het apparaatmodel, 0 tot 8 analoog ingangen worden ondersteund.
`p` `p5`	eerste voorinstelling FM-tuner vijfde voorinstelling FM-tuner	Vereist dat er een standaard FM-tuner is geconfigureerd voor de zone.
`f` {221023 1} `f2`	eerste trivum favoriet tweede trivum favoriet
`y` `y2`	eerste trivum afspeellijst tweede trivum afspeellijst
`i` 9 9020 `i2`	eerste tunein preset tweede tunein preset
`s`	standaard streambron van zone	speelt recente selectie
`t`	standaard FM-tuner van zone	speelt recente frequentie

a

a1
a3

eerste analoge ingang
eerste analoge ingang
derde analoge ingang

Afhankelijk van het apparaatmodel, 0 tot 8 analoog ingangen worden ondersteund.

p

p5

eerste voorinstelling FM-tuner
vijfde voorinstelling FM-tuner

Vereist dat er een standaard FM-tuner is geconfigureerd voor de zone.

f {221023 1}

f2

eerste trivum favoriet
tweede trivum favoriet

y

y2

eerste trivum afspeellijst
tweede trivum afspeellijst

i
9 9020 i2

eerste tunein preset
tweede tunein preset

s

standaard streambron van zone

speelt recente selectie

t

standaard FM-tuner van zone

speelt recente frequentie

Voorbeelden * *

API-oproep

opmerking

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

overschakelen naar eerste analoge ingang

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

schakel over naar de standaard FM-tuner van de zone en speel recente frequentie

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

overschakelen naar standaard FM-tuner van zone en playstation-preset 3

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

schakel over naar standaard streaming van zone en speel trivum favoriet 2

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

schakel over naar standaard streaming van zone en speel TuneIn webradio preset 5

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

Alleen C4: gebruik een bron via kaartsleuf n. (n >= 0)

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

Schakel alle zones uit.

1.3. Zone-kenmerk instellen

Verander basiswaarden in een zone, zoals volume, dempen, balans of bas.

API-oproep

opmerking

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

volume instellen (0 … 100)

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

hetzelfde als /xml/zone/runCommand.xml om een numerieke opdracht uit te voeren, in dit geval ZONECMD_POWER_OFF (1)

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

balans instellen, van -15 (volledig links) tot 15 (volledig rechts)

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

basreductie of -verbetering instellen, van -15 tot 15

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

stel treble-reductie of -verbetering in, van -15 tot 15

1.4. trivum favorieten

Om trivum-favorieten te maken:

muziek afspelen, zoals een NAS-album
selecteer vervolgens … rechts bovenaan
selecteer vervolgens "Toevoegen aan trivum favorieten".

Download de lijst met trivum-favorieten:

/api/v1/trivum/favoriet.xml

Speel een trivum-favoriet:

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

Je kunt ook opties toevoegen:

optie

opmerking

&sequence=random-sequential

selecteer een willekeurige starttrack

&volgorde=willekeurig-willekeurig

speel in permanente willekeurige volgorde

1.5. trivum-afspeellijsten

Download de lijst met trivum-afspeellijsten:

/api/v1/trivum/playlist.xml

Speel een trivum-afspeellijst:

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

Je kunt ook opties toevoegen:

optie

opmerking

&sequence=random-sequential

om op een willekeurige track te beginnen

&volgorde=willekeurig-willekeurig

om alleen willekeurige nummers af te spelen

1.6. TuneIn favorieten

Deze kunnen ook worden aangemaakt door … rechtsboven terwijl een TuneIn-station aan het spelen is.

Download de lijst met TuneIn-favorieten:

/api/v1/tunein/favoriet.xml

Speel een TuneIn-favoriet:

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

1.7. FM-voorkeuzezenders

Lijst FM-presets:

/xml/system/getTunerStationList.xml

Op C4 toont dit de systeembrede lijst met FM-presets, maar er zijn geen lokale presets opgeslagen per FM-tunerkaart.

1.8. NAS-status en besturing

API-oproep

opmerking

/xml/system/getMusicCenterStatus.xml

krijg NAS-bibliotheek status

/xml/system/scanMusicCenterShares.xml

voer de volledige NAS-scan opnieuw uit

1.9. Groep management

Groepen kunnen met één oproep worden gemaakt, gewijzigd of verwijderd:

/xml/zone/createGroup.xml?zone=zVisu&oldgroup=zMaster&members=++----------

parameters:

naam

opmerking

zVisu

index van de huidige zone van de visualisatie client

zMaster

index van de groepsleider wiens muziek moet worden gebruikt (als beide zones momenteel verschillende bronnen afspelen)

+/-

karakters die grafisch vertellen welke zones moeten deelnemen in een groep. typ bijvoorbeeld bij een systeem met 4 zones 4 tekens of minder (wordt automatisch opgevuld met -).

Voorbeeld: tweede zone sluit zich aan bij afspelen van eerste zone

eerste zone speelt een stream af, tweede zone speelt FM-tuner, alle andere zones zijn uit.
de tweede zone moet worden toegevoegd aan een groep met de eerste zone,
en deze moet de muziek van de eerste zone (de stream) overnemen.

/xml/zone/createGroup.xml?zone=1&oldgroup=0&members=++--

Resultaat: de tweede zone begint met het afspelen van dezelfde stream als de eerste zone.

Voorbeeld: eerste zone voegt zich bij het afspelen van tweede zone

eerste zone speelt een stream af, tweede zone speelt FM-tuner, alle andere zones zijn uit.
eerste zone moet worden toegevoegd aan een groep met tweede zone, en het moet muziek overnemen van tweede zone (de tuner).

/xml/zone/createGroup.xml?zone=0&oldgroup=1&members=++--

Resultaat: de eerste zone begint dezelfde FM-tuner af te spelen als de tweede zone.

Dit betekent dat als beide zones verschillende bronnen afspelen,
"oldgroup" bepaalt welke muziek wordt afgespeeld nadat de groep is toegetreden.

Voorbeeld: tweede zone verlaat de groep

/xml/zone/createGroup.xml?zone=0&oldgroup=0&members=+---

Relevant hierbij is de verandering van + naar - in de ledenlijst.

Wijzig het volumeniveau binnen een groep

Binnen een groep gebruiken zones normaal gesproken geen geïsoleerde volumeniveaus,
maar een verandering in volume heeft invloed op alle groepsleden.
Deze onderlinge afhankelijkheid wordt afgehandeld door de aanroep:

/xml/zone/setVolume.xml

Standaard zal deze oproep niet simpelweg een absoluut volumeniveau instellen, maar stapt het een beetje in de richting van een bepaald doelvolume. Dit kunt u het beste gebruiken met een + of - knop in uw visualisatie.

API-oproep

opmerking

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

Verlaag het groepsvolume voor de hele groep. id is elke zone-ID van de groep. Het volume van alle zoneleden wordt een paar stappen verlaagd.

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

Verhoog het groepsvolume voor de hele groep. Het volume van alle zoneleden wordt een paar stappen verhoogd.

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

Verhoog het volume van een enkele zone stapsgewijs, heeft geen invloed op andere groepsleden.

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

Verlaag het volume van een enkele zone stapsgewijs, heeft geen invloed op andere groepsleden.

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

Stop onmiddellijk met volumestappen.

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

Stel absoluut volume in voor een enkele zone, geïsoleerd van andere groepsleden. (Voorzichtig gebruiken.)

Om de nieuwe volumeniveau-informatie binnen een groep te krijgen, belt u getChanges en bekijkt u de volumestatuslijst.

/xml/zone/getChanges.xml?zone=@0&visuid=90&apiLevel=2&nu

Voorbeelduitvoer, indien gegroepeerd, onder 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>

Zie Krijg zonestatus voor een volledige uitleg van getChanges.

1.10. paging

Paging moet worden geconfigureerd in de webconfiguratie. Dan kunnen de volgende oproepen worden gebruikt:

Start met paging

/xml/paging/start.xml

parameters

naam omschrijving

naam	omschrijving
`id`	paging-ID, 0 - 31
`volume`	optioneel, 5 - 100. indien niet meegeleverd, wordt het geconfigureerde oproepvolume gebruikt.
`autostoptime`	optioneel, 5 - 100 seconden. indien niet geleverd worden de geconfigureerde stopinstellingen gebruikt.

id

paging-ID, 0 - 31

volume

optioneel, 5 - 100. indien niet meegeleverd, wordt het geconfigureerde oproepvolume gebruikt.

autostoptime

optioneel, 5 - 100 seconden. indien niet geleverd worden de geconfigureerde stopinstellingen gebruikt.

Voorbeeld

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

Een paging stopt automatisch na de ingestelde tijd, maar u kunt deze eerder stoppen door te bellen naar:

/xml/paging/stop.xml?id=0

2. Interactieve muziekselectie

Begint met:

/xml/system/getWebTouchMenu.xml?which=music&zone=@0&visuid=90

Dit levert records op zoals:

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

dan, per record:

decoderen en weergeven van het tekstveld in uw visualisatie.
_20 betekent een teken met Ascii-code 0x20 (een spatie).
als je aanraakt, bel dan de actie-url en toon het volgende menuniveau.

Vertrouw niet op de permanente beschikbaarheid van specifieke menuniveaus.
Vooral de menu’s van muziekservices kunnen in de loop van de tijd veranderen.

3. Krijg zonestatus

3.1. Synchroon

Poll de status van een zone met één korte API-aanroep:

/xml/zone/getChanges.xml?zone=@0&visuid=90&apiLevel=2&nu

parameters

naam

functie

visuid

een nummer van 1 tot 99 om uw externe visualisatie-exemplaar te identificeren.
binnen dit API-document wordt visuid=90 gebruikt voor testverzoeken.

apiLevel

moet altijd 2 zijn. dit levert button xml objects op onder keypad/basic.

now

vertelt de server om de nieuwe zonestatus onmiddellijk te retourneren en de verbinding te verbreken.
zonder '&nu' zou het gesprek worden geblokkeerd tot een time-out, of tot een wijziging in de zonestatusinformatie.

reload=1

als twee visualisaties toegang hebben tot dezelfde server met dezelfde -visuid, kan een fout "tweemaal gebruikt" verschijnen. in dit geval zou de most recente visualisatie &reload=1 moeten toevoegen bij de eerste oproep, om duidelijk te maken dat het de meest recente visualisatie is.

Over bedieningseenheden (visualisaties)

Als u verzoeken verzendt met visuid=90, wordt een Control Unit-object met ID 90 op de server gemaakt.

U kunt de lijst met huidige regeleenheden vinden in de webconfiguratie, onder Control Units.

Na de eerste toegang wordt het apparaat weergegeven als "Niet geconfigureerd". Zodra u de configuratie wijzigt, bijvoorbeeld door de optie "Uit te zetten door kort op power" te drukken, wordt deze Configured genoemd, en latere opschoningen van de lijst met regeleenheden zullen deze niet verwijderen.

Als er geen verzoeken zijn voor deze unit, zal deze na enige tijd worden vermeld onder "momenteel inactieve controle-units".

3.2. Asynchroon

Dit betekent dat een HTTP-oproep niet onmiddellijk wordt geretourneerd, maar wordt geblokkeerd totdat er iets verandert.

Voorbeeld:

/xml/zone/getChanges.xml?zone=@0&visuid=90&apiLevel=2

Merk op dat & now ontbreekt. Het volgende zal gebeuren:

bij de eerste API-aanroep:

Er wordt een controle-eenheid met ID 90 gemaakt en gekoppeld aan de eerste zone.
De API-aanroep keert onmiddellijk terug, met volledige statusgegevens van de zone.

bij alle verdere API-aanroepen:

De bestaande Control Unit 90 wordt hergebruikt. De API-aanroep kan blokkeren, totdat:

een time-out is bereikt (ongeveer 10 seconden). in dit geval krijg je een antwoord als:
<rows><system><timeout>1</timeout>
of totdat er iets is veranderd, bijvoorbeeld het volume in de zone.

als (veel) statusgegevens op de server zijn gewijzigd tussen twee getChanges-oproepen, wordt de oproep mogelijk helemaal niet geblokkeerd, maar wordt de nieuwe status onmiddellijk geretourneerd.

wanneer u een time-out ontvangt, voert u de getChanges onmiddellijk opnieuw uit. dit betekent dat je getChanges eindeloos kunt uitvoeren, in een lus, bijvoorbeeld in een aparte I/O-thread. Omdat een verzoek alleen terugkeert bij wijzigingen, veroorzaakt dit geen laadproblemen met de server.

wanneer u geen time-out ontvangt, d.w.z. de oproep komt onmiddellijk of na enkele seconden terug (zodra er iets is veranderd), verwerk dan de statusgegevens en voer vervolgens het getChanges-verzoek opnieuw uit.

3.3. Bijlage: schematisch voorbeeld voor een Visu Client Application

3.3.1. Applicatie met enkele draad

Dit vereist dat u in uw programmeertaal kunt testen of er antwoordgegevens voor een socket bestaan (via select() call).

Hoofddraad

start: verzend /xml/zone/getChanges.xml?visuid=90&now
loop begin: werk de GUI bij.
- invoergebeurtenissen van de gebruiker verwerken.
- stuur synchrone commando’s zoals:
  /xml/zone/runCommand.xml?…
  antwoord ontvangen, rc controleren EN xml-statusgegevens verwerken
  (hetzelfde als met getChanges-antwoorden)
- controleer of er antwoordgegevens zijn voor lopende getChanges-aanroep
  (in C-code: select() bel op socket)
  ALS er gegevens zijn van de trivum-server:
  - Zoek naar <userdata name="rc">0</userdata>.
    Indien NIET aanwezig
    _ verwerk de fout en wacht een paar seconden.
    Else if NOT een time-out
    _ xml-antwoord verwerken (statusgegevens)
    Endif
    asynchrone oproep (gewoon verzenden)
    /xml/zone/getChanges.xml&visuid=90&onlyChanges
    Endif
- als er binnen 1 minuut geen gegevens van de server aankomen
  - asynchrone oproep (gewoon verzenden)
    /xml/zone/getChanges.xml&visuid=90&onlyChanges
    endif
- lus opnieuw uitvoeren

3.3.2. Toepassingsvoorbeeld met twee draden

Kan worden gebruikt als u de voorkeur geeft aan blokkerende ontvangsten op sockets in een afzonderlijke I/O-thread.

Hoofddraad

update de GUI.
invoergebeurtenissen van de gebruiker verwerken.
stuur synchrone commando’s zoals:
/xml/zone/runCommand.xml?…
antwoord ontvangen, rc controleren EN xml-statusgegevens verwerken
(hetzelfde als met getChanges-antwoorden)
ontvang statusgegevens en fouten van Status Thread.
herhaal deze lus.

Statusthread

IF op eerste lus:
- stuur /xml/zone/getChanges.xml?visuid=90&now
  ANDERS
- verzend /xml/zone/getChanges.xml?visuid=90&onlyChanges
antwoord ontvangen (dit wordt tot 10 seconden geblokkeerd)
Zoek naar <userdata name="rc">0</userdata>.
Als dit NIET aanwezig is, is er een fout opgetreden.
Zorg ervoor dat u de lus niet simpelweg opnieuw uitvoert bij fouten,
maar wacht in ieder geval een paar seconden en vertel het aan de hoofdthread.
Zoek naar <rows><system><timeout>1</timeout>.
ALS dit aanwezig is
- voer de lus onmiddellijk opnieuw uit.
  ANDERS
- verwerk de antwoordstatusgegevens,
  en kopieer nieuwe statusgegevens naar Hoofdthread.
herhaal deze lus.

trivum API-documentatie

trivum HTTP-interface

1. commando’s

1.1. ZoneCommand

zoneId

commandNumber

1.2. Stel zonebron in

shortSourceName

1.3. Zone-kenmerk instellen

1.4. trivum favorieten

1.5. trivum-afspeellijsten

1.6. TuneIn favorieten

1.7. FM-voorkeuzezenders

1.8. NAS-status en besturing

1.9. Groep management

Wijzig het volumeniveau binnen een groep

1.10. paging

2. Interactieve muziekselectie

3. Krijg zonestatus

3.1. Synchroon

3.2. Asynchroon

3.3. Bijlage: schematisch voorbeeld voor een Visu Client Application

3.3.1. Applicatie met enkele draad

3.3.2. Toepassingsvoorbeeld met twee draden