Mengontrol perangkat di iOS

Panduan ini melanjutkan dari Mengakses perangkat dan metadata perangkat di iOS dan memperkenalkan contoh tambahan kontrol dan akses perangkat.

Untuk menggunakan jenis atau karakteristik perangkat tertentu, seperti Matter OnOffTrait yang digunakan dalam banyak contoh di sini, jenis atau karakteristik tersebut harus diimpor:

import GoogleHomeSDK
import GoogleHomeTypes

Memeriksa apakah suatu karakteristik mendukung perintah

Gunakan fungsi supports tingkat sifat untuk memeriksa apakah perintah didukung untuk perangkat tertentu.

Misalnya, untuk memeriksa dukungan perangkat terhadap perintah toggle sifat Aktif/Nonaktif:

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

Mengirim perintah ke perangkat

Mengirim perintah mirip dengan membaca atribut status dari sifat. Untuk mengaktifkan atau menonaktifkan perangkat, gunakan perintah Toggle OnOffTrait, yang ditentukan dalam model data ekosistem Google Home sebagai toggle(). Metode ini mengubah onOff menjadi false jika true, atau menjadi true jika false:

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

Perintah mungkin menampilkan pengecualian jika masalah terdeteksi pada alur eksekusi. Sebagai developer, Anda harus menggunakan blok do-catch untuk menangani pengecualian ini dengan benar, dan menampilkan informasi mendetail kepada pengguna jika error dapat ditindaklanjuti. Pengecualian yang tidak ditangani akan menghentikan runtime aplikasi dan dapat menyebabkan error di aplikasi Anda.

Atau, gunakan perintah off() atau on() untuk menetapkan status secara eksplisit:

do {
  try await onOffTraitTest.off()
  try await onOffTraitTest.on()
} catch let error as HomeError {
  // Code for handling the exception
}

Setelah mengirim perintah untuk mengubah status, setelah selesai, Anda dapat membaca status seperti yang dijelaskan dalam Membaca status perangkat untuk menanganinya di aplikasi Anda.

Mengirim perintah dengan parameter

Beberapa perintah dapat menggunakan parameter, seperti yang ada di OnOffTrait atau LevelControlTrait:

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

Memeriksa apakah suatu sifat mendukung atribut

Beberapa perangkat mungkin mendukung sifat Matter, tetapi tidak mendukung atribut tertentu. Misalnya, perangkat Cloud-to-cloud yang dipetakan ke Matter mungkin tidak mendukung setiap atribut Matter. Untuk menangani kasus seperti ini, gunakan properti isSupported tingkat sifat untuk memeriksa apakah atribut didukung untuk perangkat tertentu.

Misalnya, untuk memeriksa dukungan perangkat terhadap atribut onOff sifat Aktif/Nonaktif:

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

Beberapa atribut bersifat nullable dalam spesifikasi Matter atau skema Cloud-to-cloud smart home. Untuk atribut ini, Anda dapat menentukan apakah nil yang ditampilkan oleh atribut karena perangkat tidak melaporkan nilai tersebut, atau apakah nilai atribut sebenarnya adalah nil, dengan menggunakan isNullable selain 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)"
      )
    }
  }
}

Memperbarui atribut ciri

Jika Anda ingin mengubah nilai atribut tertentu, dan tidak ada perintah sifat yang melakukannya, atribut tersebut mungkin mendukung penetapan nilainya secara eksplisit.

Apakah nilai atribut dapat diubah bergantung pada dua faktor:

  • Apakah atribut dapat ditulis?
  • Dapatkah nilai atribut berubah sebagai efek samping dari pengiriman perintah sifat?

Dokumentasi referensi untuk sifat dan atributnya memberikan informasi ini.

Oleh karena itu, kombinasi properti yang menentukan cara nilai atribut dapat diubah adalah:

Contoh penggunaan fungsi update untuk mengubah nilai atribut

Contoh ini menunjukkan cara menetapkan nilai atribut DoorLockTrait.wrongCodeEntryLimit secara eksplisit.

Untuk menetapkan nilai atribut, panggil fungsi update dari sifat dan teruskan fungsi pembaruan yang menetapkan nilai baru. Sebaiknya verifikasi terlebih dahulu bahwa sifat mendukung atribut.

Contoh:

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