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

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

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

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

على سبيل المثال، لاستخدام سمة Matter "تشغيل/إيقاف" ونوع جهاز "وحدة مكوّنة/تشغيل/إيقاف"، استورِد الحِزم التالية إلى تطبيقك:

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

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

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

يمكن أن تُعرِض أي طريقة في واجهات برمجة التطبيقات Home API خطأ 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 flow.

إلغاء صلاحية الحالة في اشتراك سمة

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

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

احصل على السمة، ثمّ نفِّذ 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 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)
    }
  }

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

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

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

تتضمّن السمة 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 على سمة sourceConnectivity ، والتي تتضمّن معلومات عن حالة السمة على الإنترنت وموقعها الجغرافي (التوجيه المحلي أو عن بُعد).

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

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

أولاً، احصل على أنواع الجهاز باستخدام 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 في حال استخدام أنواع أجهزة مختلطة في حال عدم توفّر اتصال بالإنترنت. قد تظل سمات Matter العادية متوفّرة على الإنترنت بسبب التوجيه المحلي، ولكن سيتم إيقاف السمات المستندة إلى السحابة الإلكترونية.

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

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

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

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

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

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

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

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

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

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

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