کنترل دستگاه‌ها در 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 استفاده کنید که در مدل داده بوم‌سازگان Google Home به‌صورت toggle() تعریف شده است. این روش onOff را به false تغییر می‌دهد اگر true باشد، یا به true تغییر می‌دهد اگر false باشد:

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

اگر مشکلی در جریان اجرای دستورات شناسایی شود، ممکن است دستورات استثنایی برگردانند. به‌عنوان توسعه‌دهنده، باید از بلوک do-catch برای مدیریت صحیح این استثناها استفاده کنید و در مواردی که خطاها قابل اقدام هستند، اطلاعات دقیق را به کاربران ارائه دهید. استثناهای مدیریت‌نشده زمان اجرای برنامه را متوقف می‌کند و می‌تواند منجر به خرابی در برنامه شما شود.

یا از فرمان‌های off() یا on() برای تنظیم صریح وضعیت استفاده کنید:

do {
  try await onOffTraitTest.off()
  try await onOffTraitTest.on()
} catch let _ 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 _ 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 _ 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 تهی‌پذیر هستند. برای این مشخصه‌ها، می‌توانید بااستفاده از 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 \(String(describing: 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)
  }
}