Android पर Automation API की खास जानकारी

ऑटोमेशन की मदद से, होम में मौजूद डिवाइसों की सेटिंग और टास्क को ऑटोमेट किया जा सकता है. Google Home के नेटवर्क में, ऑटोमेशन की सुविधा Google Home app (GHA) में रूटीन के तौर पर उपलब्ध है. साथ ही, Google Home for web को automation script editor के ज़रिए भी यह सुविधा उपलब्ध कराई गई है.

अब Google Home नेटवर्क में ऑटोमेशन की सुविधा, Android के लिए Home API के ज़रिए उपलब्ध है. ये GHA रूटीन और script editor में इस्तेमाल किए गए बुनियादी कॉन्सेप्ट का इस्तेमाल करते हैं. हालांकि, इनमें बेहतर सुविधाएं और क्षमताएं होती हैं, जो सिर्फ़ Home API के ज़रिए ही संभव हैं. इनमें ये शामिल हैं:

• Home API में मौजूद, किसी डिवाइस के लिए सभी Matter स्टैंडर्ड और smart home ट्रेट का ऐक्सेस.
• क्रम में, एक साथ, और चुनिंदा तरीके से एक्ज़ीक्यूशन फ़्लो के लिए सहायता.

ऑटोमेशन, ऑटोमेशन डीएसएल का इस्तेमाल करके लिखे जाते हैं. यह Kotlin में ऑटोमेशन बनाने के लिए डिज़ाइन की गई डोमेन-स्पेसिफ़िक लैंग्वेज है.

Device & Structure या Automation API के साथ, अपने ऐप्लिकेशन में इस्तेमाल की जाने वाली सभी विशेषताओं और टाइप को शुरू में ही रजिस्टर करना ज़रूरी है. Android पर होम को शुरू करना देखें.

अगर उपयोगकर्ता सभी अनुमतियां वापस ले लेता है, तो उसके लिए दिशा-निर्देश

अगर उपयोगकर्ता सभी अनुमतियां वापस ले लेता है, तो मौजूदा ऑटोमेशन काम करना बंद कर देंगे. इसके अलावा, अगर उपयोगकर्ता कुछ डिवाइसों का ऐक्सेस वापस ले लेता है, तो उन डिवाइसों से जुड़े स्टार्टर, शर्तें, और कार्रवाइयां काम करना बंद कर देंगी.

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

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

डेवलपर की यात्रा

ऑटोमेशन एपीआई, डेवलपमेंट की बड़ी प्रोसेस का एक हिस्सा है. यह स्ट्रक्चर और डिवाइस एपीआई को इंटिग्रेट करने के बाद आता है, ताकि यह पक्का किया जा सके कि जब कोई उपयोगकर्ता ऑटोमेशन का इस्तेमाल करना चाहे, तो वह ऐसा कर सके.

1. डेवलपर, ऑटोमेशन की योजना बनाता है और ऑटोमेशन डीएसएल का इस्तेमाल करके इसे तय करता है.
2. डेवलपर, Kotlin Android ऐप्लिकेशन में ऑटोमेशन की परिभाषा को एम्बेड करता है.
3. यह ऐप्लिकेशन, उपयोगकर्ता को उसके डिवाइसों की जानकारी के आधार पर ऑटोमेशन दिखाता है. इसमें Discovery API या Device API का इस्तेमाल करके इकट्ठा की गई जानकारी शामिल होती है. जैसे, डिवाइसों की विशेषताएं, एट्रिब्यूट, निर्देश, और इवेंट.
   1. Discovery API की मदद से, ऐप्लिकेशन उपयोगकर्ता के होम स्ट्रक्चर में मौजूद डिवाइस टाइप और विशेषताओं के हिसाब से, ऑटोमेशन का ड्राफ़्ट जनरेट कर सकता है. इसके लिए, उपयोगकर्ता के इनपुट की ज़रूरत नहीं होती.
   2. Device API, Discovery API की तरह ही ज़्यादातर जानकारी दे सकता है. हालांकि, इसे ऑटोमेशन के इस्तेमाल के उदाहरणों के लिए ऑप्टिमाइज़ नहीं किया गया है. ज़्यादा जानकारी के लिए, Device API और Discovery API की तुलना करना लेख पढ़ें.
4. ऐप्लिकेशन, असल ऑटोमेशन बनाता है. यह ऑटोमेशन, चुनी गई होम स्ट्रक्चर के हिसाब से काम करता है.
5. अब ऑटोमेशन की सुविधा, उपयोगकर्ता के स्ट्रक्चर में उपलब्ध है. इसे स्ट्रक्चर एपीआई के तरीकों का इस्तेमाल करके, लागू किया जा सकता है या मिटाया जा सकता है.

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

सबसे बुनियादी स्थिति में, उपयोगकर्ताओं को पहले से तय किए गए ऑटोमेशन का सुझाव दिया जा सकता है. यह ऑटोमेशन, बुनियादी टास्क को पूरा करता है. इसके अलावा, ऑटोमेशन का एक स्केलेटन भी दिखाया जा सकता है. उपयोगकर्ता अपनी ज़रूरत के हिसाब से इसे कस्टमाइज़ कर सकता है. इसके अलावा, ओपन-एंडेड ऑटोमेशन एडिटर भी बनाया जा सकता है. इससे उपयोगकर्ता, ऑटोमेशन एपीआई में उपलब्ध सभी बिल्डिंग ब्लॉक का इस्तेमाल करके, जटिल ऑटोमेशन बना सकता है.

ऑटोमेशन के सुझाव

   Android के लिए सैंपल के तौर पर मिले ऐप्लिकेशन में लागू किया गया   

होम एपीआई, Structure के लिए ऑटोमेशन के सुझाव दे सकते हैं. ये सुझाव, स्पेस में मौजूद डिवाइसों के टाइप जैसे फ़ैक्टर के आधार पर दिए जाते हैं.

ऑटोमेशन के सुझावों को AutomationSuggestion क्लास से दिखाया जाता है.

Structure इंटरफ़ेस में HasSuggestions इंटरफ़ेस शामिल होता है. यह suggestions() फ़ंक्शन उपलब्ध कराता है, जो ऑटोमेशन के सुझावों का कलेक्शन दिखाता है.

likeSuggestion() और dislikeSuggestion() तरीकों को thumb_up और thumb_down यूज़र इंटरफ़ेस (यूआई) कंट्रोल से कनेक्ट किया जाता है. उपयोगकर्ता इन पर टैप करके, सुझाव/राय दे सकता है या शिकायत कर सकता है.

तीसरा तरीका, clearSuggestionFeedback(), उपयोगकर्ता को सुझाए गए ऑटोमेशन के लिए दिए गए सुझाव/राय को हटाने की अनुमति देता है.

उपयोगकर्ता के सुझाव, शिकायत या राय से, आने वाले समय में मिलने वाले सुझावों पर असर पड़ता है.

इस उदाहरण से पता चलता है कि किसी Structure के लिए, ऑटोमेशन के उपलब्ध सुझावों को कैसे वापस लाया जा सकता है. साथ ही, सुझाव का आईडी कैसे निकाला जा सकता है और likeSuggestion(), clearSuggestionFeedback(), और dislikeSuggestion() का इस्तेमाल करके, उपयोगकर्ता के सुझाव, शिकायत या राय को कैसे रिकॉर्ड किया जा सकता है.

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.home.Structure
import kotlinx.coroutines.launch

class AutomationSuggestionsViewModel(private val structure: Structure) : ViewModel() {

  fun loadAndGiveFeedback() {
    viewModelScope.launch {
      // 1. Fetch suggestions from structure
      val suggestions = structure.suggestions()
      val firstSuggestion = suggestions.firstOrNull() ?: return@launch

      // Extract string suggestion ID
      val suggestionId: String = firstSuggestion.id.id

      // 2. Like the suggestion (thumbs up)
      val liked = structure.likeSuggestion(suggestionId)

      // 3. Clear previous feedback if the user toggled it off
      if (liked) {
        structure.clearSuggestionFeedback(suggestionId)
      }

      // 4. Dislike the suggestion (thumbs down)
      structure.dislikeSuggestion(suggestionId)
    }
  }
}

डाइनैमिक कमांड पैरामीटर

डाइनैमिक कमांड पैरामीटर की मदद से, डेवलपर ऐसे ऐक्शन पैरामीटर बना सकते हैं जो स्टैटिक और कॉन्स्टेंट वैल्यू पर निर्भर रहने के बजाय, रनटाइम के दौरान डाइनैमिक तौर पर रिज़ॉल्व होते हैं. इससे ये दो मुख्य काम किए जा सकते हैं:

• ऐसे रेफ़रंस जो किसी स्टार्टर (जैसे, इवेंट पेलोड) या स्टेट रीडर नोड से या ऑटोमेशन फ़्लो में बताए गए लोकल वैरिएबल से किसी प्रॉपर्टी की वैल्यू पास करते हैं.
• ऐसे एक्सप्रेशन जो रनटाइम डाइनैमिक वैल्यू (जैसे, इवेंट प्रॉपर्टी या स्टेट वैल्यू) को कैप्चर करते हैं और डाइनैमिक वैल्यू को सीधे कमांड पैरामीटर में पास करते हैं.

इस्तेमाल का उदाहरण

रोटरी स्विच को डिम की जा सकने वाली लाइट से बाइंड करें. यह स्विच, कई बार दबाने पर इवेंट भेजता है. क्लिक की संख्या, रनटाइम के दौरान LevelControl स्टेप कमांड में पास की गई डाइनैमिक वैल्यू होती है.

डाइनैमिक पैरामीटर कैसे काम करते हैं

Android पर ऑटोमेशन डीएसएल में, कमांड पैरामीटर स्टैटिक कॉन्स्टेंट वैल्यू के बजाय, सीधे तौर पर Expression या Reference इंस्टेंस स्वीकार करते हैं. ऑटोमेशन बनाते समय, डीएसएल इन्हें Parameter डेफ़िनिशन में शामिल करता है.

सत्यापन नियम

डाइनैमिक कमांड पैरामीटर, पुष्टि करने से जुड़ी इन पाबंदियों का पालन करते हैं:

• डिस्कवरी के दौरान, डायनैमिक पैरामीटर को स्ट्रक्चर के हिसाब से मान्य माना जाता है. ऐसा इसलिए, क्योंकि डिस्कवरी एपीआई सिर्फ़ स्टैटिक आर्ग्युमेंट के लिए, ठोस वैल्यू की सीमाओं का आकलन करते हैं.
• रेफ़रंस या एक्सप्रेशन नोड, ऑटोमेशन ग्राफ़ में अपस्ट्रीम में दिखने चाहिए. इसके बाद ही, उन्हें डाउनस्ट्रीम कमांड ऐक्शन में रेफ़रंस के तौर पर इस्तेमाल किया जा सकता है.

Android पर डाइनैमिक कमांड पैरामीटर इस्तेमाल करना

कमांड पैरामीटर में डाइनैमिक एक्सप्रेशन सीधे तौर पर पास करें:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val keypressAutomation = automation {
  name = "Dynamic command parameters example"
  description = "Pass starter event field directly to command"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountExpr,
        )
      )
    }
  }
}

इसके अलावा, किसी लोकल वैरिएबल के एलान के लिए कोई एक्सप्रेशन असाइन करें और फ़्लो में बाद में वैरिएबल का रेफ़रंस दें:

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.fieldSelect
import com.google.home.automation.sequential
import com.google.home.automation.starter
import com.google.home.automation.variable
import com.google.home.matter.standard.DimmableLightDevice
import com.google.home.matter.standard.DimmerSwitchDevice
import com.google.home.matter.standard.LevelControl
import com.google.home.matter.standard.LevelControlTrait.StepModeEnum
import com.google.home.matter.standard.Switch

val myAutomationWithVariable = automation {
  name = "Dynamic command parameters with variables"
  description = "Declare a variable, assign value, and pass reference"
  sequential {
    val dimmerStarter = starter(
      dimmerSwitch,
      DimmerSwitchDevice,
      Switch.MultiPressOngoingEvent,
    )

    val clickCountExpr = fieldSelect<Switch.MultiPressOngoingEvent, UInt>(
      dimmerStarter,
      Switch.MultiPressOngoingEvent.EventFields.currentNumberOfPressesCounted,
    )

    val clickCountVar = variable<UInt>()
    clickCountVar.assign(clickCountExpr)

    action(dimmableLight, DimmableLightDevice) {
      command(
        LevelControl.step(
          stepMode = StepModeEnum.Up,
          stepSize = clickCountVar,
        )
      )
    }
  }
}

टाइप पर लगी पाबंदियां

पक्का करें कि वैरिएबल और एक्सप्रेशन के टाइप, कमांड पैरामीटर के लिए ज़रूरी Matter स्कीमा टाइप की परिभाषा (जैसे, UShort, UByte या UInt8) के मुताबिक हों.

संसाधन की सीमाएं

होम एपीआई में ऑटोमेशन के लिए, ये सीमाएं लागू होती हैं: