دليل 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)))
}

المشغّل اليدوي

المشغّل اليدوي هو نوع خاص من المشغّلات يتيح للمستخدم تشغيل عملية التشغيل الآلي يدويًا.

عند تحديد إجراء تفعيل يدوي:

• لا تحدِّد سمة أو نوع جهاز.
• توفير عنصر واجهة مستخدم يستدعي 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))
  }

يمكن أن تتراوح المدة بين دقيقة واحدة و30 دقيقة.

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

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