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

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

يتم وضع جميع لغات 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)

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

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

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

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

محادثة تمهيدية استنادًا إلى الطقس

يمكنك تحديد أحوال الطقس الحالية أو المتوقّعة في عامل تفعيل باستخدام سمة "الطقس":

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

مدة الشرط

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

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

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

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

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