Geräte unter iOS steuern

Dieser Leitfaden setzt den Leitfaden Zugriff auf Geräte und Gerätemetadaten auf iOS fort und enthält zusätzliche Beispiele für die Gerätesteuerung und den Zugriff.

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

import GoogleHomeSDK
import GoogleHomeTypes

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

Mit der Funktion supports auf Merkmalsebene 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 des Merkmals „Ein/Aus“ unterstützt: toggle

// 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. Verwenden Sie den OnOffTrait Befehl „Umschalten“, der im Datenmodell des Google Home-Ökosystems als toggle() definiert ist, um das Gerät ein- oder auszuschalten. 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 _ as HomeError {
  // Code for handling the exception
}

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

Alternativ können Sie die Befehle off() oder on() verwenden, um den Status explizit festzulegen:

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

Nachdem Sie einen Befehl zum Ändern des Status gesendet haben, können Sie den Status lesen, wie unter Gerätestatus lesen beschrieben, um ihn in Ihrer App zu verarbeiten.

Befehl mit Parametern senden

Einige Befehle können Parameter verwenden, z. B. die Befehle des OnOffTrait oder des Merkmals LevelControlTrait:

// Turn off the light using the DyingLight effect.
do {
  try await onOffTraitTest.offWithEffect(
    effectIdentifier: Matter.OnOffTrait.EffectIdentifierEnum.dyingLight,
    effectVariant: 0
  )
} catch let _ 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 _ as HomeError {
  // Code for handling the exception
}

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

Einige Geräte unterstützen möglicherweise ein Matter Merkmal, aber nicht ein bestimmtes Attribut. Beispielsweise unterstützt ein Cloud-to-cloud Gerät, das zugeordnet wurde, möglicherweise nicht alle Matter Attribute.Matter Verwenden Sie in solchen Fällen die Eigenschaft isSupported auf Merkmalsebene, 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 Merkmals „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 dem Cloud-to-cloud smart home Schema nullable. Bei diesen Attributen können Sie mit isNullable zusätzlich zu isSupported feststellen, ob ein von dem Attribut zurückgegebenes 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 \(String(describing: onOffTrait.attributes.startUpOnOff))"
      )
    }
  }
}

Merkmalattribute aktualisieren

Wenn Sie den Wert eines bestimmten Attributs ändern möchten und keiner der Befehle des Merkmals dies tut, unterstützt das Attribut möglicherweise das explizite Festlegen des Werts.

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 Merkmalsbefehls ändern?

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

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

• 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. Beispiel: Das currentLevel Attribut des LevelControlTrait ist schreibgeschützt, aber sein Wert kann durch Befehle wie moveToLevel geändert werden.

• Beschreibbar und nicht von anderen Befehlen betroffen. Das bedeutet, dass Sie den Wert des Attributs direkt mit der Funktion update des Merkmals ändern können, aber es gibt keine Befehle, die sich auf den Wert des Attributs auswirken. Beispiel: Das WrongCodeEntryLimit Attribut des DoorLockTrait.

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

Beispiel für die Verwendung der Funktion „update“ zum Ändern des Werts eines Attributs

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

Rufen Sie die Funktion updatedes Merkmals auf und übergeben Sie ihr eine Update-Funktion, die den neuen Wert festlegt, um einen Attributwert festzulegen. Es empfiehlt sich, zuerst zu prüfen, ob das Merkmal ein Attribut unterstützt.

Beispiel:

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