راهنمای Android DSL

از راهنمای زیر برای درک نحوه استفاده از گره‌های مختلف «زبان مدل‌سازی خودکارسازی» برای ساختن خودکارسازی استفاده کنید.

همه «زبان مدل‌سازی خودکارسازی» در یک گره automation قرار می‌گیرد. گره automation مرز بین بافت زبان Kotlin بیرونی و بافت DSL جاسازی‌شده را تشکیل می‌دهد.

جریان متوالی

جریان ترتیبی نوع پیش‌فرض جریان خودکارسازی است.

مثال 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)

آغازگر براساس ساختار و رویداد، با پارامترها

برخی‌از رویدادها می‌توانند پارامتر داشته باشند، بنابراین این پارامترها نیز باید در شروع‌کننده گنجانده شوند.

برای مثال، این آغازگر از Time مشخصه ScheduledTimeEvent برای فعال کردن خودکارسازی در ساعت ۷:۰۰ صبح استفاده می‌کند:

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 ضبط کنید. ‫A 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))
  }

مدت زمان می‌تواند از ۵ ثانیه تا ۲۴ ساعت متغیر باشد.

گره‌های کنش

گره کنش جایی است که کار خودکارسازی انجام می‌شود. در این مثال، کنش فرمان AssistantBroadcast ویژگی broadcast() را فرا می‌خواند:

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

وارد کردن صورت‌وضعیت‌ها

هنگام توسعه خودکارسازی‌ها، نحوه وارد کردن عناصر مختلف «میاناهای برنامه‌سازی کاربردی Home» به کد شما همیشه واضح نیست.

مشخصه‌های ویژگی از شیء 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
قبلی
مفاهیم DSL
بعدی
اتوماسیون های پیچیده