Schema del tratto del volume della smart home

action.devices.traits.Volume: questa caratteristica appartiene ai dispositivi in grado di regolare il volume (ad esempio impostando il volume su un determinato livello, disattivando o riattivando l'audio).

ATTRIBUTI del dispositivo

I dispositivi con questo tratto potrebbero segnalare i seguenti attributi nell'ambito dell'operazione SYNC. Per scoprire 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 l'audio. La disattivazione dell'audio è un'opzione separata, in quanto il comportamento "disattiva l'audio" imposta il volume su 0, ricordando il volume precedente, in modo che la disattivazione dell'audio lo ripristini. Questo si riflette nello stato del volume: se il volume è 5 e l'utente disattiva l'audio, il volume rimane 5 e isMuted è 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)

Il valore predefinito per le query relative al volume, ad esempio "Alza il volume di <nome_dispositivo>".
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 si tratta di un telecomando a infrarossi tradizionale), imposta questo campo su true.

Esempi

Dispositivo altoparlante che può essere disattivato e che segnala lo stato attuale

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

STATI del dispositivo

Le entità con questo attributo possono segnalare i seguenti stati nell'ambito dell'operazione QUERY. Per scoprire di più sulla gestione degli intent QUERY, consulta Completamento dell'intent.

Stati Tipo Descrizione
currentVolume Intero

Obbligatorio.

La percentuale di volume attuale. Deve essere compreso tra >0 e volumeMaxLevel.
isMuted Valore booleano

Obbligatorio se l'attributo volumeCanMuteAndUnmute è impostato su true. Vero se il volume del dispositivo è disattivato; falso in caso contrario. Se isMuted è true, il dispositivo restituisce comunque currentVolume per il punto memorizzato.

Esempi

Dispositivo altoparlante che può essere disattivato e che segnala lo stato attuale

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

COMANDI del dispositivo

I dispositivi con questa caratteristica possono rispondere ai seguenti comandi nell'ambito dell'operazione EXECUTE. Per scoprire di più sulla gestione degli intent EXECUTE, consulta Completamento dell'intent.

action.devices.commands.mute

Disattiva o riattiva l'audio del dispositivo.

Parametri

Parametri Tipo Descrizione
mute Valore booleano

Obbligatorio.

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

Impostare il volume assoluto del dispositivo speaker

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

action.devices.commands.volumeRelative

Alza o abbassa il volume di n passaggi, in base a volumeMaxLevel. Per i comandi che utilizzano una scala relativa, l'assistente selezionerà n in modo appropriato in base ai passaggi disponibili. Ad esempio, Alza molto il volume della TV imposterà un numero di passaggi superiore rispetto a Alza un po' il volume della TV.

Parametri

Parametri Tipo Descrizione
relativeSteps Intero

Obbligatorio.

negativo per "diminuzione".

Esempi

Impostare il volume relativo del dispositivo altoparlante in modalità solo comando

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

ERRORI del dispositivo

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