מדריך ל-Android DSL

המדריך הבא מסביר איך להשתמש בצמתים שונים של Automation DSL כדי ליצור אוטומציה.

כל ה-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 {...}
  }
}

אפשר לשפר את התוצאה על ידי הוספת צמתים.

מתחילים

צומתי התחלה מגדירים את הנסיבות הראשוניות שמפעילות פעולה אוטומטית. לדוגמה, שינוי במצב או בערך. כל פעולה אוטומטית חייבת לכלול לפחות גורם מפעיל אחד, אחרת היא לא תעבור את האימות. כדי להוסיף יותר מגורם מפעיל אחד לפעולה אוטומטית, צריך להשתמש בצומת select.

גורם מפעיל שמבוסס על מאפיין של תכונה

כשמצהירים על צומת התחלה שמבוסס על מאפיין של תכונה, צריך לציין:

• המכשיר
• סוג המכשיר שאליו שייכת התכונה
• המאפיין

starter<_>(thermostat, TemperatureSensorDevice, TemperatureMeasurement)

פרמטר סוג המכשיר נדרש כי הוא מאפשר לציין לאיזה סוג מכשיר בתוך מכשיר האוטומציה מתייחסת. לדוגמה, מכשיר יכול להיות מורכב מ-FanDevice ומ-HeatingCoolingUnitDevice, ושניהם מכילים את המאפיין OnOff. כשמציינים את סוג המכשיר, אין ספק לגבי החלק במכשיר שמפעיל את הפעולה האוטומטית.

גורם מפעיל שמבוסס על אירוע

כשמגדירים צומת התחלה שמבוסס על אירוע, צריך לציין:

• המכשיר
• סוג המכשיר שאליו שייכת התכונה
• האירוע

starter<_>(doorBell, GoogleDoorbellDevice, DoorbellPressed)

גורם התחלה שמבוסס על מבנה ואירוע, עם פרמטרים

לחלק מהאירועים יכולים להיות פרמטרים, ולכן צריך לכלול גם את הפרמטרים האלה בגורם שמפעיל את התרחיש.

לדוגמה, סימן תחילת הפעולה הזה משתמש במאפיין ScheduledTimeEvent של התכונה Time כדי להפעיל את הפעולה האוטומטית בשעה 7:00:

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

גורם התחלה שמבוסס על מזג האוויר

אתם יכולים לציין תנאי מזג אוויר נוכחיים או חזויים בגורם להפעלה, באמצעות התכונה "מזג אוויר":

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

סגירת התריסים אם צפוי גשם בדף דוגמאות לאוטומציות.

הפעלה ידנית

גורם ידני הוא סוג מיוחד של גורם שמאפשר למשתמש להפעיל את האוטומציה באופן ידני.

כשמגדירים הפעלה ידנית:

• אל תציינו תכונה או סוג מכשיר.
• מוסיפים רכיב בממשק המשתמש שמפעיל את 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)
}

משך התנאי

בנוסף לביטוי בוליאני בתנאי, אתם יכולים לציין מסגרת זמן שבה הביטוי חייב להיות נכון כדי להפעיל את הפעולה האוטומטית. לדוגמה, אפשר להגדיר תנאי שמופעל רק אם האור דולק במשך עשר דקות.

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

ההשהיה יכולה להימשך בין 5 שניות ל-24 שעות.

צומתי פעולה

צומת הפעולה הוא המקום שבו מתבצעת העבודה של האוטומציה. בדוגמה הזו, הפעולה מפעילה את הפקודה broadcast() של המאפיין AssistantBroadcast:

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

הצהרות ייבוא

כשמפתחים פעולות אוטומטיות, לא תמיד ברור איך לייבא רכיבים שונים של Home APIs לקוד.

מאפייני התכונה מיובאים מהאובייקט 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