iOS에서 기기 제어

이 가이드는 iOS에서 기기 및 기기 메타데이터 액세스에서 이어지며 기기 제어 및 액세스의 추가 예를 소개합니다.

여기에 있는 많은 예에서 사용되는 Matter OnOffTrait와 같은 특정 기기 유형 또는 특성을 사용하려면 가져와야 합니다.

import GoogleHomeSDK
import GoogleHomeTypes

특성이 명령어를 지원하는지 확인

특성 수준 supports 함수를 사용하여 특정 기기에 명령어가 지원되는지 확인합니다.

예를 들어 기기의 On/Off 특성 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")
}

기기에 명령어 전송

명령어를 전송하는 것은 특성에서 상태 속성을 읽는 것과 비슷합니다. 기기를 켜거나 끄려면 Google Home 생태계 데이터 모델에 toggle()로 정의된 OnOffTrait 전환 명령어를 사용합니다. 이 메서드는 onOff가 true인 경우 false로 변경하고 false인 경우 true로 변경합니다.

// 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의 명령어와 같은 매개변수를 사용할 수 있습니다.

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
}

특성이 속성을 지원하는지 확인

일부 기기는 Matter 특성을 지원하지만 특정 속성은 지원하지 않을 수 있습니다. 예를 들어 Cloud-to-cloud에 매핑된 Matter 기기는 모든 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 허용입니다. 이러한 속성의 경우 isSupported 외에 isNullable을 사용하여 속성에서 반환된 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 \(String(describing: onOffTrait.attributes.startUpOnOff))"
      )
    }
  }
}

특성 속성 업데이트

지정된 속성의 값을 변경하려고 하는데 특성의 명령어 중 어느 것도 변경하지 않는 경우 속성은 값을 명시적으로 설정하도록 지원할 수 있습니다.

속성의 값을 변경할 수 있는지 여부는 다음 두 가지 요인에 따라 달라집니다.

  • 속성을 쓸 수 있나요?
  • 특성 명령어를 전송하는 부작용으로 속성의 값이 변경될 수 있나요?

특성 및 속성의 참조 문서에서 이 정보를 제공합니다.

따라서 속성의 값이 변경되는 방식을 결정하는 속성 조합은 다음과 같습니다.

update 함수를 사용하여 속성의 값을 변경하는 예

이 예에서는 DoorLockTrait.wrongCodeEntryLimit 속성의 값을 명시적으로 설정하는 방법을 보여줍니다.

속성 값을 설정하려면 특성의 update 함수 를 호출하고 새 값을 설정하는 업데이트 함수를 전달합니다. 먼저 특성이 속성을 지원하는지 확인하는 것이 좋습니다.

예를 들면 다음과 같습니다.

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