Geräte unter iOS steuern

Dieser Leitfaden setzt auf dem Leitfaden Auf Geräte und Gerätemetadaten auf iOS zugreifen auf und enthält zusätzliche Beispiele für die Gerätesteuerung und den Gerätezugriff.

Wenn Sie bestimmte Gerätetypen oder Merkmale verwenden möchten, z. B. Matter OnOffTrait, die in vielen der Beispiele hier verwendet werden, müssen sie importiert werden:

import GoogleHomeSDK
import GoogleHomeTypes

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

Verwenden Sie die Funktion supports auf Trait-Ebene, um zu 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 des On/Off-Traits 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 Merkmal. Verwende zum Ein- oder Ausschalten des Geräts den Ein/Aus-Befehl OnOffTrait, der im Google Home-Ökosystem-Datenmodell 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.
do {
  try await onOffTraitTest.toggle()
} catch let error as HomeError {
  // Code for handling the exception
}

Befehle geben möglicherweise eine Ausnahme zurück, wenn ein Problem mit dem Ausführungsablauf erkannt wird. Als Entwickler sollten Sie einen do-catch-Block verwenden, um diese Ausnahmen richtig zu verarbeiten und Nutzern detaillierte Informationen zu Fällen zu präsentieren, in denen die Fehler behoben werden können. Nicht abgefangene Ausnahmen beenden die App-Laufzeit und können zu Abstürzen in Ihrer App führen.

Alternativ können Sie den Status explizit mit den Befehlen off() oder on() 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 den Status nach Abschluss des Vorgangs wie unter Gerätestatus lesen beschrieben lesen, um ihn in Ihrer App zu verarbeiten.

Befehl mit Parametern senden

Für einige Befehle werden möglicherweise Parameter verwendet, z. B. 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 Attribut von einem Merkmal unterstützt wird

Einige Geräte unterstützen möglicherweise ein Matter-Merkmal, aber kein bestimmtes Attribut. Beispielsweise unterstützt ein Cloud-to-cloud-Gerät, das Matter zugeordnet wurde, möglicherweise nicht jedes Matter-Attribut. Um solche Fälle zu behandeln, verwenden Sie die Eigenschaft isSupported auf Trait-Ebene, 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 Traits „Ein/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 ein von dem Attribut zurückgegebener nil darauf zurückzuführen ist, dass 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)"
      )
    }
  }
}

Trait-Attribute aktualisieren

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

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 Trait-Befehls ändern?

Diese Informationen finden Sie in der Referenzdokumentation für Traits und ihre Attribute.

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

• Schreibgeschützt und nicht von anderen Befehlen betroffen. Das bedeutet, dass sich der Wert des Attributs nicht ändert. Beispiel: Das Attribut currentPosition des Elements 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 LevelControlTrait ist beispielsweise schreibgeschützt, 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 mit der update-Funktion des Traits ändern können. Es gibt jedoch keine Befehle, die sich auf den Wert des Attributs auswirken. Beispiel: Das Attribut WrongCodeEntryLimit des Elements DoorLockTrait.

• Schreibbar und von anderen Befehlen betroffen. Das bedeutet, dass Sie den Wert des Attributs direkt mit der update-Funktion des Traits ändern können und sich der Wert des Attributs durch das Senden eines Befehls ändern kann. So kann beispielsweise das Attribut occupiedCoolingSetpoint des ThermostatTrait 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 der Wert des Attributs DoorLockTrait.wrongCodeEntryLimit explizit festgelegt wird.

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

Beispiel:

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