ภาพรวมของ Automation API ใน Android

การทำงานอัตโนมัติเป็นวิธีทำให้งานและการตั้งค่าอุปกรณ์ในบ้านเป็นแบบอัตโนมัติ การทำงานอัตโนมัติพร้อมใช้งานในระบบนิเวศของ Google Home เป็นกิจวัตรในGoogle Home app (GHA)และผ่านautomation script editorในGoogle Home for web

ตอนนี้การทำงานอัตโนมัติในระบบนิเวศของ Google Home พร้อมใช้งานผ่าน Home API สำหรับ Android แล้ว โดยใช้แนวคิดพื้นฐานเดียวกันกับที่ใช้ในกิจวัตรของ GHA และ script editor แต่มีฟีเจอร์และความสามารถที่ได้รับการปรับปรุงซึ่งทำได้ผ่าน Home API เท่านั้น ซึ่งรวมถึงสิ่งต่อไปนี้

• สิทธิ์เข้าถึงลักษณะมาตรฐาน Matter และลักษณะ smart home ทั้งหมดสำหรับอุปกรณ์ตามที่แสดงใน Home API
• รองรับโฟลว์การดำเนินการตามลำดับ พร้อมกัน และแบบเลือก

การทำงานอัตโนมัติเขียนขึ้นโดยใช้ DSL ของการทำงานอัตโนมัติ ซึ่งเป็นภาษาเฉพาะโดเมนที่ออกแบบมาเพื่อสร้างการทำงานอัตโนมัติใน Kotlin

คุณต้องลงทะเบียนลักษณะและประเภททั้งหมดที่ต้องการใช้ในแอปกับ Device & Structure API หรือ Automation API เมื่อเริ่มต้นใช้งาน ดูหัวข้อเริ่มต้นใช้งานบ้านใน Android

คำแนะนำหากผู้ใช้เพิกถอนสิทธิ์ทั้งหมด

หากผู้ใช้เพิกถอนสิทธิ์ทั้งหมด การทำงานอัตโนมัติที่มีอยู่ทั้งหมดจะหยุดทำงาน นอกจากนี้ หากผู้ใช้เพิกถอนสิทธิ์เข้าถึงอุปกรณ์บางเครื่อง เงื่อนไขเริ่มต้น เงื่อนไข และการดำเนินการที่เชื่อมโยงกับอุปกรณ์เหล่านั้นจะหยุดทำงาน

ทุกครั้งที่แอปเริ่มทำงาน โปรดตรวจสอบว่าสิทธิ์ยังคงมีผลอยู่ หากมีการเพิกถอนสิทธิ์แล้ว โปรดตรวจสอบว่าได้นำข้อมูลก่อนหน้าทั้งหมดออกแล้ว รวมถึงข้อมูลที่แคชไว้ในแอปพลิเคชัน

เมื่อสิทธิ์เข้าถึงบ้านถูกเพิกถอน ระบบจะส่ง StructureAccessRevokedEvent ไปยังแบ็กเอนด์ระบบคลาวด์ของคุณ ดูเวิร์กโฟลว์การเพิกถอนสิทธิ์การเข้าถึงระบบคลาวด์และแอปบนอุปกรณ์เคลื่อนที่ของพาร์ทเนอร์แบบครบวงจรได้ที่โครงสร้างสิทธิ์

เส้นทางของนักพัฒนาแอป

Automation API เป็นเพียงส่วนหนึ่งของเส้นทางการพัฒนาที่ใหญ่ขึ้น โดยจะเกิดขึ้นหลังจากผสานรวม Structure API และ Device API เพื่อให้มั่นใจว่าเมื่อผู้ใช้ต้องการใช้การทำงานอัตโนมัติ ก็จะสามารถทำได้

1. นักพัฒนาแอปวางแผนการทำงานอัตโนมัติและกำหนดการทำงานโดยใช้ DSL ของการทำงานอัตโนมัติ
2. นักพัฒนาแอปฝังคำจำกัดความของการทำงานอัตโนมัติในแอป Android ที่ใช้ Kotlin
3. แอปจะแสดงการทำงานอัตโนมัติแก่ผู้ใช้โดยอิงตามข้อมูลเกี่ยวกับอุปกรณ์ของผู้ใช้ ซึ่งรวมถึงลักษณะ แอตทริบิวต์ คำสั่ง และเหตุการณ์ที่รวบรวมโดยใช้ Discovery API หรือ Device API
   1. Discovery API ช่วยให้แอปสร้างร่างการทำงานอัตโนมัติที่ปรับแต่งให้เหมาะกับประเภทอุปกรณ์และลักษณะที่มีอยู่ในโครงสร้างของผู้ใช้ได้ โดยจะมีการป้อนข้อมูลของผู้ใช้หรือไม่ก็ได้
   2. Device API สามารถให้ข้อมูลส่วนใหญ่เหมือนกับ Discovery API แต่ไม่ได้เพิ่มประสิทธิภาพสำหรับกรณีการใช้งานระบบอัตโนมัติ ดูรายละเอียดเพิ่มเติมได้ที่เปรียบเทียบ Device API กับ Discovery API
4. แอปจะสร้างการทำงานอัตโนมัติจริงที่เชื่อมโยงกับบ้านที่เลือก
5. ตอนนี้การทำงานอัตโนมัติพร้อมใช้งานในบ้านของผู้ใช้แล้ว และสามารถดำเนินการหรือลบได้โดยใช้วิธีการของ Structure API

ผู้ใช้อาจสร้างอินสแตนซ์ใหม่ของการทำงานอัตโนมัติได้ทุกเมื่อ โดยเลือกบ้านอื่นหรืออาจเป็นอุปกรณ์ชุดอื่น ทั้งนี้ขึ้นอยู่กับตรรกะของแอป ทุกครั้งที่ผู้ใช้ดำเนินการดังกล่าว แอปจะสร้างอินสแตนซ์ใหม่ของการทำงานอัตโนมัติ

ในสถานการณ์พื้นฐานที่สุด คุณอาจแนะนำการทำงานอัตโนมัติที่กำหนดไว้ล่วงหน้าซึ่งทำงานที่ค่อนข้างพื้นฐานให้แก่ผู้ใช้ หรือคุณอาจแสดงโครงร่างของการทำงานอัตโนมัติที่ผู้ใช้ปรับแต่งให้ตรงกับความต้องการของตนเองได้ หรือคุณอาจเขียนเครื่องมือแก้ไขการทำงานอัตโนมัติแบบปลายเปิดที่ช่วยให้ผู้ใช้สร้างการทำงานอัตโนมัติที่ซับซ้อนโดยใช้ Building Block ทั้งหมดที่มีอยู่ใน Automation API ได้

สร้างและจัดการการทำงานอัตโนมัติ

วิธีสร้างและจัดการการทำงานอัตโนมัติใน Android

1. ลงทะเบียนประเภทอุปกรณ์และลักษณะทั้งหมดที่การทำงานอัตโนมัติอ้างอิงใน FactoryRegistry ที่ส่งไปยัง HomeConfig ระหว่างการเริ่มต้น SDK ดูรายละเอียดการลงทะเบียนได้ที่หัวข้อเริ่มต้นใช้งานบ้านใน Android
2. สร้าง DraftAutomation (BaseAutomation) โดยใช้ DSL automation() และเรียกใช้เมธอด HasAutomations มาตรฐานในออบเจ็กต์ Structure ดังนี้
   • เรียกใช้ createAutomation() เพื่อสร้างการทำงานอัตโนมัติในบ้าน
   • เรียกใช้ automations() เพื่อแสดงรายการหรือเรียกข้อมูลการทำงานอัตโนมัติที่แอปของคุณสร้างขึ้นในบ้าน
   • เรียกใช้ update() ในอินสแตนซ์ Automation เพื่ออัปเดตข้อมูลเมตาหรือแทนที่ automationGraph
   • เรียกใช้ deleteAutomation() เพื่อนำการทำงานอัตโนมัติออกตามรหัส

val draft = automation {
  name = "Turn on light"
  description = "Turn on light2 when light1 turns on."
  sequential {
    val starterNode = starter<_>(light1, OnOffLightDevice, OnOff)
    condition { expression = starterNode.onOff equals true }
    action(light2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

val createdAutomation = structure.createAutomation(draft)

ดูไวยากรณ์ DSL และตัวอย่างโค้ด CRUD ทั้งหมดได้ที่สร้างการทำงานอัตโนมัติใน Android

คำแนะนำเกี่ยวกับการทำงานอัตโนมัติ

   ติดตั้งใช้งานในแอปตัวอย่างสำหรับ Android   

Home API สามารถแนะนำการทำงานอัตโนมัติสำหรับStructure โดยอิงตามปัจจัยต่างๆ เช่น ประเภทอุปกรณ์ที่มีอยู่ในพื้นที่นั้น

คำแนะนำการทำงานอัตโนมัติจะแสดงด้วยคลาส AutomationSuggestion

อินเทอร์เฟซ Structure ประกอบด้วยอินเทอร์เฟซ HasSuggestions ซึ่งมีฟังก์ชัน suggestions() ที่แสดงผลคอลเล็กชันคำแนะนำการทำงานอัตโนมัติ

เมธอด likeSuggestion() และ dislikeSuggestion() มีไว้เพื่อเชื่อมต่อกับตัวควบคุม UI thumb_up และ thumb_down ที่ผู้ใช้แตะเพื่อแสดงความคิดเห็นได้

วิธีที่ 3 คือ 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 ขณะรันไทม์

วิธีการทำงานของพารามิเตอร์แบบไดนามิก

ใน Automation DSL บน Android พารามิเตอร์คำสั่งจะยอมรับอินสแตนซ์ Expression หรือ Reference แทนค่าคงที่แบบคงที่โดยตรง DSL จะรวมสิ่งเหล่านี้ไว้ในคำจำกัดความ Parameter เมื่อสร้างการทำงานอัตโนมัติ

กฎการตรวจสอบความถูกต้อง

พารามิเตอร์คำสั่งแบบไดนามิกเป็นไปตามข้อจำกัดด้านการตรวจสอบต่อไปนี้

• ระบบจะถือว่าพารามิเตอร์แบบไดนามิกมีความถูกต้องตามโครงสร้างในระหว่างการค้นพบ เนื่องจาก Discovery API จะประเมินข้อจำกัดของค่าที่เป็นรูปธรรมสำหรับอาร์กิวเมนต์แบบคงที่เท่านั้น
• โหนดอ้างอิงหรือนิพจน์ต้องปรากฏที่ต้นทางในกราฟการทำงานอัตโนมัติก่อนที่จะมีการอ้างอิงในการดำเนินการคำสั่งปลายทาง

ใช้พารามิเตอร์คำสั่งแบบไดนามิกใน 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)

ขีดจำกัดของทรัพยากร

ขีดจำกัดต่อไปนี้มีผลกับการทำงานอัตโนมัติใน Home API