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

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

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

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

على سبيل المثال، لاستخدام السمة 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، راجِع الحقلَين error.code و error.message لمعرفة الخطأ الذي حدث. قد تتوفّر أيضًا رموز أخطاء فرعية، لذا استدعِ طريقة getSubErrorCodes() وتحقّق من النتيجة.

سيؤدي حدوث أي أخطاء غير معالَجة إلى تعطُّل تطبيقك.

لمزيد من المعلومات، اطّلِع على مقالة التعامل مع الأخطاء.

راجِع مقالة إرسال أمر إلى جهاز للاطّلاع على مثال.

أمثلة على المكالمات

الحصول على قائمة بالأجهزة

بعد الحصول على مرجع إلى مثيل Structure، يؤدي طلب devices() إلى عرض Flow للأجهزة التي يمكنك الوصول إليها من تلك البنية:

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

إبطال حالة في اشتراك سمة

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

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

احصل على السمة، ثم شغِّل forceRead على السمة:

val onOffTrait = device.?type(DimmableLightDevice)?.map{it.trait(OnOff)}.first()
onOffTrait.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 APIs.

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

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

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

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

يمكنك الاطّلاع على واجهة 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 (Alliance) رقم تعريف المورّد الصادر: "matterOriginalVendorId": "0xfff1",

• معرّف المنتج الذي يحدّد منتج البائع بشكلٍ فريد: "matterOriginalProductId": "0x1234",

• معرّف فريد للجهاز، ويتم إنشاؤه بطريقة خاصة بالشركة المصنّعة: "matterUniqueId": "matter-device-id",

عند إدخال حقول السلسلة هذه، استخدِم Matterمعرّفات المورّد والمنتج إذا كانت متوفّرة لديك. إذا لم تكن عضوًا في Alliance ولم يتم تخصيص أرقام التعريف هذه لك، يمكنك ترك الحقلَين 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.

البيانات الوصفية للأجهزة والسمات

تحتوي الأجهزة والسمات في واجهات برمجة التطبيقات لمنزل Google على بيانات وصفية مرتبطة بها، ما يساعد في إدارة تجربة المستخدم في أحد التطبيقات.

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

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

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

أولاً، احصل على أنواع الأجهزة باستخدام 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")

سيتم اقتطاع الأسماء إذا تجاوزت الحدّ الأقصى المسموح به وهو 60 نقطة رمز يونيكود (حرفًا)، ولن يتم عرض أي أخطاء. يتحمّل المطوّرون مسؤولية التعامل مع الأسماء الطويلة، ويمكنهم مثلاً تحديد ما إذا كانوا يريدون إعلام المستخدمين بأنّه سيتم اقتطاع الأسماء.