به دستگاه‌ها و فراداده‌های دستگاه دسترسی داشته باشید

APIهای دستگاه ممکن است از طریق APIهای Home قابل دسترسی باشند. این بسته ها را به برنامه خود وارد کنید:

import com.google.home.Home
import com.google.home.HomeDevice
import com.google.home.Id

برای استفاده از انواع یا ویژگی‌های خاص دستگاه با APIهای دستگاه، باید به صورت جداگانه وارد شوند.

به عنوان مثال، برای استفاده از ویژگی Matter On/Off و نوع دستگاه Plug-in On/Off، بسته های زیر را در برنامه خود وارد کنید:

import com.google.home.matter.standard.OnOff
import com.google.home.matter.standard.OnOffPluginUnitDevice

برای اطلاعات بیشتر، مدل داده را ببینید.

رسیدگی به خطا

هر روشی در APIهای Home می‌تواند یک HomeException ایجاد کند، بنابراین توصیه می‌کنیم از یک بلوک try-catch برای گرفتن HomeException در همه تماس‌ها استفاده کنید.

هنگام مدیریت HomeException ، قسمت های code و message آن را بررسی کنید تا متوجه شوید چه مشکلی پیش آمده است.

هرگونه استثناء کنترل نشده منجر به خرابی برنامه شما می شود.

برای اطلاعات بیشتر، رسیدگی به خطا را ببینید.

برای مثال به ارسال فرمان به دستگاه مراجعه کنید.

تماس های نمونه

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

با ساختار موجود، یک فراخوانی devices() جریانی از دستگاه‌های قابل دسترسی شما را از آن ساختار برمی‌گرداند:

// Get a flow of all devices accessible to the user
val allDevicesFlow: HomeObjectsFlow<HomeDevice> = home.devices()

// Calling list() on a HomeObjectsFlow returns the first Set of elements.
val allDevices: Set<HomeDevice> = allDevicesFlow.list()

از آنجا، وضعیت های هر دستگاه قابل دسترسی است و دستورات پشتیبانی شده را می توان به دستگاه ارسال کرد.

وضعیت دستگاه را بخوانید

بیایید به نمونه ای از بررسی ویژگی OnOff از ویژگی On/Off دستگاه نگاه کنیم. با استفاده از مدل داده ویژگی Home APIs، که در آن این ویژگی به عنوان OnOff شناسایی می‌شود، می‌توانید داده‌های ویژگی را از طریق کلاس standardTraits نوع دستگاه بازیابی کنید:

// Assuming we have a device.
val deviceFlow = home.devices().itemFlow(myDeviceId)

val device = deviceFlow.first()

// Get a flow of a standard trait on the type. distinctUntilChanged() is needed to only trigger
// on the specific trait changes and not the whole type.
val onOffTraitFlow: Flow<OnOff?> =
  device.type(DimmableLightDevice).map { it.standardTraits.onOff }.distinctUntilChanged()

val onOffTrait: OnOff = onOffTraitFlow.first()!!

مشاهده distinctUntilChanged برای اطلاعات بیشتر در مورد تابع جریان Kotlin.

وضعیت را در اشتراک ویژگی باطل کنید

رابط TraitStateInvalidation این امکان را فراهم می کند که وضعیتی را که از طریق اشتراک در دستگاه هدف بازیابی شده است در مواردی که وضعیت به درستی گزارش نمی شود، باطل کند. مثال‌هایی از مواردی که ممکن است وضعیت به درستی گزارش نشود، شامل استفاده از ویژگی‌ها در ویژگی‌های Matter با کیفیت «C» یا به دلیل اجرای دستگاهی است که به‌طور غیرمنتظره باعث ایجاد مشکل می‌شود.

این API یک خواندن اجباری از وضعیت فعلی صادر می کند و نتیجه را از طریق جریان های صفت موجود برمی گرداند.

ویژگی را دریافت کنید، سپس یک forceRead روی این ویژگی اجرا کنید:

val generalDiagnosticsTrait = device.trait(GeneralDiagnostics).first()
generalDiagnosticsTrait.forceRead()

لیستی از ویژگی های نوع دستگاه را دریافت کنید

انواع دستگاه‌ها باید به‌عنوان نقطه ورودی برای خواندن صفات استفاده شوند، زیرا آنها دستگاه را به قطعات عملکردی آن تجزیه می‌کنند (مانند نقاط پایانی در Matter ).

آنها همچنین برای برخوردهای صفت در صورتی که یک دستگاه دارای دو نوع دستگاه باشد، که هر دو ممکن است دارای یک ویژگی باشند، حساب می کنند. به عنوان مثال، اگر دستگاهی هم اسپیکر و هم نور کم نور باشد، دو ویژگی روشن/خاموش و دو ویژگی کنترل سطح دارد.

برای دریافت لیستی از ویژگی های موجود برای نوع دستگاه نور کم نور:

// Get all types available on this device. Requires the types to be part of the registry during
// SDK initialization.
val typesFlow: Flow<Set<DeviceType>> = device.types()

// Get a snapshot of all types.
val types: Set<DeviceType> = typesFlow.first()

// Get the DimmableLightDevice instance from the set of types.
val dimmableLightDevice = types.filterIsInstance<DimmableLightDevice>().firstOrNull()

// Get all traits in the type + traits registered
val allTraits: Set<Trait> = dimmableLightDevice!!.traits()

نوع دیگری از برخورد صفت زمانی رخ می دهد که یک دستگاه دارای دو ویژگی با نام یکسان باشد. برای مثال، onOff می‌تواند به نمونه‌ای از ویژگی استاندارد OnOff اشاره کند، یا می‌تواند به نمونه‌ای از ویژگی OnOff تعریف‌شده توسط سازنده اشاره کند. برای از بین بردن هرگونه ابهام احتمالی در مورد اینکه کدام ویژگی مورد نظر است، یک نمونه Trait که از طریق یک دستگاه ارجاع داده می شود باید قبل از یک فضای نام واجد شرایط باشد. برای صفات استاندارد، یعنی آنهایی که مشابه خوشه‌های استاندارد Matter هستند، از standardTraits استفاده کنید. برای ویژگی های گوگل، از googleTraits استفاده کنید:

// Accessing standard traits on the type.
val onOffTrait: OnOff? = dimmableLightDevice.standardTraits.onOff
val levelControlTrait: LevelControl? = dimmableLightDevice.standardTraits.levelControl

برای دسترسی به یک ویژگی خاص سازنده، مستقیماً به آن مراجعه کنید:

// Accessing a custom trait on the type.
val customTrait = dimmableLightDevice.trait(MyCustomTrait)

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

تابع filter در Kotlin می تواند برای اصلاح بیشتر فراخوانی های API استفاده شود. به عنوان مثال، برای دریافت لیستی از دستگاه‌های موجود در خانه که همگی دارای ویژگی روشن/خاموش هستند:

// Get all devices that support OnOff
val onOffDevices: Flow<List<HomeDevice>> =
  home.devices().map { devices -> devices.filter { it.has(OnOff) } }

برای فهرست کامل ویژگی‌های موجود در Home API به رابط Trait مراجعه کنید.

لیستی از دستگاه هایی با انواع دستگاه های مشابه دریافت کنید

برای دریافت لیستی از دستگاه هایی که نشان دهنده تمام چراغ های یک خانه هستند:

// Get a list of devices with similar device types (lights)
val lightDevices =
  home.devices().map { devices ->
    devices.filter {
      it.has(DimmableLightDevice) ||
        it.has(OnOffLightDevice) ||
        it.has(ColorTemperatureLightDevice) ||
        it.has(ExtendedColorLightDevice)
    }
  }

چندین نوع دستگاه در APIهای Home وجود دارد که می تواند یک نوع دستگاه اصلی را نشان دهد. به عنوان مثال، نوع دستگاه "Light" وجود ندارد. در عوض، چهار نوع دستگاه مختلف وجود دارد که می توانند نور را نشان دهند، همانطور که در مثال قبل نشان داده شده است. به این ترتیب، برای به دست آوردن یک دید جامع از نوع دستگاه سطح بالاتر در یک خانه، چندین نوع دستگاه باید در جریان های فیلتر شده گنجانده شود.

برای مشاهده لیست کامل انواع دستگاه های موجود در Home API به رابط DeviceType مراجعه کنید.

شناسه فروشنده یا شناسه محصول یک دستگاه را دریافت کنید

ویژگی BasicInformation شامل اطلاعاتی مانند شناسه فروشنده، شناسه محصول، نام محصول و شماره سریال یک دستگاه است:

// Get device basic information. All general information traits are on the RootNodeDevice type.
val basicInformation = device.type(RootNodeDevice).first().standardTraits.basicInformation!!
println("vendorName ${basicInformation.vendorName}")
println("vendorId ${basicInformation.vendorId}")
println("productId ${basicInformation.productId}")

دستگاه های ابر به ابر را شناسایی کنید

اگر سازنده دستگاه هستید و دستگاه‌های Cloud-to-cloud می‌سازید، به منظور شناسایی دستگاه‌های Cloud-to-cloud خود از طریق ویژگی BasicInformation ، می‌توانید این فیلدهای رشته‌ای را در پاسخ SYNC آن‌ها قرار دهید:

• اتحادیه استانداردهای اتصال (CSA) شناسه فروشنده صادر کرد: "matterOriginalVendorId": "0xfff1",

• یک شناسه محصول که به طور منحصربه‌فرد محصول یک فروشنده را شناسایی می‌کند: "matterOriginalProductId": "0x1234",

• یک شناسه منحصر به فرد برای دستگاه، که به روشی خاص سازنده ساخته شده است: "matterUniqueId": "matter-device-id",

هنگام وارد کردن این فیلدهای رشته، از شناسه Matter و محصول خود در صورت داشتن آنها استفاده کنید. اگر عضو CSA نیستید و این شناسه ها به شما اختصاص داده نشده است، می توانید فیلدهای matterOriginalVendorId و matterOriginalProductId را خالی بگذارید و matterUniqueId به عنوان شناسه ارائه کنید.

نمونه پاسخ SYNC استفاده از این فیلدها را نشان می دهد:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "456",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.OnOff",
          "action.devices.traits.Brightness",
          "action.devices.traits.ColorSetting",
        ],
        "willReportState": true,
        "deviceInfo": { ... },
        "matterOriginalVendorId": "0xfff1",
        "matterOriginalProductId": "0x1234",
        "matterUniqueId": "matter-device-id",
        "otherDeviceIds": [
          {
            "deviceId": "local-device-id",
          }
        ]
      }
    ]
  }
}

برای اطلاعات بیشتر، به مستندات Cloud-to-cloud SYNC مراجعه کنید.

فراداده دستگاه و ویژگی

دستگاه‌ها و ویژگی‌ها در Home API دارای ابرداده‌های مرتبط با آن‌ها هستند که می‌تواند به مدیریت تجربه کاربر در یک برنامه کمک کند.

هر ویژگی در APIهای Home حاوی یک ویژگی sourceConnectivity است که اطلاعاتی در مورد وضعیت آنلاین و موقعیت یک صفت (مسیریابی محلی یا راه دور) دارد.

نوع اولیه یک دستگاه را دریافت کنید

برخی از دستگاه‌ها ممکن است چندین نوع دستگاه را از طریق APIهای Home ارائه دهند. برای اطمینان از اینکه گزینه‌های مناسب در یک برنامه (مانند کنترل دستگاه و اتوماسیون‌های پیشنهادی) برای دستگاه‌هایشان به کاربران ارائه می‌شود، بررسی نوع دستگاه اصلی برای یک دستگاه مفید است.

ابتدا نوع(های) دستگاه را با استفاده از type() بدست آورید، سپس تعیین کنید که کدام نوع اصلی است:

val types = device.types().first()
val primaryType = types.first { it.metadata.isPrimaryType }

بررسی کنید که آیا یک ویژگی آنلاین است یا خیر

از متد connectivityState() برای بررسی اتصال یک صفت استفاده کنید:

val onOffConnectivity = onOffTrait?.metadata?.sourceConnectivity?.connectivityState

اگر دستگاه اتصال اینترنت نداشته باشد، برخی از ویژگی‌ها، معمولاً ویژگی‌های smart home Google، ممکن است آفلاین نشان داده شوند. این به این دلیل است که این ویژگی ها مبتنی بر ابر هستند و مسیریابی محلی ندارند.

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

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

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

وضعیت PARTIALLY_ONLINE ممکن است در مورد انواع دستگاه های مختلط که اتصال اینترنت وجود ندارد مشاهده شود. ممکن است به دلیل مسیریابی محلی، ویژگی‌های استاندارد ماده همچنان آنلاین باشند، اما ویژگی‌های مبتنی بر ابر آفلاین خواهند بود.

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

محل برای یک صفت نیز در APIهای Home موجود است. dataSourceLocality نشان می دهد که آیا این ویژگی از راه دور (از طریق ابر)، به صورت محلی (از طریق یک هاب محلی)، یا همتا به همتا (مستقیم از دستگاهی به دستگاه دیگر، بدون هاب) هدایت می شود.

برای مثال زمانی که یک برنامه در حال بوت شدن است و هنوز به هاب یا سروری برای اتصال دستگاه نرسیده است، مقدار محلی ناشناخته UNSPECIFIED امکان پذیر است. این دستگاه‌ها قابل دسترسی نیستند و درخواست‌های تعامل از سوی فرمان‌ها یا رویدادها را انجام نمی‌دهند. این به مشتری بستگی دارد که نحوه کار با چنین دستگاه هایی را تعیین کند.

val onOffLocality = onOffTrait?.metadata?.sourceConnectivity?.dataSourceLocality

مسیریابی شبکه را برای یک دستگاه بررسی کنید

مانند اتصال، محل در سطح نوع دستگاه بررسی می شود. حالت برگردانده شده ترکیبی از محلی برای همه صفات در آن دستگاه است.

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

حالت MIXED ممکن است در سناریویی مشابه با اتصال PARTIALLY_ONLINE مشاهده شود: برخی از ویژگی ها مبتنی بر ابر هستند در حالی که برخی دیگر محلی هستند.

لیست API

هنگامی که یک نمونه از Home ایجاد می شود، API های دستگاه زیر از طریق آن قابل دسترسی هستند:

هنگامی که یک HomeDevice دارید، API های زیر از طریق آن قابل دسترسی هستند: