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

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

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

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

التدفّق التسلسلي هو النوع التلقائي لتدفّق التشغيل الآلي.

في ما يلي نموذج أساسي جدًا لـ Automation 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
)

أداة بدء مستندة إلى بنية وحدث، مع مَعلمات

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

على سبيل المثال، تستخدِم أداة البدء هذه TimeTrait's ScheduledEvent لتفعيل عملية التشغيل الآلي في الساعة 7:00 صباحًا:

typealias TimeTrait = Google.TimeTrait

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

أداة بدء مستندة إلى حالة الطقس

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

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، وقد تحتوي على قيم أولية مثل الأرقام والأحرف والسلاسل والقيم المنطقية، بالإضافة إلى قيم التعداد. يسمح لك تجميع التعبيرات الفرعية باستخدام الأقواس بالتحكّم في ترتيب تقييمها.

في ما يلي مثال على 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 دقيقة.

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

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

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