Android के लिए डिवाइस और डिवाइस का मेटाडेटा ऐक्सेस करना

Android के लिए Home API की मदद से, डिवाइस के एपीआई ऐक्सेस किए जा सकते हैं. अपने ऐप्लिकेशन में ये पैकेज इंपोर्ट करें:

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

डिवाइस के एपीआई के साथ, डिवाइस के खास टाइप या उसकी खासियतों का इस्तेमाल करने के लिए, उन्हें अलग-अलग इंपोर्ट करना होगा.

उदाहरण के लिए, Matter On/Off खासियत और On/Off प्लग-इन यूनिट डिवाइस टाइप का इस्तेमाल करने के लिए, अपने ऐप्लिकेशन में ये पैकेज इंपोर्ट करें:

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

ज़्यादा जानकारी के लिए, Android पर डेटा मॉडल देखें.

गड़बड़ी ठीक करना

Home API में मौजूद कोई भी तरीका, HomeException दिखा सकता है. इसलिए, हमारा सुझाव है कि सभी कॉल पर HomeException को पकड़ने के लिए, try-catch ब्लॉक का इस्तेमाल करें.

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()

यहां से, हर डिवाइस के स्टेटस को ऐक्सेस किया जा सकता है और डिवाइसों को निर्देश भेजे जा सकते हैं.

Home API के वर्शन 1.8 में, आपके पास यह विकल्प होता है कि एपीआई, कई हिस्सों वाले हर डिवाइस को एक डिवाइस के तौर पर दिखाए. इसके लिए, devices() तरीके के enableMultipartDevices पैरामीटर को true पर सेट करें. ज़्यादा जानकारी के लिए, Android पर कई हिस्सों वाले डिवाइस देखें.

डिवाइस का स्टेटस पढ़ना

डिवाइस की On/Off खासियत से, OnOff एट्रिब्यूट की जांच करने का एक उदाहरण देखें. Home API के खासियत डेटा मॉडल का इस्तेमाल करके, खासियत का डेटा वापस पाया जा सकता है. इस मॉडल में, इस खासियत की पहचान 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()!!

Kotlin के फ़्लो फ़ंक्शन के बारे में ज़्यादा जानने के लिए, distinctUntilChanged देखें.

किसी खासियत की सदस्यता में स्टेटस को अमान्य करना

The TraitStateInvalidation इंटरफ़ेस की मदद से, टारगेट डिवाइस की सदस्यताओं से वापस पाए गए स्टेटस को अमान्य किया जा सकता है. ऐसा तब किया जाता है, जब स्टेटस की जानकारी सही तरीके से नहीं दी जा रही हो. उदाहरण के लिए, ऐसा तब हो सकता है, जब Matter की खासियत में "C" क्वालिटी वाले एट्रिब्यूट का इस्तेमाल किया जा रहा हो या डिवाइस को लागू करने के तरीके की वजह से, अचानक कोई समस्या आ गई हो.

यह एपीआई, खासियत के मौजूदा स्टेटस को ज़बरदस्ती पढ़ता है और मौजूदा खासियत के फ़्लो के ज़रिए नतीजा दिखाता है.

खासियत पाएं. इसके बाद, खासियत पर forceRead चलाएं:

val onOffTrait = device.?type(DimmableLightDevice)?.map{it.trait(OnOff)}.first()
onOffTrait.forceRead()

डिवाइस टाइप की खासियतों की सूची पाना

खासियतों को पढ़ने के लिए, डिवाइस टाइप का इस्तेमाल एंट्री पॉइंट के तौर पर किया जाना चाहिए. ऐसा इसलिए, क्योंकि ये डिवाइस को उसके काम के हिस्सों में बांटते हैं. जैसे, Matter में एंडपॉइंट. Matter

अगर किसी डिवाइस में दो डिवाइस टाइप हैं और दोनों में एक ही खासियत है, तो ये खासियत के टकराव को भी ध्यान में रखते हैं. उदाहरण के लिए, अगर कोई डिवाइस स्पीकर और डिमेबल लाइट, दोनों है, तो उसमें On/Off की दो और लेवल कंट्रोल की दो खासियतें होंगी.

डिमेबल लाइट डिवाइस टाइप के लिए, उपलब्ध खासियतों की सूची पाने के लिए:

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

किसी खास खासियत वाले डिवाइसों की सूची पाना

एपीआई कॉल को बेहतर बनाने के लिए, Kotlin में filter फ़ंक्शन का इस्तेमाल किया जा सकता है. उदाहरण के लिए, घर में मौजूद उन डिवाइसों की सूची पाने के लिए जिनमें On/Off की खासियत है:

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

Home API में कई डिवाइस टाइप हो सकते हैं जो किसी मुख्य डिवाइस टाइप को दिखा सकते हैं. उदाहरण के लिए, "लाइट" डिवाइस टाइप नहीं है. इसके बजाय, चार अलग-अलग डिवाइस टाइप हैं जो लाइट को दिखा सकते हैं. जैसा कि पिछले उदाहरण में दिखाया गया है. इसलिए, घर में मौजूद डिवाइस के बड़े टाइप की पूरी जानकारी पाने के लिए, फ़िल्टर किए गए फ़्लो में कई डिवाइस टाइप शामिल किए जाने चाहिए.

Home API में उपलब्ध सभी डिवाइस टाइप की सूची देखने के लिए, DeviceType इंटरफ़ेस देखें.

किसी डिवाइस के लिए वेंडर आईडी या प्रॉडक्ट आईडी पाना

The 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 जवाब में ये स्ट्रिंग फ़ील्ड शामिल किए जा सकते हैं:

• 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 दस्तावेज़ देखें.

डिवाइस और खासियत का मेटाडेटा

Home API में मौजूद डिवाइसों और खासियतों से जुड़ा मेटाडेटा होता है. इससे, किसी ऐप्लिकेशन में उपयोगकर्ता अनुभव को मैनेज करने में मदद मिलती है.

Home API में मौजूद हर खासियत में, sourceConnectivity प्रॉपर्टी होती है. इसमें, किसी खासियत के ऑनलाइन स्टेटस और जगह (लोकल या रिमोट राउटिंग) के बारे में जानकारी होती है.

किसी डिवाइस का प्राइमरी टाइप पाना

कुछ डिवाइस, Home API की मदद से कई डिवाइस टाइप दिखा सकते हैं. यह पक्का करने के लिए कि उपयोगकर्ताओं को उनके डिवाइसों के लिए, ऐप्लिकेशन में सही विकल्प (जैसे, डिवाइस कंट्रोल और सुझाए गए ऑटोमेशन) दिखें, यह देखना ज़रूरी है कि किसी डिवाइस का प्राइमरी डिवाइस टाइप क्या है.

सबसे पहले, डिवाइस के टाइप पाने के लिए 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 स्टैंडर्ड खासियतें, लोकल राउटिंग की वजह से अब भी ऑनलाइन हो सकती हैं. हालांकि, क्लाउड पर आधारित खासियतें ऑफ़लाइन होंगी.

डिवाइस का आईपी पता पाना

डिवाइस का आईपी पता ढूंढने के लिए, खासियत के networkInterfaces एट्रिब्यूट का इस्तेमाल करें.GeneralDiagnostics पते, बाइट ऐरे के तौर पर दिखाए जाते हैं. इन्हें स्टैंडर्ड आईपीवी4 या आईपीवी6 स्ट्रिंग के तौर पर फ़ॉर्मैट किया जा सकता है:

val ipAddresses =
  trait.networkInterfaces?.flatMap { networkInterface ->
    (networkInterface.ipv4Addresses + networkInterface.ipv6Addresses).mapNotNull { bytes ->
      try {
        java.net.InetAddress.getByAddress(bytes).hostAddress
      } catch (e: java.net.UnknownHostException) {
        null
      }
    }
  } ?: emptyList()

किसी खासियत की नेटवर्क राउटिंग देखना

Home API में, किसी खासियत की जगह की जानकारी भी उपलब्ध होती है. dataSourceLocality से पता चलता है कि खासियत को रिमोट (क्लाउड के ज़रिए), लोकल (लोकल हब के ज़रिए) या पीयर-टू-पीयर (डिवाइस से डिवाइस पर सीधे, कोई हब नहीं) तरीके से राउट किया गया है.

जगह की जानकारी की अननोन वैल्यू UNSPECIFIED हो सकती है. उदाहरण के लिए, जब कोई ऐप्लिकेशन बूट हो रहा हो और डिवाइस कनेक्टिविटी के लिए, वह अब तक किसी हब या सर्वर तक न पहुंचा हो. इन डिवाइसों तक नहीं पहुंचा जा सकता. साथ ही, ये निर्देश या इवेंट से मिलने वाले इंटरैक्शन के अनुरोधों को पूरा नहीं कर पाएंगे. यह तय करना क्लाइंट पर निर्भर करता है कि ऐसे डिवाइसों को कैसे मैनेज किया जाए.

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

किसी डिवाइस की नेटवर्क राउटिंग देखना

कनेक्टिविटी की तरह, जगह की जानकारी की जांच भी डिवाइस टाइप के लेवल पर की जाती है. दिखाया गया स्टेटस, उस डिवाइस पर मौजूद सभी खासियतों की जगह की जानकारी का कॉम्बिनेशन होता है.

val lightLocality = dimmableLightDevice.metadata.sourceConnectivity.dataSourceLocality

PARTIALLY_ONLINE कनेक्टिविटी के जैसे ही किसी मामले में, MIXED का स्टेटस दिख सकता है. ऐसा तब होता है, जब कुछ खासियतें क्लाउड पर आधारित होती हैं, जबकि कुछ लोकल होती हैं.

किसी डिवाइस का नाम बदलना

किसी डिवाइस का नाम बदलने के लिए, setName() तरीके को कॉल करें:

mixerDevice.setName("Grendel")

अगर नाम, यूनिकोड कोड पॉइंट (वर्ण) की 60 की सीमा से ज़्यादा है, तो उन्हें काट दिया जाएगा. साथ ही, कोई गड़बड़ी नहीं दिखाई जाएगी. डेवलपर, लंबे नामों को मैनेज करने के लिए ज़िम्मेदार होते हैं. उदाहरण के लिए, वे यह तय कर सकते हैं कि उपयोगकर्ताओं को यह जानकारी देनी है या नहीं कि नाम काट दिए जाएंगे.