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 sifat mendukung perintah

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

Misalnya, untuk memeriksa dukungan perangkat terhadap perintah toggle fitur On/Off:

// 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 trait. Untuk mengaktifkan atau menonaktifkan perangkat, gunakan perintah OnOffTrait Toggle, yang ditentukan dalam model data ekosistem Google Home sebagai toggle(). Metode ini mengubah onOff menjadi false jika onOff adalah true, atau menjadi true jika onOff adalah false:

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

Perintah dapat 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 dalam kasus ketika 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:

// 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 karakteristik mendukung atribut

Beberapa perangkat mungkin mendukung trait 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 karakteristik untuk memeriksa apakah atribut didukung untuk perangkat tertentu.

Misalnya, untuk memeriksa dukungan perangkat terhadap atribut onOff fitur 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 dapat bernilai null dalam spesifikasi Matter atau skema Cloud-to-cloud smart home. Untuk atribut ini, Anda dapat menentukan apakah nil yang ditampilkan oleh atribut disebabkan oleh perangkat yang 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 karakteristik

Jika Anda ingin mengubah nilai atribut tertentu, dan tidak ada perintah trait yang melakukannya, atribut tersebut mungkin mendukung penetapan nilai 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 trait?

Dokumentasi referensi untuk ciri dan atributnya memberikan informasi ini.

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

• Hanya baca dan tidak terpengaruh oleh perintah lain. Artinya, nilai atribut tidak berubah. Misalnya, atribut currentPosition dari SwitchTrait.

• Hanya baca dan terpengaruh oleh perintah lain. Artinya, satu-satunya cara nilai atribut dapat berubah adalah sebagai hasil pengiriman perintah. Misalnya, atribut currentLevel dari LevelControlTrait bersifat hanya baca, tetapi nilainya dapat diubah oleh perintah seperti moveToLevel.

• Dapat ditulis dan tidak terpengaruh oleh perintah lain. Artinya, Anda dapat mengubah nilai atribut secara langsung menggunakan fungsi update dari trait, tetapi tidak ada perintah yang akan memengaruhi nilai atribut. Misalnya, atribut WrongCodeEntryLimit dari DoorLockTrait.

• Dapat ditulis dan terpengaruh oleh perintah lain. Artinya, Anda dapat mengubah nilai atribut secara langsung menggunakan fungsi update dari trait, dan nilai atribut dapat berubah sebagai hasil dari pengiriman perintah. Misalnya, atribut occupiedCoolingSetpoint dari ThermostatTrait dapat ditulis, tetapi juga diperbarui dengan perintah setpointRaiseLower.

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 trait dan teruskan fungsi update yang menetapkan nilai baru. Sebaiknya verifikasi terlebih dahulu bahwa karakteristik mendukung atribut.

Contoh:

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