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