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

استخدِم الدليل التالي لفهم كيفية استخدام عُقد Automation 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)

إجراء تفعيل استنادًا إلى بنية وحدث، مع مَعلمات

يمكن أن تتضمّن بعض الأحداث مَعلمات، لذا يجب أيضًا تضمين هذه المَعلمات في إجراء التفعيل.

على سبيل المثال، يستخدم إجراء التفعيل هذا السمة TimeScheduledTimeEvent لتفعيل التشغيل الآلي في الساعة 7:00 صباحًا:

val earlyMorning = starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(Time.ScheduledTimeEvent.clockTime(
    LocalTime.of(7, 0, 0, 0)))
}

إجراء التفعيل استنادًا إلى حالة الطقس

يمكنك تحديد أحوال الطقس الحالية أو المتوقّعة في إجراء التفعيل باستخدام السمة Weather:

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

يمكن أن تتراوح المدة بين 5 ثوانٍ و24 ساعة.

عُقد الإجراءات

عُقدة الإجراء هي المكان الذي يتم فيه تنفيذ عملية التشغيل الآلي. في هذا المثال، يستدعي الإجراء الأمر 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