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

デバイスにコマンドを送信する

コマンドの送信は、トレイトから状態属性を読み取るのと似ています。デバイスのオン / オフを切り替えるには、Google Home エコシステムのデータモデルで toggle() として定義されている OnOffTraitToggle コマンドを使用します。このメソッドは、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 プロパティを使用して、特定のデバイスで属性がサポートされているかどうかを確認します。

たとえば、オン/オフ トレイトの 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))"
      )
    }
  }
}

トレイト属性を更新する

特定の属性の値を変更したいが、トレイトのコマンドでは変更できない場合、その属性は値を明示的に設定できる可能性があります。

属性の値を変更できるかどうかは、次の 2 つの要因によって異なります。

  • 属性は書き込み可能か？
  • トレイト コマンドの送信の副作用として、属性の値を変更できるか？

トレイトとその属性のリファレンス ドキュメントには、この情報が記載されています。

したがって、属性の値を変更する方法を決定するプロパティの組み合わせは次のとおりです。

update 関数を使用して属性の値を変更する例

この例では、 DoorLockTrait.wrongCodeEntryLimit 属性の値を明示的に設定する方法を示します。

属性値を設定するには、トレイトの update関数 を呼び出し、新しい値を設定する更新関数を渡します。最初に、トレイトが属性をサポートしていることを まず 確認することをおすすめします。

次に例を示します。

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