Contrôler les appareils sur iOS

Ce guide fait suite à la section Accéder aux appareils et aux métadonnées d'appareil sur iOS et présente d'autres exemples de contrôle et d'accès aux appareils.

Pour utiliser des types ou des caractéristiques d'appareils spécifiques, tels que le Matter OnOffTrait utilisé dans de nombreux exemples ici, vous devez les importer :

import GoogleHomeSDK
import GoogleHomeTypes

Vérifier si une caractéristique est compatible avec une commande

Utilisez la fonction supports au niveau de la caractéristique pour vérifier si une commande est compatible avec un appareil spécifique.

Par exemple, pour vérifier si un appareil est compatible avec la caractéristique On/Off's toggle commande :

// 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")
}

Envoyer une commande à un appareil

L'envoi d'une commande est semblable à la lecture d'un attribut d'état à partir d'une caractéristique. Pour allumer ou éteindre l'appareil, utilisez la OnOffTrait commande Toggle, définie dans le modèle de données de l'écosystème Google Home comme toggle(). Cette méthode remplace onOff par false s'il est true, ou par true s'il est false :

// Calling a command on a trait.
do {
  try await onOffTraitTest.toggle()
} catch let _ as HomeError {
  // Code for handling the exception
}

Les commandes peuvent renvoyer une exception si un problème est détecté dans le flux d'exécution. En tant que développeur, vous devez utiliser un bloc do-catch pour gérer correctement ces exceptions et fournir des informations détaillées aux utilisateurs dans les cas où les erreurs sont exploitables. Les exceptions non gérées arrêtent l'exécution de l'application et peuvent entraîner des plantages.

Vous pouvez également utiliser les commandes off() ou on() pour définir explicitement l'état :

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

Une fois que vous avez envoyé une commande pour modifier l'état, une fois qu'elle est terminée, vous pouvez lire l' état comme décrit dans Lire l'état d'un appareil pour le gérer dans votre application.

Envoyer une commande avec des paramètres

Certaines commandes peuvent utiliser des paramètres, comme ceux de la OnOffTrait ou de la 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
}

Vérifier si une caractéristique est compatible avec un attribut

Certains appareils peuvent être compatibles avec une Matter caractéristique, mais pas avec un attribut spécifique. Par exemple, un appareil Cloud-to-cloud qui a été mappé à Matter peut ne pas être compatible avec tous les attributs Matter. Pour gérer ces cas, utilisez la propriété isSupported au niveau de la caractéristique pour vérifier si l'attribut est compatible avec un appareil spécifique.

Par exemple, pour vérifier si un appareil est compatible avec l'attribut onOff de la caractéristique On/Off :

// 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!")
}

Certains attributs peuvent être nuls dans la Matter spécification ou le Cloud-to-cloud smart home schéma. Pour ces attributs, vous pouvez déterminer si un nil renvoyé par l'attribut est dû au fait que l'appareil ne signale pas cette valeur ou si la valeur de l'attribut est réellement nil, en utilisant isNullable en plus de isSupported :

// 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))"
      )
    }
  }
}

Mettre à jour les attributs de caractéristique

Si vous souhaitez modifier la valeur d'un attribut donné et qu'aucune des commandes de la caractéristique ne le fait, l'attribut peut être compatible avec la définition explicite de sa valeur.

La possibilité de modifier la valeur d'un attribut dépend de deux facteurs :

• L'attribut est-il accessible en écriture ?
• La valeur de l'attribut peut-elle changer en tant qu'effet secondaire de l'envoi d'une commande de caractéristique ?

La documentation de référence sur les caractéristiques et leurs attributs fournit ces informations.

Par conséquent, les combinaisons de propriétés qui déterminent comment la valeur d'un attribut peut être modifiée sont les suivantes :

• Lecture seule et non affectée par d'autres commandes. Cela signifie que la valeur de l'attribut ne change pas. Par exemple, l' currentPosition attribut de SwitchTrait.

• Lecture seule et affectée par d'autres commandes. Cela signifie que la seule façon dont la valeur de l'attribut peut changer est d'envoyer une commande. Par exemple, l' currentLevel attribut du LevelControlTrait est en lecture seule, mais sa valeur peut être modifiée par des commandes telles que moveToLevel.

• Accessible en écriture et non affectée par d'autres commandes. Cela signifie que vous pouvez modifier directement la valeur de l'attribut à l'aide de la fonction update de la caractéristique, mais aucune commande n'affectera la valeur de l'attribut. Par exemple, l' WrongCodeEntryLimit attribut de DoorLockTrait.

• Accessible en écriture et affectée par d'autres commandes. Cela signifie que vous pouvez modifier directement la valeur de l'attribut à l'aide de la fonction update de la caractéristique, et que la valeur de l'attribut peut changer suite à l'envoi d'une commande. Par exemple, l' occupiedCoolingSetpoint attribut de ThermostatTrait peut être écrit, mais aussi mis à jour avec la setpointRaiseLower commande.

Exemple d'utilisation de la fonction de mise à jour pour modifier la valeur d'un attribut

Cet exemple montre comment définir explicitement la valeur de l' DoorLockTrait.wrongCodeEntryLimit attribut.

Pour définir une valeur d'attribut, appelez la fonction updatede la caractéristique et transmettez-lui une fonction de mise à jour qui définit la nouvelle valeur. Il est recommandé de vérifier d'abord que la caractéristique est compatible avec un attribut.

Exemple :

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