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 questa caratteristica possono segnalare i seguenti attributi nell'ambito dell'operazione SYNC. Per scoprire di più sulla gestione degli intent SYNC, consulta Adempimento degli intent.

Attributi Tipo Descrizione
volumeMaxLevel Intero

Obbligatorio.

Il livello di volume massimo, supponendo un valore di base pari a 0 (silenziamento). L'assistente regolerà i comandi avverbiali (ad es. "alza un po' il volume della TV") di conseguenza.
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 su <nome_dispositivo>".
commandOnlyVolume Valore booleano

(valore predefinito: false)

Indica se il dispositivo funziona utilizzando una comunicazione unidirezionale (true) o bidirezionale (false). Ad esempio, se il controller può confermare lo stato del nuovo dispositivo dopo l'invio della richiesta, questo campo sarà 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 corrente

{
  "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 Adempimento degli 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 Adempimento degli 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

Disattivare 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 speaker 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 è già al volume massimo.
  • volumeAlreadyMin: il dispositivo riceve il comando VolumeDown quando il volume è già al minimo.