الوصول إلى الأجهزة والبيانات الوصفية للأجهزة على Android

يمكن الوصول إلى واجهات برمجة تطبيقات الأجهزة من خلال واجهات برمجة تطبيقات Home لنظام التشغيل Android. استورِد هذه الحِزم إلى تطبيقك:

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

لاستخدام أنواع أو سمات أجهزة معيّنة مع Device APIs، يجب استيرادها بشكل فردي.

على سبيل المثال، لاستخدام السمة Matter On/Off ونوع الجهاز On/Off Plug-in Unit، استورِد الحِزم التالية إلى تطبيقك:

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

لمزيد من المعلومات، يُرجى الاطّلاع على نموذج البيانات على Android.

معالجة الأخطاء

يمكن لأي طريقة في واجهات برمجة التطبيقات 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 من سمة "تشغيل/إيقاف" في الجهاز. باستخدام نموذج بيانات سمة 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 بجودة "ج" أو بسبب تنفيذ الجهاز الذي يتسبّب في حدوث المشكلة بشكل غير متوقّع.

تُصدر واجهة برمجة التطبيقات هذه قراءة إجبارية لحالة السمة الحالية وتعرض النتيجة من خلال مسارات السمات الحالية.

احصل على السمة، ثم شغِّل 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. بالنسبة إلى سمات Google، استخدِم 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 لتحسين طلبات البيانات من واجهة برمجة التطبيقات. على سبيل المثال، للحصول على قائمة بالأجهزة في المنزل التي تتضمّن السمة "تشغيل/إيقاف":

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

يمكنك الاطّلاع على واجهة Trait للحصول على قائمة كاملة بالسمات المتاحة في واجهات برمجة التطبيقات الخاصة بمنصة Home.

الحصول على قائمة بالأجهزة التي تتضمّن أنواع أجهزة مشابهة

للحصول على قائمة بالأجهزة التي تمثّل جميع الأضواء في المنزل، اتّبِع الخطوات التالية:

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

تتضمّن واجهات برمجة التطبيقات Home أنواعًا متعددة من الأجهزة يمكن أن تمثّل نوعًا أساسيًا من الأجهزة. على سبيل المثال، لا يتوفّر نوع الجهاز "مصباح". بدلاً من ذلك، هناك أربعة أنواع مختلفة من الأجهزة يمكن أن تمثّل مصباحًا، كما هو موضّح في المثال السابق. وبالتالي، للحصول على عرض شامل لنوع الجهاز الأعلى مستوى في المنزل، يجب تضمين أنواع أجهزة متعددة في التدفقات التي تمّت فلترتها.

اطّلِع على واجهة DeviceType للحصول على قائمة كاملة بأنواع الأجهزة المتوفّرة في واجهات برمجة تطبيقات Home.

الحصول على معرّف المورّد أو معرّف المنتج لجهاز

يتضمّن نوع البيانات 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، يمكنك تضمين حقول السلسلة التالية في ردّ SYNC لتحديد أجهزة Cloud-to-cloud من خلال السمة BasicInformation:

• أصدرت منظمة Connectivity Standards Alliance (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 على بيانات وصفية مرتبطة بها، ما يساعد في إدارة تجربة المستخدم في التطبيق.

تحتوي كل سمة في واجهات برمجة التطبيقات Home APIs على السمة sourceConnectivity التي تتضمّن معلومات حول حالة السمة على الإنترنت وموقعها الجغرافي (التوجيه المحلي أو البعيد).

الحصول على النوع الأساسي للجهاز

قد تعرض بعض الأجهزة أنواعًا متعددة من الأجهزة من خلال واجهات برمجة التطبيقات Home APIs. لضمان عرض الخيارات المناسبة للمستخدمين في أحد التطبيقات (مثل عناصر التحكّم في الأجهزة وعمليات التشغيل الآلي المقترَحة) لأجهزتهم، من المفيد التحقّق من نوع الجهاز الأساسي.

أولاً، احصل على أنواع الأجهزة باستخدام type()، ثم حدِّد الأنواع الأساسية:

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

التحقّق مما إذا كانت السمة متاحة على الإنترنت

استخدِم طريقة connectivityState() للتحقّق من ربط سمة معيّنة:

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

قد تظهر بعض السمات، مثل سمات Google smart home عادةً، في وضع عدم الاتصال بالإنترنت إذا لم يكن الجهاز متصلاً بالإنترنت. ويرجع ذلك إلى أنّ هذه السمات مستندة إلى السحابة الإلكترونية ولا تتضمّن توجيهًا محليًا.

التحقّق من إمكانية الاتصال بجهاز

يتم في الواقع التحقّق من إمكانية اتصال الجهاز على مستوى نوع الجهاز، لأنّ بعض الأجهزة تتوافق مع أنواع أجهزة متعددة. الحالة التي يتم عرضها هي مزيج من حالات الاتصال لجميع السمات على هذا الجهاز.

val lightConnectivity = dimmableLightDevice.metadata.sourceConnectivity.connectivityState

قد تظهر حالة PARTIALLY_ONLINE في حال تضمين أنواع أجهزة مختلفة عند عدم توفّر اتصال بالإنترنت. قد تظل سمات Matter العادية متاحة على الإنترنت بسبب التوجيه المحلي، ولكن ستكون السمات المستندة إلى السحابة الإلكترونية غير متاحة.

التحقّق من توجيه الشبكة لسمة

تتوفّر أيضًا معلومات الموقع الجغرافي الخاص بالسمة في واجهات برمجة التطبيقات الخاصة بمنصة Home. تشير dataSourceLocality إلى ما إذا كان يتم توجيه السمة عن بُعد (من خلال السحابة الإلكترونية) أو محليًا (من خلال مركز محلي) أو من جهاز إلى جهاز (مباشرةً من الجهاز إلى الجهاز، بدون مركز).

من المحتمل أن تظهر قيمة الموقع الجغرافي غير المعروف UNSPECIFIED، مثلاً، أثناء تشغيل تطبيق ولم يتم بعد الوصول إلى مركز أو خادم للاتصال بالجهاز. لا يمكن الوصول إلى هذه الأجهزة، وستتعذّر طلبات التفاعل من الأوامر أو الأحداث. ويعود إلى العميل تحديد كيفية التعامل مع هذه الأجهزة.

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

التحقّق من توجيه الشبكة لجهاز

كما هو الحال مع الاتصال، يتم التحقّق من الموقع الجغرافي على مستوى نوع الجهاز. الحالة التي يتم عرضها هي مزيج من الموقع الجغرافي لجميع السمات على هذا الجهاز.

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

قد يتم رصد حالة MIXED في سيناريو مشابه لحالة اتصال PARTIALLY_ONLINE: بعض السمات مستندة إلى السحابة الإلكترونية، بينما البعض الآخر محلي.

تغيير اسم جهاز

استدعِ طريقة setName() لتغيير اسم الجهاز:

mixerDevice.setName("Grendel")

قائمة واجهات برمجة التطبيقات

بعد إنشاء مثيل من Home، يمكن الوصول إلى واجهات برمجة التطبيقات التالية الخاصة بالجهاز من خلاله:

بعد حصولك على HomeDevice، يمكنك الوصول إلى واجهات برمجة التطبيقات التالية من خلاله: