اتوماسیونها راهی برای خودکارسازی وظایف و تنظیمات دستگاه در خانه هستند. اتوماسیونها در اکوسیستم گوگل هوم به عنوان روتینها در Google Home app (GHA) و از طریق automation script editor در Google Home for web در دسترس بودهاند.
اکنون، اتوماسیونها در اکوسیستم گوگل هوم از طریق رابطهای برنامهنویسی کاربردی هوم برای اندروید در دسترس هستند. آنها از همان مفاهیم اساسی مورد استفاده در روتینهای GHA و script editor استفاده میکنند، اما با ویژگیها و قابلیتهای پیشرفتهای که فقط از طریق رابطهای برنامهنویسی کاربردی هوم امکانپذیر است، از جمله:
- دسترسی به تمام ویژگیهای استاندارد Matter و smart home برای یک دستگاه، همانطور که در APIهای Home ارائه شده است.
- پشتیبانی از جریانهای اجرای متوالی، موازی و انتخابی.
اتوماسیونها با استفاده از Automation DSL نوشته میشوند، زبانی مختص دامنه که برای ساخت اتوماسیون در کاتلین طراحی شده است.
هر ویژگی و نوع دادهای که قصد دارید در برنامه خود با رابطهای برنامهنویسی کاربردی (API) دستگاه و ساختار یا اتوماسیون استفاده کنید، باید در زمان مقداردهی اولیه ثبت شود. به بخش مقداردهی اولیه خانه در اندروید مراجعه کنید.
راهنمایی در صورت لغو کامل مجوزها توسط کاربر
اگر کاربر مجوزهای کامل را لغو کند، تمام اتوماسیونهای موجود از کار میافتند. همچنین، اگر کاربر دسترسی به دستگاههای خاص را لغو کند، شروعکنندهها، شرطها و اقدامات مرتبط با آن دستگاهها از کار میافتند.
هر بار که برنامه اجرا میشود، حتماً بررسی کنید که مجوزها هنوز معتبر باشند. اگر لغو شدهاند، مطمئن شوید که تمام دادههای قبلی، از جمله هرگونه داده ذخیره شده در حافظه پنهان برنامه، حذف شدهاند.
وقتی دسترسی به ساختار لغو میشود، یک StructureAccessRevokedEvent به بکاند ابری شما ارسال میشود. برای گردش کار لغو دسترسی به ابر و برنامه موبایل همکار به بخش کمکهای مالی ساختار مراجعه کنید.
سفر توسعهدهنده
API اتوماسیون بخشی از یک مسیر توسعهی بزرگتر است. این API پس از ادغام APIهای ساختار و دستگاه ارائه میشود تا اطمینان حاصل شود که وقتی کاربری میخواهد از اتوماسیون استفاده کند، میتواند این کار را انجام دهد.
- توسعهدهنده، اتوماسیون خود را برنامهریزی میکند و آن را با استفاده از Automation DSL تعریف میکند.
- توسعهدهنده، تعریف اتوماسیون را در یک برنامه اندروید کاتلین جاسازی میکند.
- این برنامه بر اساس اطلاعات مربوط به دستگاههای کاربر، از جمله ویژگیها، صفات، دستورات و رویدادها که با استفاده از Discovery API یا Device API جمعآوری شدهاند، اتوماسیونها را به کاربر ارائه میدهد.
- با استفاده از رابط برنامهنویسی کاربردی دیسکاوری (Discovery API)، این برنامه میتواند یک اتوماسیون پیشنویس سفارشیشده با انواع دستگاهها و ویژگیهای موجود در ساختار کاربر، با یا بدون ورودی کاربر، تولید کند.
- رابط برنامهنویسی دستگاه (Device API) میتواند بیشتر اطلاعات مشابه رابط برنامهنویسی کشف (Discovery API) را ارائه دهد، اما برای موارد استفاده خودکار بهینه نشده است. برای جزئیات بیشتر به مقایسه رابط برنامهنویسی دستگاه (Device API) و رابط برنامهنویسی کشف (Discovery API) مراجعه کنید.
- این برنامه، اتوماسیون واقعی را که با ساختار انتخاب شده مرتبط است، ایجاد میکند.
- اتوماسیون اکنون در ساختار کاربر موجود است و میتواند با استفاده از متدهای Structure API اجرا یا حذف شود.
کاربر میتواند در هر زمانی نمونههای جدیدی از اتوماسیون ایجاد کند، ساختار متفاوتی را انتخاب کند یا بسته به منطق برنامه، شاید مجموعهای متفاوت از دستگاهها را انتخاب کند. هر بار که این کار را انجام میدهد، برنامه یک نمونه جدید از اتوماسیون ایجاد میکند.
در ابتداییترین سناریو، ممکن است به کاربران خود یک اتوماسیون از پیش تعریفشده که یک کار نسبتاً اساسی را انجام میدهد، پیشنهاد دهید. یا میتوانید اسکلتی از یک اتوماسیون را ارائه دهید که کاربر آن را برای رفع نیازهای خود سفارشیسازی کند. یا میتوانید یک ویرایشگر اتوماسیون با پایان باز بنویسید که به کاربر اجازه میدهد اتوماسیونهای پیچیده را با استفاده از تمام بلوکهای سازنده موجود در API اتوماسیون بسازد.
پیشنهادات اتوماسیون
APIهای خانه میتوانند بر اساس عواملی مانند انواع دستگاههای موجود در فضا، اتوماسیونهایی را برای یک Structure پیشنهاد دهند.
پیشنهادهای اتوماسیون توسط کلاس AutomationSuggestion نمایش داده میشوند.
رابط Structure شامل رابط HasSuggestions است که تابع suggestions() را ارائه میدهد و مجموعهای از پیشنهادات اتوماسیون را برمیگرداند.
متدهای likeSuggestion() و dislikeSuggestion() به گونهای طراحی شدهاند که به کنترلهای رابط کاربری و متصل شوند که کاربر میتواند برای ارائه بازخورد، روی آنها ضربه بزند.
متد سوم، 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 در اندروید، پارامترهای دستور، نمونههای Expression یا Reference را مستقیماً به جای مقادیر ثابت استاتیک میپذیرند. DSL هنگام ساخت اتوماسیون، این موارد را در تعاریف Parameter کپسولهسازی میکند.
قوانین اعتبارسنجی
پارامترهای دستور پویا از این محدودیتهای اعتبارسنجی پیروی میکنند:
- پارامترهای پویا در طول کشف، از نظر ساختاری معتبر فرض میشوند، زیرا APIهای کشف، فقط محدودیتهای مقداری ملموس را برای آرگومانهای ایستا ارزیابی میکنند.
- گرههای مرجع یا عبارت باید قبل از اینکه در یک اقدام دستوری پاییندستی به آنها اشاره شود، در نمودار اتوماسیون در بالادست ظاهر شوند.
استفاده از پارامترهای دستور پویا در اندروید
عبارات پویا را مستقیماً به پارامترهای فرمان ارسال کنید:
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 ) همسو باشند.
محدودیتهای منابع
محدودیتهای زیر برای اتوماسیونها در APIهای Home اعمال میشود:
| متریک | حد |
|---|---|
| حداکثر تعداد اتوماسیون در هر سازه | ۶۴ |
| حداکثر تعداد گرهها در هر اتوماسیون | ۱۲۸ |
| حداکثر تعداد گرههای بیان در هر اتوماسیون | ۶۴ |
| حداکثر تعداد نمونههای اتوماسیون در هر ساختار | ۱۰۲۴ عدد |
| حداکثر تعداد نمونههای اتوماسیون به ازای هر توسعهدهنده در هر ساختار | ۶۴ |
| حداکثر تعداد اجراها در هر سازه در روز | ۱۰۲۴ عدد |
| حداکثر تعداد اجراها به ازای هر توسعهدهنده به ازای هر ساختار در روز | ۱۲۸ |