iOS에서 기기 제어

bookmark_border 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 가이드는 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")
}

기기에 명령어 전송

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

// 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 트레잇은 지원하지만 특정 속성은 지원하지 않을 수 있습니다. 예를 들어 Matter에 매핑된 Cloud-to-cloud 기기는 모든 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 스키마에서 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 \(onOffTrait.attributes.startUpOnOff)"
      )
    }
  }
}

트레잇 속성 업데이트

특정 속성의 값을 변경하려고 하는데 트레잇의 명령어 중에서 이를 실행하는 명령어가 없는 경우 속성이 값을 명시적으로 설정하는 것을 지원할 수 있습니다.

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

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

트레잇 및 속성에 관한 참조 문서에서 이 정보를 확인할 수 있습니다.

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

• 읽기 전용이며 다른 명령어의 영향을 받지 않습니다. 즉, 속성 값은 변경되지 않습니다. 예를 들어 SwitchTrait의 currentPosition 속성

• 읽기 전용이며 다른 명령어의 영향을 받습니다. 즉, 명령어를 전송한 결과로만 속성 값이 변경될 수 있습니다. 예를 들어 LevelControlTrait의 currentLevel 속성은 읽기 전용이지만 moveToLevel와 같은 명령어를 사용하여 값을 변경할 수 있습니다.

• 쓰기가 가능하며 다른 명령어의 영향을 받지 않습니다. 즉, 트레잇의 update 함수를 사용하여 속성 값을 직접 변경할 수 있지만 속성 값에 영향을 미치는 명령어는 없습니다. 예를 들어 DoorLockTrait의 WrongCodeEntryLimit 속성

• 쓰기가 가능하며 다른 명령어의 영향을 받습니다. 즉, 트레잇의 update 함수를 사용하여 속성 값을 직접 변경할 수 있으며, 명령어를 전송하면 속성 값이 변경될 수 있습니다. 예를 들어 ThermostatTrait의 occupiedCoolingSetpoint 속성은 쓰거나 setpointRaiseLower 명령어를 사용하여 업데이트할 수 있습니다.

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

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

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

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

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