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

بررسی کنید که آیا یک صفت از یک فرمان پشتیبانی می کند

پشتیبانی همچنین می تواند برای یک فرمان صفت بررسی شود. همچنین از تابع supports سطح صفت برای بررسی اینکه آیا یک فرمان برای دستگاه خاصی پشتیبانی می شود استفاده کنید.

به عنوان مثال، برای بررسی پشتیبانی دستگاه از فرمان toggle حالت روشن/خاموش:

// Check if the OnOff trait supports the toggle command.
if (onOffTrait.supports(OnOff.Command.Toggle)) {
  println("onOffTrait supports toggle command")
} else {
  println("onOffTrait does not support stateful toggle command")
}

ارسال فرمان به دستگاه

ارسال یک دستور شبیه به خواندن یک ویژگی حالت از یک صفت است. برای روشن یا خاموش کردن دستگاه، از دستور Toggle از ویژگی OnOff استفاده کنید که در مدل داده اکوسیستم Google Home به عنوان toggle() تعریف شده است. این متد onOff در صورت true بودن به false یا در صورت false بودن به true تغییر می دهد:

// Calling a command on a trait.
try {
  onOffTrait.toggle()
} catch (e: HomeException) {
  // Code for handling the exception
}

همه دستورات صفت توابع suspend هستند و تنها زمانی تکمیل می شوند که یک پاسخ توسط API برگردانده شود (مانند تأیید تغییر وضعیت دستگاه). اگر مشکلی در جریان اجرا تشخیص داده شود، ممکن است دستورات یک استثنا برگردانند. به عنوان یک توسعه‌دهنده، باید از یک بلوک try-catch برای مدیریت صحیح این استثناها استفاده کنید و اطلاعات دقیق را در مورد مواردی که خطاها قابل اجرا هستند در اختیار کاربران قرار دهید. استثناهای کنترل نشده زمان اجرای برنامه را متوقف می کند و می تواند منجر به خرابی در برنامه شما شود.

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

onOffTrait.off()
onOffTrait.on()

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

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

برخی از دستورات ممکن است از پارامترهایی مانند پارامترهای OnOff یا LevelControl استفاده کنند:

// Turn off the light using the DyingLight effect.
onOffTrait.offWithEffect(
  effectIdentifier = OnOffTrait.EffectIdentifierEnum.DyingLight,
  effectVariant = 0u,
)

// Change the brightness of the light to 50%
levelControlTrait.moveToLevel(
  level = 127u.toUByte(),
  transitionTime = null,
  optionsMask = LevelControlTrait.OptionsBitmap(),
  optionsOverride = LevelControlTrait.OptionsBitmap(),
)

برخی از دستورات دارای آرگومان های اختیاری هستند که بعد از آرگومان های مورد نیاز می آیند.

برای مثال، دستور step برای صفت FanControl دو آرگومان اختیاری دارد:

val fanControlTraitFlow: Flow<FanControl?> =
  device.type(FanDevice).map { it.standardTraits.fanControl }.distinctUntilChanged()

val fanControl = fanControlTraitFlow.firstOrNull()

// Calling a command with optional parameters not set.
fanControl?.step(direction = FanControlTrait.StepDirectionEnum.Increase)

// Calling a command with optional parameters.
fanControl?.step(direction = FanControlTrait.StepDirectionEnum.Increase) { wrap = true }

بررسی کنید که آیا یک صفت از یک ویژگی پشتیبانی می کند یا خیر

برخی از دستگاه ها ممکن است از یک ویژگی Matter پشتیبانی کنند، اما نه یک ویژگی خاص. برای مثال، یک دستگاه Cloud-to-cloud که به Matter نگاشت شده است، ممکن است از هر ویژگی Matter پشتیبانی نکند. برای رسیدگی به مواردی از این دست، از تابع supports سطح صفت و Attribute صفت enum استفاده کنید تا بررسی کنید که آیا ویژگی برای یک دستگاه خاص پشتیبانی می‌شود یا خیر.

به عنوان مثال، برای بررسی پشتیبانی دستگاه از ویژگی onOff ویژگی On/Off:

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

برخی از ویژگی ها در مشخصات Matter یا طرح smart home Cloud-to-cloud باطل هستند. برای این ویژگی‌ها، می‌توانید با استفاده از isNullable علاوه بر supports ، تعیین کنید که آیا تهی‌ای که توسط ویژگی برگردانده می‌شود به این دلیل است که دستگاه آن مقدار را گزارش نمی‌کند یا اینکه مقدار مشخصه واقعاً null است:

// Check if a nullable attribute is set or is not supported.
if (onOffTrait.supports(OnOff.Attribute.startUpOnOff)) {
  // The device supports startupOnOff, it is safe to expect this value in the trait.
  if (OnOff.Attribute.startUpOnOff.isNullable && onOffTrait.startUpOnOff == null) {
    // This value is nullable and set to null. Check the specification as to
    // what null in this case means
    println("onOffTrait supports startUpOnOff and it is null")
  } else {
    // This value is nullable and set to a value.
    println("onOffTrait supports startUpOnOff and it is set to ${onOffTrait.startUpOnOff}")
  }
} else {
  println("onOffTrait does not support startUpOnOff!")
}

ویژگی های صفت را به روز کنید

اگر می‌خواهید مقدار یک مشخصه را تغییر دهید، و هیچ یک از دستورات صفت این کار را انجام نمی‌دهد، ممکن است ویژگی از تنظیم صریح مقدار آن پشتیبانی کند.

اینکه آیا می توان مقدار یک ویژگی را تغییر داد به دو عامل بستگی دارد:

• آیا ویژگی قابل نوشتن است؟
• آیا مقدار مشخصه به عنوان یک عارضه جانبی ارسال فرمان صفت تغییر می کند؟

اسناد مرجع برای صفات و ویژگی های آنها این اطلاعات را فراهم می کند.

بنابراین، ترکیب‌هایی از ویژگی‌هایی که نحوه تغییر مقدار یک ویژگی را دیکته می‌کنند عبارتند از:

• فقط خواندنی است و تحت تأثیر سایر دستورات قرار نمی گیرد . این بدان معنی است که مقدار ویژگی تغییر نمی کند. به عنوان مثال، ویژگی currentPosition از ویژگی Switch .

• فقط خواندنی و تحت تأثیر سایر دستورات. این بدان معنی است که تنها راهی که می تواند مقدار مشخصه را تغییر دهد، در نتیجه ارسال یک فرمان است. به عنوان مثال، ویژگی currentLevel صفت LevelControl Matter فقط خواندنی است، اما مقدار آن را می توان با دستوراتی مانند moveToLevel تغییر داد.

• قابل نوشتن است و تحت تأثیر دستورات دیگر قرار نمی گیرد . این بدان معنی است که شما می توانید مستقیماً با استفاده از تابع update صفت مقدار مشخصه را تغییر دهید، اما هیچ دستوری وجود ندارد که بر مقدار ویژگی تأثیر بگذارد. به عنوان مثال، ویژگی WrongCodeEntryLimit از ویژگی DoorLock .

• قابل نوشتن و تحت تاثیر دستورات دیگر. این بدان معنی است که شما می توانید مستقیماً مقدار ویژگی را با استفاده از تابع update صفت تغییر دهید و مقدار ویژگی می تواند در نتیجه ارسال یک فرمان تغییر کند. به عنوان مثال، ویژگی occupiedCoolingSetpoint صفت Thermostat را می توان با دستور setpointRaiseLower روی آن نوشت و همچنین به روز کرد.

مثالی از استفاده از تابع به روز رسانی برای تغییر مقدار یک ویژگی

این مثال نحوه تنظیم صریح مقدار ویژگی DoorLockTrait.WrongCodeEntryLimit را نشان می دهد.

برای تنظیم یک مقدار مشخصه، تابع update صفت را فراخوانی کنید و یک تابع جهش دهنده که مقدار جدید را تنظیم می کند، به آن ارسال کنید. این یک تمرین خوب است که ابتدا تأیید کنید که این ویژگی از یک ویژگی پشتیبانی می کند .

به عنوان مثال:

    var doorLockDevice = home.devices().list().first { device -> device.has(DoorLock) }

    val traitFlow: Flow<DoorLock?> =
      doorLockDevice.type(DoorLockDevice).map { it.standardTraits.doorLock }.distinctUntilChanged()

    val doorLockTrait: DoorLock = traitFlow.first()!!

    if (doorLockTrait.supports(DoorLock.Attribute.wrongCodeEntryLimit)) {
      val unused = doorLockTrait.update { setWrongCodeEntryLimit(3u) }
    }