Cihazları kontrol edin

Bir özelliğin komutu destekleyip desteklemediğini kontrol etme

Özellik komutu için destek de kontrol edilebilir. Bir komutun belirli bir cihazda desteklenip desteklenmediğini kontrol etmek için özellik düzeyindeki supports işlevini de kullanın.

Örneğin, bir cihazın Açık/Kapalı özelliğinin toggle komutunu destekleyip desteklemediğini kontrol etmek için:

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

Bir cihaza komut gönderme

Komut gönderme, bir özellikten durum özelliğini okumaya benzer. Cihazı açmak veya kapatmak için OnOff özelliğinin açma/kapatma komutunu kullanın. Bu komut, Google Home ekosistemi veri modelinde toggle() olarak tanımlanır. Bu yöntem, onOff değeri true ise false olarak, false ise true olarak değiştirir:

// Calling a command on a trait.
try {
  onOffTrait.toggle()
} catch (e: HomeException) {
  // Code for handling the exception
}

Tüm özellik komutları suspend işlevleridir ve yalnızca API tarafından bir yanıt döndürüldüğünde (ör. cihaz durumunun değiştiğini onaylama) tamamlanır. Komutlar, yürütme akışında bir sorun algılanırsa istisna döndürebilir. Geliştirici olarak, bu istisnaları düzgün bir şekilde işlemek için bir try-catch bloğu kullanmalı ve hataların işlem yapılabilir olduğu durumlarda kullanıcılara ayrıntılı bilgiler sunmalısınız. İşlenmeyen istisnalar, uygulama çalışma zamanını durdurur ve uygulamanızda kilitlenmelere neden olabilir.

Alternatif olarak, durumu açıkça ayarlamak için off() veya on() komutlarını kullanın:

onOffTrait.off()
onOffTrait.on()

Durumu değiştirmek için bir komut gönderdikten sonra, komut tamamlandığında Cihaz durumunu okuma bölümünde açıklandığı gibi durumu okuyarak uygulamanızda kullanabilirsiniz. Alternatif olarak, tercih edilen yöntem olan Durumu gözlemleme bölümünde açıklandığı gibi akışları kullanabilirsiniz.

Parametrelerle komut gönderme

Bazı komutlar, OnOff veya LevelControl özelliklerindeki gibi parametreler kullanabilir:

// 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(),
)

Bazı komutlarda, gerekli bağımsız değişkenlerden sonra gelen isteğe bağlı bağımsız değişkenler bulunur.

Örneğin, FanControl özelliği için step komutu iki isteğe bağlı bağımsız değişkene sahiptir:

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 }

Örneğin, bir cihazın Açık/Kapalı özelliğinin onOff özelliğini destekleyip desteklemediğini kontrol etmek için:

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

Bazı özellikler Matter spesifikasyonunda veya Cloud-to-cloud smart home şemasında boş değer alabilir. Bu özellikler için, supports'e ek olarak isNullable kullanarak özelliğin döndürdüğü null değerinin cihazın bu değeri bildirmemesi mi yoksa özelliğin değerinin aslında null olması mı olduğunu belirleyebilirsiniz:

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

Özellik özelliklerini güncelleme

Belirli bir özelliğin değerini değiştirmek istiyorsanız ve özelliğin komutlarından hiçbiri bunu yapmıyorsa özellik, değerinin açıkça ayarlanmasını destekleyebilir.

Bir özelliğin değerinin değiştirilip değiştirilemeyeceği iki faktöre bağlıdır:

• Özellik yazılabilir mi?
• Özelliğin değeri, özellik komutu göndermenin bir yan etkisi olarak değişebilir mi?

Bu bilgiler, özellikler ve özelliklerine ilişkin referans dokümanlarında sağlanır.

Bu nedenle, bir özelliğin değerinin nasıl değiştirilebileceğini belirleyen özellik kombinasyonları şunlardır:

• Salt okunurdur ve diğer komutlardan etkilenmez. Bu, özelliğin değerinin değişmediği anlamına gelir. Örneğin, Switch özelliğinin currentPosition özelliği.

• Salt okunur ve diğer komutlardan etkilenir. Bu, özelliğin değerinin yalnızca bir komut gönderilmesi sonucunda değişebileceği anlamına gelir. Örneğin, LevelControl Matter özelliğinin currentLevel özelliği salt okunurdur ancak değeri moveToLevel gibi komutlarla değiştirilebilir.

• Yazılabilir ve diğer komutlardan etkilenmez. Bu, özelliğin update işlevini kullanarak özelliğin değerini doğrudan değiştirebileceğiniz anlamına gelir. Ancak özelliğin değerini etkileyecek komut yoktur. Örneğin, DoorLock özelliğinin WrongCodeEntryLimit özelliği.

• Yazılabilir ve diğer komutlardan etkilenir. Bu, özelliğin update işlevini kullanarak özelliğin değerini doğrudan değiştirebileceğiniz ve bir komut gönderilmesi sonucunda özelliğin değerinin değişebileceği anlamına gelir. Örneğin, Thermostat özelliğinin occupiedCoolingSetpoint özelliği yazılabilir ancak setpointRaiseLower komutuyla de güncellenebilir.

Bir özelliğin değerini değiştirmek için update işlevinin kullanıldığı örnek

Bu örnekte, DoorLockTrait.WrongCodeEntryLimit özelliğinin değerinin nasıl açıkça ayarlanacağı gösterilmektedir.

Bir özellik değerini ayarlamak için özelliğin update işlevini çağırın ve işleve yeni değeri ayarlayan bir değiştirici işlev aktarın. Öncelikle özelliğin bir özelliği destekleyip desteklemediğini doğrulamak iyi bir uygulamadır.

Örneğin:

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