مفاهیم DSL

این یک مرور کلی از مفاهیم اساسی Automation DSL است.

اجزای اتوماسیون

یک اتوماسیون شامل اجزای اساسی زیر است که معمولاً به این ترتیب ارزیابی می شوند:

1. شروع - شرایط اولیه ای که اتوماسیون را فعال می کند، مانند تغییر در یک ویژگی را تعریف می کند. یک اتوماسیون باید یک استارت داشته باشد.
2. شرط - هر گونه محدودیت اضافی برای ارزیابی پس از فعال شدن اتوماسیون. عبارت در یک شرط باید true ارزیابی شود تا اقدامات یک اتوماسیون ادامه یابد.
3. Action - دستورات یا به‌روزرسانی‌های حالتی که در صورت برآورده شدن همه شرایط انجام می‌شوند.

برای مثال، شاید شما یک اتوماسیون داشته باشید که وقتی تلویزیون آن اتاق بین غروب و طلوع خورشید روشن می شود، نور اتاق را کم می کند. در این مثال:

1. شروع کننده - تلویزیون روشن شد، که تغییر حالت در یک ویژگی تلویزیونی است.
2. وضعیت - زمان فعلی خانه ای که تلویزیون در آن قرار دارد ارزیابی می شود.
3. اقدام - نورهای همان اتاقی که تلویزیون در آن قرار دارد کم نور است.

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

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

گره ها

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

گره های رفتاری

گره هایی مانند شروع و کنش گره های رفتاری هستند. استارت‌ها یک اتوماسیون را بر اساس تغییرات ویژگی دستگاه فعال می‌کنند. کنش‌ها فرمان‌های دستگاه یا به‌روزرسانی ویژگی‌ها را صادر می‌کنند.

گره های رفتاری معمولاً برای استفاده به عنوان ورودی در گره های دیگر به ویژگی های دستگاه و وضعیت ویژگی خروجی گره خورده اند.

گره های جریان اجرا

برخی از گره ها نشان دهنده جریان های اجرایی مانند ترتیبی و موازی هستند. هر یک از این گره ها شامل گره های رفتاری هستند که اتوماسیون را تعریف می کنند.

به عنوان مثال، یک جریان متوالی ممکن است شامل گره هایی باشد که به ترتیب متوالی اجرا می شوند. به طور معمول، اینها شروع کننده، شرط و عمل هستند.

یک جریان موازی ممکن است دارای چندین گره عملی باشد که همزمان اجرا می شوند، مانند روشن کردن چندین چراغ به طور همزمان. گره هایی که یک جریان موازی را دنبال می کنند تا زمانی که تمام شاخه های جریان موازی به پایان نرسند اجرا نمی شوند.

نوع دیگری از جریان اجرا، جریان شرطی است که می تواند بر اساس ارزیابی یک عبارت، جریان اجرا را تغییر دهد.

به عنوان مثال، شاید شما یک اتوماسیون دارید که بر اساس شب بودن یک عمل انجام می دهد. یک گره شرطی زمان روز را بررسی می کند، سپس مسیر اجرای مناسب را بر اساس آن ارزیابی دنبال می کند.

یک جریان انتخابی زمانی مفید است که می‌خواهید بیش از یک شروع کننده داشته باشید که بتواند اتوماسیون شما را فعال کند. هنگامی که دو یا چند استارتر را در یک جریان select قرار می دهید، هر یک از استارترها می تواند اتوماسیون را فعال کند.

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

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

در اتوماسیون های پیچیده، گره های جریان اجرا نیز می توانند تو در تو باشند. به عنوان مثال، ممکن است یک جریان متوالی داشته باشید که یک جریان موازی را اجرا می کند.

گره‌های DSL را می‌توان به روش‌های مختلف تودرتو و ترکیب کرد تا نیازهای خاص شما را برآورده کند، طبق محدودیت‌های ذکر شده در جدول زیر. ستون Builder به مستندات سازنده Kotlin typesafe پیوند می‌خورد، که جزئیات موارد مجاز برای استفاده در هر نوع گره را نشان می‌دهد.

اتوماسیون DSL

در APIهای Home، اتوماسیون ها با استفاده از DSL (زبان اختصاصی دامنه) اتوماسیون تعریف می شوند. اتوماسیون DSL به عنوان یک Kotlin DSL (زبان اختصاصی دامنه) با استفاده از سازنده های نوع ایمن Kotlin پیاده سازی شده است و به طور خاص برای تعریف قالب های اتوماسیون طراحی شده است.

هنگامی که یک اتوماسیون کامپایل می‌شود، سازنده‌های ایمن نوع Kotlin کلاس‌های داده Kotlin را تولید می‌کنند که سپس به صورت سریال بافر پروتکل JSON می‌شوند، که برای برقراری تماس با سرویس‌های اتوماسیون Google استفاده می‌شود.

اتوماسیون DSL فرآیند اتوماسیون ساختمان را ساده و ساده می کند. به طور بومی از همان مدل داده ویژگی‌های استاندارد Matter و ویژگی‌های smart home که در Device API استفاده می‌شود، استفاده می‌کند.

Automation DSL همچنین منطق یک اتوماسیون را بر اساس انواع دستگاه های انتزاعی تعریف می کند، برخلاف نمونه های دستگاه خاص واقع در خانه کاربر. این به توسعه‌دهنده اجازه می‌دهد تا پارامترهای ورودی را ارائه دهد که ممکن است در زمان اجرا برای تعیین نمونه‌های واقعی دستگاه، و همچنین سایر مقادیر پارامتر مهم استفاده شوند.

نحو DSL شبیه به کاتلین است و به همان اندازه از نظر نوع ایمن است، اما اتوماسیونی که در Automation DSL نوشته شده است ساده تر و مختصرتر از همان اتوماسیون نوشته شده در Kotlin خالص است.

مثال

در زیر نمونه ای از اتوماسیونی است که یک دستگاه را روشن می کند و با استفاده از Automation DSL نوشته شده است:

val automation = automation {
  name = "MyFirstAutomation"
  description = "If light1 is on, turn on light2."
  isActive = true
  sequential {
    val onOffTrait = starter<_>(device1, OnOffLightDevice, OnOff)
    condition() { expression = onOffTrait.onOff equals true }
    action(device2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

این اتوماسیون بسیار اساسی است: هنگامی که یک چراغ، device1 ، روشن می‌شود (ویژگی onOff به true تغییر می‌کند)، سپس دستور on() را برای روشن کردن device2 ارسال می‌کند.

اتوماسیون از یک گره sequential استفاده می کند که نشان می دهد گره های آن به ترتیب متوالی اجرا می شوند.

در گره sequential گره های رفتاری مانند starter ، condition و action قرار دارند. خروجی گره starter به یک متغیر برای استفاده در گره condition اختصاص داده می شود.