מדריך ל-DSL ב-iOS

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

כל ה-DSL של האוטומציה ממוקם בתוך צומת automation יחיד. הצומת automation יוצר את הגבול בין ההקשר החיצוני של שפת Swift לבין ההקשר של ה-DSL המוטמע.

תהליך עבודה רציף

הזרימה העוקבת היא סוג ברירת המחדל של זרימת אוטומציה.

הנה תבנית בסיסית מאוד של Automation DSL שמשתמשת בזרימה רציפה שכוללת התחלה, תנאי ופעולה:

import GoogleHomeSDK
import GoogleHomeTypes

automation (
...
) {
  starter(...)
  condition {...}
  action {...}
}

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

מתחילים

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

חבילת התחלה שמבוססת על מאפיין של תכונה

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

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

starter(
  thermostat,
  Matter.TemperatureSensorDeviceType.self,
  Matter.TemperatureMeasurementTrait.self
)

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

חבילת Starter על סמך אירוע

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

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

starter(
  doorbell,
  Google.GoogleDoorbellDeviceType.self,
  Google.DoorbellPressTrait.DoorbellPressedEvent
)

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

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

לדוגמה, סימן תחילת הפעולה הזה משתמש ב-TimeTrait של ScheduledEvent כדי להפעיל את האוטומציה בשעה 7:00 בבוקר:

typealias TimeTrait = Google.TimeTrait

let earlyMorning = starter(
  structure,
  TimeTrait.ScheduledEvent.self
) {
  TimeTrait.ScheduledEvent.clockTime(TimeOfDay(hours: 7, minutes: 0))
}

התחלה על סמך מזג האוויר

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

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

אפשר לעיין בדוגמה Close the blinds if it is likely to rain (סגירת התריסים אם צפוי גשם) בדף Example automations (דוגמאות לאוטומציות).

מפעיל ידני

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

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

• אל תציינו תכונה או סוג מכשיר.
• מספקים רכיב בממשק המשתמש שקורא ל-Automation.execute().

כשמציבים הפעלה ידנית בתהליך select יחד עם הפעלה אחרת, ההפעלה הידנית מבטלת את ההפעלה האחרת:

select {
  manualStarter()
  starter(
    thermostat,
    Matter.TemperatureSensorDeviceType.self,
    Matter.TemperatureMeasurementTrait.self
  )
}

שימו לב שכל condition הצמתים שאחרי נקודת התחלה ידנית ייבדקו, ויכול להיות שהם יחסמו את ההפעלה של האוטומציה, בהתאם לcondition ביטוי.

דרך אחת לבנות את האוטומציה כך שצמתי condition לא יחסמו אוטומציה שהופעלה באמצעות התחלה ידנית היא להציב את ההתחלה האחרת בתהליך רציף נפרד יחד עם condition שלה:

import GoogleHomeSDK
import GoogleHomeTypes

automation (
...
) {

  select {
    sequential {
      starter(...)
      condition {...}
    }
    sequential {
      manualStarter()
    }
  }
  action {...}

}

הפניה לערך של מאפיין

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

עם stateReader:

typealias TimeTrait = Google.TimeTrait

let time = stateReader(structure, TimeTrait.self)
time
let currTime = time.currentTime

עם starter:

typealias LaundryWasherDeviceType = Matter.LaundryWasherDeviceType
typealias OnOffTrait = Google.OnOffTrait

let starterNode = starter(device1, LaundryWasherDeviceType.self, OnOffTrait.self)
starterNode
condition {
  starterNode.onOff.equals(true)
}

צמתי תנאים וביטויים

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

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

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

דוגמה ל-condition שמשלב כמה ביטויי משנה לביטוי אחד:

condition {
  let exp1 = starterNode.lockState.equals(.unlocked)
  let exp2 = stateReaderNode.lockState.equals(true)
  let exp3 = occupancySensingDevice.occupied.notEquals(0)
  (exp1.and(exp2)).or(exp3)
}

אפשר להפנות לערך של תכונה שאליה ניגשים דרך חבילה למתחילים:

typealias OnOffTrait = Matter.OnOffTrait

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

stateReader

דרך נוספת להפניה לערכי מאפייני מאפיינים בצומת condition היא באמצעות צומת stateReader.

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

typealias ActivatedCarbonFilterMonitoringTrait = Matter.ActivatedCarbonFilterMonitoringTrait

let filterMonitoringState = stateReader(structure, ActivatedCarbonFilterMonitoringTrait.self)

לאחר מכן, מפנים אל stateReader בצומת condition:

condition {
filterMonitoringState.changeIndication.equals(.warning)
}

אפשר להשתמש בכמה תנאים stateReaders בצומת condition באמצעות אופרטורים להשוואה ואופרטורים לוגיים:

typealias ArmDisarm = Google.ArmDisarmTrait
typealias DoorLockDevice = Matter.DoorLockDeviceType
typealias DoorLock = Matter.DoorLockTrait

let armState = stateReader(doorLock, DoorLockDevice.self, ArmDisarm )
let doorLockState = stateReader(doorLock, DoorLockDevice.self, DoorLock)
armState
doorLockState
condition {
  let exp1 = armState.armState
  let exp2 = doorLockState.lockState
  exp1.and(exp2)
}

משך התנאי

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

condition(for: .seconds(600)) {
lightStateReader.onOff.equals(true)
}

משך הזמן יכול להיות בין דקה אחת ל-30 דקות.

צמתי פעולה

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

action(speaker, SpeakerDeviceType.self) {
  Google.AssistantBroadcastTrait.broadcast(msg: "Oven Cycle Complete")
}