Cómo controlar dispositivos en iOS

Esta guía continúa desde Acceder a dispositivos y metadatos de dispositivos en iOS y presenta ejemplos adicionales de control y acceso a dispositivos.

Para usar tipos o atributos de dispositivos específicos, como el Matter OnOffTrait que se usa en muchos de los ejemplos aquí, se deben importar:

import GoogleHomeSDK
import GoogleHomeTypes

Verifica si un atributo admite un comando

Usa la función supports a nivel de atributo para verificar si se admite un comando para un dispositivo en particular.

Por ejemplo, para verificar la compatibilidad de un dispositivo con el atributo On/Off, haz lo siguiente: toggle comando:

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

Enviar un comando a un dispositivo

Enviar un comando es similar a leer un atributo de estado de un atributo. Para encender o apagar el dispositivo, usa el OnOffTrait comando Toggle, que se define en el modelo de datos del ecosistema de Google Home como toggle(). Este método cambia onOff a false si es true o a true si es false:

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

Los comandos pueden mostrar una excepción si se detecta un problema con el flujo de ejecución. Como desarrollador, debes usar un bloque do-catch para controlar correctamente estas excepciones y mostrar información detallada a los usuarios en los casos en los que los errores sean procesables. Las excepciones no controladas detendrán el tiempo de ejecución de la app y pueden provocar fallas en ella.

Como alternativa, usa los comandos off() o on() para establecer el estado de forma explícita:

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

Después de enviar un comando para cambiar el estado, una vez que se complete, puedes leer el estado como se describe en Leer el estado de un dispositivo para controlarlo en tu app.

Enviar un comando con parámetros

Algunos comandos pueden usar parámetros, como los de OnOffTrait o LevelControlTrait:

offWithEffect

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

moveToLevel

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

Verifica si un atributo admite un atributo

Es posible que algunos dispositivos admitan un Matter atributo, pero no un atributo específico. Por ejemplo, es posible que un dispositivo Cloud-to-cloud que se asignó a Matter no admita todos los atributos de Matter. Para controlar casos como estos, usa la propiedad isSupported a nivel de atributo para verificar si se admite el atributo para un dispositivo en particular.

Por ejemplo, para verificar la compatibilidad de un dispositivo con el atributo onOff del atributo On/Off, haz lo siguiente:

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

Algunos atributos pueden aceptar valores nulos en la Matter especificación o el Cloud-to-cloud smart home esquema. Para estos atributos, puedes determinar si un valor nulo que muestra el atributo se debe a que el dispositivo no informa ese valor o si el valor del atributo es realmente nil. Para ello, usa isNullable además 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))"
      )
    }
  }
}

Actualiza los atributos de los atributos

Si deseas cambiar el valor de un atributo determinado y ninguno de los comandos del atributo lo hace, es posible que el atributo admita que su valor se establezca de forma explícita.

Si se puede cambiar el valor de un atributo, depende de dos factores:

  • ¿Se puede escribir el atributo?
  • ¿Puede cambiar el valor del atributo como efecto secundario del envío de un comando de atributo?

La documentación de referencia de los atributos y sus atributos proporciona esta información.

Por lo tanto, las combinaciones de propiedades que determinan cómo se puede cambiar el valor de un atributo son las siguientes:

  • De solo lectura y no afectado por otros comandos. Esto significa que el valor del atributo no cambia. Por ejemplo, el currentPosition atributo de la SwitchTrait.

  • De solo lectura y afectado por otros comandos. Esto significa que la única forma en que puede cambiar el valor del atributo es como resultado del envío de un comando. Por ejemplo, el currentLevel atributo de LevelControlTrait es de solo lectura, pero su valor puede mutarse con comandos como moveToLevel.

  • Se puede escribir y no se ve afectado por otros comandos. Esto significa que puedes cambiar directamente el valor del atributo con la función update del atributo, pero no hay comandos que afecten el valor del atributo. Por ejemplo, el WrongCodeEntryLimit atributo de DoorLockTrait.

  • Se puede escribir y se ve afectado por otros comandos. Esto significa que puedes cambiar directamente el valor del atributo con la función update del atributo, y el valor del atributo puede cambiar como resultado del envío de un comando. Por ejemplo, el occupiedCoolingSetpoint atributo de ThermostatTrait se puede escribir, pero también se puede actualizar con el setpointRaiseLower comando.

Ejemplo de uso de la función de actualización para cambiar el valor de un atributo

En este ejemplo, se muestra cómo establecer de forma explícita el valor del DoorLockTrait.wrongCodeEntryLimit atributo.

Para establecer un valor de atributo, llama a la función update del atributo y pásale una función de actualización que establezca el valor nuevo. Es una buena práctica primero verificar que el atributo admita un atributo.

Por ejemplo:

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