คู่มือ DSL ของ Android

ใช้คำแนะนำต่อไปนี้เพื่อทำความเข้าใจวิธีใช้โหนด Automation DSL ต่างๆ เพื่อสร้างการทำงานอัตโนมัติ

Automation DSL ทั้งหมดจะอยู่ในโหนด automation เดียว โหนด automation เป็นขอบเขตระหว่างบริบทภาษา Kotlin ภายนอกกับบริบท DSL ที่ฝังไว้

โฟลว์ตามลำดับ

โฟลว์ตามลำดับเป็นประเภทโฟลว์การทำงานอัตโนมัติเริ่มต้น

ต่อไปนี้คือเทมเพลต Automation DSL พื้นฐานมากที่ใช้โฟลว์ตามลำดับซึ่งประกอบด้วยเงื่อนไขเริ่มต้น เงื่อนไข และการดำเนินการ

import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.condition
import com.google.home.automation.sequential
import com.google.home.automation.starter

...

automation {
  sequential {
    starter<_>(...)
    condition {...}
    action {...}
  }
}

คุณปรับแต่งเทมเพลตนี้ได้โดยการเพิ่มโหนดเพิ่มเติม

เงื่อนไขเริ่มต้น

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

เงื่อนไขเริ่มต้นตามแอตทริบิวต์ลักษณะ

เมื่อประกาศโหนดเงื่อนไขเริ่มต้นที่อิงตามแอตทริบิวต์ลักษณะ ให้ระบุข้อมูลต่อไปนี้

• อุปกรณ์
• ประเภทอุปกรณ์ที่ลักษณะเป็นของ
• ลักษณะ

starter<_>(thermostat, TemperatureSensorDevice, TemperatureMeasurement)

พารามิเตอร์ประเภทอุปกรณ์เป็นพารามิเตอร์ที่จำเป็นเนื่องจากช่วยให้คุณระบุประเภทอุปกรณ์ภายในอุปกรณ์ที่การทำงานอัตโนมัติจะจัดการได้ ตัวอย่างเช่น อุปกรณ์อาจประกอบด้วย a FanDevice และ a HeatingCoolingUnitDevice, ซึ่งทั้ง 2 อย่างมีลักษณะ OnOff การระบุประเภทอุปกรณ์จะช่วยให้ไม่เกิดความคลุมเครือเกี่ยวกับส่วนใดของอุปกรณ์ที่จะทริกเกอร์การทำงานอัตโนมัติ

เงื่อนไขเริ่มต้นตามเหตุการณ์

เมื่อประกาศโหนดเงื่อนไขเริ่มต้นที่อิงตามเหตุการณ์ ให้ระบุข้อมูลต่อไปนี้

• อุปกรณ์
• ประเภทอุปกรณ์ที่ลักษณะเป็นของ
• เหตุการณ์

starter<_>(doorBell, GoogleDoorbellDevice, DoorbellPressed)

เงื่อนไขเริ่มต้นตามโครงสร้างและเหตุการณ์ พร้อมพารามิเตอร์

เหตุการณ์บางอย่างอาจมีพารามิเตอร์ ดังนั้นคุณจึงต้องรวมพารามิเตอร์เหล่านี้ไว้ในเงื่อนไขเริ่มต้นด้วย

ตัวอย่างเช่น เงื่อนไขเริ่มต้นนี้ใช้ Time ของลักษณะ ScheduledTimeEvent เพื่อเปิดใช้งานการทำงานอัตโนมัติในเวลา 7:00 น.

val earlyMorning = starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(Time.ScheduledTimeEvent.clockTime(
    LocalTime.of(7, 0, 0, 0)))
}

เงื่อนไขเริ่มต้นตามสภาพอากาศ

คุณระบุสภาพอากาศปัจจุบันหรือที่คาดการณ์ไว้ในเงื่อนไขเริ่มต้นได้โดยใช้ลักษณะ Weather

val weatherState = starter<_>(structure, trait = Weather)

ดู "ปิดมู่ลี่หากมีแนวโน้มว่าฝนจะตก" ในหน้า การทำงานอัตโนมัติตัวอย่าง

เงื่อนไขเริ่มต้นด้วยตนเอง

เงื่อนไขเริ่มต้นด้วยตนเองเป็นเงื่อนไขเริ่มต้นประเภทพิเศษที่ช่วยให้ผู้ใช้เรียกใช้การทำงานอัตโนมัติด้วยตนเองได้

เมื่อประกาศเงื่อนไขเริ่มต้นด้วยตนเอง ให้ทำดังนี้

• อย่าระบุลักษณะหรือประเภทอุปกรณ์
• ระบุองค์ประกอบ UI ที่เรียก Automation.execute()

เมื่อวางเงื่อนไขเริ่มต้นด้วยตนเองในโฟลว์ select พร้อมกับเงื่อนไขเริ่มต้นอื่น เงื่อนไขเริ่มต้นด้วยตนเองจะลบล้างเงื่อนไขเริ่มต้นอื่น

select {
  manualStarter()
  starter<_>(thermostat, TemperatureSensorDevice, TemperatureMeasurement)
}

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

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

automation_graph {
  sequential {
    select {
      sequential {
        starter<_>(...)
        condition {...}
      }
      sequential {
        manualStarter()
      }
    }
    action {...}
  }
}

อ้างอิงค่าของแอตทริบิวต์

หากต้องการใช้ค่าของแอตทริบิวต์ในนิพจน์ ให้ใช้ไวยากรณ์ต่อไปนี้

เมื่อใช้ stateReader

val time = stateReader<_>(structure, Structure, Time)
val currTime = time.currentTime

เมื่อใช้ starter

val starterNode = starter<_>(device1, LaundryWasherDevice, OnOff)
condition() {
  expression = starterNode.onOff equals true
}

โหนดและนิพจน์เงื่อนไข

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

ภายในโหนด condition คุณสามารถรวมเกณฑ์เงื่อนไขหลายรายการเข้าด้วยกันได้โดยใช้ โอเปอเรเตอร์ต่างๆ ตราบใดที่นิพจน์ ประเมินเป็นค่าบูลีน เดียว หากค่าที่ได้เป็น true แสดงว่าตรงตามเงื่อนไขและการทำงานอัตโนมัติจะดำเนินการโหนดถัดไปต่อไป หากค่าที่ได้เป็น false การทำงานอัตโนมัติจะหยุดดำเนินการที่จุดนั้น

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

ต่อไปนี้คือตัวอย่างของ condition ที่รวมนิพจน์ย่อยหลายรายการเป็นนิพจน์เดียว

condition() {
  val expr1 = starterNode.lockState equals DlLockState.Unlocked
  val expr2 = stateReaderNode.lockState equals true

  val expr3 = occupancySensingDevice.occupied notEquals 0
  val expr4 = timeStateReaderNode
    .currentTime
    .between(
      timeStateReaderNode.sunsetTime,
      timeStateReaderNode.sunriseTime)
  expression = (expr1 and expr2) or (expr3 and expr4)
}

คุณสามารถอ้างอิงค่าของลักษณะที่เข้าถึงผ่านเงื่อนไขเริ่มต้นได้

val starterNode = starter<_>(device, OnOff)
condition() { expression = starterNode.onOff equals true }

stateReader

อีกวิธีหนึ่งในการอ้างอิงค่าแอตทริบิวต์ลักษณะในโหนด condition คือการใช้โหนด stateReader

หากต้องการทำเช่นนี้ ให้บันทึกค่าแอตทริบิวต์ลักษณะในโหนด stateReader ก่อน stateReader จะใช้ structure และลักษณะเป็นอาร์กิวเมนต์

import com.google.home.automation.stateReader
...
val filterMonitoringState = stateReader<_>(structure, ActivatedCarbonFilterMonitoring)

จากนั้นอ้างอิง stateReader ในโหนด condition

condition() {
  expression =
    filterMonitoringState.changeIndication
      .equals(ChangeIndicationEnum.Warning)
}

คุณสามารถใช้ stateReaders หลายรายการในโหนด condition ได้โดยใช้โอเปอเรเตอร์ เปรียบเทียบและ โอเปอเรเตอร์เชิงตรรกะ

val armState = stateReader<_>(doorLock, DoorLockDevice, ArmDisarm )
val doorLockState = stateReader<_>(doorLock, DoorLockDevice, DoorLock)
condition() {
  expression =
    (armState.armState equals true)
    and
    (doorLockState.lockState equals true)
}

ระยะเวลาของเงื่อนไข

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

  condition {
    expression(lightStateReader.onOff == true)
    forDuration(Duration.ofMinutes(10))
  }

ระยะเวลาอาจมีตั้งแต่ 5 วินาทีถึง 24 ชั่วโมง

โหนดการดำเนินการ

โหนดการดำเนินการคือจุดที่การทำงานอัตโนมัติเกิดขึ้น ในตัวอย่างนี้ การดำเนินการจะเรียกใช้ AssistantBroadcast ของลักษณะ broadcast() คำสั่ง:

action(device, SpeakerDevice) {
  command(AssistantBroadcast.broadcast("Intruder detected!"))
}

คำสั่งนำเข้า

เมื่อพัฒนาการทำงานอัตโนมัติ คุณอาจไม่ทราบวิธีนำเข้าองค์ประกอบต่างๆ ของ Home API ลงในโค้ดเสมอไป

ระบบจะนำเข้าแอตทริบิวต์ลักษณะจากออบเจ็กต์ Companion ของลักษณะ

import com.google.home.matter.standard.OnOff.Companion.onOff

ระบบจะนำเข้าโครงสร้างข้อมูลที่กำหนดโดยลักษณะจากคลาสลักษณะที่มีชื่อลงท้ายด้วย "-Trait"

import com.google.home.matter.standard.MediaPlaybackTrait.PlaybackStateEnum

ระบบจะนำเข้าคำสั่งลักษณะจากออบเจ็กต์ Companion ของลักษณะ

import com.google.home.matter.standard.Thermostat.Companion.setTemperatureSetpointHold