راهنمای iOS DSL

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

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

جریان متوالی

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

در اینجا یک الگوی DSL خودکارسازی بسیار ساده وجود دارد که از یک جریان متوالی شامل یک شروع‌کننده، یک شرط، و یک کنش استفاده می‌کند:

import GoogleHomeSDK
import GoogleHomeTypes

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

این را می‌توان با افزودن گره‌های بیشتر پالایش کرد.

آغازگر

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

آغازگر براساس مشخصه ویژگی

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

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

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

پارامتر نوع دستگاه الزامی است زیرا به شما امکان می‌دهد مشخص کنید اتوماسیون به کدام نوع دستگاه در دستگاه اشاره دارد. برای مثال، ممکن است دستگاهی از FanDeviceType و HeatingCoolingUnitDeviceType تشکیل شده باشد که هر دو حاوی مشخصه OnOffTrait هستند. با مشخص کردن نوع دستگاه، هیچ ابهامی درباره اینکه کدام بخش از دستگاه خودکارسازی را راه‌اندازی می‌کند وجود ندارد.

آغازگر براساس رویداد

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

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

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

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

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

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

typealias TimeTrait = Google.TimeTrait

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

آغازگر براساس آب‌وهوا

می‌توانید شرایط آب‌وهوایی فعلی یا پیش‌بینی‌شده را در آغازگر مشخص کنید، بااستفاده از مشخصه «آب‌وهوا»:

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

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

شروع‌کننده دستی

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

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

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

مدت وضعیت

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

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

مدت زمان می‌تواند از یک تا ۳۰ دقیقه باشد.

گره‌های کنش

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

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