ภาพรวมของ 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
• การรองรับโฟลว์การดำเนินการแบบลำดับ แบบขนาน และแบบเลือก

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

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

คำแนะนำในกรณีที่ผู้ใช้เพิกถอนสิทธิ์เต็มรูปแบบ

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

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

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

เส้นทางการพัฒนา

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

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

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

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

คำแนะนำการทำงานอัตโนมัติ

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

พารามิเตอร์คำสั่งแบบไดนามิก

พารามิเตอร์คำสั่งแบบไดนามิกช่วยให้นักพัฒนาซอฟต์แวร์สร้างพารามิเตอร์การดำเนินการที่แก้ไขแบบไดนามิกในระหว่างรันไทม์ได้ แทนที่จะอาศัยค่าคงที่แบบคงที่เพียงอย่างเดียว ซึ่งจะช่วยให้มีความสามารถหลัก 2 อย่างดังนี้

• การอ้างอิงที่ส่งค่าพร็อพเพอร์ตี้จากเงื่อนไขเริ่มต้น (เช่น เพย์โหลดเหตุการณ์) หรือโหนดตัวอ่านสถานะ หรือจากตัวแปรภายในที่ประกาศไว้ในโฟลว์การทำงานอัตโนมัติ
• นิพจน์ที่บันทึกค่าแบบไดนามิกในระหว่างรันไทม์ (เช่น พร็อพเพอร์ตี้เหตุการณ์หรือค่าสถานะ) และส่งค่าแบบไดนามิกไปยังพารามิเตอร์คำสั่งโดยตรง

กรณีการใช้งาน

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

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

ใน 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 มีขีดจำกัดดังต่อไปนี้