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

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

import GoogleHomeSDK
import GoogleHomeTypes

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

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

Home API के कुछ तरीकों से, HomeError मिलता है. इसलिए, हमारा सुझाव है कि आप उन कॉल पर HomeError को पकड़ने के लिए, do-catch ब्लॉक का इस्तेमाल करें.

HomeError को मैनेज करते समय, इसकी code और message फ़ील्ड की जांच करके देखें कि क्या गड़बड़ी हुई है.

बिना मैनेज की गई किसी भी गड़बड़ी की वजह से, आपका ऐप्लिकेशन क्रैश हो जाएगा.

ज़्यादा जानकारी के लिए, गड़बड़ी को मैनेज करना देखें.

उदाहरण के लिए, किसी डिवाइस को निर्देश भेजना देखें.

कॉल के सैंपल

डिवाइसों की सूची पाना

Home ऑब्जेक्ट के रेफ़रंस के साथ, ऐक्सेस किए जा सकने वाले डिवाइसों की सूची Query पाने के लिए, devices() को लागू करें. Query के batched() तरीके को कॉल करें. इससे एक सेट जनरेट होता है, जिसमें डिवाइस के मेटाडेटा में होने वाले हर बदलाव के साथ होम की मौजूदा स्थिति दिखती है. इसके अलावा, उपलब्ध डिवाइसों का स्नैपशॉट पाने के लिए, Query.list() पर कॉल करें. यह एक आसान तरीका है, जो batched() स्ट्रीम की सदस्यता लेता है और उत्सर्जित की गई पहली वैल्यू दिखाता है. Query.stream() एक स्ट्रीम जनरेट करती है, जो डिवाइस के मेटाडेटा में हुए बदलावों के आधार पर नई वैल्यू दिखाती है. जैसे, डिवाइस का नाम, कमरा या स्ट्रक्चर. अंदरूनी तौर पर, यह batched() का इस्तेमाल करता है और सिर्फ़ बदली गई प्रॉपर्टी को उत्सर्जित करता है.

// Get a list of all devices accessible to the user
let homeDevices = try await self.home.devices().list()

यहां से, हर डिवाइस की स्थिति को ऐक्सेस किया जा सकता है. साथ ही, डिवाइस पर काम करने वाले निर्देश भेजे जा सकते हैं.

डिवाइस के टाइप की जानकारी पाना

किसी डिवाइस से जुड़े डिवाइस टाइप जानने के लिए, डिवाइस की types प्रॉपर्टी पढ़ें. इससे DeviceTypeController दिखता है.

किसी खास डिवाइस टाइप के अपडेट पाने के लिए, DeviceTypeController.subscribe(_:) को कॉल करें:

let devices = try await self.home.devices().list()
if let device = devices.first(where: { $0.id == myDeviceId }) {
  var receivedUpdate1 = false
  var receivedUpdate2 = false
  device.types.subscribe(OnOffLightDeviceType.self)
    .assertNoFailure()
    .sink { device in
      if !receivedUpdate1 {
        receivedUpdate1 = true
        Task {
          try await device.matterTraits.onOffTrait?.on()
        }
        return
      }
      if !receivedUpdate2 {
        receivedUpdate2 = true
        return
      }
      fatalError("Received unexpected update")
    }
}

अगर डिवाइस, बताए गए डिवाइस टाइप के साथ काम नहीं करता है, तो यह Empty Publisher दिखाता है. यह Empty Publisher तुरंत पूरा हो जाता है.

अगर डिवाइस किसी खास डिवाइस टाइप के साथ काम करता है, तो get() को कॉल करके उस टाइप का हैंडल पाया जा सकता है:

if let device = devices.first(where: { $0.id == myDeviceId }) {
  let deviceType = await device.types.get(OnOffLightDeviceType.self)
}

अगर डिवाइस पर बताए गए टाइप का इस्तेमाल नहीं किया जा सकता, तो यह nil दिखाता है.

DeviceTypeCollection का Publisher पाने के लिए, DeviceTypeController.subscribeAll() पर कॉल करें. इस क्लास की मदद से, यह देखा जा सकता है कि डिवाइस किस तरह का है:

if let device = devices.first(where: { $0.id == myDeviceId }) {
  device.types.subscribeAll()
    .assertNoFailure()
    .sink { types in
      let lightDeviceType = types[OnOffLightDeviceType.self]
      let fanDeviceType = types[FanDeviceType.self]
    }
}

डिवाइस टाइप की विशेषता पाना

डिवाइस टाइप, ट्रेट पढ़ने के लिए एंट्री पॉइंट होते हैं. ऐसा इसलिए, क्योंकि वे किसी डिवाइस को उसके फ़ंक्शन के हिसाब से अलग-अलग हिस्सों में बांट देते हैं. जैसे, Matter में एंडपॉइंट.

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

जब किसी डिवाइस में एक ही नाम के दो ट्रैट मौजूद होते हैं, तो एक और तरह का ट्रैट कॉलिज़न हो सकता है. उदाहरण के लिए, onOff, स्टैंडर्ड OnOff ट्रीट की वैल्यू हो सकती है या मैन्युफ़ैक्चरर की तय की गई OnOff ट्रीट की वैल्यू हो सकती है. किसी भी तरह की गड़बड़ी को रोकने के लिए, हर डिवाइस टाइप पर, दो में से किसी एक ट्रैट कलेक्शन के ज़रिए ट्रैट का रेफ़रंस दें.

स्टैंडर्ड ट्रैट के लिए, यानी Matter स्टैंडर्ड क्लस्टर से मिलते-जुलते ट्रैट के लिए, matterTraits का इस्तेमाल करें. उदाहरण के लिए, डिम की जा सकने वाली लाइट वाले डिवाइस टाइप के लिए कोई खास ट्रैट पाने के लिए:

if let dimmableLightDeviceType =
  await device.types.get(DimmableLightDeviceType.self)
{
  // Accessing standard trait on the type.
  let levelControlTrait =
    dimmableLightDeviceType.matterTraits.levelControlTrait.self
}

Google के ट्रैट के लिए, googleTraits का इस्तेमाल करें:

if let doorbellDeviceType = await device.types.get(GoogleDoorbellDeviceType.self) {
  // Accessing Google trait on the type.
  let doorbellPressTrait =
    doorbellDeviceType.googleTraits.doorbellPressTrait.self
}

मैन्युफ़ैक्चरर के हिसाब से खास जानकारी को ऐक्सेस करने के लिए, traits प्रॉपर्टी का इस्तेमाल करें. हालांकि, इसके पहले मैन्युफ़ैक्चरर के पैकेज का नाम डालें:

let deviceType = await device1?.types.get(OnOffLightDeviceType.self)
// Accessing custom trait on the type.
if let spinnerTrait = deviceType?.traits[ExampleOrganization.SpinnerTrait.self] {
  let rpmVal = spinnerTrait.attributes.rpm
}

डिवाइस की स्थिति पढ़ना

डिवाइस के चालू/बंद होने की जानकारी देने वाले ट्रैट से OnOff एट्रिब्यूट की जांच करने के लिए, यह उदाहरण देखें:

let lightDevices = devices.filter {
  $0.types.contains(OnOffLightDeviceType.self)
}
let light1 = lightDevices.first
let lightDeviceTypeOptional = await light1?.types.get(OnOffLightDeviceType.self)
if let onOffTrait = lightDeviceTypeOptional?.matterTraits.onOffTrait {
  let onOffVal = onOffTrait.attributes.onOff
}

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

किसी खास विशेषता वाले डिवाइसों की सूची पाने के लिए, आपको डिवाइसों, हर डिवाइस के टाइप, और हर डिवाइस टाइप की विशेषताओं के बारे में जानकारी देनी होगी. उदाहरण के लिए, होम में मौजूद उन डिवाइसों की सूची पाने के लिए जिनमें सभी के लिए चालू/बंद की सुविधा है:

// Get all light devices that support levelControl
var levelControlDevices: [HomeDevice] = []
var allDevices = try await home.devices().list()
for device in allDevices {
  if let deviceType = await device.types.get(OnOffLightDeviceType.self) {
    if deviceType.traits.contains(Matter.LevelControlTrait.self) {
      levelControlDevices.append(device)
    }
  }
}

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

एक जैसे डिवाइस टाइप वाले डिवाइसों की सूची पाना

किसी होम में मौजूद सभी लाइटों को कंट्रोल करने वाले डिवाइसों की सूची पाने के लिए:

// Get a list of devices with similar device types (lights)
let lightDevices =
  try await self.home.devices().list().compactMap {
    $0.types.contains(DimmableLightDeviceType.self)
      || $0.types.contains(OnOffLightDeviceType.self)
      || $0.types.contains(ColorTemperatureLightDeviceType.self)
      || $0.types.contains(ExtendedColorLightDeviceType.self)
  }

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

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

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

BasicInformationTrait ट्रैट में, किसी डिवाइस के लिए वेंडर आईडी, प्रॉडक्ट आईडी, प्रॉडक्ट का नाम, और सीरियल नंबर जैसी जानकारी शामिल होती है:

guard
  let vendorName =
    basicInfoTrait.attributes.vendorName
else {
  fatalError("Failed to get vendorName")
}
guard
  let vendorID =
    basicInfoTrait.attributes.vendorID
else {
  fatalError("Failed to get vendorID")
}
guard
  let productID =
    basicInfoTrait.attributes.productID
else {
  fatalError("Failed to get productID")
}

डिवाइस बनाने वाली कंपनियों के लिए, क्लाउड-टू-क्लाउड डिवाइस आइडेंटिफ़िकेशन

अगर आप डिवाइस बनाने वाली कंपनी हैं और Cloud-to-cloud डिवाइस बनाते हैं, तो BasicInformation ट्रैट की मदद से अपने Cloud-to-cloud डिवाइसों की पहचान करने के लिए, उनके SYNC रिस्पॉन्स में ये स्ट्रिंग फ़ील्ड शामिल किए जा सकते हैं:

• Connectivity Standards Alliance (सीएसए) से मिला वेंडर आईडी: "matterOriginalVendorId": "0xfff1",

• प्रॉडक्ट आइडेंटिफ़ायर, जो किसी वेंडर के प्रॉडक्ट की खास पहचान करता है: "matterOriginalProductId": "0x1234",

• डिवाइस के लिए यूनीक आइडेंटिफ़ायर, जिसे मैन्युफ़ैक्चरर के हिसाब से बनाया जाता है: "matterUniqueId": "matter-device-id",

इन स्ट्रिंग फ़ील्ड में जानकारी डालते समय, अपने Matter वेंडर और प्रॉडक्ट आईडी का इस्तेमाल करें. अगर आप सीएसए के सदस्य नहीं हैं और आपको ये आईडी असाइन नहीं किए गए हैं, तो matterOriginalVendorId और matterOriginalProductId फ़ील्ड को खाली छोड़ा जा सकता है. साथ ही, आइडेंटिफ़ायर के तौर पर matterUniqueId दिया जा सकता है.

सिंक किए गए डेटा के जवाब के उदाहरण में, इन फ़ील्ड का इस्तेमाल दिखाया गया है:

{
  "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 के ज़रिए कई तरह के डिवाइसों की जानकारी दिखा सकते हैं. यह पक्का करने के लिए कि उपयोगकर्ताओं को उनके डिवाइसों के लिए, ऐप्लिकेशन में सही विकल्प (जैसे, डिवाइस कंट्रोल और सुझाए गए ऑटोमेशन) दिखाए जाएं, यह देखना ज़रूरी है कि डिवाइस का टाइप, डिवाइस का मुख्य टाइप है या नहीं.

if let deviceType =
  await device?.types.get(HumiditySensorDeviceType.self)
{
  if deviceType.metadata.isPrimaryType {
    print("Humidity Sensor is the primary type on this device.")
  } else {
    print("Humidity Sensor isn't the primary type on this device.")
  }
}

यह देखना कि कोई ट्रैट ऑनलाइन है या नहीं

किसी ट्रैट की कनेक्टिविटी की जांच करने के लिए, connectivityState प्रॉपर्टी पढ़ें:

let levelControlConnectivity =
  levelControlTrait.metadata.sourceConnectivity
  .connectivityState

अगर डिवाइस में इंटरनेट कनेक्शन नहीं है, तो हो सकता है कि कुछ खासताओं के लिए, डिवाइस पर ऑफ़लाइन वैल्यू दिखें. आम तौर पर, Google smart home की खासताओं के लिए ऐसा होता है. ऐसा इसलिए है, क्योंकि ये ट्रैट क्लाउड-आधारित होते हैं और इनमें लोकल रूटिंग नहीं होती.

किसी डिवाइस की कनेक्टिविटी की जांच करना

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

let lightConnectivity =
  dimmableLightDeviceType.metadata.sourceConnectivity
  .connectivityState

अलग-अलग तरह के डिवाइसों के मामले में, partiallyOnline की स्थिति तब दिख सकती है, जब इंटरनेट कनेक्शन न हो. Matter स्टैंडर्ड ट्रैट अब भी ऑनलाइन हो सकते हैं, क्योंकि लोकल रूटिंग की वजह से ऐसा होता है. हालांकि, क्लाउड-आधारित ट्रैट ऑफ़लाइन हो जाएंगे.

किसी विशेषता के नेटवर्क राउटिंग की जांच करना

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

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

let levelControlLocality =
  levelControlTrait.metadata.sourceConnectivity
  .dataSourceLocality

किसी डिवाइस के लिए नेटवर्क रूटिंग की जांच करना

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

let lightLocality =
  dimmableLightDeviceType.metadata.sourceConnectivity.dataSourceLocality

mixed की स्थिति, partiallyOnline कनेक्शन की स्थिति जैसी ही हो सकती है: कुछ ट्रैट क्लाउड-आधारित होते हैं, जबकि अन्य स्थानीय होते हैं.

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

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

let updatedDevice = try await theDevice.setName("new device name")

किसी डिवाइस का नाम बदलने पर, ओरिजनल HomeDevice स्ट्रक्चर में कोई बदलाव नहीं होता. बदलाव, दिखाए गए अपडेट किए गए HomeDevice ऑब्जेक्ट में दिखता है.

एपीआई की सूची

Home का एक इंस्टेंस बनाने के बाद, इन डिवाइस एपीआई को इसके ज़रिए ऐक्सेस किया जा सकता है:

HomeDevice मिलने के बाद, इन एपीआई को ऐक्सेस किया जा सकता है: