راهنمای DSL - اتوماسیون های اساسی، راهنمای DSL - اتوماسیون های اساسی

از راهنمای زیر برای درک چگونگی استفاده از گره های DSL مختلف اتوماسیون برای ساخت یک اتوماسیون استفاده کنید.

تمام DSL های اتوماسیون درون یک گره automation قرار می گیرند. گره automation مرز بین زمینه زبان کاتلین خارجی و زمینه 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 {...}
  }
}

این را می توان با افزودن گره های اضافی اصلاح کرد.

استارتر

گره های شروع کننده شرایط اولیه ای را که یک اتوماسیون را فعال می کند، تعریف می کنند. به عنوان مثال، تغییر در وضعیت یا مقدار. یک اتوماسیون باید حداقل یک شروع کننده داشته باشد، در غیر این صورت اعتبار سنجی ناموفق خواهد بود. برای اضافه کردن بیش از یک شروع کننده به یک اتوماسیون، باید از یک گره انتخابی استفاده کنید.

شروع کننده بر اساس ویژگی صفت

هنگام اعلان یک گره شروع که بر اساس یک ویژگی مشخصه است، مشخص کنید:

• دستگاه
• نوع دستگاهی که این صفت به آن تعلق دارد
• صفت

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)))
}

استارت دستی

استارت دستی نوع خاصی از استارت است که به کاربر اجازه می دهد اتوماسیون را به صورت دستی اجرا کند.

هنگام اعلام استارت دستی:

• یک ویژگی یا نوع دستگاه را مشخص نکنید.
• یک عنصر رابط کاربری ارائه کنید که 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 است.

برای انجام این کار، ابتدا مقدار ویژگی trait را در یک گره 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))
  }

مدت زمان می تواند از یک تا 30 دقیقه متغیر باشد.

گره های عمل

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

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

بیانیه های وارداتی

هنگام توسعه اتوماسیون، همیشه مشخص نیست که چگونه عناصر مختلف APIهای Home را به کد خود وارد کنید.

ویژگی‌های صفت از شی Companion این صفت وارد می‌شوند:

import com.google.home.matter.standard.OnOff.Companion.onOff

ساختارهای داده‌ای که توسط یک صفت تعریف می‌شوند از کلاس صفت که نام آن به "-Trait" ختم می‌شود وارد می‌شوند:

import com.google.home.matter.standard.MediaPlaybackTrait.PlaybackStateEnum

دستورات Trait از شی Companion این صفت وارد می شوند:

import com.google.home.matter.standard.Thermostat.Companion.setTemperatureSetpointHold