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 ciri perangkat tertentu, seperti Matter OnOffTrait yang digunakan dalam banyak contoh di sini, perangkat tersebut harus diimpor:

import GoogleHomeSDK
import GoogleHomeTypes

Periksa apakah suatu sifat mendukung suatu perintah

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

Misalnya, untuk memeriksa dukungan perangkat terhadap perintah toggle pada sifat Nyala/Mati:

// 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 _ 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 saat 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 _ 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 _ 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 _ as HomeError {
  // Code for handling the exception
}

Periksa apakah suatu sifat mendukung suatu 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 dari sifat Nyala/Mati:

// 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 \(String(describing: onOffTrait.attributes.startUpOnOff))"
      )
    }
  }
}

Memperbarui atribut ciri

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

Dokumentasi referensi untuk ciri dan atributnya memberikan informasi ini.

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

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

• Hanya dapat dibaca dan dipengaruhi 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. Ini berarti Anda dapat langsung mengubah nilai atribut dengan menggunakan fungsi update dari sifat tersebut, tetapi tidak ada perintah yang akan memengaruhi nilai atribut. Misalnya, atribut WrongCodeEntryLimit dari DoorLockTrait.

• Dapat ditulis dan terpengaruh oleh perintah lain. Artinya, Anda dapat langsung mengubah nilai atribut menggunakan fungsi update dari trait, dan nilai atribut dapat berubah sebagai hasil dari mengirim 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. Merupakan praktik yang baik untuk terlebih dahulu memverifikasi bahwa sifat tersebut mendukung suatu atribut.

Contoh:

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