在 iOS 设备上控制设备

本指南延续了 iOS 上的设备和设备元数据访问权限，并介绍了设备控制和访问的其他示例。

如需使用特定设备类型或特征，例如此处许多示例中使用的 Matter OnOffTrait，必须导入它们：

import GoogleHomeSDK
import GoogleHomeTypes

检查某个特征是否支持某个命令

使用特征级 supports 函数检查特定设备是否支持某个命令。

例如，如需检查设备是否支持“开/关”特征的 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")
}

向设备发送命令

发送命令类似于从特征读取状态属性。如需开启或关闭设备，请使用 OnOffTrait 切换命令，该命令在 Google Home 生态系统数据模型中定义为 toggle()。如果此方法为 true，则将其更改为 false；如果此方法为 false，则将其更改为 true：onOff

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

如果执行流程中检测到问题，命令可能会返回异常。作为开发者，您应使用 do-catch 块来正确处理这些异常，并在错误可操作的情况下向用户显示详细信息。未处理的异常会停止应用运行时，并可能导致应用崩溃。

或者，使用 off() 或 on() 命令明确设置状态：

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

发送更改状态的命令后，一旦命令完成，您就可以按照读取设备状态中所述读取状态，以便在应用中处理该状态。

发送带参数的命令

某些命令可能会使用参数，例如 OnOffTrait 或 LevelControlTrait 中的参数：

offWithEffect

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

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 error as HomeError {
  // Code for handling the exception
}

检查某个特征是否支持某个属性

某些设备可能支持 Matter 特征，但不支持特定属性。例如，映射到 Matter 的 Cloud-to-cloud 设备可能不支持所有 Matter 属性。为了处理此类情况，请使用特征级 isSupported 属性来检查特定设备是否支持该属性。

例如，如需检查设备是否支持 On/Off 特征的 onOff 属性，请执行以下操作：

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

某些属性在 Matter 规范或 Cloud-to-cloud smart home 架构中可为 null。对于这些属性，您可以结合使用 isNullable 和 isSupported，以确定属性返回的 nil 是因为设备未报告相应值，还是属性的值实际上为 nil：

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

更新特征属性

如果您想更改给定属性的值，但没有任何特征命令可以实现此目的，则该属性可能支持显式设置其值。

能否更改属性的值取决于以下两个因素：

  • 属性是否可写入？
  • 属性的值是否会因发送特征命令而发生变化？

有关特征及其属性的参考文档提供了此信息。

因此，决定属性值可能如何更改的属性组合如下：

使用更新函数更改属性值的示例

此示例展示了如何显式设置 DoorLockTrait.wrongCodeEntryLimit 属性的值。

如需设置属性值，请调用特征的 update 函数，并向其传递一个用于设置新值的更新函数。建议您先验证该特征是否支持某个属性。

例如：

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