التحكّم في الأجهزة على نظام التشغيل iOS

يستند هذا الدليل إلى الوصول إلى الأجهزة وبياناتها الوصفية على iOS ويقدّم أمثلة إضافية على التحكّم في الأجهزة والوصول إليها.

لاستخدام أنواع أو سمات أجهزة معيّنة، مثل Matter OnOffTrait المستخدَمة في العديد من الأمثلة هنا، يجب استيرادها:

import GoogleHomeSDK
import GoogleHomeTypes

التحقّق مما إذا كانت السمة تتوافق مع أمر

استخدِم الدالة supports على مستوى السمة للتحقّق مما إذا كان الأمر متوافقًا مع جهاز معيّن.

على سبيل المثال، للتحقّق من توافق الجهاز مع الأمر toggle الخاص بسمة "تشغيل/إيقاف":

// Check if the OnOff trait supports the toggle command.
if onOffTraitTest.supportsToggleCommand {
  print("onOffTrait supports toggle command")
} else {
  print("onOffTrait does not support stateful toggle command")
}

إرسال أمر إلى جهاز

يشبه إرسال أمر قراءة سمة حالة من سمة. لتشغيل الجهاز أو إيقافه، استخدِم الأمر OnOffTrait Toggle، وهو محدّد في نموذج بيانات المنظومة المتكاملة في Google Home باسم toggle(). تغيّر هذه الطريقة القيمة من onOff إلى false إذا كانت true، أو من false إلى true إذا كانت false:

// Calling a command on a trait.
do {
  try await onOffTraitTest.toggle()
} catch let error as HomeError {
  // Code for handling the exception
}

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

بدلاً من ذلك، استخدِم الأمرَين off() أو on() لضبط الحالة بشكل صريح:

do {
  try await onOffTraitTest.off()
  try await onOffTraitTest.on()
} catch let error as HomeError {
  // Code for handling the exception
}

بعد إرسال أمر لتغيير الحالة، يمكنك قراءة الحالة بعد اكتمالها كما هو موضّح في قراءة حالة الجهاز للتعامل معها في تطبيقك.

إرسال أمر يتضمّن مَعلمات

قد تستخدم بعض الطلبات مَعلمات، مثل تلك الواردة في OnOffTrait أو LevelControlTrait:

// Turn off the light using the DyingLight effect.
do {
  try await onOffTraitTest.offWithEffect(
    effectIdentifier: Matter.OnOffTrait.EffectIdentifierEnum.dyingLight,
    effectVariant: 0
  )
} catch let error as HomeError {
  // Code for handling the exception
}

// Change the brightness of the light to 50%
do {
  try await levelControlTraitTest.moveToLevel(
    level: UInt8(127),
    transitionTime: 0,
    optionsMask: Matter.LevelControlTrait.OptionsBitmap(),
    optionsOverride: Matter.LevelControlTrait.OptionsBitmap()
  )
} catch let error as HomeError {
  // Code for handling the exception
}

التحقّق مما إذا كانت السمة تتوافق مع إحدى السمات

قد تتوافق بعض الأجهزة مع سمة Matter، ولكن ليس مع سمة معيّنة. على سبيل المثال، قد لا يتوافق جهاز Cloud-to-cloud الذي تم ربطه بـ Matter مع كل سمات Matter. للتعامل مع حالات مثل هذه، استخدِم السمة isSupported على مستوى السمة للتحقّق مما إذا كانت السمة متوافقة مع جهاز معيّن.

على سبيل المثال، للتحقّق من توافق الجهاز مع السمة onOff الخاصة بميزة "تشغيل/إيقاف":

// Check if the OnOff trait supports the onOff attribute.
if onOffTrait.attributes.$onOff.isSupported {
  print("onOffTrait supports onOff state")
} else {
  print("onOffTrait is for a command only device!")
}

تكون بعض السمات قابلة للقيم الفارغة في مواصفات Matter أو مخطط Cloud-to-cloud smart home. بالنسبة إلى هذه السمات، يمكنك تحديد ما إذا كانت القيمة null التي تعرضها السمة ناتجة عن عدم إبلاغ الجهاز بهذه القيمة، أو ما إذا كانت قيمة السمة هي nil فعلاً، وذلك باستخدام isNullable بالإضافة إلى isSupported:

// Check if a nullable attribute is set or is not supported.
if let deviceType = await device.types.get(OnOffLightDeviceType.self) {
  if let onOffTrait = deviceType.traits[Matter.OnOffTrait.self] {
    if onOffTrait.attributes.startUpOnOff == nil {
      if onOffTrait.attributes.$startUpOnOff.isSupported {
        print(
          "onOffTrait supports startUpOnOff and it is nil. Check the spec for the contextual meaning."
        )
      } else {
        print("onOffTrait does not support startUpOnOff!")
      }
    } else {
      print(
        "onOffTrait supports startUpOnOff and it is set to \(onOffTrait.attributes.startUpOnOff)"
      )
    }
  }
}

تعديل سمات السلوك

إذا أردت تغيير قيمة سمة معيّنة، ولم يفعل أي من أوامر السمة ذلك، قد تتيح السمة ضبط قيمتها بشكل صريح.

يعتمد إمكانية تغيير قيمة السمة على عاملين:

• هل يمكن تعديل السمة؟
• هل يمكن أن تتغيّر قيمة السمة كتأثير جانبي لإرسال أمر سمة؟

تقدّم مستندات المرجع الخاصة بالسمات وخصائصها هذه المعلومات.

وبالتالي، فإنّ مجموعات الخصائص التي تحدّد كيفية تغيير قيمة السمة هي:

• للقراءة فقط ولا تتأثر بالأوامر الأخرى وهذا يعني أنّ قيمة السمة لا تتغيّر. على سبيل المثال، السمة currentPosition الخاصة بالعنصر SwitchTrait.

• للقراءة فقط ويتأثر بأوامر أخرى وهذا يعني أنّ الطريقة الوحيدة لتغيير قيمة السمة هي نتيجة إرسال أمر. على سبيل المثال، السمة currentLevel الخاصة بالعنصر LevelControlTrait هي للقراءة فقط، ولكن يمكن تغيير قيمتها باستخدام أوامر مثل moveToLevel.

• يمكن الكتابة فيه ولا يتأثر بالأوامر الأخرى. هذا يعني أنّه يمكنك تغيير قيمة السمة مباشرةً باستخدام الدالة update الخاصة بالسمة، ولكن لا توجد أوامر تؤثر في قيمة السمة. على سبيل المثال، السمة WrongCodeEntryLimit الخاصة بالعنصر DoorLockTrait.

• يمكن الكتابة فيه ويتأثر بأوامر أخرى. هذا يعني أنّه يمكنك تغيير قيمة السمة مباشرةً باستخدام الدالة update الخاصة بالسمة، ويمكن أن تتغيّر قيمة السمة نتيجةً لإرسال أمر. على سبيل المثال، يمكن كتابة السمة occupiedCoolingSetpoint الخاصة بالعنصر ThermostatTrait ، كما يمكن تعديلها باستخدام الأمر setpointRaiseLower.

مثال على استخدام دالة التعديل لتغيير قيمة إحدى السمات

يوضّح هذا المثال كيفية ضبط قيمة السمة DoorLockTrait.wrongCodeEntryLimit بشكل صريح.

لضبط قيمة سمة، استدعِ الدالة update الخاصة بالسمة وامرر إليها دالة تعديل تضبط القيمة الجديدة. من الممارسات الجيدة أن تتأكّد أولاً من أنّ السمة تتيح استخدام سمة.

على سبيل المثال:

if doorLockTraitTest.attributes.$wrongCodeEntryLimit.isSupported {
  let _ = try await doorLockTraitTest.update {
    $0.setWrongCodeEntryLimit(3)
  }
}