Mengontrol perangkat

Memeriksa apakah suatu karakteristik mendukung perintah

Dukungan juga dapat diperiksa untuk perintah sifat. Gunakan juga 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 (onOffTrait.supports(OnOff.Command.Toggle)) {
  println("onOffTrait supports toggle command")
} else {
  println("onOffTrait does not support stateful toggle command")
}

Mengirim perintah ke perangkat

Mengirim perintah mirip dengan membaca atribut status dari suatu sifat. Untuk mengaktifkan atau menonaktifkan perangkat, gunakan perintah Tombol dari sifat OnOff, 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.
try {
  onOffTrait.toggle()
} catch (e: HomeException) {
  // Code for handling the exception
}

Semua perintah sifat adalah fungsi suspend dan hanya selesai saat respons ditampilkan oleh API (seperti mengonfirmasi bahwa status perangkat telah berubah). Perintah mungkin menampilkan pengecualian jika masalah terdeteksi pada alur eksekusi. Sebagai developer, Anda harus menggunakan blok try-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:

onOffTrait.off()
onOffTrait.on()

Setelah mengirim perintah untuk mengubah status, setelah selesai, Anda dapat membaca status seperti yang dijelaskan dalam Membaca status perangkat untuk menanganinya di aplikasi Anda. Atau, gunakan alur seperti yang dijelaskan dalam Mengamati status, yang merupakan metode yang lebih disukai.

Mengirim perintah dengan parameter

Beberapa perintah dapat menggunakan parameter, seperti yang ada pada sifat OnOff atau LevelControl:

// Turn off the light using the DyingLight effect.
onOffTrait.offWithEffect(
  effectIdentifier = OnOffTrait.EffectIdentifierEnum.DyingLight,
  effectVariant = 0u,
)

// Change the brightness of the light to 50%
levelControlTrait.moveToLevel(
  level = 127u.toUByte(),
  transitionTime = null,
  optionsMask = LevelControlTrait.OptionsBitmap(),
  optionsOverride = LevelControlTrait.OptionsBitmap(),
)

Beberapa perintah memiliki argumen opsional, yang muncul setelah argumen yang diperlukan.

Misalnya, perintah step untuk karakteristik FanControl memiliki dua argumen opsional:

val fanControlTraitFlow: Flow<FanControl?> =
  device.type(FanDevice).map { it.standardTraits.fanControl }.distinctUntilChanged()

val fanControl = fanControlTraitFlow.firstOrNull()

// Calling a command with optional parameters not set.
fanControl?.step(direction = FanControlTrait.StepDirectionEnum.Increase)

// Calling a command with optional parameters.
fanControl?.step(direction = FanControlTrait.StepDirectionEnum.Increase) { wrap = true }

Memeriksa apakah suatu karakteristik 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 fungsi supports tingkat sifat dan enum Attribute 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.supports(OnOff.Attribute.onOff)) {
  println("onOffTrait supports onOff state")
} else {
  println("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 null yang ditampilkan oleh atribut disebabkan oleh perangkat yang tidak melaporkan nilai tersebut, atau apakah nilai atribut sebenarnya adalah null, dengan menggunakan isNullable selain supports:

// Check if a nullable attribute is set or is not supported.
if (onOffTrait.supports(OnOff.Attribute.startUpOnOff)) {
  // The device supports startupOnOff, it is safe to expect this value in the trait.
  if (OnOff.Attribute.startUpOnOff.isNullable && onOffTrait.startUpOnOff == null) {
    // This value is nullable and set to null. Check the specification as to
    // what null in this case means
    println("onOffTrait supports startUpOnOff and it is null")
  } else {
    // This value is nullable and set to a value.
    println("onOffTrait supports startUpOnOff and it is set to ${onOffTrait.startUpOnOff}")
  }
} else {
  println("onOffTrait does not support 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 karakteristik 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. Ini berarti nilai atribut tidak berubah. Misalnya, atribut currentPosition dari sifat Switch.

• Hanya baca dan dipengaruhi oleh perintah lain. Artinya, satu-satunya cara nilai atribut dapat berubah adalah sebagai hasil dari pengiriman perintah. Misalnya, atribut currentLevel dari sifat Matter LevelControl hanya dapat dibaca, 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 sifat, tetapi tidak ada perintah yang akan memengaruhi nilai atribut. Misalnya, atribut WrongCodeEntryLimit dari sifat DoorLock.

• Dapat ditulis dan dipengaruhi oleh perintah lain. Artinya, Anda dapat mengubah nilai atribut secara langsung menggunakan fungsi update dari sifat, dan nilai atribut dapat berubah sebagai hasil dari pengiriman perintah. Misalnya, atribut occupiedCoolingSetpoint dari sifat Thermostat 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 dari sifat dan teruskan fungsi pengubah yang menetapkan nilai baru. Sebaiknya verifikasi terlebih dahulu bahwa atribut mendukung atribut.

Contoh:

    var doorLockDevice = home.devices().list().first { device -> device.has(DoorLock) }

    val traitFlow: Flow<DoorLock?> =
      doorLockDevice.type(DoorLockDevice).map { it.standardTraits.doorLock }.distinctUntilChanged()

    val doorLockTrait: DoorLock = traitFlow.first()!!

    if (doorLockTrait.supports(DoorLock.Attribute.wrongCodeEntryLimit)) {
      val unused = doorLockTrait.update { setWrongCodeEntryLimit(3u) }
    }