Управление устройствами на 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 Toggle, которая в модели данных экосистемы Google Home определена как toggle() . Этот метод изменяет onOff на false , если оно равно true , или на true если оно равно false :

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

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

// 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 , но не поддерживать определённый атрибут. Например, устройство Cloud-to-cloud , сопоставленное с Matter , может поддерживать не все атрибуты Matter . Для обработки подобных случаев используйте свойство isSupported на уровне свойства, чтобы проверить, поддерживается ли атрибут конкретным устройством.

Например, чтобы проверить, поддерживает ли устройство атрибут 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!")
}

Некоторые атрибуты допускают значение NULL в спецификации Matter или схеме smart home Cloud-to-cloud . Для этих атрибутов можно определить, является ли возвращаемое атрибутом значение NIL следствием того, что устройство не сообщает это значение, или же значение атрибута действительно равно nil , используя isNullable в дополнение к 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 \(onOffTrait.attributes.startUpOnOff)"
      )
    }
  }
}

Обновление атрибутов черт

Если вы хотите изменить значение определенного атрибута, а ни одна из команд признака не делает этого, атрибут может поддерживать явную установку своего значения.

Возможность изменения значения атрибута зависит от двух факторов:

• Доступен ли атрибут для записи?
• Может ли значение атрибута измениться в качестве побочного эффекта отправки команды характеристики?

Эту информацию можно найти в справочной документации по признакам и их атрибутам.

Таким образом, комбинации свойств, которые определяют, как может быть изменено значение атрибута, следующие:

• Доступно только для чтения и не подвержено влиянию других команд. Это означает, что значение атрибута не изменяется. Например, атрибут currentPosition объекта SwitchTrait .

• Доступно только для чтения и может изменяться другими командами. Это означает, что значение атрибута может измениться только в результате отправки команды. Например, атрибут currentLevel объекта LevelControlTrait доступен только для чтения, но его значение можно изменить с помощью таких команд, как moveToLevel .

• Доступно для записи и не подвержено влиянию других команд. Это означает, что вы можете напрямую изменить значение атрибута, используя функцию update трейта, но нет команд, которые могли бы повлиять на значение атрибута. Например, атрибут WrongCodeEntryLimit объекта DoorLockTrait .

• Доступно для записи и воздействия другими командами. Это означает, что вы можете напрямую изменить значение атрибута, используя функцию update трейта, и значение атрибута может измениться в результате отправки команды. Например, атрибут occupiedCoolingSetpoint объекта ThermostatTrait можно записывать, а также обновлять с помощью команды setpointRaiseLower .

Пример использования функции обновления для изменения значения атрибута

В этом примере показано, как явно задать значение атрибута DoorLockTrait.wrongCodeEntryLimit .

Чтобы установить значение атрибута, вызовите функцию update трейта и передайте ей функцию обновления, которая устанавливает новое значение. Рекомендуется сначала убедиться, что трейт поддерживает атрибут .

Например:

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