دستگاه ها را در iOS کنترل کنید

این راهنما از Access دستگاه‌ها و فراداده دستگاه در 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
}

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

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

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

پس از ارسال فرمان برای تغییر وضعیت، پس از تکمیل آن، می توانید وضعیت را همانطور که در Read a device state توضیح داده شده است بخوانید تا آن را در برنامه خود مدیریت کنید.

یک فرمان با پارامترها ارسال کنید

برخی از دستورات ممکن است از پارامترهایی استفاده کنند، مانند آنچه در 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 ویژگی On/Off:

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