interfaccia HTTP trivum

25-lug-2023

L’interfaccia HTTP trivum accetta le richieste che possono essere testate facilmente da un browser Web e restituisce le risposte in formato XML.

1. comandi

1.1. ZoneCommand

Permette di fare cose basilari come spegnere una zona o cambiare volume.

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

L’ID di una zona. Per l’elenco dei possibili ID, esamina la configurazione web in
Automation /trivum API o vedi sotto l’esempio getAll.xml.

Alcuni attuatori potrebbero non indirizzare la prima zona di @0 ma di @1 a causa di file di configurazione interni non utilizzati. Per risolvere questo problema, puoi reimpostare l’intera configurazione tramite:
Sistema/Backup/Ripristino/Ripristina tutti i dati di configurazione

Invece di @0 si può dare il nome della zona. Se contiene caratteri speciali riscrivili usando % :

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

commandNumber

Questo è un comando numerico con questi possibili valori:

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

Esempi

chiama function

/xml/zone/getAll.xml

Elenca tutti i possibili ID di zona.

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

Ottenere lo stato di una singola zona. I parametri opzionali sono: &addSourceBasicData &addSourceStatusData

/xml/zone/getSelection.xml?grouped

Elenca le zone con informazioni complete sul gruppo.

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

Imposta la prima zona sullo streaming predefinito.

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

Disattiva la prima zona.

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

Disattiva tutte le zone.

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

Disattiva audio

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

Disattiva audio

1.2. Imposta la sorgente della zona

Seleziona una zona sorgente per nome breve

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

shortSourceName
testo azione note

a

a1
a3

primo ingresso analogico
primo ingresso analogico
terzo ingresso analogico

A seconda del modello del dispositivo, da 0 a 8 ingressi analogici sono supportati.

p

p5

prima preimpostazione sintonizzatore FM
quinta preimpostazione sintonizzatore FM

Richiede che per la zona sia configurato un sintonizzatore FM predefinito.

f {22102 31}

f2

primo trivum preferito
secondo trivum preferito

y

y2

primo trivum playlist
secondo trivum playlist

i
9 9020 i2

prima sintonizzazione preimpostata
seconda sintonizzazione preimpostata

s

sorgente di flusso predefinita della zona

riproduzione della selezione recente

t

sintonizzatore FM predefinito della zona

riproduzione della frequenza recente

Esempi

Chiamata API

commento

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

passa al primo ingresso analogico

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

passa al sintonizzatore FM predefinito della zona e riproduci la frequenza recente

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

passa al sintonizzatore FM predefinito della zona e alla stazione di riproduzione preimpostata 3

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

passa allo streaming predefinito della zona e riproduci trivum preferiti 2

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

passa allo streaming predefinito della zona e riproduci TuneIn webradio preset 5

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

Solo C4: utilizzare una sorgente dallo slot per schede n. (n >= 0)

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

Disattiva tutte le zone.

1.3. Imposta l’attributo della zona

Cambia i valori di base in una zona, come volume, silenziamento, bilanciamento o basso.

Chiamata API

commento

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

imposta volume (0 …​ 100)

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

come /xml/zone/runCommand.xml per eseguire un comando numerico, in questo caso ZONECMD_POWER_OFF (1)

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

imposta il bilanciamento, da -15 (tutto a sinistra) a 15 (tutto a destra)

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

impostare la riduzione o il miglioramento dei bassi, da -15 a 15

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

impostare la riduzione o il miglioramento degli acuti, da -15 a 15

1.4. Preferiti trivum

Per creare preferiti trivum:

  • riprodurre alcuni contenuti musicali, come un album NAS

  • quindi seleziona …​ nella parte superiore destra

  • quindi selezionare "Aggiungi a trivum preferiti".

Ottieni l’elenco dei preferiti di trivum:

/api/v1/trivum/favorite.xml

Gioca a trivum preferito:

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

Puoi anche aggiungere opzioni:

opzione

commento

&sequence=random-sequential

seleziona una traccia iniziale casuale

&sequenza=casuale-casuale

gioca in ordine casuale permanente

1.5. trivum playlist

Ottieni l’elenco delle playlist trivum:

/api/v1/trivum/playlist.xml

Riproduci una playlist trivum:

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

Puoi anche aggiungere opzioni:

opzione

commento

&sequence=random-sequential

iniziare da una traccia casuale

&sequenza=casuale-casuale

per riprodurre solo tracce casuali

1.6. TuneIn Favorites

Questi possono anche essere creati da …​ in alto a destra durante la riproduzione di una stazione TuneIn.

Ottieni l’elenco dei preferiti di TuneIn:

/api/v1/tunein/favorite.xml

Riproduci un preferito di TuneIn:

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

1.7. Preset FM

Elenca i preset FM:

/xml/system/getTunerStationList.xml

Su C4 questo mostra l’elenco a livello di sistema di preimpostazioni FM, ma nessuna preimpostazione locale memorizzata per scheda di sintonizzazione FM.

1.8. Stato e controllo NAS

Chiamata API

commento

/xml/system/getMusicCenterStatus.xml

ottenere lo stato della libreria NAS

/xml/system/scanMusicCenterShares.xml

eseguire nuovamente la scansione completa del NAS

1.9. Gestione del gruppo

I gruppi possono essere creati, modificati o rimossi da una sola chiamata:

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

parametri:

nome

commento

zVisu

indice della zona corrente del client di visualizzazione

zMaestro

indice del master del gruppo la cui musica deve essere utilizzata (se entrambe le zone stanno attualmente riproducendo sorgenti diverse)

+/-

caratteri che indicano graficamente quali zone devono far parte di un gruppo. ad esempio, con un sistema a 4 zone, digitare 4 caratteri o meno (viene riempito automaticamente con -).

Esempio: la seconda zona si unisce alla riproduzione della prima zona

  • la prima zona sta riproducendo uno streaming, la seconda zona sta riproducendo il sintonizzatore FM, tutte le altre zone sono disattivate.

  • la seconda zona dovrebbe essere aggiunta a un gruppo con la prima zona,
    e dovrebbe rilevare la musica dalla prima zona (lo stream).

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

Risultato: la seconda zona inizia a riprodurre lo stesso flusso della prima zona.

Esempio: la prima zona si unisce alla riproduzione della seconda zona

  • la prima zona sta riproducendo uno streaming, la seconda zona sta riproducendo il sintonizzatore FM, tutte le altre zone sono disattivate.

  • la prima zona dovrebbe essere aggiunta a un gruppo con la seconda zona e dovrebbe rilevare la musica dalla seconda zona (l’accordatore).

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

Risultato: la prima zona inizia a riprodurre lo stesso sintonizzatore FM della seconda zona.

Ciò significa che se entrambe le zone riproducono sorgenti diverse,
"oldgroup" decide quale musica riprodurre dopo che il gruppo si è unito.

Esempio: la seconda zona dovrebbe lasciare il gruppo

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

Rilevante è il passaggio da + a - nell’elenco dei membri.

Cambia il livello del volume all’interno di un gruppo

All’interno di un gruppo, le zone normalmente non utilizzano livelli di volume isolati,
ma una modifica del volume influisce su tutti i membri del gruppo.
Questa interdipendenza è gestita dalla chiamata:

/xml/zona/setVolume.xml

Per impostazione predefinita, questa chiamata non imposterà semplicemente un livello di volume assoluto, ma passerà un po' nella direzione di un determinato volume di destinazione. È meglio utilizzarlo con un pulsante + o - nella visualizzazione.

Chiamata API

commento

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

Aumenta il volume del gruppo verso il basso per l’intero gruppo. id è qualsiasi ID zona del gruppo. Il volume di tutti i membri della zona verrà ridotto di alcuni passaggi.

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

Aumenta il volume del gruppo per l’intero gruppo. Il volume di tutti i membri della zona verrà aumentato di alcuni passaggi.

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

Aumenta gradualmente il volume di una singola zona, senza influire sugli altri membri del gruppo.

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

Diminuisci il volume di una singola zona gradualmente, senza influire sugli altri membri del gruppo.

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

Arresta immediatamente l’aumento del volume.

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

Imposta il volume assoluto per una singola zona, isolata dagli altri membri del gruppo. (Usare con cautela.)

Per ottenere le nuove informazioni sul livello del volume all’interno di un gruppo, effettuare una chiamata getChanges ed esaminare l’elenco dello stato del volume.

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

Esempio di output, se raggruppato, in zona/stato:

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

Per una spiegazione completa di getChanges vedere Ottieni lo stato della zona.

1.10. paging

I cercapersone devono essere configurati nella configurazione web. Quindi possono essere utilizzate le seguenti chiamate:

Avvia il paging

/xml/paginazione/start.xml

parametri

nome descrizione

id

ID cercapersone, 0 - 31

volume

opzionale, 5 - 100. se non fornito viene utilizzato il livello del volume di paging configurato.

autostoptime

opzionale, 5 - 100 secondi. se non fornito vengono utilizzate le impostazioni di arresto configurate.

  • * Esempio

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

Un cercapersone si interrompe automaticamente dopo il tempo definito, ma è possibile interromperlo prima chiamando:

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

2. Selezione musicale interattiva

Inizia con:

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

Questo produce record come:

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

quindi, per record:

  • decodificare e visualizzare il campo di testo nella visualizzazione.
    _20 indica un carattere con codice Ascii 0x20 (uno spazio).

  • se toccato, richiama l’url azione e visualizza il livello successivo del menu.

Non fare affidamento sulla disponibilità permanente di specifici livelli di menu.
Soprattutto i menu forniti dai servizi musicali possono cambiare nel tempo.

3. Ottieni lo stato della zona

3.1. Sincrono

Interroga lo stato di una zona con una breve chiamata API:

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

parametri

nome

funzione

visuid

un numero compreso tra 1 e 99 per identificare l’istanza di visualizzazione esterna.
all’interno di questo documento API, visuid=90 viene utilizzato per le richieste di test.

apiLevel

dovrebbe sempre essere 2. questo produrrà button xml objects sotto keypad/basic.

now

dice al server di restituire immediatamente lo stato della nuova zona e di chiudere la connessione.
senza &ora la chiamata si bloccherebbe fino a un timeout o fino a quando non cambia le informazioni sullo stato della zona.

reload=1

se due visualizzazioni accedono allo stesso server con lo stesso visuid , potrebbe apparire un errore "usato due volte". in questo caso la visualizzazione più recente dovrebbe aggiungere &reload=1 alla prima chiamata, per indicare chiaramente a che si tratta della visualizzazione più recente.

Informazioni sulle unità di controllo (visualizzazioni)

Se invii richieste con visuid=90 viene creato un oggetto Control Unit con ID 90 nel server.

È possibile ottenere l’elenco delle unità di controllo correnti nella configurazione Web, in Unità di controllo.

Dopo il primo accesso, l’unità viene elencata come "Non configurata". Non appena si modifica la sua configurazione, ad esempio impostando l’opzione "Off premendo brevemente su power", viene chiamato Configured e le successive pulizie dell’elenco delle unità di controllo non lo elimineranno.

Se non ci sono richieste per questa centralina, dopo qualche tempo verrà elencata sotto "centrali attualmente inattive".

3.2. Asincrono

Ciò significa che una chiamata HTTP non verrà restituita immediatamente, ma si bloccherà fino a quando qualcosa non cambierà.

Esempio:

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

Si noti che manca & now. Il seguente accadrà:

alla prima chiamata API:

Viene creata una Centrale con ID 90, collegata alla prima zona.
La chiamata API viene restituita immediatamente, con i dati completi sullo stato della zona.

su tutte le ulteriori chiamate API:

L’unità di controllo 90 esistente viene riutilizzata. La chiamata API potrebbe bloccarsi fino a quando:

  • viene raggiunto un timeout (10 secondi circa). in questo caso ricevi una risposta del tipo:
    <rows><system><timeout>1</timeout>

  • o fino a quando qualcosa è cambiato, ad esempio, il volume nella zona.

se (molti) dati di stato sono cambiati sul server tra due chiamate getChanges, la chiamata potrebbe non bloccarsi affatto, ma restituire immediatamente il nuovo stato.

quando ricevi un timeout, riesegui immediatamente getChanges. questo significa che puoi eseguire getChanges all’infinito, in un ciclo, ad esempio in un thread I/O separato. Poiché una richiesta ritorna solo in caso di modifiche, ciò non causerà problemi di caricamento con il server.

quando non ricevi un timeout, cioè la chiamata ritorna immediatamente o dopo pochi secondi (non appena qualcosa è cambiato), quindi elabora i dati di stato, quindi esegui nuovamente la richiesta getChanges.

3.3. Appendice: esempio schematico per un’applicazione client Visu

3.3.1. Applicazione a filo singolo

Ciò richiede che tu possa testare, nel tuo linguaggio di programmazione, se esistono dati di risposta per un socket (tramite la chiamata select()).

Filettatura principale

  • start: invia /xml/zone/getChanges.xml?visuid=90&now

  • loop begin: aggiorna la GUI.

    • elaborare gli eventi di input dall’utente.

    • invia comandi sincroni come:
      /xml/zone/runCommand.xml?…​
      ricevi risposta, controlla rc ED elabora i dati di stato xml
      (come con le risposte getChanges)

    • controlla se esistono dati di risposta per la chiamata getChanges in corso
      (nel codice C: chiamata select() su socket)
      SE i dati esistono dal server trivum:

      • Cerca <userdata name="rc">0</userdata>.
        Se NON presente
        _ elaborare l’errore e attendere qualche secondo.
        Else if NOT a timeout
        _ process xml reply (dati di stato)
        Endif
        chiamata asincrona (basta inviare)
        /xml/zone/getChanges.xml&visuid=90&onlyChanges
        Endif

    • se non arrivano dati dal server entro 1 minuto

      • chiamata asincrona (basta inviare)
        /xml/zone/getChanges.xml&visuid=90&onlyChanges
        endif

    • riesegui il ciclo

3.3.2. Esempio di applicazione a due thread

Può essere utilizzato se si preferisce eseguire il blocco dei ricevimenti sui socket in un thread I/O separato.

Filettatura principale

  • aggiornare la GUI.

  • elaborare gli eventi di input dall’utente.

  • invia comandi sincroni come:
    /xml/zone/runCommand.xml?…​
    ricevi risposta, controlla rc ED elabora i dati di stato xml
    (come con le risposte getChanges)

  • ricevere dati di stato ed errori da Status Thread.

  • rieseguire questo ciclo.

Discussione di stato

  • IF sul primo ciclo:

    • invia /xml/zone/getChanges.xml?visuid=90&now
      ELSE

    • invia /xml/zone/getChanges.xml?visuid=90&onlyChanges

  • ricevere risposta (questo è bloccato fino a 10 secondi)

  • Cerca <userdata name="rc">0</userdata>.
    Se NON è presente allora c’è un errore.
    Assicurati di non rieseguire semplicemente il ciclo in caso di errori,
    ma almeno di attendere qualche secondo e comunicarlo al thread principale.

  • Cerca <rows><system><timeout>1</timeout>.
    SE presente

    • rieseguire immediatamente il ciclo.
      ALTRO

    • elaborare i dati sullo stato della risposta,
      e copiare i nuovi dati sullo stato nel thread principale.

  • rieseguire questo ciclo.