trivum interfaz HTTP

25-jul-2023

La interfaz HTTP trivum acepta solicitudes que un navegador web puede probar fácilmente y devuelve respuestas en formato XML.

1. Comandos

1.1. ZoneCommand

Permite hacer cosas básicas como desactivar una zona o cambiar el volumen.

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

zoneId

El ID de una zona. Para ver la lista de ID posibles, busque en la configuración web en
Automation /trivum API o vea a continuación el ejemplo de getAll.xml.

Es posible que algunos actuadores no aborden la primera zona con @0 sino con @1 debido a archivos de configuración internos no utilizados. Para solucionar esto, puede restablecer toda la configuración mediante:
Sistema/Copia de seguridad/Restaurar/Restablecer todos los datos de configuración

En lugar de @0 se puede dar el nombre de la zona. Si contiene caracteres especiales, reescríbalos usando %:

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

commandNumber

Este es un comando numérico con estos valores posibles:

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

Ejemplos

llamar function

llamar	function
`/xml/zone/getAll.xml`	Enumere todos los ID de zona posibles.
`/xml/zone/get.xml?zone=@0`	Obtener el estado de una sola zona. Los parámetros opcionales son: &addSourceBasicData &addSourceStatusData
`/xml/zone/getSelection.xml?grouped`	Lista de zonas con información completa del grupo.
`/xml/zone/runCommand.xml?zone=@0&command=50`	Cambie la primera zona a transmisión predeterminada.
`/xml/zone/runCommand.xml?zone=@0&command=1`	Apague la primera zona.
`/xml/zone/runCommand.xml?zone=@0&command=15`	Desactivar todas las zonas.
`/xml/zone/runCommand.xml?zone=@0&command=680`	Silencio en
`/xml/zone/runCommand.xml?zone=@0&command=681`	Silencio desactivado

/xml/zone/getAll.xml

Enumere todos los ID de zona posibles.

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

Obtener el estado de una sola zona. Los parámetros opcionales son: &addSourceBasicData &addSourceStatusData

/xml/zone/getSelection.xml?grouped

Lista de zonas con información completa del grupo.

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

Cambie la primera zona a transmisión predeterminada.

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

Apague la primera zona.

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

Desactivar todas las zonas.

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

Silencio en

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

Silencio desactivado

1.2. Establecer fuente de zona

Seleccione una fuente de zona por nombre corto

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

shortSourceName

texto acción remark

texto	acción	remark
`a` `a1` `a3`	primera entrada analógica primera entrada analógica tercera entrada analógica	Dependiendo del modelo de dispositivo, de 0 a 8 analógicas las entradas son compatibles. 231} `f2`
primero trivum favorito segundo trivum favorito		`y` `y2`
primera trivum lista de reproducción segunda trivum lista de reproducción		`i` `i2`
primer ajuste predeterminado segundo ajuste predeterminado		`s`
fuente de transmisión predeterminada de la zona	reproduciendo selección reciente	`t`
sintonizador de FM por defecto de la zona	reproduciendo frecuencia reciente	`l`

a

a1
a3

primera entrada analógica
primera entrada analógica
tercera entrada analógica

Dependiendo del modelo de dispositivo, de 0 a 8 analógicas las entradas son compatibles. 231}

f2

primero trivum favorito
segundo trivum favorito

y

y2

primera trivum lista de reproducción
segunda trivum lista de reproducción

i

i2

primer ajuste predeterminado
segundo ajuste predeterminado

s

fuente de transmisión predeterminada de la zona

reproduciendo selección reciente

t

sintonizador de FM por defecto de la zona

reproduciendo frecuencia reciente

l

Ejemplos

Llamada a la API

comentario

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

cambiar a la primera entrada analógica

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

cambie al sintonizador de FM predeterminado de la zona y reproduzca la frecuencia reciente

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

cambia al sintonizador de FM predeterminado de la zona y la presintonía de la estación de reproducción 3

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

cambie a la transmisión predeterminada de la zona y reproduzca trivum favorito 2

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

cambie a la transmisión predeterminada de la zona y reproduzca la radio web TuneIn preestablecida 5

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

Solo C4: use una fuente por ranura de tarjeta n. (n >= 0)

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

Apagar todas las zonas.

1.3. Establecer atributo de zona

Cambia los valores básicos en una zona, como volumen, silencio, balance o bajo.

Llamada a la API

comentario

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

establecer volumen (0 … 100)

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

igual que /xml/zone/runCommand.xml para ejecutar un comando numérico, en este caso ZONECMD_POWER_OFF (1)

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

establezca el saldo, de -15 (totalmente a la izquierda) a 15 (totalmente a la derecha)

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

establecer reducción o mejora de graves, de -15 a 15

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

establecer reducción o mejora de agudos, de -15 a 15

1.4. Trivum Favoritos

Para crear favoritos trivum:

reproducir algún contenido musical, como un álbum NAS
luego selecciona … en la parte superior derecha
luego seleccione "Agregar a trivum favoritos".

Obtener la lista de trivum favoritos:

/api/v1/trivum/favorito.xml

Juega un trivum favorito:

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

También puede agregar opciones:

opción

comentario

&sequence=random-secuencial

seleccione una pista de inicio aleatoria

&secuencia=aleatorio-aleatorio

jugar en orden aleatorio permanente

1.5. listas de reproducción trivum

Obtén la lista de trivum listas de reproducción:

/api/v1/trivum/lista de reproducción.xml

Reproduce una lista de reproducción trivum:

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

También puede agregar opciones:

opción

comentario

&sequence=random-secuencial

para comenzar en una pista aleatoria

&secuencia=aleatorio-aleatorio

para reproducir solo pistas aleatorias

1.6. TuneIn Favoritos

Estos también se pueden crear con … en la parte superior derecha mientras se reproduce una estación TuneIn.

Obtenga la lista de favoritos de TuneIn:

/api/v1/tunein/favorito.xml

Juega un favorito de TuneIn:

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

1.7. Presets de FM

Lista de preajustes de FM:

/xml/system/getTunerStationList.xml

En C4, esto muestra la lista de presintonías de FM de todo el sistema, pero no hay presintonías locales almacenadas por tarjeta sintonizadora de FM.

1.8. Estado y control NAS

Llamada a la API

comentario

/xml/system/getMusicCenterStatus.xml

obtener el estado de la biblioteca NAS

/xml/system/scanMusicCenterShares.xml

vuelva a ejecutar el escaneo NAS completo

1.9. Manejo de grupo

Los grupos se pueden crear, cambiar o eliminar mediante una llamada:

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

Parámetros:

nombre

comentario

zVisu

índice de la zona actual de la visualización client

zMaestro

índice del maestro de grupo cuya música se debe usar (si ambas zonas están reproduciendo actualmente fuentes diferentes)

+/-

caracteres que indican gráficamente qué zonas deben formar parte de un grupo. por ejemplo, con un sistema de 4 zonas, escriba 4 caracteres o menos (se rellena con - automáticamente).

Ejemplo: la segunda zona se une a la reproducción de la primera zona

la primera zona está reproduciendo una transmisión, la segunda zona está reproduciendo un sintonizador de FM, todas las demás zonas están apagadas.
la segunda zona debe agregarse a un grupo con la primera zona,
y debe hacerse cargo de la música de la primera zona (la transmisión).

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

Resultado: la segunda zona comienza a reproducir la misma secuencia que la primera zona.

Ejemplo: la primera zona se une a la reproducción de la segunda zona

la primera zona está reproduciendo una transmisión, la segunda zona está reproduciendo un sintonizador de FM, todas las demás zonas están apagadas.
la primera zona debe agregarse a un grupo con la segunda zona, y debe hacerse cargo de la música de la segunda zona (el sintonizador).

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

Resultado: la primera zona comienza a reproducir el mismo sintonizador de FM como segunda zona.

Esto significa que si ambas zonas están reproduciendo fuentes diferentes,
"oldgroup" decide qué música reproducir después de que el grupo se una.

Ejemplo: la segunda zona debería abandonar el grupo

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

Aquí es relevante el cambio de + a - en la lista de miembros.

Cambiar el nivel de volumen dentro de un grupo

Dentro de un grupo, las zonas normalmente no usan niveles de volumen aislados,
pero un cambio en el volumen afecta a todos los miembros del grupo.
Esta interdependencia la maneja la llamada:

/xml/zona/setVolume.xml

De forma predeterminada, esta llamada no establecerá simplemente un nivel de volumen absoluto, sino que avanza un poco en la dirección de un volumen objetivo dado. Esto se usa mejor con un botón + o - en su visualización.

Llamada a la API

comentario

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

Reduzca el volumen del grupo para todo el grupo. id es cualquier ID de zona del grupo. El volumen de todos los miembros de la zona se reducirá unos pocos pasos.

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

Aumente el volumen del grupo para todo el grupo. El volumen de todos los miembros de la zona aumentará unos pocos pasos.

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

Aumente el volumen de una sola zona paso a paso, sin afectar a otros miembros del grupo.

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

Disminuya el volumen de una sola zona paso a paso, sin afectar a otros miembros del grupo.

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

Detenga el paso de volumen inmediatamente.

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

Configure el volumen absoluto para una sola zona, aislada de otros miembros del grupo. (Usar con cuidado.)

Para obtener la información del nuevo nivel de volumen dentro de un grupo, haga una llamada a getChanges y observe la lista de estado del volumen.

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

Ejemplo de salida, si está agrupado, en zona/estado:

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

Para obtener una explicación completa de getChanges, consulte Obtener estado de zona.

1.10. Paginación

Las paginaciones deben configurarse en la configuración web. Entonces se pueden usar las siguientes llamadas:

Inicia la búsqueda

/xml/paginación/inicio.xml

Parámetros

nombre descripción

nombre	descripción
`id`	ID de paginación, 0 - 31
`volume`	opcional, 5 - 100. si no se proporciona, se utiliza el nivel de volumen de megafonía configurado.
`autostoptime`	opcional, 5 - 100 segundos. si no se suministran, se utilizan los ajustes de parada configurados.

id

ID de paginación, 0 - 31

volume

opcional, 5 - 100. si no se proporciona, se utiliza el nivel de volumen de megafonía configurado.

autostoptime

opcional, 5 - 100 segundos. si no se suministran, se utilizan los ajustes de parada configurados.

Ejemplo

/xml/paginación/start.xml?id=0&volume=10&autostoptime=10

Un aviso se detiene automáticamente después del tiempo definido, pero puede detenerlo antes llamando al:

/xml/paginación/stop.xml?id=0

2. Selección de música interactiva

Comienza con:

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

Esto produce registros como:

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

luego, por registro:

decodificar y mostrar el campo de texto en su visualización.
_20 significa un carácter con código Ascii 0x20 (un espacio).
si se toca, llame a la url de acción y muestre el siguiente nivel de menú.

No confíe en la disponibilidad permanente de niveles de menú específicos.
Especialmente, los menús proporcionados por los servicios de música pueden cambiar con el tiempo.

3. Obtener estado de zona

3.1. sincrónico

Sondee el estado de una zona con una breve llamada a la API:

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

Parámetros

nombre

función

visuid

un número del 1 al 99 para identificar su instancia de visualización externa.
dentro de este documento API, visuid=90 se usa para solicitudes de prueba.

apiLevel

siempre debe ser 2. esto producirá button xml objects bajo keypad/basic.

ahora

le dice al servidor que devuelva el estado de la nueva zona inmediatamente y que cierre la conexión.
sin &now la llamada se bloquearía hasta un tiempo de espera, o hasta un cambio en las informaciones de estado de la zona.

reload=1

si dos visualizaciones acceden al mismo servidor con el mismo visuid , puede aparecer un error "used two". en este caso, la visualización más reciente debe agregar &reload=1 en la primera llamada, para decirle claramente a que es la visualización más reciente.

Acerca de las unidades de control (Visualizaciones)

Si envía solicitudes con visuid=90, se crea un objeto Control Unit con ID 90 en el servidor.

Puede obtener la lista de unidades de control actuales en la configuración web, en Unidades de control.

Después del primer acceso, la unidad aparece como "No configurada". Tan pronto como cambie su configuración, por ejemplo, configurando la opción "Off presionando brevemente power", se llama Configurado, y las limpiezas posteriores de la lista de Unidades de control no eliminarán este.

Si no hay solicitudes para esta unidad, después de un tiempo se incluirá en "unidades de control actualmente inactivas".

3.2. Asíncrono

Esto significa que una llamada HTTP no regresará inmediatamente, sino que se bloqueará hasta que algo cambie.

Ejemplo:

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

Observe que falta & now. Lo siguiente sucederá:

en la primera llamada a la API:

Se crea una Unidad de Control con ID 90 y se vincula con la primera zona.
La llamada a la API vuelve inmediatamente, con todos los datos de estado de la zona.

en todas las demás llamadas a la API:

La Unidad de Control 90 existente se reutiliza. La llamada API puede bloquearse, hasta que:

se alcanza un tiempo de espera (10 segundos aprox.). en este caso obtienes una respuesta como:
<rows><system><timeout>1</timeout>
o hasta que algo cambie, por ejemplo, el volumen en la zona.

si (muchos) datos de estado han cambiado en el servidor entre dos llamadas a getChanges, es posible que la llamada no se bloquee en absoluto, pero devuelva el nuevo estado inmediatamente.

cuando reciba un tiempo de espera, simplemente vuelva a ejecutar getChanges inmediatamente. esto significa que puede ejecutar getChanges indefinidamente, en un bucle, por ejemplo, en un subproceso de E/S separado. Debido a que una solicitud regresa solo en los cambios, esto no causará problemas de carga con el servidor.

cuando no recibe un tiempo de espera, es decir, la llamada regresa inmediatamente o después de unos segundos (tan pronto como algo haya cambiado), luego procese los datos de estado y luego vuelva a ejecutar la solicitud getChanges.

3.3. Apéndice: ejemplo esquemático para una aplicación Visu Client

3.3.1. Aplicación de hilo único

Esto requiere que pueda probar, en su lenguaje de programación, si existen datos de respuesta para un socket (a través de la llamada select()).

Tema principal

inicio: enviar /xml/zone/getChanges.xml?visuid=90&now
loop begin: actualiza la GUI.
- procesar eventos de entrada del usuario.
- enviar comandos sincrónicos como:
  /xml/zone/runCommand.xml?…
  recibir respuesta, verificar rc Y procesar datos de estado xml
  (igual que con las respuestas de getChanges)
- verifique si existen datos de respuesta para la llamada getChanges en curso
  (en código C: seleccione () llame al socket)
  SI existen datos del servidor trivum:
  - Busque <userdata name="rc">0</userdata>.
    Si NO está presente
    _ procesa el error y espera unos segundos.
    De lo contrario, si NO es un tiempo de espera
    _ procesar respuesta xml (datos de estado)
    Endif
    llamada asíncrona (solo enviar)
    /xml/zone/getChanges.xml&visuid=90&onlyChanges
    Endif
- si no llegan datos del servidor en 1 minuto
  - llamada asíncrona (solo enviar)
    /xml/zone/getChanges.xml&visuid=90&onlyChanges
    endif
- volver a ejecutar el bucle

3.3.2. Ejemplo de aplicación de dos hilos

Se puede usar si prefiere ejecutar bloqueos de recepciones en sockets en un subproceso de E/S separado.

Tema principal

actualizar la interfaz gráfica de usuario.
procesar eventos de entrada del usuario.
enviar comandos sincrónicos como:
/xml/zone/runCommand.xml?…
recibir respuesta, verificar rc Y procesar datos de estado xml
(igual que con las respuestas de getChanges)
recibir datos de estado y errores de Status Thread.
vuelva a ejecutar este bucle.

Tema de estado

SI en el primer ciclo:
- enviar /xml/zone/getChanges.xml?visuid=90&now
  OTRO
- enviar /xml/zone/getChanges.xml?visuid=90&onlyChanges
recibir respuesta (esto se bloquea hasta 10 segundos)
Busque <userdata name="rc">0</userdata>.
Si esto NO está presente, entonces hay un error.
Asegúrese de no simplemente volver a ejecutar el ciclo en caso de errores,
sino al menos esperar unos segundos e informar al hilo principal.
Busque <rows><system><timeout>1</timeout>.
SI esto está presente
- vuelva a ejecutar el ciclo inmediatamente.
  MÁS
- procese los datos de estado de respuesta,
  y copie los nuevos datos de estado en el subproceso principal.
vuelva a ejecutar este bucle.

documentación trivum API

trivum interfaz HTTP

1. Comandos

1.1. ZoneCommand

zoneId

commandNumber

1.2. Establecer fuente de zona

shortSourceName

1.3. Establecer atributo de zona

1.4. Trivum Favoritos

1.5. listas de reproducción trivum

1.6. TuneIn Favoritos

1.7. Presets de FM

1.8. Estado y control NAS

1.9. Manejo de grupo

Cambiar el nivel de volumen dentro de un grupo

1.10. Paginación

2. Selección de música interactiva

3. Obtener estado de zona

3.1. sincrónico

3.2. Asíncrono

3.3. Apéndice: ejemplo esquemático para una aplicación Visu Client

3.3.1. Aplicación de hilo único

3.3.2. Ejemplo de aplicación de dos hilos