Smart-Home-Trait-Schema für Lautstärke

action.devices.traits.Volume : Dieses Trait gehört zu Geräten, bei denen die Lautstärke geändert werden kann (z. B. Einstellen der Lautstärke auf einen bestimmten Pegel, Stummschalten oder Aufheben der Stummschaltung).

Geräteattribute

Geräte mit diesem Trait können die folgenden Attribute im Rahmen des SYNC Vorgangs melden. Weitere Informationen zum Verarbeiten von SYNC Intents finden Sie unter Intent-Ausführung.

Attribute Typ Beschreibung
volumeMaxLevel Ganzzahl

Erforderlich.

Die maximale Lautstärke, wobei von einer Baseline von 0 (stumm) ausgegangen wird. Der Assistant passt adverbiale Befehle entsprechend an (z.B. „Mach den Fernseher etwas lauter“).
volumeCanMuteAndUnmute Boolesch

Erforderlich.

Gibt an, ob die Lautstärke des Geräts stummgeschaltet und die Stummschaltung aufgehoben werden kann. Die Stummschaltung ist eine separate Option, da die Lautstärke bei der Stummschaltung auf 0 gesetzt wird, die vorherige Lautstärke aber gespeichert wird, sodass sie durch Aufheben der Stummschaltung wiederhergestellt werden kann. Dies spiegelt sich im Lautstärkenstatus wider: Wenn die Lautstärke auf 5 eingestellt ist und der Nutzer das Gerät stummschaltet, bleibt die Lautstärke auf 5 und isMuted ist „true“.
volumeDefaultPercentage Ganzzahl

(Standardeinstellung: 40)

Die Lautstärke (in Prozent) für die vom Nutzer oder Hersteller definierte Standardlautstärke. Der Wert muss zwischen 0 und 100 liegen.

Der Wert muss zwischen 0 und 100 liegen.
levelStepSize Ganzzahl

(Standardeinstellung: 1)

Die Standard-Schrittgröße für relative Lautstärkeabfragen wie „Lautstärke erhöhen auf <Gerätename>“.
commandOnlyVolume Boolesch

(Standardeinstellung: false)

Gibt an, ob das Gerät mit unidirektionaler (true) oder bidirektionaler (false) Kommunikation arbeitet. Wenn der Controller beispielsweise den neuen Gerätestatus bestätigen kann, nachdem er die Anfrage gesendet hat, ist dieses Feld „false“. Wenn es nicht möglich ist, zu bestätigen, ob die Anfrage erfolgreich ausgeführt wurde, oder den Status des Geräts abzurufen (z. B. wenn das Gerät eine herkömmliche Infrarot-Fernbedienung ist), legen Sie für dieses Feld „true“ fest.

Beispiele

Lautsprecher, der stummgeschaltet werden kann und den aktuellen Status meldet

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

Gerätestatus

Entitäten mit diesem Trait können die folgenden Status im Rahmen des QUERY Vorgangs melden. Weitere Informationen zum Verarbeiten von QUERY Intents finden Sie unter Intent-Ausführung.

Status Typ Beschreibung
currentVolume Ganzzahl

Erforderlich.

Die aktuelle Lautstärke in Prozent. Der Wert muss zwischen >0 und volumeMaxLevel liegen.

Mindestwert: 0.
isMuted Boolesch

Erforderlich, wenn das Attribut volumeCanMuteAndUnmute auf „true“ gesetzt ist. „True“, wenn das Gerät stummgeschaltet ist, andernfalls „false“. Wenn isMuted „true“ ist, gibt das Gerät weiterhin currentVolume für den gespeicherten Punkt zurück.

Beispiele

Lautsprecher, der stummgeschaltet werden kann und den aktuellen Status meldet

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

Gerätebefehle

Geräte mit diesem Trait können im Rahmen des EXECUTE Vorgangs auf die folgenden Befehle reagieren. Weitere Informationen zum Verarbeiten von EXECUTE Intents finden Sie unter Intent-Ausführung.

action.devices.commands.mute

Schaltet das Gerät stumm oder hebt die Stummschaltung auf.

Parameter

Parameter Typ Beschreibung
mute Boolesch

Erforderlich.

Gibt an, ob ein Gerät stummgeschaltet oder die Stummschaltung aufgehoben werden soll.

Beispiele

Lautsprecher stummschalten

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

action.devices.commands.setVolume

Stellt die Lautstärke basierend auf volumeMaxLevel auf den angeforderten Pegel ein.

Parameter

Parameter Typ Beschreibung
volumeLevel Ganzzahl

Erforderlich.

Neue Lautstärke zwischen 0 und volumeMaxLevel.

Mindestwert: 0.

Beispiele

Absolute Lautstärke des Lautsprechers einstellen

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

action.devices.commands.volumeRelative

Stellt die Lautstärke basierend auf volumeMaxLevel um n Schritte nach oben oder unten ein. Bei Befehlen, die eine relative Skala verwenden, wählt der Assistant n entsprechend aus, um die verfügbaren Schritte zu skalieren. Beispielsweise wird bei Mach den Fernseher viel lauter eine höhere Anzahl von Schritten festgelegt als bei Mach den Fernseher etwas lauter.

Parameter

Parameter Typ Beschreibung
relativeSteps Ganzzahl

Erforderlich.

Negativ für „verringern“.

Beispiele

Relative Lautstärke des Lautsprechers im Befehlsmodus einstellen

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

Gerätefehler

Eine vollständige Liste der Fehler und Ausnahmenfinden Sie hier.
  • volumeAlreadyMax: Das Gerät empfängt den Befehl VolumeUp, obwohl die Lautstärke bereits auf dem höchsten Pegel ist.
  • volumeAlreadyMin: Das Gerät empfängt den Befehl VolumeDown, obwohl die Lautstärke bereits auf dem niedrigsten Pegel ist.