دليل DSL لنظام التشغيل Android

استخدِم الدليل التالي لفهم كيفية استخدام العقد المختلفة في Automation DSL لإنشاء عملية مبرمَجة.

يتم وضع كل لغة DSL للتشغيل الآلي ضمن عقدة automation واحدة. تشكل العقدة automation الحدود بين سياق لغة Kotlin الخارجي وسياق لغة DSL المضمّنة.

التدفق التسلسلي

إنّ المسار التسلسلي هو النوع التلقائي لمسار التشغيل الآلي.

في ما يلي نموذج أساسي جدًا لـ Automation 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)

نموذج أساسي يستند إلى بنية وحدث، مع مَعلمات

يمكن أن تحتوي بعض الأحداث على مَعلمات، لذا يجب أيضًا تضمين هذه المَعلمات في المشغِّل.

على سبيل المثال، يستخدم هذا الإجراء المشغِّل 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، يمكنك دمج معايير شروط متعددة باستخدام عوامل تشغيل مختلفة، ما دام التعبير يُحتسب على أنّه قيمة boolean واحدة. إذا كانت القيمة الناتجة هي 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. تأخذ الدالة 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!"))
}

عبارات الاستيراد

عند تطوير عمليات التشغيل الآلي، لا يكون من الواضح دائمًا كيفية استيراد مختلف عناصر واجهات برمجة تطبيقات 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