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 के ज़रिए उपलब्ध कराई जा सकती हैं. इनमें ये शामिल हैं:

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

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

डिवाइस और स्ट्रक्चर या ऑटोमेशन एपीआई के साथ अपने ऐप्लिकेशन में इस्तेमाल किए जाने वाले सभी टाइप और ट्रेट, शुरू में ही रजिस्टर किए जाने चाहिए. Android डिवाइस पर होम को इनिशियलाइज़ करना लेख पढ़ें.

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

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

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

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

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

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

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

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

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

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

होम एपीआई, 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 step कमांड में पास की गई डाइनैमिक वैल्यू होती है.

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

Android पर Automation DSL में, कमांड पैरामीटर, स्टैटिक कॉन्स्टेंट वैल्यू के बजाय सीधे तौर पर 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) के मुताबिक हों.

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

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