סקירה כללית על Automation API ב-Android

פעולות אוטומטיות הן דרך להפוך משימות והגדרות המכשיר בבית לאוטומטיות. פעולות אוטומטיות זמינות בסביבה של Google Home כתרחישים בGoogle Home app (GHA) ובאמצעות automation script editor ב-Google Home for web.

עכשיו, פעולות אוטומטיות בסביבה העסקית של Google Home זמינות דרך ממשקי ה-API של Home ל-Android. הם משתמשים באותם מושגים בסיסיים שמשמשים בתרחישים של GHA ובscript editor, אבל עם תכונות ויכולות משופרות שזמינות רק דרך ממשקי ה-API של Home, כולל:

• גישה לכל התכונות הרגילות של Matter ושל smart home במכשיר, כפי שהן מוצגות בממשקי ה-API של Home.
• תמיכה בתהליכי ביצוע סדרתיים, מקבילים וסלקטיביים.

האוטומציות נכתבות באמצעות Automation DSL, שפה ספציפית לתחום שמיועדת ליצירת אוטומציות ב-Kotlin.

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

הנחיות למקרה שבו המשתמש מבטל את ההרשאות המלאות

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

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

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

התהליך שעובר המפתח

‫Automation API הוא רק חלק אחד מתהליך פיתוח רחב יותר. הוא מגיע אחרי שילוב של Structure API ו-Device API, כדי לוודא שמשתמשים שרוצים להשתמש באוטומציה יכולים לעשות את זה.

1. המפתח מתכנן את האוטומציה ומגדיר אותה באמצעות Automation 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.

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

בתרחיש הכי בסיסי, אתם יכולים להציע למשתמשים אוטומציה מוגדרת מראש שמבצעת משימה בסיסית יחסית. לחלופין, אפשר להציג שלד של אוטומציה שהמשתמש יכול להתאים אישית לפי הצרכים שלו. אפשר גם לכתוב עורך אוטומציה פתוח שמאפשר למשתמש ליצור פעולות אוטומטיות מורכבות באמצעות כל אבני הבניין שזמינות ב-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   

ממשקי ה-API של Home יכולים להציע אוטומציות לStructure על סמך גורמים כמו סוגי המכשירים שנמצאים במרחב.

הצעות לאוטומציה מיוצגות על ידי המחלקה AutomationSuggestion.

הממשק Structure כולל את הממשק HasSuggestions, שמספק את הפונקציה suggestions() שמחזירה אוסף של הצעות לאוטומציה.

השיטות likeSuggestion() ו-dislikeSuggestion() מיועדות לחיבור לרכיבים האינטראקטיביים thumb_up ו-thumb_down, שהמשתמש יכול ללחוץ עליהם כדי לשלוח משוב.

השיטה השלישית, 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 בזמן הריצה.

איך פועלים פרמטרים דינמיים

ב-Automation DSL ב-Android, הפרמטרים של הפקודות מקבלים מופעים של Expression או Reference ישירות במקום ערכים קבועים סטטיים. ה-DSL כולל את אלה בהגדרות של Parameter כשיוצרים את האוטומציה.

כללי אימות

פרמטרים של פקודות דינמיות כפופים למגבלות האימות הבאות:

• המערכת מניחה שהפרמטרים הדינמיים תקינים מבחינה מבנית במהלך הגילוי, כי ממשקי ה-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: