دليل لغات وصف البيانات (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))
}

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

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

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

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