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

استخدِم الدليل التالي لفهم كيفية استخدام عُقد Automation DSL المختلفة لإنشاء عملية تشغيل آلي.

يتم وضع كل Automation 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)

المشغِّل المستند إلى بنية وحدث، مع مَعلمات

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

على سبيل المثال، يستخدم هذا المشغِّل Time من السمة ScheduledTimeEvent لتفعيل عملية التشغيل الآلي في الساعة 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، وقد تحتوي على قيم أولية مثل الأرقام والأحرف والسلاسل والقيم المنطقية، بالإضافة إلى قيم التعداد. يتيح لك تجميع التعبيرات الفرعية باستخدام الأقواس التحكّم في ترتيب تقييمها.

في ما يلي مثال على 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)
}

مدة الشرط

بالإضافة إلى التعبير المنطقي في الشرط، يمكنك تحديد إطار زمني يجب أن تكون فيه قيمة التعبير `true` لتشغيل عملية التشغيل الآلي. على سبيل المثال، يمكنك تحديد شرط يتم تنشيطه فقط إذا كان المصباح مضاءً لمدة عشر دقائق.

  condition {
    expression(lightStateReader.onOff == true)
    forDuration(Duration.ofMinutes(10))
  }

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

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

عقدة الإجراء هي المكان الذي يتم فيه تنفيذ عملية التشغيل الآلي. في هذا المثال، يستدعي الإجراء الأمر broadcast() من السمة AssistantBroadcast:

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

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

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