Contrôler des appareils

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

Vous pouvez également vérifier la compatibilité d'une commande de trait. Utilisez également la fonction supports au niveau des traits pour vérifier si une commande est compatible avec un appareil particulier.

Par exemple, pour vérifier si un appareil est compatible avec la commande toggle de la caractéristique Marche/Arrêt:

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

Envoyer une commande à un appareil

L'envoi d'une commande est semblable à la lecture d'un attribut d'état à partir d'un trait. Pour allumer ou éteindre l'appareil, utilisez la commande d'activation/de désactivation de la caractéristique OnOff, qui est 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 s'agit de true, ou par true s'il s'agit de false:

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

Toutes les commandes de trait sont des fonctions suspend et ne sont terminées que lorsqu'une réponse est renvoyée par l'API (par exemple, pour confirmer que l'état de l'appareil a changé). Les commandes peuvent renvoyer une exception si un problème est détecté avec le flux d'exécution. En tant que développeur, vous devez utiliser un bloc try-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'environnement d'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:

onOffTrait.off()
onOffTrait.on()

Une fois la commande envoyée pour modifier l'état, vous pouvez lire l'état comme décrit dans Lire l'état d'un appareil pour le gérer dans votre application. Vous pouvez également utiliser des flux comme décrit dans Observer l'état, ce qui est la méthode recommandée.

Envoyer une commande avec des paramètres

Certaines commandes peuvent utiliser des paramètres, comme ceux des traits OnOff ou 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(),
)

Certaines commandes comportent des arguments facultatifs, qui viennent après les arguments obligatoires.

Par exemple, la commande step pour le trait FanControl comporte deux arguments facultatifs:

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 }

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

Certains appareils peuvent prendre en charge un trait Matter, mais pas un attribut spécifique. Par exemple, un appareil Cloud-to-cloud mappé sur Matter peut ne pas prendre en charge tous les attributs Matter. Pour gérer des cas comme ceux-ci, utilisez la fonction supports au niveau de la caractéristique et l'énumération Attribute de la caractéristique pour vérifier si l'attribut est compatible avec un appareil particulier.

Par exemple, pour vérifier si un appareil est compatible avec l'attribut onOff de la caractéristique Marche/Arrêt:

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

Certains attributs sont nullables dans la spécification Matter ou le schéma smart home Cloud-to-cloud. Pour ces attributs, vous pouvez déterminer si une valeur null renvoyée par l'attribut est due au fait que l'appareil ne signale pas cette valeur, ou si la valeur de l'attribut est réellement null, en utilisant isNullable en plus de supports:

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

Mettre à jour les attributs des traits

Si vous souhaitez modifier la valeur d'un attribut donné et qu'aucune des commandes de la caractéristique ne le fait, il est possible que l'attribut puisse être défini explicitement.

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

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

La documentation de référence sur les traits 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:

• En lecture seule et non affecté par les autres commandes. Cela signifie que la valeur de l'attribut ne change pas. Par exemple, l'attribut currentPosition du trait Switch.

• En lecture seule et affecté par d'autres commandes. Cela signifie que la valeur de l'attribut ne peut changer que suite à l'envoi d'une commande. Par exemple, l'attribut currentLevel du trait Matter LevelControl est en lecture seule, mais sa valeur peut être modifiée par des commandes telles que moveToLevel.

• Il peut être écrit et n'est pas affecté par les autres commandes. Cela signifie que vous pouvez modifier directement la valeur de l'attribut à l'aide de la fonction update du trait, mais aucune commande n'affectera la valeur de l'attribut. Par exemple, l'attribut WrongCodeEntryLimit du trait DoorLock.

• Peut être écrit et est affecté par d'autres commandes. Cela signifie que vous pouvez modifier directement la valeur de l'attribut à l'aide de la fonction update du trait, et que la valeur de l'attribut peut changer en raison de l'envoi d'une commande. Par exemple, l'attribut occupiedCoolingSetpoint du trait Thermostat peut être écrit, mais aussi mis à jour à l'aide de la commande setpointRaiseLower.

Exemple d'utilisation de la fonction update pour modifier la valeur d'un attribut

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

Pour définir une valeur d'attribut, appelez la fonction update du trait et transmettez-lui une fonction de modification qui définit la nouvelle valeur. Nous vous recommandons de commencer par vérifier que la caractéristique est compatible avec un attribut.

Exemple :

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