Schema del tratto Volume smart home

action.devices.traits.Volume: questa caratteristica appartiene ai dispositivi in grado di modificare il volume (ad esempio, impostare il volume a un determinato livello, disattivare o riattivare l'audio).

ATTRIBUTI dispositivo

I dispositivi con questa caratteristica potrebbero segnalare i seguenti attributi nell'ambito dell'operazione SYNC. Per saperne di più sulla gestione degli intent SYNC, consulta Completamento degli intent.

Attributi Tipo Descrizione
volumeMaxLevel Intero

Obbligatorio.

Il livello di volume massimo, presupponendo una base di 0 (audio disattivato). L'assistente regolerà di conseguenza i comandi avverbiali (ad es. "alza un po' il volume della TV").
volumeCanMuteAndUnmute Valore booleano

Obbligatorio.

Indica se il dispositivo può disattivare e riattivare il volume. La disattivazione dell'audio è un'opzione separata, in quanto il comportamento di "disattivazione dell'audio" porta il volume a 0, ricordando 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 isMuted è true.
volumeDefaultPercentage Intero

(Valore predefinito: 40)

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

Il valore deve essere compreso tra 0 e 100.
levelStepSize Intero

(Valore predefinito: 1)

La dimensione del passo predefinita per le query sul volume relativo come "Alza il volume su <device_name>.
commandOnlyVolume Valore booleano

(Valore predefinito: false)

Indica se il dispositivo funziona utilizzando la comunicazione unidirezionale (true) o bidirezionale (false). Ad esempio, se il controller può confermare il nuovo stato del dispositivo dopo l'invio della richiesta, questo campo sarà false. Se non è possibile confermare l'esecuzione corretta della richiesta o ottenere lo stato del dispositivo (ad esempio, se il dispositivo è un telecomando a infrarossi tradizionale), imposta questo campo su true.

Esempi

Dispositivo speaker che può essere silenziato e segnala lo stato attuale

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

Stati del dispositivo

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

Stati Tipo Descrizione
currentVolume Intero

Obbligatorio.

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

Valore minimo: 0.
isMuted Valore booleano

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

Esempi

Dispositivo speaker che può essere silenziato e segnala lo stato attuale

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

COMANDI del dispositivo

I dispositivi con questa caratteristica potrebbero rispondere ai seguenti comandi nell'ambito dell'operazione EXECUTE. Per saperne di più sulla gestione degli intent EXECUTE, consulta Completamento 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 speaker

{
  "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.

Valore minimo: 0.

Esempi

Impostare il volume assoluto del dispositivo speaker

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

action.devices.commands.volumeRelative

Imposta il volume su o giù di n passaggi, in base a volumeMaxLevel. Per i comandi che utilizzano una scala relativa, l'assistente selezionerà n in modo appropriato per scalare i 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 comandi

{
  "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 è già al volume più basso.