Как управлять устройствами на 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(). Этот метод меняет значение onOff на false, если оно равно true, или на true, если оно равно false:

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

Команды могут возвращать исключение, если при выполнении обнаруживается проблема. Разработчикам следует использовать блок do-catch, чтобы правильно обрабатывать исключения и показывать пользователям подробную информацию об ошибках, которые можно исправить. Необработанные исключения останавливают выполнение приложения и могут привести к сбоям.

Вы также можете явно задать состояние с помощью команд off() или on():

do {
  try await onOffTraitTest.off()
  try await onOffTraitTest.on()
} catch let _ 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 _ 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
}

Как проверить, поддерживает ли признак атрибут

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

Некоторые атрибуты могут иметь нулевое значение в спецификации Matter или схеме Cloud-to-cloud smart home. Чтобы определить, является ли значение 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 \(String(describing: onOffTrait.attributes.startUpOnOff))"
      )
    }
  }
}

Как изменить атрибуты сегментов

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

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