Android डिवाइसों को कंट्रोल करना

यह देखना कि कोई trait किसी निर्देश के साथ काम करता है या नहीं

ट्रेट कमांड के लिए भी सहायता देखी जा सकती है. इसके अलावा, trait-level supports फ़ंक्शन का इस्तेमाल करके देखें कि किसी डिवाइस के लिए कोई निर्देश काम करता है या नहीं.

उदाहरण के लिए, यह देखने के लिए कि कोई डिवाइस, On/Off trait के toggle कमांड के साथ काम करता है या नहीं:

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

किसी डिवाइस को निर्देश भेजना

निर्देश भेजना, किसी ट्रेट से स्टेट एट्रिब्यूट को पढ़ने जैसा ही है. डिवाइस को चालू या बंद करने के लिए, OnOff ट्रेट के टॉगल कमांड का इस्तेमाल करें. इसे Google Home नेटवर्क के डेटा मॉडल में toggle() के तौर पर तय किया गया है. यह तरीका onOff को false में बदल देता है, अगर यह true है या true में बदल देता है, अगर यह false है:

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

सभी trait commands, suspend फ़ंक्शन होते हैं और ये सिर्फ़ तब पूरे होते हैं, जब एपीआई से कोई response मिलता है. जैसे, device state के बदलने की पुष्टि करना. अगर एक्ज़ीक्यूशन फ़्लो में कोई समस्या मिलती है, तो हो सकता है कि कमांड से कोई अपवाद मिले. डेवलपर के तौर पर, आपको इन अपवादों को ठीक से मैनेज करने के लिए, try-catch ब्लॉक का इस्तेमाल करना चाहिए. साथ ही, उन मामलों में उपयोगकर्ताओं को पूरी जानकारी देनी चाहिए जिनमें गड़बड़ियों को ठीक किया जा सकता है. अनहैंडल्ड एक्सेप्शन की वजह से, ऐप्लिकेशन का रनटाइम रुक जाएगा और आपका ऐप्लिकेशन क्रैश हो सकता है.

इसके अलावा, स्थिति को साफ़ तौर पर सेट करने के लिए, off() या on() कमांड का इस्तेमाल करें:

onOffTrait.off()
onOffTrait.on()

स्थिति बदलने के लिए निर्देश भेजने के बाद, जब यह पूरा हो जाए, तब डिवाइस की स्थिति पढ़ें में बताए गए तरीके से स्थिति को पढ़ा जा सकता है. इससे आपको अपने ऐप्लिकेशन में इसे मैनेज करने में मदद मिलेगी. इसके अलावा, स्थिति देखें में बताए गए फ़्लो का इस्तेमाल करें. यह सबसे सही तरीका है.

पैरामीटर के साथ कोई निर्देश भेजना

कुछ निर्देश, पैरामीटर का इस्तेमाल कर सकते हैं. जैसे, OnOff या 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(),
)

कुछ निर्देशों में वैकल्पिक आर्ग्युमेंट होते हैं. ये ज़रूरी आर्ग्युमेंट के बाद आते हैं.

उदाहरण के लिए, FanControl trait के लिए step कमांड में दो वैकल्पिक आर्ग्युमेंट होते हैं:

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 }

उदाहरण के लिए, यह देखने के लिए कि कोई डिवाइस, On/Off trait की onOff विशेषता के साथ काम करता है या नहीं:

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

Matter स्पेसिफ़िकेशन या Cloud-to-cloud smart home स्कीमा में, कुछ एट्रिब्यूट की वैल्यू शून्य हो सकती है. इन एट्रिब्यूट के लिए, यह तय किया जा सकता है कि एट्रिब्यूट से मिली null वैल्यू, डिवाइस की ओर से उस वैल्यू को रिपोर्ट न करने की वजह से है या एट्रिब्यूट की वैल्यू असल में null है. इसके लिए, supports के साथ-साथ isNullable का इस्तेमाल करें:

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

ट्रेट एट्रिब्यूट अपडेट करना

अगर आपको किसी एट्रिब्यूट की वैल्यू बदलनी है और ट्रेट का कोई भी निर्देश ऐसा नहीं करता है, तो हो सकता है कि एट्रिब्यूट की वैल्यू को साफ़ तौर पर सेट किया जा सके.

किसी एट्रिब्यूट की वैल्यू बदली जा सकती है या नहीं, यह दो बातों पर निर्भर करता है:

• क्या एट्रिब्यूट में बदलाव किया जा सकता है?
• क्या trait कमांड भेजने से, एट्रिब्यूट की वैल्यू बदल सकती है?

ट्रेट और उनके एट्रिब्यूट के रेफ़रंस दस्तावेज़ में यह जानकारी दी गई है.

इसलिए, किसी एट्रिब्यूट की वैल्यू में बदलाव करने के तरीके को तय करने वाली प्रॉपर्टी के कॉम्बिनेशन ये हैं:

• यह सिर्फ़ पढ़ने के लिए है और इस पर अन्य कमांड का कोई असर नहीं पड़ता. इसका मतलब है कि एट्रिब्यूट की वैल्यू नहीं बदलती. उदाहरण के लिए, Switch ट्रेट का currentPosition एट्रिब्यूट.

• सिर्फ़ पढ़ने के लिए और अन्य कमांड से असर पड़ता है. इसका मतलब है कि एट्रिब्यूट की वैल्यू सिर्फ़ तब बदल सकती है, जब कोई निर्देश भेजा जाए. उदाहरण के लिए, LevelControl Matter trait का currentLevel एट्रिब्यूट रीड-ओनली है, लेकिन इसकी वैल्यू को moveToLevel जैसे कमांड से बदला जा सकता है.

• इसमें डेटा लिखा जा सकता है और अन्य कमांड का इस पर कोई असर नहीं पड़ता. इसका मतलब है कि trait के update फ़ंक्शन का इस्तेमाल करके, एट्रिब्यूट की वैल्यू को सीधे तौर पर बदला जा सकता है. हालांकि, ऐसे कोई निर्देश नहीं हैं जिनसे एट्रिब्यूट की वैल्यू पर असर पड़े. उदाहरण के लिए, DoorLock ट्रेट का WrongCodeEntryLimit एट्रिब्यूट.

• इसमें बदलाव किया जा सकता है और अन्य कमांड का इस पर असर पड़ता है. इसका मतलब है कि विशेषता के update फ़ंक्शन का इस्तेमाल करके, एट्रिब्यूट की वैल्यू को सीधे तौर पर बदला जा सकता है. साथ ही, कोई निर्देश भेजने पर एट्रिब्यूट की वैल्यू बदल सकती है. उदाहरण के लिए, FanControlTrait के speedSetting एट्रिब्यूट को सीधे तौर पर लिखा जा सकता है. हालांकि, step कमांड का इस्तेमाल करके भी इसमें बदलाव किया जा सकता है.

किसी एट्रिब्यूट की वैल्यू बदलने के लिए, अपडेट फ़ंक्शन का इस्तेमाल करने का उदाहरण

इस उदाहरण में, DoorLockTrait.WrongCodeEntryLimit एट्रिब्यूट की वैल्यू को साफ़ तौर पर सेट करने का तरीका बताया गया है.

किसी एट्रिब्यूट की वैल्यू सेट करने के लिए, ट्रेट के update फ़ंक्शन को कॉल करें. साथ ही, उसे एक म्यूटेटर फ़ंक्शन पास करें, जो नई वैल्यू सेट करता है. सबसे पहले, यह पुष्टि करना ज़रूरी है कि trait किसी attribute के साथ काम करता है या नहीं.

उदाहरण के लिए:

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

एक साथ कई निर्देश भेजना

Batching API की मदद से, क्लाइंट एक ही पेलोड में Home API के कई डिवाइस कमांड भेज सकता है. निर्देशों को एक ही पेलोड में बैच किया जाता है और एक साथ लागू किया जाता है. यह ठीक उसी तरह है जैसे कोई व्यक्ति पैरलल नोड का इस्तेमाल करके, Home API ऑटोमेशन बना सकता है. जैसे, सूर्योदय से पहले ब्लाइंड खोलना. हालांकि, Batching API, Automation API की तुलना में ज़्यादा जटिल और बेहतर तरीके से काम करता है. जैसे, किसी भी शर्त के हिसाब से रनटाइम के दौरान डिवाइसों को डाइनैमिक तौर पर चुनने की सुविधा.

एक बैच में मौजूद निर्देश, कई डिवाइसों पर मौजूद कई विशेषताओं को टारगेट कर सकते हैं. ये डिवाइस, अलग-अलग कमरों और अलग-अलग स्ट्रक्चर में मौजूद हो सकते हैं.

एक साथ कई निर्देश भेजने पर, डिवाइस एक साथ कई कार्रवाइयां कर सकते हैं. हालांकि, अलग-अलग अनुरोधों में क्रम से निर्देश भेजने पर ऐसा नहीं किया जा सकता. बैच में दिए गए निर्देशों का इस्तेमाल करके, डेवलपर डिवाइसों के ग्रुप की स्थिति को पहले से तय की गई कुल स्थिति से मैच करने के लिए सेट कर सकता है.

Batching API का इस्तेमाल करना

Batching API के ज़रिए कमांड को शुरू करने के लिए, तीन बुनियादी चरण शामिल हैं:

1. Home.sendBatchedCommands() तरीके को शुरू करें.
2. sendBatchedCommands() ब्लॉक के मुख्य हिस्से में, बैच में शामिल किए जाने वाले कमांड की जानकारी दें.
3. भेजे गए निर्देशों के नतीजे देखें, ताकि पता चल सके कि वे सफल हुए या नहीं.

एक साथ कई निर्देश भेजना

Home.sendBatchedCommands() तरीके को कॉल करें. बैकग्राउंड में, यह तरीका एक खास बैच कॉन्टेक्स्ट में लैम्ब्डा एक्सप्रेशन सेट अप करता है.

home.sendBatchedCommands() {

बैच के लिए निर्देश तय करना

sendBatchedCommands() ब्लॉक के मुख्य हिस्से में, बैच किए जा सकने वाले कमांड भरें. बैच किए जा सकने वाले निर्देश, मौजूदा Device API के निर्देशों के "शैडो" वर्शन होते हैं. इनका इस्तेमाल बैच के संदर्भ में किया जा सकता है. इनके नाम के आखिर में Batchable जोड़ा जाता है. उदाहरण के लिए, LevelControl ट्रेट के moveToLevel() कमांड का एक काउंटरपार्ट है, जिसका नाम moveToLevelBatchable() है.

उदाहरण:

  val response1 = add(command1)

  val response2 = add(command2)

बैच के कॉन्टेक्स्ट में सभी कमांड जोड़ने और एक्ज़ीक्यूशन के कॉन्टेक्स्ट से बाहर निकलने के बाद, बैच अपने-आप भेज दिया जाता है.

जवाबों को DeferredResponse<T> ऑब्जेक्ट में कैप्चर किया जाता है.

DeferredResponse<T> के इंस्टेंस को किसी भी तरह के ऑब्जेक्ट में इकट्ठा किया जा सकता है. जैसे, Collection या आपकी तय की गई डेटा क्लास. जवाबों को इकट्ठा करने के लिए, आपने जिस तरह का ऑब्जेक्ट चुना है, sendBatchedCommands() वही ऑब्जेक्ट दिखाता है. उदाहरण के लिए, बैच कॉन्टेक्स्ट, Pair में DeferredResponse के दो इंस्टेंस दिखा सकता है:

  val (response1, response2) = homeClient.sendBatchedComamnds {
    val response1 = add(someCommandBatched(...))
    val response2 = add(someOtherCommandBatched(...))
    Pair(response1, response2)
  }

इसके अलावा, बैच कॉन्टेक्स्ट, कस्टम डेटा क्लास में DeferredResponse के इंस्टेंस दिखा सकता है:

  // Custom data class
  data class SpecialResponseHolder(
    val response1: DeferredResponse<String>,
    val response2: DeferredResponse<Int>,
    val other: OtherResponses
  )
  data class OtherResponses(...)

हर जवाब की जांच करना

sendBatchedCommands() ब्लॉक के बाहर, जवाबों की जांच करके पता लगाएं कि उससे जुड़ा निर्देश पूरा हुआ या नहीं. इसके लिए, DeferredResponse.getOrThrow() को कॉल किया जाता है. इससे: - एग्ज़िक्यूट किए गए कमांड का नतीजा मिलता है, - या अगर बैच स्कोप पूरा नहीं हुआ है या कमांड पूरा नहीं हुआ है, तो गड़बड़ी का मैसेज दिखता है.

आपको सिर्फ़ sendBatchedCommands() लैम्ब्डा स्कोप के बाहर के नतीजे देखने चाहिए.

उदाहरण

मान लें कि आपको एक ऐसा ऐप्लिकेशन बनाना है जो Batching API का इस्तेमाल करके, 'गुड नाइट' सीन सेट अप करता हो. यह सीन, घर के सभी डिवाइसों को रात के समय के लिए कॉन्फ़िगर करता है, जब सभी लोग सो रहे होते हैं. इस ऐप्लिकेशन को लाइटें बंद करनी चाहिए और आगे और पीछे के दरवाज़े लॉक करने चाहिए.

इस टास्क को पूरा करने का एक तरीका यहां बताया गया है:

val lightDevices: List<OnOffLightDevice>
val doorlockDevices: List<DoorLockDevice>

// Send all the commands
val responses: List<DeferredResponse<Unit>> = home.sendBatchedCommands {
  // For each light device, send a Batchable command to turn it on
  val lightResponses: List<DeferredResponse<Unit>> = lightDevices.map { lightDevice ->
    add(lightDevice.standardTraits.onOff.onBatchable())
  }

  // For each doorlock device, send a Batchable command to lock it
  val doorLockResponse: List<DeferredResponse<Unit>> = doorlockDevices.map { doorlockDevice ->
    add(doorlockDevice.standardTraits.doorLock.lockDoorBatchable())
  }

  lightResponses + doorLockResponses
}

// Check that all responses were successful
for (response in responses) {
  response.getOrThrow()
}