Geräte unter iOS steuern

Dieser Leitfaden knüpft an den Artikel Auf Geräte und Gerätemetadaten auf iOS-Geräten zugreifen an und enthält weitere Beispiele für die Gerätesteuerung und den Zugriff.

Wenn Sie bestimmte Gerätetypen oder -merkmale verwenden möchten, z. B. Matter OnOffTrait, das in vielen der folgenden Beispiele verwendet wird, müssen diese importiert werden:

import GoogleHomeSDK
import GoogleHomeTypes

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

Mit der Funktion supports auf Merkmalebene können Sie 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 die Eigenschaft „An/Aus“ unterstützt:

// Check if the OnOff trait supports the toggle command.
if onOffTraitTest.supportsToggleCommand {
  print("onOffTrait supports toggle command")
} else {
  print("onOffTrait does not support stateful toggle command")
}

Befehl an Geräte senden

Das Senden eines Befehls ähnelt dem Lesen eines Statusattributs aus einem Attribut. Verwenden Sie den Befehl OnOffTrait „Ein/Aus“, um das Gerät ein- oder auszuschalten. Dieser Befehl ist im Datenmodell des Google Home-Systems als toggle() definiert. 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.
do {
  try await onOffTraitTest.toggle()
} catch let error as HomeError {
  // Code for handling the exception
}

Befehle können eine Ausnahme zurückgeben, wenn ein Problem mit dem Ausführungsablauf erkannt wird. Als Entwickler sollten Sie einen do-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:

do {
  try await onOffTraitTest.off()
  try await onOffTraitTest.on()
} catch let error as HomeError {
  // Code for handling the exception
}

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.

Befehl mit Parametern senden

Für einige Befehle können Parameter verwendet werden, z. B. die für OnOffTrait oder LevelControlTrait:

// Turn off the light using the DyingLight effect.
do {
  try await onOffTraitTest.offWithEffect(
    effectIdentifier: Matter.OnOffTrait.EffectIdentifierEnum.dyingLight,
    effectVariant: 0
  )
} catch let error as HomeError {
  // Code for handling the exception
}

// Change the brightness of the light to 50%
do {
  try await levelControlTraitTest.moveToLevel(
    level: UInt8(127),
    transitionTime: 0,
    optionsMask: Matter.LevelControlTrait.OptionsBitmap(),
    optionsOverride: Matter.LevelControlTrait.OptionsBitmap()
  )
} catch let error as HomeError {
  // Code for handling the exception
}

Prüfen, ob ein Merkmal ein Attribut unterstützt

Einige Geräte unterstützen möglicherweise eine Matter-Eigenschaft, aber nicht ein bestimmtes Attribut. Ein Cloud-to-cloud-Gerät, das Matter zugeordnet wurde, unterstützt beispielsweise möglicherweise nicht alle Matter-Attribute. In solchen Fällen können Sie mit der Eigenschaft isSupported auf Merkmalsebene 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 der Eigenschaft „An/Aus“ unterstützt:

// Check if the OnOff trait supports the onOff attribute.
if onOffTrait.attributes.$onOff.isSupported {
  print("onOffTrait supports onOff state")
} else {
  print("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 isSupported feststellen, ob der vom Attribut zurückgegebene Wert nil ist, weil das Gerät diesen Wert nicht meldet, oder ob der Wert des Attributs tatsächlich nil ist:

// Check if a nullable attribute is set or is not supported.
if let deviceType = await device.types.get(OnOffLightDeviceType.self) {
  if let onOffTrait = deviceType.traits[Matter.OnOffTrait.self] {
    if onOffTrait.attributes.startUpOnOff == nil {
      if onOffTrait.attributes.$startUpOnOff.isSupported {
        print(
          "onOffTrait supports startUpOnOff and it is nil. Check the spec for the contextual meaning."
        )
      } else {
        print("onOffTrait does not support startUpOnOff!")
      }
    } else {
      print(
        "onOffTrait supports startUpOnOff and it is set to \(onOffTrait.attributes.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 SwitchTrait.

• 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 des Elements LevelControlTrait ist beispielsweise nur lesbar, sein Wert kann aber durch Befehle 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 DoorLockTrait

• 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 Attribut occupiedCoolingSetpoint von ThermostatTrait nicht nur beschrieben, sondern 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 Aktualisierungsfunktion, die den neuen Wert festlegt. Es empfiehlt sich, zuerst zu prüfen, ob das Attribut vom Merkmal unterstützt wird.

Beispiel:

if doorLockTraitTest.attributes.$wrongCodeEntryLimit.isSupported {
  let _ = try await doorLockTraitTest.update {
    $0.setWrongCodeEntryLimit(3)
  }
}