Schema delle funzionalità del volume per la smart home

action.devices.traits.Volume: questo tratto appartiene ai dispositivi in grado di regolare il volume (ad esempio, impostando il volume a un determinato livello oppure attivando o disattivando l'audio).

ATTRIBUTES dispositivo

I dispositivi con questo tratto potrebbero segnalare quanto segue nell'ambito dell'operazione SYNC. Per ulteriori informazioni scopri di più sulla gestione degli intent SYNC; consulta Completamento dell'intent.

Attributi Tipo Descrizione
volumeMaxLevel Intero

Obbligatorio.

Il livello di volume massimo, ipotizzando un valore di base pari a 0 (audio disattivato). L'assistente regolerà i comandi avverbali di conseguenza (ad es. "alza il volume della TV").

volumeCanMuteAndUnmute Valore booleano

Obbligatorio.

Indica se il dispositivo può disattivare e riattivare il volume. L'audio è un'opzione separata dall'audio porta il volume a 0 mentre viene memorizzato il volume precedente, in modo che la riattivazione dell'audio lo ripristini. Ciò si riflette nello stato del volume: se il volume è 5 e l'utente disattiva l'audio, il volume rimane 5 e il valore isMuted è impostato su true.

volumeDefaultPercentage Intero

(Valore predefinito: 40)

Il volume (in percentuale) del volume predefinito definito dall'utente o dal produttore. La scala deve essere compresa tra 0 e 100.

levelStepSize Intero

(Valore predefinito: 1)

La dimensione predefinita dei passaggi per le query di volume relative, come "volume up on <device_name>".

commandOnlyVolume Valore booleano

(Valore predefinito: false)

Indica se il dispositivo funziona utilizzando una comunicazione unidirezionale (vero) o bidirezionale (false). Ad esempio, se il controller può confermare il nuovo stato del dispositivo dopo aver inviato la richiesta, questo campo è falso. Se non è possibile confermare se la richiesta è stata eseguita correttamente o ottenere lo stato del dispositivo (ad esempio, se il dispositivo è un tradizionale telecomando a infrarossi), imposta questo campo su true.

Esempi

Speaker con audio che può essere disattivato e che segnala lo stato attuale

{
  "volumeMaxLevel": 11,
  "volumeCanMuteAndUnmute": true,
  "levelStepSize": 2,
  "commandOnlyVolume": false,
  "volumeDefaultPercentage": 6
}

STATES del dispositivo

Le entità con questo tratto possono segnalare quanto segue nell'ambito dell'operazione QUERY. Per ulteriori informazioni scopri di più sulla gestione degli intent QUERY; consulta Completamento dell'intent.

Stati Tipo Descrizione
currentVolume Intero

Obbligatorio.

La percentuale di volume attuale. Il valore deve essere compreso tra >0 e volumeMaxLevel.

isMuted Valore booleano

Obbligatorio se l'attributo volumeCanMuteAndUnmute è impostato su true. True se l'audio del dispositivo è disattivato; false negli altri casi. Se isMuted è true, il dispositivo restituisce comunque currentVolume per il punto memorizzato.

Esempi

Speaker con audio disattivato e segnalazione dello stato attuale

{
  "currentVolume": 5,
  "isMuted": false
}

COMANDI dispositivo

I dispositivi con questo tratto potrebbero rispondere ai seguenti nell'ambito dell'operazione EXECUTE. Per ulteriori informazioni scopri di più sulla gestione degli intent EXECUTE; consulta Completamento dell'intent.

action.devices.commands.mute

Viene disattivato o riattivato l'audio del dispositivo.

Parametri

Parametri Tipo Descrizione
mute Valore booleano

Obbligatorio.

Indica se disattivare o riattivare l'audio di un dispositivo.

Esempi

Disattiva l'audio del dispositivo altoparlante

{
  "command": "action.devices.commands.mute",
  "params": {
    "mute": true
  }
}

action.devices.commands.setVolume

Imposta il volume al livello richiesto, in base a: volumeMaxLevel.

Parametri

Parametri Tipo Descrizione
volumeLevel Intero

Obbligatorio.

Nuovo volume, da 0 a volumeMaxLevel.

Esempi

Imposta il volume assoluto dello speaker

{
  "command": "action.devices.commands.setVolume",
  "params": {
    "volumeLevel": 6
  }
}

action.devices.commands.volumeRelative

Imposta il volume di n passi in base a volumeMaxLevel. Per i comandi che utilizzano una bilancia relativa, l'assistente selezionerà n in modo appropriato per scalare in base ai passaggi disponibili. Ad esempio, l'opzione Alza il volume della TV imposterà un numero di passi più alto rispetto all'opzione Alza il volume della TV.

Parametri

Parametri Tipo Descrizione
relativeSteps Intero

Obbligatorio.

negativo per "diminuisci".

Esempi

Impostare il volume relativo dello speaker in modalità di solo comando

{
  "command": "action.devices.commands.volumeRelative",
  "params": {
    "relativeSteps": -1
  }
}

ERRORI dispositivo

Consulta l'elenco completo errori ed eccezioni.
  • volumeAlreadyMax: il dispositivo riceve il comando VolumeUp quando viene è già al massimo volume.
  • volumeAlreadyMin: il dispositivo riceve il comando VolumeDown quando viene è già al minimo.