ऑटोमेशन बनाना

ऑटोमेशन एपीआई को Home एपीआई के ज़रिए ऐक्सेस किया जा सकता है. हालांकि, इनका एंट्री पॉइंट स्ट्रक्चर होता है. इसलिए, इनका इस्तेमाल करने से पहले, स्ट्रक्चर के लिए अनुमति देनी होगी.

किसी स्ट्रक्चर के लिए अनुमतियां मिलने के बाद, इन पैकेज को अपने ऐप्लिकेशन में इंपोर्ट करें:


import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.Id
import com.google.home.Structure

स्ट्रक्चर में, ऑटोमेशन के लिए ये तरीके इस्तेमाल करने वाला HasAutomations इंटरफ़ेस होता है:

एपीआई ब्यौरा
automations() स्ट्रक्चर से जुड़े सभी ऑटोमेशन की सूची बनाएं. सिर्फ़ वे ऑटोमेशन दिखाए जाते हैं जिन्हें आपने Home के एपीआई की मदद से बनाया है.
createAutomation(automation) किसी स्ट्रक्चर के लिए ऑटोमेशन इंस्टेंस बनाएं.
deleteAutomation(automationId) ऑटोमेशन इंस्टेंस को उसके आईडी के हिसाब से मिटाएं.

ऑटोमेशन बनाना

होम का इंस्टेंस बनाने और उपयोगकर्ता से अनुमतियां मिलने के बाद, स्ट्रक्चर और डिवाइस(डिवाइसों) का ऐक्सेस पाएं:

val structure = homeManager.structures().list().single()
val device = homeManager.devices().get(Id("myDevice"))!!

इसके बाद, ऑटोमेशन डीएसएल का इस्तेमाल करके, अपने ऑटोमेशन का लॉजिक तय करें. Home API में, ऑटोमेशन को Automation इंटरफ़ेस से दिखाया जाता है. इस इंटरफ़ेस में प्रॉपर्टी का एक सेट होता है:

  • मेटाडेटा, जैसे कि नाम और ब्यौरा.
  • उदाहरण के लिए, ऐसे फ़्लैग जिनसे पता चलता है कि ऑटोमेशन को लागू किया जा सकता है या नहीं.
  • नोड की सूची, जिसमें ऑटोमेशन का लॉजिक होता है. इसे ऑटोमेशन ग्राफ़ कहा जाता है और इसे automationGraph प्रॉपर्टी से दिखाया जाता है.

automationGraph, डिफ़ॉल्ट रूप से SequentialFlow टाइप का होता है. यह एक ऐसी क्लास है जिसमें क्रम से चलने वाले नोड की सूची होती है. हर नोड, ऑटोमेशन के किसी एलिमेंट को दिखाता है. जैसे, स्टार्टर, शर्त या कार्रवाई.

ऑटोमेशन को name और description असाइन करें.

ऑटोमेशन बनाने पर, isActive फ़्लैग डिफ़ॉल्ट रूप से true पर सेट हो जाता है. इसलिए, इस फ़्लैग को साफ़ तौर पर सेट करने की ज़रूरत नहीं है, बशर्ते कि आपने ऑटोमेशन को शुरू में बंद न किया हो. ऐसे में, फ़्लैग को बनाने के दौरान false पर सेट करें.

DraftAutomation इंटरफ़ेस का इस्तेमाल, ऑटोमेशन बनाने और उन्हें सेट अप करने के लिए किया जाता है. साथ ही, Automation इंटरफ़ेस का इस्तेमाल, डेटा वापस पाने के लिए किया जाता है. उदाहरण के लिए, यहां एक ऑटोमेशन के लिए ऑटोमेशन डीएसएल दिया गया है, जो किसी डिवाइस के चालू होने पर, दूसरे डिवाइस को चालू करता है:

import com.google.home.automation.Action
import com.google.home.automation.Automation
import com.google.home.automation.Condition
import com.google.home.automation.DraftAutomation
import com.google.home.automation.Equals
import com.google.home.automation.Node
import com.google.home.automation.SequentialFlow
import com.google.home.automation.Starter
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.matter.standard.OnOff
import com.google.home.Structure

...

val automation: DraftAutomation = automation {
  name = "MyFirstAutomation"
  description = "Turn on a device when another device is turned on."
  sequential {
    val starterNode = starter<_>(device1, OnOffLightDevice, trait=OnOff)
    condition() { expression = stateReaderNode.onOff equals true }
    action(device2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

ऑटोमेशन डीएसएल तय करने के बाद, DraftAutomation इंस्टेंस बनाने के लिए, इसे createAutomation() तरीके पर पास करें:

val createdAutomation = structure.createAutomation(automation)

यहां से, ऑटोमेशन के लिए अन्य सभी तरीकों का इस्तेमाल किया जा सकता है. जैसे, execute(), stop(), और update().

पुष्टि से जुड़ी गड़बड़ियां

अगर ऑटोमेशन बनाने की प्रोसेस के दौरान पुष्टि नहीं हो पाती है, तो चेतावनी या गड़बड़ी का मैसेज, समस्या के बारे में जानकारी देता है. ज़्यादा जानकारी के लिए, ValidationIssueType रेफ़रंस देखें.

कोड के उदाहरण

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

आसान ऑटोमेशन

सुबह 8:00 बजे ब्लाइंड ऊपर करने वाला ऑटोमेशन इस तरह से लागू किया जा सकता है:

// get all the automation node candidates in the structure
val allCandidates = structure.allCandidates().first()
// determine whether a scheduled automation can be constructed
val isSchedulingSupported =
  allCandidates.any {
    it is EventCandidate &&
      it.eventFactory == Time.ScheduledTimeEvent &&
      it.unsupportedReasons.isEmpty()
  }
// get the blinds present in the structure
val blinds =
  allCandidates
    .filter {
      it is CommandCandidate &&
        it.commandDescriptor == WindowCoveringTrait.UpOrOpenCommand &&
        it.unsupportedReasons.isEmpty()
    }
    .map { it.entity }
    .filterIsInstance<HomeDevice>()
    .filter { it.has(WindowCoveringDevice) }
 if (isSchedulingSupported && blinds.isNotEmpty()) {
  // Proceed to create automation
  val automation: DraftAutomation = automation {
    name = "Day time open blinds"
    description = "Open all blinds at 8AM everyday"
    isActive = true
    sequential {
      // At 8:00am local time....
      val unused =
        starter(structure, Time.ScheduledTimeEvent) {
          parameter(Time.ScheduledTimeEvent.clockTime(LocalTime.of(8, 0, 0, 0)))
        }
        // ...open all the blinds
       parallel {
        for (blind in blinds) {
          action(blind, WindowCoveringDevice) { command(WindowCovering.upOrOpen()) }
        }
      }
    }
  }
   val createdAutomation = structure.createAutomation(automation)
} else if (!isSchedulingSupported) {
  // Cannot create automation. Set up your address on the structure, then try again.
} else {
  // You don't have any WindowCoveringDevices. Try again after adding some blinds to your structure.
}

जटिल ऑटोमेशन

मोशन का पता चलने पर, लाइटें चमकने की सुविधा को इस तरह से लागू किया जा सकता है:

import com.google.home.Home
import com.google.home.HomeClient
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure
import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.equals
import com.google.home.automation.parallel
import com.google.home.automation.starter
import com.google.home.google.AssistantBroadcast
import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOff.Companion.toggle
import com.google.home.matter.standard.OnOffLightDevice
import java.time.Duration

// get all the automation node candidates in the structure
val allCandidates = structure.allCandidates().first()

// get the lights present in the structure
val availableLights = allCandidates.filter {
   it is CommandCandidate &&
   it.commandDescriptor == OnOffTrait.OnCommand
}.map { it.entity }
.filterIsInstance<HomeDevice>()
.filter {it.has(OnOffLightDevice) ||
         it.has(ColorTemperatureLightDevice) ||
         it.has(DimmableLightDevice) ||
         it.has(ExtendedColorLightDevice)}

val selectedLights = ... // user selects one or more lights from availableLights

automation {
isActive = true

sequential {
   // If the presence state changes...
   val starterNode = starter<_>(structure, AreaPresenceState)
   // ...and if the area is occupied...
   condition() {
      expression = starterNode.presenceState equals PresenceState.PresenceStateOccupied
   }
   // "blink" the light(s)
   parallel {
            for(light in selectedLights) {
            action(light, OnOffLightDevice) { command(OnOff.toggle()) }
            delayFor(Duration.ofSeconds(1))
            action(light, OnOffLightDevice) { command(OnOff.toggle()) }
            delayFor(Duration.ofSeconds(1))
            action(light, OnOffLightDevice) { command(OnOff.toggle()) }
            delayFor(Duration.ofSeconds(1))
            action(light, OnOffLightDevice) { command(OnOff.toggle())}
         }
      }
   }
}

सामान्य ऑटोमेशन

नीचे दिए गए कोड में बताया गया है कि Structure API, Device API, और Discovery API का इस्तेमाल करके, उपयोगकर्ता के होम के बारे में डेटा कैसे इकट्ठा किया जा सकता है. इससे, उपयोगकर्ता को अपना सामान्य ऑटोमेशन बनाने में मदद मिलती है. इस बारे में ऑटोमेशन डिज़ाइन करना: सामान्य ऑटोमेशन में बताया गया है.

val structureFlow: Flow<Structure> = home.structures().itemFlow(myStructureId)

// Get a snapshot of the structure.
val structure: Structure = structureFlow.first()

   // map of devices where key is device id
val devicesById = mutableMapOf<Id,HomeDevice>()

home.devices().list().map { devicesById.put(it.id, it) }

// map of rooms where key is room id
val roomsByName: MutableMap<String,Room?> = mutableMapOf<String,Room?>()

structure.rooms().list().map { roomsByName.put(it.name, it) }

// map of commands where key is trait id
val commandsByTrait: MutableMap<String,MutableList<CommandCandidate>?> = mutableMapOf<String,MutableList<CommandCandidate>?>()

// map of commands where key is DeviceType.Metadata.hashcode()
val commandsByDeviceType: MutableMap<Id,MutableList<CommandCandidate>?> = mutableMapOf<Id,MutableList<CommandCandidate>?>()

// map of commands where key is entity id
val commandsByEntity: MutableMap<Id,MutableList<CommandCandidate>?> = mutableMapOf<Id,MutableList<CommandCandidate>?>()


// map of stateReaders where key is trait id
val stateReadersByTrait: MutableMap<Int,MutableList<StateReaderCandidate>?> = mutableMapOf<Int,MutableList<StateReaderCandidate>?>()

// map of stateReaders where key is DeviceType.Metadata.hashcode()
val stateReadersByDeviceType: MutableMap<Int,MutableList<StateReaderCandidate>?> = mutableMapOf<Int,MutableList<StateReaderCandidate>?>()

// map of stateReaders where key is  entity id
val stateReadersByEntity: MutableMap<Int,MutableList<StateReaderCandidate>?> = mutableMapOf<Int,MutableList<StateReaderCandidate>?>()

// map of starters where key is trait id
val startersByTrait: MutableMap<Int,MutableList<StarterCandidate>?> = mutableMapOf<Int,MutableList<StarterCandidate>?>()

// map of starters where key is DeviceType.Metadata.hashcode()
val startersByDeviceType: MutableMap<Int,MutableList<CommandCandidate>?> = mutableMapOf<Int,MutableList<CommandCandidate>?>()

// map of starters where key is entity id
val startersByEntity: MutableMap<Int,MutableList<StarterCandidate>?> = mutableMapOf<Int,MutableList<StarterCandidate>?>()

// populate candidate maps
structure.allCandidates().first().map {
  when (it) {
   is CommandCandidate -> {

      // update commandsByTrait
      // TODO refactor into generic function to eliminate duplicate code
      var commandsByTraitList: MutableList<CommandCandidate>? = commandsByTrait.get(it.trait.factory.traitId: String)
      if(commandsByTraitList == null) { commandsByTraitList = arrayListOf<CommandCandidate>() }

      commandsByTraitList.add(it)
      commandsByTrait.put(it.trait.factory.traitId, commandsByTraitList)

      // update commandsByDeviceType
      // TODO refactor into generic function to eliminate duplicate code
      for (t in it.types) {

      //TODO filter out device types not present in the home

      //TODO how to get a reference to device type id? 

      var commandsByDeviceTypeList: MutableList<CommandCandidate>? = commandsByDeviceType.get(t.factory.typeId: Id)

      if (commandsByDeviceTypeList == null)  { commandsByDeviceTypeList = arrayListOf<CommandCandidate>() }

      commandsByDeviceTypeList.add(it)

      commandsByDeviceType.put(t.factory.typeId, commandsByDeviceTypeList)
      }

      // update commandsByEntity
      // TODO refactor into generic function to eliminate duplicate code
     var commandsByEntityList: MutableList<CommandCandidate>? = commandsByEntity.get(it.entity.id: Id)
      if ( commandsByEntityList == null ) {commandsByEntityList = arrayListOf<CommandCandidate>()}
      commandsByEntityList.add(it)
      commandsByEntity.put(it.entity.id, commandsByEntityList)
   }

/*
   is StateReaderCandidate -> {

      // update stateReadersByTrait

      var stateReadersList: MutableList<StateReaderCandidate>? = stateReadersByTrait.get(it.trait.factory.traitId)
      if(stateReadersList == null) { stateReadersList = arrayListOf<StateReaderCandidate>() }

      stateReadersList.add(it)
      stateReadersByTrait.put(it.trait.factory.traitId, stateReadersList)

   // update stateReadersByDeviceType

      for (t in it.types) {
      //TODO filter out device types not present in the home
      var stateReadersList: MutableList<StateReaderCandidate>? = stateReadersByDeviceType.get(t.metadata.hashcode())

      if (stateReadersList == null)  { stateReadersList = arrayListOf<StateReaderCandidate>() }

      stateReadersList.put(it)

      stateReadersByDeviceType.put(t.metadata.hashCode(),deviceTypeStateReaderList)
      }

      // update stateReadersByEntity

      MutableList<StateReaderCandidate> entityStateReaderList? = stateReadersByEntity.get(it.entity.id)
      if  entityStateReaderList  is null  {entityStateReaderList = arrayListOf<StateReaderCandidate>()}
      entityStateReaderList.add(it)
      stateReadersByEntity.put(it.entity.id, entityStateReaderList)
   }

   */

   /*
   is StarterCandidate  -> {

      // update startersByTrait

      var startersList: MutableList<StateReaderCandidate>? = startersByTrait.get(it.trait.factory.traitId)
      if(startersList == null) { startersList = arrayListOf<StateReaderCandidate>() }

      startersList.add(it)
      startersByTrait.put(it.trait.factory.traitId, startersList)

   // update startersByDeviceType

      for (t in it.types) {
      //TODO filter out device types not present in the home
      var startersList: MutableList<StateReaderCandidate>? = startersByDeviceType.get(t.metadata.hashcode())

      if (startersList == null)  { startersList = arrayListOf<StateReaderCandidate>() }

      startersList.put(it)

      startersByDeviceType.put(t.metadata.hashCode(),deviceTypeStateReaderList)
      }

      // update startersByEntity

      MutableList<StateReaderCandidate> entityStateReaderList? = startersByEntity.get(it.entity.id)
      if  entityStateReaderList  is null  {entityStateReaderList = arrayListOf<StateReaderCandidate>()}
      entityStateReaderList.add(it)
      stateReadersByEntity.put(it.entity.id, entityStateReaderList)

      }
*/
 else -> println("unknown type encountered: " + it)

  }
}

ऑटोमेशन चलाना

execute() के तरीके का इस्तेमाल करके, बनाया गया ऑटोमेशन चलाएं:

createdAutomation.execute()

अगर ऑटोमेशन में मैन्युअल स्टार्टर है, तो execute() उस बिंदु से ऑटोमेशन शुरू करता है. साथ ही, मैन्युअल स्टार्टर से पहले के सभी नोड को अनदेखा करता है. अगर ऑटोमेशन में मैन्युअल स्टार्टर नहीं है, तो पहले स्टार्टर नोड के बाद वाले नोड से प्रोसेस शुरू होती है.

अगर execute() ऑपरेशन पूरा नहीं हो पाता है, तो HomeException को ट्रिगर किया जा सकता है. गड़बड़ी को मैनेज करना देखें.

किसी ऑटोमेशन को रोकना

stop() तरीके का इस्तेमाल करके, चल रहे ऑटोमेशन को रोकने के लिए:


createdAutomation.stop()

अगर stop() ऑपरेशन पूरा नहीं हो पाता है, तो HomeException को ट्रिगर किया जा सकता है. गड़बड़ी को मैनेज करना देखें.

किसी स्ट्रक्चर के लिए ऑटोमेशन की सूची पाना

ऑटोमेशन, स्ट्रक्चर के लेवल पर तय किए जाते हैं. ऑटोमेशन के Flow को ऐक्सेस करने के लिए, स्ट्रक्चर के automations() पर इकट्ठा करें:


import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
structure.automations().collect {
  println("Available automations:")
  for (automation in it) {
    println(String.format("%S %S", "$automation.id", "$automation.name"))
  }
}

इसके अलावा, इसे किसी स्थानीय Collection को असाइन करें:

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

var myAutomations: Collection<Automation> = emptyList()
myAutomations = structure.automations()

आईडी के हिसाब से ऑटोमेशन पाना

ऑटोमेशन आईडी के हिसाब से ऑटोमेशन पाने के लिए, स्ट्रक्चर पर automations() तरीका कॉल करें और आईडी पर मैच करें:

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
val automation: DraftAutomation = structure.automations().mapNotNull {
  it.firstOrNull
    { automation -> automation.id == Id("automation-id") }
  }.firstOrNull()

जवाब:

// Here's how the automation looks like in the get response. Here, it's represented
// as if calling a println(automation.toString())

Automation(
  name = "automation-name",
  description = "automation-description",
  isActive = true,
  id = Id("automation@automation-id"),
  automationGraph = SequentialFlow(
    nodes = [
      Starter(
        entity="device@test-device",
        type="home.matter.0000.types.0101",
        trait="OnOff@6789..."),
      Action(
        entity="device@test-device",
        type="home.matter.0000.types.0101",
        trait="OnOff@8765...",
        command="on")
    ]))

नाम के आधार पर ऑटोमेशन पाना

Kotlin में filter() तरीका का इस्तेमाल करके, एपीआई कॉल को और बेहतर बनाया जा सकता है. नाम के हिसाब से ऑटोमेशन पाने के लिए, स्ट्रक्चर के ऑटोमेशन पाएं और ऑटोमेशन के नाम के हिसाब से फ़िल्टर करें:

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
val automation: DraftAutomation = structure.automations().filter {
  it.name.equals('Sunset Blinds') }

किसी डिवाइस के लिए सभी ऑटोमेशन पाना

किसी डिवाइस का रेफ़रंस देने वाले सभी ऑटोमेशन पाने के लिए, नेस्ट किए गए फ़िल्टर का इस्तेमाल करके, हर ऑटोमेशन के automationGraph को स्कैन करें:

import android.util.Log
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure
import com.google.home.automation.Action
import com.google.home.automation.Automation
import com.google.home.automation.Automation.automationGraph
import com.google.home.automation.Node
import com.google.home.automation.ParallelFlow
import com.google.home.automation.SelectFlow
import com.google.home.automation.SequentialFlow
import com.google.home.automation.Starter
import com.google.home.automation.StateReader

...

fun collectDescendants(node: Node): List<Node> {
  val d: MutableList<Node> = mutableListOf(node)

  val children: List<Node> =
    when (node) {
      is SequentialFlow -> node.nodes
      is ParallelFlow -> node.nodes
      is SelectFlow -> node.nodes
      else -> emptyList()
    }
  for (c in children) {
    d += collectDescendants(c)
  }
  return d
}

val myDeviceId = "device@452f78ce8-0143-84a-7e32-1d99ab54c83a"
val structure = homeManager.structures().list().single()
val automations =
  structure.automations().first().filter {
    automation: Automation ->
    collectDescendants(automation.automationGraph!!).any { node: Node ->
      when (node) {
        is Starter -> node.entity.id.id == myDeviceId
        is StateReader -> node.entity.id.id == myDeviceId
        is Action -> node.entity.id.id == myDeviceId
        else -> false
      }
    }
  }

ऑटोमेशन अपडेट करना

किसी ऑटोमेशन का मेटाडेटा अपडेट करने के लिए, उसका update() तरीका कॉल करें. साथ ही, मेटाडेटा सेट करने वाला लैंब्डा एक्सप्रेशन पास करें:

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
val automation: DraftAutomation = structure.automations().mapNotNull {
  it.firstOrNull
    { automation -> automation.id == Id("automation-id") }
  }.firstOrNull()
automation.update { this.name = "Flashing lights 2" }

update() वाला तरीका, ऑटोमेशन ग्राफ़ को पूरी तरह से बदलने में मदद करता है. हालांकि, यह ग्राफ़ के हर नोड में बदलाव करने में मदद नहीं करता. नोड के आपस में जुड़े होने की वजह से, हर नोड में बदलाव करने पर गड़बड़ियां हो सकती हैं. अगर आपको किसी ऑटोमेशन का लॉजिक बदलना है, तो नया ग्राफ़ जनरेट करें और मौजूदा ग्राफ़ को पूरी तरह से बदलें.

ऑटोमेशन मिटाना

किसी ऑटोमेशन को मिटाने के लिए, स्ट्रक्चर के deleteAutomation() तरीके का इस्तेमाल करें. किसी ऑटोमेशन को मिटाने के लिए, उसके आईडी का इस्तेमाल करना ज़रूरी है.

import com.google.home.automation.Automation
import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.HomeManager
import com.google.home.Id
import com.google.home.Structure

...

val structure = homeManager.structures().list().single()
val automation: DraftAutomation = structure.automations().first()
structure.deleteAutomation(automation.id)

अगर डेटा मिटाने में कोई गड़बड़ी होती है, तो HomeException दिख सकता है. गड़बड़ी को मैनेज करना देखें.

ऑटोमेशन पर डिवाइस मिटाने का असर

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