دليل لغات وصف البيانات (DSL) لنظام التشغيل iOS

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

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

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

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

في ما يلي نموذج أساسي جدًا للغة DSL الخاصة بالأتمتة يستخدم تسلسلاً يتألف من إجراء تفعيل وشرط وإجراء:

import GoogleHomeSDK
import GoogleHomeTypes

automation (
...
) {
  starter(...)
  condition {...}
  action {...}
}

يمكن تحسين ذلك من خلال إضافة عُقد إضافية.

مبتدئ

تحدّد عُقد إجراءات التفعيل الظروف الأولية التي تؤدي إلى تفعيل عملية التشغيل الآلي. على سبيل المثال، تغيير في الحالة أو القيمة. يجب أن يتضمّن التشغيل الآلي إجراء تفعيل واحدًا على الأقل، وإلا ستتعذّر عملية التحقّق من صحته. لإضافة أكثر من إجراء تفعيل واحد إلى عملية تشغيل آلي، عليك استخدام عقدة select.

إجراء التفعيل المستند إلى سمة السمة

عند تعريف عقدة بادئة تستند إلى سمة مميزة، حدِّد ما يلي:

• الجهاز
• نوع الجهاز الذي تنتمي إليه السمة
• السمة

starter(
  thermostat,
  Matter.TemperatureSensorDeviceType.self,
  Matter.TemperatureMeasurementTrait.self
)

معلَمة نوع الجهاز مطلوبة لأنّها تتيح لك تحديد نوع الجهاز الذي يستهدفه التشغيل الآلي. على سبيل المثال، قد يتكوّن الجهاز من FanDeviceType وHeatingCoolingUnitDeviceType، وكلاهما يحتويان على السمة OnOffTrait. من خلال تحديد نوع الجهاز، لن يكون هناك أي غموض بشأن الجزء من الجهاز الذي يؤدي إلى تشغيل عملية التشغيل الآلي.

إجراء التفعيل المستند إلى الأحداث

عند تعريف عقدة بادئة تستند إلى حدث، حدِّد ما يلي:

• الجهاز
• نوع الجهاز الذي تنتمي إليه السمة
• الحدث

starter(
  doorbell,
  Google.GoogleDoorbellDeviceType.self,
  Google.DoorbellPressTrait.DoorbellPressedEvent
)

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

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

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

typealias TimeTrait = Google.TimeTrait

let earlyMorning = starter(
  structure,
  TimeTrait.ScheduledEvent.self
) {
  TimeTrait.ScheduledEvent.clockTime(TimeOfDay(hours: 7, minutes: 0))
}

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

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

let weatherState = starter<_>(structure, trait = Weather)

اطّلِع على إغلاق الستائر إذا كان من المحتمل هطول الأمطار في صفحة أمثلة على عمليات التشغيل الآلي.

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

إجراء التفعيل اليدوي هو نوع خاص من إجراءات التفعيل يتيح للمستخدم تشغيل عملية التشغيل الآلي يدويًا.

عند تعريف مشغّل يدوي:

• لا تحدّد سمة أو نوع جهاز.
• توفير عنصر في واجهة المستخدم يستدعي Automation.execute()

عند وضع مشغّل يدوي في مسار select مع مشغّل آخر، سيتجاوز المشغّل اليدوي المشغّل الآخر:

select {
  manualStarter()
  starter(
    thermostat,
    Matter.TemperatureSensorDeviceType.self,
    Matter.TemperatureMeasurementTrait.self
  )
}

يُرجى العِلم أنّه سيتم تقييم أي عقد condition تلي إجراء تفعيل يدوي، وقد تحظر تنفيذ التشغيل الآلي، وذلك استنادًا إلى تعبير condition.

إحدى طرق تنظيم عملية التشغيل الآلي كي لا تحظر عقد condition عملية تشغيل آلي تم تفعيلها باستخدام إجراء تفعيل يدوي هي وضع إجراء التفعيل الآخر في مسار تسلسلي منفصل مع condition الخاص به:

import GoogleHomeSDK
import GoogleHomeTypes

automation (
...
) {

  select {
    sequential {
      starter(...)
      condition {...}
    }
    sequential {
      manualStarter()
    }
  }
  action {...}

}

الرجوع إلى قيمة سمة

لاستخدام قيمة سمة في تعبير، استخدِم البنية التالية.

باستخدام stateReader:

typealias TimeTrait = Google.TimeTrait

let time = stateReader(structure, TimeTrait.self)
time
let currTime = time.currentTime

باستخدام starter:

typealias LaundryWasherDeviceType = Matter.LaundryWasherDeviceType
typealias OnOffTrait = Google.OnOffTrait

let starterNode = starter(device1, LaundryWasherDeviceType.self, OnOffTrait.self)
starterNode
condition {
  starterNode.onOff.equals(true)
}

عُقد التعبيرات والشروط

تمثّل عقدة الشرط نقطة اتخاذ قرار تحدّد ما إذا كان سيتم مواصلة عملية التشغيل الآلي أم لا. يمكن أن يحتوي التشغيل الآلي على عُقد condition متعددة. إذا تم تقييم تعبير أي عقدة condition على أنّه false، يتوقف تنفيذ عملية التشغيل الآلي بأكملها.

ضمن عقدة condition، يمكنك دمج معايير شروط متعددة باستخدام عوامل تشغيل مختلفة، طالما أنّ التعبير يتم تقييمه إلى قيمة منطقية واحدة. إذا كانت القيمة الناتجة true، يكون الشرط مستوفى وتواصل عملية التشغيل الآلي تنفيذ العقدة التالية. إذا كانت القيمة false، يتوقف التنفيذ التلقائي عند هذه النقطة.

يتم إنشاء التعبيرات بشكل مشابه للتعبيرات في Swift، وقد تحتوي على قيم أولية مثل الأرقام والأحرف والسلاسل والقيم المنطقية، بالإضافة إلى قيم Enum. يتيح لك تجميع التعبيرات الفرعية باستخدام الأقواس التحكّم في ترتيب تقييمها.

في ما يلي مثال على condition يجمع عدة تعبيرات فرعية في تعبير واحد:

condition {
  let exp1 = starterNode.lockState.equals(.unlocked)
  let exp2 = stateReaderNode.lockState.equals(true)
  let exp3 = occupancySensingDevice.occupied.notEquals(0)
  (exp1.and(exp2)).or(exp3)
}

يمكنك الرجوع إلى قيمة سمة تم الوصول إليها من خلال إجراء التفعيل:

typealias OnOffTrait = Matter.OnOffTrait

let starterNode = starter(device, OnOffTrait.self)
starterNode
condition {
  starterNode.onOff.equals(true)
}
val starterNode = starter<_>(device, OnOff)
condition() { expression = starterNode.onOff equals true }

stateReader

الطريقة الأخرى للإشارة إلى قيم سمات السمة في عقدة condition هي باستخدام عقدة stateReader.

لإجراء ذلك، عليك أولاً تسجيل قيمة سمة السمة في عقدة stateReader. تأخذ الدالة A stateReader السمة structure والسمة كمعلَمات:

typealias ActivatedCarbonFilterMonitoringTrait = Matter.ActivatedCarbonFilterMonitoringTrait

let filterMonitoringState = stateReader(structure, ActivatedCarbonFilterMonitoringTrait.self)

بعد ذلك، أشِر إلى stateReader في العقدة condition:

condition {
filterMonitoringState.changeIndication.equals(.warning)
}

باستخدام عوامل المقارنة وعوامل التشغيل المنطقية، يمكن استخدام عدة stateReaders في عقدة condition:

typealias ArmDisarm = Google.ArmDisarmTrait
typealias DoorLockDevice = Matter.DoorLockDeviceType
typealias DoorLock = Matter.DoorLockTrait

let armState = stateReader(doorLock, DoorLockDevice.self, ArmDisarm )
let doorLockState = stateReader(doorLock, DoorLockDevice.self, DoorLock)
armState
doorLockState
condition {
  let exp1 = armState.armState
  let exp2 = doorLockState.lockState
  exp1.and(exp2)
}

مدة الحالة

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

condition(for: .seconds(600)) {
lightStateReader.onOff.equals(true)
}

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

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

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

action(speaker, SpeakerDeviceType.self) {
  Google.AssistantBroadcastTrait.broadcast(msg: "Oven Cycle Complete")
}