دستگاه ها را در 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 true باشد، آن را به false و اگر مقدار false باشد، آن را به true تغییر می‌دهد:

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

اگر مشکلی در جریان اجرا تشخیص داده شود، دستورات ممکن است یک استثنا (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 در سطح trait استفاده کنید تا بررسی کنید که آیا این ویژگی برای یک دستگاه خاص پشتیبانی می‌شود یا خیر.

برای مثال، برای بررسی پشتیبانی دستگاه از ویژگی 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 یا طرح smart home Cloud-to-cloud قابل تهی شدن هستند. برای این ویژگی‌ها، می‌توانید با استفاده از isNullable علاوه بر isSupported ، تعیین کنید که آیا تهی بودن برگردانده شده توسط ویژگی به دلیل عدم گزارش آن مقدار توسط دستگاه است یا اینکه مقدار ویژگی در واقع nil است:

// 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)
  }
}