Geräte steuern

Prüfen, ob ein Attribut einen Befehl unterstützt

Der Support kann auch nach einem Befehl für Merkmale suchen. Mit der Funktion supports auf Merkmalebene können Sie auch prüfen, ob ein Befehl für ein bestimmtes Gerät unterstützt wird.

So prüfen Sie beispielsweise, ob ein Gerät den Befehl toggle für das Attribut „An/Aus“ unterstützt:

// Check if the OnOff trait supports the toggle command.
if (onOffTrait.supports(OnOff.Command.Toggle)) {
  println("onOffTrait supports toggle command")
} else {
  println("onOffTrait does not support stateful toggle command")
}

Befehl an Geräte senden

Das Senden eines Befehls ähnelt dem Lesen eines Statusattributs aus einem Attribut. Wenn Sie das Gerät ein- oder ausschalten möchten, verwenden Sie den Befehl „An/Aus“ des Attributs OnOff, das im Datenmodell des Google Home-Systems als toggle() definiert ist. Mit dieser Methode wird onOff in false geändert, wenn es true ist, oder in true, wenn es false ist:

// Calling a command on a trait.
try {
  onOffTrait.toggle()
} catch (e: HomeException) {
  // Code for handling the exception
}

Alle Attributbefehle sind suspend-Funktionen und werden erst abgeschlossen, wenn eine Antwort von der API zurückgegeben wird, z. B. eine Bestätigung, dass sich der Gerätestatus geändert hat. Befehle können eine Ausnahme zurückgeben, wenn ein Problem mit dem Ausführungsablauf erkannt wird. Als Entwickler sollten Sie einen try-catch-Block verwenden, um diese Ausnahmen ordnungsgemäß zu behandeln und Nutzern detaillierte Informationen zu Fällen zur Verfügung zu stellen, in denen die Fehler behoben werden können. Unbehandelte Ausnahmen beenden die App-Laufzeit und können zu Abstürzen Ihrer App führen.

Alternativ können Sie den Status mit den Befehlen off() oder on() explizit festlegen:

onOffTrait.off()
onOffTrait.on()

Nachdem Sie einen Befehl zum Ändern des Status gesendet haben, können Sie ihn wie unter Gerätestatus lesen beschrieben lesen, um ihn in Ihrer App zu verarbeiten. Alternativ können Sie auch Abläufe wie unter Status beobachten beschrieben verwenden. Dies ist die bevorzugte Methode.

Befehl mit Parametern senden

Einige Befehle können Parameter verwenden, z. B. die auf den Eigenschaften OnOff oder LevelControl:

// Turn off the light using the DyingLight effect.
onOffTrait.offWithEffect(
  effectIdentifier = OnOffTrait.EffectIdentifierEnum.DyingLight,
  effectVariant = 0u,
)

// Change the brightness of the light to 50%
levelControlTrait.moveToLevel(
  level = 127u.toUByte(),
  transitionTime = null,
  optionsMask = LevelControlTrait.OptionsBitmap(),
  optionsOverride = LevelControlTrait.OptionsBitmap(),
)

Einige Befehle haben optionale Argumente, die nach den erforderlichen Argumenten kommen.

Der Befehl step für das Attribut FanControl hat beispielsweise zwei optionale Argumente:

val fanControlTraitFlow: Flow<FanControl?> =
  device.type(FanDevice).map { it.standardTraits.fanControl }.distinctUntilChanged()

val fanControl = fanControlTraitFlow.firstOrNull()

// Calling a command with optional parameters not set.
fanControl?.step(direction = FanControlTrait.StepDirectionEnum.Increase)

// Calling a command with optional parameters.
fanControl?.step(direction = FanControlTrait.StepDirectionEnum.Increase) { wrap = true }

Prüfen, ob ein Attribut von einem Merkmal unterstützt wird

Einige Geräte unterstützen möglicherweise ein Matter-Attribut, aber kein bestimmtes Attribut. Ein Cloud-to-cloud-Gerät, das Matter zugeordnet wurde, unterstützt beispielsweise möglicherweise nicht alle Matter-Attribute. Verwenden Sie in solchen Fällen die Funktion supports auf Merkmalebene und das Attribute-Enum des Merkmals, um zu prüfen, ob das Attribut für ein bestimmtes Gerät unterstützt wird.

So prüfen Sie beispielsweise, ob ein Gerät das Attribut onOff des Attributs „An/Aus“ unterstützt:

// Check if the OnOff trait supports the onOff attribute.
if (onOffTrait.supports(OnOff.Attribute.onOff)) {
  println("onOffTrait supports onOff state")
} else {
  println("onOffTrait is for a command only device!")
}

Einige Attribute sind in der Matter-Spezifikation oder im Cloud-to-cloud smart home-Schema nullable. Bei diesen Attributen können Sie mithilfe von isNullable zusätzlich zu supports feststellen, ob der vom Attribut zurückgegebene Wert null ist, weil das Gerät diesen Wert nicht meldet, oder ob der Wert des Attributs tatsächlich null ist:

// Check if a nullable attribute is set or is not supported.
if (onOffTrait.supports(OnOff.Attribute.startUpOnOff)) {
  // The device supports startupOnOff, it is safe to expect this value in the trait.
  if (OnOff.Attribute.startUpOnOff.isNullable && onOffTrait.startUpOnOff == null) {
    // This value is nullable and set to null. Check the specification as to
    // what null in this case means
    println("onOffTrait supports startUpOnOff and it is null")
  } else {
    // This value is nullable and set to a value.
    println("onOffTrait supports startUpOnOff and it is set to ${onOffTrait.startUpOnOff}")
  }
} else {
  println("onOffTrait does not support startUpOnOff!")
}

Merkmalattribute aktualisieren

Wenn Sie den Wert eines bestimmten Attributs ändern möchten und keiner der Befehle des Merkmals dies tut, kann es sein, dass der Wert des Attributs explizit festgelegt werden kann.

Ob der Wert eines Attributs geändert werden kann, hängt von zwei Faktoren ab:

• Ist das Attribut beschreibbar?
• Kann sich der Wert des Attributs als Nebeneffekt des Sendens eines Attributbefehls ändern?

Diese Informationen finden Sie in der Referenzdokumentation zu Merkmalen und ihren Attributen.

Die Kombinationen von Eigenschaften, die festlegen, wie der Wert eines Attributs geändert werden kann, sind daher:

• Schreibgeschützt und nicht von anderen Befehlen betroffen. Das bedeutet, dass sich der Wert des Attributs nicht ändert. Beispiel: das currentPosition-Attribut des Merkmals Switch.

• Schreibgeschützt und von anderen Befehlen betroffen. Das bedeutet, dass sich der Wert des Attributs nur durch das Senden eines Befehls ändern kann. Das Attribut currentLevel der Eigenschaft LevelControl Matter ist beispielsweise nur lesend, sein Wert kann aber mit Befehlen wie moveToLevel geändert werden.

• Schreibbar und nicht von anderen Befehlen betroffen. Das bedeutet, dass Sie den Wert des Attributs direkt mithilfe der update-Funktion des Merkmals ändern können. Es gibt jedoch keine Befehle, die sich auf den Wert des Attributs auswirken. Beispiel: das WrongCodeEntryLimit-Attribut des Merkmals DoorLock.

• Schreibbar und von anderen Befehlen betroffen. Das bedeutet, dass Sie den Wert des Attributs direkt mithilfe der update-Funktion des Merkmals ändern können. Der Wert des Attributs kann sich auch durch das Senden eines Befehls ändern. So kann beispielsweise das occupiedCoolingSetpoint-Attribut des Thermostat-Attributs geschrieben, aber auch mit dem Befehl setpointRaiseLower aktualisiert werden.

Beispiel für die Verwendung der Update-Funktion zum Ändern des Werts eines Attributs

In diesem Beispiel wird gezeigt, wie Sie den Wert des Attributs DoorLockTrait.WrongCodeEntryLimit explizit festlegen.

Wenn Sie einen Attributwert festlegen möchten, rufen Sie die update-Funktion des Merkmals auf und übergeben Sie ihr eine Mutatorfunktion, die den neuen Wert festlegt. Es empfiehlt sich, zuerst zu prüfen, ob das Attribut vom Merkmal unterstützt wird.

Beispiel:

    var doorLockDevice = home.devices().list().first { device -> device.has(DoorLock) }

    val traitFlow: Flow<DoorLock?> =
      doorLockDevice.type(DoorLockDevice).map { it.standardTraits.doorLock }.distinctUntilChanged()

    val doorLockTrait: DoorLock = traitFlow.first()!!

    if (doorLockTrait.supports(DoorLock.Attribute.wrongCodeEntryLimit)) {
      val unused = doorLockTrait.update { setWrongCodeEntryLimit(3u) }
    }